Model help:TopoFlow-Meteorology

The CSDMS Help System


The module is the meteorology process component for a D8-based, spatial hydrologic model

Model introduction

This component reads a variety of variables for the atmosphere and for the land surface from input files or as simple scalars. It then computes many additional variables, such as vapor pressure, eair, and net shortwave (solar) radiation, QSW, using built-in shortwave and longwave radiation calculators that are based on celestial mechanics and widely-used empirical relationships. These additional variables are needed by the Snowmelt → Energy Balance and Evaporation → Energy Balance components. Direct, diffuse and back-scattered radiation fluxes are all modeled. Properties of the atmosphere (e.g. precipitation rate, P, air temperature, Tair, relative humidity, RH, and dust attenuation, γ), are used as well as surface/topographic properties (e.g. slope angle, aspect angle and surface albedo). The approach used here closely follows the one outlined in Appendix E of Dingman (2002). However, instantaneous vs. day-integrated radiation fluxes are used and the optical air mass is modeled using the widely used method of Kasten and Young (1989).

Model parameters

Parameter Description Unit
Components status Enabled/Disabled
Input directory
Output directory
Site prefix file prefix for the study site
Case prefix file prefix for the model scenario
Number of steps number of time steps
Time step meteorology time step sec
ρ H2O type allowed input types (Scalar/Grid/Time_Series/Grid_Sequence)
ρ H2O density of water kg/m3
Cp_air type allowed input types (Scalar/Grid/Time_Series/Grid_Sequence)
Cp air heat capacity of air J/kg/K
ρ_air type: allowed input types (Scalar/Grid/Time_Series/Grid_Sequence)
ρ air density of air kg/m3
Precipitation rates type allowed input types (Scalar/Grid/Time_Series/Grid_Sequence)
Precipitation rates mm/yr
PRECIPITATION ONLY toggle toggle to turn off all variable updates except precipitation
Parameter Description Unit
T_air type allowed input types (Scalar/Grid/Time_Series/Grid_Sequence) -
T_air temperature of air degree C
T_surf type allowed input types (Scalar/Grid/Time_Series/Grid_Sequence)
T_surf temperature of surface degree C
RH type allowed input types (Scalar/Grid/Time_Series/Grid_Sequence)
RH relative humidity
p0 type allowed input types (Scalar/Grid/Time_Series/Grid_Sequence)
p0 atmospheric pressure mbar
uz type allowed input types (Scalar/Grid/Time_Series/Grid_Sequence)
uz wind velocity at height z m / s
z type allowed input types (Scalar/Grid/Time_Series/Grid_Sequence)
z wind reference height m
z0_air type allowed input types (Scalar/Grid/Time_Series/Grid_Sequence)
z0_air surface roughness length scale for wind m
Parameter Description Unit
albedo type allowed input types (Scalar/Grid/Time_Series/Grid_Sequence)
albedo surface albedo in [0,1]
emissivity type allowed input types (Scalar/Grid/Time_Series/Grid_Sequence)
emissivity surface emissivity in [0,1]
dust atten. type allowed input types (Scalar/Grid/Time_Series/Grid_Sequence)
dust attenuation dust attenuation factor in [0,0.3]
cloud factor type allowed input types (Scalar/Grid/Time_Series/Grid_Sequence)
cloud factor cloudiness factor in [0,1]
canopy factor type allowed input types (Scalar/Grid/Time_Series/Grid_Sequence)
canopy factor canopy coverage factor in [0,1]
slope grid file flat binary, row-major file with grid of 4-byte slopes
aspect grid file flat binary, row-major file with grid of 4-byte aspects
time zone offset time zone offset from GMT
start month
Parameter Description Unit
Save grid timestep time interval between saved grids sec
Save e_air grids toggle option to save grids of vapor pressure (in air) -
Save e_air grids file filename for grid stack of vapor pressure (in air) mbar
Save e_surf grids toggle option to save grids of vapor pressure (at surface) -
Save e_surf grids file filename for grid stack of vapor pressure (surf) mbar
Save Qn_SW grids toggle option to save grids of net short wave radiation -
Save Qn_SW grids file filename for grid stack of short wave radiation W / m2
Save Qn_LW grids toggle option to save grids of net longwave radiation -
Save Qn_LW grids file filename for grid stack of net longwave radiation W / m2
Save em_air grids toggle option to save grids of air emissivity
Save em_air grids file filename for grid stack of air emissivity in [0,1]
Parameter Description Unit
Save pixels timestep time interval between time series values sec
Save e_air pixels toggle option to save time series of sat. vapor pressure (in air) -
Save e_air pixels file filename for time series of sat. vapor pressure (in air) mbar
Save e_surf pixels toggle option to save time series of sat. vapor pressure (at surface) -
Save e_surf pixels file filename for time series of sat. vapor pressure (surf) mbar
Save Qn_SW pixels toggle option to save time series of net shortwave radiation -
Save Qn_SW pixels file filename for time series of short wave radiation W / m2
Save Qn_LW pixels toggle option to save time series of net longwave radiation -
Save Qn_LW pixels file filename for time series of net longwave radiation W / m2
Save em_air pixels toggle option to save time series of air emissivity
Save em_air pixels file filename for time series of air emissivity in [0,1]

Uses ports

• Snow (Snowmelt)

Provides ports

• Meteorology
• Configure (tabbed dialog GUI to change settings)
• Run (only if used as the Driver)

Main equations

Equations Used to Compute Longwave Radiation

  • Net longwave radiation
[math]\displaystyle{ Q_{LW} = \left (LW_{in} - LW_{out}\right ) }[/math] (1)
  • Incoming longwave radiation (using Stefan-Bolzman law)
[math]\displaystyle{ LW_{in} = \varepsilon_{air} \cdot \sigma \cdot \left (T_{air} + 273.15 \right )^4 }[/math] (2)
  • Outgoing longwave radiation (using Stefan-Bolzman law)
[math]\displaystyle{ LW_{out} = \varepsilon_{surf} \cdot \sigma \cdot \left (T_{surf} + 273.15 \right )^4 + \left ( 1 - \varepsilon_{surf} \right ) \, LW_{in} }[/math] (3)
  • Saturation vapor pressure, Brutsaert (1975) method
[math]\displaystyle{ e_{sat} = 0.611 \cdot \exp [\left ( 17.3 \cdot T \right ) / \left ( T + 237.3 \right )] }[/math] (4)
  • Saturation vapor pressure, Satterlund (1979) method
[math]\displaystyle{ e_{sat} = \frac{10^\left[11.4 - (2353 / (T + 273.15)) \right]}{1000} }[/math] (4)
  • Vapor pressure of air
[math]\displaystyle{ e_{air} = e_{sat} \cdot RH }[/math] (5)
  • Emissivity of air
[math]\displaystyle{ \varepsilon_{air} = \left[\left (1 - F \right ) \, 1.72 \, \left[e_{air}/ \left (T_{air} + 273.15 \right ) \right]^ \left ({\frac{1}{7}} \right ) \, \left (1 + 0.22 \cdot C^2 \right ) \right] + F }[/math] (6)

Equations Used to Compute Shortwave Radiation

  • Day angle or fractional year
[math]\displaystyle{ \Gamma = 2 \, \pi \, \left ( J - 1 \right ) / 365 }[/math] (1)
  • Earth orbit eccentricity correlation
[math]\displaystyle{ \begin{align} E_{0} &= \left ( r_{0} / r \right )^2 \\ &= 1.000110 + 0.034221 \cdot \cos \left ( \Gamma \right ) + 0.001280 \cdot \sin \left ( \Gamma \right ) + \\ & \qquad \qquad \qquad 0.000719 \cdot \cos \left ( 2 \, \Gamma \right ) + 0.000077 \cdot \sin \left ( 2 \, \Gamma \right ) \end{align} }[/math] (2)
  • Declination of the sun at a given latitude
[math]\displaystyle{ \begin{align} \delta &= \left( 180 / \pi \right) \, [ 0.006918 - 0.399912 \cdot \cos \left( \Gamma \right) + 0.070257 \cdot \sin \left( \Gamma \right) - \\ & \qquad \qquad \qquad \qquad 0.006758 \cdot \cos \left( 2 \, \Gamma \right) + 0.000907 \cdot \sin \left( 2 \, \Gamma \right) - \\ & \qquad \qquad \qquad \qquad 0.002697 \cdot \cos \left( 3 \, \Gamma \right) + 0.00148 \cdot \sin \left( 3 \, \Gamma \right) ] \end{align} }[/math] (3)
  • Zenith angle
[math]\displaystyle{ \theta = \arccos [\sin \left ( \Lambda \right ) \, \sin \left ( \delta \right ) + \cos \left ( \Lambda \right ) + \cos \left ( \Lambda \right ) \, \cos \left (\delta \right ) \, \cos \left ( \omega \, t_{h} \right )] }[/math] (4)
  • Sunrise offset, horizontal plane (hours before true solar noon)
[math]\displaystyle{ T_{hr} = - {\frac{ \arccos \left[- \tan \left( \Lambda \right) \, \tan \left ( \delta \right ) )\right] }{\omega}} }[/math] (5)
  • Sunset offset, horizontal plane (hours after true solar noon)
[math]\displaystyle{ T_{hs} = + {\frac{ \arccos \left[- \tan \left ( \Lambda \right ) \, \tan \left ( \delta \right ) \right]}{\omega}} }[/math] (6)
  • Instantaneous extraterrestrial radiation flux on a horizontal plane
[math]\displaystyle{ k_{ET}^' = I_{sc} \, E_{0} \, [\cos \left ( \delta \right ) \, \cos \left ( \Lambda \right ) \, \cos \left ( \omega \, t \right ) + \sin \left ( \delta \right ) \, \sin \left ( \Lambda \right )] }[/math] (7)
  • Dew point temperature
[math]\displaystyle{ T_{dew} = {\frac{ \ln \left ( e\right ) + 0.4926}{0.0708 - 0.00421 \, \ln \left ( e \right )}} }[/math] (8)
  • Precipitable water content
[math]\displaystyle{ W_{p} = 1.12 \, \exp \left ( 0.0614 \, T_{dew} \right ) }[/math] (9)
  • Optical air mass (from Kasten and Young, 1989)
[math]\displaystyle{ M_{opt} = 1 / [\cos \left ( \theta \right ) + 0.50572 \, \left ( 96.07995 - \theta \right ) ^ \left (-1.6364 \right )] }[/math] (10)
  • Total atmospheric transmissivity
[math]\displaystyle{ \tau = \exp \left[ -0.124 - 0.0207 \, W_{p} - \left (0.0682 + 0.0248 \, W_{p} \right ) \, M_{opt} \right] }[/math] (11)
  • Instantaneous direct radiation flux
[math]\displaystyle{ k_{dir}^ ' = \tau \, k_{ET}^ ' }[/math] (12)
  • Scattering attenuation
[math]\displaystyle{ \gamma_{s} = 1 - \exp \left [ -0.0363 - 0.0084 \, W_{p} - \left (0.0572 + 0.0173 \, W_{p} \right ) \, M_{opt} \right ] + \gamma_{dust} }[/math] (13)
  • Instantaneous diffuse radiation flux
[math]\displaystyle{ k_{dif}^ ' = 0.5 \, \gamma_{s} \, k_{ET} ^ ' }[/math] (13)
  • Instantaneous global radiation flux
[math]\displaystyle{ k_{global}^' = k_{dir}^' + k_{dif}^' }[/math] (14)
  • Backscattered radiation flux
[math]\displaystyle{ k_{bs}^' = 0.5 \, a \, \gamma_{s} \, k_{global}^' }[/math] (15)
  • Longitude offset for sloped topography
[math]\displaystyle{ \Delta \Omega = \arctan \left[{\frac{\sin \left ( \beta \right ) \, \sin \left ( \alpha \right )}{\cos \left ( \beta \right ) \, \cos \left ( \Lambda \right ) - \sin \left ( \beta \right ) \, \sin \left ( \Lambda \right ) \, \cos \left ( \alpha \right )}} \right] }[/math] (16)
  • Equivalent latitude for sloped topography
[math]\displaystyle{ \Lambda_{eq} = \arcsin \left[ \sin \left (\beta \right ) \, \cos \left ( \alpha \right ) \, \cos \left ( \Lambda \right ) + \cos \left ( \beta \right ) \, \sin \left ( \Lambda \right ) \right] }[/math] (17)
  • Sunrise offset for sloped topography
[math]\displaystyle{ T_{sr} = - {\frac{ \arccos \left[ - \tan \left ( \Lambda_{eq} \right ) \, \tan \left ( \delta \right ) \right] - \Delta \Omega}{\omega}} }[/math] (18)
  • Sunset offset for sloped topography
[math]\displaystyle{ T_{ss} = + {\frac{ \arccos \left[ - \tan \left ( \Lambda_{eq} \right ) \, \tan \left ( \delta \right ) \right] - \Delta \Omega}{\omega}} }[/math] (19)
  • Instantaneous extra-terrestrial radiation flux for sloped topography
[math]\displaystyle{ k_{ET} = I_{sc} E_{\theta} \left[ \cos \left ( \delta \right ) \cos \left ( \Lambda_{eg} \right ) \cos \left ( \omega \, t_{h} + \Delta \Omega \right ) + \sin \left ( \delta \right ) \sin \left ( \Lambda_{eg} \right ) \right] }[/math] (20)
  • Instantaneous clear sky radiation for sloped topography
[math]\displaystyle{ k_{cs} = \tau \, k_{ET} + k_{dif}^' + k_{bs} ^' }[/math] (21)
  • Net shortwave radiation for sloped topography
[math]\displaystyle{ Q_{SW} = k_{cs} }[/math] (21)
  • Earth rotation rate
[math]\displaystyle{ \Omega = 2 \, \pi \, {DPY}_{sidereal} }[/math] (22)


Notes on Input Parameters

For each input variable, you may choose from the droplist of data types. For the "Scalar" data type, enter a numeric value with the units indicated in the dialog. For the other data types, enter a filename. Values in files must also use the indicated units.

Single grids and grid sequences are assumed to be stored as RTG and RTS files, respectively. Time series are assumed to be stored as text files, with one value per line. For a time series or grid sequence, the time between values must coincide with the timestep provided.

For DEMs with pixel geometry and bounding box given in terms of Geographic coordinates, the latitude and longitude of each pixel is used in the calculations. For DEMs with a "fixed-length" pixel geometry (e.g. UTM coordinates), which tend to span smaller areas, the dialog prompts for a single lat/lon pair to be used in the calculations.

In the calculation, the timestep between frames in the new grid sequence (RTS file) should typically be about one hour and should match the timestep that will be used to model the Snowmelt or Evaporation processes. The number of frames in the RTS file will depend on the start and stop times, as well as the timestep. The start time, stop time and timestep should match those used to create the new shortwave radiation file with extension "*.Qn-SW".

Notes on the Equations

All variables and their units can be seen by expanding the Nomenclature section above.

time zone: Boundaries of time zones can be very irregular and a time zone map should be consulted if you are unsure. The time zone is not simply a function of the longitude. You can select an adjacent time zone to include the effect of Daylight Savings Time. Time zones with non-integer offsets from GMT are not yet supported.

slope: Topographic slopes (not slope angles) are specified as dimensionless numbers [m/m]. A RiverTools grid (RTG file) with extension "_slope.rtg", "_mf-slope.rtg" or "_dinf-slope.rtg" can be used.

aspect: Aspect is specified as an angle measured in radians counter-clockwise from due east (the standard convention). A RiverTools grid (RTG file) with extension "_mf-angle.rtg" or "_dinf-angle.rtg" can be used for the (continuous-angle) aspect grid.

QSW is set to zero between the times of local sunset and local sunrise, so frames in the RTS file that correspond to nighttime hours will contain only zeros.

Notes on the Equations to Compute Longwave Radiation

The value 237.3 in Brutsaert's equation for emair is not a misprint.

Notes on the Equations to Compute Shortwave Radiation

The declination of the sun reaches its lowest value of -23.5 degrees on the Winter Solstice (Dec. 21/22) and reaches its highest value of 23.5 degrees on the Summer Solstice(June 21/22). It is zero for both the Vernal Equinox (Mar. 20/21) and the Autumnal Equinox (Sept. 22/23). The value of 23.4397 degrees is the fixed tilt angle of the Earth's axis from from the plane of the ecliptic.

The equation for declination of the sun is a Fourier series expansion that is supposed to have a maximum error of 0.0006 radians (less than 3 arcminutes). This should be double-checked. The equation shown here can also be found at:, and is derived in the paper called "Fourier series representation of the position of the sun", by J.W. Spencer (1971), of CSIRO.

If (abs(latdeg) gt 66.5) we are above Arctic circle or below Antarctic circle. This can also happen if latdeg is an "equivalent latitude" for sloped topography. In this case, the absolute value of the argument to ACOS can exceed one and there is either no sunrise or no sunset at the given location. If the argument to ACOS is less than -1, it is set to -1. If it is greater than 1 it is set to 1.

True solar noon (TSN) for a given location is the time when the sun reaches its highest point above the horizon. At this time, the zenith angle attains its minimum value for the day and the sun is said to be "on the meridian." In order to compute the clock time at which true solar noon occurs, we start with the number 12, then add the following three corrections:

(1) ΔTc is the time difference between true solar noon and local clock noon, without accounting for any arbitrary time zone adjustments. It is computed from the so-called Equation of Time and is related to the figure-8-shaped "analemma". See: and Whitman, A.M. (2003) A Simple Expression for the Equation of Time (online document:
(2) ΔTtz is computed as the (signed) difference between the local longitude and the longitude at the center of the local time zone, divided by 15. The Earth turns through 15 degrees of longitude in one hour. The longitude at the center of a time zone is given by its GMT offset (and integer between -12 and 12) times 15.
(3) ΔTdst is a correction for Daylight Savings Time, generally an integer.

Sunrise and sunset occur when zenith angle, θ, is equal to π/2, so cos(θ) = 0. Using the equation for the zenith angle we can then solve for time offsets (e.g. sunrise and sunset offsets) as th, in hours.

Many of these equations are from Dingman, Appendix E. In his notation, a lower-case "k" indicates an instantaneous radiation flux. In expressions for "k", the argument "th" is the number of hours before (th < 0) or after (th > 0) true solar noon. Upper-case "K" then indicates the integral of "k" when th is allowed to vary from the sunrise offset to the sunset offset. Primes on "k" or "K" indicate values for a horizontal plane which must be corrected (as explained by Dingman) for sloped topography. For example, the sunrise and sunset times for a given location depend on the slope and aspect of the local topography.

The equation for kET' is similar to Dingman, App. E, E-25, but his was integrated over one day and this one is instantaneous. Need to double check that integrating the equation here over one day gives his equation E-25. Note that ω has units of radians/hour and ΔΩ (longitude offset) has units of radians. See the TopoFlow source code file:, which is imported by

TopoFlow provides two methods for computing the saturated vapor pressure, esat = e*, as a function of temperature, T. One is from Brutsaert (1975) (and used in Dingman) and the other is from Satterlund (1979). Liston (1995, EnBal) uses the Satterlund method. When plotted, the two curves look almost identical for T between -40 and 20, but start to separate from one another for T > 20..

By definition, the relative humidity is the ratio of the actual vapor pressure to the saturated vapor pressure. That is, RH = ea / ea *. However, relative humidity is generally measured and used together with an equation for saturated vapor pressure to compute the vapor pressure as a function of temperature.

Optical air mass, Mopt is a dimensionless number that gives the relative path length (greater than 1) that radiation must travel through the atmosphere as the result of not entering at a right angle. The equation for optical air mass used here is from Kasten and Young (1989) and depends on latitude, declination and time of day. Instead of this equation, Dingman plots a family of curves in his Figure E-4 (p. 605) for *average daily* optical air mass. It would be interesting to integrate the equation given for Mopt over one day and compare the two by creating a contour plot.

Typical clear-sky values for γdust are between 0 and 0.2. See Dingman, p. 604-605.

The following variables are considered as input parameters (to be provided) that are used to compute many others: latitude (lat_deg), longitude (lon_deg or Λ), temperature (T), relative humidity (RH), slope angle (α), aspect angle (β), albedo, dust attenuation, cloudiness, canopy cover, solar constant (Isc}), and various attributes of Earth such as angular velocity, tilt angle, eccentricity of orbit, days per year and perihelion.

A table of typical surface albedos is given by Dingman, Table D-2 on page 584.

The Earth orbit eccentricy *correction*, E0, depends on the day angle, Γ, while the Earth orbit eccentricity is computed as: e = (b-a)/a, where a and b are the semi-major and semi-minor axes of the elliptical orbit.


An example run with input parameters, BLD files, as well as a figure / movie of the output

Follow the next steps to include images / movies of simulations:

See also: Help:Images or Help:Movies


Scott Peckham


Dingman, S.L (2002) Physical Hydrology, 2nd ed., Prentice Hall, New Jersey. (see Appendix E)

Brutsaert, W. (1975) On a derivable formula for long-wave radiation from clear skies, Water Resources Research, 11, 742-744.

Kasten and Young (1989) Revised optical air mass tables and approximation formula. Applied Optics, 28 (22): 4735~4738. (for the optical air mass equation)

Liston, G. *******

Marks and Dozier (1992) Climate and Energy exchange at the Snow Surface in the Alpine Region of the Sierra Nevada 1. Meteorological Measurements and Monitoring. Water Resources Research, 28(11), 3029~3042.

Whitman, A.M. (2003) A simple expression for the equation of time, online document, Also see:


Related Help Pages

Model Metadata