Technical Manual

[ Return to Technical Manual Index ]

System Structure - Model

  1. Conceptual overview
  2. Implementation details


Conceptual Overview

RHESSys is a GIS-based, hydro-ecological modeling framework. RHESSys combines both a set of physically based process models and a methodology for partitioning and parameterizing the landscape. The process models simulate carbon, water and nutrient fluxes while the RHESSys architecture models the spatial distribution and spatial temporal interactions between the different processes.

Associated with the RHESSys simulation are a number of interface programs, which organize and input data into the format required by the simulation model. These include a standard GIS-based terrain partitioning program, r.watershed, and other basic GIS routines as part of the GRASS or ARC-INFO GIS database and two RHESSys specific programs :

GRASS2WORLD - derives landscape representation from GIS images

CREATE_FLOWPATHS - establishes connectivity between spatial units

These programs include methods for partitioning a landscape into hydrologically distinct units, establishing the connectivity between them and determining how input data should be assigned to the RHESSys framework.

Figure 1 presents an overview of inputs, outputs and flow of control in the RHSSys modelling system.

Landscape Representation

The RHESSys framework partitions the landscape into a hierarchical structure as shown in the following diagram. Each level of this spatial hierarchy fully covers the spatial extent of the world or landscape. Levels differ, however, in their partitioning of the landscape and each level is nested within the preceding level of the hierarchy.




Each level of the spatially hierarchy is associated with different processes modelled by the simulation system. Thus, each level of the hierarchy is defined as a particular object type with specific state variables (storages and fluxes appropriate for that level) and defaults. The entire landscape structure is described and parameterised in the worldfile, which is input into the RHESSys simulation.

For further details please see the RHESSys Manual.


Implementation Details

This section gives a description of how the logical view of the RHESSys system described above maps into actual C++ objects and structures. As can be seen from the following diagram, there are four main classes:

  1. The world class: this is a representation of the physical world at a specific time.
  2. The command_line class: this contains all the infromation passed to RHESSys on the command line at run time.
  3. The output_files class: this contains filenames and file pointers for all the model's output.
  4. The tec class: this class contains a pointer to the tec file and is responsible for advancing the world class forwards through time.



World class:

This class is created in main(). The instantiation of the world class creates the entire hierarchy, because the world constructor creates all the necessary basins, whose respective constructors then create all the hillslopes - and so on. Data is read into the objects as they are created because a file pointer to the world file is passed to each constructor. This file pointer advances sequentially from one object to another, and so the arrangement objects inside the world file is critical - its format must replicate the construction sequence. Each constructor, then, essentially does two things:

  1. Read data from the world file into the current object, then
  2. Construct all objects contained within the current object. For example, if the object being created is a basin, then construct all hillslopes contained within this basin.

In addition, some levels perform additional functions upon creation:


Command line class

There is only one instance of this class - a local variable of the main() function, created immediately upon entry. Its constructor parses the command line into a structure which can be used by the rest of the model. A pointer to the command line is passed to the constructor of each spatial object. This enables every spatial object to store a pointer to the command line, eliminating the overhead of passing this pointer to each daily_I, daily_F and hourly call. For more information, see the command_line class description and the command line options documentation.


Tec class

As with the command_line class, the tec class has only one instance which is a local variable of the main() function. It maintains a file pointer to the tec file which advances as the simulation runs. The whole simulation is invoked by a single call to tec::execute_tec from within the main() function. execute_tec() consists of an event loop which handles special events as they occur and fills in the intervening time by repeated calls to world_daily_I (at the beginning of each day), world_hourly (24 times in each day) and world_daily_F (at the end of each day). This can be seen in the following simplified call diagram:



Each special event in the tec file is loaded into a tec_entry object, which is handled by a call to its method tec_entry::handle_event().

tec::execute_tec() also calls the functions which write to the output files at the end of each timestep.


Output files class

RHESSys can output the state of each level at various temporal resolutions: hourly, daily, monthly and yearly.

The output_files class holds the hourly, daily, monthly, and yearly output file pointers for a specific level of the spatial hierarchy. The world_output_files class contains five output_files objects, one for each level. Thus there can be a maximum of 20 (4 * 5) output files for any simulation.

There is one instance of the world_output_files class, again a local variable of main(). A pointer to this object is passed, via tec::execute_tec(), to each output function.