ENVISION

Sync is an Envision plug-in that allows for "synchronizations" to be run whenever specified changes in the underlying spatial database (IDUs) happen as a result of some other Envision process running - in effect, a sync is a "listener" that responds when specific database changes occur. In that sense, it is similar to another Envision plug-in, Trigger. Defining a sync is straightforward - like most Envision plug-ins, Syncs are specified using an XML file, described below. Syncs are defined based on what field changes they are listening for. Syncs can be turned on and off for specific scenarios through use of the "use" attribute, which is exposed as a scenario variable (settable scenario by scenario in the study area project file.

Comparing Sync and Trigger

Property	Sync	Trigger
Is invoked based on:	Detecting A specified value, a change of value, or range of values in a source column	Each IDU that satisfies a spatial query
Computation Time:	Executes quickly	Executes more slowly
Value used to update IDUs:	a single value or range of values	A Mathematical Expression, include field values

Sync Input File

The basic XML format for a Sync input file is provided below.

<?xml version="1.0" encoding="utf-8"?>
<syncs>
    <sync name='MySyncName' use='1' query='myQuery' >
        <outcome target_col="SomeCol" target_value='SomeExpression" probability='SomeProbability'>/>
            ...
        <outcome target_col="SomeCol" target_value='SomeOtherExpression" probability='SomeOtherProbability'>/>
    <sync>
    ...
    <sync name='MySyncName' use='1' query='myQuery' >
        <outcome target_col="SomeCol" target_value='SomeExpression" probability='SomeProbability'>/>
            ...
        <outcome target_col="SomeCol" target_value='SomeExpression" probability='SomeProbability'>/>
    <sync>
</syncs>

In the example above, for each time step, the sync "MySyncName" would invoked for every IDU for which the query "MyQuery" is satisfied. In that case, each outcome associated with this sync would be applied to the IDU database. Using the example above, the IDU field "SomeCol" would get populated with the result of evaluating the expression "SomeExpression"; the likelihood of that expression being applied is determined by the value "SomeProbability". Specific tags and attributes shown in the figure above are described below.

Tag Definitions for Sync

<sync> tag

The <sync> tag defines the name of the sync, the spatial domain of the sync, and whether the sync is enabled by default. Any number of <sync>s can be placed in the file; each operate independently of the other. Syncs are executed in the order specified in the input file; changes made by a 'higher' sync are not seen by "lower" syncs (the results of the sync outcomes aren't written to the IDU database until all syncs have executed. The <sync> tag has no attributes, but contains child <sync_map> tags that define mappings for different syncs, described below.

[top]

<sync_map> tag

The <sync_map> tag defines the name of the sync, source and target columns, and the source of information generating a sync event, and whether the sync is enabled by default. Any number of <sync>s can be placed in the file; each operate independently of the other. Syncs are executed in the order specified in the input file; changes made by a 'higher' sync are not seen by "lower" syncs (the results of the sync outcomes aren't written to the IDU database until all syncs have executed.

Attribute	Description	Default Value	Required?
name	Name of the model		Yes
source_col	The field in the IDU coverage that is monitored for changes		Yes
target_col	The field in the IDU coverage that receives the result of a sync operations		Yes
method	"useMap" or "useDelta" - determines whether changes are detected by scanning the Delta Array or the IDU coverage	"useDelta"	No

[top]

Within a <sync_map> tag, child <map> tags determine specific values Sync listens for, and what value is populated into the IDU as a result. These are defined below.

<map> tag

Attribute	Description	Default Value	Required?
source_value	Value(s) of the attribute indicated by the source_col attribute above that trigger a sync event. Note that this can be one of: a specified value (e.g. source_value="0.1") a range of value (e.g. source_value="2.2-5.8") any value (indicated with a ) (e.g. source_value="")		Yes

[top]

A sync event can be defined to have a single, or multiple, outcome. Outcomes can be deterministic or probablistic. These outcomes are defined by using <outcome> tags, which are nested as children within the <map> tag, as follows:

<outcome> tag

The <outcome> tag specifies the IDU field to be updated when the sync is invoked, along with an expression that is evaluated to determine what value is written to the IDU field. Optionally, a probability (0-1) can be defined that determines the likelihood of that outcome actually being wrtten to the IDU.

Attribute	Description	Default Value	Required?
target_value	a value used to populate the 'target_col' defined above when this sync is invoked		Yes
probability	fraction (0-1) specifying the probability that this outcome will be applied.	1.0	No

[top]

An Example Sync Input File

Below is an example sync input file.

<?xml version="1.0" encoding="UTF-8"?>

<!-- Sync specifies a set of mappings between variables in one column to 
     variables in another column. -->

<sync>

    <!-- this map looks for disturbances and flips them to there negative values at the begining of a step -->
    <sync_map name="Disturb Flipper" target_col="DISTURB" source_col="DISTURB" method="useMap">
        <map source_value="21">
            <outcome probability="1.0" target_value="-21"/>
        </map>
        <map source_value="23-25">
            <outcome probability="1.0" target_value="-23"/>
        </map>
    </sync_map>

    <!-- this map looks for disturbances and sets the time since disturbance to 0 -->
    <sync_map target_col="TSD" source_col="DISTURB">
        <map source_value="*">
            <outcome probability="1.0" target_value="0"/>
        </map>
    </sync_map>
</sync>