skip to main content
Trace Directory DMI
Data Management Interface (DMI)
Trace Directory DMI
The Trace Directory Data Management Interface (DMI) is similar to the Control File-Executable approach where the user develops a “control file” that specifies the slot data to move into or out of RiverWare. However, instead of an executable, the user specifies a top directory, under which the data files for traces are accessed in subdirectories named with the trace number.
Overview
The Trace Directory DMI provides a means to transfer data between RiverWare and data files in a known directory structure. There are two directions in which the DMI can transfer data:
• An Input DMI transfers data from data files into RiverWare.
• An Output DMI transfers data from RiverWare into data files.
The Trace Directory DMI consists of several components. Figure 3.1 illustrates the relationships among these components.
Figure 3.1  Trace Directory DMI components
• The user-specified Control File is created by the user and contains a list of slots which the user wants imported or exported from the RiverWare model. The control file is an ASCII file which can map data between object.slot names in the Workspace and data file names. See “Control File” for details. But no file= needs to be specified as the Trace Directory DMI can resolve the file name from the trace directory path and the object.slot name. The control file could be as simple as the following entry:
BigRes.Outflow: units=cfs scale=1
• The user-specified top directory is a directory under which data files will be located within subdirectories named with the trace number corresponding to the data (i.e. trace1, trace2, etc.) Multiple traces could be associated with input or output DMIs from multiple runs, but running a Trace Directory DMI outside of MRM would use a single trace folder. Figure 3.2 is an example of a top directory (NatFlowInput) and trace subdirectories, each of which contains slot data files.
Figure 3.2   
• The RiverWare DMI data files are a set of files used to transfer the data to and from the RiverWare model. Each of these files contains the data for a single slot in the model. In an output DMI RiverWare will create the files, or will read existing files for an input DMI. See “Data Files” for details.
Following is an example of how the DMI works. In this example we assume it is an Input DMI, but it is the same, just reversed for an Output DMI.
1. The user Invokes the Input DMI.
2. RiverWare verifies the DMI to make sure it is valid.
3. RiverWare reads the user Control File and resolves all wild carding. It then substitutes the directory path for the current trace into the file keyword path for each entry in the control file. If a file keyword is not provided, it generates one from the trace directory path and the object.slot name. It then writes the Meta Control File, which has a fully specified line for each slot in the Control File.
4. RiverWare then uses the Meta Control File to read the DMI Data Files from their appropriate directory and imports the data into the slots in RiverWare.
Trace Directory DMI Editor Dialog
A new Trace Directory DMI is created from the main DMI Manager dialog by selecting DMI, then New DMI, then Trace Directory DMI. Edit the DMI by double-clicking in the DMI Manager or by selecting Edit from the Edit menu; the Trace Directory DMI Editor dialog appears.
Figure 3.3   
Many of the configuration options are the same as those for the Control File-Executable DMI. The following list references the discussions in that section for the equivalent controls:
• Name - Name.
• Type - Type.
• Confirm Warnings Toggle - Confirm Warnings Checkbox.
• Record Invocations - Record Invocations.
• Allow Spaces in File Paths - Allow Spaces in File Paths.
• Limit Output to Run Range - Limit Output to Run Range.
• Line Ending - Line Ending.
• Control File - Control File.
To specify a Top Directory and the Control File the user either:
• The button to open a chooser dialog and select the directory/file.
• Select the field to edit the path in place.
The top directory path can contain environment variable references of the form:
• $VARIABLE
• $(VARIABLE)
• ${VARIABLE}
VARIABLE is a letter followed by zero or more letters, digits or underscores. If the variable is followed by a letter, digit or underscore it must be “quoted” with () or {}. For example:
• $DMI_DIR/EvapData/
• $(DMI_DIR)_$TARGET/EvapData/
The Trace to use outside of MRM control is an integer spinner where a trace number can be selected or typed. If this DMI is executed outside of a multiple run, this trace number is used to determine the subdirectory under the top directory to use for reading or writing data. For example, if the trace number is 3, the subdirectory “trace3” is used as the location for the DMI input or output files. Within MRM, the trace number is automatically substituted.
 
Revised: 06/03/2019