Smart Linking in TRIM.FaTE

TRIM.FaTE has the ability to add most of the links you will need to the outdoor environment based on the properties of the available algorithms. This document describes how this automatic linking is performed. In addition to the automated Smart Link feature, you may also add links manually. When you add links manually, algorithms will be automatically placed on the links as described in Determining whether Algorithms can be Placed on a Link

Table 1 specifies the algorithm properties that are used to determine whether an algorithm should be placed on a link between compartments when smart link is applied.

Table 1. Algorithm Properties used during a Smart Link

doesTransformChemical	The algorithm transforms a chemical from one species to another
doesTransportChemical	The algorithm transports a chemical from one compartment to another
sendingCompartmentCategory	The sending compartment must have this (or a more specific) category
receivingCompartmentCategory	The receiving compartment must have this (or a more specific) category
chemicalCategory	For transport algorithms, the chemical must have this (or a more specific) category
sendingChemicalName	For transform algorithms, the sending chemical must have this name
receivingChemicalName	For transform algorithms, the receiving chemical must have this name
compartmentRelationship	An optional property for algorithms. This restricts whether an algorithm applies based on the spatial relationship between the sending and receiving compartments. Valid values are: SAME (compartments are the exact same compartment), SENDER_ABOVE (the sending compartment is directly above the receiving compartment), SENDER_BELOW (the sending compartment is directly below the receiving compartment), NEXT_TO (the sides of the sending & receiving compartments touch each other), IN_SAME_VOLUME_ELEMENT (sending & receiving compartments are in the same volume element), IN_SAME_COMPOSITE (sending & receiving compartments are in the same composite compartment).

Background On Categories

Three of the properties used in the smart link process are "category properties". A category is used to classify objects hierarchically. The different levels of the hierarchy are separated with vertical bars ('|'). For example, a duck compartment could have a category of "bird | duck", or a surface soil compartment could have the category "soil | surface". The definition of the categories is up to the study designer. For example, a surface soil compartment could have a category of "soil | surface" or simply "Surface Soil". The important thing is that the category notation be consistent within the projects and libraries used for the study. One advantage of using a hierarchical system for the categories is that it allows algorithms to be specified at higher levels. For example, if the categories "soil | surface" and "soil | vadose" were used for surface soil and vadose soil compartments, then an algorithm that specified "soil" as the sending or receivingCompartmentCategory would apply to surface soil and vadose soil compartments. The recommended approach is to use only as much hierarchy as is useful for the system being studied.

Determining whether Algorithms can be Placed on a Link

The determination of whether an algorithm should be placed on a link is affected by whether the algorithm transports a chemical from one compartment to another or transforms a chemical from one species to anther. (Note that it is possible for an algorithm to both transform and transport a chemical.)

If the algorithm transforms a chemical from one species to another, the system will add the algorithm to links between pairs of sending / receiving compartments which meet the following criteria:

The category of the sending compartment is the same as (or more specific than) the sendingCompartmentCategory of the algorithm
The category of the receiving compartment is the same as (or more specific than) the receivingCompartmentCategory of the algorithm
One of the chemicals in the simulation has the name specified as the sendingChemicalName.
One of the chemicals in the simulation has the name specified as the receivingChemical Name.
The sending and receiving compartments satisfy the compartmentRelationship (if one is specified).

Note: Usually, the sending and receiving compartments of a link with a transform algorithm are the same compartment (i.e. the chemical is transformed within a single compartment), but this will not be the case if the algorithm both transforms and transports a chemical.

If the algorithm transports a chemical from one compartment to another, the system will add the algorithm to links between pairs of sending / receiving compartments which meet the following criteria:

The sending and receiving compartments are not the same compartment.
The category of the sending compartment is the same as (or more specific than) the sendingCompartmentCategory of the algorithm
The category of the receiving compartment is the same as (or more specific than) the receivingCompartmentCategory of the algorithm
At least one chemical in the simulation has the same (or a more specific) category specified as the chemicalCategory for the algorithm.
If the compartments are in different volume elements, the volume elements are adjacent and the compartments are abiotic.
The sending and receiving compartments satisfy the compartmentRelationship (if one is specified).

For smart linking to work properly, it is important that the values of sendingCompartmentCategory and receivingCompartmentCategory for the algorithms be consistent with the values of the "category" properties for the compartments. For example, if the algorithm specifies "Air - Default" for sendingCompartmentCategory, and the Air - Default compartment specifies "Abiotic | Air - Default" as its category, then the smart link will not place the algorithm on the link between compartments. However, if the algorithm specifies "Air" for sendingCompartmentCategory, and value of the category property for the Air - Default compartment is "Air | Air - Default", then the algorithm will be placed on the link because "Air" is more general than "Air | Air - Default".

Similar care must be taken when specifying categories for chemicals. For example, if the category for the chemical "Divalent Mercury" is specified as "Metal | Mercury | Divalent Mercury", but the chemicalCategory for an algorithm is listed as "Mercury", the algorithm will not be placed on a link that uses this chemical. However, if the chemicalCategory for the algorithm is "Metal | Mercury", the algorithm will be placed on the link.

The Smart Linking Methodology

The Smart Link processes creates links automatically for the selected volume elements according to the following methodology:

Create links between the compartments within each volume element when algorithms exist that can go on the link. This has the effect of linking biotic compartments to other compartments within their own volume element (wherever possible) instead of linking to compartments outside the volume element. Examples of algorithms that could fit this category: hawk eats mouse, mouse excretes to soil.
Create links between the abiotic compartments in each volume element and abiotic compartments in neighboring volume elements when algorithms exist that can go on the link. Examples of algorithms that could fit this category: advective transport between air compartments, erosion from soil to surface water.
After performing the above steps for all requested volume elements, examine the biotic compartments for each volume element to see if any algorithms that could apply for compartments with its category have not yet been used on the compartment's links. Examples of algorithms that could fit this category: deer drinks from water, hawk eats fish. If any such unused algorithms exist, examine the compartments in the neighboring volume elements to see how many of them can satisfy each algorithm. If the resulting number of matching compartments in neighbors is
- Zero: then log a warning that the algorithm has not been satisfied
- One: then make a link between the compartments and add the algorithm
- More than one: There is more than one possibility for the link, so do not make one automatically - log a warning instead. The user will probably have to make this link manually later by connecting the correct pairs of compartments.

After performing a smart link, any warnings that occurred during the process will be shown. It is very important to carefully examine the warnings to help you determine cases for which you will need to make links manually.