TRIM.FaTE Computer Framework Guide (Ver. 3.6)

Table of Contents

** New Features in Version 3.6 **

** New Features in Version 3.5 **

** New Features in Version 3.4 **

** New Features in Version 3.3 **

 

1. Introduction

2. Basic Concepts

3. Installing TRIM.FaTE

4. Using TRIM.FaTE

  4.1 Common Problems in Getting Started

  4.2 Main Window

  4.3 Library Window

  4.4 Property Editor

  4.5 Object Window

  4.6 Property Type Window

  4.7 Composite Compartment Window

  4.8 Project Window

5. TRIM.FaTE Simulations

  5.1 FaTE Scenario Window

5.1.1 Scenario View

5.1.2 Sources View

5.1.3 Chemicals View

5.1.4 Compartments View

5.1.5 Links View

5.1.6 Algorithms View

5.1.7 Analyses View

  5.2 Steps to Setup a New TRIM.FaTE Scenario

  5.3 Select Dialog Window

  5.4 Outputs from TRIM.FaTE

  5.5 Additional Information about TRIM.FaTE Simulations

5.5.1 Specifying boundary conditions

5.5.2 Specifying output concentration units

5.5.3 Reporting one Chemical as another
5.5.4 Specifying initial concentrations
5.5.5 Specifying fixed compartment concentrations
5.5.6 Specifying compartment abbreviations
5.5.7 Specifying source emissions rates
5.5.8 Specifying output file names and directories

5.5.9 Running simulations in batch mode with command line options
5.5.10 Specifying map projection
5.5.11 Setting up a steady-state simulation
5.5.12 Other notes

  5.6 Examining the relationships between Compartments

  5.7 Processing and Viewing TRIM.FaTE Results

  5.8 Performing a Sequence of Simulation Runs

  5.9 Performing a Sensitivity Analysis

5.9.1 Selecting properties to be varied

5.9.2 Varying property values for the analysis

5.9.3 Executing the sensitivity analysis runs
5.9.4 Performing sensitivity calculations
5.9.5 Sensitivity analysis results

  5.10 Performing a Monte Carlo Analysis

5.10.1 Selecting properties to be varied

5.10.2 Specifying property value distributions and output directory

5.10.3 Configuring and executing the Monte Carlo runs
5.10.4 Collating Monte Carlo analysis results

  5.11 TRIM.FaTE Utility Programs

6. Tips and Troubleshooting

  6.1 Known Bugs

  6.2 Enhancement Wish List

  6.3 Submitting Bugs & Requests

  6.4 Revision History and New Features

7. References and Related Documents

1. Introduction

This is a guide to the TRIM.FaTE Computer Framework.  This document is accessible in the doc subdirectory of the TRIM installation directory under the file name user_guide.html. Background and other information about TRIM.FaTE and the TRIM project as a whole can be found in the following documents:

• USEPA. 2002. "Total Risk Integrated Methodology. TRIM.FaTE Technical Support Document. Volume I: Description of Module." Office of Air Quality Planning and Standards, Research Triangle Park, NC.

• USEPA. 2002. "Total Risk Integrated Methodology. TRIM.FaTE Technical Support Document. Volume II: Description of Chemical Transport and Transformation Algorithms." Office of Air Quality, Planning and Standards, Research Triangle Park, NC.

2. Basic Concepts

Exceptions: Exceptions are errors that are detected when a program is executing. In TRIM.FaTE, exceptions are used to notify you of problems. Exceptions are often presented to you with a dialog box that shows the name of the exception and the message that was passed with it. The name is sometimes preceded by a Java package, such as java.io.IOException, or gov.epa.trim.util.TRIMException.

Object: A general term that refers to items created and used by TRIM.FaTE. Examples include: Volume Elements, Chemicals, Compartments, Links, Algorithms, Sources, Property Types, Sinks, and Scenarios.

Library: A repository for different types of objects that can be drawn upon for use in modeling scenarios. Libraries and their contents can be saved to disk. The following types of objects are stored in libraries: Algorithms, Chemicals, Compartments, Composite Compartments, Sources, and Property Types.

Project: Contains a collection of modeling scenarios and references a set of libraries whose objects can be used by the scenarios. Projects and their contents can be saved to disk.

Scenario: A configuration for a simulation that includes properties such as the starting date/time, ending date/time, and all the information that constitutes the outdoor environment.

Outdoor Environment: The environment that is used for a simulation. This includes the volume elements used, their compartments, links, and algorithms; and the chemicals, sources, and sinks used.

Property: Objects have properties that store information about the objects in the system. Examples of properties for a chemical include melting point, vapor pressure, and molecular weight; examples of properties for an algorithm include the receiving compartment type, sending compartment type, and whether it transforms a chemical. Each property references a property type that defines the name of the property, the type of data (e.g., real number, date and time, true or false), a default value, a description, and for numeric data types the recommended minimum and maximum values and the units. Objects have some properties that are always present (mandatory) and others that are optional. For more information on mandatory and optional properties for each type of object, see the Object Importer Specification.

Property Type: Each property has a single property type that defines the name, type of data, units, default value, and minimum and maximum values for the property. The available types of data are: real number, integer, date and time, true or false, text, and category.

Category: A hierarchical classification for objects ordered from most general to most specific, with each level separated by a vertical bar ("|"). For example, a chemical might have a category of "metal" or "organic | aldehyde"; a biological organism might have a category of "bird" or "mammal | rodent". There is an implicit category called "All" that all other categories are more specific than. This is useful in cases where a category is used to specify which objects are applicable for a certain purpose. For example, if "All" is the value of the acceptableAbiotic property for a compartment, then the compartment can be attached to a volume element with any type of abiotic compartment, or if "All" is the value of the chemicalCategory property for an algorithm, it means the algorithm is applicable to all chemicals.

Form: A property that stores data of type Real Number can come in several different "forms", such as "Constant Real Number" (a singular value), "Unevenly Time Stepped Real Number" (a sequence of real values with associated dates and times), or Formula Real Number (a mathematical formula that can include references to other properties in this or other objects).

Composite Compartment: A composite compartment is a compartment that is made up of other compartments. For example, leaves, a stem, and roots may comprise a plant.

3. Installing TRIM.FaTE

To use TRIM.FaTE, your PC should be equipped with at least:

• 256MB of RAM; and
• 400 MHz or faster processor.

PCs with lesser configurations will also work, but performance (e.g., model run time) will be less than optimal.

Software Requirements

TRIM.FaTE is compatible with the following computer operating systems:

• Windows XP
• Windows 2000
• Windows NT
• Windows 95/98

However, Windows XP, Windows 2000, and Windows NT are the recommended operating systems for running TRIM.FaTE because they best meet the memory requirements of the model.  Because TRIM.FaTE was developed using Java, it can be run under a number of other operating systems, such as Linux and Solaris; however, TRIM.FaTE has not been fully implemented or tested in any non-Windows-based operating systems to date.

Important Note: If installing TRIM.FaTE on a computer using the Windows XP, Windows 2000, or Windows NT operating system, the user must be logged onto the computer as an "Administrator" to complete the installation process.  If it is not clear how to do this, contact the person(s) in charge of maintaining software on your computer.

FaTE is now installed as part of the larger TRIM system. For the latest installation instructions, please see those available from the TRIM Installation page under the web site http://www.epa.gov/ttn/fera. The instructions may also be available from your local TRIM installation at ../install.html.

4. Using TRIM.FaTE

Once the TRIM.FaTE installation is complete, the system is ready to run.  TRIM.FaTE is started by running the trimjava.bat file, as described below.

• From the bat directory, double-click on trimjava.bat in Windows Explorer.  or choose TRIM->Run FaTE from the programs menu.

After starting TRIM, the user should set the user and system paths, as described below.

• Select "Preferences" from the File menu of the main TRIM.FaTE window (see Figure 2).
• Set the system path to the TRIM directory (e.g., C:\TRIM, C:\Models\TRIM).
• Set the user path to the directory in which your TRIM.FaTE data files will be stored (e.g., C:\TRIM).  By default, TRIM.FaTE looks for data files in the data subdirectory of the user path (e.g., C:\TRIM\data).
• If you wish to create databases with FaTE to use with TRIM.Risk-Eco, specify you MySQL username and password in the Database Setup section.

Figure 2.  Selecting Preferences

Note that the on-line Computer Framework Guide may not be available from the Help menu until TRIM.FaTE has been restarted after setting the preferences.

4.1  Common Problems in Getting Started

Several problems that have arisen in TRIM.FaTE test applications are listed in Table 1 along with solutions or suggested methods for circumventing the problem.  Note that this list is not meant to be comprehensive and focuses primarily on general problems related to navigation of the TRIM.FaTE software that users have encountered in test case applications.

Table 1.  Common TRIM.FaTE Problems and Suggested Solutions

4.2 Main Window

4.3 Library Window

Figure 3.  Library Window

From this window you can create new or examine existing objects. The window has three parts: the menu bar at the top, the object browser on the left, and the Property Editor on the right. The Property Editor is discussed in a later section. The functions of the object browser and menu bar are described in Table 3. The objects that currently exist in the library of the class specified by Contents are shown in a list below the Contents menu. The list will have scroll bars if needed. You can select objects from this list (and from many other lists & tables in the system) in several ways:

• click once with the left mouse button to select a single object
• to select a continuous set of objects, select the first object as above then scroll to the last object to be selected and hold down the Shift key while single clicking with the left mouse button
• to select a non-continuous range of objects, select the first object as above, then scroll to the next object to be selected and hold down the Control key while single clicking with the left mouse button; select the remaining objects as needed with the Control key depressed

If you need to change the relative sizes of the left and right sides of the Library Window, place the mouse pointer on the boundary between the left and right parts of the window so that a double arrow appears, then Click and drag the divider to the left or right. This type of graphical user interface (GUI) feature is called a "splitter". You can make one side or the other of the window totally disappear by putting the mouse pointer over one of the small arrows near the top of the splitter, and doing a single click with the left mouse button. Splitters are used in several parts of the TRIM.FaTE GUI.

4.4 Property Editor

The Property Editor has three parts: the label and button bar at the top, the property table in the center, and the Value Editor at the bottom. The Value Editor is used only for the special formula and time-stepped properties mentioned above; values for other types of properties are edited directly in the table. Note that there is a splitter between the property table and the Value Editor. The buttons for the Property Editor and Value Editor are described in Table 4.

The property table shows all the properties in the object(s) for which the Property Editor was created. For example, from the Library Window you can select multiple objects and then click the "Properties" button. This shows you the properties for all objects selected in the library's list in the Property Editor. Using the property table to edit multiple objects is very powerful because it allows you to add, delete, or modify properties for many objects simultaneously. The values for the properties are compared and if they are all the same, the actual value is shown in the Value column. If they are not all the same, "<Differ>" is shown as the value. If the property does not exist for all selected objects, "<Not in all>" is shown as the value. If a property is not in all selected objects and you want to put it in all selected objects, first delete the property, then add it back using the "New" button. The label at the top of the Property Editor indicates whether one or multiple objects are being edited by modifying the case of the object class and listing the names of multiple objects as space allows (e.g., "Properties for Algorithm a" vs. "Properties for 3 Algorithms a, b, c"). Some additional information about the property table follows:

• The property table shows information about the properties in the object(s) it is editing. This includes the property name, a chemical qualifier (if the property is specific to a chemical), its value, units (as applicable), the type of data stored (e.g., Real Number, True or False), and a description.

• Only the Value and the Description fields can be edited in the property table. If you edit the value or description, press Return when you are finished your edits to store your changes or press Escape to cancel them.

• The property description can be used to specify where a particular value was obtained, or to show other useful information.

• The description for the property's property type is shown as a "tool tip" (i.e., a floating bubble of text) when the cursor is placed over the property name. This description should give some information about what that type or property is used for.

• Data can be cut and pasted within the table (or elsewhere on your computer) using the standard method for your computer (e.g., for PCs use Ctrl-C to copy, Ctrl-X to cut, and Ctrl-V to paste).

• The columns in the property table can be resized by placing the mouse pointer between two column labels and by clicking and dragging it to one side or the other.

• The columns in the property table can be rearranged by placing the mouse pointer over the title for the column and then clicking and dragging the mouse to move the column to a new position.

• To create a property that varies over time, select a property with the data type "Real number", then click on "Form" and choose "Unevenly Time Stepped Real Number". Then you can use the Value Editor buttons described below, such as "Insert" to enter data by hand or "Import" to load data from a file (See Table 4 for more information on "Import").

# Level 1 Wind speed data from the National Weather Service
# DD/MM/YYYY Hour TimeZone Value (m/s)
01/1/1991      0    EST     6.826
01/2/1991      0    EST     5.993

4.5 Object Window

4.6 Property Type Window

New property types with the following names should not be created, as they are standard names with special meanings to the system: mass, moles, totalMass, initialConcentration_g_per_m3, initialConcentration_g_per_L, initialConcentration_g_per_kg, boundaryConcentration_g_per_m3, emissionRate, useSpecifiedConcentration, concentration_g_per_m3, concentration_g_per_L, concentration_g_per_kg, boundaryContribution.
 

4.7 Composite Compartment Window

4.8 Project Window

5. TRIM.FaTE Simulations

5.1 FaTE Scenario Window

When you select a scenario in a project and click the "FaTE..." button beneath the Scenarios list, a FaTE Scenario Window appears for the selected scenario. This window provides you access to many functions that must be performed before running a TRIM.FaTE simulation. The window consists of a menu bar and a set of tabbed views that allow you to define the properties of the scenario and its outdoor environment. There is a tab for the scenario and one tab each for the sources, chemicals, compartments, links, and algorithms that constitute the outdoor environment. The general procedure for populating the outdoor environment is to copy objects from libraries into the scenario's outdoor environment, and then customize the objects as needed. Before running a simulation, you should visit each of the tabbed views on the FaTE Scenario window to populate the scenario with sources, chemicals, compartments, links, and algorithms.  Table 7 describes the items accessible from the Scenario view and the menu of the FaTE Scenario Window and Table 8 describes the buttons accessible from the non-Scenario views.

Each of the tabbed views on the FaTE Scenario Window, except the Scenario and Analyses Tabs, has a Property Editor on the right side of the pane. There are two Properties buttons on each pane; the editor will show properties for the object(s) selected in the list or tree that is above the most recently clicked "Properties" button. On many of the tabbed panes, the volume elements, compartments, and links in the outdoor environment are displayed in an outline form that can be expanded and collapsed to display varying levels of detail using a tree. The panel on which the tree resides is called an "Outdoor Environment Panel". The buttons at the bottom of the panel vary depending on the purpose of the panel at a particular place in the GUI. Descriptions of the tabs, buttons, and menu items in the FaTE Scenario Window are provided in Sections 5.1.1 through 5.1.7.

After the properties for the scenario are set and the sources, chemicals, compartments, links, and algorithms are assigned to the outdoor environment, it is possible to run a simulation. The first time you run a simulation, you should select "Verify Scenario" from the Run menu in the FaTE Scenario Window to ensure that all information needed to run the simulation is available (e.g., that all properties needed by the simulation have values). A useful side-effect of the Verify is that any necessary properties found to be missing will be added and given their default values (provided that property types are available for them).

The Run Scenario menu item on the Run menu is used to start the simulation. You are prompted about whether to perform a Verify before running the simulation. Verify is recommended if you have added, removed, enabled, or disabled objects in the Outdoor Environment, or if you have added or removed properties or edited a formula for any objects in the Outdoor Environment. If you Run a simulation and it complains that properties are missing, try doing a Verify first.  After the simulation is performed, export the results by choosing Export from the File menu or by setting the export option in the Scenario view on the FaTE Scenario Window (discussed in detail in Section 5.1.1).

5.1.1 Scenario View

The Scenario View has a Property Editor on the right side of the pane. It allows you to change the properties of the scenario. To begin setting up your scenario, set any unset properties for the scenario (e.g., simulationBeginDateTime and simulationEndDateTime).   An example of the Scenario View is presented in Figure 4.  The scenario properties are described in Table 9.

Figure 4. FaTE Scenario Window, Scenario View

Aside from setting the scenario properties, you need to add volume elements to your scenario (if they are not already there). This can be done by selecting "Import Volume Elements" from the File menu. You are then prompted for a file from which to import the volume elements. The format for this file is described in the Volume Element Importer Specification. During the volume element import process, the primary abiotic compartments for the volume elements are also added to the scenario (e.g., air, surface water, surface soil).  NOTE: the abiotic compartments referenced in your volume elements file must be present in one of the libraries attached to the project. Be aware that volume element relationships (i.e., which volume elements are next to, above, or below other volume elements) cannot change over the course of the simulation. After the volume elements are imported, sinks are automatically created at the beginning of the simulation for the exposed faces of each volume element according to its properties (e.g., the top and bottom). The volume elements, compartments, chemicals, links, sources, and algorithms for the simulation can be edited from other tabs of the FaTE Scenario window.

5.1.2 Sources View

To add sources to your scenario, go to the Sources View, select sources in the libraries from the right hand list and click "<< Add". If the source you want isn't shown in the list, you must add it to one of the libraries attached to the project.  Refer to Table 8 for a description of any buttons on this view.  The special source properties that affect the behavior of TRIM.FaTE are presented in Table 10.

Table 10.  Source Properties

5.1.3 Chemicals View

To add chemicals to the scenario, follow a similar procedure to the sources, but use the Chemicals View. Refer to Table 8 for a description of any buttons on this view.  The special chemical properties that affect the behavior of TRIM.FaTE are presented in Table 11.

Table 11.  Chemical Properties

5.1.4 Compartments View

To add biotic and special abiotic compartments, use Smart Add (described below). 

• Smart Add will add biotic and non-primary abiotic compartments to volume elements based on the value of the acceptableAbiotic and category properties. For example, if a volume element's primary abiotic compartment has "Surface Water" as the value for its category property, and the compartment "Bass" has the value "Surface Water" for its acceptableAbiotic property, then the Bass compartment will be added to the volume element during a Smart Add. Note that the primary abiotic compartments are automatically added to the outdoor environment when the volume elements are imported, whereas biotic compartments can be manually added and deleted from the Compartments pane.

An example of the Compartment View is presented in Figure 5.  Refer to Table 8 for a description of any additional buttons on this view.  The special compartment properties that affect the behavior of TRIM.FaTE are presented in Table 12.

Figure 5. FaTE Scenario Window, Compartments View

Table 12.  Compartment Properties

5.1.5 Links View

To add most of the links to the scenario, use Smart Link (described below), but be careful to add any additional links with "<< Link >>".  Refer to Table 8 for a description of any additional buttons on this view.

• Smart Link will automatically create links between adjacent or collocated compartments for the selected volume elements. Links will be created if algorithms that connect their compartment types exist in the project's libraries. Smart Link makes decisions about which links to create based primarily on the "category" properties of the compartments and the receivingCompartmentCategory, sendingCompartmentCategory, and compartmentRelationship properties for the algorithms. Note that only compartments in the same or neighboring volume elements will be linked. For more information on the Smart Link process, see Information on Smart Linking. NOTE: Links between non-adjacent compartments must be created manually using the "<< Link >>" button. With "<<Link>>", the compartments selected in the right and left panels are each linked to each other and any algorithms that are appropriate are added to them. The algorithms that reside on the links can be viewed and added or removed manually from the Algorithms pane.

5.1.6 Algorithms View

Algorithms do not require a separate step, since they are added automatically to links. However, the algorithms and associated properties for each link can be viewed from this view using the Property Editor.  Refer to Table 8 for a description of any buttons on this view.  The special algorithm properties that affect the behavior of TRIM.FaTE are presented in Table 13.

Table 13.  Algorithm Properties

5.1.7 Analyses View

    The Analyses View contains the list of sensitivity and Monte Carlo analyses for the Scenario.  The dropdown menu at the top of the view allows the user to choose between Sensitivity and Monte Carlo analyses.  Within the window below the dropdown menu, the user can open an existing analysis ("Open" button), create a new analysis ("New" button), rename an analysis ("Rename" button), and delete an analysis ("Delete" button).  The user can also select the "Current" analysis using the "Current" button.  This button allows the user to indicate which analysis should be selected when adding properties for stochastic analysis.  Refer to Section 5.8 for a description of the Sensitivity Analysis tool and Section 5.9 for a description of the Monte Carlo Analysis tool.

5.2 Steps to Set up a New TRIM.FaTE Scenario

• If you have an existing scenario and want to make a new scenario that is similar, but you want to put it in a new project file, then open the existing project and choose "Save As" from the File menu. Now you can make changes to the new scenario. The changes will be made in the new project file and the old one will remain unchanged.
  
• If you want to create a new scenario that is similar to an existing scenario and keep it in the same project file, then open the project, select the existing scenario, and click on the "Duplicate" button under the "Scenarios" list. (Note that duplicating a scenario does not make a complete new copy. Duplicated scenarios share properties with the original scenario, but when the properties are changed they belong to the new scenario. This helps to save space when new scenarios are created.) Now you can make changes to the new scenario.  NOTE: Duplicating scenarios does not duplicate any Monte Carlo or sensitivity analyses associated with the existing scenario.
  
• If you are starting from scratch with a brand new project, follow the steps below to create your project (most of these steps are described in more detail in the following sections):

 
1. Choose "New Project" from the File menu on the TRIM.FaTE Main Window. Enter a name for the project and click "OK."  Then enter a name for the first scenario and click "OK."
    
2. Attach a library to your project by clicking the "Add" button under the "Libraries" list on the Project Window, selecting the library with the file browser, and clicking "Add Library to Project."  The library you attach should contain the sources, chemicals, compartments, and algorithms that you plan to use in the scenario(s).
    
3. Open the new scenario by double-clicking on it in the "Scenarios" list (or by selecting it with a single click then clicking on "FaTE...").
    
4. On the Scenario View, use the Property Editor to set all the scenario properties that have the value "<Unset>".  NOTE:  If you have previously run a scenario with the same name as the scenario you are editing, be sure you choose a different output directory (using the outputDir property) or you run the risk of writing over the results from previous runs.
    
5. Import volume elements to the scenario by selecting "Import Volume Elements..." from the File menu in the Fate Scenario Window.  Select a projection type from the "Available Projection Families" dropdown list.  Then select an ellipsoid from the "Ellipsoids" dropdown menu.  Optionally, you can specify a name for the map projection by typing a name in the box next to "Name:".  Then specify values for the parameters in the table (the exact list will depend on the selected projection type) and click "OK."  For more information on the different map projections options, refer to the discussion of map projections later in this guide.
    
6. Click on the Sources tab.  Select the source(s) you want to use from the "Sources in Libs" list and click "<< Add" to add them to the scenario.
    
7. Click on the Chemicals tab.   Select the chemical(s) you want to use from the "Chemicals in Libs" list and click "<< Add" to add them to the scenario.
    
8. Click on the Compartments tab. The volume elements and primary abiotic compartments should already be shown in the outdoor environment tree. To add biotic compartments and other abiotic compartments (e.g. flush rate sink), select the volume element(s) to which you want to add compartments from the Outdoor Environment list.  Next select the compartment(s) you want to add to the volume element from the "Compartments in Libs" list and click "<< Add" to add the selected compartments to the selected volume elements.  Alternatively, you can select all the volume elements to which you want to add compartments from the Outdoor Environment list, select the compartments you want to add to these volume elements from the "Compartments in Libs" list, and then click the "Smart Add" button.  This will add the selected compartments to the selected volume elements based on the types of volume elements (e.g., air volume elements, surface soil volume elements) the compartments are allowed to be added t.  Review the compartments in the outdoor environment to make sure all the compartments you want are there and there are not any extra ones.
    
9. Click on the Links tab. Select all the volume elements in the right hand outdoor environment tree. (e.g., Show only Volume Elements in the tree by selecting Volume Elements from the menu at the top of the tree. Then you can select the first volume element with a single click, then scroll down to the bottom and select the last volume element by clicking while holding down the shift key.) Now click the "Smart Link" button at the bottom of the second Outdoor Environment column from the left. This will add all the links that the system can determine should be made to the system. Note that the smart linking process may take several minutes. For more information on smart linking, see smart_linking.html.
    
10. Next, you should review the warning messages returned from the smart link process very carefully. It may be helpful to save them to a file when prompted to do so. These warnings will help identify places where you may need to add links manually and adjustments you need to make in algorithm properties. Also, it may be helpful to export the scenario to HTML using the "Export" item on the File menu of the FaTE Scenario Window. You should examine the compartments for their incoming and outgoing links and the Link Index for a list of all links.

If you find extra links, you can delete them from the Links or Algorithms View by selecting them in the tree and clicking "Delete". If you need to make additional links manually, from the Links View, select the compartments you want to link on the left-hand outdoor environment panel, then select the compartment(s) you want to link on the right-hand outdoor environment panel and click "<< Link >>". Links will be made between the compartments selected on either side in both directions, and any appropriate algorithms will be automatically added to the new links. After making the manual adjustments to the links, it may be useful to export to HTML again.
 

11. Define the erosion / runoff properties on the surface soil to surface soil and surface soil to surface water links. The link properties FractionOfTotalErosion and FractionOfTotalRunoff determine how erosion/runoff material in the sending compartment is distributed to the receiving compartments.  Provide values for these link properties for each of the surface soil to surface soil, surface soil to surface soil sink, and surface soil to surface water links.
     
12. Set any time-varying input parameters such as meteorological data and plant related properties (e.g., litterFallRate and leafAreaIndex for leaves and allowExchange for leaves, leaf particles, stems, and roots). If you need to set the same property for many objects, you can select all the objects from the outdoor environment tree (either manually or using the Select Dialog Window), and click the Properties button. Then any changes you make to properties will be made to all of the objects.

To define a time-varying property, select the property and click the "Form" button, then choose "Unevenly Time-Stepped Real Number" and click "OK."  The Value Editor will appear at the bottom of the Property Editor.  From the Value Editor you can either import the values from a file (e.g., for meteorological data) or enter them manually (e.g., for plant-related data that doesn't change very often). To import data from a file, click the "Import" button in the toolbar above the editor and select the file containing the data for the selected property using the File Browser that pops up.  The file must be in tab-delimited text format and must have data in the forms specified in the column headings (e.g., MM/DD/YYYY for date).  Once the file has been selected, click "Import."  When you are finished importing or entering the data manually, click "Store" to save the data with the property (otherwise your changes will be lost).

To define a time-varying property that is to be read in from a file (a format often used for meteorological data properties), select the property and click the "Form" button, then choose "Unevenly Time-Stepped Real Number From File" and click "OK.". An editor will appear at the bottom of the Property Editor.  Click the "Browse" button and use the File Browser that pop up to select the file that contains the data for the selected property.  The file must be in the format described in Unevenly Time-Stepped From File format.  Once the file has been selected, click "Open."  Enter the data delimiter of the file in the "Delimiter" box and click "Scan File". This will scan through the file and pick out the column names.   Select the column name that contains your data and click the "Store" button in the toolbar above the editor.
 

13. At this point it is useful to perform a Verify.  This is done by selecting "Verify" from the Run menu on the FaTE Scenario Window. This will add any properties that are needed but do not exist to the appropriate objects and will notify you of unset properties. Provide values for any unset properties. After setting the properties, click "Verify" again to make sure all properties are now set.

 
14. Save the project by selecting "Save Project" from the File menu of the FaTE Scenario Window.
     
15. Run the simulation by choosing "Run Scenario" from the Run menu.

5.3 Select Dialog Window

The Select Dialog Window that appears from an outdoor environment panel has the basic options listed above, additional options to specify the type of the object (Volume Element, Compartment, Composite Compartment, or Link), and a checkbox to specify whether the object was added using the Smart Add or Smart Link feature. The latter checkbox is useful when you want to select then delete objects that were added to the outdoor environment automatically (as opposed to manually). The Select Dialogs that appear from the outdoor environment panel on the Algorithms tabs allow you to specify the category and name for the sending and receiving compartments of links. Its use for selecting other types of objects is somewhat limited.

When you are finished specifying the selection criteria, click the "Select" button to select the objects or click the "Cancel" button to cancel the selection process.

5.4 Outputs from TRIM.FaTE

There are two types of general output from TRIM.FaTE: output data and export data.  The output data are the moles, mass, and concentration outputs for each modeled chemical and time-step.  These data reflect the results at the end of a time step (i.e., if a compartment has a specified concentration/mass that changes at the time of the output time step, the new value will not be shown until the following output time step).  The user has the following options for the output data:

• Mass Export - the mass results for each compartment at each output time step.  The Mass Export can be created using the "Export" command in the File menu of the FaTE Scenario Window or by setting the "exportMass" Property in the Scenario View to true.
• Concentration Export - the concentration results for each compartment at each output time step.  The Concentration Export can be created using the "Export" command in the File menu of the FaTE Scenario Window or by setting the "exportConcentration" Property in the Scenario View to true.
• Moles Export - the moles results for each compartment at each output time step.  The Mass Export is automatically created for each run, regardless of the value of the "exportMoles" property..

The export data contain information about the setup of a simulation, particularly the property values and relationships between compartments and volume elements.  There are a number of different ways to export the information contained in TRIM.FaTE libraries and scenarios.

The Library Export Options are:

• Object Export - a text file that contains all of the information in the library; can be edited in a text editor and re-imported into TRIM.FaTE.  The Object Export can be created using the "Export" command in the File menu of the FaTE Library Window.
• Property Export - a delimited text file (that can be read into Excel) that contains the complete list of properties (w/ corresponding values/formulas) in the library, i.e., the defaults for algorithm, chemical, compartment type and source properties coming into the project set-up.  The Property Export can be created using the "Export" command in the File menu of the FaTE Library Window.
• Property Type Export - a delimited text file (that can be read into Excel) that contains the complete list of property types in the library.  The Property Type Export can be created using the "Export" command in the File menu of the FaTE Library Window.

The Scenario Export Options are:

• HTML Export - a set of HTML files that contains a detailed description of a TRIM.FaTE scenario.  It can be created before or after running a simulation, although the export following a simulation contains information not contained in an export performed prior to a simulations.  This export is very useful in evaluating results because the user can see the values of formula properties and the transfer factors and fluxes between compartments.  The HTML Export can be created using the "Export" command in the File menu of the FaTE Scenario Window or by setting the "exportHTML" and "evaluateHTMLPropertiesAtTime" properties in the Scenario View.
• Link Export - a text file that contains a list of all of the links and their associated algorithms in a scenario.  The Link Export can be created using the "Export" command in the File menu of the FaTE Scenario Window.
• Outdoor Environment Export - a delimited text file (that can be read into Excel) that contains the list of volume elements, compartments and links defined for the project scenario, along with the algorithms associated with each link.  The Outdoor Environment Export can be created using the "Export" command in the File menu of the FaTE Scenario Window.
• Property Export - a delimited text file (that can be read into Excel) that contains the customization of the library for the scenario, including any geographic variation in property values/formulas across the scenario compartments. It also includes the link, scenario (e.g., start time and end time of run, export options), sink, and volume element properties that have been defined in the project scenario.  The Property Export can be created using the "Export" command in the File menu of the FaTE Scenario Window.

5.5 Additional Information about TRIM.FaTE Simulations

5.5.1  Specifying Boundary Conditions

Boundary conditions are used to account for the chemical mass that is transported into the system from outside the modeling domain.  Thus, they should only be added to compartments that are on the exterior of the modeling domain (i.e., they have at least one face that is not neighbored by any other volume element).  NOTE: The current version of the model only supports adding boundary conditions to air compartments.

To specify a boundary concentration, 

1. Add the property boundaryContribution to the compartment(s). The default value of this property is: 

   boundaryContribution(containingVolumeElement.chemical.boundaryConcentration_g_per_m3, containingVolumeElement.horizontalWindSpeed, containingVolumeElement.windDirection)

   Therefore, by default, the information regarding the boundary contribution is taken from the volume element in which the compartment resides.
   

2. Add the property boundaryConcentration_g_per_m3 for the appropriate chemical to the compartment's volume element and set it to the appropriate concentration.
   

5.5.2  Specifying Output Concentration Units

There are two properties in each compartment that affect the units in which the results are written to the concentration output file(s):

• concentrationOutputFactor
• concentrationOutputUnits

By default, the concentrationOutputFactor is set to 1.0 and the concentrationOutputUnits are set to the default concentration units for that compartment.  The default concentrations units for each type of compartment are:

• g/m3 for air, sediment, and soil (surface, root, and vadose) [calculated by dividing the chemical mass in the compartment by the volume of the volume element containing the compartment]; 
• g/L for surface water and ground water [calculated by dividing the chemical mass in the compartment by the volume of the volume element containing the compartment]; and 
• g/kg wet weight for biota [calculated by dividing the chemical mass in the compartment by the total wet weight of the compartment. 

However, the user may change this by inputting a factor (which may be a constant or a formula) and changing the name of the units to correspond with the units after the factor is applied.

For example, if the user wanted to write soil compartment concentration (default = g/m3 wet) as g/g dry weight, the user would:

1. Change the value of the concentrationOutputFactor property to the following formula:

   1.0 / (Comparment.rho * Compartment.VolumeFraction_Solid * 1000)

 
 
2. Set the concentrationOutputUnits property to "g/g dry weight"

The concentrations for the selected soil compartments would then be in "g/g dry weight".

The currently available TRIM.FaTE libraries use the default concentrationOutputFactor and concentrationOutputUnits for all compartments except the three soil compartments and the sediment compartment.  The soil and sediment compartments have modified with the appropriate factors to output concentrations in units of "g/g dry weight".

5.5.3 Reporting one Chemical as another in results files

There are times when the user may wish to report a simulated chemical as another. For example, risk analysts may wish to see the mass of Methyl Mercury reported as Mercury. To do this, you must add three properties to the chemical whose output you would like to change.

1. reportAsOtherChemical - This is the name of the other chemical that you would like to report this chemical as. This name will appear in the results file units. This might read "Hg" in the above example of Mercury.

2. reportingChemMW - This is the molecular weight in g/mol of the chemical that you would like to report as. This would be 201.0 in the case of Mercury.

3. molesOfReportingChemicalPerMoleOfThisChemical - This is the number of moles of the reporting chemical in the main chemical. In the case of Mercury in Methyl Mercury, this is 1.

5.5.4  Specifying Initial Concentrations

There are three primary properties used in specifying initial concentrations: initialConcentrion_[units], initialConcentration_[units]_UserSupplied, and FractionInitialConcentrations.  The property initialConcentrion_[units]_UserSupplied is a Compartment Property that contains the value for the initial concentration the user wants to use for a particular compartment.  The property FractionInitialConcentrations is a Scenario Property that specifies the fraction of initialConcentrion_[units]_UserSupplied that should be used in the simulation (e.g., 0 if the user did not want to include initial concentrations for a particular simulation, 1 if the user wanted to use all of the user-specified initial concentrations in a simulation).  The property initialConcentrion_[units] contains a formula that calculates the initial concentration that the model that will be used in the simulation by multiplying initialConcentrion_[units]_UserSupplied by FractionInitialConcentrations.

The details for setting up initial concentration are provided below.

1. Add one of the pairs of properties to the compartment(s) for the desired chemical(s):*
   • initialConcentration_g_per_m3 and initialConcentration_g_per_m3_UserSupplied (for all abiotic media except surface and ground water)**,
   • initialConcentration_g_per_L and initialConcentration_g_per_L_UserSupplied (for surface and ground water), or 
   • initialConcentration_g_per_kg and initialConcentration_g_per_kg_UserSupplied (for biota).
2. Input your initial concentrations for each chemical using the initialConcentration_[units]_UserSupplied property.
3. Set the initialConcentrations_[units] property to the appropriate formula (if the property was already added, it should be set to the correct formula):
   • containingScenario.FractionInitialConcentrations * compartment.Chemical.initialConcentration_g_per_m3_UserSupplied (for all abiotic media except surface and ground water)
   • containingScenario.FractionInitialConcentrations * compartment.Chemical.initialConcentration_g_per_L_UserSupplied (for surface and ground water), or
   • containingScenario.FractionInitialConcentrations * compartment.Chemical.initialConcentration_g_per_kg_UserSupplied (for biota).
4. OPTIONAL.  If you would like to scale the initial concentrations by a particular fraction, or turn them off all together, adjust the scenario property "FractionInitialConcentrations" accordingly.  The default value for the property is 1.0.  Some example uses of the property:
   • If you would like to turn off the initial concentrations, set FractionInitialConcentrations to 0.0.
   • If you would like to set the initial concentrations to 50% of their original values (as set in step (2)), set FractionInitialConcentrations to 0.5.
   • If you would like to use the initial concentrations as set in step (2), set FractionInitialConcentrations to 1.0.

* Be sure to check if the properties are already added for the compartment(s) in which you want to set initial concentrations.  In most cases, the properties should already be there.

** Although the initialConcentration units for soil and sediment are grams per m3, the output units for both media in the available libraries are grams per gram (dry weight).  The model will likely be modified in the future to allow the user to input initial concentrations in the same units as the output concentrations, but this functionality is not currently available. 

5.5.5  Specifying Fixed Compartment Concentrations

To specify that the concentration for a compartment remain fixed throughout the simulation:

1. Add the property useSpecifiedConcentration to the compartment(s) and set it to "true". This property should not have any Chemical associated with it (i.e., select "none" when prompted for chemical).
2. Add one of the following properties (with a Chemical) and set the value to the appropriate concentration level:
   • concentration_g_per_m3 (for all abiotic media except surface and ground water),
   • concentration_g_per_L (for surface and ground water), or 
   • concentration_g_per_kg (for biota). 

   If more than one of the concentration_[units] properties is added, they will all be ignored.

Note: If you want the value at the first time step to be the same as the fixed value, you must also specify the initial Concentration.

5.5.6  Specifying Compartment or Chemical Abbreviations

To specify an abbreviation for a Compartment or Chemical to be used in the results file, add a Property called abbreviation.

5.5.7  Specifying Source Emission Rates

Sources, when first created, do not have any properties for emissions because it is not possible to know which chemical(s) it should be emitting. So, prior to running a simulation, you should add an emissionRate property for each of the chemicals emitted by each source. Based on the location information given for the source, the system will determine the volume element to which the source emits.  If the emissionRate is constant, the "Form" of the property should be "Constant Real Number".  If the emissionRate varies with time, the "Form" of the property should be either "Unevenly Time Stepped Real Number" or "Unevenly Time Stepped Real Number from File".  If the emissionRate is a function, the "Form" of the property should be "Formula Real Number".

5.5.8 Specifying Output File Names and Directories

TRIM.FaTE creates output files using the name of the scenario, the names of the modeled chemicals, the type of output (moles, mass, or concentration), and a internally-generated ID (e.g., A0).  For example, the elemental mercury concentration file for a scenario named "TestCase" might be "TestCase_Elemental_Mercury_concA1.txt".  If multiple runs of the same scenario are performed during a single session (i.e., without closing the scenario or project), the model will name these files using different IDs, thus eliminating the potential for overwriting existing output files.  However, if multiple runs of a scenario are performed during separate sessions (i.e., closing the scenario between runs), the model could assign an ID that corresponds to the ID of an existing output file, and thus the user could accidentally overwrite existing output files.  To prevent this, the user should always check the output directory prior to performing a simulation to make sure there are no existing output files with the same scenario name in the output directory.  If there are, the user may be best served by changing the output directory of the current run (this is done by changing the outputDir property in the list of scenario properties under the Scenario View).

5.5.9  Running Simulations in Batch Mode with Command Line Options

You may start TRIM.FaTE with a set of command line options that allow you to run a specific FaTE Scenario. To use this feature:

• Add either "-run" or "-runthenexit" after the TRIM.FaTE startup command in the batch file you use to run TRIM.FaTE.  "-run" will open TRIM.FaTE, run the selected simulation, and leave TRIM.FaTE open after the simulation completes.  "-runthenexit" will open TRIM.FaTE, run the selected simulation, and then exit TRIM.FaTE.
• Add "-showGUI true[or false]" to specify whether to show the TRIM.FaTE GUI during the run.
• Add "-verify true [or false]" to specify whether to verify the scenario.
• Add "-prefs" and the name of a preferences file to specify the user preferences.
• Add "-project" and the name of the Project file that you wish to run. 
• Add "-fatescenario" and the name of the Scenario within the Project that you wish to run.
• Add "-propsfile" and the name of a property file to run a simulation overriding the selected properties in the scenario

Example:

    %JRE% -Xmx400m -classpath [.....] java gov.epa.trim.main.Main -run -showGUI true -project c:\TRIM\models\woodland.trp - fatescenario forest -propsfile FullMaine_properties.txt

NOTE: Currently, running in batch mode only works for deterministic simulations and not for Monte Carlo or sensitivity runs.

5.5.10  Specifying Map Projection

When importing the volume element file, you will be prompted to provide information about the map projection of the volume element layout.  There are four basic items that should be specified (in the following order):

1. Projection Family - The projection family is selected first from the drop-down menu labeled "Available Projection Families".  The current version of the model includes:
   • Lambert
   • Latitude-Longitude, and 
   • Universal Transverse Mercator (UTM).
 
2. Ellipsoid - The ellipsoid is selected next from the drop-down menu labeled "Ellipsoids".  The current version of the model includes:
   • Sphere
   • WGS 1994
   • Clarke 1880
   • International 1909
   • SGS 1985
   • GRS 1967
   • GRS 1980
   • WGS 1960
   • WGS 1966
   • WGS 1972
    
3. Name - This is an optional items that can be filled in by the user to name the projection.
    
4. Parameters - The parameter values that must be completed depend on the selected projection family.  For Lambert projections, the user must specify:
   • Secant Latitude South
   • Secant Latitude North
   • Central Longitude
   • Central Latitude

   For Latitude-Longitude projections, the user must specify Central Longitude.

   For UTM projections, the user must specify the UTM Zone.

5.5.11  Setting Up a Steady-state Simulation

TRIM.FaTE can be run in two modes: dynamic and steady-state.  For a dynamic run, you should simply follow the instructions provided in Section 5.2, using whatever input data you determine is appropriate, and making sure that the Scenario Property "simulateSteadyState" is set to "false".  Performing a steady-state run is identical, except for the following:

• Set the Scenario Property "simulateSteadyState" to "true".
• No time-varying data (e.g., meteorological data) can be included in the steady-state simulation.  If you are setting up a steady-state simulation from a dynamic simulation, you should replace all of the time-varying data with constants (possibly averages of the time-varying data for some properties).
• All links FROM groundwater compartments must be disabled by setting the "enabled" property to "false".  This step is required because the transfers from ground water are so slow that they act as virtual sinks and prevent the solver from finding a steady-state solution.

5.5.12  Other Notes

• In some cases, using time keywords in formulas (e.g., time.hour) can slow down the simulation. For instance, using the hour will force calculations to be performed for each hour in the day, whereas they might actually otherwise need to be calculated only once per day or even less frequently.
 
• When adding a new chemical, be sure to set the doesTransform property to the appropriate value.  For example, doesTransform would be set to "true" for elemental mercury and "false" for benzo(a)pyrene.

5.6 Examining the food chain relationships between Compartments

The various tree views can be used to view which Compartments are contained in which Volume Element and which links go into and out of which Compartment. But it may be easier to view some relationships graphically. 

If you want to view the diet of a certain animal (this only applies to biotic Compartments) select the Compartment on the Compartments View and go to the View menu and select Food Chain.  This will bring up a window that will display the food chain leading to that Compartment with the percentage diet on each link. An arrow is drawn if there is a Link between two Compartments and there is an active algorithm on that Link. The value that is placed on the link is related to a Property in the predator that starts with "fractiondiet" and ends with the name of the prey.  An example of the food chain window is provided in Figure 6.

Figure 6. Food Chain

You can associate images with certain Compartments to make the food chain easier to view. To do this, add a Property called "image" to each Compartment and set it's value to be the path to an image file that matches the Compartment.

5.7 Processing and Viewing TRIM.FaTE results

After completing a simulation, you can view the results in several ways. TRIM.FaTE contains a text file viewer as well as a graphical display of the results. Note that for large simulations with a large number of Compartments or a large number of time steps, it may be best to average the results before attempting to view them.

If your Compartment names are very long and you would like to use an abbreviation, you can add a Property called "abbreviation" that will use the abbreviation as the column name in the results files.

To view the results in a table, go to the View menu and select Run Results. This will present a window that will allow you to choose the Chemical and the units that you wish to view. You may also choose between the Basic Viewer and the Analysis Engine table viewer. Note that the analysis engine table has been under active development through 2006, but the basic viewer has not been updated since 2003. Make your selections and then press OK.  This will bring up a results file for the last TRIM.FaTE simulation that you performed (you must have performed at least one simulation to view results.) To view the results from an earlier run, you can press the Browse button and select the file yourself. This will bring the file into a tool called JART (Java Analysis and Reporting Tool). It contains many sorting and filtering options to allow you to analyze and organize your output results. This tool is documented here.

After completing a simulation, you may also view the results graphically from a "bird's eye" view. Click the Analysis Tab and press the Show Results button. This will bring up a file browser. Select the results file that you wish to view and press Open. Note: you can only view simulation results for the currently open FaTE Scenario.  An example of the Graphical Results Viewer is provided in Figure 7.

Figure 7. Graphical TRIM.FaTE Results

On the left is a view of the Volume Elements looking down from above. If a Compartment is displayed, you will be able to see it's concentration based on the color legend on the right.  The type of Compartment that is displayed is selected in the Compartments list in the middle of the screen.  The legend for the colors and values is displayed on the right and the time step is displayed below the plot. The units of the currently displayed Compartment are displayed above the legend.

The Compartments in TRIM.FaTE are laid out in Volume Element at different levels. It would not be easy to view two Compartments that were in Volume Elements that are on top of each other. In order to prevent this type of conflict, you can only view Compartments that are in one type of Volume Element at a time. Within those Volume Elements, you can view one type of Compartment that they contain at a time. In the above picture, the "Surface Water" Volume Elements are selected. There are two of these and they are represented by the red and orange polygons in the display. The Compartments list is filled with the types of Compartments that are found in the Surface Water Volume Element and the values for the Common Loon are currently being viewed.  To view Compartment in a different type of Volume Element (Air, Groundwater, Surface Soil...), select a different value from the Volume Element Types list and select the Compartment type that you wish to view from the Compartments list. To print out the current plot, you can press the print button (with the printer icon) to the upper left of the plot. You can also use the magnifying glasses to zoom in and out.  If you would like to see the Lat/Lon and X/Y coordinates of certain points in the plot, check the Location check box and move your mouse to the point. The values will be displayed next to the check box.

 The legend for the colors and values is on the right hand side. When you select a new Compartment, TRIM.FaTE will automatically rescale the legend based on the minimum and maximum values for the Compartment that you are viewing. The scale can be set to linear or logarithmic by selecting the Linear or Log radio buttons below the list of values. At the top is a drop down box where you can select the number of colors that you want to use. This can range from 2 to 20. If you would like to change the colors, you can click on the color and change it. After this, you should press Redraw to redraw your plot with the new colors. You can also change the values by hand and use the Redraw button to reflect these changes. You can also enter a minimum value in the lowest text field and a high value in the topmost text field and press the Redistribute button to redistribute the between the minimum and maximum value that you added.

The time step that is being displayed can be controlled from the Time panel beneath the plot. To advance the time step forward, press the ">" button. To move the time step backward, press the "<" button. The "<<" button will set the plot to the first time step and the ">>" will set it to the last time step. You can also move the slider to change the time step. Note that for very large files, there may be a delay between when you move the slider and when the plot refreshes.  The plot will also animate forward in time. You can press the Start button to begin the animation and use the Stop button to stop at the current time step. The Faster and Slower buttons will speed up or slow down the animation.  TIP: Always try to "rewind" to the beginning of the time period before changing compartment types.  This simple step will greatly decrease the time it takes to bring up the data for the newly selected compartment type.

You can add GIS layers on top of the TRIM.FaTE data results by going to the Layer menu and selecting Edit Layers. This will bring up a dialog that will contain information about the layers in your plot (an example is provided in Figure 8).  The first layer is the parcel layer. This is the outline of the parcels in your Scenario. The next layer is the data layer. This contains the colored polygons that represent the data you are currently displaying. 

Figure 8. Layer Control Window

To add a layer, press the Add button. This will bring up an open file dialog and allow you to choose a file to add. Currently, TRIM.FaTE can only read ESRI shape files. To show a layer, check the Show check box next to it's name. To hide a layer, uncheck the Show check box. You can raise and lower layers by selecting them and using the Raise and Lower buttons. A layer can be deleted from the plot by selecting it and pressing the Delete button. To set options for the layer, like polygon and line colors, press the Options button on the same row as the layer name.

The layer options window (shown in Figure 9) allows you to change attributes of the polygons, line and points in the layers. For a polygon, you can specify whether it is filled or open by using the Filled and Outline radio buttons on the right. If you select Outline, then only the Outline color will be used to draw the outline of the polygon. If you select Filled, then the Fill color will be used to fill the polygon and the Outline color will be used to draw outline of the polygon. You can change the color by clicking on the color box. Note that you can set the transparency of the color to allow lower layers to bleed through higher layers.  The line thickness of the outline in pixels can be set using the Thickness box.  Lines can be edited using the options in the Lines area. If there are Points in the shape file, the type, color and size can be set in the Points area. The available types are circle, square, triangle, diamond, cross and star. If you would like to preview the changes before you close the window, you can press Apply to apply the changes. Press OK to close and apply the changes. 

Figure 9. Layer Options Window

Figure 10 provides an example of GIS layers displayed with TRIM.FaTE data. Some of the streams and ponds in the area have been loaded and their color has been set to a transparent blue to allow the data colors to be seen with the water boundaries.

Figure 10.  GIS Layers on top of TRIM.FaTE data

You can also add your own overlays to the map with points, lines and polygons (as demonstrated in Figure 11). These are specified in a text file format which is detailed here. With this format, you can place labeled points and polygons on your plots to provide context for the data. Polygons may be either filled or unfilled and you can specify the fill color, line color, line thickness and line style. For labeled points, you can specify the symbol type, color and size. You can also specify the font color, type, style, size and orientation about the point. This feature could be used to add cities, buildings, park outlines and roads to the plot.  Below is an example of some of features of the overlay file.

Figure 11. Overlay of points on data

5.8 Performing a Sequence of Simulation Runs

Before running a sequence of simulations, the user should make certain that the scenario is set up correctly. It is advised that you set the output directory property in the scenario to identify the location where the run results will be written.

The first step in performing a sequence of simulations is to configure the runs.  To do this, open the Sequential Runs Window (Run -> Sequential Runs).  This will bring up a window similar to Figure 12.  By default, there will be one run, named "Run 1" in the Runs pane.  You can add new runs and duplicate, delete, or open existing runs using the buttons below the Runs pane.  You can also rename a run using the Run -> Rename menu item.

The second step in performing a sequence of simulations is to select the properties and objects that will be varied for each run (all other object properties in the scenario will be the same for all of the sequential runs).  This step involves the following tasks:

1. Select the "current" run from the Sequential Runs Window by selecting a run from the Runs pane and then selecting the "Set as Current Run" menu item from the Run menu.  After specifying a run as "current", all properties added (as described in item 6) will be added to this run until you select a different run as current.
2. Select the tab (e.g., Chemical Tab, Compartments Tab) that contains an object property that you wish to vary.
3. Select the object (or objects) containing the property (or properties) you wish to vary.  This can be done manually or using the Select Dialog.
4. Press the Properties button to display the properties for the selected object (or objects) up in the Property Editor.
5. Select one or more properties. 
6. From the Add menu, select "Add Selected Properties to Sequential [Run Name]."  It is important to note that the selected properties will be added for ALL of the selected objects.  To view the objects associated with the added properties, first view the properties for the run by (1) opening the Sequential runs window (Run -> Sequential Runs) and (2) selecting the run of interest and hitting the "Properties."  Then select the property (or properties) of interest.  When you select the property (or properties), the objects associated with these properties will be displayed in the Objects for Property pane.
7. Select a different run as "current" (as described in item 1) and repeat steps 2 through 7 until all of the desired properties have been added to all of the runs.

After selecting all of the properties that you want to vary in the sequential runs, go through each of the runs and change the properties values to the values you want to use in each of the simulations.  Finally, select the simulations you want in the Runs pane of the Sequential Runs Window and select "All Selected Runs" from the Run menu.

Figure 12. Sequential Run Window

5.9 Performing a Sensitivity Analysis

The TRIM.FaTE sensitivity analysis functionality is accessed via the Analyses view of the Scenario window by selecting “Sensitivity Analyses” from the drop-down box in the upper left corner. The window below the drop-down box (i.e., the “Sensitivity Analyses” pane) lists the sensitivity analyses that are in the current scenario. By default, an “empty” sensitivity analysis is created with every scenario and is labeled with the name of the scenario. To add a new sensitivity analysis, click the “New” button and enter a name when prompted. The other buttons below the analyses window can be used to delete, rename, or open analyses. In the example shown in Figure 13, five sensitivity analyses have been created.

To view specific information about an analysis, the user can bring up the Sensitivity Analysis window. This window is opened by selecting a sensitivity analysis name and clicking the “Open” button or by double-clicking the analysis name in the Sensitivity Analyses listing. Alternatively, the user can access this window by clicking on the “Run” pull-down menu in the scenario window, selecting “Sensitivity Analysis,” and then selecting the appropriate analysis in the dialog box that appears. The Sensitivity Analysis Window contains tabs that access three views:

1. The Properties view, used to specify the variation of the values included in the sensitivity analysis;
2. The Runs view, which conveys information about the status of the sensitivity run; and
3. The Analysis view, used to specify how the results of the analysis will be calculated.

The features associated with each of these views is described in more detail in the sections that follow.

Figure 13. FaTE Scenario Analysis View

5.9.1  Selecting Properties to be Varied

There is no default set of properties for a TRIM.FaTE sensitivity analysis. To designate the properties that will be varied, the user must add properties to the sensitivity analysis from the scenario window. The following steps describe this process.

1. Designate a “Current” sensitivity analysis by selecting one of the analyses from the Sensitivity Analyses list below the drop-down menu in the Analyses view of the Scenario Window (see Figure 13) and then clicking the “Current” button below the pane. After specifying an analysis as “current,” all properties added will be included in this analysis until the user designates a different analysis as current.
    
2. Click the tab in the main Scenario window (e.g., Chemical Tab, Compartments Tab) that contains the object property to be varied.
   
   
3. Select the object(s) containing the property or properties to be varied. This can be done manually, by finding the object and clicking on it to highlight the object name, or with assistance from the TRIM.FaTE “Select” tool by clicking the “Select” button and using the dialog window that appears (this feature can help the user find and select multiple, similar objects). Note that objects in the scenario with properties to be varied must be selected from the Outdoor Environment pane on the left, not the library pane that appears in the center.
   
   
4. Click the “Properties” button to bring the properties for the highlighted object(s) up in the Property Editor.
   
   
5. Select one or more properties by highlighting them in the Property Editor.
    
6. From the Add pull-down menu at the top of the scenario window, select “Add Selected Properties to Sensitivity Analysis [Analysis Name].” It is important to note that the selected properties will be added for ALL of the selected objects. When the property or properties have been added to the sensitivity analysis, a message will appear at the bottom of the TRIM window stating “### properties added to sensitivity analysis for ### objects” (each “###” will be replaced with the appropriate number depending on what the user has selected).
    
7. OPTIONAL: If you want to set up more than one sensitivity analysis, select a different run as "current" (as described in Step 1) and repeat Steps 2 through 7 until all of the desired properties have been added to all of the runs.

To view the properties that have been added to an analysis, open the Sensitivity Analysis window and click the Properties tab.  Next, select the property (or properties) of interest.  When you select the property (or properties), the objects associated with these properties will be displayed in the Objects for Property pane.  An example is provided in Figure 14.

Figure 14. Sensitivity Analysis Window, Properties View

5.9.2  Varying Property Values for the Analysis

Once the appropriate properties have been added to the analysis, the new values to be included in the sensitivity analysis runs can be set via the Properties view. As shown in Figure 14, each property is listed on a separate row of the table that appears on the left side of this view, with values for the following data fields in the columns (note that not all of these columns are visible in the window presented in Figure 14; the horizontal scroll bar at the bottom of the window can be used to view the hidden columns):

• # (contains a number that TRIM.FaTE assigns to the property for identification);
• Property name;
• Chemical to which the property pertains (if applicable);
• Value (i.e., the adjusted value to be used in the sensitivity analysis);
• Units of the value;
• Data type (only properties defined as real numbers should be added to a sensitivity analysis);
• Reference; and
• Old value (i.e., the original value for the property as defined in the base case).

The objects to which the currently selected properties apply (e.g., compartments, links, chemicals) will appear in the pane on the right under the label “Objects for [object name(s)],” where the name(s) in the brackets will be filled in depending on which properties are currently highlighted in the table.

The precise new value for a property can be set directly or by specifying a percentage change from the base value. To set the value directly, the user can edit the value displayed in the “Value” column for that property in the Sensitivity Analysis window. Alternatively, the value can be changed by a percentage of the original value by selecting the property, entering a percent variation in the text box at the top of the Properties view, and clicking the “Adjust” button. A positive percent variation will increase the value (a positive sign (“+”) is not required). Negative numbers can be entered using the negative sign (“–”) to denote a decrease in the value. Note that the actual percent should be entered in this window (e.g., to increase the values by 10 percent, enter “10,” not “0.10”). A different percent variation can be used for different properties, or the same percent variation can be implemented for multiple properties by selecting multiple properties (using the shift or control key) and entering a value for variation.

When adjusting property values by a given percent for a sensitivity run, the values are always adjusted from the original base case value. For example, if property values are initially varied by 10 percent, and the variation is then changed to 20 percent, the new values will vary by 20 percent of the original base case values, not by 20 percent of the 10 percent varied values. If desired, the user can reset one (or all) Property values to their original base case values by selecting the property (or all properties) and clicking the “Reset” button.

5.9.3  Executing the Sensitivity Analysis Runs

Information about the status and location of the simulation runs that are being performed is summarized on the Runs View within the Sensitivity Analysis window (see Figure 15). In the table that appears on this view, information about individual runs is presented on separate rows, including:

• the name of the run in the left column of the row;
• the status of the run in the middle column (i.e., whether or not the run has been completed, and whether or not the run was successful); and
• the name of the subdirectory where the run results will be saved in the right column.

Note that the table on the Runs View is simply used to present information to the user (i.e., the user cannot modify this table directly to change run information).

Two important options must be set by the user via the Runs view:

1. The output directory where the results files for the simulations will be stored should be specified in the window at the top of this view. This directory can be entered manually by the user, by clicking within the directory window and typing in the location. Alternatively, the user can click the “Set” button to bring up a file browser window that allows the user to find and select a directory.
    
2. The form of results to be used for presenting the sensitivity analysis (i.e., mass, moles and/or concentration) by checking one (or more) of the three check boxes below the output directory window.

  Figure 15. Sensitivity Analysis Window, Runs View

Once these options have been set, the model simulations associated with the sensitivity analysis can be run. Note that a separate simulation is completed for the base case and each of the “runs” (i.e., one for each of the properties that is selected to be varied). To execute these simulations, select one or more run in the table on the Runs View and click the “Run Selected” button at the bottom of the view. This will start the selected runs as a batch. While the simulations are processing, a small window with a “Stop” button will appear that can be used to stop the batch of simulations at any point during the run (it may take a minute or two for the simulation to stop after the button is clicked).

After the simulation for a given run has been completed, the status of that run in the table on the Runs View will change to “Successful,” “Warnings,” or “Failed.” An output subdirectory will be created within the main output directory (specified above) for each run as listed in the “Subdirectory” column. For each run included in the analysis (i.e., the base case run plus each of the runs for the properties that were perturbed), a complete set of output files will be saved in the corresponding subdirectory. These simulation results are used by TRIM.FaTE to calculate quantitative sensitivity results, as described in the following section.

Important Note: Depending on the complexity of the scenario and, likely, whether the model is run in dynamic or steady state mode, including a large number of runs in a single batch may cause model execution problems. Running multiple batches of runs (each containing a subset of the runs comprising a sensitivity analysis) may reduce the potential for this problem.

5.9.4  Performing Sensitivity Calculations

After the simulations for the base run and the perturbed properties have been completed, the sensitivity calculations to be completed using the simulation results can be specified via the Analysis View within the Sensitivity Analysis window (see Figure 16). To obtain sensitivity results, the user selects compartments and chemicals for which to evaluate the sensitivity of the properties that were varied from their base values. The steps involved in specifying and executing the calculations are described below.

Figure 16. Sensitivity Analysis Window, Analysis View

1. Using the small window at the top of the Analysis view, enter the name of the TRIM.FaTE Statistics file to be used for the calculations. The file name can be entered manually, or the user can click the “...” button to bring up a file browser and select a file. This Statistics file contains the coefficient of variation (CV) needed for each property included in the analysis.  The format of the statistics file is the same for the Sensitivity Analysis and Monte Carlo Analysis, and is described in the Statistics File Format document.  Note that the user is responsible for ensuring that the appropriate values for property CVs are used in this analysis.
    
2. For analyses involving results from dynamic simulations, specify a date and time from the simulations for which the sensitivity results will be calculated. This date and time should be entered in the window below the file name. If the simulation results did not include that particular date and time, TRIM.FaTE will use the last time point at which results were output. For example, if results for a run are calculated every four hours (e.g., hours 00:00, 4:00:00, 8:00:00, ... during a day), the results for 4:00:00 would be used if the user enters any time ranging from 4:00:00 to 7:59:59. If the sensitivity calculations are to be performed on averaged results, TRIM.FaTE will use the results for the time interval inclusive of this date and time.
    
3. For analyses involving results from dynamic simulations, specify the Average Interval for the simulation results (i.e., the time interval in hours within which the model simulation outputs will be averaged) in the text box to the right of the date window. This interval must be specified as either a whole-number multiple of the scenario output time interval or “monthly” or “annual.” For example, if simulation results are output every 3 hours (per user specification of the scenario properties for the simulation), the Average Interval could be specified as 3 hours, 6 hours, 12 hours, any other time period into which 3 hours is evenly divided, or as “monthly” or “annual.” For the sensitivity calculations to be performed on the simulation results as they are output from TRIM.FaTE (i.e., without subsequent averaging), enter the value (in hours) of the simulation output time step.  Note that the output time step is the product of the simulationStepsPerOutputStep and the simulationTimeStep properties (which are specified in the Scenario Window of the scenario).
    
4. In the “Outdoor Environment” pane in the center of the view, select the compartment(s) for which the output results will be analyzed. Multiple compartments can be selected simultaneously using the shift or control keys, and the “Select” button can be used to find and select groups of compartments. Click the “<<Add” button to add the selected compartments to the analysis. The selected compartments should appear in the “Selected Compartments” pane on the left side of the window. The “Delete” button below the pane can be used to remove compartments that have been added to the analysis.
    
5. Click the “Add” button below the “Chemicals of Interest” pane on the right-hand side of the window to bring up a “Select Chemicals” dialog box. From the list that appears, select the chemical(s) for which the output results will be analyzed. The selected chemicals should then appear in the “Chemicals of Interest” pane. The “Delete” button below the pane can be used to remove chemicals that have been added to the analysis.
    
6. Click the “Analyze” button at the bottom of the view to generate the results files. If the simulation is large (i.e., many compartments and links), or a large number of simulations are to be completed (i.e., many properties were perturbed), the analysis step may take some time.

Note that Steps 2 and 3 are not required if the sensitivity simulations are run in steady-state mode. If the simulation is being run in steady-state mode, TRIM.FaTE will automatically shade the date and averaging interval windows and the user will not be able to access them.

With the completion of the analysis step, TRIM.FaTE creates a sensitivity summary file for each combination of chemical (per user specification in step 5) and form of results (per user specification in the Runs view).

To perform additional sets of sensitivity calculations from the same set of sensitivity runs (e.g., to generate sensitivity analysis results for other combinations of compartments and chemicals, or to evaluate the sensitivity at a different date/time by entering a different date/time in Step 2), Steps 2 through 6 can be repeated. Note, however, that TRIM.FaTE will not change the name of the output file(s). That is, existing summary results files will be overwritten if Steps 2 through 6 are repeated for the same TRIM.FaTE sensitivity analysis. Therefore, if additional calculations are to be performed to produce new summary files, the user should first rename the previous summary files in order to preserve them.

For sensitivity calculations on results from dynamic TRIM.FaTE simulations, Steps 2 and 3 specify which results (i.e., from which time point or, for averaged results, which time interval) to use in the sensitivity calculations. The “Average Interval” input provides a way for the user to use time-averaged results rather than an instantaneous point in time. For example, if the Average Interval is specified as “annual” and the user enters a date/time that falls within the 20th year of the simulation, then the annual average of the simulation results for the 20th year will be used to calculate that set of sensitivity results. The user should note that the “sensitivity score” value that is calculated by TRIM.FaTE could vary depending on the averaging interval used and the selected time.

5.9.5  Sensitivity Analysis Results

    Summary Files

TRIM.FaTE generates summary results for the sensitivity analysis based on the user specifications listed in the previous section. These summary results will be saved to a series of text files in a subdirectory of the output directory specified in the Runs view of the Sensitivity Analysis window. The subdirectory will be named “Sensitivity Analysis” and will include an additional subdirectory with the name of the analysis.

One summary file will be created for each combination of chemical and form of results (i.e., mass, moles and/or concentration). Each row within a given summary file contains sensitivity results for a property that was perturbed and a selected compartment for which the output was of interest (i.e., the compartments listed in the “Selected Compartments” pane). For example, if four properties were varied in the sensitivity analysis, and three compartments were selected on the Analysis view, the sensitivity results file for a selected chemical and form of results (e.g., moles of divalent mercury) would contain 12 rows of data. Each row in the summary results file will include, in separate columns, values for the sensitivity parameters generated by TRIM.FaTE as presented in Table 15.  Key measures of sensitivity are highlighted in boldface in Table 15. Note that the calculation of the sensitivity score relies on the coefficient of variation provided by the user for each perturbed property in the TRIM.FaTE statistics file.

Sensitivity analysis summary results files will be semicolon delimited and can be opened in a spreadsheet program. Alternatively, they can be viewed within a TRIM.FaTE window by clicking the “View Results” button at the bottom of the Results view screen. A new TRIM.FaTE window will appear that contains an array of results for the current compartment(s) and chemical(s) (i.e., the compartment(s) and chemical(s) selected on the Analysis view).

Table 15.  Sensitivity Output File Columns

   
Individual Sensitivity Run Files

The run results from which the sensitivity measures are calculated consist of model results files for each unique combination of modeled chemical, form of results (i.e., moles, mass, or concentration), and perturbed property value. The format of these files is identical to the format of the outputs from a deterministic simulation. These results files are saved in subdirectories of the analysis results folder that are named using the property names included in the analysis. For example, using the output directory specified in Figure 15, the results for the runs in which the DustLoad property was perturbed will be saved in the following directory:

c:\MyFiles\ModelsTRIM\data\Public Reference\test\SensitivityAnalysis\test\ DustLoad3

Note that TRIM.FaTE assigns a subdirectory name for the individual run results that matches the name of the property being varied in the analysis with the addition of a numeral. The numeral corresponds to the order in which the property was selected for the analysis, starting with zero and skipping one (i.e., 0, 2, 3, 4...). This number is used to differentiate the subdirectory with these run results from the subdirectory with results corresponding to a different run involving the same property names.  Thus, the numeral “3” was attached to the folder name by TRIM.FaTE to differentiate these results from separate runs related to the same property name (e.g., if the property DustLoad for a different compartment was added to the analysis).

5.10 Performing a Monte Carlo Analysis

A Monte Carlo analysis involves running several simulations and varying a specified group of Properties in each simulation. These properties might have been chosen by selecting the most influential input Properties from a Sensitivity Analysis or based on some other criteria.  Unlike the Sensitivity Analysis where properties are varied by a percentage of the base value, the selected properties in a Monte Carlo analysis are varied by sampling from the input distributions of the properties, which are defined in a statistics file which you provide.

To access the Monte Carlo feature, go to the Analyses view within a TRIM.FaTE scenario and select “Monte Carlo Analyses” from the drop-down box in the upper left corner (see Figure 13). The window below the drop-down box (labeled the “Monte Carlo Analyses” pane) will list the Monte Carlo analyses that are in the current scenario. By default, an “empty” Monte Carlo analysis is created with every scenario and labeled with the scenario name. To add a new Monte Carlo analysis, click the “New” button and enter a name when prompted. The other buttons below the Analyses window can be used to delete, rename, or open analyses.

To view specific information about an analysis, the user can bring up the Monte Carlo Analysis window. This window is opened by selecting a Monte Carlo analysis name and clicking the “Open” button or by double-clicking the analysis name in the Monte Carlo Analyses pane. (Alternatively, the user can access this window by clicking on the “Run” pull-down menu in the scenario window, selecting “Monte Carlo Analysis,” and then selecting the desired analysis in the dialog box that appears.) Like the Sensitivity Analysis Window, the Monte Carlo Analysis Window contains tabs that allow the user to access three views:

1. The Properties view, used to specify the properties to be varied and the general set-up of the analysis;
2. The Runs view, which conveys information about the status of the Monte Carlo run; and
3. The Results view, used to specify how the results of the analysis will be calculated.

Each of these views is described in more detail in the sections that follow.

5.10.1  Selecting Properties to be Varied

The process for selecting properties to be included in the Monte Carlo analysis (i.e., properties for which values will be varied according to a specified distribution) is nearly identical to the process used to add properties to the sensitivity analysis (see Section 5.9.1). The steps to be followed are described here.

1. Designate a “Current” Monte Carlo analysis by selecting one of the analyses from the “Monte Carlo Analyses” pane below the drop-down menu and then clicking the “Current” button below the pane. After specifying an analysis as “current,” all properties added will be included in this analysis until the user designates a different analysis as current.
    
2. Click on the tab in the main Scenario window (e.g., Chemical Tab, Compartments Tab) that contains the object property to be varied.
    
3. Select the object(s) containing the property or properties to be varied. This can be done manually, by finding the object and clicking on it to highlight the object name, or with assistance from the TRIM.FaTE “Select” tool by clicking the “Select” button and using the dialog window that appears (this can help the user find and select multiple, similar objects). Note that objects in the scenario with properties to be varied must be selected from the Outdoor Environment pane on the left, not the library pane that appears in the center.
    
4. Click the “Properties” button to bring the properties for the highlighted object(s) up in the Property Editor.
    
5. Select one or more properties by highlighting them in the Property Editor.
    
6. From the Add pull-down menu at the top of the scenario window, select “Add Selected Properties to Monte Carlo Analysis [Analysis Name].” It is important to note that the selected properties will be added for ALL of the selected objects. When the property or properties have been added to the Monte Carlo analysis, a message will appear at the bottom of the TRIM window stating “### properties added to Monte Carlo analysis for ### objects” (each “###” will be replaced with the appropriate number depending on what the user has selected).

To view the properties that have been added to an analysis, click on the Properties tab within the Monte Carlo analysis window. The properties selected for inclusion in the Monte Carlo analysis will be listed in the left-hand window along with the original property values that were assigned for the simulation. The objects to which these properties apply will be shown in the right-hand window. An example of the Properties view within the Monte Carlo Analysis window for a sample analysis entitled “test” is presented in Figure 17. In this example, three properties have been added to the current analysis. The highlighted property in the example (AirDensity_g_cm3) has been added for the five air compartments shown in the right-hand object window.

To set up a separate Monte Carlo analysis, designate a different run as “Current” as described in Step 1, and repeat Steps 2 through 6 until all of the desired properties have been added to the run. Properties can be removed from an analysis by highlighting the unwanted property and clicking the “Del” button above the properties table.

Figure 17. Monte Carlo Analysis Window, Properties View

5.10.2  Specifying Property Value Distributions and Output Directory

The Properties view is also used to specify where the model can find the statistical distribution data for the selected properties. These data are stored in the statistics file for the scenario (which can be the same file in which the coefficients of variation for the sensitivity analysis are stored). Refer to the Statistics File Format document for information on how to set up and format the statistics data file. The user should specify the location of the statistics file using the “Statistics File” window at the top of the Properties view (see Figure 17). The file name and directory can be entered directly by the user (by clicking in the window and typing the directory and name of the file), or the user can click the “...” button to bring up a file browser that allows the user to find and select the appropriate file.

In addition, the directory where the Monte Carlo analysis output will be saved is also specified on the Properties view in the “Output Directory” window. Note that this procedure is slightly different from setting the output directory for the sensitivity analysis (when it is specified via the Runs view).

5.10.3  Configuring and Executing the Monte Carlo Runs

Information about the status and location of the Monte Carlo analysis model runs that will be performed is summarized on the Runs view (see Figure 18). The user defines three analysis settings on this view.

Figure 18. Monte Carlo Analysis Window, Runs View

=

1. Set the number of runs (iterations) to be performed by entering a value in the “Number of Runs” text box at the top of the view. If simple random sampling is being used to sample property values from the distributions, the number of runs can be set to any positive integer. However, if the Latin Hypercube sampling option has been selected, the number of runs must be set to an even multiple of the number of properties that are included in the analysis. For example, if four properties will be varied, the number of runs must be set to a multiple of four (e.g., 12, 400, 1000). After the number of runs has been entered, click the “Set” button next to the window. The runs will appear in the table along with each run’s status and the sub-directory to which the run results will be saved.
    
2. Set the numerical seed to be used for initializing the random number generation in the “Seed” text box. This step is optional; if not specified, TRIM.FaTE will set the seed to a random number by default. Setting the seed to certain number may be useful when comparing separate uncertainty runs that vary similar parameters. Note that if a previous Monte Carlo analysis is to be replicated, the user must specify the seed used in the original analysis here.
    
3. Select the sampling method to be used (i.e., either Random or Latin Hypercube).

After following these steps, the user must click the “Sample” button at the bottom of the view to sample from the distributions for each property. If one of the Properties does not exist in the statistics file, TRIM.FaTE will notify the user via an error message, and the user must edit the statistics file and resave the file to the location specified on the Properties view. The property values assigned by TRIM.FaTE for the Monte Carlo analysis can be viewed by clicking the “View Inputs” button at the bottom of the view (the values will appear in a new TRIM.FaTE window).

To start running the simulations for the Monte Carlo analysis, the user should select the runs to be performed by highlighting them in the table and clicking the “Run” button at the bottom of the view. A small window containing a “Stop” button will appear; this button can be clicked to abort the batch of runs.

Important Note: Depending on the complexity of the scenario and, likely, whether the model is run in dynamic or steady state mode, including a large number of runs in a single batch may cause model execution problems. Running multiple batches of runs (each containing a subset of the runs comprising a Monte Carlo analysis) may reduce the potential for this problem.

5.10.4  Collating Monte Carlo Analysis Results

After the simulations for the Monte Carlo analysis have been completed, the results can be collated (i.e., combined to a single summary file) via the Results view (see Figure 19). The following six steps should be completed to collate the results.

Figure 19. Monte Carlo Analysis Window, Results View

1. Select the units for which the results should be processed (i.e., mass, moles, or concentration, or any combination of these) by clicking the appropriate button(s) at the top of the view.
    
2. For analyses involving results from dynamic simulations, specify a date and time from the simulations for which the sensitivity results will be calculated. This date and time should be entered in the window below the check boxes for results units. If the simulation results did not include that particular date and time, TRIM.FaTE will use the last time point at which results were output. For example, if results for a run are calculated every four hours (e.g., hours 00:00, 4:00:00, 8:00:00, ... during a day), the results for 4:00:00 would be used if the user enters any time ranging from 4:00:00 to 7:59:59. If the Monte Carlo results are to be collated from averaged results, TRIM.FaTE will use the results for the time interval inclusive of this date and time.
    
3. For analyses involving results from dynamic simulations, specify the Average Interval for the simulation results (i.e., the time interval in hours within which the model simulation outputs will be averaged) in the text box to the right of the date window.  This interval must be specified as either a whole-number multiple of the scenario output time interval or “monthly” or “annual”. For the calculations to be performed on the simulation results as they are output from TRIM.FaTE (i.e., without subsequent averaging), enter the value (in hours) of the simulation output time step.  Note that the output time step is the product of the simulationStepsPerOutputStep and the simulationTimeStep properties (which are specified in the scenario view of the scenario window).
    
4. In the “Outdoor Environment” pane in the middle of the view, specify the Compartments for which the results will be collated by highlighting them (multiple compartments can be selected simultaneously using the shift or control keys, and the “Select” button can be used to find and select groups of compartments). Click the “<<Add” button to add the selected compartments to the analysis. The selected compartments should appear in the “Selected Compartments” pane on the left side of the view.
    
5. To specify which chemicals to include in the analysis, click the “Add” button below the “Chemical of Interest” pane on the right-hand side of the view to bring up a “Select Chemicals” dialog box. Select the appropriate chemical(s) from the list that appears. The selected chemicals should appear in the “Chemicals of Interest” pane.
    
6. Click the “Collate Results” button at the bottom of the view to collate the results (i.e., bring all of the final values in the selected compartments for the selected chemicals together into a single summary file).

Note that Steps 2 and 3 are not required if the sensitivity simulations are run in steady-state mode. If the simulation is being run in steady-state mode, TRIM.FaTE will automatically shade the date and averaging interval windows and the user will not be able to access them.

Once the results have been collated by TRIM.FaTE, there will be one results file for each combination of chemical and form of results. For example, if mass and concentration are both selected as the form of results and three chemicals are included in the simulations, six results files will be generated. Each results file that is created will contain an array of results, with results for each user-specified compartment saved in the columns of the array and the results for each run saved in the rows in the array.

To complete a Monte Carlo analysis for the same set of properties (i.e., to collate files at a different date/time by entering a different date/time in Step 2), Steps 2 through 6 can be repeated. Note, however, that TRIM.FaTE will not change the name of the output file(s). That is, existing collated results files will be overwritten if Steps 2 through 6 are repeated for the same TRIM.FaTE Monte Carlo analysis. Therefore, if additional calculations are to be performed to produce new collated results files, the user should first rename the previous results files in order to preserve them.

For collating Monte Carlo results from dynamic TRIM.FaTE simulations, Steps 2 and 3 specify which results (i.e., from which time point or, for averaged results, which time interval) to use in collating the Monte Carlo results. The “Average Interval” input provides a way for the user to use time-averaged results rather than an instantaneous point in time.

Each collated results file will be saved in a subdirectory of the output directory specified on the Properties view of the Monte Carlo analysis window (see Figure 17). The subdirectory will be named “MonteCarlo” and will include an additional subdirectory with the name of the analysis. The model results for individual runs will also be saved in folders within the scenario name subdirectory of the “MonteCarlo” subdirectory according to the names specified on the Runs view.  A collated Monte Carlo results file can be used to calculate statistics on the outputs of the Monte Carlo simulations (e.g., mean or median values in the compartments of interest; percentiles). TRIM.FaTE does not calculate such statistics internally; they must be calculated off-line by the user.

5.11 TRIM.FaTE Utility Programs

Several tools have been developed to assist users in processing TRIM.FaTE input and output data.  A brief description, as well as a link to a more detailed description, of each tool is provided below.

• Averager - This utility can be used to (1) average time-varying input files into larger time steps, (2) average time-varying output files into larger time steps, and (3) extract selected columns of input or output files into separate files.
  
• Transposer - This utility can be used to transpose output files (i.e., rotate delimited files so that the rows become the columns and the columns become the rows).  It is particularly useful for processing the results of a simulation with many compartments and few time steps so that the data can be read into a spreadsheet program (such as Excel) without exceeding the maximum allowable number of columns.
  
• Aggregator - This utility is used to create tables of aggregated model output.  For example, if the model was run for three species of mercury, the aggregator could be used to produce tables of total mercury by combining the results for each compartment across the different species.  This tool is very flexible in that it allows the user to design their own output table formats with a limited amount of effort.

6. Tips and Troubleshooting

6.1 Known Bugs

• Clicking on a window does not always bring it to the front: If you click on a window and it does not come to the front, try clicking on another window and then clicking on the original one. This seems to be a problem with one of the Java or Windows toolkits used by TRIM.FaTE.
• Splitters sometimes get stuck: If you try to use a splitter and it doesn't work, it may be due to the fact that splitters calculate the minimum size of the items on each side of the splitter, and they will not allow you to reduce either side to less than its minimum size. This can occur when you've already clicked "Properties" to bring up a Property Editor on the Library Window or the Outdoor Environment Window. If the Property Editor is visible, the splitter may not let you reduce the size of that portion of the window. However, if you close the window and recreate it, the splitter will work if you move it before you show the properties for an object. Other options include making the window containing the window larger and trying to move the splitter again, or use the buttons at the top of the splitter to make it go all the way to one side or the other instead of moving it incrementally.
• Can't find the Value column in the Library Property Editor: If you show properties for a chemical in a library, the Chemical column that is there for other types of objects is removed (because properties for Chemicals cannot be chemical-dependent). Then if you switch to another type of object the value column may appear to be missing. It is actually there, but is on the right side of the table. You can scroll to the right and put it back to its normal position by grabbing its Title Bar and dragging it to the appropriate place.
• Saving new projects & libraries: File names don't get automatically assigned when new projects and libraries are saved. (336)
• Object windows don't close with project / library: If you close a project or library and you have Object Windows open, the object windows still remain open. However, Close All will close all windows. (335, 461)
• Remove algorithm then Undo: If you select some links, then click "Show Algs" (gives union of algorithms on all links), then delete an algorithm, then Undo, it will add the algorithm back to all the selected links, instead of to just the ones it was on originally. An alternative is to re-smart link instead of undoing. (449)
• Editing library objects from the Outdoor Environment Window: If you edit an object in a library from the Outdoor Environment Window (e.g. a compartment), the library does not show an asterisk next to the name to indicate that it has been changed. (422)
• Undoing removing compartments: If you remove a compartment from the outdoor environment then Undo it, then Redo it, the links that were attached to the compartment are not visible unless you do a Refresh. (416)
• Library files get big unexpectedly: We have noticed some instances when library files suddenly get a lot bigger even though a lot of objects have not been added. We have been unable to diagnose the cause. If you find a situation in which you can readily reproduce this, please let us know. (416)
• Object importer messages: When the object importer sees a duplicate object, the error message gives the last line of the object instead of the first line. (339)
• Duplicating Scenarios does not work for Sensitivity and Monte Carlo Analyses: If you select "Duplicate" under the "Scenarios" pane in the "Project" window, or "Duplicate Scenario" in the "File" menu of the "Scenario" window, any sensitivity and Monte Carlo analyses associated with the scenario will not be included in the newly created scenario. (23)
• Uses too much memory for each sensitivity/Monte Carlo simulation:  We have noticed that TRIM.FaTE uses ~2MB of RAM per simulation due to a memory leak.  When you are performing sensitivity/Monte Carlo simulations, this can cause the computer to run out of memory prior to completion of the runs.  We recommend assuming that each run will use 2-3MB of RAM, and calculating the number of runs you can complete before running out of RAM.  Then you can "chunk" the runs (i.e., run a subset of the total runs you want to do, save your project, close TRIM.FaTE, reopen TRIM.FaTE, and move onto your next subset, repeating this process until you've completed all of your runs). (183)
• Graphical results viewer cannot show multiple air layers: The current graphical results viewer can only visualize results for runs with one air layer. (334)
• Graphical results viewer cannot show results for sinks: The current graphical results viewer gives an error if you try to display the results for a sink. (388)
• The animation for the graphical results viewer is VERY slow when GIS layers are added. As a workaround, do not animate with extra GIS layers.   (399)
• Time-step in graphical results viewer is incorrect: The time-step shown in the graphical results viewer does not exactly match the time-step being displayed. (342)

6.2 Enhancement Wish List

Property editor
1. When adding properties to an object, try to limit property types shown to those applicable to that type of object.
2. Enhance "Select" tool by allowing the user to: select objects by property value, search for particular properties in objects

Simulation

3. Make it easy to disable compartments in a simulation
4. The user should be warned if the only links in the outdoor environment are to sinks
5. Include links to the relevant properties in the verify warning and error windows.
6. Provide a GUI that allows the user to choose between multiple algorithms (or sets of algorithms) for a given process
7. Support multiple plant types within a single volume element
8. For the "Evaluate properties for selected objects", do not include unused algorithms when the properties for a link are evaluated.
9. Add check to make sure all animals with inhalation algorithms are linked to an air compartment.
10. Add check to make sure all aquatic animals that ingest soil are linked to a soil compartment.
11. Make SmartLink check to see if a link has already been added before giving a "No compartments match" or "Multiple compartments match" warning.
12. Do not show zero values in the food chain viewer.
13. Develop a GUI that simplifies the setup of the food web and erosion/runoff.
14. Make the process of setting up boundary conditions more user-friendly.
15. Streamline the calculation of air transfer factors.
16. Implement "distancetoMidpoint" function for surface water to surface water links.
17. Add a check that makes sure ending mass - added mass = initial mass.  If not, generate an error.  This feature would be turned off for steady-state simulations.

Import/Export and Files

18. Save results of simulation in binary files instead of just text files.
19. Support additional map projections
20. Export hard-coded constants in HTML
21. Export report describing source contributions
22. Move output options to a new output tabbed view in the scenario window.

Formulas

23. Provide mean() function in formulas.

General

24. Indicate when the system is busy doing something with a busy cursor.
25. Support a hierarchical view for the object chooser (e.g. compartment categories).
26. Support consistency checks for algorithms & volume elements (e.g. thicker soil shouldn't be on top of thinner).
27. Allow user to specify locations & data of interest for analysis.
28. Decrease file size & improve access time (may need a database instead).
29. Show progress bars during import, export, and other time consuming operations.
30. Track which properties and objects have changed since loaded from a library.
31. Allow compartments to have multiple acceptableAbiotic compartments
32. Change library select dialog to the same one used in the outdoor environment
33. Enhance meteorological data preprocessor so that it generate datasets for longer periods that the source data covers by repeating the source data.
34. Display properties values geographically.
35. Allow user to save plots from geographical results viewer to a file.
36. Add 2-stage uncertainty/variability capability.
37. Upgrade to Java JRE 1.4.

6.3 Revision History

• Unevenly Time Stepped Properties can be exported to / imported from libraries.
• Times in summer in Date Time Properties and Unevenly Time Stepped Properties no longer automatically change to daylight savings time zone.
• Can access most recently opened or saved Project and Library from the File menu on the Main Window.

New Features in Version 1.3

• Support for multiple runs (e.g. for Sensitivity and uncertainty analysis) - Properties to be changed for a set of sequential runs can be defined in a text file that follows the Run Importer syntax. This feature is accessed by choosing Load Runs from File from the File menu of the Scenario controls window.

• Properties for a scenario can be read in from a file - The Run Importer syntax can also be used to set the properties for the current scenario. The user will be prompted to choose one run from the list of runs in the file and the properties will be set according to those specified for the chosen run.

• Output results to files instead of being stored in memory - Results for concentration, mass, and moles are written directly to files at the completion of a scenario. They are placed in the most recently accessed directory. Output files are appended with a run number and are therefore not overwritten when the scenario is executed multiple times.

• Import multiple time-varying properties from a single file - Properties can be imported from a column in a delimited ASCII file. The user can define the delimiter (e.g. tab (\t), comma, semicolon). The data can be preceded with lines describing the file (try not to use the delimiter in these lines though). Below the header there should be a row naming the columns just above the data values. The leftmost three columns of the file should be: mm/dd/yyyy, hh:mm:ss, time zone where the minutes and seconds are optional and the time zone is a three character abbreviation. The data columns should be to the right of the time stamp information. The data in columns should be separated by the delimiter.

• Viewer for results - The Java Analysis and Reporting Tool (JART) has been integrated into TRIM.FaTE and can be used to analyze the results from the most recently executed simulation. Within the Report window you can sort, filter, and record and save the operations performed so they can be repeated at a later time.

• Automatic export of HTML or Mass and Concentration - There are two new scenario properties that, if used, will cause TRIM.FaTE to automatically export HTML and/or mass and concentration text files after the simulation completes. The property names are exportMassAndConcentration and exportHTML. If you have an existing scenario, you can add these properties. For new scenarios they will be added automatically with exportHTML set to false and exportMassAndConcentration set to true.

New Features in Version 2.0

• TRIM EXPO module with support for APEX and HAPEM.
• New FATE Scenario window layout. All tabs for the Outdoor Environment and Scenario are in one window.
• Sensitivity Analysis for FATE Scenarios.
• Sequential Runs for FATE Scenarios.
• Stop button to stop a Simulation or group of Simulations in the middle of a run.

New Features in Version 2.5

If you haven't used TRIM.FaTE since version 1.3, you should also check out the New Features in Version 2.0. The features added in Version 2.5 are:

• Additional Export Options.
• A set of pre- and post-processing FATE tools.
• Refined Sensitivity Analysis for FATE Scenarios.
• Monte Carlo Analysis for FATE Scenario.
• Re-initialize a simulation from a previous run.
• Average results files after a run and in monthly and annual time steps.
• Specify the number of significant digits in the output files.
• GIS Results Viewer.
• Food Chain Viewer.
• Ability to read compartments from a file.
• Food web and erosion/runoff checkers.
• Revised SmartLink so that it does not create unnecessary warnings.
• Revised Run -> Verify so that it removes links with no associated algorithms.
• Added additional output units options.
• Fixed bug that prevented users from saving large projects.

New Features in Version 2.6

If you haven't used TRIM.FaTE since version 2.5, you should also check out the New Features in Version 2.5. The features added in Version 2.6 are:

• Additional export options for creating TRIM.Expo-Ingestion inputs 
• Additional export options for creating TRIM.Risk-Eco inputs
• Ability to export deposition estimates
• Ability to export biotic dose estimates
• Ability to specify a properties file when running FaTE in command line mode.
• Ability to write FaTE output to a MySQL database
• Fixed duplicating scenarios (although Monte Carlo and Senstivity Analyses are not duplicated).
• TRIM.FaTE now closes the first time you ask it to.

New Features in Version 3.0

If you haven't used TRIM.FaTE since version 2.6, you should also check out the New Features in Version 2.6. The features added in Version 3.0 are:

• Changed all references to "PointSources" in GUI to "Sources"
• Enabled unset properties to be included in object export
• Disabled the "Add to Lib" button for the Outdoor Environment Panel
• When using the "Add to Lib" button, the string " from <Scenario Name>" (where <Scenario Name> corresponds to the name of the scenario) is added to the end of the object being added to the library.  This change makes the origin of the object more transparent.
• After adding a new object(s) from a scenario to a library using the "Add to Lib" button, the library opens automatically.  If the user tries to close the library, they are prompted as to whether they want to save the changes to the library, which in this case would be the addition of the new object(s).
• Changed all reference to the "TRIM.FaTE Computer Framework Guide" in the GUI to "TRIM.FaTE Computer Framework Guide."
• Disabled zeroSmallAmounts scenario property.
• Added "fateVersion" as mandatory scenario properties.
• Removed "exportDatabase" scenario property.
• Changed default delimiter in Averager and Transposer utility programs from comma to semicolon.
• Added VE_Info and NumObjs columns to Sensitivity Analysis summary file.

New Features in Version 3.1

• A new scenario property called exportBiotaIntakeRates was added. If this is set to true, intake rates for mammals and birds are placed in the MySQL database. This is relevant for TRIM.Risk applications.
• The bug that occasionally caused a scenario to be added to a library was corrected.
• An emissions source can now be correctly added to a library from a scenario.
• Additional checking regarding some scenario properties is added. If you encounter errors when you verify your scenario relating to this, add the missing properties to the scenario from the Scenario tab by clicking the New button on the Properties editor, Choosing None for Chemical, and choosing the property from the list of property types.

New Features in Version 3.2

• If you add the property outputAdvectionFactorsFile to your scenario and give it a file name (without a directory), TRIM.FaTE will write a file containing the air advection factors generated during the run to your output directory. These factors are useful when developing steady state applications.

New Features in Version 3.3

• Improved error reporting when computing a property value fails
• Better error messages when the user tries to save a project or library to a read-only file
• Fractional simulation time steps are now detected (based on the simulationBeginDateTime, simulationEndDateTime and simulationTimeStep properties).
• Fewer errors are generated when exporting to HTML.
• The Averager now correctly averages the wind direction.
• The Averager now accepts multiple items for the -incl and -excl options (separated using the same delimiter as the input file.
• The Averager takes a new argument -echoFirstLine that controls whether the first line of the output file is an average or a copy of the first line of the input file.
• The Averager now correctly diagnoses whether files have units.

New Features in Version 3.4 (12/22/2003)

• Default directory for the documentation is now doc/fate
• Added mySQLDataDir property to the scenario to facilitate the use of non-default MySQL installation locations.
• Require four digit year for meteorological and other time stepped input files.

New Features in Version 3.5 (11/12/2004)

• Enhanced command line arguments to better support use of FaTE from MIMS scenarios.
• Made updates that allow FaTE to work with MySQL 4.1.
• Corrected occasional problem that caused the first time step of output files to be overwritten.
• Corrected problem that required exportIngestion to be set for exportRiskEcoInputs to work properly.
• Removed extra delimiter from the end of the units line in some output files.

New Features in Version 3.6 (10/14/2005)

• The _dose output files were renamed to _intake.
• The stability class is no longer a required property for advection.
• The MySQL username and password can now be specified on the Preferences dialog and are used in any connections to MySQL.
• Implemented some corrections to the random sampling methods for uniform, normal, lognormal and triangular distributions, including bounds checking for normal and lognormal distributions.
• Improved Latin Hypercube by using a new sampling library and checking that values fall between the proper minimum and maximum.
• Specify 0 for the duration in the output database when steady state simulations are run.
• Addressed some issues with reading in date properties using Java 1.5
• Added the Analysis Engine table as an option for viewing results.

7. References and Related Documents

Volume Element Importer Specification

Compartment Chooser File Format

Formula Syntax Specification

Information on Smart Linking

Run Importer Syntax

Overlay File Format

Statistics File Format

Sample Database Queries

Java Analysis and Reporting Tool (JART) Documentation

Copyright Information