Object Importer
Purpose
The Object Importer reads a textual description of property types, compartments,
algorithms, chemicals, sources, and composite compartments and creates
objects in a library. Volume elements are imported by a different importer.
File Syntax
The example below illustrates the file's syntax.
It might be helpful to examine the example while reading the description
of the syntax.
The first noncomment line in the file must specify the file format version
as "Version: <version #>" (without the quotes). The current version
number is 1.
Objects are described by pairs of keywords and values. Examples
of keywords include "Compartment:" and "Property:". Values can be specified
in two ways. Values that do not span lines can simply appear after
the colon. All white space between the colon and the value and between
the value and the end of the line will be discarded. For values that
span multiple lines, the value must be preceded by "[[" and followed
by "]]". Embedded new line characters and adjacent white space are
converted to one space. To include a carriage return in the value
use "\n". Use "\\" to insert a backslash into a multiline value.
The case of keywords is ignored, but the case of values is retained.
The start of a new object is represented by an initial keyword that
identifies the type of object to create. The initial keyword is followed
by the name of the object. There are restrictions on the forms of names
for property types. The lines following the initial keyword's line contain
additional keywords and values that describe the new object. The following
table describes the keywords that are accepted for different types of objects.
Follow the link for a keyword to see its meaning and appropriate values.
Properties can be specified for all types of objects except Property Types
with the "Property" keyword. The table shows TRIM-defined required and
optional properties for each type of object. Follow the link for each property
to see its description.
It's important to understand the relationship between properties and
property types. A property could be considered to be a variable
that describes an object (except property types do not have properties). For
instance, the temperature of a compartment or volume element would be
stored as a property. A property type determines what type of information
is contained in a property, but it does not determine the value of a property.
This is analogous to a declaration of a variable in some programming languages.
For instance, a temperature property type would indicate that temperature is
a floating point value. Each property is based on a property type. Corresponding
properties and property types have the same name.
Two forms of comments are supported. A "//" indicates that all text
until the end-of-line is a comment. A "/*" indicates that all text up to
and including a "*/" is a comment. This type of comment can span multiple
lines. However, it cannot be embedded in other values. It must start on
it's own line. Blank lines can be included between keywords.
Non-Initial Keywords
-
Category
-
A property type's category helps define the objects for which the property
type could be used. For instance, a property type with category "Air" will
apply to compartments with categories "Air" and "Air | Boundary Layer".
If no category is specified, "All" is assumed.
-
Class
-
A property type's class helps define the objects for which the property
type could be used. If it is not specified, the property type applies to
all types of objects. Valid values for class are Algorithm, Chemical, Compartment,
CCompartment, PointSource, Project, Scenario, and VolumeElement.
-
Component
-
This specifies the name of a compartment that should be included in the
composite compartment. Each compartment must be defined earlier in the
file or in the library. This keyword is specified once for each compartment
that belongs to the composite.
-
DataType
-
This specifies the type of information that a property provides, such as
a text string. In many cases this will be the type of information that
is stored in the property. Floating-point values can also be expressed
in other forms, such as a formula that returns a floating-point value.
Valid data types are Boolean, Category, DateTime, FloatingPoint, Integer,
and String.
-
DefaultValue
-
When a default value is specified for a property type, each new property
of that type will be created with its value set to the default value.
-
Description
-
This is a textual description of an object. The description of the property
type describes the purpose of the property, such as "the rate of uptake"
and any guidelines that should be used in setting values. Users can see
the first part of a property type description as a tooltip while entering
property values in TRIM. The description should be entered before any
Properties.
-
Max
-
If a maximum value is specified for a numeric property type, the user is
warned when he or she enters a new property value that exceeds the maximum.
-
Min
-
If a minimum value is specified for a numeric property type, the user is
warned when he or she enters a new property value that exceeds the minimum.
-
Property
-
A property specifies an attribute of an object. Note that property types
do not have properties. The value for this keyword is a property name,
which must match the name of an existing property type. These names are
not case sensitive. Properties are described in more detail in the
next section.
-
Units
-
Each floating-point or integer property type must declare which units will
be used, such as "K" or "g/s". If the property type describes a unitless
value, such as the number of organisms, use "N/A" as the units.
Properties
All objects except property types are described by properties. Each property
is defined by a property type. TRIM declares some property types, which
are listed in the table above. The user can create additional property
types. Each property contains several pieces of information. Required properties
do not have to be set when the object is imported, but they must be set
before a simulation can be performed.
Properties are described by a special set of keywords, which must be
in the following order (optional keywords can be omitted).
-
Form
-
This indicates how the property value is represented. This keyword is optional.
The default form is Constant, which is a value that does not change during
the simulation. The only other form currently recognized by this importer
is Formula, which is a formula that returns a floating-point value. If no
form is entered for a given property, the last form entered will be used.
This allows constants and formulas to be grouped together without having
to specify the form for each property. For example, if you specify that a
property is a formula, then all properties that follow it in that Object
will be treated as formulas until a constant form is specified.
-
Value
-
This is the value of a property. Currently, this must be a constant value
or a formula.
Boolean values should be specified as "true" or "false" without
the quotes. Categories are specified as text separated by "|" characters.
Text after the vertical bar represent a specialization of preceding information.
Use "All" (without the quotes) when an object applies to everything. The syntax for
dates is "MM/dd/yyyy HH:mm:ss ZZZ" (without the quotes) where "ZZZ" is
a three-character time zone. The syntax for formula values is described
elsewhere.
Some property values are chemical-specific. For instance, an organism
might uptake different chemicals at different rates. Chemical-specific
values can be specified by preceding the value with the chemical name in
curly braces (e.g., {HgO}). This keyword can be specified multiple times
for a single property if different chemical names are specified.
-
Description
-
An optional description of the property's value. The description of the
property type describes the purpose of the property, such as "the rate
of uptake" and any guidelines that should be used in setting values. The
description of an individual property is intended to describe the particular
value assigned to the property, such as "From Smith & Jones (1997)".C
TRIM's predefined property types are the following (data types are indicated
in parentheses):
-
AcceptableAbiotic
-
This is the category of abiotic compartments to which this compartment
can be added. For instance, the value for a fish compartment might be "Surface
Water" (without the quotes). (category)
-
boundaryContribution
-
This specifies a value for contribution from the boundary in g/day.
If the scenario's boundaryContributionEnabled flag is 'true' and a compartment
on the border of the simulation domain has this property, this property's value
is the boundary contribution to the compartment.
-
Category
-
This specifies an object's category. Do not use "All". For algorithms this
should only be specified when there a multiple interchangeable algorithms
that should not be used together, such as different implementations of
chemical uptake. No two algorithms on a link can have the same category.
(category)
-
ChemicalCategory
-
For algorithms that do not transform chemicals, the category of chemical
to which the algorithm applies. If not specified, "All" is used. (category)
-
CompartmentRelationship
-
For algorithms that only apply when the compartments have a specific
relationship with one another. Allowable values are:
- ANY - applies regardless of relationship between compartments
- SAME - algorithm applies within the same compartment only
- SENDER_ABOVE - algorithm applies when sender is above receiver
- SENDER_BELOW - algorithm applies when sender is below receiver
- NEXT_TO - algorithm applies when reciever is (horizontally) next to sender
- IN_SAME_VOLUME_ELEMENT - algorithm applies when reciever & sender are
in the same volume element
- IN_SAME_COMPOSITE - algorithm applies when receiver & sender are in
the same composite compartment
- ABOVE_OR_BELOW - algorithm applies when receiver is above or below sender
- ADJACENT - algorithm applies when sender is above, below, or next to sender
-
DoesTransformChemical
-
This indicates if the algorithm transforms chemicals. (boolean)
-
DoesTransportChemical
-
This indicates if the algorithm transports chemicals between compartments.
(boolean)
-
Elevation
-
This is the effective elevation of the emissions point source in meters.
This would typically include the height of the stack above the zero
elevation level for the simulation and any bouyant rise of the plume.
-
EmissionRate
-
The chemical-specific emission rate in grams/day.
-
Enabled
-
This indicates if an object is enabled for the simulation. For instance,
chemicals and algorithms can be disabled. (boolean)
-
initialConcentration_g_per_kg
-
The initial concentration of a chemical in a compartment in grams/kg.
-
initialConcentration_g_per_L
-
The initial concentration of a chemical in a compartment in grams/liter.
-
initialConcentration_g_per_m3
-
The initial concentration of a chemical in a compartment in grams/cubic meter.
-
IsBiotic
-
This indicates if the compartment is biotic. (boolean)
-
IsDefaultForCategory
-
If multiple algorithms with the same category apply to a link, this indicates
if this algorithm should be the one that is used. (boolean)
-
Mate
-
The name of the algorithm that should be used on reciprocal links. (string)
-
ReceivingChemicalName
-
For algorithms that transform chemicals, the name of the chemical on the
receiving side of the link (i.e., the reactant). (string)
-
ReceivingCompartmentCategory
-
The category of compartment that this algorithm can accommodate on the
receiving (upstream) side of a link. (category)
-
SendingChemicalName
-
For algorithms that transform chemicals, the name of the chemical on the
sending side of the link (i.e., the reaction product). (string)
-
SendingCompartmentCategory
-
The category of compartment that this algorithm can accommodate on the
sending (downstream) side of a link. (category)
-
totalMass
-
The total mass of this compartment (e.g, the mass of fish represented by
the compartment) in kilograms.
-
TransferFactor
-
This is the transfer factor for an algorithm. It is almost always expressed
as a formula. (floating-point)
-
X
-
This is the X-location of the point source within the modeling domain (in meters).
-
Y
-
This is the Y-location of the point source within the modeling domain (in meters).
Example
/*
* This is an example file that illustrates the syntax
* for the Object Importer. Different formatting styles are
* used to illustrate available options. This example has no
* scientific validity.
*/
Version: 1
//
// Define a property type.
//
// Note that case is ignored for keywords.
ptype: FOC
DESCRIPTION: [[The fraction of carbon in soil.\n\n
The value should be between 0 and 1.]] // a multi-line value
DataType: floatingPoint
Units: N/A
Category: Soil
Class: Compartment
Max: 1
Min: 0
ptype: Temperature
description: The temperature of a compartment.
DataType: floatingPoint
Units: K
Class: Compartment
Max: 350
Min: 200
ptype: EliminationRate // leading and trailing white space is ignored
Description: The rate an organism eliminates a chemical.
DataType: floatingPoint
Units: g/hr
Category: Biotic
Class: Compartment
//
// Define a skeletal chemical
Chemical: HgO
//
// Define some compartments
compartment: Trout
Property: Category
Value: Biotic | fish | trout
Property: IsBiotic
Value: true
Property: EliminationRate
Form: Formula
Value: {HgO} [[Compartment.Temperature *
0.005]]
Description: [[ Smith & Jones (1997) report that the elimination
rate is temperature dependent. ]] // Only one space will appear between "elimination" and "rate"
Compartment: Algae
Property: Category
Value: Biotic | Algae
Property: IsBiotic
Value: true
//
// Define a composite compartment
CCompartment: Surface water food web
Component: Trout
Component: Algae
//
// Define an algorithm
Algorithm: Uptake by Trout
Property: DoesTransformChemical
Value: false
Property: DoesTransportChemical
Value: true
Property: IsDefaultForChemical
Value: false
Property: ReceivingCompartmentCategory
Value: Biotic | fish | trout
Property: SendingCompartmentCategory
Value: Biotic | Algae
Property: TransferFactor
Form: Formula
Value: PrimaryAbioticCompartment.Temperature * 0.001
File Version: $Date: 2000/01/20 17:12:03 $