In this section, Envision's input files are described. These are essential to defining and configuring an Envision application. Envision consists of a number of files that collectively provide input to drive a futuring analysis. These are shown in the figure below and described here.

The Project File is an XML-based file that specifies a number of settings and inputs required for a given ENVISION application. It is organized as a series of sections, specified in a particular order. Each section is specified by a header of the form <section_name>. The Project File is a standard ASCII (text) file that can be edited with Notepad or any other ASCII editor, or any XML-based editor. Generally, this file is autogenerated by Envision and does not need to be edited directly. Instead, Envision provide a Project File Editor that allow maintenance of this file. However, some developers prefer to maintain this file by hand, providing more flexibility.

When starting a new project, Envision will prompt for the name and path for this file, and automatically create a basic Project file.

The sections of the Project file include the following:

SectionDescription
<settings> sectiondefines high-level Envision settings
<layers> sectiondefines map layers (coverages) to be used in the application
<zooms> sectiondefines predefined viewing levels, locations
<auto_processes> sectiondefines any autonomous process models used in the application
<eval_models> sectiondefines any evaluative models used in the application

Individual sections of the Project file are described below.


<settings>

Attribute NameDefinitionValuesRequired?
Envision Environment
debug ReservedNo
logMsgLevel Level of logging messages0=log everything (default),
1=log critical events,
2= log nothing
No
noBuffering Determines where buffering is suported in policy outcome0=buffering supported
1=buffering not supported (default)
No
parallelIf enabled, allows evaluative models and autonomous processes to be run in parallel if multiple CPU cores are available0 = disable parallel execution of plugins (default)
1 = enable parallel execution of plugins
No
path Adds the specified path(s) to the Envision PATH search; multiple paths must be separted by ';' or '|'No
deltaAllocationSize“Chunk” size, in bytes, by which new deltas are allocated Generally, this can be ignored.0 (default) allocates delta arrays in 32KB chunks.No
Project Setup
spatialIndexDistanceMinimum distance for a spatial index to use.0 will disable loading of spatial index; positive values will check any existing spatial index to be sure it is sufficient, and rebuild it if necessary. Large values make take a long time to build the index. You should set this to whatever the maximum distance any of your spatial queries, Expand() functions, etc. might use. (Default=0)No
areaCutoffMinimum area of polygon for which a label, if defined, will be shown. Measured in map units. Used to control label display for smaller polygons.0 indicates to display labels regardless of polygon sizeNo
policyPrefenceWtdefault weight used for policy scoring preferences during actor decision-making0 to 1 (the sum of actorAltruismWt, actorSelfInterestWt, and policyPrefenceWt should equal 1)No (defaults to 0.33)
addReturnsToBudget When considering cost limitations on policies, whether to include negative costs (returns) to the available budget.0=don't add returns (default), 1=add returnsNo
mapUnits Map Units of the IDU coverage‘feet’, ‘meters’,’degrees’,’unknown’ (default)No
ConstraintsReservedNo
Runtime Control
startYear Default starting year of runs. This can be changed at runtime.No (defaults to '0')
defaultPeriod Default length (in years) of runs. This can be changed at runtime.No (defaults to '25')
startRunNumber starting run number for this session, used to control autogenerated output file names.No (defaults to '0')
multiRunIterationsDefault number of runs used during multirun (Monte Carlo) simulations. THis can be changed at runtime.No (defaults to '20')
dynamicUpdate Indicates whether on-screen maps/views/text are updated during a run (slows performance) 0=no dynamic update
1=Update Views annually
2=Update Map annually
4=Update year of simulation on Map
8=Update which process is running on Map
16=reserved
No (defaults to '3')
discardMultirunDeltas Frees memory associated with delta arrays during successive monte-carlo runs during a multirun. Because delta arrays can have a large memory footprint, this may provent running out of memory during a multirun.
0=retain delta arrays during multiruns (default),
1=discard deltas during multiruns
No
Actor Setup
actorInitMethodMethod used to initialize Actor weights0 = no actors (default)
1 = actors are created from weights specified in the IDU coverage.
2 = actors are created from Groups defined in the project file. The IDU cover contains the group ID in a field called ACTOR
3 = actors are created based on a query string specified for the actorGroup in the project file
4 = a single actor is created from a single ActorGroup specified in the project file
5 = random actors are generated
No
actorAssociationsReserved for future useNo
loadSharedPoliciesDetermines whether shared policies are loaded from the policy database0=don’t load shared policies
1=load shared policies (default)
No
actorDecisionElementsIndicates globally what elements of decision-making are available to actors.This is an integer that is the sum of the following:
1 – self-interested decision making
2 – altruistic decision making
4 – global policy preference
8 – utility
32 – social network influences
For example, if the application wants to allow 1,2 and 4, but not 8 and 32, then this flag should be set to (1+2+4)=7.
Note that 8 (utility) requires a user-defined autonomous process to populate a “UTILITY” field, and 32 (social network) requires that a social network be defined. See relevant topics for more information.
No
actorDecisionMethodDetermines whether actors select policies proabilistically or always selecting the “best” policy1=probabilistically select policies based on scores (default) 2= always pick policy with the highest score
dynamicActorsReserved for future useNo
shuffleActorPolysIf enabled, the polygon order by which actors make decisions is randomized at each step0 = used fixed order (default)
1 = randomize order at each step (slightly more expensive computationally)
No
Output Control
collectPolicyData Flag indicating whether policy statistics are collected during a run.0=don't collect, 1=collect (default)No
exportMapIntervalDefault map export interval (years) during a run-1 =do not export maps during a run (default)
Positive value = export IDU map at the specified interval during a run.
Note that this can be controlled interactively during run-time as well. Exported maps will be placed in subdirectories labeled with the scenario name and run number within the directory containing the IDU coverage
No
exportBmpIntervalDefault map export (as BMP's) interval (years) during a run-1 =do not export maps during a run (default)
Positive value = export IDU map at the specified interval during a run. Exported BMP's will be placed in subdirectories labeled with the scenario name and run number within the directory containing the IDU coverage
No
exportBmpPixelSizeCell size (in map units) for exporting bitmaps (.bmp). Only used if exportMapInterval > 0Must be a positive value, in map units
exportBmpColsString indicating with column(s) of the IDU coverage should be exported. Ignored if BMP export is disabled.Comma-separated list of field names to be exported a bitmaps. If not specified and exporting bitmaps is enabled, the currently active field is exported.No
exportOutputsEnables automatic export of CSV files containing model results and exposed variables at the end of a run0 = don’t export model outputs
1 = export model outputs
Exported files will be placed in subdirectories labeled with the scenario name and run number within the directory containing the IDU coverage
No
exportDeltas Flag indicating whether to export the delta array at the end of the run0=dont' export delta array (default)
1=export delta array
No
exportDeltaColsString indicating with column(s) of the delta array should be exported. Ignored if delta export is disabled. Comma-separated list of field names to be exported inthe delta array. If not specified and exporting delta arrays is enabled, all field will be included in the exported delta arrayNo

<layers>

Coverages included in an Envision application are specified within the <layers> tag. Individual layers are defined with individual <layer> entries. The first <layer> entry is required to be the IDU coverage. Additional layers are dependent on the specific needs of the models used in the application.

Attributes for the <layers> tag are defined below.

Attribute NameDefinitionValuesRequired?
bkgr The path to a background image displayed "underneath" the coverages described below..No (no background image is displayed)
left The "real world" x coordinate of the left hand side of the image (expressed in map units)Yes, if 'bkgr' is defined.
right The "real world" x coordinate of the right side of the image (expressed in map units)Yes, if 'bkgr' is defined.
top The "real world" y coordinate of the top side of the image (expressed in map units)Yes, if 'bkgr' is defined.
bottom The "real world" y coordinate of the bottom hand side of the image (expressed in map units)Yes, if 'bkgr' is defined.
prjFile The path to a projection file for the image. If not specified, the projection of the IDU coverage is assumed.No

Nested within the <layers> tag, individual coverages are specified with <layer> tags. Attributes for this tag are defined below.

Attribute NameDefinitionValuesRequired?
name A name associated with the coverage.Any stringYes
path The path to the coverage on diskYes
initField Initial field to be displayed after the coverage is loaded into EnvisionAny valid fieldNo (defaults to first field)
overlayFields No
color Color for drawing polygon/line edges, expressed as an RGB triplet, i.e. r,g,bExample: '0,0,0' results in a black polygon/line edgeNo, defaults to '140,140,140' (gray)
fieldInfoFile The path to the field information file (legend) for this layer. If not specified, a file matching the shape file but with an xml extension is assumed.No
labelField A field in the coverage containing string used for labeling featuresAny valid string fieldNo (labels won't be drawn)
labelFont The name of the font used to draw labelsNo, defaults to 'Arial'
labelSize The size of the labels to be drawnNo, defaults to '120'
labelColor Color for drawing labels, expressed as an RGB triplet, i.e. r,g,bExample: '0,0,0' results in a black fontNo, defaults to '255,255,255' (white)
labelQuery A spatial query used to determine which IDU's should be used for labelingAn valid spatial queryNo, defaults to all IDUs
type The type of the coverage. -1=infer from extension (default),
0=shape file,
1=integer grid
2=floating point grid. For grids, this attribute must be set to either 1 or 2
No
records Number of coverage database records to load. Specifying -1 indicates to load all records. Only applies to shape files.No (defaults to -1)
expandLegend Flag indicating whether legend for the layer is initially expanded.0=don't expand, 1=expand (default)No