Minimum and Maximum Air Temperatures In VELMA

Overview

Four of VELMA's six existing weather models now support specification of daily (i.e. per-step) minimum and/or maximum air temperature ("airT") values.

Weather Model	Min/Max AirT Support?	Notes
DefaultWeatherModel	Yes	For Min/Max AirT support use weatherDriverDataFileName parameter and single weather driver data file.
SingleLocationWeatherModel	Yes	Not selectable in JVelma GUI. Use DefaultWeatherModel instead: it has identical behavior.
MapDrivenWeatherModel	No	Not selectable in JVelma GUI. For VELMA developer use only.
MultipleLocationWeatherModel	Yes	Cell-specific values are provided by the nearest weather station driver data.
MultipleWeightedLocationWeatherModel	Yes	Cell-specific values are weighted average of all weather station values.
SpatialWeatherModel	No	Implementation possible, but pending verification of how to compute cell-specific value from driver data.

Specifying min/max airT values is optional, but when they are provided, they may be accessed by the VELMA simulator engine and its sub-models. Currently, the only sub-model that uses min/max airT values is the SurfaceEvaporationModel.

Min and max airT values are reported in columns of a VELMA simulation results DailyResults.csv file and the files derived from it (Combined_DailyResults.csv and AnnualResults.csv). They are also reported in columns of the Cell_*.csv files for any CellDataWriter parameterizations configured for the simulation run.

How to Specify Min/Max AirT Values

Like all weather driver data, when minimum and or maximum air temperature driver data is provided for simulation configuration, it must be provided for every day (simulation step) within the range of years specified by the forcing_start and forcing_end configuration parameters.

Example:
Suppose forcing_start=1999 and forcing_end=2000, then 365 + 366 = 731 total values are required for each driver data category.

Unlike other weather driver data, when a minumum or maximum air temperature driver data value is missing, the simulation will not fail with an error. However, the simulation will run behaving as if there is no minimum and/or maximum (depending upon what is missing) air temperature driver data at all. In such cases, all minimum and/or maximum air temperature values are reports as NaN.

All the VELMA weather models that support min/max airT values expect weather station driver data to be provided in one or more .csv files. Each file should have one row of driver data per simulation step, and each row must provide the following values in the following order:

Year,Jday,Precipitation,Average_AirT,Minumum_AirT,Maximum_AirT

Where:

• Year is the year this driver data is for. This value must be a four-digit integer.

• Jday is the Julian day this driver data is for. This value must be an integer in the range [1, 366].

• Precipitation is the amount of precipitation (in mm) on Year, Jday. This value must be a non-negative floating-point or integer value.

• Average_AirT The average air temperature (in degrees C) on Year, Jday. This value must be a floating-point or integer value.

• Minimum_AirT The minimum air temperature (in degrees C) on Year, Jday. This value must be a floating-point or integer value.

• Maximum_AirT The maximum air temperature (in degrees C) on Year, Jday. This value must be a floating-point or integer value.

A weather station driver data .csv file must specify the Year, Jday, Precipitation, and Average_AirT values, but the Minimum_AirT and Maximum_AirT values are optional.

The following row formats are all valid and allowed:
(n.b. field names have been abbreviated to reduce the table width.)

Data Row Format	Description
Year,Jday,Precip,Ave_AirT,Min_AirT,Max_AirT	Specifies all possible driver data
Year,Jday,Precip,Ave_AirT,Min_AirT	Specifies minimum airT, but not maximum airT. Note: do not include a right-hand, trailing ',' (comma). Max airT always reported as NaN.
Year,Jday,Precip,Ave_AirT,,Max_AirT	Specifies minimum airT, but not maximum airT Note: the ',,' "empty" field for the missing minimum airT is required. Min airT always reported as NaN.
Year,Jday,Precip,Ave_AirT	Only specifies required driver data. Note: do not include a right-hand, trailing ',' (comma). Both min and max airT always reported as NaN.

Model-Specific Details

DefaultWeatherModel

Prior to supporting min/max airT values, the DefaultWeatherModel used two separate configuration parameters to specify two separate driver data files one for precipitation, and one for (average) air temperature. To support legacy use, those parameters still exist, but new simulation configurations should specify a single driver data file (in the format described above) to the weatherDriverDataFileName configuration parameter.
When the weatherDriverDataFileName is specified, the two legacy parameters are ignored, and data is loaded only from the single driver data file. However, when weatherDriverDataFileName is left unspecified (i.e. blank), the DefaultWeatherModel will try to load data via the two legacy parameters, and will expect those parameters to specify valid driver data files in the legacy format.

SingleLocationWeatherModel

The SingleLocationWeatherModel is not intended for direct specification by VELMA users.
It is used "underneath" the MultipleLocationWeatherModel. VELMA users configuring a simulation should use DefaultWeatherModel, which is the selectable, functional equivalent of SingleWeatherModel.

MultipleLocationWeatherModel

Each weather station driver data file specified in a row of the weatherLocationsDataFileName configuration parameter's .csv list of locations and weather stations can specify min and/or max airT values by following the format described above.

The "all or nothing" rule for one driver data file applies across all weather station driver date files. If any station is missing even one min or max airT value, every weather station behaves as if no min or max airT values exist.

MultipleWeightedLocationWeatherModel

Each weather station driver data file specified in a row of the weatherLocationsDataFileName configuration parameter's .csv list of locations and weather stations can specify min and/or max airT values by following the format described above.

The "all or nothing" rule for one driver data file applies across all weather station driver date files. If any station is missing even one min or max airT value, every weather station behaves as if no min or max airT values exist.

MultipleWeightedLocationWeatherModel computes cell-specific values as a weighted distance average of all specified weather station values: review min and max airT simulation value carefully.

Appendix A: Notes for VELMA Developers

Minimum and maximum air temperature support was added to VELMA code base by declaring new methods in the IWeatherModel interface:

[ . . . ]
public float getMinAirTemperature(int iCell, ISimulatorClock clock);
public float getMaxAirTemperature(int iCell, ISimulatorClock clock);
public boolean hasMinAirTemperatureData();
public boolean hasMaxAirTemperatureData();
[ . . . ]

The BaseWeatherModel class acts as a base-level implementor of IWeatherModel. It was updated with stub methods that behave as follows:

• BaseWeatherModel.getMinAirTemperature always returns Float.NaN.
• BaseWeatherModel.getMaxAirTemperature always returns Float.NaN.
• BaseWeatherModel.hasMinAirTemperatureData always returns false.
• BaseWeatherModel.hasMaxAirTemperatureData always returns false.

All six existing VELMA weather model extend BaseWeatherModel, so even if a specific weather model hasn't been updated to support min/max airT data (e.g. SpatialWeatherModel), the above four functions are available and return consistent, correct (for weather models without min/max airT support) values.

Specific weather models (e.g. DefaultWeatherModel) that have been updated to support min/max airT values override the BaseWeatherModel stub method implementations to provide actual min and/or max airT data, depending, of course, on what the driver data file(s) of a simulation configuration provide.

The GlobalState class further wraps a given simulation instance's weather model object's calls with methods that do not require passing in the simulator clock:

[ . . . ]
public float getMinAirTemperature(int iCell)
public float getMaxAirTemperature(int iCell)
public boolean hasMinAirTemperatureData()
public boolean hasMaxAirTemperatureData()
[ . . . ]

These methods call the corresponding underlying weather model method with the current simulation step, and are what other sub-model code (e.g. a SurfaceEvaporationModel object instance) are expected to call to determine whether min/max airT values are available (the have... methods) and what those values are (the get... methods).