Simulators API

The Simulators API uses several Cognite Data Fusion (CDF) 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

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

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 and model revisions

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.

Simulator Routines and routine revisions

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.

Each routine is bound to a specific connector, which manages scheduling and execution. 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 load by creating multiple connectors and assigning routines across them for a manageable workload per connector.

Simulation Runs and simulation data

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

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.