1r.sun(1) GRASS GIS User's Manual r.sun(1)
2
3
4
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
16 raster, solar, sun energy, shadow, parallel
17
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
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
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
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
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
440 r.horizon, r.slope.aspect, r.sunhours, r.sunmask, g.proj, r.null,
441 v.surf.rst
442
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
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
505 Available at: r.sun source code (history)
506
507 Accessed: Saturday Oct 28 18:18:00 2023
508
509 Main index | Raster index | Topics index | Keywords index | Graphical
510 index | Full index
511
512 © 2003-2023 GRASS Development Team, GRASS GIS 8.3.1 Reference Manual
513
514
515
516GRASS 8.3.1 r.sun(1)