Skip to content


This section describes the input files required to operate the StateMod Model. Some data file formats have been superseded over time while continuing to maintain the old format. For a description of the old format see Section 9 Discontinued but Supported File Formats.

Regardless of how the model is applied: Base Flow, Simulate, Report, or Data Check of a monthly simulation requires no more than the first 29 files (less may be provided if wells are simulated). Additional files are needed to implement more complex operations, including files 31 - 33 for variable efficiency and soil moisture accounting; files 36 – 46 for a daily simulation; and files 47 – 53 for specific, relatively unique applications that include a downstream call, plans, and the Rio Grande Compact.

Throughout this documentation a standard file naming convention has been used (e.g. Response file (*.rsp), Control file (*.ctl), etc. where * refers to a basin or scenario). This naming convention is recommended for scenario management but it is not required. Note that model output files take on the name of the response (*.rsp) file; the user is encouraged to manage different model runs using the response file name.

When the base streamflow file is generated outside the StateMod baseflow module or represents a file that has been saved for historical purposes, it is typically named *.rim. However when the StateMod baseflow results are used for the simulation, the baseflow file it is typically named *.xbm to ensure data passes from the baseflow module to the simulate module.

In general, the top of each data set contains a variable number of comment cards identified by a # in column 1; for files created using a DMI (TSTool or StateDMI) these comments reflect the command file used to create the file. Generally, only the control (*.ctl) file and operational right (*.opr) files allow comments identified by a # below the header and within the data itself. It is recommended that a # sign be used specifically in the operating rule file to provide additional comments (as this file is not created using a DMI) and to turn off all lines associated with operating rules not used in a given scenario. Monthly time series data contain values for each month of the study period. Annual time series contain twelve values to be repeated for each year of the study period.

All structure names and ID’s are limited to 24 and 12 characters respectively. To allow free formatted input files there should be no blank characters in the name or ID or they should be in single or double quotes (e.g. instead of My Name use 'My_Name' or “My Name”).

Identifiers used throughout the model are limited to 12 characters. However if the standard numbering convention shown below is followed the ID should be limited to 9 characters since 3 of the 12 may be used to identify up to 99 unique water rights (e.g. 123456789.01). In general, any character may be used as an ID in StateMod although two reports; one related to the operational right file and one related to consumptive use by water district identifier look for specific characters in specific fields to simplify reporting. The Data Check option generates a report for operating rules which uses the operational right ID to the left of the decimal point to group operational rights from the same source together. Similarly, the consumptive use report (*.xcu) from the Report option presents the diversions by water district by combining all structures that have the first two digits of their ID the same. The following convention is recommended to ensure the reports operate appropriately and that data for different river basins will have unique identifiers:

Item Source Example
Diversion ID State WD + 5-digit ID 5700501
Reservoir ID State WD + 5-digit ID 5703001
Instream Flow ID State WD + 5-digit ID 5702501
Instream Flow terminus ID State WD + 5-digit ID 5702501_Dwn
Water Right Associated Structure ID plus .01, .02, etc. 5700501.01
Operational Right ID Source Structure * 10 + .01, .02, etc. 5703010.01
Streamflow Gage ID USGS ID 09010400
Intermediate River Node Upstream USGS ID + .01 09010400.01
Precipitation ID NOAA/NCDC ID USC00050848
Evaporation ID NOAA/NCDC ID USC00050848
Administration Number State Engineer's Administration Number 16192.10378
Delay (Return Flow) Table ID 1, 2, 3, etc.
Aggregated diversions User WD_XXB### 43_ADW001
WD is the water district
XX is the aggregated type (AD = diversion, AR = reservoir, AM = municipal, AS = stock pond)
B = basin (W = White, S = San Juan, etc.)
### = counter