Run Importer

Purpose

The Run Importer allows property values and links for a series of Simulation runs to be read in from a file. Several runs can be stored and retrieved and for each run, a different set of property values and links can be set. After each run, the properties are restored to their old values and any links created by the importer are destroyed. For example, this would be used for sensitivity testing or for Monte Carlo analyses where multiple properties would be varied for each run.

File Syntax

General Notes

All keywords are not case sensitive. The text values for properties will retain the case that they have in the file. The general format of the file is Keyword: value. Note that the keyword is followed immediately by a colon. This is required. Then a value follows. This value may be on a single line or on multiple lines. To place a value on a single line simply place it after the keyword. To enter a value that spans multiple lines, enclose it in "[[" and "]]" brackets.

Comments may be placed in the file. To place a comment on an entire line, use "//" at the start of the line. To use a comment that will span over many lines, use "/*" and "*/" to enclose the comment.

Here is a short example:

...
// A simple, single line comment.
Property: ConvectionRate
    Form: Function
   Value: v^2/area
Property: SampleLongField
   Value: [[ This is a long and rambling sentence to
illustrate the use of a multi-line value. ]]
/* A more involved and longer
comment that spans several
lines. */
...

White space will be trimmed from around values. If you wish to place a new-line in the value of a property, use "\n". If you wish to place a back-slash in a property value, use a "\\".

Detailed Syntax

Header

The first line without a comment must contain a "Version:" keyword and a version number. Currently, this must be version 1.
This must be followed by a "Scenario:" keyword and the name of a Scenario that exists in the currently loaded project.
This may be optionally followed by a "NumberOfRuns:" keyword and the number of runs in the file. This is not required as the importer will discover the number of runs in the file as it reads them in.

Version: 1
Scenario: Fish In Walden Pond
NumberOfRuns: 4
...

Body

If there are property values or links that should be set for all runs, they should be set here. They will be set in the Scenario before any runs begin and will be unset after all runs are complete. The syntax for setting properties and links in described below.

After this, there must be one or more Run sections, each of which describes property values and/or links to set for each run. A run section is preceded by the keyword "Run:" and a name. The run may be optionally followed by a "Description:" keyword and a description of the file.

Run: First run varying temperature

After this specify any number of properties or links to use in the current run. A property that is found in the object will be replaced with the new value before the run starts. At the end of the run, the old value will be restored. A property that is not found in a given object will be created and then removed after the run is over. Links will be treated similarly. If the link that is specified is in the object exists, the one in the file will replace it during the run and the original will be restored after the run is over. If the link does not exist, it will be created and added before the run and deleted after the run completes.

Setting Property Values

The first keyword needed to specify a property is the type of object that contains this property. This could be "Algorithm:", "Chemical:", "Compartment:", "Link:", "Scenario:", "Source:" or "VolumeElement:". This should be followed by the full name of the object. This can be any object in that exists in the system. If the specified object does not exist, the importer will generate an error. Objects can be read in from files using the Object Importer. The only exception to this rule if for Links, which can be created as described further below. If you are setting the same property across multiple objects to the same value, then you can specify the objects in a list by placing each one on a separate line. For example, to specify a property for one object, use this syntax:

Compartment: Fish - Default Fish in Pond - Greenwich
Property: Respiration
Value: 4.4E-2

To specify the same property over multiple objects, use this syntax:

Compartment: Grass - Default Grass in Field - Greenwich
Compartment: Trees - Default Trees in Forest - Greenwich
Compartment: Algae - Default Algae in Pond - Greenwich
Property: Respiration
Value: 4.4E-2

After the objects have been specified, the "Property:" keyword must be used to specify which property to change. The property name can be preceded with a chemical name if it applies only to one chemical. This chemical name must be enclosed in "{...}" brackets. After this, the form of the property may need to be specified. Properties can have one of 4 different forms; Constant, Formula, UnevenlyStepped and InputFromFile. The default form of properties is Constant. If your property value is constant, you do not need to use the "Form:" keyword. If it is any other form, you will need to include the "Form:" keyword followed by "Formula", "UnevenlyStepped" or "InputFromFile". After this the "Value:" keyword is used to specify the new value of the property.

The value for the Formula for is simply the formula typed in. If it extends over multiple lines, use the "[[" and "]]"
Below are several examples of each form in use.

Chemical: Methyl Mercaptan
Property: MolecularWeight
   Value: 52
Property: VaporPressure
    Form: Formula
   Value: a^2*t + b*t + c
Property: DecompositionRate
    Form: UnevenlyStepped
   Value: [[ (01/01/2000, 12:00:00 GMT, 5.0E-3),(01/01/2000, 13:00:00, 5.5E-3)
          (01/01/2000, 14:00:00 GMT, 5.65E-3),(01/01/2000, 15:00:00, 5.8E-3) ]]
Property: HeatCapacity
    Form: InputFromFile
   Value: c:\\trim\\data\\simulation, HeatCap, ";"

The Constant form requires that the value simply be a numeric constant.

The Formula form requires that the value be a valid TRIM formula a described in the formula syntax.

The UnevenlyStepped form represents data that varies over time. This form consists of a series of (<date>, <time>, <value>) triplets. The date must be in the form MM/dd/yyyy. The time must be in the form hh:mm:ss Z where the hours run from 0-23 and the 'Z' stands for the three letter abbreviation for the time zone. The example above shows this syntax.

The InputFromFile form allows data to be read in from a file. To use this form, specify the full path to a data file followed by the column name of the variable in the file followed by the data delimiter used in the file, in double-wuotes. These must be separated by a comma.

To specify multiple values for different chemicals in a property, simple use the "Value:" keyword multiple times with the chemical name in curly braces {<chemical>}.

Compartment: Fish in Walden Pond
   Property: UptakeRate
      Value: {benzene} 7.0E-3
      Value: {toluene} 5.0E-2
      Value: {anthracene} 10.0E-2

To specify multiple values for in different forms, use the "Form:" keyword to specify the form of the value and the "Value:" to specify the values for each chemical.

Compartment: Fish in Walden Pond
   Property: UptakeRate
       Form: Formula
      Value: {benzene} (Temperature * BenzeneConcentration)^(0.33)
       Form: Constant
      Value: {toluene} 5.0E-2
       Form: UnevenlyStepped
      Value: {anthracene} (07/01/1991, 00:00:00 EST, 6.0E-1),(07/02/1991, 00:00:00 EST, 10.0E-1)

Adding a Link

A Link is added by using the keyword "NewLink:" followed by the name of the new link. This is followed by the required keyword "ReceivingCompartment:" with the name of a valid compartment and the required keyword "SendingCompartment:" and another valid compartment. You may optionally specify a reciprocal link with the "ReciprocalLink:" keyword followed by the name of a link which either exists in the scenario or will be created for you. If the link has already been created, it will be associated with that link. If not, then a new link will be created that will use the same algorithms as the current link. If you wish to create a reciprocal link that uses different algorithms than the current link, then you must create two links, with two spearate lists of algorithms and then link them with the ReciprocalLink keyword.

The Algorithms to use in this Link can be specified in several ways. The default behavior if this keyword is not used is to use the default Algorithms for this type of Link.

NewLink:
SendingCompartment: Pond Water - default in Walden Pond
ReceivingCompartment: Air - default in Walden Pond

To specify an Algorithm, use the "Algorithm:" keyword followed by the name of the Algorithm. If you would like to use the default algorithms in addition to other ones, then you can use the keyword "Default" after the Algorithm keyword and then specify each additional Algorithm on a separate line.

NewLink:
SendingCompartment: Pond Water - default in Walden Pond
ReceivingCompartment: Air - default in Walden Pond
Algorithm: Default
Algorithm: AirToWaterExchange
Algorithm: Evaporation

If you would not like to use the default Algorithms, but use ones that you specify instead, then do not use the "Default" keyword, but specify only the Algorithms that you would like to use.

NewLink:
SendingCompartment: Pond Water - default in Walden Pond
ReceivingCompartment: Air - default in Walden Pond
ReciprocalLink: Air - default in Walden Pond to Pond Water - default in Walden Pond
Algorithm: AirToWaterExchange
Algorithm: Evaporation

NewLink:
SendingCompartment: Air - default in Walden Pond
ReceivingCompartment: Pond Water - default in Walden Pond
ReciprocalLink: Pond Water - default in Walden Pond to Air - default in Walden Pond
Algorithm: AirToWaterExchange
Algorithm: Condensation

Sample Run Importer File

/* Sample Run Importer File. The properties and examples may not make any
scientific sense what so ever. */

Version: 1
Scenario: abiotic
NumberOfRuns: 4

// Set these properties for all runs in this file.
Scenario: abiotic
Property: simulationBeginDateTime
   Value: 07/01/1991 00:00:00 EST
Property: simulationEndDateTime
   Value: 07/10/1991 00:00:00 EST
Property: Rain
   Value: 0.05
Link: Root Zone - Forest in Root Zone - Hampden to Vadose Zone - default in Vadose - Hampden
Property: fractionOfErosion
   Value: 0.65

// First run
Run: Raise background concentration
Compartment: Groundwater - default in Groundwater - Hampden
   Property: BackgroundConcentration_DomainSpecificUnits
      Value: {Divalent Mercury}1.0E-6
      Value: {Elemental Mercury}1.0E-10
      Value: {MethylMercury}2.0E-8
// Setting properties for multiple compartments to the same value
Compartment: Vadose Zone - default in Vadose - Hampden
Compartment: Root Zone - Forest in Root Zone - Hampden
Compartment: Surface Soil - Forest in Surface Soil - Hampden
   Property: BackgroundConcentration_DomainSpecifiUnits
      Value: {Divalent Mercury}2.0E-6
      Value: {Elemental Mercury}2.0E-10
      Value: {MethylMercury}4.0E-8

// Second run
Run: Read in data from a file
Source: Example Facility
Property: emissionRate
    Form: InputFromFile
   Value: c:\\TRIM\\data\\run1\\Emissions1991.txt, Emission
VolumeElement: Lower Air
     Property: top
         Form: InputFromFile
        Value: c:\\TRIM\\data\\run1\\VETop.txt, East, ","

// Third Run
Run: Set Properties in different forms
Compartment: Vadose Zone - default in Vadose - Pond Drainage
   Property: D_effective
       Form: Formula
      Value: {Divalent Mercury}[[ currentChemical.Z_purewater /compartment.Chemical.Z_total *
             currentChemical.D_PureWater * compartment.theta ** (10 / 3) / compartment.phi ** 2 +
             currentChemical.Z_pureair /compartment.Chemical.Z_total * currentChemical.D_pureair *
             compartment.epsilon ** (10 / 3) / compartment.phi ** 2 ]]
       From: UnevenlyStepped
      Value: {Elemental Mercury} [[ (07/01/1991 0:00:00 EST 0.5E-5), (07/01/1991 0:12:00 EST 1.0E-5),
             (07/02/1991 0:00:00 EST 2.0E-5), (07/02/1991 0:12:00 EST 4.0E-5) ]]

// Fourth Run
Run: Create new links
NewLink:
SendingCompartment: Groundwater - default in Groundwater - Hampden
ReceivingCompartment: Surface Soil - Forest in Root Zone - Hampden
      ReciprocalLink: [[ Surface Soil - Forest in Root Zone - Hampden to
                      Groundwater - default in Groundwater - Hampden ]]
           Algorithm: DiffusionThroughWetSoil
NewLink:
SendingCompertment: Surface Soil - Forest in Root Zone - Hampden
ReceivingCompartment: Groundwater - default in Groundwater - Hampden
      ReciprocalLink: [[ Groundwater - default in Groundwater - Hampden to
                      Surface Soil - Forest in Root Zone - Hampden ]]
           Algorithm: DiffusionThroughWetSoil

File Version: $Date: 2003/03/07 14:41 $