Generating RHESSys input files

Default files

The default files describe characteristics of the variables associated with each object (level) of the spatial hierarchy. The default parameters are assigned values that stay constant through time and describe the performance of the parameters associated with an object. For example, the patch object would have default files associated with it that describe the characteristics of the soil type identified in that patch. Such parameter files are associated with each level of the spatial hierarchy. A library of commonly used parameter files assigned to specific soil, vegetation, and land use types have been developed, based on extensive literature research.

The basin and hillslope default file structures contain no parameters beyond the default file identifier. The default identifier maintains consistency of every object from basin through strata that has that basin/hillslope default identifier.

The zone default file contains atmospheric parameters associated with zone objects. The values provided in the standard zone default file are likely to be reasonably invariant for many environments, therefore, is a good first source in the absence of atmospheric research specific to a study site.

The soil and land use default files associated with the patch object address the routing and input of water at the patch level. Soil default files describe characteristics of particular soil types. Land use default files account for additional nitrogen and water inputs from developed areas.

The stratum default files describe characteristics of different vegetation types and associated processes such as carbon allocation, radiation interception, respiration, stomatal physiology, phenology, etc...

A set of default files has been provided with the tutorial exercise data, which you should have copied into your defs directory. Open a few of these default files to see the structure and content.

unix> more veg_conifer.def
unix> more sandyloam.def

Notice the first line for each default file assigns a default_ID. Every parameter type has a numerical identification, which corresponds to the ID's assigned in the GIS spatial layers, and is defined within the levels of the landscape representation. For details on the file structure and variable descriptions, see the Default files page.

Worldfiles

The worldfile defines the landscape representation within RHESSys. It is based on the hierarchical structure that describes each spatial level containing progressively finer units. The worldfile is generated with a GRASS interface program that references the input maps and a text document defining initial state variables (starting point for each variable). Within the worldfile, each spatial level is associated with the following items:

Identifier: each instance within a level is assigned an ID based on the map used to partition that level.

State Variables: values for stores and fluxes organized at each spatial level are initialized at the start of the simulation, typically changing as the simulation runs (ie. saturation deficit within the patch level)

A link to a climate station: link between the zone level and a particular climate station and the climate time series input information.

Because the worldfile for a complex landscape may contain hundreds of lines, a program called grass2world (g2w) is used to automatically generate the worldfile from spatial data layers within GRASS GIS. To create a worldfile with g2w, you need a text file (by convention, beginning with the prefix template) to be in your home working directory. The template is essentially a set of instructions that tells the GRASS interface program (g2w) how to create the initial values for each of the state variables in a spatial object at each level of the spatial hierarchy. Within the template file are initial values for variables such as carbon and nitrogen stores, or references to images (maps) that hold those values. grass2world expands the template file to assign values for every basin, hillslope, zone, patch, and stratum within the geographic extent of your modeled landscape. grass2world must be run from inside the GRASS GIS system. The program will look for the template file you designate on the command line in the calling directory, along with the associated maps in the GRASS database.

Template

There are 3 things that need to be initialized in the template:

1. Definition of the spatial layers
Spatial definition of the world objects (ie. basin, hillslope, zone, patch, and stratum) can be identified by looking at the lines beginning with an underscore (ie. _basin). Each level in the spatial hierarchy is defined using a raster map (which you created in GRASS in module I). A specific format must be used to define the various partitions as follows:
spatial_level map_name extent Spatial level indicates the level of the spatial heirarchy, and map_name identifies the GRASS raster map which defines the spatial partition. Extent specifies the number of vertical layers defined at that particular level of the spatial hierarchy. The extent parameter allows for non-spatial partitioning at a given level in the spatial hierarchy. The current version of RHESSys only allows non-spatial partitioning to occur at the stratum level (see special module for understory/overstory). Thus, for all levels other than canopy stratum, extent should be equal to 1.

2. Initialization of state variables
Generally, there are two ways to initialize state variables: assign a constant value, or use a map to assign values. This allows soil or vegetation to either be of one homogenous coverage or vary throughout the landscape, in which case you would reference a map containing multiple ID's. The default ID's used to identify soil and vegetation types in a map correspond to the ID's in the default files. The format for variables in the template is as follows:

Variable_name Function Constant_Value/Map

A. Assign a constant value Example: soil_default_ID value 3.0 (variable_name) (function) (constant_value)

Assigning a constant value of 3 (the default ID for sandyloam) to the variable soil_default_id within the _patch level would indicate a constant soil type (sandyloam) across the landscape.

B. Use a map to assign values Example: soil_default_ID mode variable_soils (variable_name) (function) (map)

The map variable_soils is a map of soils that vary across the landscape. The function mode takes the modal values from the map used. There are different ways to use maps (mode, averages, with an equation – see website for more information). Note that for map ID's with variables that should not be averaged, mode must be used.

3. Assigning default ID's and base-stations The beginning (header) of the template file lists the default and climate station files that will be used to describe the parameters associated with the world objects. Each level of the spatial hierarchy (basin, hillslope, zone, patch, and stratum) has default files associated with it. A climate base station that links to the climate data files must also be listed. The template format lists the number of default files that correspond to a given variable (i.e. number of soil or vegetation types), as well as the number of climate base stations, followed by the location and name of the default file or base station file.

Climate inputs are linked to particular zones by the climate station ID affiliated with that zone. A single climate station (or base station) will typically serve multiple zones within the landscape.

See the attached annotated template at the end of this module for further description of the template structure and content (under construction – I will distribute soon!). It denotes the most commonly edited lines within the template.

The following exercises will take you through editing the fields most commonly edited in the template file, and creating a worldfile.

Editing the Template

If you have not already done so, copy the template file to your working directory (contained in grassdata/templates), then open it for editing:

unix> vi template

If necessary, edit the header by directing the default and climate base station files to the correct path and file names. For this exercise, change the default file patch.def to sandyloam.def to change the soil type default file that RHESSys will look for.

Note the format of the line: ../defs/patch.def This is the format that will be listed at the top of the worldfile, after g2w uses the template information to create the expanded worldfile. UNIX format is used to direct RHESSys back one directory relative to where it is being run from (which will be the scripts directory), into the defs directory, and to read patch.def.

Edit each level of the spatial hierarchy (using the same process of vi commands described above) to correspond with the appropriate map you created in module I (don't worry about extent for now, for this exercise extent should be left at 1 for all layers). For example, if you are using the w8 mapset, you would edit as follows:

	_world w8basin 1
		_basin w8basin 1
			_hillslope h100.w8 1
				_zone h100.w8 1
					_patch w8dem.cl 1
						_stratum w8dem.cl 1

Within each of the basin, hillslope, zone, and patch levels, edit the z variable to correspond to the DEM map. Template format: z aver hjadem (average of the DEM at that level)

Within the zone and patch levels, edit the slope variable to correspond to the slope map. Template format: slope aver slope (uses the average Slope)

Within the zone level edit the aspect variable to correspond to the aspect map. Template format: aspect spavg aspect slope (takes the spherical average)

For this exercise, you will only use single values for soil and vegetation across the landscape (i.e. homogeneous soil type). Within the patch level, edit the soil_default_id from 1.0 (default ID used for a general soil type) to 3.0 (default ID assigned to sandyloam).

Be sure to save your changes before quitting.

You can save the template with any extension name you choose. This should be something to identify it, such as template.w8.

Creating the worldfile You are now ready to run Grass2World, which must be run from within GRASS. Start GRASS and make sure you have the correct LOCATION, MAPSET and DATABASE set.

Make sure you have the appropriate mask set for the watershed you are creating the worldfile for (i.e. w8 or the watershed you created)

grass> r.mask

At the GRASS prompt, type the command:

grass> g2w -w new_worldfile_name -t template_name

This will create a worldfile in your working directory (the directory you are currently in) with the output name you indicated on the gw2 command line. By convention, all worldfiles should begin with the prefix world to identify the file as a worldfile. You can use any name you want after the prefix world, however, it should be a name representative of its location, structure, etc... For this exercise I suggest calling it world.tutorial.

Move the worldfile into your worldfiles directory.

Flowtables

The flowtable is only necessary if routing is going to be incorporated into the model. The flowtable describes connectivity between patches within a hillslope. A GRASS interface program (cf9) generates the flowtable from the set of images that describe the landscape partitioning, which must correspond with the images used to generate the spatial object hierarchy in the worldfile. cf9 determines how each patch routes water and nutrients, and assigns an effective gradient and transmissivity for each patch, which is used to model subsurface throughflow and overland flow routing.

cf9 uses GRASS raster images to create the flowtable.

Start GRASS

To create the flowtable, at the GRASS prompt type the command:

grass> cf9 output=<output filename> template=<worldfile template name> stream=<> road=<> dem=<> slope=<>

where the brackets are filled with the name of the appropriate raster map. cf9 has several additional options, but these are the required ones. Note that cf9 will pull the name of the basin, hillslope, patch, and zone rasters from the template. A file name <output>_flow_table.dat will be written to your working directory. Rename this file to prevent overwriting it by subsequent calls to cf9. By convention, flowtables should start with the prefix flow followed by a name representing the study area, ie. flow.w8. For this exercise, I suggest calling it flow.tutorial.

Move the flowtable to your flowtables directory.

Open the flowtable to look at the structure. The very first line, which is one number, lists the number of patches in the landscape representation. The flow table format lists the patch, zone, and hillslope ID's, followed by X, Y, and Z centroid information, accumulated area, land type, a parameter that integrates the effect of slope boundary width and soil transmissivity, and the number of adjacent patches. Underneath each individual patch are the patch, zone, and hill ID's for the adjacent patches which that patch flow into and a number that indicates the proportion of flow that will be routed to that patch.

Tecfiles

RHESSys is structured as an event driven simulation, where most of the process modeling occurs between events. The TEC, or Temporal Event Control file, tells RHESSys when certain events occur. An event may be a redefinition of the strata (ie. removal of vegetation due to fire), or redefinition of the world (ie. in the event of development), or when to start generating output. For this basic exercise, the only temporal event will be a printing event. These events are used to specify printing at an hourly, daily, monthly, or yearly timestep. The tecfile does not specify the level of processing or spatial aggregation (ie. average basin conditions, or the condition of a single hillslope, patch, or stratum) for the output. These options are addressed when you run a simulation and will be explained in module 3. Rather, the tecfile tells RHESSys when something (ie. printing out results) should occur, and how often (ie. daily or monthly) it should occur.

RHESSys has more than 100 state variables that can be looked at. Different command line options in combination with different printing TEC events (tecfile) produce output files with specific variables aggregated to specific spatial/temporal scales. Be sure to consider what type of output you are interested in, as each combination of tecfile and command line options outputs different variables (a list of output file headings and their units is listed at Temporal Event Control files).

For example, if you are interested in average basin conditions, the outputs are different for daily basin, daily basin growth, monthly basin, and yearly basin output.

Tecfile formatting:

1. The TEC file is created in a text editor (such as VI)
2. Events must be listed in order of execution
3. Only one event per line is allowed, no blank lines are allowed
4. The format for events in the TEC file is as follows: Year Month Day Hour Printing_event

When executing several printing events that start on the same day, the events must be sequential. Two events cannot be scheduled to happen at the same time. Therfore, if you have two printing events scheduled on the same day, make the first printing event start on hour 1, the second on hour 2, etc...

Create a tecfile with the text editor VI unix> vi tec.tutorial (insert the following text (i) and save it to the new file (wq))

1979 10 1 2 print_daily_growth_on
1979 10 1 3 print_monthly_on
By convention, all tecfiles should begin with the prefix tec
followed by a name pertaining to your project or task.

A list of other TEC event options is available on the RHESSys website.