1r.sun(1)                      Grass 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
12       angle and/or irradiance raster maps. The shadowing effect of the topog‐
13       raphy is optionally incorporated.
14

KEYWORDS

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

DESCRIPTION

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

OPTIONS

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

NOTES

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

EXAMPLES

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

SEE ALSO

435        r.horizon,  r.slope.aspect,  r.sunhours,  r.sunmask,  g.proj,  r.null,
436       v.surf.rst
437

REFERENCES

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

AUTHORS

493       Jaroslav Hofierka, GeoModel, s.r.o. Bratislava, Slovakia
494       Marcel Suri, GeoModel, s.r.o. Bratislava, Slovakia
495       Thomas Huld, JRC, Italy
496       © 2007, Jaroslav Hofierka, Marcel Suri. This program is  free  software
497       under  the  GNU  General  Public  License  (>=v2)  hofierka@geomodel.sk
498       suri@geomodel.sk
499
500       Last changed: $Date: 2018-01-22 15:17:21 +0100 (Mon, 22 Jan 2018) $
501

SOURCE CODE

503       Available at: r.sun source code (history)
504
505       Main index | Raster index | Topics index | Keywords index  |  Graphical
506       index | Full index
507
508       © 2003-2019 GRASS Development Team, GRASS GIS 7.6.0 Reference Manual
509
510
511
512GRASS 7.6.0                                                           r.sun(1)
Impressum