Skip to main content

Model context schema

This guide provides a reference on the model context schema.

example

For a complete model context file example, please see Model context example.

Properties​

Below are detailed descriptions of the context object's properties. To find a specific property, use the navigation menu on the right. To find a specific property, use the navigation menu on the right.

version​

Specifies the platform version.

  • Type: string
  • Nullable: false

variables​

An object that describes the model variables that comprise the archived run state. In each key-value pair, the key is the variable name and the value is a VariableOptions object describing the processing options for the variable.

VariableOptions object properties​

PropertyTypeNullableDescription
resetDecisionbooleanYesOnly used for Simlang. If true, decisions are reset to the calculated value after each step. If false, decisions keep the user-entered value.
dialectstringYesThe way we describe the variable. For possible values, see dialect values below.
savebooleanYesIf true, the value should be saved to database. This property only applies to Excel and systems dynamics languages like SimLang, Vensim, STELLA, and Powersim. In programming languages, like Python, you must call Epicenter.record() to save a variable value.
reportPernumberYesA floating-point number of time steps. Defines the frequency with which the value should be saved to the database. Used with modelling languages like Vensim, STELLA, and Powersim. There can be thousands of time steps in a model. You might not want to save the variable values for every step lest the history become too large. To define the optimal number of time steps between variable saves, set this value.
sensitivitybooleanYesParticular to Vensim. Marks a variable as one that will be output during a sensitivity run.
reportOffsetintegerYesThe time step when the first variable save should occur.

dialect values​

  • POINT_IN_TIME For languages like Simlang that can return a history of a variable's value. This dialect returns only the head of that history, which is the current value.
  • XY: Returns an array of objects with two values: the timestep value and the variable value.
  • COLLAPSED_ARRAY: Vensim, STELLA, and Powersim give you subscripted variables. This dialect leaves out the subscripts. Returns an array of values in the correct subscript order.
Variables example
    "variables": {
        "variable-1": {
            "dialect": "point_in_time",
            "resetDecision": true,
            "save": true,
            "sensitivity": false,
            "reportPer": 2,
            "reportOffset": 0
        },
        "sensitivity-variable-1": {
            "resetDecision": false,
            "save": false,
            "sensitivity": true,
            "reportPer": 1,
            "reportOffset": 0
        },
        ...
    },
    ...

externalFunctions​

An object that describes external functions mapped in the model. Each key-value pair consists of a function name as the key and a WireExternalFunction object as the value.

WireExternalFunction object properties​

PropertyTypeNullableDescription
routeRoute objectNoDefines the route to the external function.
argumentsstringYesArguments for the external function.

Route object properties​

PropertyTypeNullableDescription
servicestringYesThe name of the external service that provides the function.
versionintegerYesThe external service version.
External functions example
    "externalFunctions": {
        "key": {
            "wire": {
                "route": {
                    "function": {
                        "name": "create"
                    },
                    "service": "user",
                    "version": 2
                },
                "arguments": "[\"name\",\"email\"]"
            }
        }
    },
    ...

modelVersion​

Allows you to version your models.

tip

If you would like to version your models, please contact Forio support, as this may require a custom implementation.

  • Type: integer
  • Format: int32
  • Minimum: 0
  • Nullable: true
Model version example
    "modelVersion": 3

mappedFiles​

Use this property to provide a list of mapped context files.

An object containing string key-value pairs.

  • Keys: Names for the mapped files (string)
  • Values: The mapped file paths (string)
  • Nullable: true
Mapped files example
    "mappedFiles": {
        "region_1": "path/to/file/for/region_1",
        ...
    },
    ...

control​

Provide specific settings for each modelling language in this property.

ExcelModelControl object properties​

PropertyTypeNullableDescription
autoRecalculatebooleanYesIf true, automatically recalculate all values after each state-changing operation. Alternatively, Epicenter provides a recalculate() function that can be called by the model when making a step.

JavaModelControl object properties​

PropertyTypeNullableDescription
executablestringYesThe name of the executable you want from the model JAR.

PowersimModelControl object properties​

PropertyTypeNullableDescription
minimizeMemoryFootprintbooleanYesDetermines whether to minimize memory usage during model execution.

VensimModelControl object properties​

PropertyTypeNullableDescription
sensitivityControlSensitivityControl objectNoConfiguration object for controlling sensitivity analysis in Vensim.
extensionModulestringYesThe name of an optional Vensim extension module to load.

SensitivityControl object properties​

PropertyTypeNullableRequiredDescription
noiseSeedinteger (int32)YesYesThe random seed used for introducing noise during sensitivity analysis.
reportPernumber (double)YesNoThe frequency (in time steps) at which results are reported.
numberOfSimulationsinteger (int32)YesYesThe total number of simulations to run for the sensitivity analysis.
parametersstring arrayYesNoA list of parameter names to vary in the sensitivity analysis.
reportOffsetinteger (int32)YesNoThe time step at which reporting should start.
algorithmstringYesYesThe algorithm to use for the sensitivity analysis.
Vensim model control example
  "control": {
      "vensim": {
          "sensitivityControl": {
              "algorithm": "M",
              "parameters": [
                  "Constant=RANDOM_UNIFORM(2,4)"
              ],
              "numberOfSimulations": 1,
              "noiseSeed": 1234
          }
      }
  },
  ...

language​

Epicenter defaults to the earliest version of a modelling language. If you are using a later version, set this property.

  • Type: string
  • Nullable: true

protections​

A model is a global namespace. To protect against unwanted variable value changes, you can introduce guards based on specific user attributes, for example, role.

  • Type: object
  • Nullable: false

Properties​

PropertyTypeNullableDescription
guardsarrayNoAn array of objects that define validation rules. Must not be empty. Each item is one of the following: InputGuard, OverwriteGuard, PrivilegeGuard, RelativeGuard, or RoleGuard.

InputGuard object properties​

PropertyTypeNullableDescription
regexstringNoA regular expression pattern to validate input. Must not be blank.
operandstringNoThe operand used in the validation logic.
operatorstringNoThe operator applied for comparison or matching during validation.

OverwriteGuard object properties​

PropertyTypeNullableDescription
regexstringNoA regular expression pattern to validate input. Must not be blank.
dialectstringYesSpecifies the dialect used for interpreting the validation logic.
initialstringNoThe initial value to apply during the overwrite operation.

PrivilegeGuard object properties​

PropertyTypeNullableDescription
regexstringNoA regular expression pattern to validate privilege rules. Must not be blank.
readstringNoSpecifies the read permissions for the privilege guard.
domainstringNoThe domain to which the privilege rules apply.
grantstringNoThe grant type that defines the level of access.
writestringNoSpecifies the write permissions for the privilege guard.
executestringNoSpecifies the execute permissions for the privilege guard.

RelativeGuard object properties​

PropertyTypeNullableDescription
regexstringNoA regular expression pattern to validate relative rules. Must not be blank.
dialectstringYesSpecifies the dialect used for interpreting the validation logic.
valuestringNoThe value used for comparison in the relative guard condition.
operatorstringNoThe operator applied in the relative validation logic (e.g., ==, !=, <, >).
keystringNoThe key or field name that the guard applies to. Must not be blank.

RoleGuard object properties​

PropertyTypeNullableDescription
regexstringNoA regular expression pattern to validate role rules. Must not be blank.
rolestringNoThe name of the role required for validation. Must not be blank.
domainstringNoThe domain to which the role validation applies.
grantstringNoThe grant type that defines the level of access.
Protections object example

    "protections": {
        "guards": [
            {
                "role": {
                    "regex": "state.players.doctor.*",
                    "grant": "ALLOW",
                    "domain": "variable",
                    "role": "doctor"
                }
            },
            {
                "overwrite": {
                    "regex": "state.internal.precondition",
                    "initial": "-1"
                }
            },
            {
                "relative": {
                    "operator": "eq",
                    "value": "42",
                    "key": "state.internal.other"
                }
            },
            {
                "input": {
                    "regex": "state.internal.precondition",
                    "operator": "lt",
                    "operand": "0"
                }
            },
            {
                "privilege": {
                    "regex": "*",
                    "grant": "DISALLOW",
                    "read": "PARTICIPANT",
                    "write": "PARTICIPANT",
                    "execute": "PARTICIPANT"
                }
            }
        ]
    },
    ...

restorations​

This object configures two key behaviors for your model runs:

note

If both snapshot and rewind are enabled, we restore from the snapshot, but still store the history for rewinds.

Properties​

PropertyTypeNullableDescription
rewindRewindMarker objectYesSettings for a model run rewind.
assemblyarray of ReplayRestoration or SnapshotRestorationYesDefines how we store the history and how we restore the run.
logstringYesDefines how we store the history if you have replay operations or rewind. For possible values, see log values below.

log values​

  • Possible values:
    • FULL: Store all state-changing operations in order they are executed.
    • TEMPORAL: Only the latest in a series of similar operations is saved for each step. (For model languages that implement a non-real-time step function). Deprecated and replaced by TEMPORAL_2.
    • TEMPORAL_2: Only the latest in a series of similar operations is saved for each step. This setting is more efficient than TEMPORAL.
  • The default value depends on the model language:
    • In Python, we save all state-changing operations.
    • In languages that have steps like Vensim, we only store the last operation on a particular variable for each step.
warning

If you do not define a rewind or any restore commands, Epicenter doesn't store history for your model runs.

RewindMarker object properties​

PropertyTypeNullableDescription
namestringYesThe name of the function that implements a time step.
argumentsobjectYesAn object describing the arguments that are part of the step function signature.
destructiblebooleanYesIf true, remove the step you are rewinding from history. In this case, the step will not be included in the restore.

ReplayRestoration object properties​

This object contains a set of commands for a full history restore.

PropertyTypeNullableDescription
operationsarray of ReplayOperation objectsYesThe restore commands.

ReplayOperation object properties​

PropertyTypeNullableDescription
operationTypestringNoThe type of restore command. Possible values: operationType values.
targetTypestringNoSpecifies the action you are taking on the target. Possible values: targetType values.
targetKeystringNoThe name of the function to call or the variable to set.

operationType values​

  • "stop_before": Stop the restore before the specified operation.
  • "stop_after": Stop the restore after the specified operation.
  • "include": Include the specified operation in the restore.
  • "exclude": Exclude the specified operation from the restore.

targetType values​

  • "execute": indicates a function call
  • "set": setting a variable value
tip

To provide several stop_before or stop_after operations would be redundant. The restore will stop at the first stop operation. You could have more than one exclude or include operations.

SnapshotRestoration object properties​

PropertyTypeNullableDescription
variablesarrayYesAn array of variable names (strings) included in the snapshot restoration.
Restorations object example
    "restorations": {
        "rewind": {
            "arguments": [
                1,
                "hello"
            ],
            "name": "step_operation",
            "destructible": false
        },
        "assembly": [
            {
                "snapshot": {
                    "variables": [
                        "variableOne",
                        "variableTwo"
                    ]
                }
            },
            {
                "replay": {
                    "operations": [
                        {
                            "operationType": "stop_before",
                            "targetType": "execute",    // this is a function call
                            "targetKey": "operation"    // the name of the function
                        },
                        {
                            "operationType": "stop_after",
                            "targetType": "set",        // setting a variable
                            "targetKey": "variable"     // the variable name
                        },
                        {
                            "operationType": "include",
                            "targetType": "execute",
                            "targetKey": "operation"
                        },
                        {
                            "operationType": "exclude",
                            "targetType": "set",
                            "targetKey": "variable"
                        }
                    ]
                }
            }
        ],
        "log": "full"
    },
    ...

workerImage​

Change the Docker worker image with this setting.

  • Type: string
  • Nullable: true

Epicenter has default Docker images for all supported languages. If you are producing a custom worker image, substitute the default image name here.

Important

Please talk to Forio support before changing this value.

dependencies​

Use this setting to provide a list of dependencies for a custom Docker image.

AptExternalDependency object properties​

PropertyTypeNullableDescription
packagestringYesThe name of the APT package to install.
repositorystringYesThe repository from which to fetch the package.
versionstringYesThe version of the package to install.

CranExternalDependency object properties​

PropertyTypeNullableDescription
packagestringYesThe name of the CRAN package to install.
versionstringYesThe version of the package to install.

GitExternalDependency object properties​

PropertyTypeNullableDescription
urlstringYesThe URL of the Git repository to clone.
scriptstringYesA script to run after cloning the repository.

JuliaExternalDependency object properties​

PropertyTypeNullableDescription
packagestringYesThe name of the Julia package to install.
versionstringYesThe version of the package to install.

NpmExternalDependency object properties​

PropertyTypeNullableDescription
packagestringYesThe name of the npm package to install.
versionstringYesThe version of the package to install.

PypiExternalDependency object properties​

PropertyTypeNullableDescription
packagestringYesThe name of the PyPI package to install.
versionstringYesThe version of the package to install.

ShellExternalDependency object properties​

PropertyTypeNullableDescription
scriptstringYesThe shell script content or path to execute.
Dependencies example
  "dependencies": [
      {
          "pypi": {
              "package": "package",
              "version": "1.0.0"
          }
      },
      {
          "apt": {
              "package": "package",
              "version": "1.0.0",
              "repository": "repository"
          }
      }
  ],
  ...

operations​

An object that lists the functions in the model.

  • Keys: The function names (string)
  • Values: OperationOptions object that contains metadata for the operation.
  • Nullable: true

OperationOptions object properties​

PropertyTypeNullableDescription
timeoutSecondsintegerYesHow long we wait for a response before it's a timeout (64-bit integer).
inertbooleanYesIf true, the operation is non-state-changing. For example, a complex operation on several variables that doesn't change any variable values.
tip

Set inert to true for operations that don't change the state. That helps avoid unnecessary operations in the history and speeds up run restore and rewind.

Operations example
  "operations": {
      "operation": {
          "timeoutSeconds": 20,
          "inert": false
      }
  },
  ...

enableStateCache​

For efficiency, Epicenter can cache the return values of non-state-changing operations and flash the cache when state is updated.

  • Type: boolean
  • Nullable: true
Important

Please reach out to Forio support if you would like to use this feature.

redirectStandardOut​

Channels your standard output to the log file.

  • Type: boolean
  • Nullable: true

startDebugger​

Indicates whether the debugger should start with the model (for languages that have a debugger).

  • Type: boolean
  • Nullable: true

inceptionGracePeriodSeconds​

How long we should wait for the model to start. The default is 180 seconds (3 minutes).

  • Type: integer
  • Format: int32
  • Minimum: 1
  • Nullable: true

minimumLogLevel​

Set this value to have Epicenter create a log for your model.

  • Type: string
  • Nullable: true

Logging can be helpful in a development environment. However, it is suggested to leave logging off unless you need it.

Possible values:

  • INFO
  • DEBUG

A debug-level log is much more detailed and requires significantly more storage space.

warning

There is no logging unless this value is set.

events​

Override defaults for event handlers. The keys are the event names, and the values are objects containing override values.

EventOptions object properties​

PropertyTypeNullableDescription
timeoutSecondsintegerYesEnter a custom timeout value for the event handler in seconds.

defaults​

Specifies the default context settings for the model.

warning

The defaults property is implemented for backward compatibility. It is a best practice to set explicit values for the properties, rather than to define the defaults.

ModelContextDefaults object properties​