sitemap.xml llms.txt
Skip to main content

Run Entities

These entities are used by the Run adapter and encapsulate data objects used by the Epicenter Run API.

Enums​

MORPHOLOGY​

Denotes the type of run.

Possible values:​

  • MORPHOLOGY.MANY = 'MANY' - A regular model run with a randomly generated unique key.
  • MORPHOLOGY.SINGULAR = 'SINGULAR' - Denotes a singular run.
  • MORPHOLOGY.PROXY = 'PROXY' - Denotes a singular run with an open HTTP endpoint useful for fine grained permission elevation of client calls.

Interfaces​

ModelContext​

Contains overrides for model context values.

Properties​

  • version (string): The model context version. Possible values:
    • "V1"
    • "V2"
  • variables (Record<string, VariableOptions>, optional): The run state variables that need to be stored and their processing options.
  • externalFunctions (Record<string, WireExternalFunction>, optional): A mapping of external function names to WireExternalFunction objects, allowing integration with external logic or systems.
  • modelVersion (number, optional): The numerical version identifier of the model.
  • mappedFiles (Record<string, string>, optional): A mapping of model context files for different simulation scenarios.
  • control (ExcelModelControl | JavaModelControl | PowersimModelControl | VensimModelControl, optional): An object with settings specific to the model language.
  • language (string, optional): The primary programming or modeling language used for this model context.
  • protections (Protections, optional): Protection settings for state variables.
  • restorations (Restorations, optional): Settings defining how a model run gets restored.
  • workerImage (string, optional): The Docker worker image.
  • dependencies (AptExternalDependency | CranExternalDependency | GitExternalDependency | JuliaExternalDependency | NpmExternalDependency | PypiExternalDependency | ShellExternalDependency, optional): A list of external dependencies for the model.
  • operations (Record<string, OperationOptions>, optional): A mapping of operation names to OperationOptions objects that define how the operations are executed.
  • defaults (ModelContextDefaults, optional): Specifies the default context settings for the model.
  • enableStateCache (boolean, optional): If true, cache the values of non-state-changing operations.
  • redirectStandardOut (boolean, optional): If true, redirects the standard output (stdout) stream to a log file.
  • startDebugger (boolean, optional): If true, starts the debugger (for languages that have a debugger).
  • inceptionGracePeriodSeconds (number, optional): How long we should wait for the model to start. The default is 180 seconds (3 minutes).
  • minimumLogLevel (string, optional): The minimum severity level of the log.
  • events (Record<string, EventOptions>, optional): A mapping of event names to EventOptions objects that control event-handling.

ExecutionContext​

Represents the execution context for a run.

Properties:​

  • presets (Record<string, Record<string, unknown>>, optional): A mapping of variables that you want pre-set on a run.
  • mappedFiles (Record<string, string>, optional): A mapping of context files.
  • version: string - The version of the execution context. Possible values: "V1".
  • tool (StellaModelTool | VensimModelTool, optional): An object containing language specific properties for the model.

StellaModelTool​

Represents Stella-specific execution options for a model run.

Properties:​

  • objectType: 'stella' — Identifies the tool as a Stella model tool.
  • gameMode (boolean, optional): If true, run the model in game-mode. This allows for an interactive step-by-step model run.

VensimModelTool​

Represents Vensim-specific execution options for a model run.

Properties:​

  • objectType: 'vensim' — Identifies the tool as a Vensim model tool.
  • sensitivityMode (boolean, optional): If true, this is a sensitivity run.
  • cinFiles (string[], optional): A list of CIN file names to be used to load external data at runtime.

ProcActionable​

Represents a procedure execution.

Properties:​

  • name: string - The name of the procedure to execute.
  • arguments (unknown[], optional): An array of arguments to pass to the procedure.
  • objectType: 'execute' - Identifies the actionable as a procedure execution.

GetActionable​

Represents a variable value retrieval.

Properties:​

  • name: string - The name of the variable to retrieve.
  • objectType: 'get' - Identifies the actionable as a retrieval operation.

SetActionable​

Represents a variable value assignment.

Properties:​

  • name: string - The name of the variable to set.
  • value: unknown - The value to assign.
  • objectType: 'set' - Identifies the actionable as a set operation.

MetadataFirstPop​

Represents a metadata pop operation that removes the first element.

Properties:​

objectType: 'first' - Identifies the pop operation as targeting the first element.

MetadataLastPop​

Represents a metadata pop operation that removes the last element.

Properties:​

objectType: 'last' - Identifies the pop operation as targeting the last element.

MetadataAllPop​

Represents a metadata pop operation that removes all elements, optionally filtered by a value.

Properties:​

  • objectType: 'all' - Identifies the pop operation as targeting all elements.
  • value (unknown, optional): A value used to determine which elements should be removed.

MetadataUpdate​

Represents a set of metadata update operations.

Generics:​

Extends RunMetadata - the metadata object type being updated. Defaults to RunMetadata.

Properties:​

  • pop (Partial<Record<keyof M, MetadataPop>>, optional): Defines pop operations to apply to metadata fields.
  • set (Partial<M>, optional): Defines metadata fields and values to set or overwrite.
  • push (Partial<M>, optional): Defines metadata fields and values to append.

Types​

MetadataPop​

MetadataPop is a union type that defines the supported strategies for removing values from a metadata field:

RunVariables​

Record<string, unknown>

Represents the shape of variables associated with a run.

This type defines a generic key-value mapping where:

  • Keys are variable names (string)
  • Values can be of any type (unknown)

RunMetadata​

Record<string, unknown>

Represents the shape of metadata associated with a run.

This type defines a generic key-value mapping where:

  • Keys are metadata field names (string)
  • Values can be of any type (unknown)

RunReadOutView​

RunReadOutView is used by the Run adapter functions and contains properties of a run. It is a generic type that allows you to strongly type both the run variables and metadata.

Type parameters​

Properties:​

  • runKey: string - The unique identifier of the run.
  • scope: { userKey?: string } & GenericScope - The scope of the run. Combines GenericScope with optional userKey for user-specific scope.
  • permit?: Permit - The permit defining read and write access.
  • variables?: V - The run variables object, typed according to the generic parameter V.
  • metaData?: M - The run metadata object, typed according to the generic parameter M.
  • executionContext?: V1ExecutionContext - Execution context used during model initialization.
  • modelFile?: string - The name of the model file used for the run.
  • modelVersion?: number - The version of the model used to create the run.
  • modelLanguage?: string - The programming language of the model.
  • grammar?: string - The grammar associated with the model.
  • trackingKey?: string - A string that you can assign to a run for tracking purposes.To track the run, perform a search for the trackingKey value.
  • morphology?: string - One of the values of the MORPHOLOGY enum.
  • perpetual?: boolean - Indicates whether the run is perpetual.
  • cloud?: string - Cloud execution environment identifier.
  • cluster?: string - Cluster identifier where the run is executed.
  • allowChannel?: boolean - Indicates whether push notifications are enabled for the run.
  • hidden?: boolean - Indicates whether the run is hidden.
  • marked?: boolean - Indicates whether the run has been marked.
  • closed?: boolean - Indicates whether the run is closed.
  • runState?: string - The current state of the run.
  • tombstone?: string - Indicates a deletion marker or archived state.
  • created?: string - Timestamp of when the run was created.
  • lastModified?: string - Timestamp of the last modification.
  • lastOperated?: string - Timestamp of the last operation performed on the run.
  • address?: Address - The storage address associated with the run.
  • user?: PseudonymReadOutView - A PseudonymReadOutView object the user who started the run (for single-user runs).

Actionable​

This union type implements:

Type aliases​

RunCreateOptions​

Defines options for creating a run.

Properties:​

  • readLock?: keyof typeof ROLE - (Optional) Read lock level. Part of the permit for the run.
  • writeLock?: keyof typeof ROLE - (Optional) Write lock level. Part of the permit for the run.
  • ephemeral?: boolean - (Optional) If true, the run will only exist so long as its in memory. Nothing is written to the database, history, or variables.
  • trackingKey?: string - (Optional) A string that you can assign to a run for tracking purposes.To track the run, perform a search for the trackingKey value.
  • modelContext?: ModelContext - (Optional) Context information for the model.
  • executionContext?: ExecutionContext - (Optional) Execution context for the model on this run.
  • allowChannel?: boolean - (Optional) Whether channel access is allowed.
  • RoutingOptions - Additional routing options.

RunStrategy​

Defines the strategy for handling runs.

Possible values:

  • 'reuse-across-sessions' -- will get the most recent run for the given scope, creating it if it does not exist
  • 'reuse-never' -- will create a new run every time
  • 'reuse-by-tracking-key' - Reuse a run identified by a tracking key.
  • 'multiplayer' - Supports multiple players interacting in the run.