r.sun.hourly
Runs r.sun in loop for given time range within one day (mode 1 or 2)
r.sun.hourly [-ctbpm] elevation=string [aspect=string] [slope=string] [linke=name] [linke_value=float] [albedo=name] [albedo_value=float] [coeff_bh=name] [coeff_bh_strds=name] [coeff_dh=name] [coeff_dh_strds=name] [lat=name] [long=name] mode=string start_time=float end_time=float [time_step=float] day=integer year=integer [civil_time=float] [distance_step=float] [beam_rad_basename=string] [diff_rad_basename=string] [refl_rad_basename=string] [glob_rad_basename=string] [incidout_basename=string] [beam_rad=string] [diff_rad=string] [refl_rad=string] [glob_rad=string] [solar_constant=float] [nprocs=integer] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]
Example:
r.sun.hourly elevation=string mode=mode1 start_time=float end_time=float day=integer year=1900
grass.script.run_command("r.sun.hourly", elevation, aspect=None, slope=None, linke=None, linke_value=3.0, albedo=None, albedo_value=0.2, coeff_bh=None, coeff_bh_strds=None, coeff_dh=None, coeff_dh_strds=None, lat=None, long=None, mode="mode1", start_time, end_time, time_step=1, day, year=1900, civil_time=None, distance_step=1.0, beam_rad_basename=None, diff_rad_basename=None, refl_rad_basename=None, glob_rad_basename=None, incidout_basename=None, beam_rad=None, diff_rad=None, refl_rad=None, glob_rad=None, solar_constant=None, nprocs=1, flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)
Example:
gs.run_command("r.sun.hourly", elevation="string", mode="mode1", start_time=float, end_time=float, day=integer, year=1900)
Parameters
elevation=string [required]
Name of the input elevation raster map [meters]
aspect=string
Name of the input aspect map (terrain aspect or azimuth of the solar panel) [decimal degrees]
slope=string
Name of the input slope raster map (terrain slope or solar panel inclination) [decimal degrees]
linke=name
Name of the Linke atmospheric turbidity coefficient input raster map [-]
linke_value=float
A single value of the Linke atmospheric turbidity coefficient [-]
Allowed values: 0.0-
Default: 3.0
albedo=name
Name of the ground albedo coefficient input raster map [-]
albedo_value=float
A single value of the ground albedo coefficient [-]
Allowed values: 0.0-1.0
Default: 0.2
coeff_bh=name
Name of real-sky beam radiation coefficient (thick cloud) input raster map [0-1]
coeff_bh_strds=name
Name of real-sky beam radiation coefficient (thick cloud) input space-time raster dataset
coeff_dh=name
Name of real-sky diffuse radiation coefficient (haze) input raster map [0-1]
coeff_dh_strds=name
Name of real-sky diffuse radiation coefficient (haze) input space-time raster dataset
lat=name
Name of input raster map containing latitudes [decimal degrees]
long=name
Name of input raster map containing longitudes [decimal degrees]
mode=string [required]
Select r.sun mode to choose between irradiance (mode 1) and irradiation (mode 2)
Allowed values: mode1, mode2
Default: mode1
mode1: r.sun mode 1 computes irradiance [W.m-2]
mode2: r.sun mode 2 computes irradiation [Wh.m-2]
start_time=float [required]
Start time of interval
Use up to 2 decimal places
Allowed values: 0-24
end_time=float [required]
End time of interval
Use up to 2 decimal places
Allowed values: 0-24
time_step=float
Time step for running r.sun [decimal hours]
Use up to 2 decimal places
Allowed values: 0-24
Default: 1
day=integer [required]
No. of day of the year
Allowed values: 1-365
year=integer [required]
Year used for map registration into temporal dataset or r.timestamp
This value is not used in r.sun calculations
Allowed values: 1900-9999
Default: 1900
civil_time=float
Civil time zone value, if none, the time will be local solar time
distance_step=float
Sampling distance step coefficient (0.5-1.5)
Default: 1.0
beam_rad_basename=string
Base name for output beam irradiance [W.m-2] (mode 1) or irradiation raster map [Wh.m-2] (mode 2)
Underscore and time are added to the base name for each map
diff_rad_basename=string
Base name for output diffuse irradiance [W.m-2] (mode 1) or irradiation raster map [Wh.m-2] (mode 2)
Underscore and time are added to the base name for each map
refl_rad_basename=string
Base name for output ground reflected irradiance [W.m-2] (mode 1) or irradiation raster map [Wh.m-2] (mode 2)
Underscore and time are added to the base name for each map
glob_rad_basename=string
Base name for output global (total) irradiance [W.m-2] (mode 1) or irradiation raster map [Wh.m-2] (mode 2)
Underscore and time are added to the base name for each map
incidout_basename=string
Base name for output incidence angle raster maps (mode 1 only)
Underscore and time are added to the base name for each map
beam_rad=string
Output beam irradiation raster map [Wh.m-2] (mode 2) integrated over specified time period
diff_rad=string
Output diffuse irradiation raster map [Wh.m-2] (mode 2) integrated over specified time period
refl_rad=string
Output ground reflected irradiation raster map [Wh.m-2] (mode 2) integrated over specified time period
glob_rad=string
Output global (total) irradiation raster map [Wh.m-2] (mode 2) integrated over specified time period
solar_constant=float
Solar constant [W/m^2]
If not specified, r.sun default will be used.
nprocs=integer
Number of r.sun processes to run in parallel
Allowed values: 1-
Default: 1
-c
Compute cumulative raster maps of irradiation (only with mode 2)
-t
Register created series of output maps into temporal dataset
Dataset name is the same as the base name for the output series of maps
-b
Create binary rasters instead of irradiance rasters
-p
Do not incorporate the shadowing effect of terrain
-m
Use the low-memory version of the program
--overwrite
Allow output files to overwrite existing files
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--qq
Very quiet module output
--ui
Force launching GUI dialog
elevation : str, required
Name of the input elevation raster map [meters]
Used as: input, raster
aspect : str, optional
Name of the input aspect map (terrain aspect or azimuth of the solar panel) [decimal degrees]
Used as: input, raster
slope : str, optional
Name of the input slope raster map (terrain slope or solar panel inclination) [decimal degrees]
Used as: input, raster
linke : str, optional
Name of the Linke atmospheric turbidity coefficient input raster map [-]
Used as: input, raster, name
linke_value : float, optional
A single value of the Linke atmospheric turbidity coefficient [-]
Allowed values: 0.0-
Default: 3.0
albedo : str, optional
Name of the ground albedo coefficient input raster map [-]
Used as: input, raster, name
albedo_value : float, optional
A single value of the ground albedo coefficient [-]
Allowed values: 0.0-1.0
Default: 0.2
coeff_bh : str, optional
Name of real-sky beam radiation coefficient (thick cloud) input raster map [0-1]
Used as: input, raster, name
coeff_bh_strds : str, optional
Name of real-sky beam radiation coefficient (thick cloud) input space-time raster dataset
Used as: input, strds, name
coeff_dh : str, optional
Name of real-sky diffuse radiation coefficient (haze) input raster map [0-1]
Used as: input, raster, name
coeff_dh_strds : str, optional
Name of real-sky diffuse radiation coefficient (haze) input space-time raster dataset
Used as: input, strds, name
lat : str, optional
Name of input raster map containing latitudes [decimal degrees]
Used as: input, raster, name
long : str, optional
Name of input raster map containing longitudes [decimal degrees]
Used as: input, raster, name
mode : str, required
Select r.sun mode to choose between irradiance (mode 1) and irradiation (mode 2)
Allowed values: mode1, mode2
mode1: r.sun mode 1 computes irradiance [W.m-2]
mode2: r.sun mode 2 computes irradiation [Wh.m-2]
Default: mode1
start_time : float, required
Start time of interval
Use up to 2 decimal places
Allowed values: 0-24
end_time : float, required
End time of interval
Use up to 2 decimal places
Allowed values: 0-24
time_step : float, optional
Time step for running r.sun [decimal hours]
Use up to 2 decimal places
Allowed values: 0-24
Default: 1
day : int, required
No. of day of the year
Allowed values: 1-365
year : int, required
Year used for map registration into temporal dataset or r.timestamp
This value is not used in r.sun calculations
Allowed values: 1900-9999
Default: 1900
civil_time : float, optional
Civil time zone value, if none, the time will be local solar time
distance_step : float, optional
Sampling distance step coefficient (0.5-1.5)
Default: 1.0
beam_rad_basename : str, optional
Base name for output beam irradiance [W.m-2] (mode 1) or irradiation raster map [Wh.m-2] (mode 2)
Underscore and time are added to the base name for each map
diff_rad_basename : str, optional
Base name for output diffuse irradiance [W.m-2] (mode 1) or irradiation raster map [Wh.m-2] (mode 2)
Underscore and time are added to the base name for each map
refl_rad_basename : str, optional
Base name for output ground reflected irradiance [W.m-2] (mode 1) or irradiation raster map [Wh.m-2] (mode 2)
Underscore and time are added to the base name for each map
glob_rad_basename : str, optional
Base name for output global (total) irradiance [W.m-2] (mode 1) or irradiation raster map [Wh.m-2] (mode 2)
Underscore and time are added to the base name for each map
incidout_basename : str, optional
Base name for output incidence angle raster maps (mode 1 only)
Underscore and time are added to the base name for each map
beam_rad : str, optional
Output beam irradiation raster map [Wh.m-2] (mode 2) integrated over specified time period
diff_rad : str, optional
Output diffuse irradiation raster map [Wh.m-2] (mode 2) integrated over specified time period
refl_rad : str, optional
Output ground reflected irradiation raster map [Wh.m-2] (mode 2) integrated over specified time period
glob_rad : str, optional
Output global (total) irradiation raster map [Wh.m-2] (mode 2) integrated over specified time period
solar_constant : float, optional
Solar constant [W/m^2]
If not specified, r.sun default will be used.
nprocs : int, optional
Number of r.sun processes to run in parallel
Allowed values: 1-
Default: 1
flags : str, optional
Allowed values: c, t, b, p, m
c
Compute cumulative raster maps of irradiation (only with mode 2)
t
Register created series of output maps into temporal dataset
Dataset name is the same as the base name for the output series of maps
b
Create binary rasters instead of irradiance rasters
p
Do not incorporate the shadowing effect of terrain
m
Use the low-memory version of the program
overwrite: bool, optional
Allow output files to overwrite existing files
Default: False
verbose: bool, optional
Verbose module output
Default: False
quiet: bool, optional
Quiet module output
Default: False
superquiet: bool, optional
Very quiet module output
Default: False
DESCRIPTION
r.sun.hourly is a convenient script for running r.sun for multiple times in a loop. It allows to run r.sun in mode 1 to create maps of instantaneous solar irradiance. Alternatively, it allows to integrate solar irradiance maps over specified time period to compute solar irradiation (mode 2). See r.sun manual page for more information.
Output parameters explanation
There are three basic types of output:
In mode 1, if one of options beam_rad_basename, diff_rad_basename refl_rad_basename, glob_rad_basename, and incidout_basename is selected, it will compute a time series of irradiance maps. Optionally, b flag will convert them to binary rasters representing shaded areas. Using this flag in combination with beam_rad_basename is a convenient way to determine if there is direct sunlight or not at a certain place and time. Series of maps are (if flag t is checked) registered to space time raster dataset with absolute time and point time (not interval time). Option year has to be specified so that the raster maps can be registered to space time dataset or assigned a timestamp. The reason is that it is not possible to assign time without date.
In mode 2, a series of solar irradiation maps will be computed with units Wh/m2. This is done by multiplying an instantaneous irradiance raster computed in the middle of the specified intervals by time step. For example, if start_time is 8, end_time is 10 and time_step is 0.5, the irradiation rasters will be computed for times 8:15, 8:45, 9:15 and 9:45.
If flag c is selected it will accumulate the irradiation values, meaning the last raster represents all solar irradiation during the period.
When any of output options beam_rad, diff_rad refl_rad and glob_rad are specified, irradiation rasters are summed over the specified period (mode 2 only).
Real-sky radiation parameters
Real-sky radiation parameters (see r.sun) can be input as raster map (coeff_bh and coeff_dh), or space-time raster dataset (coeff_bh_strds and coeff_dh_strds) to account for time-varying conditions. The space-time raster dataset (strds) needs to be interval-based (i.e. have start and end time, see t.register, for more details).
EXAMPLES
Calculate for current region the beam irradiance (direct radiation) for DOY 355 in 2014 from 8am to 3pm:
g.region -p
r.sun.hourly elevation=elevation start_time=8 end_time=15 \
day=355 year=2014 beam_rad_basename=beam nprocs=4 -t
# show information about newly created space time dataset
t.info beam
# show raster maps registered in beam temporal dataset
t.rast.list beam
Calculate beam irradiation during day and also cumulative irradiation, use different steps:
g.region raster=elevation res=100 -pa
r.sun.hourly elevation=elevation year=2019 day=100 start=8 end=16 time_step=0.333 beam_rad_basename=beam_m2_step_short mode=mode2 nprocs=4 -t
r.sun.hourly elevation=elevation year=2019 day=100 start=8 end=16 time_step=0.333 beam_rad_basename=beam_m2_step_short_cum mode=mode2 nprocs=4 -tc
r.sun.hourly elevation=elevation year=2019 day=100 start=8 end=16 time_step=1 beam_rad_basename=beam_m2_step_long mode=mode2 nprocs=4 -t
r.sun.hourly elevation=elevation year=2019 day=100 start=8 end=16 time_step=1 beam_rad_basename=beam_m2_step_long_cum mode=mode2 nprocs=4 -tc
g.gui.tplot strds=beam_m2_step_short,beam_m2_step_long,beam_m2_step_short_cum,beam_m2_step_long_cum coordinates=636919,220431
NOTE
Beam irradiance binary raster maps can be displayed as semitransparent over other map layers or module r.null can be used to set one of the values (either shade or sunlight) as NULL.
SEE ALSO
r.sun, r.sun.daily in Addons
AUTHORS
Vaclav Petras, NCSU GeoForAll
Lab,
Anna Petrasova, NCSU GeoForAll
Lab
SOURCE CODE
Available at: r.sun.hourly source code
(history)
Latest change: Thursday Feb 20 13:02:26 2025 in commit 53de819