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  atmo-
       spheric	conditions. Solar parameters (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 irradiance raster maps. The  shad-
       owing 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 equations  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-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 reso-
       lution of the modelled area, as well as integration over time, are lim-
       ited  only by the memory and data storage resources. The model is built
       to fulfil user needs in various fields of science (hydrology, climatol-
       ogy,  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 topog-
       raphy.	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 radi-
       ation [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 esti-
       mates 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  latitude for locations with known and defined projec-
       tion/coordinate system (check it out using g.projinfo 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
       interpolated  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  general  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  dis-
       tributed  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 (_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_, latitude _l_a_t _(_l_a_t_i_n_)_, eleva-
       tion _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 coeffi-
       cient.  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 abso-
       lutely 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  computed
       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	calculations.  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/irradia-
       tion  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	preci-
       sion  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. sampling 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 sur-
       rounding 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  dissected  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  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	radia-
       tion  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-  interac-
       tively.	 The  program will be run non-interactively if the user speci-
       fies 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  parame-
       ter  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  com-
       puted 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  fac-
	   tor [-].

       lliinn=val
	   Set	the  single  value  of	the Linke atmospheric turbidity 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  irradiation	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 distance (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  con-
       cerning	energy	industry,  landscape,  vegetation, evapotranspiration,
       snowmelt or remote sensing. Solar rays  incidence  angle  maps  can  be
       effectively  used  in  radiometric and topographic corrections in moun-
       tainous 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, dif-
       fuse and reflected components. The main difference between solar radia-
       tion 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): 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@geomodel.sk suri@geo-
       model.sk

RREEFFEERREENNCCEESS
       Hofierka, J., Suri, M. (2002): The clear-sky solar radiation model  for
       Open  source GIS: implementation and applications. 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,  Aus-
       tria, 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 Slo-
       vak).  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 radi-
       ation (in Slovak). VEDA, Bratislava, p. 150.

       Krcho,  J.  (1990).  Morphometric analysis and digital models of geore-
       lief.  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  sur-
       faces.	Solar  energy  R&D in the European Community, 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 software. 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)
