1r.sun(1)                    GRASS GIS User's Manual                   r.sun(1)
2
3
4

NAME

6       r.sun  - Solar irradiance and irradiation model.
7       Computes  direct (beam), diffuse and reflected solar irradiation raster
8       maps for given day, latitude, surface and atmospheric conditions. Solar
9       parameters  (e.g.  sunrise, sunset times, declination, extraterrestrial
10       irradiance, daylight length) are saved in the map history file.  Alter‐
11       natively,  a local time can be specified to compute solar incidence an‐
12       gle and/or irradiance raster maps. The shadowing effect of the topogra‐
13       phy is optionally incorporated.
14

KEYWORDS

16       raster, solar, sun energy, shadow, parallel
17

SYNOPSIS

19       r.sun
20       r.sun --help
21       r.sun  [-pm]  elevation=string   [aspect=string]   [aspect_value=float]
22       [slope=string]            [slope_value=float]            [linke=string]
23       [linke_value=float]         [albedo=string]        [albedo_value=float]
24       [lat=string]    [long=string]    [coeff_bh=string]    [coeff_dh=string]
25       [horizon_basename=basename]    [horizon_step=float]   [incidout=string]
26       [beam_rad=string]          [diff_rad=string]          [refl_rad=string]
27       [glob_rad=string]     [insol_time=string]    day=integer   [step=float]
28       [declination=float]         [solar_constant=float]         [time=float]
29       [nprocs=integer]       [distance_step=float]      [npartitions=integer]
30       [civil_time=float]   [--overwrite]   [--help]   [--verbose]   [--quiet]
31       [--ui]
32
33   Flags:
34       -p
35           Do not incorporate the shadowing effect of terrain
36
37       -m
38           Use the low-memory version of the program
39
40       --overwrite
41           Allow output files to overwrite existing files
42
43       --help
44           Print usage summary
45
46       --verbose
47           Verbose module output
48
49       --quiet
50           Quiet module output
51
52       --ui
53           Force launching GUI dialog
54
55   Parameters:
56       elevation=string [required]
57           Name of the input elevation raster map [meters]
58
59       aspect=string
60           Name  of the input aspect map (terrain aspect or azimuth of the so‐
61           lar panel) [decimal degrees]
62
63       aspect_value=float
64           A single value of the orientation (aspect), 270 is south
65           Default: 270
66
67       slope=string
68           Name of the input slope raster map (terrain slope  or  solar  panel
69           inclination) [decimal degrees]
70
71       slope_value=float
72           A single value of inclination (slope)
73           Default: 0.0
74
75       linke=string
76           Name  of  the  Linke atmospheric turbidity coefficient input raster
77           map [-]
78
79       linke_value=float
80           A single value of the Linke atmospheric turbidity coefficient [-]
81           Default: 3.0
82
83       albedo=string
84           Name of the ground albedo coefficient input raster map [-]
85
86       albedo_value=float
87           A single value of the ground albedo coefficient [-]
88           Default: 0.2
89
90       lat=string
91           Name of input raster map containing latitudes [decimal degrees]
92
93       long=string
94           Name of input raster map containing longitudes [decimal degrees]
95
96       coeff_bh=string
97           Name of real-sky beam radiation  coefficient  (thick  cloud)  input
98           raster map [0-1]
99
100       coeff_dh=string
101           Name  of real-sky diffuse radiation coefficient (haze) input raster
102           map [0-1]
103
104       horizon_basename=basename
105           The horizon information input map basename
106
107       horizon_step=float
108           Angle step size for multidirectional horizon [degrees]
109
110       incidout=string
111           Output incidence angle raster map (mode 1 only)
112
113       beam_rad=string
114           Output beam irradiance [W.m-2] (mode 1) or irradiation  raster  map
115           [Wh.m-2.day-1] (mode 2)
116
117       diff_rad=string
118           Output  diffuse  irradiance  [W.m-2] (mode 1) or irradiation raster
119           map [Wh.m-2.day-1] (mode 2)
120
121       refl_rad=string
122           Output ground reflected irradiance [W.m-2] (mode 1) or  irradiation
123           raster map [Wh.m-2.day-1] (mode 2)
124
125       glob_rad=string
126           Output  global  (total)  irradiance/irradiation [W.m-2] (mode 1) or
127           irradiance/irradiation raster map [Wh.m-2.day-1] (mode 2)
128
129       insol_time=string
130           Output insolation time raster map [h] (mode 2 only)
131
132       day=integer [required]
133           No. of day of the year (1-365)
134           Options: 1-365
135
136       step=float
137           Time step when computing all-day radiation sums [decimal hours]
138           Default: 0.5
139
140       declination=float
141           Declination value (overriding the internally computed value) [radi‐
142           ans]
143
144       solar_constant=float
145           Solar constant [W/m^2]
146           Default: 1367
147
148       time=float
149           Local (solar) time (to be set for mode 1 only) [decimal hours]
150           Options: 0-24
151
152       nprocs=integer
153           Number of threads which will be used for parallel computing
154           Options: 1-1000
155           Default: 1
156
157       distance_step=float
158           Sampling distance step coefficient (0.5-1.5)
159           Default: 1.0
160
161       npartitions=integer
162           Read the input files in this number of chunks
163           Default: 1
164
165       civil_time=float
166           Civil time zone value, if none, the time will be local solar time
167

DESCRIPTION

169       r.sun  computes beam (direct), diffuse and ground reflected solar irra‐
170       diation raster maps for given day, latitude,  surface  and  atmospheric
171       conditions. Solar parameters (e.g. time of sunrise and sunset, declina‐
172       tion, extraterrestrial irradiance, daylight length) are stored  in  the
173       resultant  maps’  history  files.  Alternatively, the local time can be
174       specified to compute solar incidence  angle  and/or  irradiance  raster
175       maps.  The  shadowing  effect  of the topography is incorporated by de‐
176       fault. This can be done either internally by calculatoion of the  shad‐
177       owing effect directly from the digital elevation model or by specifying
178       raster maps of the horizon height which is much faster.  These  horizon
179       raster maps can be calculated using r.horizon.
180
181       For  latitude-longitude  coordinates it requires that the elevation map
182       is in meters.  The rules are:
183
184           •   lat/lon coordinates: elevation in meters;
185
186           •   Other coordinates: elevation in the  same  unit  as  the  east‐
187               ing-northing coordinates.
188       The  solar geometry of the model is based on the works of Krcho (1990),
189       later improved by Jenco (1992). The equations describing Sun  --  Earth
190       position  as  well as an interaction of the solar radiation with atmos‐
191       phere were originally based on the formulas  suggested  by  Kitler  and
192       Mikler  (1986).  This component was considerably updated by the results
193       and suggestions of the working group co-ordinated by Scharmer and Greif
194       (2000)  (this  algorithm  might be replaced by SOLPOS algorithm-library
195       included in GRASS within r.sunmask command).  The  model  computes  all
196       three  components of global radiation (beam, diffuse and reflected) for
197       the clear sky conditions, i.e. not taking into consideration  the  spa‐
198       tial  and  temporal variation of clouds. The extent and spatial resolu‐
199       tion of the modelled area, as well as integration over time,  are  lim‐
200       ited  only by the memory and data storage resources. The model is built
201       to fulfil user needs in various fields of science (hydrology, climatol‐
202       ogy,  ecology  and  environmental sciences, photovoltaics, engineering,
203       etc.) for continental, regional up to the landscape scales.
204
205       The model considers a shadowing effect of the local  topography  unless
206       switched  off with the -p flag.  r.sun works in two modes: In the first
207       mode it calculates for the set local time a solar incidence angle  [de‐
208       grees]  and  solar irradiance values [W.m-2].  In the second mode daily
209       sums of solar radiation [Wh.m-2.day-1] are computed within a  set  day.
210       By a scripting the two modes can be used separately or in a combination
211       to provide estimates for any desired time interval. The model  accounts
212       for  sky obstruction by local relief features. Several solar parameters
213       are saved in the resultant maps’ history files,  which  may  be  viewed
214       with the r.info command.
215
216       The  solar  incidence  angle raster map incidout is computed specifying
217       elevation raster map elevation, aspect raster map aspect, slope  steep‐
218       ness  raster map slope, given the day day and local time time. There is
219       no need to define latitude for locations with known and defined projec‐
220       tion/coordinate  system (check it with the g.proj command). If you have
221       undefined projection, (x,y) system, etc. then the latitude can  be  de‐
222       fined explicitly for large areas by input raster map lat_in with inter‐
223       polated latitude values. All input raster maps must be  floating  point
224       (FCELL)  raster  maps. Null data in maps are excluded from the computa‐
225       tion (and also speeding-up the computation), so each output raster  map
226       will contain null data in cells according to all input raster maps. The
227       user can use r.null command to create/reset null file  for  your  input
228       raster maps.
229       The  specified  day  day  is  the number of the day of the general year
230       where January 1 is day no.1 and December 31 is 365. Time time must be a
231       local  (solar)  time  (i.e.  NOT a zone time, e.g. GMT, CET) in decimal
232       system, e.g. 7.5 (= 7h 30m A.M.), 16.1 = 4h 6m P.M..
233
234       The solar declination parameter is an option to override the value com‐
235       puted by the internal routine for the day of the year. The value of ge‐
236       ographical latitude can be set as a constant for the whole computed re‐
237       gion or, as an option, a grid representing spatially distributed values
238       over a large region. The geographical latitude must be also in  decimal
239       system  with  positive  values for northern hemisphere and negative for
240       southern one.  In similar principle the Linke turbidity factor  (linke,
241       lin ) and ground albedo (albedo, alb) can be set.
242
243       Besides clear-sky radiations, the user can compute a real-sky radiation
244       (beam, diffuse) using coeff_bh and coeff_dh input raster maps  defining
245       the  fraction  of  the respective clear-sky radiations reduced by atmo‐
246       spheric factors (e.g. cloudiness). The value is  between  0-1.  Usually
247       these  coefficients  can  be  obtained from a long-terms meteorological
248       measurements provided as raster maps with spatial distribution of these
249       coefficients  separately  for  beam and diffuse radiation (see Suri and
250       Hofierka, 2004, section 3.2).
251
252       The solar irradiation or irradiance  raster  maps  beam_rad,  diff_rad,
253       refl_rad  are  computed for a given day day, latitude lat_in, elevation
254       elevation, slope slope and aspect aspect raster maps.  For convenience,
255       the  output  raster  given as glob_rad will output the sum of the three
256       radiation components. The program uses the Linke  atmosphere  turbidity
257       factor and ground albedo coefficient.  A default, single value of Linke
258       factor is lin=3.0 and is near the annual average for rural-city  areas.
259       The  Linke  factor  for  an absolutely clear atmosphere is lin=1.0. See
260       notes below to learn more about this factor. The incidence solar  angle
261       is the angle between horizon and solar beam vector.
262
263       The  solar  radiation  maps for a given day are computed by integrating
264       the relevant irradiance between sunrise and sunset times for that  day.
265       The  user  can set a finer or coarser time step used for all-day radia‐
266       tion calculations with the step option. The default value  of  step  is
267       0.5  hour.  Larger  steps  (e.g. 1.0-2.0) can speed-up calculations but
268       produce less reliable (and more  jagged)  results.  As  the  sun  moves
269       through  approx.   15° of the sky in an hour, the default step of half
270       an hour will produce 7.5° steps in the  data.  For  relatively  smooth
271       output  with the sun placed for every degree of movement in the sky you
272       should set the step to 4 minutes or less. step=0.05  is  equivalent  to
273       every  3  minutes. Of course setting the time step to be very fine pro‐
274       portionally increases the module’s running time.
275
276       The  output  units  are  in  Wh  per  squared  meter  per   given   day
277       [Wh/(m*m)/day]. The incidence angle and irradiance/irradiation maps are
278       computed with the shadowing influence of relief by default. It is  also
279       possible  for them to be computed without this influence using the pla‐
280       nar flag (-p).  In mountainous areas this can lead  to  very  different
281       results!  The user should be aware that taking into account the shadow‐
282       ing effect of relief can slow down the speed of computation, especially
283       when the sun altitude is low.
284
285       When  considering the shadowing effect, speed and precision of computa‐
286       tion can be controlled by the distance_step  parameter,  which  defines
287       the sampling density at which the visibility of a grid cell is computed
288       in the direction of a path of the  solar  flow.  It  also  defines  the
289       method  by  which  the obstacle’s altitude is computed. When choosing a
290       distance_step less than 1.0 (i.e. sampling points will be  computed  at
291       distance_step  *  cellsize distance), r.sun takes the altitude from the
292       nearest grid point. Values above 1.0  will  use  the  maximum  altitude
293       value found in the nearest 4 surrounding grid points. The default value
294       distance_step=1.0 should give reasonable results for most  cases  (e.g.
295       on  DEM). The distance_step value defines a multiplying coefficient for
296       sampling distance. This basic sampling distance equals  to  the  arith‐
297       metic  average  of  both  cell  sizes. The reasonable values are in the
298       range 0.5-1.5.  The values below 0.5 will decrease and values above 1.0
299       will  increase the computing speed. Values greater than 2.0 may produce
300       estimates with lower accuracy in highly  dissected  relief.  The  fully
301       shadowed  areas  are  written  to the output maps as zero values. Areas
302       with NULL data are considered as no barrier with shadowing effect.
303
304       The maps’ history files are generated containing the  following  listed
305       parameters used in the computation:
306       - Solar constant used W.m-2
307       -  Extraterrestrial  irradiance  on  a plane perpendicular to the solar
308       beam [W.m-2]
309       - Day of the year
310       - Declination [radians]
311       - Decimal hour (Alternative 1 only)
312       - Sunrise and sunset (min-max) over a horizontal plane
313       - Daylight lengths
314       - Geographical latitude (min-max)
315       - Linke turbidity factor (min-max)
316       - Ground albedo (min-max)
317
318       The user can use a nice shellcript with variable day to compute  radia‐
319       tion  for some time interval within the year (e.g. vegetation or winter
320       period). Elevation, aspect and slope input values should not be reclas‐
321       sified into coarser categories. This could lead to incorrect results.
322

OPTIONS

324       Currently,  there  are two modes of r.sun.  In the first mode it calcu‐
325       lates solar incidence angle and solar irradiance raster maps using  the
326       set  local  time.  In  the  second mode daily sums of solar irradiation
327       [Wh.m-2.day-1] are computed for a specified day.
328

NOTES

330       Solar energy is an important input parameter in different  models  con‐
331       cerning  energy  industry,  landscape,  vegetation, evapotranspiration,
332       snowmelt or remote sensing. Solar rays incidence angle maps can be  ef‐
333       fectively  used in radiometric and topographic corrections in mountain‐
334       ous and hilly terrain where very accurate investigations should be per‐
335       formed.
336
337       The  clear-sky  solar  radiation model applied in the r.sun is based on
338       the work undertaken for development of European Solar  Radiation  Atlas
339       (Scharmer  and Greif 2000, Page et al. 2001, Rigollier 2001). The clear
340       sky model estimates the global radiation from the sum of its beam, dif‐
341       fuse and reflected components.  The main difference between solar radi‐
342       ation models for inclined surfaces in Europe is the  treatment  of  the
343       diffuse  component. In the European climate this component is often the
344       largest source of estimation error. Taking into consideration  the  ex‐
345       isting  models  and their limitation the European Solar Radiation Atlas
346       team selected the Muneer (1990) model as it has a sound theoretical ba‐
347       sis and thus more potential for later improvement.
348
349       Details  of  underlying  equations used in this program can be found in
350       the reference literature cited below or book published by  Neteler  and
351       Mitasova:  Open  Source  GIS: A GRASS GIS Approach (published in Kluwer
352       Academic Publishers in 2002).
353
354       Average monthly values of the Linke turbidity coefficient  for  a  mild
355       climate  in  the northern hemisphere (see reference literature for your
356       study area):
357
358       Month                                                        Jan                                                          Feb                                                          Mar                                                          Apr                                                          May                                                          Jun                                                          Jul                                                          Aug                                                          Sep                                                          Oct                                                          Nov                                                          Dec                                                          annual
359
360       mountains                                                    1.5                                                          1.6                                                          1.8                                                          1.9                                                          2.0                                                          2.3                                                          2.3                                                          2.3                                                          2.1                                                          1.8                                                          1.6                                                          1.5                                                          1.90
361
362       rural                                                        2.1                                                          2.2                                                          2.5                                                          2.9                                                          3.2                                                          3.4                                                          3.5                                                          3.3                                                          2.9                                                          2.6                                                          2.3                                                          2.2                                                          2.75
363
364       city                                                         3.1                                                          3.2                                                          3.5                                                          4.0                                                          4.2                                                          4.3                                                          4.4                                                          4.3                                                          4.0                                                          3.6                                                          3.3                                                          3.1                                                          3.75
365
366       industrial                                                   4.1                                                          4.3                                                          4.7                                                          5.3                                                          5.5                                                          5.7                                                          5.8                                                          5.7                                                          5.3                                                          4.9                                                          4.5                                                          4.2                                                          5.00
367
368
369       Planned improvements include the use of the SOLPOS algorithm for  solar
370       geometry calculations and internal computation of aspect and slope.
371
372   Solar time
373       By  default  r.sun  calculates  times as true solar time, whereby solar
374       noon is always exactly 12 o’clock everywhere in the current region. De‐
375       pending  on  where  the zone of interest is located in the related time
376       zone, this may cause differences of up to an hour, in some cases  (like
377       Western Spain) even more.  On top of this, the offset varies during the
378       year according to the Equation of Time.
379
380       To overcome this problem, the user can use the option civil_time=<time‐
381       zone_offset>  in r.sun to make it use real-world (wall clock) time. For
382       example, for Central Europe the timezone offset is +1, +2 when daylight
383       saving time is in effect.
384
385   Extraction of shadow maps
386       A  map  of  shadows can be extracted from the solar incidence angle map
387       (incidout). Areas with NULL values are shadowed. This will not work  if
388       the -p flag has been used.
389
390   Large maps and out of memory problems
391       With  a large number or columns and rows, r.sun can consume significant
392       amount of memory. While output raster maps are not  partitionable,  the
393       input  raster maps are using the npartitions parameter.  In case of out
394       of memory error (ERROR: G_malloc: out of memory), the  npartitions  pa‐
395       rameter  can be used to run a segmented calculation which consumes less
396       memory during the computations.  The amount of memory by r.sun is esti‐
397       mated as follows:
398       # without input raster map partitioning:
399       #  memory requirements: 4 bytes per raster cell
400       #  rows,cols: rows and columns of current region (find out with g.region)
401       #  IR: number of input raster maps without horizon maps
402       #  OR: number of output raster maps
403       memory_bytes = rows*cols*(IR*4 + horizon_steps + OR*4)
404       # with input raster map partitioning:
405       memory_bytes = rows*cols*((IR*4+horizon_steps)/npartitions  + OR*4)
406

EXAMPLES

408       North Carolina example (considering also cast shadows):
409       g.region raster=elevation -p
410       # calculate horizon angles (to speed up the subsequent r.sun calculation)
411       r.horizon elevation=elevation step=30 bufferzone=200 output=horangle \
412           maxdistance=5000
413       # slope + aspect
414       r.slope.aspect elevation=elevation aspect=aspect.dem slope=slope.dem
415       # calculate global radiation for day 180 at 2p.m., using r.horizon output
416       r.sun elevation=elevation horizon_basename=horangle horizon_step=30 \
417             aspect=aspect.dem slope=slope.dem glob_rad=global_rad day=180 time=14
418       # result: output global (total) irradiance/irradiation [W.m-2] for given day/time
419       r.univar global_rad
420
421       Calculation  of  the  integrated  daily  irradiation  for  a  region in
422       North-Carolina for a given day of the year at 30m resolution. Here  day
423       172 (i.e., 21 June in non-leap years):
424       g.region raster=elev_ned_30m -p
425       # considering cast shadows
426       r.sun elevation=elev_ned_30m linke_value=2.5 albedo_value=0.2 day=172 \
427             beam_rad=b172 diff_rad=d172 \
428             refl_rad=r172 insol_time=it172
429       d.mon wx0
430       # show irradiation raster map [Wh.m-2.day-1]
431       d.rast.leg b172
432       # show insolation time raster map [h]
433       d.rast.leg it172
434       We can compute the day of year from a specific date in Python:
435       >>> import datetime
436       >>> datetime.datetime(2014, 6, 21).timetuple().tm_yday
437       172
438

SEE ALSO

440         r.horizon,  r.slope.aspect,  r.sunhours,  r.sunmask,  g.proj, r.null,
441       v.surf.rst
442

REFERENCES

444           •   Hofierka, J., Suri, M. (2002): The solar  radiation  model  for
445               Open source GIS: implementation and applications. International
446               GRASS users conference in Trento, Italy, September 2002.  (PDF)
447
448           •   Hofierka, J. (1997). Direct solar radiation modelling within an
449               open  GIS  environment.  Proceedings of JEC-GI’97 conference in
450               Vienna, Austria, IOS Press Amsterdam, 575-584.
451
452           •   Jenco, M. (1992). Distribution of  direct  solar  radiation  on
453               georelief  and  its modelling by means of complex digital model
454               of terrain (in Slovak). Geograficky casopis, 44, 342-355.
455
456           •   Kasten, F. (1996). The Linke turbidity factor based on improved
457               values  of  the  integral Rayleigh optical thickness. Solar En‐
458               ergy, 56 (3), 239-244.
459
460           •   Kasten, F., Young, A. T. (1989). Revised optical air  mass  ta‐
461               bles and approximation formula. Applied Optics, 28, 4735-4738.
462
463           •   Kittler, R., Mikler, J. (1986): Basis of the utilization of so‐
464               lar radiation (in Slovak). VEDA, Bratislava, p. 150.
465
466           •   Krcho, J. (1990). Morfometrická  analza  a  digitálne  modely
467               georeliéfu (Morphometric analysis and digital models of geore‐
468               lief, in Slovak).  VEDA, Bratislava.
469
470           •   Muneer, T. (1990). Solar radiation model for  Europe.  Building
471               services engineering research and technology, 11, 4, 153-163.
472
473           •   Neteler,  M., Mitasova, H. (2002): Open Source GIS: A GRASS GIS
474               Approach, Kluwer Academic Publishers. (Appendix  explains  for‐
475               mula; r.sun script download)
476
477           •   Page,  J. ed. (1986). Prediction of solar radiation on inclined
478               surfaces. Solar energy R&D in the European Community, series  F
479               - Solar radiation data, Dordrecht (D. Reidel), 3, 71, 81-83.
480
481           •   Page,  J.,  Albuisson,  M., Wald, L. (2001). The European solar
482               radiation atlas: a valuable digital  tool.  Solar  Energy,  71,
483               81-83.
484
485           •   Rigollier,  Ch.,  Bauer,  O., Wald, L. (2000). On the clear sky
486               model of the ESRA - European Solar radiation Atlas -  with  re‐
487               spect to the Heliosat method.  Solar energy, 68, 33-48.
488
489           •   Scharmer, K., Greif, J., eds., (2000). The European solar radi‐
490               ation atlas, Vol. 2: Database and exploitation software.  Paris
491               (Les Presses de l’École des Mines).
492
493           •   Joint  Research Centre: GIS solar radiation database for Europe
494               and Solar radiation and GIS
495

AUTHORS

497       Jaroslav Hofierka, GeoModel, s.r.o. Bratislava, Slovakia
498       Marcel Suri, GeoModel, s.r.o. Bratislava, Slovakia
499       Thomas Huld, JRC, Italy
500       © 2007, Jaroslav Hofierka, Marcel Suri. This program is free  software
501       under  the  GNU  General  Public  License  (>=v2)  hofierka@geomodel.sk
502       suri@geomodel.sk
503

SOURCE CODE

505       Available at: r.sun source code (history)
506
507       Accessed: Mon Jun 20 16:46:30 2022
508
509       Main index | Raster index | Topics index | Keywords index  |  Graphical
510       index | Full index
511
512       © 2003-2022 GRASS Development Team, GRASS GIS 8.2.0 Reference Manual
513
514
515
516GRASS 8.2.0                                                           r.sun(1)
Impressum