Provided by: grass-doc_6.4.3-3_all bug

NAME

       r.sun  - Solar irradiance and irradiation model.
       Computes direct (beam), diffuse and reflected solar irradiation raster maps for given day,
       latitude, surface and atmospheric  conditions.  Solar  parameters  (e.g.  sunrise,  sunset
       times,  declination,  extraterrestrial  irradiance,  daylight length) are saved in the map
       history file. Alternatively, a local time can be  specified  to  compute  solar  incidence
       angle  and/or irradiance raster maps. The shadowing effect of the topography is optionally
       incorporated.

KEYWORDS

       raster, sun energy

SYNOPSIS

       r.sun
       r.sun help
       r.sun   [-sm]   elevin=string     [aspin=string]      [aspect=float]      [slopein=string]
       [slope=float]      [linkein=string]      [lin=float]      [albedo=string]      [alb=float]
       [latin=string]   [longin=string]    [coefbh=string]    [coefdh=string]    [horizon=string]
       [horizonstep=float]      [incidout=string]      [beam_rad=string]      [insol_time=string]
       [diff_rad=string]    [refl_rad=string]    [glob_rad=string]    day=integer    [step=float]
       [declin=float]   [time=float]   [dist=float]   [numpartitions=integer]   [civiltime=float]
       [lat=float]   [--overwrite]  [--verbose]  [--quiet]

   Flags:
       -s
           Incorporate the shadowing effect of terrain

       -m
           Use the low-memory version of the program

       --overwrite
           Allow output files to overwrite existing files

       --verbose
           Verbose module output

       --quiet
           Quiet module output

   Parameters:
       elevin=string
           Name of the input elevation raster map [meters]

       aspin=string
           Name of the input aspect map (terrain aspect or azimuth of the solar  panel)  [decimal
           degrees]

       aspect=float
           A single value of the orientation (aspect), 270 is south
           Default: 270

       slopein=string
           Name of the input slope raster map (terrain slope or solar panel inclination) [decimal
           degrees]

       slope=float
           A single value of inclination (slope)
           Default: 0.0

       linkein=string
           Name of the Linke atmospheric turbidity coefficient input raster map [-]

       lin=float
           A single value of the Linke atmospheric turbidity coefficient [-]
           Default: 3.0

       albedo=string
           Name of the ground albedo coefficient input raster map [-]

       alb=float
           A single value of the ground albedo coefficient [-]
           Default: 0.2

       latin=string
           Name of input raster map containing latitudes [decimal degrees]

       longin=string
           Name of input raster map containing longitudes [decimal degrees]

       coefbh=string
           Name of real-sky beam radiation coefficient (thick cloud) input raster map [0-1]

       coefdh=string
           Name of real-sky diffuse radiation coefficient (haze) input raster map [0-1]

       horizon=string
           The horizon information input map prefix

       horizonstep=float
           Angle step size for multidirectional horizon [degrees]

       incidout=string
           Output incidence angle raster map (mode 1 only)

       beam_rad=string
           Output beam irradiance [W.m-2] (mode 1) or irradiation raster map [Wh.m-2.day-1] (mode
           2)

       insol_time=string
           Output insolation time raster map [h] (mode 2 only)

       diff_rad=string
           Output  diffuse  irradiance  [W.m-2] (mode 1) or irradiation raster map [Wh.m-2.day-1]
           (mode 2)

       refl_rad=string
           Output ground  reflected  irradiance  [W.m-2]  (mode  1)  or  irradiation  raster  map
           [Wh.m-2.day-1] (mode 2)

       glob_rad=string
           Output     global    (total)    irradiance/irradiation    [W.m-2]    (mode    1)    or
           irradiance/irradiation raster map [Wh.m-2.day-1] (mode 2)

       day=integer
           No. of day of the year (1-365)
           Options: 1-365

       step=float
           Time step when computing all-day radiation sums [decimal hours]
           Default: 0.5

       declin=float
           Declination value (overriding the internally computed value) [radians]

       time=float
           Local (solar) time (to be set for mode 1 only) [decimal hours]
           Options: 0-24

       dist=float
           Sampling distance step coefficient (0.5-1.5)
           Default: 1.0

       numpartitions=integer
           Read the input files in this number of chunks
           Default: 1

       civiltime=float
           Civil time zone value, if none, the time will be local solar time

       lat=float
           This does nothing. It is retained for backwards compatibility

DESCRIPTION

       r.sun computes beam (direct), diffuse and ground reflected solar irradiation  raster  maps
       for  given  day, latitude, surface and atmospheric conditions. Solar parameters (e.g. time
       of sunrise and sunset, declination,  extraterrestrial  irradiance,  daylight  length)  are
       stored  in  the  resultant  maps'  history  files.  Alternatively,  the  local time can be
       specified to compute solar incidence angle and/or irradiance raster  maps.  The  shadowing
       effect  of  the  topography  is  optionally  incorporated.  This  can  be  done  either by
       calculating the shadowing effect directly  from  the  digital  elevation  model  or  using
       rasters of the horizon height which is much faster. The horizon rasters can be constructed
       using  r.horizon.

       For latitude-longitude coordinates it requires that the elevation map is in  meters.   The
       rules are:

                      lat/lon coordinates: elevation in meters;

                      Other  coordinates:  elevation  in  the  same  unit as the easting-northing
                     coordinates.

       The solar geometry of the model is based on the works of Krcho (1990), later  improved  by
       Jenco  (1992).  The  equations  describing  Sun  –  Earth  position  as  well  as an
       interaction of the solar radiation with atmosphere were originally based on  the  formulas
       suggested  by  Kitler  and  Mikler  (1986). This component was considerably updated by the
       results and suggestions of the working group co-ordinated by  Scharmer  and  Greif  (2000)
       (this  algorithm  might  be  replaced by SOLPOS algorithm-library included in GRASS within
       r.sunmask command). The model computes all three components  of  global  radiation  (beam,
       diffuse  and  reflected)  for the clear sky conditions, i.e. not taking into consideration
       the spatial and temporal variation of clouds. The extent and  spatial  resolution  of  the
       modelled  area,  as well as integration over time, are limited only by the memory and data
       storage resources. The model is built to fulfil user needs in various  fields  of  science
       (hydrology,  climatology,  ecology and environmental sciences, photovoltaics, engineering,
       etc.) for continental, regional up to the landscape scales.

       As an option the model considers a shadowing effect of the local  topography.   The  r.sun
       program works in two modes. In the first mode it calculates for the set local time a solar
       incidence angle [degrees] and solar irradiance values [W.m-2].  In the second  mode  daily
       sums  of  solar radiation [Wh.m-2.day-1] are computed within a set day. By a scripting the
       two modes can be used separately or in a combination to provide estimates for any  desired
       time  interval.  The  model accounts for sky obstruction by local relief features. Several
       solar parameters are saved in the resultant maps' history files, which may be viewed  with
       the r.info command.

       The  solar incidence angle raster map incidout is computed specifying elevation raster map
       elevin, aspect raster map aspin, slope steepness raster map slopin, given the day day  and
       local  time time. There is no need to define latitude for locations with known and defined
       projection/coordinate system (check it with the g.proj command).  If  you  have  undefined
       projection, (x,y) system, etc. then the latitude can be defined explicitly for large areas
       by input raster map latin with interpolated latitude values. All input raster maps must be
       floating  point  (FCELL)  raster maps. Null data in maps are excluded from the computation
       (and also speeding-up the computation), so each output raster map will contain  null  data
       in  cells  according  to  all  input  raster  maps.  The  user  can  use r.null command to
       create/reset null file for your input raster maps.
       The specified day day is the number of the day of the general year where January 1 is  day
       no.1 and December 31 is 365. Time time must be a local (solar) time (i.e. NOT a zone time,
       e.g. GMT, CET) in decimal system, e.g. 7.5 (= 7h 30m A.M.), 16.1 = 4h 6m P.M..

       Setting the solar declination declin by user is an option to override the  value  computed
       by the internal routine for the day of the year. The value of geographical latitude can be
       set as a constant for the whole computed region or, as  an  option,  a  grid  representing
       spatially  distributed  values over a large region. The geographical latitude must be also
       in decimal system with positive values for northern hemisphere and negative  for  southern
       one.   In  similar  principle the Linke turbidity factor (linkein, lin ) and ground albedo
       (albedo, alb) can be set.

       Besides clear-sky radiations, the user can compute a real-sky  radiation  (beam,  diffuse)
       using  coefbh  and coefdh input raster maps defining the fraction of the respective clear-
       sky radiations reduced by atmospheric factors (e.g. cloudiness). The value is between 0-1.
       Usually  these  coefficients can be obtained from a long-terms meteorological measurements
       provided as raster maps with spatial distribution of  these  coefficients  separately  for
       beam and diffuse radiation (see Suri and Hofierka, 2004, section 3.2).

       The  solar irradiation or irradiance raster maps beam_rad, diff_rad, refl_rad are computed
       for a given day day, latitude latin, elevation elevin,  slope  slopein  and  aspect  aspin
       raster  maps.  For convenience, the output raster given as glob_rad will output the sum of
       the three radiation components. The program uses the Linke atmosphere turbidity factor and
       ground albedo coefficient.  A default, single value of Linke factor is lin=3.0 and is near
       the annual average for  rural-city  areas.  The  Linke  factor  for  an  absolutely  clear
       atmosphere  is  lin=1.0.  See  notes  below to learn more about this factor. The incidence
       solar angle is the angle between horizon and solar beam vector.

       The solar radiation maps for  a  given  day  are  computed  by  integrating  the  relevant
       irradiance  between  sunrise  and  sunset  times for that day. The user can set a finer or
       coarser time step used for all-day  radiation  calculations  with  the  step  option.  The
       default  value  of step is 0.5 hour. Larger steps (e.g. 1.0-2.0) can speed-up calculations
       but produce less reliable (and more jagged) results. As  the  sun  moves  through  approx.
       15&deg of the sky in an hour, the default step of half an hour will produce 7.5° steps
       in the data. For relatively smooth output with the sun placed for every degree of movement
       in  the sky you should set the step to 4 minutes or less. step=0.05 is equivalent to every
       3 minutes. Of course setting the time step to be very fine  proportionally  increases  the
       module's running time.

       The  output  units are in Wh per squared meter per given day [Wh/(m*m)/day]. The incidence
       angle and irradiance/irradiation maps can  be  computed  without  shadowing  influence  of
       relief  by  default  or  they  can  be  computed with this influence using the flag -s. In
       mountainous areas this can lead to very different results! The user should be  aware  that
       taken  into  account  the  shadowing effect of relief can slow down the speed of computing
       especially when the sun altitude is low.  When  considering  shadowing  effect  (flag  -s)
       speed  and  precision  computing  can  be controlled by a parameter dist which defines the
       sampling density at which the visibility of a grid cell is computed in the direction of  a
       path  of  the  solar  flow. It also defines the method by which the obstacle's altitude is
       computed. When choosing dist less than 1.0 (i.e. sampling points will be computed at  dist
       *  cellsize  distance), r.sun takes altitude from the nearest grid point. Values above 1.0
       will use the maximum altitude value found in the nearest 4 surrounding  grid  points.  The
       default  value dist=1.0 should give reasonable results for most cases (e.g.  on DEM). Dist
       value defines a  multiplying  coefficient  for  sampling  distance.  This  basic  sampling
       distance equals to the arithmetic average of both cell sizes. The reasonable values are in
       the range 0.5-1.5.  The values below 0.5 will decrease and values above 1.0 will  increase
       the  computing speed. Values greater than 2.0 may produce estimates with lower accuracy in
       highly dissected relief. The fully shadowed areas are written to the output maps  as  zero
       values. Areas with NULL data are considered as no barrier with shadowing effect .

       The  maps'  history files are generated containing the following listed parameters used in
       the computation:
       - Solar constant 1367 W.m-2
       - Extraterrestrial irradiance on a plane perpendicular to the solar beam [W.m-2]
       - Day of the year
       - Declination [radians]
       - Decimal hour (Alternative 1 only)
       - Sunrise and sunset (min-max) over a horizontal plane
       - Daylight lengths
       - Geographical latitude (min-max)
       - Linke turbidity factor (min-max)
       - Ground albedo (min-max)

       The user can use a nice shellcript with variable day to compute radiation  for  some  time
       interval  within  the year (e.g. vegetation or winter period). Elevation, aspect and slope
       input values should not be reclassified  into  coarser  categories.  This  could  lead  to
       incorrect results.

OPTIONS

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

NOTES

       Solar  energy  is  an  important  input  parameter  in  different models concerning energy
       industry, landscape, vegetation, evapotranspiration, snowmelt  or  remote  sensing.  Solar
       rays  incidence  angle  maps  can  be  effectively  used  in  radiometric  and topographic
       corrections in mountainous and hilly terrain where very accurate investigations should  be
       performed.

       The  clear-sky  solar radiation model applied in the r.sun is based on the work undertaken
       for development of European Solar Radiation Atlas (Scharmer and Greif 2000,  Page  et  al.
       2001,  Rigollier 2001). The clear sky model estimates the global radiation from the sum of
       its beam, diffuse and reflected components.  The main difference between  solar  radiation
       models  for  inclined surfaces in Europe is the treatment of the diffuse component. In the
       European climate this component is often the largest source of  estimation  error.  Taking
       into  consideration  the existing models and their limitation the European Solar Radiation
       Atlas team selected the Muneer (1990) model as it has a sound theoretical basis  and  thus
       more potential for later improvement.

       Details  of  underlying  equations  used  in  this  program  can be found in the reference
       literature cited below or book published by Neteler and Mitasova: Open Source GIS: A GRASS
       GIS Approach (published in Kluwer Academic Publishers in 2002).

       Average  monthly  values  of  the  Linke  turbidity  coefficient  for  a mild climate (see
       reference literature for your study area):
       MonthJanFebMarAprMayJunJulAugSepOctNovDecannual
            |  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
            |  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
            | 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
            |   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

       Planned  improvements  include  the  use  of  the  SOLPOS  algorithm  for  solar  geometry
       calculations and internal computation of aspect and slope.

   Solar time
       By default r.sun calculates times as true solar time, whereby solar noon is always exactly
       12 o'clock everywhere in the current region. Depending on where the zone  of  interest  is
       located  in  the  related  time zone, this may cause differences of up to an hour, in some
       cases (like Western Spain) even more.  On top of this, the offset varies during  the  year
       according to the Equation of Time.

       To  overcome  this problem, the user can use the option civiltime= in r.sun to make it use
       real-world (wall clock) time. For example, for Central Europe the timezone offset  is  +1,
       +2 when daylight saving time is in effect.

   Shadow maps
       A  map  of  shadows  can be extracted from the solar incidence angle map (incidout). Areas
       with zero values are shadowed. The -s flag has to be used.

   Large maps and out of memory problems
       With a large number or columns and rows, r.sun can consume significant amount  of  memory.
       While  output  raster  maps  are  not  partitionable,  the input raster maps are using the
       numpartitions parameter.  In case of out of memory error (ERROR: G_malloc: out of memory),
       the numpartitions parameter can be used to run a segmented calculation which consumes less
       memory during the computations.  The amount of memory by r.sun is estimated as follows:
       # without input raster map partitioning:
       #  memory requirements: 4 bytes per raster cell
       #  rows,cols: rows and columns of current region (find out with g.region)
       #  IR: number of input raster maps without horizon maps
       #  OR: number of output raster maps
       memory_bytes = rows*cols*(IR*4 + horizonsteps + OR*4)
       # with input raster map partitioning:
       memory_bytes = rows*cols*((IR*4+horizonsteps)/numpartitions  + OR*4)

EXAMPLE

       Calculation of the integrated daily irradiation for a region in North-Carolina for a given
       day of the year at 30m resolution. Here day 172 (i.e., 21 June in non-leap years):
       g.region rast=elev_ned_30m -p
       # considering cast shadows (-s)
       r.sun -s elev_ned_30m lin=2.5 alb=0.2 day=172 \
             beam_rad=b172 diff_rad=d172 \
             refl_rad=r172 insol_time=it172
       d.mon x0
       # show irradiation raster map [Wh.m-2.day-1]
       d.rast.leg b172
       # show insolation time raster map [h]
       d.rast.leg it172

SEE ALSO

        r.horizon, r.slope.aspect, r.sunmask, g.proj, r.null, v.surf.rst

REFERENCES

                      Hofierka,  J.,  Suri,  M. (2002): The solar radiation model for Open source
                     GIS: implementation and applications. International GRASS  users  conference
                     in Trento, Italy, September 2002.  (PDF)

                     Hofierka,  J.  (1997).  Direct  solar radiation modelling within an open GIS
                     environment. Proceedings of JEC-GI'97 conference  in  Vienna,  Austria,  IOS
                     Press Amsterdam, 575-584.

                     Jenco,  M.  (1992).  Distribution of direct solar radiation on georelief and
                     its modelling by means of complex digital  model  of  terrain  (in  Slovak).
                     Geograficky casopis, 44, 342-355.

                     Kasten,  F.  (1996).  The Linke turbidity factor based on improved values of
                     the integral Rayleigh optical thickness. Solar Energy, 56 (3), 239-244.

                     Kasten, F., Young, A.  T.  (1989).  Revised  optical  air  mass  tables  and
                     approximation formula. Applied Optics, 28, 4735-4738.

                     Kittler,  R., Mikler, J. (1986): Basis of the utilization of solar radiation
                     (in Slovak). VEDA, Bratislava, p. 150.

                     Krcho, J. (1990).  Morfometrická  analza  a  digitálne  modely
                     georeliéfu (Morphometric analysis and digital models of georelief, in
                     Slovak).  VEDA, Bratislava.

                     Muneer, T. (1990). Solar  radiation  model  for  Europe.  Building  services
                     engineering research and technology, 11, 4, 153-163.

                     Neteler,  M.,  Mitasova,  H.  (2002): Open Source GIS: A GRASS GIS Approach,
                     Kluwer  Academic  Publishers.  (Appendix  explains  formula;  r.sun   script
                     download)

                     Page,  J.  ed.  (1986).  Prediction of solar radiation on inclined surfaces.
                     Solar energy R&D in the European Community, series F – Solar radiation
                     data, Dordrecht (D. Reidel), 3, 71, 81-83.

                     Page,  J.,  Albuisson,  M.,  Wald,  L.  (2001). The European solar radiation
                     atlas: a valuable digital tool. Solar Energy, 71, 81-83.

                     Rigollier, Ch., Bauer, O., Wald, L. (2000). On the clear sky  model  of  the
                     ESRA - European Solar radiation Atlas - with respect to the Heliosat method.
                     Solar energy, 68, 33-48.

                     Scharmer, K., Greif, J., eds., (2000). The European solar  radiation  atlas,
                     Vol.  2:  Database and exploitation software. Paris (Les Presses de l’
                     École des Mines).

                     Joint Research Centre: GIS solar radiation database  for  Europe  and  Solar
                     radiation and GIS

AUTHORS

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

       Last changed: $Date: 2013-06-16 05:08:46 +0200 (Sun, 16 Jun 2013) $

       Full index

       © 2003-2013 GRASS Development Team