1r.sun(1) Grass 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
12 angle and/or irradiance raster maps. The shadowing effect of the topog‐
13 raphy is optionally incorporated.
14
16 raster, solar, sun energy, shadow
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] [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
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
265 an hour will produce 7.5° steps in the data. For relatively smooth
266 output with the sun placed for every degree of movement in the sky you
267 should set the step to 4 minutes or less. step=0.05 is equivalent to
268 every 3 minutes. Of course setting the time step to be very fine pro‐
269 portionally 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
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
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
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
435 r.horizon, r.slope.aspect, r.sunhours, r.sunmask, g.proj, r.null,
436 v.surf.rst
437
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
463 georeliéfu (Morphometric analysis and digital models of geore‐
464 lief, 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
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
501 Available at: r.sun source code (history)
502
503 Main index | Raster index | Topics index | Keywords index | Graphical
504 index | Full index
505
506 © 2003-2019 GRASS Development Team, GRASS GIS 7.8.2 Reference Manual
507
508
509
510GRASS 7.8.2 r.sun(1)