r.sun(1)	       Grass User's Manual		 r.sun(1)



NNAAMMEE
       rr..ssuunn   -  Computes  beam  (direct),  diffuse  and  ground
       reflected solar irradiation raster  maps  for  given  day,
       latitude, surface and atmospheric conditions. Solar param-
       eters (e.g.  time  of  sunrise  and  sunset,  declination,
       extraterrestrial irradiance, daylight length) are saved in
       a local text file. Alternatively, the local  time  can  be
       specified  to compute solar incidence angle and/or irradi-
       ance raster maps. The shadowing effect of  the  topography
       is optionally incorporated.

SSYYNNOOPPSSIISS
       rr..ssuunn

       rr..ssuunn hheellpp

       rr..ssuunn	[-s]	eelleevviinn=name    aassppiinn=name    ssllooppeeiinn=name
       [lliinnkkeeiinn=name]	[lliinn=value]   [aallbbeeddoo=name]   [aallbb=value]
       [llaattiinn=name]   [llaatt=value]   [ccooeeffbbhh=name]   [ccooeeffddhh=name]
       [iinncciiddoouutt=name]	   [bbeeaamm__rraadd=name]	[iinnssooll__ttiimmee=name]
       [ddiiffff__rraadd=name]	 [rreeffll__rraadd=name]  ddaayy=value  [sstteepp=value]
       [ddeecclliinn=value] [ttiimmee=value] [ddiisstt=value]

DDEESSCCRRIIPPTTIIOONN
       The solar geometry of the model is based on the	works  of
       Krcho  (1990),  later  improved by Jenco (1992). The equa-
       tions describing Sun &#8211; 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-ordi-
       nated  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 sci-
       ences, 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 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 script-
       ing  the two modes can be used separately or in a combina-
       tion to provide estimates for any desired  time	interval.
       The  model  accounts  for  sky obstruction by local relief
       features.  Several solar parameters are saved in  a  local
       text file named _r_._s_u_n___o_u_t_._t_x_t.

       The  solar incidence angle raster map _i_n_c_i_d_o_u_t is computed
       specifying elevation raster map _e_l_e_v_i_n, aspect raster  map
       _a_s_p_i_n,  slope  steepness  raster map _s_l_o_p_i_n_, given the day
       _d_a_y and local time _t_i_m_e. There is no need to define  lati-
       tude    for    locations    with    known    and   defined
       projection/coordinate system (check it  out  using  g.pro-
       jinfo  command).  If  you have undefined projection, (x,y)
       system, etc. then the latitude can be defined  explicitely
       for  large  areas  by input raster map _l_a_t_i_n with interpo-
       lated latitude values or,  for  smaller	areas,	a  single
       region  latitude value _l_a_t can be used instead. Elevation,
       slope as well as aspect should be  floating  point  raster
       maps. Undefined elevation is -9999 and undefined aspect 0.
       Null data in cells must be valid data (-9999  or  0).  The
       user  should run r.null to create/reset null file for your
       input raster maps.

       The specified day _d_a_y is the number of the day of the gen-
       eral  year  where January 1 is day no.1 and December 31 is
       365. Time _t_i_m_e 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 _d_e_c_l_i_n 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  north-
       ern  hemisphere	and negative for southern one. In similar
       principle the Linke turbidity factor  (_l_i_n_k_e_i_n,	_l_i_n)  and
       ground albedo (_a_l_b_e_d_o, _a_l_b) can be set.

       Besides	clear-sky radiations, user can compute a real-sky
       radiation (beam, diffuse) using _c_o_e_f_b_h  and  _c_o_e_f_d_h  input
       raster maps defining the fraction of the respective clear-
       sky  radiations	reduced  by  atmospheric  factors   (e.g.
       cloudiness).  Usually  these  coefficients can be obtained
       from a long-terms meteorological measurements.

       The solar irradiation or irradiance raster maps	_b_e_a_m___r_a_d,
       _d_i_f_f___r_a_d, _r_e_f_l___r_a_d are computed for a given day _d_a_y_, lati-
       tude _l_a_t _(_l_a_t_i_n_)_,  elevation  _e_l_e_v_i_n,  slope  _s_l_o_p_e_i_n  and
       aspect  _a_s_p_i_n  raster  files.  The  program uses the Linke
       atmosphere turbidity factor and ground albedo coefficient.
       A  default, single value of Linke factor is _l_i_n=3.0 and is
       near the annual average for rural-city  areas.  The  Linke
       factor  for an absolutely clear atmosphere is _l_i_n=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 given  day	are  com-
       puted  integrating the relevant irradiance between sunrise
       and sunset times for given day. The user can set finer  or
       coarser time step _s_t_e_p used for all-day radiation calcula-
       tions. A default value of _s_t_e_p is 0.5 hour.  Larger  steps
       (e.g.  1.0-2.0) can speed-up calculations but produce less
       reliable results. 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  moun-
       tainous 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 _d_i_s_t  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 _d_i_s_t less than 1.0  (i.e.  sam-
       pling  points  will  be	computed  at _d_i_s_t * cellsize dis-
       tance), 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  _d_i_s_t=1.0	should	give  reasonable results for most
       cases (e.g. on DEM).  _D_i_s_t  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  dis-
       sected relief. The fully shadowed areas are written to the
       ouput maps as zero values.

       The text file _r_._s_u_n___o_u_t_._t_x_t is generated with the  follow-
       ing 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.

OOPPTTIIOONNSS
       The user can run this program either interactively or non-
       interactively.	The program will be run non-interactively
       if the user specifies program arguments and flag  settings
       on the command line using the form:

       r.sun	[-s]	elevin=name    aspin=name    slopein=name
       [linkein=name]	[lin=value]   [albedo=name]   [alb=value]
       [latin=name]   [lat=value]   [coefbh=name]   [coefdh=name]
       [incidout=name]	   [insol_time=name]	  [beam_rad=name]
       [diff_rad=name]	 [refl_rad=name]  day=value  [step=value]
       [declin=value] [time=value] [dist=value]

       Alternately, the user can simply type _r_._s_u_n on the command
       line  without  program  arguments.  In this case, the user
       will be prompted for parameter values using  the  standard
       GRASS  parser interface. 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
       [kWh.m-2.day-1] are computed for a specified day.

   FFllaagg::
       --ss


   PPaarraammeetteerrss::
       eelleevviinn=name
	   Use	the  existing  raster file with elevationsname as
	   input [metres].

       aassppiinn=name
	   Use the existing raster file with aspectname as  input
	   (aspect  or	azimuth  of  the  solar  panel)  [decimal
	   degrees].

       ssllooppeeiinn=name
	   Use the existing raster file with slopename	as  input
	   (slope  angle  or solar panel inclination raster file)
	   [decimal degrees].

       lliinnkkeeiinn=name
	   Use the existing raster file  with  Linke  atmospheric
	   turbidity factor [-].

       lliinn=val
	   Set	the single value of the Linke atmospheric turbid-
	   ity factor (default: 3.0).

       aallbbeeddoo=name
	   Use the existing raster file with ground albedo raster
	   file [-].

       aallbb=val
	   Set	the  single  value of the ground albedo (default:
	   0.2).

       llaattiinn=name
	   Use the existing raster file with.latitude raster file
	   [decimal degrees].

       llaatt=name
	   Set	the single value of latitude [decimal degrees] to
	   val.

       ccooeeffbbhh=name
	   The real-sky beam radiation coefficient file.

       ccooeeffddhh=name
	   The real-sky diffuse radiation coefficient file.

       iinncciiddoouutt=name
	   Output solar  incidence  angle  raster  file  [decimal
	   degrees] (mode 1 only).

       iinnssooll__ttiimmee=name
	   Output  time  duration  of the beam irradiation raster
	   file [min.] (mode 2 only).

       bbeeaamm__rraadd=name
	   Output beam irradiance [W.m-2] (mode 1) or irradiation
	   raster file [Wh.m-2.day-1] (mode 2).

       ddiiffff__rraadd=name
	   Output diffuse irradiance [W.m-2] (mode 1) or irradia-
	   tion raster file [Wh.m-2.day-1] (mode 2).

       rreeffll__rraadd=name
	   Output ground reflected irradiance [W.m-2] (mode 1) or
	   irradiation raster file [Wh.m-2.day-1] (mode 2).

       ddaayy=val
	   Set the number of day of the year [1-365] to val.

       sstteepp=val
	   Set	the time step when computing radiation daily sums
	   [decimal hours] (default 0.5 hour) to val.

       ddeecclliinn=val
	   Set the declination value (overriding  the  internally
	   computed value) [radians] to val.

       ttiimmee=val
	   Set	the  decimal value of local (solar) time [decimal
	   hours] (to be set for mode 1 only) to val.

       ddiisstt=val
	   Set the step coefficient defining  the  sampling  dis-
	   tance  (0.2-1.5)  in relative values of a cell size to
	   val	(default: 1.0).






NNOOTTEESS
       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 radiomet-
       ric and topographic corrections in mountainous  and  hilly
       terrain	where very accurate investigations should be per-
       formed.

       The clear-sky solar radiation model applied in  the  r.sun
       is  based  on the work undertaken for development of Euro-
       pean Solar Radiation Atlas (Scharmer and Greif 2000,  Page
       et  al.	2001,  Rigollier 2001). The clear sky model esti-
       mates the global radiation from the sum of its beam,  dif-
       fuse 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  Publish-
       ers in 2002).

       Average	monthly values of the Linke turbidity coefficient
       for a mild climate  (see  reference  literature	for  your
       study  area): Month	Jan  Feb  Mar  Apr  May  Jun  Jul
       Aug  Sep  Oct  Nov  Dec	annual
       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 It should by noted that _r_._s_u_n
       currently uses a lot  of  memory,  some	improvements  are
       under  way.  Planned  improvements may includes the use of
       SOLPOS  algorithm  for  solar  geometry	calculations  and
       internal computation of aspect and slope.

SSEEEE AALLSSOO
       _s_._s_u_r_f_._r_s_t_, _r_._s_l_o_p_e_._a_s_p_e_c_t_, _r_._s_u_n_m_a_s_k

AAUUTTHHOORRSS
       Jaroslav Hofierka, GeoModel, s.r.o. Bratislava, Slovakia


       Marcel Suri, GeoModel, s.r.o. Bratislava, Slovakia


       (C)  2002,  Jaroslav  Hofierka,	Marcel Suri hofierka@geo-
       model.sk suri@geomodel.sk

RREEFFEERREENNCCEESS
       Hofierka, J., Suri, M. (2002): The clear-sky solar  radia-
       tion  model for Open source GIS: implementation and appli-
       cations. Manuscript submitted to the  International  GRASS
       users conference in Trento, Italy, September 2002.

       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  thick-
       ness. 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). Morphometric analysis and digital models
       of georelief.  VEDA, Bratislava (in Slovak).

       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.

       Page,  J.  ed.  (1986).	Prediction  of solar radiation on
       inclined surfaces.  Solar energy R&D in the European  Com-
       munity,	series	F &#8211; 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  soft-
       ware.  Paris  (Les  Presses  de	l&#8217; &Eacute;cole des
       Mines).

       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_2_/_0_4_/_2_2 _1_7_:_3_5_:_1_8 _$



GRASS 5.0						 r.sun(1)
