tRIBS Distributed Hydrologic Modeling System

The TIN-based Real-Time Integrated Basin Simulator is a fully-distributed, continuous hydrologic model operating on a Triangulated Irregular Network (TIN). The code can be accessed through GitHub at tRIBS Distributed Hydrologic Modeling System. This document is intended to serve as a user manual for the tRIBS model, including instructions on how to obtain, compile, set up and run tRIBS using GitHub. In addition, an effort has been made to document the model software design using class and workflow diagrams. Additional information can be obtained through the tRIBS References.

The tRIBS model in this release under the MIT license includes:

Hydrologic Processes:

• Soil moisture infiltration fronts and their vertical redistribution.

• Coupled dynamics of the vadose and saturated zones with a dynamic water table.

• Topography-driven lateral fluxes in the vadose and saturated zones.

• Radiation and energy balance components on complex terrain.

• Single layer snowpack accumulation, ablation and melt on complex terrain.

• Rainfall and snow interception on vegetation canopies.

• Evaporation of intercepted rainfall, soil evaporation and plant transpiration.

• Hydrologic hillslope routing, hydraulic routing in channels, level-pool reservoir routing.

Computational Processes:

• Multi-resolution domain generated with channel network and watershed boundary.

• Computationally-efficient methods for infiltration, snow dynamics and flow routing.

• Serial operation for point-scale simulations and small watershed domains.

• Parallelized operation for large domains optimized through subbasin partitioning methods.

• Ingestion of time-varying meteorological forcing from stations or raster-based products.

• Ingestion of soil and vegetation parameters from tabular data or raster-based products.

• Pre- and post-processing workflows for time series and spatial analysis using Python.

---

Introduction

A number of distributed hydrologic models of varying degrees of complexity have been developed to simulate the land phase of the hydrologic cycle. Physically-based, distributed models solve parameterized equations for fluid flow in both space and time. Most models of this type, however, have large execution times, diminishing their capacity for model simulations. One of the major factors leading to the large execution times is the inefficiency in the representation of terrain inherent in a raster grid, the preferred mesh structure in most distributed hydrologic models. This document elaborates on the use and application of a distributed model that resolves these difficulties by representing the terrain through triangulated irregular networks (TINs).

The TIN-based Real-time Integrated Basin Simulator (tRIBS) is a collection of C++ classes designed for distributed hydrologic modeling at small to regional catchment scales. The object-oriented software design offers several advantages. In particular, by grouping data and functions operating on these variables into distinct classes, it becomes possible to separate the various hydrologic processes operating on the TIN mesh from the procedures for creating the mesh itself (Tucker et. al, 2001). The object-oriented approach also allows for code modularity that facilitates development through code reuse and integration of new process modules. Such a strategy permitted the development of the tRIBS model from the CHILD modeling framework (Tucker et. al, 1999). Hydrologic modules from the RIBS model (Garrote and Bras, 1995) and new hydrologic process models were incorporated into the CHILD framework as separate classes.

The tRIBS documentation is intended to serve as an introduction for new users. It covers topic areas related to the design, setup, execution and proper usage of the model, in addition to discussing limitations. tRIBS is provided here as an open source tool for the use in the resesarch and practitioner communities. It is the responsibility of the user to make sure that input file formats are correct and that parameter values are reasonable. This document provides sufficient information for the proper construction and execution of tRIBS.

References

The tRIBS model has a substantial record of peer-reviewed publications. The sections below provide the key references for the model code released under the tRIBS Github Page as well as the model application carried out in different watersheds and for varying purposes. The model release (v5.2) is documented in the Journal of Open Source Software (Raming et al., 2024).

Primary Model References

Ivanov, V.Y., Vivoni, E.R., Bras, R.L., and Entekhabi, D. 2004. Catchment Hydrologic Response with a Fully-distributed Triangulated Irregular Network Model. Water Resources Research. 40(11): W11102. https://doi.org/10.1029/2004WR003218

Vivoni, E.R., Entekhabi, D., Bras, R.L., and Ivanov, V.Y. 2007. Controls on Runoff Generation and Scale-dependence in a Distributed Hydrologic Model. Hydrology and Earth System Sciences. 11(5): 1683-1701. https://doi.org/10.5194/hess-11-1683-2007

Additional References for Github Release

Cazares-Rodriguez, J.E., Vivoni, E.R., and Mascaro, G. 2017. Comparison of Two Watershed Models for Addressing Stakeholder Flood Mitigation Strategies: Case Study of Hurricane Alex in Monterrey, México. Journal of Hydrologic Engineering. 22(9): 05017018, 1-16. https://doi.org/10.1061/(ASCE)HE.1943-5584.0001560

Ko, A., Mascaro, G., and Vivoni, E.R. 2019. Strategies to Improve and Evaluate Physics-Based Hyperresolution Hydrologic Simulations at Regional Basin Scales. Water Resources Research. 55(2): 1129-1152. https://doi.org/10.1029/2018WR023521

Raming, L.W., Vivoni, E.R., Mascaro, G., Cederstrom, C.J., Ko, A., Schreiner-McGraw, A.P., Cazares-Rodriguez, J.E., and Lizarraga-Celaya, C. 2024. tRIBS v5.2: A Multi-resolution, Parallel Platform for Tributary Hydrology in Forest Applications. Journal of Open Source Software. (Under Review).

Rinehart, A.J., Vivoni, E.R., and Brooks, P.D. 2008. Effects of Vegetation, Albedo and Solar Radiation Sheltering on the Distribution of Snow in the Valles Caldera, New Mexico. Ecohydrology. 1(3): 253-270. https://doi.org/10.1002/eco.26

Schreiner-McGraw, A.P., and Vivoni, E.R. 2018. On the Sensitivity of Hillslope Runoff and Channel Transmission Losses in Arid Piedmont Slopes. Water Resources Research. 54(7): 4498-4518. https://doi.org/10.1029/2018WR022842

Vivoni, E.R., Mascaro, G., Mniszewski, S., Fasel, P., Springer, E.P., Ivanov, V.Y., and Bras, R.L. 2011. Real-world Hydrologic Assessment of a Fully-Distributed Hydrological Model in a Parallel Computing Environment. Journal of Hydrology. 409: 483-496. https://doi.org/10.1016/j.jhydrol.2011.08.053

Selected Application References

Hawkins, G.A., Vivoni, E.R., Robles-Morua, A., Mascaro, G., Rivera, E., and Dominguez, F. 2015. A Climate Change Projection for Summer Hydrologic Conditions in a Semiarid Watershed of Central Arizona. Journal of Arid Environments. 118: 9-20. https://doi.org/10.1016/j.jaridenv.2015.02.022

Ivanov, V.Y., Vivoni, E.R., Bras, R.L., and Entekhabi, D. 2004. Preserving High-Resolution Surface and Rainfall Data in Operational-scale Basin Hydrology: A Fully-distributed Physically-based Approach. Journal of Hydrology. 298(1-4): 80-111. https://doi.org/10.1016/j.jhydrol.2004.03.041

Mahmood, T.H., and Vivoni, E.R. 2014. Forest Ecohydrological Response to Bimodal Precipitation during Contrasting Winter to Summer Transitions. Ecohydrology. 7(3): 998-1013. https://doi.org/10.1002/eco.1424

Mahmood, T.H., and Vivoni, E.R. 2011. A Climate-Induced Threshold in Hydrologic Response in a Semiarid Ponderosa Pine Hillslope. Water Resources Research. 47: W09529. https://doi.org/10.1029/2011WR010384

Mascaro, G., and Vivoni, E.R. 2012. Utility of Coarse and Downscaled Soil Moisture Products at L-band for Hydrologic Modeling at the Catchment Scale. Geophysical Research Letters. 39: L10403. https://doi.org/10.1029/2012GL051809

Mascaro, G., Vivoni, E.R., and Deidda, R. 2010. Implications of Ensemble Quantitative Precipitation Forecast Errors on Distributed Streamflow Forecasting. Journal of Hydrometeorology. 11(1): 69-86. https://doi.org/10.1175/2009JHM1144.1

Mascaro, G., Ko, A., and Vivoni, E.R. 2019. Closing the Loop of Satellite Soil Moisture Estimation via Scale Invariance of Hydrologic Simulations. Scientific Reports. 9: 16123. https://doi.org/10.1038/s41598-019-52650-3

Mendez-Barroso, L.A., Vivoni, E.R., Robles-Morua, A., Mascaro, G., Yepez, E.A., Rodriguez, J.C., Watts, C.J., Garatuza-Payan, J., and Saiz-Hernandez, J. 2014. A Modeling Approach Reveals Differences in Evapotranspiration and Its Partitioning in Two Semiarid Ecosystems in Northwest Mexico. Water Resources Research. 50(4): 3229-3252. https://doi.org/10.1002/2013WR014838

Moreno, H.A., Vivoni, E.R., and Gochis, D.J. 2013. Limits to Flood Forecasting in the Colorado Front Range for Two Summer Convection Periods using Radar Nowcasting and a Distributed Hydrologic Model. Journal of Hydrometeorology. 14(4): 1075-1097. https://doi.org/10.1175/JHM-D-12-0129.1

Vivoni, E.R., Rodriguez, J.C., and Watts, C.J. 2010. On the Spatiotemporal Variability of Soil Moisture and Evapotranspiration in a Mountainous Basin within the North American Monsoon Region. Water Resources Research. 46: W02509. https://doi.org/10.1029/2009WR008240

Xiang, T.T., Vivoni, E.R., and Gochis, D.J. 2014. Seasonal Evolution of Ecohydrological Controls on Land Surface Temperature over Complex Terrain. Water Resources Research. 50(5): 3852-3874. https://doi.org/10.1002/2013WR014787

Primary Contacts

The tRIBS User Google Group is the primary means for interactions about the model setup and applications. Model users can request membership in the Google Group.

All other exchanges on the tRIBS code and its supporting tools are managed through the tRIBS Github Page.

Model Design

The software design of the tRIBS Model is based on object-oriented C++ programming. The model classes support and use various object oriented methods including inheritance, polymorphism and virtual functions. In addition, the use of linked list and class templates is particularly important within the tRIBS code. As an object-oriented code, tRIBS constructs a set of objects that encapsulate variables and functions and declares their accessibility to other model objects. These objects are then used to carry out the various modeling functions in the hydrologic simulation. In order to best describe the software architecture of the model, it is important to first understand the file structure. Tables 1.1 and 1.2 list the directories and files that form part of tRIBS. For the new user, this is a starting point to begin to form a mental picture of how the model operates.

Model File Structure

The tRIBS Model is organized into a single directory (called tRIBS) with various sub directories that contain the model C++ classes. Each sub directory encapsulates classes with similar functionality or behavior. Table 1.1 shows the sub directories as a user would see upon downloading the source code. Various of these sub directories deal with the hydrologic processes (tHydro, tFlowNet, tRasTin), others create the mesh architecture (tMesh, tMeshElements, tMeshList), while others are general purpose classes used for model execution (tSimulator, tInOut, tCNode) or within other classes (tArray, tList, tPtrList). The Headers and Mathutil directories contain global header files and mathematical utilities for the model, respectively. Two subdirectories have been added for parallelization (tGraph, tParallel).

Table 1.1 tRIBS Model Subdirectories

Headers	tInOut	tMeshList
Mathutil	tList	tPtrList
utilities	tListInputData	tRasTin
tArray	tMesh	tSimulator
tCNode	tMeshElements	tStorm
tHydro	tFlowNet	tGraph
tParallel

In addition to the sub directories, the tRIBS directory contains a main function (main.cpp) and a makefile (CMake). Running the makefile will create a directory to store the object files for each class (*.o) and the platform-specific executable (called tribs). Each sub directory of the source code includes the C++ class files (*.cpp used as convention) and the C++ Header Files (*.h). Table 1.2 shows a list of the code files in the tRIBS model for further reference.

Table 1.2 tRIBS Model Class and Header Files

tRIBS	main.cpp, makefile
/Headers	Classes.h, Definitions.h, Inclusions.h, globalFns.h,
	globalFns.cpp, TemplDefinitions.h, globallO.h
/Mathutil	geometry.h , mathutil.h, mathutil.cpp,
	predicates.h, predicates.cpp
/utilities	InitialGW.cpp, RunTracker.cpp, RainInputCheck.cpp, mergOutput.pl
/tArray	tArray.h, tMatrix.h, tMatrix.cpp
/tCNode	tCNode.h, tCNode.cpp
/tFlowNet	tFlowNet.h, tFlowNet.cpp, tFlowResults.h, tFlowResults.cpp,
	tKinemat.h, tKinemat.cpp, tReservoir.cpp, tReservoir.h,
	tResData.cpp, tResData.h
/tGraph	tGraph.h, tGraph.cpp, tGraphNode.h, tGraphNode.cpp
/tHydro	tEvapoTrans.h, tEvapoTrans.cpp, tHydroMet.h, tHydroMet.cpp,
	tHydroMetConvert.h, tHydroMetConvert.cpp, tHydroMetStoch.h,
	tHydroMetStoch.cpp tHydroModel.h, tHydroModel.cpp,
	tIntercept.h, tIntercept.cpp, tWaterBalance.h, tWaterBalance.cpp,
	tSnowPack.h, tSnowPack.cpp
/tInOut	tInputFile.h, tInputFile.cpp, tOutput.h, tOutput.cpp,
	tOstream.h, tOstream.cpp
/tList	tList.h, tList.cpp
/tListInputData	tListInputData.h, tListInputData.cpp
/tMesh	tMesh.h, tMesh.cpp, tTriangulator.h, tTriangulator.cpp,
	heapsort.h
/tMeshElements	meshElements.h, meshElements.cpp
/tMeshList	tMeshList.h
/tParallel	tTimer.h, tTimer.cpp, tTimings.h, tTimings.cpp,
	tParallel.h, tParallel.cpp
/tPtrList	tPtrList.h, tPtrList.cpp
/tRasTin	tInvariant.h, tInvariant.cpp, tRainfall.h, tRainfall.cpp,
	tResample.h, tResample.cpp, tVariant.h, tVariant.cpp,
	tRainGauge.h, tRainGauge.cpp,
	tShelter.h, tShelter.cpp
/tSimulator	tRunTimer.h, tRunTimer.cpp, tRestart.h, tRestart.cpp,
	tSimul.h, tSimul.cpp, tControl.h, tControl.cpp,
	tPreProcess.h, tPreProcess.cpp,
/tStorm	tStorm.h, tStorm.cpp

The class names are indicative of the functionality for that particular class. Most files contain a single class that encapsulate the data and functions operating on the data within a single object. In some occasions, it has been convenient to include several interrelated classes within the same file. A list of all non-derived tRIBS Classes can be found in tRIBS/Headers/Classes.h. main.cpp is used in tRIBS to construct the various objects, while the simulation control is performed by tSimul.cpp.

Computational Mesh

The tRIBS Model inherited the Triangulated Irregular Network (TIN) mesh architecture from the CHILD model (Tucker et al., 1999) using various options in the tMesh class. In addition, new input capabilities take advantage of the TIN creation capabilities in external multiple reslution mesh generators to represent real world watersheds as “hydrologically” significant TINs. The most used options for creating the computational mesh are the following:

• Generate a set of points from an Arc/Info TIN ungenerate files (*.pnt, *.lin).

• Generate a new mesh from a given set of coordinates (x , y , z, b) with a boundary flag (*.points).

• Generate a new mesh using the outputs of tRIBS Meshbuilder for large domains (*.nodes, *.edges, *.tri, *.z).

• Read in existing tRIBS Mesh files from a previous run (*.nodes, *.edges, *.tri, *.z).

A TIN within these methods is a set of highly interconnected triangle objects with three edge and three node objects (as defined in MeshElements.cpp). The TIN mesh allows for flow from TIN node to TIN node, along a triangle edge, using a finite difference approach. Hydrologic computations made at each TIN node (e.g. infiltration, evaporation, groundwater table elevation) are assumed valid over a region consisting of the Voronoi polygon associated with the node. In this way the Voronoi polygon is used as the control volume for mass conservation. The Voronoi polygon is the dual diagram of the TIN mesh and can be computed by the intersection of perpendicular bisectors to each TIN edge.

Model Input Formats

The tRIBS model is designed to accept input from various types of data formats: grid data, TIN data, point data and text tables. The grid data can be time-invariant (soils and vegetation) or time-varying (rainfall and weather) grids. TIN data are inputted using a variety of methods depending on the application. The point data represent the values of time-varying forcings, such as meteorological data, that are available at specified points within the watershed. Resampling routines are available for geographically overlaying the grid or point data onto the Voronoi polygon mesh. Finally, text tables are used in the model for inputting parameter values associated with soil and vegetation maps or time series of hydrometeorological data.

Grid Input

A standard ASCII grid format is used for all raster input, which may include soil and vegetation index maps, initial groundwater table depth, depth to bedrock, and hydrometeorological grids. The ASCII grid format consists of a small, 6-line header that describes the matrix data presented in the text file, as shown in Table 2.1. This format is a convenient method for data exchange and is often used in Geographical Information Systems (GIS). Any extension name for the grid data can be used within tRIBS as long the filename is specified. Although each grid input is treated differently within the model, the grid input format should be identical. The grid pathname and file name are specified within the Input File. The model assumes that a coordinate systems with a spacing in meters along x, y, and z are used, such as the UTM coordinate system.

Table 2.1. Example of a standard ASCII grid file.

ncols	6
nrows	6
xllcorner	346035
yllcorner	3979905
cellsize	2000
NODATA_value	-9999
-9999	-9999	-9999	0.511	0.111	-9999
-9999	-9999	0.951	1.873	0.239	-9999
-9999	-9999	0.824	0.412	0.444	1.051
-9999	3.123	0.154	0.853	-9999	-9999
1.090	2.541	0.288	-9999	-9999	-9999
2.241	0.312	-9999	-9999	-9999	-9999

Table 2.1 has various features to note:

1. the grid input must be composed of square grid cells (i.e. dx = dy = cellsize (in meters)),

2. the coordinate system is specified by the values of x and y at the lower left corner (in this case, UTM zone 15 coordinates are shown),

3. the entire grid can be rectangular, such that nrows and ncols can differ, and

4. the NODATA_value can be used to represent cells outside of the domain of interest.

TIN Input

Topographic data is inputted into the tRIBS Model through a variety of methods that are implemented in the tMesh class. For applications in real watersheds with complex topography and stream networks, the method of choice is to generate the TIN mesh and export it into a format that tRIBS can read in as a Points File (*.points), an example of which is shown in Table 2.2. A Points File is a simple text file that contains a listing of point coordinates (x, y, z) and the boundary code (b) for each point (in that specific order) with a small header that indicates the total number of points in the file. The boundary code is indicative of the node position within the watershed: 0 (mesh interior node), 1 (closed mesh boundary node), 2 (open mesh boundary or outlet node), 3 (stream network node). Proper creation and consistency of the Points File is very important for the tRIBS Model and the *.points file should be carefully inspected.

Table 2.2. Example of a tRIBS Points File (*.points)

7
405	0	0	1
495	0	0	2
585	0	0	1
360	90	1	1
450	90	1	0
540	90	1	0
630	90	1	1

The Points File is the recommended TIN input for the tRIBS Model during the initial model construction, usually necessary when a new basin is modeled for the first time. After a successful tRIBS model run, the model outputs a set of files that describe the TIN mesh properties in greater detail, including the connectivity between nodes and the triangles within the mesh. The set of files includes: *.nodes, *.edges, *.tri and *.z. These files can be read directly into the model during subsequent model runs, thus avoiding the use of the *.points file and speeding up the process of mesh construction.

Point Station Input

Hydrometeorological data can be inputted into the tRIBS model through methods for Point Station Input implemented in the tEvapoTrans and tRainfall classes and the tHydroMet and tRainGauge storage classes. Point Station Input is useful for providing meteorological data from weather stations or rain gauges. The data from these sparse stations or points is resampled by using a Thiessen polygon method at the point coordinates. The station properties, including coordinates, are specified through an SDF file (Station Descriptor File), while the station data are provided in an MDF file (Meteorological Data File).

Text File Inputs

Various types of text files are used in the tRIBS Model to specify model options, hydrologic parameters or control commands. The most important of the text files is the Model Input File (*.in). This file contains various required and optional parameters organized by keywords. The format for each parameter consists of a line of descriptive text followed by the value of the parameter itself on a second line. There are over 100 different keyword inputs in a typical Model Input File. These can be classified into various groupings: Model Run Parameters, Model Run Options and Model Input Files and Pathnames. Subgroupings include: Time Variables, Routing Variables, Mesh Generation, Resampling Grids, Meteorological Data and Output Data. More details concerning the Model Input File will be presented in the section on Model Input File in this document. An example .in file is provided on the Templates page.

Another important use of text files is for the reclassification of soil and land use grids into meaningful hydrologic parameters assigned to each Voronoi polygon. A simple text file is used to relate each cover class to the particular hydrologic parameter required for the model equations. It consists of a small header followed by a matrix of parameter values for each cover class. In the case of the soil reclassification table (*.sdt), the parameters are used to specify the soil hydraulic and thermal properties. In the case of the land reclassification table (*.ldt), the parameters are used to relate the cover type to the interception and evapotranspiration properties of the vegetation and land cover. Both types of files will be explain in greater detail in the section on Soil and Land Use Input.

A shell script can also be used to run the model and specify the command line options desired during the run by using a Model Run File (*_run). This file consists of a single line that specifies the pathname of the tRIBS executable followed by the name of the Model Input File and the desired command line options. For examples see the Templates page.

Parallel Model Inputs

The parallel mode can be toggled on/off using the keyword PARALLELMODE in the tRIBS Input file (*.in). In this section, we will only provide details on the input of the graph partitioning files (*.graph). The graph files are utilized to specify how a large watershed domain is partitioned into subbasins and on which computer processor each subbasin is run on. There are currently three methods implemented to partition a domain:

1. A default partitioning of the graph;

2. A reach-based partitioning; and

3. An inlet/outlet-based partitioning.

The various options can be selected utilizing the keyword GRAPHOPTION. The default graph partitioning is based on an automatic splitting of the internal node list. It is a simple method that does not permit user control or interaction. As a result, it may not be an optimal way for subdividing a domain into a well-balanced computational effort among different processors. The reach-based and inlet/outlet-based methods require user input of a file into tRIBS by specifying the filename using the keyword GRAPHFILE. The file structure varies for each type of domain decomposition. The following tables indicate the file structure for the reach-based and inlet/outlet-based approaches.

Table 2.3 Reach-based Graph Input File (*.graph or *.reach)

Processor ID (#)	Reach ID (#)
Processor ID (#)	Reach ID (#)
Processor ID (#)	Reach ID (#)
Processor ID (#)	Reach ID (#)
…	…

The reach-based graph input (Table 2.3) is essentially a two-column text file with no header. Column 1 holds the numerical IDs of the computer processors to be used (labeled from 0 to N) while Column 2 holds the numerical IDs (labeled from 0 to M) of the reaches to be run on the corresponding computer processors. The reach IDs need to be determined from the *__reach file generated by the tRIBS model after mesh construction (note this is not the same thing as the *.reach file generated by MeshBuilder). The user will need to determine the most appropriate method for distributing the various reaches onto the available processors. Proper load balancing needs to be considered to distribute effort among different sub-basins. Because, manual construction of the graph input file may become cumbersome for large domains, we provide the auxiliary program MeshBuilder as discussed below.

The inlet/outlet-based graph input (Table 2.4) is essentially a three-column text file with no header. Column 1 holds the numerical IDs of the computer processors to be used (labeled from 0 to N), Column 2 holds the numerical IDs of the channel nodes that form the inlet (upstream) segment of a reach and Column 3 holds the numerical IDs of the channel nodes that form the outlet (downstream) segment of a reach. Inlet nodes are typically inside sub-basins along the headwater areas, while outlet nodes are typically the closest downstream location along the main channel. The inlet/outlet-based graph partitioning provides for flexibility to the user, but may be more complicated to set up. The inlet/outlet IDs need to be determined from the *.voi file generated by the tRIBS model after mesh construction. As with the above case, the user will need to experiment with the inlet/outlet partitioning in order to obtain proper load balancing and performance.

Table 2.4 Inlet/Outlet-based Graph Input File (*.graph)

Processor ID (#)	Inlet ID (#)	Outlet ID (#)
Processor ID (#)	Inlet ID (#)	Outlet ID (#)
Processor ID (#)	Inlet ID (#)	Outlet ID (#)
Processor ID (#)	Inlet ID (#)	Outlet ID (#)
…	…	…

MeshBuilder

MeshBuilder is a utility program that can automatically generate *.reach graphfiles for parallel tRIBS simulations. We provide both the source code as well a docker image for MeshBuilder. Instructions for running MeshBuilder are provided in both locations.

Reservoir Model Input

The input of reservoir data into tRIBS enables the level pool routing simulation within the hydraulic channel routing scheme. To enable this routing option, there are two main files the user is required to provide. The Reservoir Polygon ID File provides information concerning the selected nodes to be used as Reservoirs. Table 2.5 presents the format required in the Polygon ID file (*.res). The number of reservoirs (nReservoirs) specifies the number of TIN nodes (Voronoi polygons) that will be used as dam locations in the simulation. nNodeParams are the number of parameters required for each node, which should always be set at 3. In the body of the file, the user should include the ID number of the TIN node in the first column (NodeID, int, node selected by the user as a reservoir), followed by the type of reservoir the node will be (ResNodeType, int, type of reservoir associated with the node, linked to the RESDATA information) and the initial water surface elevation (Initial_H, double, meters) at the reservoir in the third column (empty reservoir should be specified as 0.0 m). When assigning the node to be used as a reservoir, the user should assign nodes that correspond to the start or the end of a river reach, to do so it is recommended to use the Voronoi mesh and stream network to identify potential nodes. An example of a *.res file is presented in Table 2.6.

Table 2.5 Format for the Reservoir Polygon ID File (*.res).

#Reservoirs	nNodeParams
NodeID	ResNodeType	Initial_H

Table 2.6 Example of a Reservoir Polygon ID File (*.res).

4	3
578867	0	0.0
575490	1	0.0
573514	2	0.0
574354	3	0.0

The second file that the user should provide is the RESDATA information (*.eds) related to the elevation-discharge-storage data of each reservoir type. Table 2.7 presents the format required for the elevation-discharge-storage data file (*.eds). The header will include the number of types (nTypes) of reservoirs and the number of reservoir parameters (nResParams) required which should always be set to 4. The identifier for the type of reservoir should start with the number zero and be repeated for each row that describes an individual reservoir type. For a second reservoir type, the identifier would have a number of one. The second column will have the elevation (in meters) with the corresponding discharge (m3/s, double) and storage (1000 m3, double) for that elevation in the third and fourth column. An example of the reservoir data file (RESDATA) is presented in Table 2.8, notice the change from 0 to 1 in the first column indicating the change from one reservoir type to another.

Table 2.7 Format for the Reservoir Data File (*.eds).

nTypes	nResParams
Type#	Elevation (m)	Discharge (m3/s) | Storage (1000m3)

Table 2.8 Example of a Reservoir Data File (*.eds).

2	4
0	0	0	0
0	0.5	50	10
0	1	350	50
0	1.5	1200	300
0	2	1500	12000
1	0	0	0
1	0.5	10	100
1	1	20	400
1	1.5	30	800
1	2	40	1600

Model Parameters and Forcings

A tRIBS model application consists of a series of Voronoi polygons that discretely represent a watershed. At each TIN node associated with a Voronoi polygon, a set of governing equations describing the hydrologic and energy processes are computed. To solve these equations for each location, spatially distributed data describing surface topography, soils, vegetation and hydrometeorology are required, which can be obtained from field measurements, remote sensing data interpretation or model output such as numerical weather models.

Model Parameters

In the case of soil and vegetation cover, different data sources can be used to assign uniform or spatially-explicit parameter values for the governing equations. The soils parameters listed in Table 3.1 are necessary for carrying out the vertical infiltration and lateral flow redistribution, as well computing the soil heat budget within the sloped, heterogeneous, anisotropic soil columns assumed at each Voronoi polygon. Note that the parameter requirements vary with the specified hydrologic processes selected during a model run. For example, the surface heat parameters are only required if the radiation balance is computed. The order in which the soil parameters are listed in the tabular input should correspond to the list below and the units should match. Actual parameter names are not important for tabular input, whereas raster-based inputs assume slightly different naming conventions. Similar units need to be used when specifying soil parameters as raster inputs.

Table 3.1 tRIBS Soil Parameter Description

Parameter	Description	Unit
Ks	Saturated Hydraulic Conductivity	[mm/hr]
thetaS	Saturated Soil Moisture	[-]
thetaR	Residual Soil Moisture	[-]
m	Pore Distribution Index	[-]
PsiB	Air Entry Bubbling Pressure	[mm] (negative)
f	Hydraulic Decay Parameter	[1/mm]
As	Saturated Anisotropy Ratio	[-]
Au	Unsaturated Anisotropy Ratio	[-]
n	Porosity	[-]
ks	Volumetric Heat Conductivity	[J/msK]
Cs	Soil Heat Capacity	[J/m3K]

The vegetation or land-use parameters in Table 3.2 are necessary for carrying out the rainfall interception, bare soil evaporation and evapotranspiration within each Voronoi polygon, as well as determining the radiation and energy balance within the land surface. Note that the parameter requirements vary with the specified processes selected during a model run. For example, rainfall interception can be computed using a simple canopy storage method or the more complex Rutter model. The order in which the vegetation parameters are listed in the tabular input should correspond to the list below and the units should match. Actual parameter names are not important for tabular input, whereas raster-based inputs assume slightly different naming conventions. Similar units need to be used when specifying vegetation parameters as raster inputs.

Table 3.2 tRIBS Vegetation or Land Use Description

Parameter	Description	Unit
a	Canopy Storage - Storage Method	[mm]
b1	Interception Coefficient - Storage Method	[-]
P	Free Throughfall Coefficient - Rutter Method	[-]
S	Canopy Field Capacity - Rutter Method	[mm]
K	Drainage Coefficient - Rutter Method	[mm/hr]
b2	Drainage Exponent - Rutter Method	[1/mm]
Al	Albedo	[-]
h	Vegetation Height	[m]
Kt	Optical Transmission Coefficient	[-]
Rs	Stomata Resistance	[s/m]
V	Vegetation Fraction	[-]
LAI	Leaf Area Index	[-]
thetas	Stress Threshold for Evaporation [0 to 1]	[-]
thetat	Stress Threshold for Transpiration [0 to 1]	[-]

Input Formats

One form of data input for soil textural and vegetation data is through the use of ASCII grids consisting of soil or land use codes or indices. The soil (*.soi) and land use (*.lan) grids are specified in the Input File by using the keywords SOILMAPNAME and LANDMAPNAME. Table 3.3 presents an example of a soil or land use grid. As with other grid input, care should be taken to specify the grids in the same coordinate system as the topographic TIN data.

Table 3.3 Example of Soil or Land Use Class ASCII grid (*.soi and *.lan)

nrows	6
ncols	6
xllcorner	346035
yllcorner	3979905
cellsize	2000
NODATA_value	-9999
-9999	-9999	-9999	1	0	-9999
-9999	-9999	1	0	0	-9999
-9999	-9999	1	0	1	1
-9999	0	1	1	-9999	-9999
0	0	-9999	-9999	-9999	-9999

The parameter values for the soil and land use grids are read from a reclassification table inputted separately using the keywords SOILTABLENAME and LANDTABLENAME. The format of these soil reclassification (*.sdt) and land use reclassification (*.ldt) tables include a small header which specifies the number of cover types (#Types) and the number of variables for each type (#Params), as shown in Table 3.4 and Table 3.5. The header is followed by a matrix of parameter values where each row represents one cover type and each column represents one parameter. The order and units of these parameters are fixed. Since parameter values outside the appropriate range may results in inaccurate calculations, the user should be careful to select realistic values from literature sources prior to model use.

Table 3.4 Soil Reclassification Table Structure (*.sdt)

#Types	nParams
ID	Ks	thetaS	thetaR	m	PsiB	f	As	Au	n	ks	Cs

Table 3.5 Land Use Reclassification Table Structure (*.ldt)

#Types

nParams

ID

a

bI

P

S

K

b2

Al

h

Kt

Rs

V

LAI

Note that the soil parameters relate to the hydraulic and thermal properties in the upper portions of the soil profile. Most of these can be directly related to the surface soil texture. The first nine parameters are essential for running the Unsaturated Zone Model while the last two are required if the keyword GFLUXOPTION = 1. Note that these land use parameters relate to the interception and evaporation properties of the vegetative cover or land use type. The first two parameters are required if the keyword OPTINTERCEPT = 1, while the next four are required if OPTINTERCEPT = 2. The final five parameters are required for various options of the keyword OPTEVAPOTRANS. The last two parameters have been added to specify the soil moisture stress threshold for soil evaporation and plant transpiration in units of relative soil moisture (varying from 0 to 1).

Gridded soil data can be used as an alternative to the tabular soil parameter input. To activate the use of the gridded soil data the user must the keyword OPTSOILTYPE = 1 in the Input File (*.in). If OPTSOILTYPE = 0 then the use of the tabular data will be selected. The information is provided through the use of a text file for reading soil grid input (*.gdf) specified through the keyword SCGRID. The structure of the soil grid data file or GDF is shown in Table 3.6.

Table 3.6 Soil Parameter GDF File Structure

#Params
Latitude	Longitude	GMT
KS	Grid File Pathname	Grid Extension
TS	Grid File Pathname	Grid Extension
TR	Grid File Pathname	Grid Extension
PI	Grid File Pathname	Grid Extension
PB	Grid File Pathname	Grid Extension
FD	Grid File Pathname	Grid Extension
AR	Grid File Pathname	Grid Extension
UA	Grid File Pathname	Grid Extension
PO	Grid File Pathname	Grid Extension
VH	Grid File Pathname	Grid Extension
SH	Grid File Pathname	Grid Extension

An alternative input format type for dynamic land cover data is with the use of grid data. This option in the tRIBS model is used with the keyword OPTLANDUSE = 1, while the more static land cover is specified with OPTLANDUSE = 0. The use of dynamic land cover variables maybe convenient for inputting remotely sensed vegetation fields. Information is provided through a text file for reading in land cover grid input (*.gdf) as specified through the keyword LUGRID in the Input File. The structure of the Grid Data File or GDF is presented in Table 3.7.

Table 3.7 Land Cover GDF File Structure

#Params
Latitude	Longitude	GMT
AL	Grid File Pathname	Grid Extension
TF	Grid File Pathname	Grid Extension
VH	Grid File Pathname	Grid Extension
SR	Grid File Pathname	Grid Extension
VF	Grid File Pathname	Grid Extension
CS	Grid File Pathname	Grid Extension
IC	Grid File Pathname	Grid Extension
CC	Grid File Pathname	Grid Extension
DC	Grid File Pathname	Grid Extension
DE	Grid File Pathname	Grid Extension
OT	Grid File Pathname	Grid Extension
LA	Grid File Pathname	Grid Extension

In the above *.gdf files, note that the first line specifies the total number of parameters to be inputted, while the second line is used to input a representative absolute latitude, longitude and GMT values for all the input grids. The next #Params lines are used to specify the parameter code, the file pathname of the land cover parameter grid (including the basename of the file) and the extension given to the particular grid. The NO_DATA flag is used to specify the grids that are not available for a particular parameter.

Model Forcings

In the case of hydrometeorological forcings, model inputs can be achieved in a number of different ways: (1) point input of hydrometeorological observations; (2) grid input of meteorological observations or numerical model results, or (3) point input of stochastic climate simulations. The model can handle the meteorological forcing in the point or grid format and has internal routines to assign this information to Voronoi polygons or TIN nodes via Thiessen resampling or nearest neighbor approaches.

Table 3.8 lists the hydrometeorological model forcings. The primary hydrometeorological parameter is rainfall at a specified temporal resolution, typically hourly. Sub-hourly forcing can be specified despite having no minute column, by simply providing the data in order using the same hour in the hour column. The requirement of the other meteorological parameters depends on the processes selected for the model run. Some of the parameter information is redundant, for example dew point temperature and relative humidity are interchangeable. When incoming solar radiation is used, sky cover is not neeed. Other information can be input directly or computed within the model, for example net radiation, using the other meteorological measurements. The naming convention for each variable is used when specifying raster-based inputs. Units should be preserved.

Table 3.8 tRIBS Hydrometeorological Parameter Description

Parameter	Description	Unit
PA	Atmospheric Pressure	[mb]
TD	Dew Point Temperature	[C]
RH	Relative Humidity	[%]
VP	Vapor Pressure	[mb]
XC	Sky Cover	[tenths] (0 to 10)
US	Wind Speed	[m/s]
TA	Air Temperature	[C]
TS	Surface Temperature	[C]
NR	Net Radiation	[W/m2]
R	Rainfall	[mm/hr]
IS	Incoming Solar Radiation	[W/m2]

Input Formats

Meteorological input into tRIBS can from point data or grid data, depending on the data sources available. The two data inputs are treated differently in the model. Table 3.9 shows the two forms of meteorological data input and storage.

Table 3.9 Meteorological Data Input Methods

Characteristic	Point Data	Grid Data
Input	Station Descriptor File (*.sdf)	ASCII grids (*.txt, *.lan, *.soi)
	Meteorological Data File (*.mdf)
Storage	Assignment to storage objects	Direct assignment to tCNode
Manipulation	Thiessen point resampling	Grid resampling
Examples	tHydroMet, tRainGauge	tRainfall, tVariant, tInvariant

The format of the Station Descriptor Files (*.sdf) and the Meteorological Data Files (*.mdf) is modified slightly depending on whether these contain meteorological or rain gauge data.

Table 3.10. Weather Station SDF Structure

#Stations	#Params
StationID	FilePath	AbsLat	RefLat	AbsLong	RefLong	GMT	RecordLength	#WeatherParams	Other

Table 3.11. Rain Gauge SDF Structure

#Stations	#Params
StationID	FilePath	RefLat	RefLong	RecordLength	#RainParams	Elevation

Note the following: #Stations is the number of total stations to be read, #Params is the number of parameters for each of the subsequent lines, StationID must be unique values for each station (starting at 0), the FilePath refers to the MDF file for that particular station and must be relative to the location of the executable, the AbsLong and AbsLat must be in decimal degree (lat/long), the RefLong and RefLat must be in the same coordinate system as the input grids and watershed TIN, Greenwich Mean Time (GMT) is difference in hours between the location and the Greenwich Meridian (negative number in Western Hemisphere), the RecordLength is the length of the time series in the MDF file, the #WeatherParams and #RainParams are the number of parameters in the MDF file including the date and time, and Other is used for inputting additional station information, such as station elevation, if desired. These keywords are not included in the file, just the parameter value.

Table 3.12 Weather Station MDF Structure

Y	M	D	H	PA	TD/RH/VP	XC	US	TA	TS	NR
…	…	…	…	…	…	…	…	…	…	…

Table 3.13 Rain Gauge MDF Structure

Y	M	D	H	R
…	…	…	…	…

Note the following: the parameter names must be a placed in a header for each MDF file, the TD/RH/VP imply that either one of these parameters can be inputted into that particular field, there must be RecordLength number of lines following after the header in intervals, missing data must be inputted with the NO_DATA flag = 9999.99, and the units must be retained as indicated, including for IS, NR and TS. Rainfall (R) is typically specified in its own MDF file. Notice that the file does not contain a minute column. Nevertheless, sub-hourly data can be inputted into the model at intervals that are multiples of the TIMESTEP. For example, for 15-minute data, the user should specify four rows for each hour (same H) in order. A similar approach is taken for sub-hourly rain gauge data.

An alternative input format type for meteorological data is with the use of grid data. This option in the tRIBS model is used with the keyword METDATAOPTION = 2, while the more traditional weather station data is specified with METDATAOPTION = 1. The additional information is provided through a text file for reading in meteorological input (*.gdf) as specified through the keyword HYDROMETGRID in the Input File. The structure of the Grid Data File or GDF is presented in Table 3.14.

Table 3.14 Meteorological GDF File Structure

#Params
Latitude	Longitude	GMT
PA	Grid File Pathname	Grid Extension
TD	Grid File Pathname	Grid Extension
XC	Grid File Pathname	Grid Extension
US	Grid File Pathname	Grid Extension
TA	Grid File Pathname	Grid Extension
IS	NO_DATA	NO_DATA
TS	NO_DATA	NO_DATA
NR	NO_DATA	NO_DATA
RH	NO_DATA	NO_DATA

Note that the first line specifies the total number of parameters to be inputted, while the second line is used to input a representative absolute latitude, longitude and GMT values for all the input grids. The next #Params lines are used to specify the parameter code, the file pathname of the weather grid (including the basename of the file) and the extension given to the particular grid. The NO_DATA flag is used to specify that weather grids are not available for a particular parameter. All the keywords used to represent the parameters are fixed as well as the units.

Model Input File

As with any model, half the battle in getting a correct model run is in providing the appropriate model input. Without having all the correct model input, the tRIBS Model will exit with an appropriate error message.

Input File Contents

The tRIBS Model Input File (*.in) is currently the primary user interface to the model. Although not a graphical medium, it is an easy and efficient means of manipulating all modeling options, parameters and inputs. Those parameters that are not required for a particular run are ignored by the model. The *.in file is organized by keywords. The format for each parameter consists of a line of descriptive text followed by the value of the parameter itself on a second line. Table 4.1 presents a list of the keywords. Note that all keywords are capitalized. The values associated with each parameter may be a number or a string. If the units are specified as ints or doubles, this implies that the parameters are dimensionless, otherwise a unit is expressed. The difference between a pathname and a base pathname is simply that the pathname includes the entire path plus the entire name of the file, including the extension, while a base pathname is only the path and the base name of the file (no extension). See Templates for an example input file. NOTE: Even if they are note being used, all keywords in the input file must be present for proper model execution.

Table 4.1 List of Model Parameters in tRIBS Model Input File

Keyword	Units	Description
STARTDATE	date format	Date of start of simulation
RUNTIME	hours	Total number of hours in run
TIMESTEP	mins	Unsaturated zone time step
GWSTEP	mins	Saturated zone time step
METSTEP	mins	Meteorological data input time step
ETISTEP	hours	ET, interception and snow time step
RAININTRVL	hours	Rainfall data input time step
INTSTORMMAX	hours	Interstorm interval
RAINSEARCH	hours	Rainfall search interval
BASEFLOW	m3/s	Minimum baseflow discharge
VELOCITYCOEF	double	Discharge-velocity coefficient
KINEMVELCOEF	double	Kinematic routing velocity coefficient
VELOCITYRATIO	double	Stream-hillslope velocity coefficient
FLOWEXP	double	Nonlinear discharge coefficient
CHANNELROUGHNESS	double	Uniform channel roughness value
CHANNELWIDTH	double	Uniform channel width
CHANNELWIDTHCOEFF	double	Coefficient in width-area relation
CHANNELWIDTHEXPNT	double	Exponent in width-area relation
CHANNELWIDTHFILE	pathname	Input file name for channel widths
CHANNELCONDUCTIVITY	double	Hydraulic conductivity in channel
TRANSIENTCONDUCTIVITY	double	Hydraulic conductivity during transient period
TRANSIENTTIME	double	Time until transient period ends
CHANNELPOROSITY	double	Porosity in channel
CHANPOREINDEX	double	Pore index parameter in channel
CHANPSIB	double	Matric potential in channel
OPTMESHINPUT	int	Option for Mesh generation
RAINSOURCE	int	Source of rainfall data
OPTEVAPOTRANS	int	Option for Evapotranspiration scheme
OPTSNOW	int	Option for snow
HILLALBOPT	int	Option for hillslope albedo
OPTRADSHELT	int	Option for radiation sheltering of snow
OPTINTERCEPT	int	Option for Interception scheme
OPTLANDUSE	int	Option for static or dynamic land cover
OPTLUINTERP	int	Option for land cover interpolation
OPTSOILTYPE	int	Option for soil parameter format
GFLUXOPTION	int	Option for Ground heat flux scheme
METDATAOPTION	int	Point or Grid weather data
CONVERTDATA	int	Processing weather or raingauge data
OPTBEDROCK	int	Option for uniform or variable depth
OPTGROUNDWATER	int	Option to turn on groundwater module
OPTGWFILE	int	Option for groundwater input file
WIDTHINTERPOLATION	int	Option for interpolating width variables
OPTRUNON	int	Option for hillslope runon
OPTRESERVOIR	int	Option for reservoir routing
OPTPERCOLATION	int	Option for channel percolation losses
INPUTDATAFILE	base pathname	Input file base name for Mesh files
INPUTTIME	int	Time slice for Mesh file input
ARCINFOFILENAME	base pathname	Input file base name for Arc files
POINTFILENAME	pathname	Input file name for Points files
SOILTABLENAME	pathname	Soil parameter reference table
SOILMAPNAME	pathname	Soil texture ASCII grid
LANDTABLENAME	pathname	Land use parameter reference table
LANDMAPNAME	pathname	Land use ASCII grid
GWATERFILE	pathname	Ground water ASCII grid
DEMFILE	pathname	DEM for sheltering
RAINFILE	base pathname	Radar Rainfall ASCII grids
RAINEXTENSION	extension	Extension for Radar Rainfall grids
DEPTHTOBEDROCK	meters	Uniform depth to bedrock
BEDROCKFILE	pathname	Bedrock depth ASCII grid
LUGRID	pathname	Dynamic land cover ASCII grid list
SCGRID	pathname	Spatially-variable soil parameter ASCII grid list
HYDROMETSTATIONS	pathname	Hydrometeorological station file
HYDROMETGRID	pathname	Hydrometeorological ASCII grid list
HYDROMETCONVERT	pathname	Hydrometeorological data input file
HYDROMETBASENAME	base pathname	Hydrometeorological data file
GAUGESTATIONS	pathname	Rain gauge station file
GAUGECONVERT	pathname	Rain gauge data input file
GAUGEBASENAME	base pathname	Rain gauge data file
RESPOLYGONID	pathname	Reservoir polygon ID file
RESDATA	pathname	Reservoir data table
OUTFILENAME	base pathname	tMesh and variable output
OUTHYDROFILENAME	base pathname	Hydrograph output
OPINTRVL	hours	Output interval
SPOPINTRVL	hours	Spatial output interval
OUTHYDROEXTENSION	extension	Extension for hydrographs
RIBSHYDOUTPUT	int	Compatibility with RIBS Output
NODEOUTPUTLIST	pathname	Node output list file
HYDRONODELIST	pathname	Node runtime output list file
OUTLETNODELIST	pathname	Interior node output list
OPTSPATIAL	int	Option for generating spatial output
OPTINTERHYDRO	int	Option for generating intermediate hydrographs
OPTHEADER	int	Option for generating headers in output files
FORECASTMODE	int	Forecast mode options
FORECASTTIME	int	Time in hours from start
FORECASTLEADTIME	int	Total lead time (hrs)
FORECASTLENGTH	int	Total forecast length (hrs)
FORECASTFILE	pathname	Forecast file directory
CLIMATOLOGY	double	Climatology rainfall (mm/hr)
RAINDISTRIBUTION	int	Spatial or lumped rainfall
STOCHASTICMODE	int	Stochastic model option
PMEAN	double	Mean rainfall intensity (mm/hr)
STDUR	double	Mean storm duration (hrs)
ISTDUR	double	Mean time interval between storms (hrs)
SEED	int	Random seed
PERIOD	double	Period of variation (hrs)
MAXPMEAN	double	Maximum value of mean rainfall intensity (mm/hr)
MAXSTDURMN	double	Maximum value of mean storm duration (hrs)
MAXISTDURMN	double	Maximum value of mean interstorm duration (hrs)
WEATHERTABLENAME	filename	Stochastic weather file name
TLINKE	double	Atmospheric turbidity parameter
MINSNTEMP	double	Minimum snow temperature allowed (Celsius)
SNLIQFRAC	double	Liquid water holding capacity
TEMPLAPSE	double	Temperature lapse rate
PRECLAPSE	double	Precipitation lapse rate
PARALLELMODE	int	Option to run as serial (0) or parallel (1) mode
GRAPHOPTION	int	Option for graph file type (0, 1 or 2)
GRAPHFILE	filename	Reach connectivity (graph) filename
RESTARTMODE	int	Option for restart mode (0, 1, 2 or 3)
RESTARTINTRVL	hours	Time set for restart output
RESTARTDIR	pathname	Path of directory for restart output
RESTARTFILE	filename	Filename of restart file
OPTVIZ	int	Option to write viz binary files
OUTVIZFILENAME	filename	Filename for viz binary files

Input File Options

Model Run Parameters: Time Variables

The STARTDATE keyword is used to indicate the starting time of the model simulation in the following format: MM/DD/YYYY/HH/MM (Month/Day/Year/Hour/Minutes). Values of the rainfall and meteorological inputs must exist for this starting date for the model to execute properly. The RUNTIME keyword is used to specify the number of hours in the total length of the simulation. Similarly, there must be hydrometeorologic data that span the period between the start date and the end date. The TIMESTEP parameter is used to specify the Unsaturated Zone computational time step in minutes. For proper execution, the unsaturated time step should be on the order of minutes. The GWSTEP represents the groundwater or Saturated Zone computational time step, also in minutes. Typically, the groundwater time step can be on the order of tens of minutes for most applications. METSTEP specifies the time step of hydrometeorological data input from weather stations, in minutes. This time step is usually set to 60 minutes since the weather parameters are available at this temporal resolution. ETISTEP specifies the interval for the evapotranspiration, interception and snow model calculations in hours. The RAININTRVL keyword is used for the input time interval of rainfall data, either from radar rainfall grids or from raingauges, in hours. This interval will depend on the resolution of the radar data which is available from 15 minute up to daily intervals. INTSTORMMAX is the amount of hours without rainfall that the model considers to be sufficient for an interstorm period to begin, while RAINSEARCH is the amount of hours that the model will search for the next rainfall file without producing an error message and exiting the program.

Model Input Files and Pathnames: Mesh Generation

The OPTMESHINPUT keyword is used to indicate the option for inputting the topographic data into the model. It controls the sort of mesh data that is read by the model and necessary input data files related to the model mesh. Seven options currently are implemented within the tRIBS Model: 1 = tMesh files from a prior run are used to recreate the mesh (*.nodes, *.edges, *.tri, *.z); 2 = Point file used to create a new mesh (*.points); 3 = Arc/Info Grid file is read and sampled randomly to create the mesh; 4 = Arc/Info Grid file is read and sampled hexagonally to create the mesh; 5 = Arc/Info Ungenerated TIN file used to create a Points File (*.net); 6 = Arc/Info Ungenerated TIN files used to create a Points File (*.pnt and *.lin); 7 = Mesh constructed from scratch; 8 = Point File used with Tipper Triangulation procedure (*.points); 9 = Meshbuilder routines to deal with very large TIN domains (>200,000 to 10s of millions of nodes). The Meshbuilder is a separate executable that operates with an input file (*.in) and a points file (*.points).

When specifying the OPTMESHINPUT option, the model will require that the pathname of the input files be included within the Mesh Generation section of the Model Input File. The INPUTDATAFILE option is used to input the basename for the Mesh input files produced during a previous run (OPTMESHINPUT = 1), while the INPUTTIME keyword specifies the time slice for mesh input (for tRIBS, INPUTTIME should always be set to zero). If using OPTMESHINPUT = 2, then the POINTFILENAME keyword must be used to specify the pathname and filename of the Points File (*.points). If using OPTMESHINPUT = 2 through 6, then the keyword ARCINFOFILENAME specifies the pathname and basename for the Arc/Info grids or output files (*.asc, *.net, *.lin, *.pnt).

Model Run Parameters: Routing Variables

The tRIBS has a simplified hydrologic scheme for hillslope routing and a finite-element channel routing scheme. The model allows for non-linear routing based on the discharge at a single watershed outlet and two parameter values, the stream velocity and the hillslope velocity, shared by all TIN nodes of that particular type. The hydrologic routing scheme utilizes the discharge at the closest stream node to determine the hillslope velocity. Six routing parameters are specified to the model: BASEFLOW, VELOCITYCOEF, FLOWEXP, VELOCITYRATIO, CHANNELROUGHNESS, and CHANNELWIDTH. (Note: The WIDTHINTERPOLATION keyword is used to specify whether or not channel widths will be interpolated between the measured and observed widths (= 0) or only between the measured channel widths (= 1), inputted to the model through the file name specified using the keyword CHANNELWIDTHFILE.)

BASEFLOW is used to specify the minimum flow in the stream network in cubic meters per second, a required parameter since the flow network velocities depend on the outlet discharge in some linear or nonlinear fashion. If the BASEFLOW parameter is not specified, a value of 0.001 cubic meters per second is assigned as default. VELOCITYCOEF is used to specify the coefficient in the relationship between the stream velocity and the outlet discharge, while the FLOWEXP is the exponent on the discharge in this relationship. Specifying FLOWEXP = 0 implies a linear relationship between the stream velocity and the outlet discharge. The VELOCITYRATIO keyword is the ratio between the calculated stream velocity and the hillslope velocity assigned to non-stream nodes. The last two parameters: CHANNELROUGHNESS and CHANNELWIDTH are both uniform parameters for the entire stream network in this model version. The roughness parameters refers to a non-dimensional Manning’s coefficient while the width is a channel width in meters.

Model Run Parameters: Hydrologic Processes

This section is dedicated to the model run options used to specify which hydrological processes are chosen for a particular model run.

The OPTEVAPOTRANS parameter indicates the evapotranspiration option selected during the model run. The choice of the particular option will set the required parameter values used from the land use reclassification table and the meteorological data file. Five options are available for evapotranspiration: 0 = Inactive; 1 = Penman-Monteith method; 2 = Deardorff method; 3 = Priestley-Taylor method; 4 = Pan Evaporation measurements. The OPTINTERCEPT option allows the user to choose between three particular interception routines: 0 = Inactive, 1 = Canopy storage method; 2 = Canopy water balance method. The choice of the particular option will set the required parameter values used from the land use reclassification table. The GFLUXOPTION keyword allows two types of ground heat flux calculations to be performed: 0 = Inactive; 1 = Temperature gradient method, 2 = Force-restore method. The choice of the particular option will set the required parameter values used from the soil reclassification table.

The OPTSNOW parameter indicates the snow pack option used. Currently, either the single-layer energy balance module is on (OPTSNOW = 1) or off (OPTSNOW = 0). With the single-layer EB model, it has been found necessary to also input a minimum allowable temperature in Celsius (MINSNTEMP) in order to allow numerical stability. Additionally, the maximum fraction of liquid water, SNLIQFRAC, in the snowpack must also be specified.

The OPTLANDUSE parameter is used to indicate if static or dynamic land cover maps will be used in the simulation. Two options exist: OPTLANDUSE = 0 (static representation read in at the initial time period) and OPTLANDUSE = 1 (dynamic updating of the land cover at times specified by the available grids). If the dynamic updating is specified, then the user must indicate the pathname of the file containing the filenames of the ASCII grids to be read. This is specified using the keyword LUGRID (pathname to a Grid Data File, *.gdf). This file should contain the pathnames to the dynamic land cover grids. File naming convention only uses up to the hourly time stamp (no minutes, for example). The files need to be within the time boundaries of the simulation period. The keyword OPTLUINTERP allows for two types of interpolations between available land cover maps (at different time periods). OPTLUINTERP = 0 assigns the current gridded time step value to all model time steps up until the next available file. OPTLUINTERP = 1 linearly interpolates the land cover parameter values between two different grid time steps.

The OPTSOILTYPE keyword is used to activate the use of gridded soil parameter data input into the model. This option replaces the use of a soil grid index map and a soil parameter table. Two options exist: OPTSOILTYPE = 0, uses the traditional tabular soil data associated with a soil map of soil type numbers; OPTSOILTYPE =1, activates the use of gridded soil data, a new functionality. If OPTSOILTYPE = 1 then an additional folder named SoilTexture must be created in the main tRIBS directory where folders like Input and Output are located. This new folder should contain a database (*.gdf) file indicating the paths to all the grid files for each soil parameter. The format is similar to that used for the dynamic land cover maps. The directory path to the new folder is indicated under SCGRID keyword in the Input File.

The OPTBEDROCK keyword is used to specify the format of the bedrock depth data: 0 = Uniform bedrock depth over the basin; 1 = Grid bedrock file. If OPTBEDROCK = 0, then the DEPTHTOBEDROCK keyword is required (input is a double), otherwise the BEDROCKFILE keyword is required (input is a path and filename with extension *.brd).

The OPTGROUNDWATER runs the groundwater module; 1 = the groundwater module is on, 0= the groundwater module is off.

The OPTGWFILE keyword is used to specify the format of the initial groundwater input file. 0 = Resample ASCII grid file indicated in GWATERFILE; 1 = Read in Voronoi polygon file with groundwater levels output from previous run. GWATERFILE keyword only used for OPTGWFILE option 0, otherwise, the Voronoi GW file is read in through user interaction with model run (e.g. through screen).

The OPTRESERVOIR keyword is used to activate the use of the linear reservoir module (tReservoir) in the model. 0 = Disable the use of Reservoirs. 1 = Activate the use of Reservoirs. If OPTRESERVOIR = 1 then additional information is required by specifying the path to the file containing the TIN nodes (or Voronoi polygons) to be used as reservoirs in RESPOLYGONID (*.res) and the path to the file containing the elevation-discharge-storage information for each type of reservoir in RESDATA (*.eds).

The OPTPERCOLATION keyword allows the user to select from several options for channel percolation losses. 0 = No channel percolation. 1 = Constant loss method where the infiltration rate is equal to the channel saturated hydraulic conductivity specified under CHANNELCONDUCTIVITY. 2 = Constant loss method with a transient period applied with the transient hydraulic conductivity specified as TRANSIENTCONDUCTIVITY and the transient time period specified as TRANSIENTTIME. 3 = Green-Ampt infiltration equation with the parameters specified as CHANNELPOROSITY, CHANPOREINDEX and CHANPSIB.

Mesh Input Files and Pathnames: Spatial Data

The path and filenames of the grid input and the reclassification tables for the soil and land use data are grouped together within this section of the Input File. The soil grid (*.soi), land use grid (*.lan) and initial groundwater table position (*.iwt) are specified using the SOILMAPNAME, LANDMAPNAME and GWATERFILE keywords. The DEM used to derive the remote sheltering grids is specified by the DEMFILE keyword. The DEM used should encompass the study area and all significant surrounding topographic features, possibly outside the study area.

Additionally if OPTBEDROCK =1, then the path and filename with extension to the ascii grid must be specified using BEDROCKFILE. Likewise if either OPTSOILTYPE = 1 and or OPTLANDUSE = 1 then a grid data file (.gdf) will need to be specified with the keywords *SCGRID and LUGRID, respectively.

Mesh Input Files and Pathnames: Meteorological Data

The path and filenames of the meteorological data are grouped together in this section of the Model Input File.

The RAINSOURCE keyword is used to indicate the rainfall data source given to the model. Two types of radar rainfall data, as well as raingauge measurements are considered in the tRIBS Model: 1 = NEXRAD Stage III Radar (cm/hr); 2 = WSI Precipitation Radar (mm/hr); 3 = Rain Gauge station data (mm/hr).The radar rainfall grid (for RAINSOURCE = 1 or 2) base name is specified using the RAINFILE keyword and the extension is inputted by using the RAINEXTENSION keyword.

The METDATAOPTION is used to indicated the input format for the meteorological data: 0 = Inactive; 1 = Weather station point data; 2 = Grid meteorological data. The particular choice determines which type of text files, grid or point data files are required during model execution. The CONVERTDATA option is used to indicate whether or not meteorological pre-processing is activated: 0 = Inactive pre-processing; 1 = Activated pre-processing of meteorological data from RFC Point Data; 2 = Activated pre-processing of meteorological data from gridded observations provided by University of Washington (DMIP).

If METDATAOPTION = 1, then the Station Data File (*.sdf) must be specified in HYDROMETSTATIONS and the Meteorological Data File (*.mdf) basename in HYDROMETBASENAME. Otherwise, if METDATAOPTION = 2, then the HYDROMETGRID keyword must contain the Grid Data File (*.gdf). If CONVERTDATA = 1, then the HYDROMETCONVERT parameter must specify the path and filename of the Meteorological Data Input (*.mdi) File. If CONVERTDATA = 2, then the GAUGECONVERT parameter must be specify the path and filename of the rain gauge conversion file (*.mdi). The GAUGEBASENAME keyword is used to specify the base pathname of the MDF raingauge files. Finally, if RAINSOURCE = 3, then the GAUGESTATIONS keyword is used to specify the rain gauge SDF file. If CONVERTDATA = 3, then preprocessing of DMIP formatted observed energy forcings is performed. This results in an MDF file particular to the basin of interest (1992-2000 period) with somewhat altered list of meteorological parameters that can be ingested into the model. A separate SDF file must be prepared to correspond with this data.

Lapse rates have been implemented in the model for precipitation and temperature. The temperature lapse rate is assigned from TEMPLAPSERATE. The precipitation lapse rate is specified by PRECLAPSE in mm/m. Scattered light from opposing hillslopes can be a significant component of incoming radiations in snowy environments. HILLALBOPT = 0 uses the snow albedo for the hillslope albedo, HILLALBOPT = 1 uses the land-use albedo for the hillslope albedo, and HILLALBOPT = 2 uses a dynamic representation of albedo, where the snow albedo is used if there is snow in the canopy and a vegetative fraction weighted average of snow and land-use albedo is used otherwise. OPTRADSHELT tells what radiation sheltering scheme is used: 0 = local; 1 = remote controls on diffuse shortwave radiation; 2 = remote controls on entire shortwave radiation; 3 = no sheltering.

Mesh Input Files and Pathnames: Output Data

The path and basenames of the output data are grouped in this section of the Model Input File. The keyword OUTFILENAME is used to specify the location and basename of the output mesh and the voronoi file (*.nodes, *.tri, *.edges, *.z and *.voi) as well as the dynamic variable output (*.pixel and *.dat). The keyword OUTHYDROFILENAME specifies the path and basename of the outputted hydrograph and hyetograph time series. The format of the hydrograph and hyetograph file (*.mdf) depends on the value of RIBSHYDOUTPUT: = 0, not compatible with RIBS output; or = 1, compatible with RIBS output. This distinction is necessary if the *.mrf files are to be used with the RIBS graphical user interface. The NODEOUTPUTLIST specifies the path and filename of the Node Output List (*.nol) file used to input the node IDs for dynamic variable output. The OUTLETNODELIST keyword specifies the interior stream nodes to be used for output of the interior hydrographs (*.nol) file. OPTINTVL notifies the model at what interval the model output will be produced. Likewise, SPOPTINTVL specifies at what interval the dyanmic spatial files (*_00d) are written out.

Model Modes: Rainfall Forecasting Mode

The tRIBS model can be used for real-time flood forecasting given predicted rainfall data from any number of sources (radar extrapolation, numerical weather prediction). Currently, the Rainfall Forecasting Mode allows the user to specify the forecast time, lead time and forecasting interval using the FORECASTTIME, FORECASTLEADTIME and FORECASTLENGTH keywords. The Forecasting mode is turned on using FORECASTMODE. Three options are available: Single or Updating forecast, Persistence Forecast or Climatological Forecasting. They differ in the product used after the forecast time. For single or updating, the FORECASTFILE directory is read for the forecast product. Otherwise, a persistence of the last available rainfall or the climatological value are used. The RAINDISTRIBUTION enables the inputted rainfall to be spatially-averaged within tRIBS.

Model Modes: Stochastic Rainfall Mode

The tRIBS model can be forced with real rainfall data or stochastic rainfall input using the Eagleson or Rodriguez-Iturbe type Poisson storm process at a point. The STOCHASTICMODE keyword is used to specify whether or not stochastic rainfall forcing is used as an alternative to providing observed data from radar (grid field) or rain gauge (point). The stochastic mode is off (= 0) or on in various ways: Mean forcing (= 1), random forcing (= 2), sinusoidal forcing (= 3), mean and sinusoidal forcing (= 4) and random and sinusoidal forcing (= 5). The parameters of the stochastic mode include a random seed, a periodicity, a mean/max storm duration, a mean/max interstorm duration, a mean/max rainfall intensity.The keywords PMEAN, STDUR, ISTDUR are used alone (option 1: mean forcing), in conjunction with the random seed SEED (option 2: random forcing), in conjunction with periodic forcing using the PERIOD, MAXPMEAN, MAXSTDURMN and MAXISTDURMN (option 3: sinusoidal forcing), in combination of both mean and sinusoidal (option 4: mean and sinusoidal forcing) or in combination of both mean and random forcing (option 5: mean and random forcing). A complete stochastic weather generator for all climatic variables can also be utilized by specifying STOCHASTICMODE = 6 and a filename for WEATHERTABLENAME.

Model Modes: Restart Mode

The tRIBS model can output binary files corresponding to the entire set of model states at a particular time interval. This may be necessary for recovering from a system crash and can be very useful in data assimilation and forecasting schemes. The restart mechanism is invoked by using the RESTARTMODE keyword which has four options: No restart mechanism (option 0), Write files only (option 1), Read files only (option 2), Read and write files (option 3). In this context, writing implies making model output states at a specified interval defined by the keyword RESTARTINTRVL (in hours); while reading implies using a previously generated restart file as your initial state. The restart output is written to a directory specified by the keyword RESTARTDIR (pathname of directory); while the restart reading is from a file specified by the keyword RESTARTFILE (filename). The restart mechanism should be utilized with caution with respect to file space as the restart files can be large.

Model Modes: Parallel Mode

The tRIBS model can be run in either serial or parallel mode. The keyword PARALLELMODE is used to specify either serial (option 0) or parallel (option 1) computation. If the parallel mode is used, then attention needs to be paid to the graph file partitioning option. Three methods for graph partitioning can be selected utilizing the keyword GRAPHOPTION: (a) A default partitioning of the graph (option 0); (b) A reach-based partitioning (option 1); and (c) An inlet/outlet-based partitioning (option 2). If either option 1 or 2 are selected, the keyword GRAPHFILE needs to be specified with the name of the graph file to be used (either reach or inlet/outlet based). Otherwise, no filename is required.

Model Execution

The development, operation, and execution of the tRIBS model has been improved significantly for the release under the MIT license. Despite this, it remains the responsibility of the user to provide the model with the appropriate inputs in the correct format and to understand the various means of running the model.

Compilation Instructions

tRIBS is written in C++ and must be compiled before use. To facilitate cross-platform compilation and increase the ease of compiling tRIBS in either parallel or serial mode, we employ the CMake build system. If you intend to use tRIBS in parallel then you will need to install a Message Passing Interface (MPI), the current version has been tested to compile correctly with OpenMPI though other MPI software may work. Instructions for compiling tRIBS on your machine using CMake are outlined below. Additionally, we maintain a Docker image that contains both the serial and parallel version of tRIBS as documented here. Note: these instructions are for using CMake via terminal; additional documentation is available for using the CMake GUI.

CMake

1. Use Homebrew to install CMake. Alternatively, you can download CMake directly, but Homebrew or a similar package manager is preferred as it will catch additional dependencies.

2. You can check to see if CMake is on your path by typing cmake into the command line. If it says it’s not found, then you will need to set cmake to your path. For example, if you downloaded CMake and it’s now in your application folder, you can use:

sudo "/Applications/CMake.app/Contents/bin/cmake-gui" --install

3. Next, change directory to the tRIBS source code. It should look something like this but is dependent on where the tRIBS source code is located:

cd ~/Documents/tRIBS

4. Once in the directory containing the src code subdirectory and CMakeLists.txt, execute the following code in the terminal:

cmake -S . -B build
cmake --build build --target all

The first command tells CMake to generate the make files for tRIBS in a folder called build, followed by the second line which effectively compiles the code.

5. After, you can check to see that the executable was made by using:

ls build/

The executable will have a name specified in the CMakeLists.txt file. Currently, it is set to tRIBS.

Content of CMakeLists

In some instance, CMakeLists.txt needs to be modified, for example if you want to change the name of the executable, or specify the parallel or serial build, or add additional compiler flags.

• Compiling the parallel or serial version of tRIBS can be achieved by setting the variable parallel to ON or OFF.

• The executable name is specified here set(exe "tRIBS"), where “tRIBS” can be modified.

• Additional compiler flags can be set here: set(cxx_flags "-O2"), in this case an optimization level of 2 is being passed by -O2.

Run Instructions

In order to run the tRIBS Model, an Input File is required. This file can have any name, but by convention the extension *.in is used. The model can be run from the UNIX command line by using the following syntax (within the same directory as the tribs executable):

% tribs inputfile.in [options]

For running the model in parallel mode, mpirun (or a suitable alternative MPI command) is needed:

% mpirun [options] ./tRIBS inputfile.in [options]

Alternatively, the model can be run from a separate directory by specifying the pathnames of the executable and the Input File. Table 5.1 presents a list of the options with descriptions and default values.

Table 5.1 tRIBS Run Options (*_run) [NEEDS TO BE UPDATED]

Run Option	Description	Default Setting
-A	Automatic listing of rainfall fields	(default = off)
-F	Measured and forecasted rain	(default = off)
-V	[NodeID] Verbose mode (output run-time info)	(default = off)
-O	On after simulation completion, awaiting user input	(default = off)
-K	Check input file for consistency	(default = on)

The most important of these options for the new user to be acquainted with are -V (verbose screen output), -O (continuously on model state). The last of these should be used only if one wishes to keep the model in memory while changing the inputs specified in the Input File (all model inputs except the TIN Mesh can be altered).

Model Outputs

The tRIBS Model produces a number of output files that represent the time series or the spatial distribution of model state or output variables. Output variables include the position of moisture fronts in the unsaturated zone, water table elevation, surface runoff, subsurface flux, rainfall rate, interception loss, evapotranspiration, and information on the mesh triangulation. Table 6.1, Table 6.2, and Table 6.3 summarize: (1) mesh output files, (2) time series outputs, and (3) spatial outputs. More detailed descriptions of the individual files are provided in the following sections.

Table 6.1 tRIBS Mesh Output Files

Model Mesh Files	Extension	Description
Mesh Node File	*.nodes	Node (x,y), ID of spoke, boundary code.
Mesh Edge File	*.edges	ID of origin and destination node, ID of CCW edge.
Mesh Triangle File	*.tri	ID of vertex nodes, ID of neighboring triangles opposite the
		vertex node, ID of CCW edge originating with the vertex node.
Mesh Node Elevation File	*.z	Node elevation (meters).
Mesh Voronoi Geometry	*_voi	File containing individual Voronoi polygon geometry.

Table 6.2 tRIBS Model Time Series Files

Time Series	Extension	Description
Discharge Time Series.	*_Outlet.qout or *qout	Time series of outlet or node hydrograph (m³/s).
Basin Averaged File	*.mrf	Time series of basin-averaged model variables.
Hydrograph Runoff Types File	*.rft	Time series of outlet hydrograph by runoff type (m³/s).
Node Dynamic Output File	*.pixel	Time series of dynamic variables for a specific node.

Table 6.3 tRIBS Model Spatial Output Files

Model Spatial Output Files	Extension	Description
Mesh Dynamic Output File	*timestamp_00d	Dynamic variable output for all mesh nodes at specific time.
Mesh Integrated Output File	*timestamp_00i	Time-integrated variable output for all mesh nodes.

The location of the output files is specified in the tRIBS Model Input File by using the keywords OUTFILENAME and OUTHYDROFILENAME. An important note to make is that the *.mrf, *.rft and *.dat files produced by the model are labeled with additional identifiers before the extension that relate to the time of the output. For each OPINTRVL time step, the model will produce output of the *.mrf type, while the *.rft file is produced only after completion of the entire run. The spatial output (*timestamp_00d) are determined by the time step specified in the SPOPINTRVL keyword. Time-integrated spatial output (*timestamp_00i) is produced only at the end of the simulation. The model also produces various files with a *.pixel extension followed by a node ID number at the end of the run. The *.pixel# files contain the dynamic variable output for a single node for all model times. The number of *.pixel# files produced is specified through a Node Output List (*.nol) File described below.

Table 6.4 Node Output List File Structure

#Nodes

NodeID 1

…

NodeID n

A similar structure and file is used for the keyword HYDRONODELIST and OUTLETNODELIST. Using this file, allows the user to obtain the runtime hydrologic information in the unsaturated and saturated model for each time step as output to the screen, a useful tool for debugging. No filename suppresses the debugging information.

Time Series

Basin Outlet Discharge Time Series

Table 6.5 Content of *_Outlet.qout file or *qout file if Voronoi IDs are provided via OUTLETNODELIST

Column	Description	Units
1	Time	[hr]
2	Discharge, Qstrm	[m3/s]
3	Channel stage, HLevel	[m]

Hydrologic Time Series at Selected TIN nodes

Table 6.6 Content of *.pixel files

Column	Description	Units
1	Node Identification, ID	[id]
2	Time	[hr]
3	Depth to groundwater table, Nwt	[mm]
4	Wetting front depth, Nf	[mm]
5	Top front depth, Nt	[mm]
6	Total moisture above the water table, Mu	[mm]
7	Moisture content in the initialization profile, Mi	[mm]
8	Unsaturated lateral flow out from cell, Qpout	[mm/hr]
9	Unsaturated lateral flow into cell, Qpin	[mm/hr]
10	Transmissivity, Trnsm	[m²/hr]
11	Groundwater flux, GWflx	[m³/hr]
12	Surface Runoff, Srf	[mm]
13	Rainfall, Rain	[mm/hr]
14	Soil Moisture, top 10 cm, SoilMoist	[ ]
15	Root Zone Moisture, top 1 m, RootMoist	[ ]
16	Air Temperature, AirT	[°C]
17	Dew Point Temperature, DewT	[°C]
18	Surface Temperature, SurfT	[°C]
19	Soil Temperature, SoilT	[°C]
20	Atmospheric Pressure, Press	[Pa]
21	Relative Humidity, RelHum	[ ]
22	Sky Cover, SkyCov	[ ]
23	Wind Speed, Wind	[m/s]
24	Net Radiation, NetRad	[W/m²]
25	Incoming Shortwave Radiation, ShrtRadIn	[W/m²]
26	Incoming Direct Shortwave Radiation, ShrtRadIn_dir	[W/m²]
27	Incoming Diffuse Shortwave Radiation, ShrtRadIn_dif	[W/m²]
28	Shortwave Absorbed Radiation, Vegetation, ShortAbsbVeg	[W/m²]
29	Shortwave Absorbed Radiation, Soil, ShortAbsbSoi	[W/m²]
30	Incoming Longwave Radiation, LngRadIn	[W/m²]
31	Outgoing Longwave Radiation, LngRadOut	[W/m²]
32	Potential Evaporation, PotEvp	[mm/hr]
33	Actual Evaporation, ActEvp	[mm/hr]
34	Total Evapotranspiration, EvpTtrs	[mm/hr]
35	Evaporation from Wet Canopy, EvpWetCan	[mm/hr]
36	Evaporation from Dry Canopy, EvpDryCan	[mm/hr]
37	Evaporation from Bare Soil, EvpSoil	[mm/hr]
38	Ground Heat Flux, Gflux	[W/m²]
39	Sensible Heat Flux, Hflux	[W/m²]
40	Latent Heat Flux, Lflux	[W/m²]
41	Net Precipitation, NetPrecip	[mm/hr]
42	Liquid Water Equivalent, LiqWE	[cm]
43	Ice Water Equivalent, IceWE	[cm]
44	Snow Water Equivalent, SnWE	[cm]
45	Sublimation from Snowpack, SnSub	[cm]
46	Evaporation from Snowpack, SnEvap	[cm]
46	Internal Energy of Snow Pack, U	[kJ/m²]
47	Routed Melt Water Equivalent, RouteWE	[cm]
48	Snow Temperature, SnTemp	[°C]
50	Snow Surface Age, SurfAge	[hr]
51	Change in Snow Pack Internal Energy, DU	[kJ/m²]
52	Latent Heat Flux from Snow Cover, snLHF	[kJ/m²]
53	Sensible Heat Flux from Snow Cover, snSHF	[kJ/m²]
54	Ground Heat Flux from Snow Cover, snGHF	[kJ/m²]
55	Precip Heat Flux from Snow Cover, snPHF	[kJ/m²]
56	Outgoing Longw. Rad. from Snow, snRLout	[kJ/m²]
57	Incom. Longw. Radn. from Snow, snRLin	[kJ/m²]
58	Incom. Shortw. Radn. from Snow, snRSin	[kJ/m²]
59	Error in Energy Balance, Uerror	[kJ/m²]
60	Intercepted Snow Water Equivalent, intSWEq	[cm]
61	Sublim. Snow Water Equiv. from Canopy, intSub	[cm]
62	Unloaded SWE from Canopy, intSnUnload	[cm]
63	Canopy Storage, CanStorage	[mm]
64	Cumulative Interception, CumIntercept	[mm]
65	Interception, Interception	[mm]
66	Recharge, Recharge	[mm/hr]
67	Runon, RunOn	[mm]
68	Surface Runoff in Hour, srf_Hour	[mm]
69	Discharge, Qstrm	[m³/s]
70	Channel Stage, Hlevel	[m]
71	Canopy Storage Parameter, CanStorParam	[mm]
72	Interception Coefficient, IntercepCoeff	[ ]
73	Free Throughfall Coeff.- Rutter, ThroughFall	[ ]
74	Canopy Field Capacity – Rutter, CanFieldCap	[mm]
75	Drainage coefficient – Rutter, DrainCoeff	[mm/hr]
76	Drainage Expon. Param. – Rutter, DrainExpPar	[mm⁻¹]
77	Albedo, LandUseAlb	[ ]
78	Vegetation Height , VegHeight	[m]
79	Optical Transmission Coeff., OptTransmCoeff	[ ]
80	Canopy- Average Stomatal Resistance, StomRes	[s/m]
81	Vegetation Fraction, VegFraction	[ ]
82	Canopy Leaf Area Index, LeafAI	[ ]

Basin-averaged Hydrological Time Series

Table 6.7 Content of *.mrf file

Column	Description	Units
1	Time	[hr]
2	Surface Runoff from Hydrologic Routing, Srf	[m³/s]
3	Mean Areal Precipitation, MAP	[mm/hr]
4	Maximum Rainfall Rate, Max	[mm/hr]
5	Minimum Rainfall Rate, Min	[mm/hr]
6	Forecast State, Fstate	[ ]
7	Mean Surface Soil Moisture (in top 10 cm), MSM100	[ ]
8	Mean Soil Moisture in Root Zone (in top 1 m), MSMRt	[ ]
9	Mean Soil Moisture in Unsaturated Zone (above water table), MSMU	[ ]
10	Mean Depth to Groundwater, MGW	[mm]
11	Mean Evapotranspiration, MET	[mm]
12	Areal Fraction of Surface Saturation, Sat	[ ]
13	Areal Fraction of Rainfall, Rain	[ ]
14	Average Snow Water Equivalent, AvSWE	[cm]
15	Average Amount of Snow Melt, AvMelt	[cm]
16	Average Snow Temperature, AvSTC	[°C]
17	Average Change in Snow Pack Internal Energy, AvDUint	[kJ/m²]
18	Average Latent Heat Flux from Snow Covered Areas, AvSLHF	[kJ/m²]
19	Average Sensible Heat Flux from Snow Covered Areas, AvSSHF	[kJ/m²]
20	Average Precipitation Heat Flux from Snow Covered Areas, AvSPHF	[kJ/m²]
21	Average Ground Heat Flux from Snow Covered Areas, AvSGHF	[kJ/m²]
22	Average Incoming Longwave Radiation from Snow Covered Areas, AvSRLI	[kJ/m²]
23	Average Outgoing Longwave Radiation from Snow Covered Areas, AvSRLO	[kJ/m²]
24	Average Incoming Shortwave Radiation from Snow Covered Areas, AvSRSI	[kJ/m²]
25	Mean Intercepted Snow Water Equivalent, AvInSn	[cm]
26	Mean Sublimation from Intercepted Snow, AvInSu	[cm]
27	Mean Unloaded Snow from Canopy, AvInUn	[cm]
28	Fraction Snow Covered Area, SCA	[ ]
29	Channel percolation, ChanP	[m³]

Basin-averaged Hydrological Time Series

Table 6.8 Content for *.mrf files

Column	Description	Units
1	Time	[hr]
2	Infiltration-excess Runoff, Hsrf	[m³/s]
3	Saturation-excess Runoff, Sbsrf	[m³/s]
4	Perched Return Flow, Psrf	[m³/s]
5	Groundwater Exfiltration, Satsrf	[m³/s]

Spatial Output

Dynamic Spatial Output Tables

Table 6.9 Content of *timestamp_00d files

Column	Description	Units
1	Node Identification, ID	[id]
2	Depth to groundwater table, Nwt	[mm]
3	Total moisture above the water table, Mu	[mm]
4	Moisture content in the initialization profile, Mi	[mm]
5	Wetting front depth, Nf	[mm]
6	Top front depth, Nt	[mm]
7	Unsaturated lateral flow out from cell, Qpout	[mm/hr]
8	Unsaturated lateral flow into cell, Qpin	[mm/hr]
9	Surface Runoff, Srf	[mm]
10	Rainfall, Rain	[mm/hr]
11	Snow Temperature, ST	[°C]
12	Ice Part of Snow Water Equivalent, IWE	[cm]
13	Liquid Part of Snow Water Equivalent, LWE	[cm]
14	Snow Sublimation, SnSu	[cm]
15	Snow Evaporation, SnEvap	[cm]
16	Snow Melt, SnMelt	[cm]
17	Internal Energy of Snow Pack, Upack	[kJ/m²]
18	Latent Heat Flux from Snow Cover, sLHF	[kJ/m²]
19	Sensible Heat Flux from Snow Cover, sSHF	[kJ/m²]
20	Ground Heat Flux from Snow Cover, sGHF	[kJ/m²]
21	Precipitation Heat Flux from Snow Cover, sPHF	[kJ/m²]
22	Outgoing Longwave Radiation from Snow Cover, sRLo	[kJ/m²]
23	Incoming Longwave Radation from Snow Cover, sRLi	[kJ/m²]
24	Incoming Shortwave Radiation from Snow Cover, sRSi	[kJ/m²]
25	Error in Energy Balance, Uerr	[J/m²]
26	Intercepted SWE, IntSWE	[cm]
27	Sublimated Snow from Canopy, IntSub	[cm]
28	Unloaded Snow from Canopy, IntUnl	[cm]
29	Soil Moisture, top 10 cm, SoilMoist	[ ]
30	Root Zone Moisture, top 1 m, RootMoist	[ ]
31	Canopy Storage, CanStorage	[mm]
32	Actual Evaporation, ActEvp	[mm/hr]
33	Evaporation from Bare Soil, EvpSoil	[mm/hr]
34	Total Evapotranspiration, ET	[mm/hr]
35	Ground Heat Flux, Gflux	[W/m²]
36	Sensible Heat Flux, Hflux	[W/m²]
37	Latent Heat Flux, Lflux	[W/m²]
38	Discharge, Qstrm	[m³/s]
39	Channel Stage, Hlev	[m]
40	Channel Flow Velocity, FlwVlc	[m/s]
41	Canopy Storage Parameter, CanStorParam	[mm]
42	Interception Coeff., IntercepCoeff.	[ ]
43	Free Throughfall Coeff.- Rutter, ThroughFall	[ ]
44	Canopy Field Capacity – Rutter, CanFieldCap	[mm]
45	Drainage coefficient – Rutter, DrainCoeff	[mm/hr]
46	Drainage Expon. Param. – Rutter, DrainExpPar	[mm⁻¹]
47	Albedo, LandUseAlb	[ ]
48	Vegetation Height , VegHeight	[m]
49	Optical Transmission Coeff., OptTransmCoeff	[ ]
50	Canopy- Average Stomatal Resistance, StomRes	[s/m]
51	Vegetation Fraction, VegFraction	[ ]
52	Canopy Leaf Area Index, LeafAI	[ ]

Time-integrated Spatial Output Table

Table 6.10 Content of *timestamp_00i file

Column	Description	Units
1	Node Identification, ID	[id]
2	Boundary Flag, BndCd	[ ]
3	Elevation, Z	[m]
4	Voronoi Area, VAr	[m²]
5	Contributing Area, CAr	[km²]
6	Curvature, Curv	[ ]
7	Flow Edge Length, EdgL	[m]
8	Tangent of Flow Edge Slope, tan(Slp)	[ ]
9	Width of Voronoi Flow Window, FWidth	[m]
10	Site Aspect as Angle from North, Aspect	[radian]
11	Sky View Factor, SV	[ ]
12	Land View Factor, LV	[ ]
13	Average Soil Moisture, top 10 cm, AvSM	[ ]
14	Average Root Zone Moisture, top 1 m, AvRtM	[ ]
15	Infiltration-excess Runoff Occurences, HOccr	[# of TIMESTEP]
16	Infiltration-excess Runoff Average Rate, HRt	[mm/hr]
17	Saturation-excess Runoff Occurences, SbOccr	[# of TIMESTEP]
18	Saturation-excess Runoff Average Rate, SbRt	[mm/hr]
19	Perched Return Runoff Occurences, POccr	[# of TIMESTEP]
20	Perched Return Runoff Average Rate, PRt	[mm/hr]
21	Groundwater Exfiltration Runoff Occurences, SatOccr	[# of GWSTEP]
22	Groundwater Exfiltration Runoff Average Rate, SatRt	[mm/hr]
23	Soil Saturation Occurences, SoiSatOccr	[# of TIMESTEP]
24	Recharge-Discharge Variable, RchDsch	[m]
25	Average Evapotranspiration, AveET	[mm/hr]
26	Evaporative Fraction, EvpFrct	[ ]
27	Cumulative Evapotranspiration, cET	[mm]
28	Cumulative Soil Evaporation, cEsoil	[mm]
29	Cumulative Latent Heat Flux from Snow Cover, cLHF	[kJ/m²]
30	Cumulative Melt, cMelt	[cm]
31	Cumulative Sensible Heat Flux from Snow Cover, cSHF	[kJ/m²]
32	Cumulative Precipitation Heat Flux from Snow Cover, cPHF	[kJ/m²]
33	Cumulative Incoming Longwave Radiation from Snow Cover, cRLIn	[kJ/m²]
34	Cumulative Outgoing Longwave Radiation from Snow Cover, cRLo	[kJ/m²]
35	Cumulative Incoming Shortwave Radiation from Snow Cover, cRSIn	[kJ/m²]
36	Cumulative Ground Heat Flux from Snow Cover, cGHF	[kJ/m²]
37	Cumulative Energy Balance Error, cUErr	[kJ/m²]
38	Cumulative Hrs of Sun exposure,cHrsSun	[hr]
39	Cumulative Hours Snow Covered, cHrsSnow	[hr]
40	Longest Time of Continuous Snow Cover, persTime	[hr]
41	Maximum Season SWE, peakWE	[cm]
42	Simulation Hour of Maximum SWE, peakTime	[hr]
43	Simulation Hr of Initial SWE, initTime	[hr]
44	Cumulative Sublimated Snow from | [cm] Canopy, cIntSub
45	Cumulative Sublimaton from Snow Pack, cSnSub	[cm]
46	Cumulative Evaporation from Snow Pack, cSnEvap	[cm]
47	Cumulative Unloaded Snow from Canopy, cintUnl	[cm]
48	Av. Canopy Storage Parameter, AvCanStorParam	[mm]
49	Av. Intercep. Coeff., AvIntercCoeff	[ ]
50	Av. Free Throughfall Coeff.- Rutter, AvTF	[ ]
51	Av. Canopy Field Capac. – Rutter, AvCanFieldCap	[mm]
52	Av. Drain. Coeff. – Rutter, AvDrainCoeff	[mm/hr]
53	Av. Drain. Expon. Param. – Rutter, AvDrainExpPar	[mm⁻¹]
54	Av. Albedo,AvLUAlb	[ ]
55	Av. Veg. Height , AvVegHeight	[m]
56	Av. Optical Transm. Coeff., AvOTCoeff	[ ]
57	Av. Canopy- Average Stom. Resist., AvStomRes	[s/m]
58	Av. Veg. Frac., AvVegFract	[ ]
59	Av. Canopy Leaf Area Index, AvLeafAI	[ ]
60	Depth to Bedrock, Bedrock_Depth_mm	[mm]
61	Saturate Hydraulic Conducitivity, Ks	[mm/hr]
62	Saturated Soil Moisture, ThetaS	[-]
63	Residual Soil Moisture, ThetaR	[-]
64	Pore Distribution Index, PoreSize	[-]
65	Air Entry Bubbling Pressure, AirEBubP	[mm] (negative)
66	Hydraulic Decay Parameter, DecayF	[1/mm]
67	Saturated Anisotropy Ratio, SatAnRatio	[-]
68	Unsaturated Anisotropy Ratio, UnsatAnRatio	[-]
69	Porosity, Porosity	[-]
70	Volumetric Heat Conductivity, VolHeatCond	[J/msK]
71	Soil Heat Capacity, SoilHeatCap	[J/m^k]
72	Soil Class, SoilID	[-]
73	Landuse Class, LandUseID	[-]

Development

tRIBS model development is driven by research, testing, and updates in software standards. We document information about the latest release in Release Notes. Technical issues related to tRIBS code are logged using GitHub Issues. Additional resource about model setup and applications can be found through the tRIBS User Google Group. The remaining portion of this section is dedicated to describing the formal steps involved in tRIBS development and release of new versions. If you are interested in working with the tRIBS source code please see Contributing and Using GitHub.

Support

We want to emphasize that tRIBS is a research related product developed and maintained in academic environment. Consequently, there is no official support for the tRIBS model. You are welcome to use tRIBS in your own research endeavors, however, the model code comes with no guarantees, expressed or implied, as to suitability, completeness, accuracy, and whatever other claim you would like to make. Additionally, we cannot provide individual support in setting up and running the model. This website includes reasonably complete instructions on how to run the model, including benchmark cases with full setups for example. See Model Design and Benchmark Datasets. Finally, as an open source code we rely on the community for helping drive model development and improvements. Please refer to Contributing for more information on how you can contribute to tRIBS.

Versioning

tRIBS follows Semantic Versioning nomenclature for model versions. In summary, the naming convention is as follows: tRIBS MAJOR.MINOR.PATCH.

• MAJOR version number is updated when ever a backward incompatible change is introduced.

• MINOR version number is updated when new feature or functions are added, but are backwards compatible.

• PATCH version number is updated when backwards-compatible bugs are fixed.

tRIBS Release

Anytime there is a MAJOR, MINOR, or PATCH update the following steps are performed.

1. The updated/fixed branch is merged with the main tRIBS branch through a pull request. This requires review and approval from the tRIBS maintainers. For more detail see Using GitHub.

2. We are developing various tests, from testing code compilation, end-to-end tests, and science tests. As these are developed, any new changes will be tested following these protocols.

3. With the completion of successful tests, a new build of the docker image and updates to documentation will be implemented. Note: At a minimum the Release Notes must be updated.

4. The release will be finalized on GitHub with git tag -a v<Major.Minor.Patch> -m "example of tagging", where previous releases can be identified by searching these tags.

Contributing

Open Source Frame Work

tRIBS is available as an open source software through GitHub and Docker Hub. More information can be found at Using GitHub and Docker. One of the benefits of open source software is that the underlying code is available for anyone to inspect, modify, debug, and fix. We expect that both maintainers and experienced user at some point or another will have valuable modifications or fixes for tRIBS source code. Below we highlight some resources and provide instructions for contributing to the code base.

Resources

Integrated Development Environment (IDE)

If you are going to be interacting with tRIBS source code we recommend that you use an IDE. There are some freely available IDE’s such as Visual Studio Code. Alternatively, CLion provides excellent resources for working with C++ for a yearly subscription fee or is free with an educational license. With an IDE you can actively track variables in real time even for compiled languages, or alternatively you can use GDB to debug and identify variable behavior inside tRIBS while it’s executing.

Issues

If you encounter an error, we first ask that you check to ensure that it is not user related. The majority of issues arise from user related errors, a result of improperly setting up the model inputs, including not specifying the right paths to important datasets or forgetting to turn on or off certain option in the input file. Though tRIBS has been developed to catch a number of user errors and provide informative error messages, we ask that if you encounter a potential error that you double check to ensure that is not user related, this can be achieved using an IDE or GDB as outlined above. If it is user related, but tRIBS does not provide an informative error message, we encourage you to still log the issue as outlined below.

If you do encounter an error that is clearly related to tRIBS syntax or semantics, we encourage you to take the following steps.

1. Visit both the tRIBS GitHub Issue page and the tRIBS Google Group and search the sites to see if your error has been encountered before.

2. If the issue has not been documented, then feel free to create a new issue on the tRIBS GitHub Issue page . We ask that if your issue is related to tRIBS behavior that you provide as much information as possible about the error, including details in your model setup.

3. Once the issue is flagged, you can either wait for another user or one of the maintainers to fix the problem. Or if you are able to fix the problem yourself, you can provide a pull request outlined at Using GitHub.

Modifications and Improvements

If you have comments or ideas for improving tRIBS, or would like to introduce new functionality to the source code, we ask that you log these ideas under the tRIBS GitHub Milestone page: Exploratory Ideas. Also consider starting a conversation around your ideas or comments on the tRIBS Google Group site. Lastly, we would like to note that tRIBS is a large program and introducing new features or improvements can be challenging and requires significant tests as well as clear demonstration that the improvements are needed.

For minor fixes that are on the level of patches, see Development, we maintain a separate tRIBS GitHub Milestone page: To Do this is mostly intended as a place to log needed fixes that are not critical but are on the docket for the next PATCH update.

Release Notes

This page provide a record of changes recorded by each version of tRIBS, starting with Version 5.2.0.

Known Issues

For a list of known issues and their status, visit the tRIBS GitHub Issues page.

---

Version History

tRIBS 5.2.0 (March 2024)

The tRIBS Distributed Hydrologic Modeling System, Version 5.2.0, represents a culmination of efforts and significant improvements from the initial release [1] and later versions [2], [3]. This latest version includes new physical processes related to level-pool reservoir routing [4] and channel transmission losses [5]. In addition, the latest updates (Version 5.0 and onward) entail a CMake build system , major code improvements, including a refactored snow module, fixed memory leaks in parallel mode, and updates to C++ 17 standards.

[1]

Ivanov, V.Y., Vivoni, E.R., Bras, R.L., and Entekhabi, D. 2004. Catchment Hydrologic Response with a Fully-distributed Triangulated Irregular Network Model. Water Resources Research. 40(11): W11102. https://doi.org/10.1029/2004WR003218

[2]

Vivoni, E.R., Mascaro, G., Mniszewski, S., Fasel, P., Springer, E.P., Ivanov, V.Y., and Bras, R.L. 2011. Real-world Hydrologic Assessment of a Fully-Distributed Hydrological Model in a Parallel Computing Environment. Journal of Hydrology. 409: 483-496. https://doi.org/10.1016/j.jhydrol.2011.08.053

[3]

Rinehart, A.J., Vivoni, E.R., and Brooks, P.D. 2008. Effects of Vegetation, Albedo and Solar Radiation Sheltering on the Distribution of Snow in the Valles Caldera, New Mexico. Ecohydrology. 1(3): 253-270. https://doi.org/10.1002/eco.26

[4]

Cazares-Rodriguez, J.E., Vivoni, E.R., and Mascaro, G. 2017. Comparison of Two Watershed Models for Addressing Stakeholder Flood Mitigation Strategies: Case Study of Hurricane Alex in Monterrey, México. Journal of Hydrologic Engineering. 22(9): 05017018, 1-16. https://doi.org/10.1061/(ASCE)HE.1943-5584.0001560

[5]

Schreiner-McGraw, A.P., and Vivoni, E.R. 2018. On the Sensitivity of Hillslope Runoff and Channel Transmission Losses in Arid Piedmont Slopes. Water Resources Research. 54(7): 4498-4518. https://doi.org/10.1029/2018WR022842

---

Using GitHub

The tRIBS source code is stored on GitHub using the version control system Git. As a result, any effort to develop, fix, or modify tRIBS source code requires understanding of these tools. While there are a number of useful resources that describe these tools, below we outline the steps that we request all tRIBS developers and users adhere to:

1. Start by creating a fork of the tRIBS repository.

2. Create a development branch to add any changes in the source code.

3. Keep your main and development branch up to date with changes from the main tRIBS repository.

4. Update the main tRIBS source code from your local fork by creating pull requests on GitHub.

In summary, this means that, any modification or fixes of the tRIBS source code should take place in your own fork of the main tRIBS repository. A fork is a mirror of the repository and is hosted on your personal GitHub account. Any updates, modifications, or fixes to the tRIBS source code can be implemented on this fork. These updates then can be merged to the tRIBS main repository through implementing a pull request on the GitHub website.

Note, if you do not already have a GitHub account you will need to create one, likewise you may need to install Git on your computer. Here are links for creating a GitHub account and installing Git, or alternatively you can use a GitHub graphical user interface here. If you use Git through the command line you will need to configure your account for write access using an SSH key with relevant documentation provided here.

Forking tRIBS

The following steps will create a fork of the tRIBS repository under your GitHub account.

1. Sign in to your GitHub account.

2. Go to the tRIBS home page on GitHub.

3. Click the fork button in the upper-right corner of the page.

Once completed, you will be redirected to the home page for your own copy of tRIBS.

Cloning your fork to your computer

You can clone the fork (that lives on the GitHub website) locally to your computer either using the GitHub app (the GUI), or directly from the command line using git. If you’ve never used Git before, the app is probably the way to go.

Using the GUI/app

1. Sign in to GitHub on the GUI.

2. Click on your account on the left side of the GUI.

3. This will show your fork of tRIBS. Click on the clone option next to the fork which will initiate the download of tRIBS to your computer.

Using the command line

Use the following commands from the terminal.

$ git clone git@github.com:your-user-name/tRIBS.git
$ cd tRIBS
$ git remote add upstream git://github.com/tribshms/tRIBS.git

Note if you are running into the following errors,

git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.

then you will likely need to generate a new ssh key and add it to your GitHub profile.

Docker

Docker is a containerization platform that enables developers to package applications and their dependencies into portable containers. These containers effectively run like a virtual machine and can be utilized across different computing environments. Docker images of tRIBS (both parallel and serial versions) and MeshBuilder are maintained at Docker Hub.

Getting Started with Docker

To get started with Docker, first, install Docker on your system by downloading the appropriate version for your operating system from the official Docker website. Docker can be ran both through the desktop client or via command line. In this tutorial we only focus on pulling and running tRIBS and or MeshBuilder via the command line. Additional information about running Docker can be found here.

Pulling and Running Docker Images

Once docker has successfully been installed you can pull either image from Docker Hub. We walk through both case here highlighting minor differences in this processes.

tRIBS

From the command line execute the following:

docker pull tribs/tribs:latest

You can check to see if the image is now available locally by:

docker image

From here the tRIBS image can be accessed by using docker run -it tribs/tribs:latest, where the -it flag creates an interactive session from the command line. However, in most cases, in order to successfully run tRIBS through the docker image you will need to be able to mount a local volume where data to run tRIBS is located. This can be accomplished by using the -v flag, where the local directory is mapped to a directory in the image following this structure path/in/local:path/in/image. For example, one could run:

docker run -it -v /local/path/to/data:/tribs/data tribs/tribs:latest

In this case /tribs/data represents the directory in the image to access your data stored locally. Note: it is also possible to download data into the image. From here one can execute tRIBS normally. There are two tRIBS binaries stored in /tribs/bin, a serial version, tRIBS and a version for parallel simulation tRIBS_par.

MeshBuilder

Following the above steps one can obtain a Docker image of MeshBuilder as follows:

docker pull tribs/meshbuilder:latest

MeshBuilder also requires data that should be mounted to the image. The MeshBuilder image contains a shell script meshbuild_workflow.sh. This script runs through the various steps required to successfully run MeshBuilder, but is predicated on the mounted volume containing:

1. A points file for the TIN mesh

2. A .in file, where the POINTFILENAME refers to the point file in the volume, and OUTFILENAME is the same as the base name for the model simulation.

To run the MeshBuilder image:

docker run -it -v /local/path/to/data:/meshbuild/data tribs/meshbuilder:latest

This will open up the command line for the image. To initiate the MeshBuilder workflow run ./meshbuild_workflow.sh. This will prompt the user to enter the following information:

1. Name of the .in file stored in the volume

2. Number of compute nodes to partition the mesh on

3. Method for partitioning

4. And the model base name.

These steps can be recreated manually with a more detailed description of the processes here.

Benchmark Datasets

Benchmark datasets are publicly available and hosted permanently on Zenodo, under version control and with an assigned digital object identifier (DOI). These examples are provided for a user to test the model execution against a previously-derived set of model outputs. The contents of the benchmark datasets are described both on Zenodo and the accompanying README file, which contain simple instructions for running tRIBS. The point-scale benchmark dataset demonstrates the application of tRIBS in serial mode, whereas the basin-scale benchmark dataset is a simulation that can be executed in either serial or parallel mode.

These examples are for forested regions in northern Arizona with warm and cold season hydrologic processes. As such, these cases test a wide range of the model physics for interception, soil moisture, evapotranspiration, snowpack dynamics and streamflow. Nevertheless, not all of the model capabilities are executed in the benchmark datasets and a model user needs to exercise caution when changing model inputs or altering the selected procesess.

Additional benchmark datasets will be addded here as these are released via Zenodo.

Point-Scale Simulations

tRIBS benchmark: SNOTEL point-scale simulation, Happy Jack, AZ, USA.

Basin-Scale Simulations

tRIBS benchmark: Basin-scale simulation, Big Spring, AZ, USA.

Templates

The tRIBS model setup can be facilitated by inspecting prior model runs, including the format of the main text file (Input File *.in) used to input information to the model, as well as example files for gridded or text-based inputs. The tRIBS Benchmark datasets provide useful examples. Below are some useful templates.

Input Files

• Template for tRIBS V 5.2 input file

Shell Scripts

• Example shell script for running tRIBS in parallel

• Example shell script for running tRIBS in serial