Run simulations

You can trigger simulation runs manually in the CDF user interface, programmatically using the Cognite API, or schedule simulation runs in the simulation routine configuration.

Before you start

For a simulation to run, you need

• A simulator model with at least one revision.
• A simulator routine with at least one revision.
• An active connector associated with your routine.

Trigger runs manually

Navigate to Data management > Build solutions in the CDF user interface and initiate a simulation run directly by selecting ▶ on a simulator routine. This is typically used for testing routines or running one-off simulations.

By default, manual triggers use the latest model and routine revisions, and runType is set to manual. Set runTime to the trigger moment.

Trigger runs programmatically

Use the Simulators API to trigger simulations programmatically. Set up triggers using the API to integrate with external systems and workflows. runType is set to external. Using the API gives detailed control over execution parameters.

Schedule trigger runs

Configure routines to run automatically at specified times on a given frequency by setting up the schedule in the simulation routine. Scheduled triggers use cron expressions to define precise timing.

Scheduled triggers use the latest model and routine revisions, and runType is set to scheduled.

Note

If the connector is offline when the simulation is scheduled to run, the simulation is skipped. The connector only runs future schedules. Consider this limitation when using the native scheduling feature.

Configuration parameters

Resource selection

Parameter	Description
Default behavior	The simplest approach is to specify only the routineExternalId, which will use the latest revisions of both the routine and its associated model.
Version control	For more control, you can specify both routineRevisionExternalId and modelRevisionExternalId to run simulations using specific historical versions of models and routines. This enables you to simulate past scenarios using model and routine configurations that were valid at that time.

Timing Controls

• Run-time: Define when the simulation should take place. For manual and API triggers, if not specified, defaults to the current time when the trigger is initiated. For scheduled runs, it matches the schedule time.

Input Overrides

You can override any input defined in the routine:

• Both constant values and time series references can be overridden
• Numerical inputs accept values in any compatible unit of the same quantity
• Overrides must maintain the same value type as defined in the routine revision
• All inputs (constant, sampled, and overridden) are stored in the simulation data

Execution Settings

• Queue parameter: Set to true to ensure simulation runs are created even when the associated connector is offline.
• Log severity: Control the level of detail in execution logs, which is particularly useful for troubleshooting.

Simulation status lifecycle

Understanding how a simulation progresses through its lifecycle helps you track and manage your simulations effectively. Each simulation goes through three distinct phases from creation to completion.

Phase 1 - Creation. When you first trigger a simulation run, the API creates the simulation run resource, assigns a unique id and logId for tracking purposes, records the exact creation time, and sets status to ready. The simulation then waits in this state until a connector is ready to process it.

Phase 2 - Execution. Once the connector picks up the simulation, status is set to running. The connector actively processes the simulation according to the configured routine.

Phase 3 - Completion. The connector performs one last update to lastUpdatedTime, and sets status to success or failure. The simulation logs and results become available for analysis. Note that if the simulation fails, output data may be incomplete or missing, but logs can be consulted for troubleshooting.

Accessing results

Once a simulation completes, there are different resources which might be of interest:

Simulation data

The simulation data endpoint provides the complete record of each simulation run. This includes all input values used during the simulation, whether they were constant values, overrides, or sampled from time series and the outputs generated during the simulation. This data serves as the primary source of truth for simulation results and provides complete traceability of the simulation process, including both the values and their associated units.

Time series data

For numerical values that have been configured to be saved as time series, the connector automatically stores both inputs and outputs as time series data points. Each data point has the timestamp of the simulation time, that lets you to track trends across multiple simulation runs and compare results from different configurations. This integration with time series data makes it easy to analyze simulation results alongside other operational data in your CDF project.

Execution logs

The execution logs provide detailed information about how your simulation ran, accessible using the simulation's logId. The logs capture the step-by-step progression of the simulation, with the level of detail determined by your configured log severity. Use the logs for troubleshooting failed simulations and understanding how your simulation executed.

Important timestamps

Timestamp	Description
Run Time	Acts as the reference point for all data preprocessing activities and determines which input data will be considered for the simulation.
Simulation Time	Represents when the input data was actually sampled and is used to index your results. Read more about how this timestamp is calculated in the data sampling guide.
Created Time	When simulation run resource is created by the API.
Last Updated Time	Changes throughout the simulation's lifecycle to track its progress through different stages.

Best practices

Model management

Maintaining accurate and up-to-date simulation models is important to obtain representative and reliable results. Keep your models calibrated with any changes to your physical assets, and use version control to track modifications over time. Document all changes to models, including the reasoning behind updates, to maintain a clear history of model evolution.

Resource optimization

Effective resource management requires balancing simulation frequency with available computational resources and license usage. Consider how often you really need updated results and adjust run schedules accordingly. For complex simulations or high-frequency requirements, consider distributing routines across multiple connectors to optimize resource usage and ensure reliable execution.

Data quality

Implementing robust data validation methods is also important for representative and reliable simulation results. Configure appropriate validation rules to ensure input data meets quality standards before running simulations. Regularly monitor input data quality and validate simulation results against expected ranges and patterns. Use the data validation methods provided by CDF to automatically check for data quality issues.

Result management

Be aware that simulation runs and logs are subject to retention policies. See the API documentation for current limits. If you need to maintain permanent records of simulation runs and their associated logs, establish a data workflow to copy data into a permanent storage before the retention period expires.