Control File Optional Keyword Value Pairs
The optional keyword=value pairs provide additional information about the data files the slots will write or read. (The one exception to this is the file keyword, which identifies the data file itself.) Although the keywords are not case sensitive, the values can be.
The currently supported keywords are:
file=<data file>
The data file the slot will read from or write to, as described above in
File Name and Directory Specification.
start_timestep=<datetime>
An optional datetime that indicates the timestep at which to start importing/exporting, as described above in
Time Range Specification. If not specified for an input DMI and the data file has a
start_date keyword, the data are imported beginning with the data file’s
start_date. If not specified for an input DMI and the data file does not have a
start_date, the slot’s start timestep is used. If not specified for an output DMI, the slot’s start timestep is used. The datetime can be specified symbolically using RPL syntax.
end_timestep=<datetime>
An optional datetime that indicates the timestep at which to end the importing/exporting, as described above in
Time Range Specification. If not specified or an input DMI, the end of the import range is based on the combination of the
end_date keyword in the data file and the
import=<fixed>|<resize> keyword in the control file as described in
import=<fixed>|<resize>. If not specified for an output DMI, the end timestep of the slot is used. The datetime can be specified symbolically using RPL syntax.
units=<units>
The units of the data the slot will import or export. <units> must match exactly one of the units defined in the Units List dialog (see
Display Units in User Interface for details on the Units List).
Note: If
units are not specified in the control file, then it defaults to the current setting in the user interface as specified by the active Unit Scheme; (see
Unit Schemes in User Interface for details). Since the unit scheme can change from invocation to invocation, it is
strongly recommended that the control file always contain units.
scale=<scale>
The scale of the data the slot will import or export.
Note: If
scale is not specified in the control file, then it defaults to the current setting in the user interface as specified by the active Unit Scheme; (see
Unit Schemes in User Interface for details). Since the unit scheme can change from invocation to invocation, it is
strongly recommended that the control file always contain the scale (even if the scale is 1.0).
precision=<display>|<model>
The precision of the data the slot will import or export. The <display> precision is that specified in the Unit Scheme for the slot. The <model> precision is 17, the same precision as all internal calculations. The default is <display>.
import=<fixed>|<resize>
This keyword controls how the DMI sets the time series range of the series slot. The default is fixed.
For either import option, the Begin Timestep of the slot is set in the same manner. If the data file contains a start_date header, the slot Begin Timestep is set to the start_date from the data file. If the data file does not contain a start_date header, the slot maintains its existing Begin Timestep.The data import always starts on the new Begin Timestep of the slot with the first value in the data file.
For import=resize, if the data file contains an end_date header, the End Timestep of the time series range of the series slot will be set to the later of the end_date header in the data file or the number of timesteps necessary hold the number of data values in the data file given the updated Begin Timestep of the slot from above. If the data file does not contain an end_date header, the End Timestep of the time series range of the slot will be extended, if necessary, to hold the number of data values in the data file given the updated Begin Timestep of the slot from above. The End Timestep of the slot will never be moved earlier if there is no end_date header in the data file.
For import=fixed, if the data file contains an end_date header, the End Timestep of the series slot is set to the end_date from the data file. Data will not be imported past the new End Timestep of the slot. If the data file does not contain an end_date header and the existing End Timestep on the slot is later than the updated Begin Timestep, the slot maintains its existing End Timestep. Data will not be imported past the End Timestep of the slot. If the existing End Timestep on the slot is equal to or earlier than the updated Begin Timestep, then the slot will be expanded to hold all of the data values in the data file starting with the updated Begin Timestep.
Note: If the control file uses the
start_timestep and
end_timestep keywords, the time range for the slot after import will still be as described here, but data will only be imported for the time range corresponding to the
start_timestep and
end_timestep in the control file. Any additional timesteps will contain NaN. (See
Time Range Specification.)
flags=<true>|<false>
The flags keyword specifies whether or not Series Slot flag values (Input, Target, Best Efficiency, Max Capacity, Drift, and Unit Values) will be exported or imported with the data. The syntax is flags=true; the default is <false>. If an input DMI, the keyword pairs in the data file should be specified as “value flag” with the flag being an integer value, e.g. Input = 1, Output = 2, etc.
aggregate=<true>|<false>
The aggregate keyword is used to specify whether or not the DMI should import/export all time series slots on an Aggregate Series slot or just the first time series column. If present, with the value “true”, and if the slot indicated is an Aggregate Series slot, the data file is expected to (on import) or will (on export) contain data for all subslots (columns) in the Aggregate Series slot. If the keyword=value pair is absent, or if its value is “false”, only the data for the first subslot (column) of the Aggregate Series slot are present.
Table 2.1 shows the resulting metacontrol file entry for the range of possible control file entries and , the aggregate keyword values
Table 2.1 Possible entries when using the aggregate keyword.
Control File entry | aggregate keyword | Metacontrol result | Comment |
|---|
Obj.Slot | false | Obj.Slot.ColumnLabel | Only the first column of the agg is import/exported |
Obj.Slot | true | Obj.Slot | All columns are imported/exported |
Obj.Slot.ColumnLabel | false | Obj.Slot.ColumnLabel | Only the specified column is imported/exported |
Obj.Slot.ColumnLabel | true | Obj.Slot | A warning is posted that the keyword is inconsistent and will be ignored. |
When Aggregate Series slot data are imported or exported in total, the data are in row-major format, one timestep per line. The subslots of the aggregation must be homogeneous in start-date, end-date and step size, and all subslots (columns) must be represented on each line.
If used with the ‘flags=true’ keyword-value pair, the data will appear in the form:
value flag value flag value flag...
The flag is an integer number representing the flag. If the named slot is in fact the first subslot (column) of an Aggregate Series slot, the behavior is the same as if the subslot (column) name were absent.
slot_anno = <true>|<false>
The slot_anno keyword indicates whether to import or export series slot notes; see
Exporting and Importing Notes Using DMIs in User Interface for details. The default value for slot_anno is false, meaning no notes will be written.
When slot_anno is set to true for an output DMI, each timestep that has a note will have the following content in the data file to the right of the slot value:
anno {<Note Group>} {<Note Text>} {<Timestamp>} {<Username>}
For an input DMI, a note in the data file should have the same format. The timestamp corresponds to the time at which the note instance was applied and has the format MM-DD-YYYY HH:MM:SS. For an input DMI, if no timestamp is included in the data file, the note instance will be given a timestamp corresponding to the time of the data import, otherwise it will apply the timestamp from the data file. The username corresponds to the user who applied the note instance.
slot_set_info = <true>|<false>
The slot_set_info keyword indicates whether to export series slot value information. The default value for slot_set_info is false, meaning no information will be written.When true, the information corresponds to the tool tips seen on slot values on slot and SCTs will be written to the file; see
Series Slots in User Interface for details. The string appears after the value. Examples of the information are “Set by DMI: Input DMI", “Set by Rule: (7) Flood Control”.
slot_opt_sol_info = <true>|<false>
The slot_opt_sol_info keyword indicates whether to export series slot optimization solution information . The default value for slot_opt_sol_info is false, meaning no information will be written. When true, the available per slot/value optimization solution information will be written to the file. The string appears after each value. Examples of the information are “Frozen at Lower Bound”, or “Frozen by (3) Minimum Load 47.6% between limits set by 3.1.1.1 and 2.1.1.1.”. See
Tooltips on Variables in Optimization for details.
User keyword=value Pairs
The user keyword=value pairs provide an additional means by which the user can pass parameters to the DMI executable. The user keyword=value pairs are specified in the control file as:
!keyword=value
The keyword=value pairs are written to the metaControl file, with the ‘!’ removed, on all lines they apply to. The DMI executable can then use the keyword=value pairs to influence its behavior.
Example 2.1
#
# All LevelPowerReservoir Outflows
#
LevelPowerReservoir.Outflow: file=~/%o.Outflow units=cfs scale=1.0
#
# All LevelPowerReservoir Pool Elevations,
# but for Hiwassee use a different scale.
#
LevelPowerReservoir.Pool Elevation: file=~/%o.%s units=ft scale=1.0
Hiwassee.Pool Elevation: file=~/%o.%s units=ft scale=10.0
#
# All LevelPowerReservoir Storages.
#
LevelPowerReservoir.Storage: file=~/%o.%s units=cfs-day scale=1.0
#
# All LevelPowerReservoir Hydrologic Inflows.
#
LevelPowerReservoir.Hydrologic Inflow: file=~/%o.%s units=cfs scale=1.0
#
# Finally, all SeriesSlots which are not selected by one of
# the preceding lines. (Remember that *.<slot type> is the
# least exact specification.) The file ~/start_end is a data
# file which contains only the start_date: and end_date:
# attributes. This will serve to change the start date and
# end date for all series slots which import this file.
#
*.SeriesSlot: file=~/start_end