Skip to content

TSTool / Datastore Reference / StateModB


The StateModB time series input type corresponds to the file format used by the State of Colorado's StateMod model, in particular the binary FORTRAN direct access output files. These files contain important water balance information for every node in the model network. The following table summarizes the contents of the binary files and corresponding text report files (all files can be large for large data sets):

StateMod Binary Files and Corresponding Report Files

Node Type Monthly Binary File Monthly Report File Daily Binary File Daily Report File
Diversion *.b43 *.xdd *.b49 *.xdy
Instream flow *.b43 *.xdd *.b49 *.xdy
Reservoir *.b44 *.xre *.b50 *.xry
Stream gage and Stream estimate *.b43 *.xdd *.b49 *.xdy
Well *.b42 *.xwe *.b65 *.xwy

The following documentation describes the format of the b43 binary file. Other files are similar. See the StateMod Documentation for a complete description of StateMod output files. Important comments about the file format are:

  • The file is generated by StateMod as a direct access binary file with fixed-length records. The record length is 140 bytes.
  • The file is divided into a header section (top) and data section (bottom).
  • The format is optimized to allow a full year of data to be read for the entire data set. Efficiently reading a time series for a single location for the full period requires reading appropriate lines of the file using direct access. Because the file is binary and consistent for a given data set, file reads can be optimized.
  • The data period and the calendar year type are consistent with the StateMod control file.
  • All character strings are left justified and are padded with spaces. Therefore, software that reads the file should trim trailing spaces after reading the strings.
  • River node identifiers in record 5 are included for all nodes in the network and data records (record 11) follow this order. Subsequent lists for various node types are a subset of the list in record 5 and have data items to reference the position in the river node list. Time series are queried using the identifiers in records 6+. However, the river node position is actually used to retrieve data in the file.

The b43 binary file contains the following records:

b43 Binary File Record Specification

Record Field StateMod Variable           Type Description
1 1 iystr0 integer Beginning year of simulation, for year type in StateMod control file.
1 2 iyend0 integer Ending year of simulation, for year type in StateMod control file.
2 1 numsta integer Number of river nodes.
2 2 numdiv integer Number of direct diversions.
2 3 numifr integer Number of instream flows.
2 4 numres integer Number of reservoirs.
2 5 numown integer Number of reservoir owners.
2 6 nrsact integer Number of active reservoirs.
2 7 numrun integer Number of base flow nodes.
2 8 numdivw integer Number of diversion structures with wells.
2 9 numdxw integer Number of well only structures.
3 1 xmonam(14) Each is char(4). Month names corresponding to the calendar type for the simulation. This information is provided as a convenience for data processing. For example, if the year type is WYR (water year), xmonam(1) is OCT. The 13th value is TOT and the 14th value is AVE.
4 1 mthday(12) Each is integer. Number of days per month, corresponding to the calendar type for the simulation. This information is provided as a convenience for data processing and to convert daily data values to monthly. For example, if the year type is WYR (water year), mthday(1) is 31 for October. The number of days in February is typically 28 and is used for all data processing, regardless of whether a year is a leap year.
5 Repeat record for numsta 1 j integer Counter for record type 5.
5 2 cstaid(j) char(12) River node identifiers.
5 3 stanam(j) real(6) River node names.
6 Repeat record for numdiv 1 j integer Counter for record type 6.
6 2 cdivid(j) char(12) Diversion identifier.
6 3 divnam(j) real(6) Diversion name.
6 4 idvsta(j) integer River node position (1+) to allow cross-reference with river nodes.
7 Repeat record for numifr 1 j integer Counter for record type 7.
7 2 cifrid(j) char(12) Instream flow identifier.
7 3 xfrnam(j) real(6) Instream flow name.
7 4 ifrsta(j) integer River node position (1+) to allow cross-reference with river nodes.
8 Repeat record for numres 1 j integer Counter for record type 8.
8 2 cresid(j) char(12) Reservoir identifier.
8 3 resnam(j) real(6) Reservoir name.
8 4 irssta integer River node position (1+) to allow cross-reference with river nodes.
9 Repeat record for numrun 1 j integer Counter for record type 9.
9 2 crunid(j) char(12) Base flow node identifier.
9 3 runnam(j) real(6) Base flow node name.
9 4 irusta(j) integer River node position (1+) to allow cross-reference with river nodes.
10 Repeat record for numdivw 1 j integer Counter for record type 10.
10 2 cdividw(j) char(12) Well identifier.
10 3 divnamw(j) real(6) Well name.
10 4 idvstw(j) integer River node position (1+) to allow cross-reference with river nodes.
11 Repeat record for every river node numsta, for every month of the simulation. See the StateMod documentation for a full description of parameters. Parameters are grouped as shown in the *.xdd file. 1 dat(1) real Demand - Total_Demand
11 2 dat(2) real Demand - CU_Demand
11 3 dat(3) real Water Supply - From_River_By_Priority
11 4 dat(4) real Water Supply - From_River_By_Storage
11 5 dat(5) real Water Supply - From_River_By_Exchange
11 6 dat(6) real Water Supply - From_Well
11 7 dat(7) real Water Supply - From_Carrier_By_Priority
11 8 dat(8) real Water Supply - From_Carrier_By_Storage
11 9 dat(9) real Water Supply - Carried_Water
11 10 dat(10) real Water Supply - From_Soil
11 11 dat(11) real Water Supply - Total_Supply
11 12 dat(12) real Shortage - Total_Short
11 13 dat(13) real Shortage - CU_Short
11 14 dat(14) real Water Use - Consumptive_Use
11 15 dat(15) real Water Use - To_Soil
11 16 dat(16) real Water Use - Total_Return
11 17 dat(17) real Water Use - Loss
11 18 dat(18) real Station In/Out - Upstream_Inflow
11 19 dat(19) real Station In/Out - Reach_Gain
11 20 dat(20) real Station In/Out - Return_Flow
11 21 dat(21) real Station In/Out - Well_Depletion
11 22 dat(22) real Station In/Out - To_From_GW_Storage
11 23 dat(23) real Station Balance - River_Inflow
11 24 dat(24) real Station Balance - River_Divert
11 25 dat(25) real Station Balance - River_By_Well
11 26 dat(26) real Station Balance - River_Outflow
11 27 dat(27) real Available Flow - Available_Flow
11 28 dat(28) real Structure type (Na):
  • < 0 = Baseflow node (e.g., -10001 indicates a diversion that is a baseflow node).
  • 0 = Well only.
  • 1-5000 = Diversion
  • 5001 – 7500 = Instream flow
  • 7501 – 10000 = Reservoir
11 29 dat(29) real Number of structures at this node (typically 1).

Standard Time Series Properties

The standard time series identifier for StateMod binary time series is of the form:


Time series properties are set using the following guidelines:

  • The location part of the time series identifier is taken from the identifier field in the data. The identifier for the specific node type (e.g., diversion) is used, not the river node identifier. The river node identifier is often the same as for the specific node type, but this is not a requirement within StateMod.
  • The data source part of the time series identifier is set to StateMod, because StateMod has created the output time series.
  • The data type is assigned as the parameter name (see record 11 above, without using the group). Parameters with name NA should be ignored because they are placeholders for future additions.
  • The data interval is assigned as Month or Day, depending on the file extension.
  • The scenario is set to blank.
  • The input type is set to StateModB, which indicates to software how to read the time series.
  • The input name is set to the name of the file.
  • The units for daily data are assigned as CFS. The units for monthly data in the files are average CFS for the month and are converted to ACFT, assuming a constant number of days per month, as read from record 4. February normally has 28 days per month in the header and therefore leap years have one fewer days than actual.
  • The missing data value is assigned to -999.0.
  • The description is set to the node name.
  • The period is set based on the header information in record 1 (for the year) and record 3 (to determine the start and end months, based on the calendar type).


StateMod binary files have the following limitations:

  • The file does not contain a format version; therefore, it is difficult for software to handle changes in the file format.
  • The file does not contain header information indicating the source of the file (e.g., the creation date, user, directory, StateMod response file, command line). Therefore, it is difficult to know with certainty how a file was created.
  • Leap years are not explicitly handled with 29 days.
  • Baseflow nodes in record 9 may have the same identifier as other nodes because any node can be a baseflow node. This can be confusing since software may list the node in more than one list. The software that reads the file filters out duplicate time series identifiers to try to resolve this problem.
  • This documentation is limited in that it presents the file format only for the *.b43 file. Additional documentation may be added in the future.