forio Toggle navigation

Model Context

In addition to your model code, you can optionally include additional information about the context in which your model should be run. This context information determines how your project is configured in the Epicenter backend.

There are two formats for specifying your model context information:

  • In a *.cfg file ("configuration file" or "config file"), which is required if you are using the v1 Epicenter APIs to create runs for your project. See more on the .cfg file format.
  • In a *.ctx file ("context file"), which is required if you are using the v3 or later Epicenter APIs to create runs for your project. See more on the .ctx file format.
  • In either a *.ctx or *.cfg file if you are using the v2 Epicenter APIs.

Important: Not sure which API versions you are using?

  • If you don't do anything special, or if you are using Epicenter.js version 1.8.1 or earlier, or if you are using Flow.js version 0.10.0 or earlier, then you're using v1.
  • If you are prefacing your REST API calls with "/v2/", or if you are using Epicenter.js version 2.0 or later, then you're using v2.
  • The v3 Epicenter APIs are not yet publicly available.

Creating and Naming the Context File

Your context file must have the same name as your primary model file. For example, if your model is "my_model.py", then your context file must be "my_model.ctx". It must be saved in your project's Model folder.

The context file is a text file that contains a single JSON object.

Model Context Options

Key Value Default Modeling Languages Example
language Optional. The modeling language for this simulation.

The modeling language is automatically set based on the file extension of the model file used to create the run. Setting the language in the model context file overrides the language derived from the model file extension.
Automatically set based on the file extension of the model file used to create the run.

If you are using the v1 or v2 Epicenter APIs (see above), and your model file ends in .py, the default is to use Python 2.
Python, R, Vensim, Powersim, Julia. Options are:
  • python2
  • python3
  • r
  • vensim
  • powersim
  • julia
mappedFiles Optional. An object with key : value pairs for files to be read by your model. Each key may be used as an identifier in your model code. Each value must be the name of a file in your Model folder. None: If not included, no file identifiers are available for use within your model.

(However, you can still load files directly from your model file. For example, in R: mydata <- read.table("historic_data.csv") if "historic_data.csv" is in your project's Model folder. )
Python, Julia, R, Vensim "mappedFiles": { "myData": "historic_data.csv" } means you can use the identifier myData in your model code to access the "historic_data.csv" file.
restorations Optional. Information about how to restore runs from the Epicenter database back into memory, so that you can update variables and call operations. (See more background on run persistence.)

This is an array, and each run is restored following the instructions in each element of the array, one after the other.
If not included in the model context file, the default value is "restorations": [{ "replay": {} }], meaning all commands in the run's history are replayed, in order, when the run is brought back into memory. Python, Julia, R, Vensim, Powersim It is most common to not include this option in your model context file, which means your projects will use the default behavior of replaying all commands in the run's history.

To force the restoration to do nothing, set this to an empty array: "restorations": []. Otherwise, see examples below for the replay and snapshot objects.
restorations[{"replay": {}}] The run is restored by re-executing all of the end user interactions (including updating model variables and calling model operations), from the creation of the run up to the time it was last persisted in the database. If no operations are listed, all of the end user interactions are re-executed.

Optionally, the replay object can include an operations object with an array of operations to NOT replay. Each operation (array element) is an object including commandType, commandName, and operationType for the command to replay. You can check the Model State API to view the commands for a run to confirm which you want to include or not in the restorations here.
Python, Julia, R, Vensim, Powersim When the run is retrieved from the database, advance the run only up until the first occurrence of the "step" operation: "restorations": [{"replay": {"operations": [ {"commandType": "proc", ...} ]} }]
restorations[{"snapshot": {}}] The run is restored by copying in variables listed. Specific end user inputs and operations are NOT replayed. If no variables are listed, then no variables are restored. Python, Julia, R, Vensim, Powersim Restore two variables:

"restorations": [ {"snapshot": {"variables": ["varName1", "varName2"] } } ]

Restore no variables: "restorations": [{ "snapshot": {} }]
simulation None. This is a top-level object. n/a Python, Julia, R, Vensim, Powersim n/a
simulation.reportPer Optional. This is how often the values of variables are reported, in Vensim TIMESTEP units. 1 Vensim Sometimes models are very granular in order to properly model the underlying equations, however, not every value needs to be available for end users to view or manipulate.
simulation.save Optional. Whether or not the variables should be saved. false Vensim Explicitly not saving some variables may help performance in large models.
simulation.savePer Optional. This is how often, in Vensim time units, the values of variables are saved. The default value is the "SavePer" value in the Vensim model. Vensim Even if your model is doing calculations based on a large number of time steps, you may only care about the values at particular steps (e.g. years, if you are modeling each time unit as a year).
variables None. This is a top-level object. n/a Python, Julia, R, Vensim, Powersim n/a
variables.[varName].simulation None. This is a top-level object. n/a Python, Julia, R, Vensim, Powersim n/a
variables.[varName].simulation.reportPer Optional. This is how often the values of variables are reported, in Vensim TIMESTEP units. Defaults to the value of simulation.reportPer (which itself defaults to 1). If provided, overrides that value for this variable only. Vensim Sometimes models are very granular in order to properly model the underlying equations, however, not every value needs to be available for end users to view or manipulate.
variables.[varName].simulation.save Optional. Whether or not the variable should be saved. Defaults to the value of simulation.save (which itself defaults to false). If provided, overrides that value for this variable only. Vensim, Powersim Explicitly not saving some variables may help performance in large models.
variables.[varName].simulation.savePer Optional. This is how often, in Vensim time units, the values of variables are saved. Defaults to the value of simulation.savePer (which itself defaults to the "SavePer" value in the Vensim model.) Vensim Even if your model is doing calculations based on a large number of time steps, you may only care about the values at particular steps (e.g. years, if you are modeling each time unit as a year).
version Optional. The version of the Model Context structure. If not included, assumed to be v1. Python, Julia, R, Vensim, Powersim "version": "v1"
workerImage Optional. The name of the Epicenter backend server ("worker") to use with this model. If not provided, the default value is default. Python, Julia, R, Vensim, Powersim Options are:
  • default: there is a default worker for all languages
  • sklearn: for Python only, you can choose to run your model on a server that already includes the "scikit-learn" library.

Model Context Examples

Python.

This example sets the model language to Python 3.

{
    "language": "python3"
}

Vensim.

This example includes a reference to an external file (here, an Excel file) with data to load as part of the model. (See more detailed steps on using external data in Vensim.)

Additionally, this example explicitly lists two model variable that should be saved with each time step: Price and Profit. Other model variables will not be saved. Explicitly not saving some variables — such as those that are internal to the model calculations, and never exposed to users — may help performance in large models.

{
    "mappedFiles": { "data": "data.xlsx" },
    "simulation": {
        "save": false
    },
    "variables": {
        "Price": {
            "simulation": {
                "save": true
            }
        },
        "Profit": {
            "simulation": {
                "save": true
            }
        }
    }
}

Creating and Naming the Configuration File

Your configuration file must have the same name as your primary model file. For example, if your model is "my_model.py", then your configuration file must be "my_model.cfg". It must be saved in your project's Model folder.

The configuration file is a text file that contains a single JSON object.

Model Configuration Options

Key Value Default Modeling Languages Example
environment None. This is a top-level object. n/a All n/a
environment.workerImage Optional. The name of the Epicenter backend container ("worker") for this modeling language. The default for Python is the Python2 worker (Python 2.7.6). Other languages only have one valid option; if this option is not present, it defaults to the current (most up-to-date) worker for that language. All Options are:
  • Forio SimLang: standard-1.0
  • Julia: standard-1.0
  • Python: python3-standard-1.0 (Python 3.4), standard-1.0 (Python 2.7.6)
  • R: standard-1.0
  • Vensim: standard-1.4
files Optional. The files object describes external files (for example, Excel files) with data to load as part of the model. Inside the files object, include a key : value pair for each file included. Each name can be any designation you like (for example: data or file1). The value is name of the file to load. This file must be in your project's Model folder. n/a Vensim For example: "files": {"data": "myData.xlsx"} or "files": {"file1": "myFirstFile.xlsx", "file2": "mySecondFile.xlsx"}. Note that in addition to listing the files here, you also need to pass this files object as an argument when you create a run. For more information on working with external resources, see How To: Use External Data in Vensim.
model None. This is a top-level object. n/a All n/a
model.autoRestore Describes when runs should be restored (replayed) into memory from the database. (See more on Run Persistence.) Runs must be in memory in order for you to update variables or call operations on them. If not included, the default value is change. All Possible values are:
  • none: Never restore a run.
  • always: Always restore a run.
  • change: Only restore a run if needed, that is, if a model variable is being updated or a model operation is being called.
model.restoreMode Optional. Describes how restoring runs should occur. By default, runs are restored (if needed) when model operations are called or model variables are updated. They are also explicitly restored when you call the Model State API to bring an existing, persisted run from the database back into memory. The default value is REPLAY if restoreMode is not included in the .cfg file, or if there is no .cfg file. Python, R, Julia Options are:
  • REPLAY: when a run is restored, all of the end user interactions, from the creation of the run up to the time it was last persisted in the database, are re-run.
  • SNAPSHOT: the run is instead restored only by copying in variables that have a restore attribute of true (see below). Specific end user inputs and operations are NOT replayed.
model.restore Optional. Governs whether variables are copied into the run when the run is replayed, if the run is using restoreMode: "SNAPSHOT". The default value is false. Python, R, Julia
  • If set to true, all of the model variables are copied into the run when the run is replayed, if the run is using restoreMode: "SNAPSHOT".
  • If set to false, only the model variables with variables.[variableName].restore property set to true are restored.
model.reportPer Optional. This is how often the values of variables are reported, in Vensim TIMESTEP units or SimLang TimeStep units. 1 Forio SimLang, Vensim Sometimes models are very granular in order to properly model the underlying equations, however, not every value needs to be available for end users to view or manipulate. For example, the combination of an M TimeStep 0.5 in your SimLang model and "reportPer": 2 in your .cfg file means that your variables are reported once each time unit.
model.savePer Optional. This is how often, in Vensim or SimLang time units, the values of variables are saved.
  • In SimLang, the default value is 1.
  • In Vensim, the default value is the "SavePer" value in the Vensim model.
Forio SimLang, Vensim Even if your model is doing calculations based on a large number of time steps, you may only care about the values at particular steps (e.g. years, if you are modeling each time unit as a year).
model.subscriptFormat Optional. For accessing Vensim arrayed variables, specify whether the step (the array index) is the first or last index passed in during a request to read or write this variable. Valid values are time_first and time_last. time_last Vensim Suppose you have the variable: price[apple, orange, banana].
  • If you want the value from the second step, with time_last, you request price[apple,2].
  • If you want the value from the second step, with time_first, you instead request price[2,apple].
For arrayed constants, there is no time index.

Important: In the model context file, there is no way to specify this; the time step is always the last index.
model.timeFormat Optional. If provided, must be vector. vector Vensim "timeFormat": "vector"
variables None. This is a top-level object. n/a All n/a
variables.[varName] None. This is an enclosing object. n/a All n/a
variables.[varName].restore Optional. This property allows you to override the model.restore property for particular variables. That is, it governs whether variables are copied into the run when the run is replayed, if the run is using restoreMode: "SNAPSHOT". The default value is the value of model.restore (which, if not specified, defaults to false). Python, R, Julia
  • If set to true, this model variable is copied into the run when the run is replayed, if the run is using restoreMode: "SNAPSHOT".
  • If set to false, this model variable is not copied into the run.
variables.[varName].resetDecision Optional. Describes whether the decision is recalculated at each time step. This property is available only at the variables level. This property is optional. If not included, the default value is false. Forio SimLang "variables": { "Price": { "resetDecision": "true" } }
variables.[varName].save Optional. Whether or not the variable should be saved. This property is available only at the variable level. This property is optional. Including a savePer in the entry for this variable implies save with a value of true. If both save (at the variable level) and savePer (at either the model or variable level) are not included, the variable is saved. Forio SimLang, Vensim Explicitly not saving some variables may help performance in large models. For example, in Forio SimLang models typically you only need to save those decisions ("D" variables, or model elements subject to user control) and variables ("V" variables, or model elements calculated each time step) that you want to display directly to the user.
variables.[varName].savePer Optional. This is how often, in Vensim or SimLang time units, the values of variables are saved. The default value is the value of model.savePer (which, if not specified, defaults to 1 for Forio SimLang models or the "SavePer" value in the Vensim model). Forio SimLang, Vensim Even if your model is doing calculations based on a large number of time steps, you may only care about the values at particular steps (e.g. years, if you are modeling each time unit as a year).
variables.[varName].timeFormat Optional. If provided, must be vector. vector Vensim "variables": { "Price": { timeFormat": "vector" } }

Model Configuration Examples

Python.

This example sets the Python version to 3.4 instead of the default 2.7.6. (No .cfg file is needed if you prefer 2.7.6.)

Also, this example sets the model's restore mode to "snapshot." Because the model.restore property is set to true, all recorded variables are copied into the restored run except for variables with explicit properties of restore set to false (such as "profit" in the example below).

{
    "environment": {
        "workerImage": "python3-standard-1.0"
    },
    "model": {
        "restoreMode": "SNAPSHOT",
        "restore": true // all recorded variables are restored
    },
    "variables": {
        "profit": {
            "restore": false  // except for Profit 
        }
    }
}        

As an alternative, this example also sets the restore mode to "snapshot," but explicitly marks each variable with a restore property value of true that will be copied into the run.

{
    "environment": {
        "workerImage": "python3-standard-1.0"
    },
    "model": {
        "restoreMode": "SNAPSHOT",
        "restore": false // none of the recorded variables are restored
    },
    "variables": {
        "time": {
            "restore": true  // except for Time
        }
    }
}

Vensim.

This example sets saving and reporting preferences for several model variables. It also includes a reference to external files (here, an Excel file) with data to load as part of the model.

{
    "environment": {
        "workerImage": "standard-1.4"
    },
    "files": {
        "data": "myData.xlsx"
    },
    "model": {
        "timeFormat": "vector",
        "subscriptFormat": "time_last",
            // reportPer is twelve times per time unit, 
            // implying Vensim TIMESTEP of 0.08333
        "reportPer": 12, 
        "savePer": 1
    },
    "variables": {
        "Sales": {
            "timeFormat": "vector",
            "save": true
        },
        "Revenue": {
            "timeFormat": "vector",
            "savePer": 0.25 // four times per time unit
        },
        "Total Revenue": {
            "timeFormat": "vector",
            "savePer": 1
        }
    }
}