Requirements¶

The requirements for installing RHEAS include

• Python and a number of python packages

  • Numpy
  • NetCDF4
  • GDAL
  • Scipy

• GCC compiler

• Automake

• PostgreSQL server with the PostGIS extension

• VIC model executable

• DSSAT model executable

Thankfully most of these requirements are automatically installed using Buildout, a Python-based build system for creating, assembling and deploying applications from multiple parts.

In terms of hardware, the recommended requirements include any modern computer system with hard drive storage of at least 250 GB, and memory of at least 4 GB.

Installing on Linux and MacOS¶

In order to compile RHEAS, we need a C compiler and the Make utilities, as well as some other software packages. Depending on the Linux distribution these can be installed

sudo dnf groupinstall "Development Tools"
sudo dnf install scipy numpy gdal-devel python-dateutil libxslt-devel python-lxml libxslt-python readline-devel geos-devel proj-devel Cython pyproj python-pandas wine

for RPM-based distros (such as RedHat, Fedora, Centos)

sudo aptitude update && sudo aptitude -y upgrade
sudo aptitude -y install git build-essential python-numpy python-scipy python-gdal python-argparse python-dateutil libgdal-dev libproj-dev libxslt-dev libreadline-dev cython python-pandas
sudo dpkg --add-architecture i386
sudo aptitude update
sudo aptitude -y install wine winetricks

for DEB-based distros (such as Ubuntu, Debian, Mint)

If you’re on a MacOS, the easiest way to install the dependencies is by using the Homebrew package manager. Follow the instructions to install Homebrew and then run

brew update
brew install python readline gdal netcdf wine winetricks sfcgal
pip install numpy scipy gdal argparse py-dateutil lxml requests

We then clone and uncompress the software archive

git clone https://github.com/nasa/RHEAS.git
cd RHEAS

and then run the buildout script. Before that, we boostrap the build by running

python bootstrap.py

After that we can install everything by running

./bin/buildout

The buildout script will install the PostgresQL database along with the PostGIS extension, and create a database for the user. The script will also install some additional Python modules, and build the VIC hydrology model.

After the script finishes you should have a rheas executable in your bin directory!

Installing on Windows¶

It is currently possible to run RHEAS in a bash-shell environment such as Cygwin. However, due to backwards compatibility issues with PostGIS dependencies, this method is not currently recommended.

Testing the installation¶

A number of unit tests have been created to validate the installation of RHEAS. The tests create a temporary database and perform the following operations:

• Download and ingest the suite of datasets into the database
• Run nowcasts for VIC and DSSAT
• Run forecasts for VIC and DSSAT

The tests can be run with

./bin/test

Nowcast options¶

The available options for a nowcast simulation include:

• model: the model(s) to be used for this simulation. Valid options include vic and dssat; if both models are requested they need to be separated by a comma (required)
• startdate: the start date of the simulation in the “year-month-day” format (required)
• enddate: the start date of the simulation in the “year-month-day” format (required)
• name: name of the simulation (required)
• basin: path to a shapefile of the model domain. If not provided, the name option should correspond to a previously performed simulation
• resolution: spatial resolution of the simulation (required)

Forecast options¶

The available options for a forecast simulation include:

• model: the model(s) to be used for this simulation. Valid options include vic and dssat; if both models are requested they need to be separated by a comma (required)
• startdate: the start date of the simulation in the “year-month-day” format (required)
• enddate: the start date of the simulation in the “year-month-day” format (required)
• name: name of the simulation (required)
• basin: path to a shapefile of the model domain. If not provided, the name option should correspond to a previously performed simulation
• resolution: spatial resolution of the simulation (required)
• ensemble size: the size of the forecast ensemble (required)
• method: method to use to generate the meteorological forcings for VIC (required). The options that have been implemented include:
  • esp: use the Ensemble Streamflow Prediction approach that randomly resamples the climatology
  • iri: resample climatology based on the probabilities in the IRI meteorological forecasts

VIC options¶

The options for the VIC model include:

• precip: dataset to use for precipitation forcing (required)
• temperature: dataset to use for maximum and minimum temperature forcing (required)
• wind: dataset to use for wind speed forcing (required)
• lai: dataset to use for leaf area index forcing
• save state: directory where VIC model state file is saved in
• save to: option for saving output variables. Can be one of
  • db: save output to database
  • path to copy raw VIC output files to
• initialize: whether to initialize the model from a previously saved state file (can be given as on/off, true/false or yes/no)
• save: a comma-separated list of variables to be saved from VIC. The variable names can be:
  • net_long: net downward longwave flux [W/m2]
  • net_short: net downward shortwave flux [W/m2
  • snow_cover: fractional area of snow cover [fraction]
  • salbedo: snow pack albedo [fraction]
  • snow_depth: depth of snow pack [cm]
  • tdepth: depth of thawing fronts [cm] for each thawing front
  • fdepth: depth of freezing fronts [cm] for each freezing front
  • rootmoist: root zone soil moisture [mm]
  • smfrozfrac: fraction of soil moisture (by mass) that is ice, for each soil layer
  • smliqfrac: fraction of soil moisture (by mass) that is liquid, for each soil layer
  • snow_canopy: snow interception storage in canopy [mm]
  • soil_moist: soil total moisture content [mm] for each soil layer
  • soil_wet: vertical average of (soil moisture - wilting point)/(maximum soil moisture - wilting point) [mm/mm]
  • surfstor: storage of liquid water and ice (not snow) on surface (ponding) [mm]
  • swe: snow water equivalent in snow pack (including vegetation-intercepted snow) [mm]
  • wdew: total moisture interception storage in canopy [mm]
  • baseflow: baseflow out of the bottom layer [mm]
  • evap: total net evaporation [mm]
  • evap_bare: net evaporation from bare soil [mm]
  • evap_canop: net evaporation from canopy interception [mm]
  • prec: incoming precipitation [mm]
  • rainf: rainfall [mm]
  • refreeze: refreezing of water in the snow [mm]
  • runoff: surface runoff [mm]
  • snow_melt: snow melt [mm]
  • snowf: snowfall [mm]
  • transp_veg: net transpiration from vegetation [mm]
  • albedo: average surface albedo [fraction]
  • baresoilt: bare soil surface temperature [C]
  • snow_surf_temp: snow surface temperature [C]
  • soil_temp: soil temperature [C] for each soil layer
  • surf_temp: average surface temperature [C]
  • vegt: average vegetation canopy temperature [C]
  • advection: advected energy [W/m2]
  • grnd_flux: net heat flux into ground [W/m2]
  • latent: net upward latent heat flux [W/m2]
  • melt_energy: energy of fusion (melting) in snowpack [W/m2]
  • rfrz_energy: net energy used to refreeze liquid water in snowpack [W/m2]
  • sensible: net upward sensible heat flux [W/m2]
  • aero_cond: “scene” aerodynamic conductance [m/s]
  • air_temp: air temperature [C]
  • longwave: incoming longwave [W/m2]
  • shortwave: incoming shortwave [W/m2]
• observations: a comma-separated list of the observations to be assimilated into VIC. Any of the datasets with AS mode outlined in the database table can be used with their table name (without the schema, e.g. grace)
• update: the date or frequency when assimilation should be performed. Valid options for the assimilation frequency are: daily, weekly, and monthly. If this option is not set, assimilation is performed whenever the observation is available during the simulation period. When performing a forecast simulation, this option is not taken into account and assimilation is performed at the forecast initialization date

DSSAT options¶

The options for the DSSAT model include:

• shapefile: a shapefile contains the areas (e.g. administrative boundaries) for which DSSAT will be run (required)
• ensemble size: the size of the ensemble to be used (optional)
• assimilate: flag indicating whether to assimilate soil moisture (sm), LAI (lai) observations or both (optional)

Initializing and updating the database¶

The RHEAS database needs to be populated with a variety of datasets that can be fetched automatically. A configuration file can be used to control and define which datasets are downloaded and imported in the PostGIS database. The configuration file follows the INI format, with each section corresponding to a dataset.

Unless the entire spatial extent of the datasets needs to be ingested into the database, a domain section should be created in the configuration file describing the bounding box for the domain of interest.

• minlat: the minimum latitude of the bounding box
• maxlat: the maximum latitude of the bounding box
• minlon: the minimum longitude of the bounding box
• maxlon: the maximum longitude of the bounding box

If the dataset is being fetched for the first time, a starting date needs to be provided within each dataset section while an ending date can be optionally provided.

• startdate: start date of data fetched (format is year-month-day)
• enddate: the last date of data to be fetched

If the dataset already exists in the database, then RHEAS will only download data after the last date available in the database (unless this is bypassed by the startdate keyword).

An example configuration file (named data.conf) that will download TRMM, CHIRPS and IRI datasets is given below.

[domain]
minlat: -2
maxlat: -2
minlon: 30
maxlon: 34

[trmm]

[iri]
startdate: 2000-2-1
enddate: 2000-3-1

[chirps]
startdate: 2014-1-3

Since no option is provided under the trmm section, RHEAS will download data from the latest date available in the database to today.

After the configuration file has been created, the database can be initialized/updated by calling RHEAS as

./bin/rheas -u data.conf

where data.conf is the name of the configuration file.

Using a custom database¶

Assuming that you have created (using RHEAS or not) a PostGIS database (named customdb here as an example) that contains the necessary schemas and tables, it can be used to perform nowcast and forecast simulations by

./bin/rheas -d customdb nowcast.conf

where nowcast.conf is the RHEAS configuration file.

Writing custom scripts with the RHEAS API¶

RHEAS exposes most of its functions within each module, allowing for a relatively simple API to be used to further customize it.

In the first example, we will assume that we want to run a deterministic VIC simulation but use custom meteorological data (from Numpy arrays). We first initialize a VIC object

import vic
model = vic.VIC(".", "customdb", 0.25, 2015, 1, 1, 2015, 3, 31, "customname")

and then write the VIC global and soil parameter files

model.writeParamFile()
model.writeSoilFile("basin.shp")

where basin.shp is a shapefile that describes our basin. Assuming that we have Numpy arrays containing the data for precipitation (prec), air temperature (tmax and tmin) and wind speed (wind) we can then write out the forcings for VIC, run the model and save the output into the database

model.writeForcings(prec, tmax, tmin, wind)
model.run(vicexe)
model.save("db", ["runoff"])

In a second example of using the RHEAS API, we will assume that we have a customized version of the DSSAT model (as an executable) that needs an additional line written in its configuration file. In order to achieve that, we will decorate the corresponding DSSAT class method and replace one of its parameters. We begin by initializing the DSSAT object

model = dssat.DSSAT("customdb", "customname", 0.25, 2015, 1, 1, 2015, 3, 31, 40, vicoptions, "basin.shp", True)

and then decorate the function writeConfigFile to change its behavior

def addLineToConfig(func):
    def wrapper(*args, **kwargs):
        fname = func(args, kwargs)
        with open(fname, 'a') as fout:
             fout.write("Additional line with parameters")
     return wrapper

model.writeConfigFile = addLineToConfig(model.writeConfigFile)

Finally, we run the customized DSSAT model

model.run("dssat_new.exe")