SpatialAllocator 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, SpatialAllocators are specified using an XML file, described below. SpatialAllocators are defined based on what field changes they are listening for. SpatialAllocators 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.

Property	SpatialAllocator	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

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

<?xml version="1.0" encoding="utf-8"?>
<syncs>
    <sync name='MySpatialAllocatorName' 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='MySpatialAllocatorName' 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 "MySpatialAllocatorName" 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 SpatialAllocator

<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. SpatialAllocators 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.

<sync_map> tag

The <sync_map> tag defines the name of the sync, source and target columns, and 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. SpatialAllocators 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
query	A query used to determine which IDU's are synced		Yes
use	Flag indicating whether this sync should be active during a run.  It is expled as a scenario variable.	1 (use is enabled)	No

<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_col	IDU field that will be populated by this outcome		Yes
target_value	a map expression that is evaluated when this sync is invoked		Yes
probability	decimal fraction (0-1) specifying the probability that this outcome will be applied.	1.0	No

An Example SpatialAllocator Input File

Below is an example sync input file.

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

<!-- SpatialAllocator specifies a set of mappings between variables in one column to 
     variables in another column. <sync method: "useDelta" (default) or "useMap" -->

<sync method="useMap">

    <!-- 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">
        <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>