Simulators API - Cognite Docs

The Simulators API uses several Cognite API resources to enable comprehensive simulation operations. These resources work together to provide a complete system for managing simulation operations, from model definition to results analysis. Simulators contains the definitions necessary for CDF to interact with a given simulator. This resource serves as a central contract for APIs, user interfaces, and connectors to use the same definitions when dealing with a specific simulator. Each simulator is uniquely identified and can be associated with various file extension types, model types, step fields, and unit quantities. Simulators are essential for managing data flows between CDF and external simulation applications, ensuring consistency and reliability in data handling. Simulator Integrations represents a simulator connector in CDF. This resource provides information about the configured connectors for a given simulator, such as status, data set, name, license status, connector version, simulator version. While the simulator connector is the active service performing the actual work, the simulator integration serves as its digital identity in CDF, providing real-time status monitoring through heartbeat information and managing relationships with other resources. This resource is essential for monitoring and managing the interactions between CDF and external simulation applications, ensuring proper data flow and integration. Simulator Models represent an asset modeled in a simulator. For instance, an asset can be a pump, a well, a processing facility, or a refinery. The simulator model is the root of its associated revisions, routines, runs, and results. The data set assigned to a model is inherited by its children. Deleting a model also deletes all its children, thereby maintaining the integrity and hierarchy of the simulation data. Simulator Model Revisions track changes and updates to simulator models to make sure modifications are traceable and to understand the evolution of a given model. Model revisions are immutable once created, providing reliable version control and history tracking. When a revision is created, a connector attempts to parse the model file, recording the success or failure of this operation. The parsing process can generate additional Simulator Model Revision Data, which contains extracted information from the simulator file. This data resource includes structured information about the simulator model file. The type and extent of information extracted varies by simulator type and connector implementation, enabling the extraction of valuable metadata about the model’s internal structure and configuration.

Model revision limit

Each simulator model can have up to 200 revisions. On POST /simulators/models/revisions, set deleteOldest to true on the request to create a new revision and delete the oldest revisions afterward, keeping only the newest 200. The parameter defaults to false. There is no connector configuration setting, and Simulators in CDF does not set this field. Rolling delete requires the simulators:delete capability on the relevant data set scope. See Simulators users. Without delete access, CDF returns HTTP 403 Forbidden. If deleteOldest is false or omitted and the model already has 200 revisions, CDF returns HTTP 422 with this message: Resource limit exceeded for simulator model revision. Max 200 per model.

When rolling delete removes a model revision, CDF also deletes all simulation runs that reference that revision, not only scheduled runs.

Example request body:

{
  "items": [
    {
      "externalId": "pump-model-rev-201",
      "modelExternalId": "pump-model",
      "fileId": 1234567890123456
    }
  ],
  "deleteOldest": true
}

Simulator Routines defines instructions for interactions with a simulator model. A simulator routine includes comprehensive specifications for how simulations should be executed, including inputs (values set into the simulator model), commands (actions to be performed by the simulator), and outputs (values read from the simulator model). Simulator routines can have multiple revisions, enabling users to track changes and evolve the routine over time. Each model can have multiple routines, each performing different objectives such as calculating optimal operation setpoints, forecasting production, benchmarking asset performance, and more. Simulator Routine Revisions enable version control of routine configurations, to track changes and evolve the routine over time. A routine revision consists of a configuration section and a script section. The configuration section defines settings for automated execution, data sampling parameters, and input/output specifications. The script section contains ordered groups and steps that define the execution sequence, with step types and arguments based on the simulator’s capabilities. By default, a simulator routine references a simulator integration, so schedules and runs stay on that connector. Connectors use a queue system to manage simulation runs triggered by schedules and API calls, with configurable timeout settings to handle scenarios where incoming load exceeds processing capacity. You can distribute the load by creating multiple connectors and assigning routines across them for a manageable workload per connector. When you enable Simulation run load balancing (preview) for your CDF project, runs wait in a shared FIFO queue (first in, first out). CDF assigns each run to one healthy registered connector (exactly-once execution: one run, one connector). For higher throughput, install, configure, and start additional connector services on the machines where your simulators run. CDF does not create connector instances or run connector services in the cloud for you. See Run simulations for how run status reflects assignment and execution. Connectors poll CDF for assigned runs on a configurable interval (connector.fetch-runs-interval), apply timeouts to stale runs, and emit logs when incoming load exceeds capacity. Every time a simulation routine executes, a simulation run object is created to make sure each routine execution is documented and traceable. The simulation run tracks execution status, progress, timestamps, and configuration details throughout a defined lifecycle. Each run has an associated Simulation Data resource, which stores the inputs and outputs of a simulation run, capturing the values set into and read from the simulator model for traceability and integrity of the simulation data. Simulation runs provide a historical record of the simulations performed for you to analyze and compare different runs, track changes over time, and make informed decisions based on the simulation results. Simulator Logs provide detailed tracking of all system activities, including simulation runs, model parsing operations, and generic connector activities. Each log entry includes timestamp information, severity level, detailed messages, and any error information. These logs are essential for monitoring system health, debugging issues, auditing operations, and understanding system behavior. The logging system supports different severity levels to control the amount of detail captured, making it easier to focus on relevant information during troubleshooting or analysis.

​Model revision limit

Model revision limit