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.
Individual sections of the Project file are described below.
| Attribute Name | Definition | Values | Required? |
|---|
| Envision Environment |
| debug | Reserved | | No |
| logMsgLevel | Level of logging messages | 0=log everything (default),
1=log critical events,
2= log nothing | No |
| noBuffering | Determines where buffering is suported in policy outcome | 0=buffering supported
1=buffering not supported (default) | No |
| parallel | If enabled, allows evaluative models and autonomous processes to be run in parallel if multiple CPU cores are available | 0 = 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 |
| spatialIndexDistance | Minimum 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 |
| areaCutoff | Minimum 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 size | No |
| policyPrefenceWt | default weight used for policy scoring preferences during actor decision-making | 0 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 returns | No |
| mapUnits | Map Units of the IDU coverage | ‘feet’, ‘meters’,’degrees’,’unknown’ (default) | No |
| Constraints | Reserved | | No |
| 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') |
| multiRunIterations | Default 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 |
| actorInitMethod | Method used to initialize Actor weights | 0 = 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 |
| actorAssociations | Reserved for future use | | No |
| loadSharedPolicies | Determines whether shared policies are loaded from the policy database | 0=don’t load shared policies
1=load shared policies (default) | No |
| actorDecisionElements | Indicates 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 |
| actorDecisionMethod | Determines whether actors select policies proabilistically or always selecting the “best” policy | 1=probabilistically select policies based on scores (default)
2= always pick policy with the highest score |
| dynamicActors | Reserved for future use | | No |
| shuffleActorPolys | If enabled, the polygon order by which actors make decisions is randomized at each step | 0 = 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 |
| exportMapInterval | Default 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 |
| exportBmpInterval | Default 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 |
| exportBmpPixelSize | Cell size (in map units) for exporting bitmaps (.bmp). Only used if exportMapInterval > 0 | Must be a positive value, in map units | |
| exportBmpCols | String 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 |
| exportOutputs | Enables automatic export of CSV files containing model results and exposed variables at the end of a run | 0 = 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 run | 0=dont' export delta array (default)
1=export delta array | No |
| exportDeltaCols | String 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 array | No |
| Attribute Name | Definition | Values | Required? |
|---|
| name | A name associated with the coverage. | Any string | Yes |
| path | The path to the coverage on disk | | Yes |
| initField | Initial field to be displayed after the coverage is loaded into Envision | Any valid field | No (defaults to first field) |
| overlayFields | | | No |
| color | Color for drawing polygon/line edges, expressed as an RGB triplet, i.e. r,g,b | Example: '0,0,0' results in a black polygon/line edge | No, 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 features | Any valid string field | No (labels won't be drawn) |
| labelFont | The name of the font used to draw labels | | No, defaults to 'Arial' |
| labelSize | The size of the labels to be drawn | | No, defaults to '120' |
| labelColor | Color for drawing labels, expressed as an RGB triplet, i.e. r,g,b | Example: '0,0,0' results in a black font | No, defaults to '255,255,255' (white) |
| labelQuery | A spatial query used to determine which IDU's should be used for labeling | An valid spatial query | No, 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 |