Configure simulation routines

Configure simulation routines to run simulations. Routines include scheduling information, data preprocessing settings, input and output mapping, and execution steps. Simulator routines can have multiple revisions to track changes and evolve the routine. Each model can have multiple routines, each performing different tasks, such as calculating optimal operation set points, forecasting production, and benchmarking asset performance.

Simulator routines can be considered as "folders" that organize different versions of simulation instructions. Each routine represents a specific objective you want to achieve with your model. For example, a well model might have separate routines for daily production optimization, monthly performance forecasting, equipment sizing studies, and what-if scenario analysis.

Note

Each routine revision is immutable. Once it's created, you can't modify the configuration or script. When you need to make changes, create a new revision. This ensures you maintain a complete history of your simulation configurations and can track how your routines evolve over time.

Before you start

Consider the input data to the simulator. These are the values set into the simulator model. You can use constant values or time series, such as data from process sensors. For time series, make sure to consider data sampling.
Plan the execution steps to issue to the simulator. Each simulator may support different steps, which are defined in the stepFields property of the simulator resource in CDF.
Decide which output data to read from the simulator. These are the values read from the simulation model. All connectors provided by Cognite support unit management, so you can define the units of the input and output values.

Note

The script in a routine determines the order of how the connector sets the input, issues commands, and fetches outputs.

Routine revision structure

Identification uniquely identifies the revision and links it to its parent routine.
Configuration:
- Schedule defines if or when the routine should run automatically.
- Data sampling controls how time series data is processed.
- Input configuration specifies values to set in the simulator.
- Output configuration defines values to read from the simulator.
Script is an ordered list of stages and steps that define the execution sequence.

Configure input

Constant inputs are values that remain constant across simulation runs for a given routine revision. You can override these values when you trigger individual simulation runs. Unit specification is optional for numeric types. This input type is useful for parameters that rarely change but might need occasional adjustments. Valid value types:

STRING for text values.
DOUBLE for numeric values.
STRING_ARRAYfor arrays of text.
DOUBLE_ARRAYfor arrays of numbers.

Time series inputs read values from CDF time series data points. You can override these values when you trigger individual simulation runs. Only the DOUBLE value type is valid. This input type is useful for dynamic parameters that typically come from sensors. The processing of this input depends on the data sampling configuration:

Latest value if data sampling is disabled.
Aggregated values based on sampling settings if this is enabled.

Configuration parameters

Common parameters for both input types:

Parameter	Description
`referenceId`	A unique identifier used to link the input with the script steps.
`name`	A human-readable description.
`unit`	Optional, but required to specify the unit of measure for numeric values.
`saveTimeseriesExternalId`	Stores input values to time series data points. This is only used for the `DOUBLE` value type. This parameter is optional.

Time series input parameters:

Parameter	Description
`sourceExternalId`	References the source time series to read from.
`aggregate`	Specifies how to aggregate values within the sampling window.

Configure output

Outputs define the values to read from the simulator. Each output requires these parameters:

Parameter	Description
`referenceId`	Links the output with script steps.
`name`	A human-readable description.
`valueType`	The same options as inputs.
`unit`	Enable unit awareness and conversion for numeric values. This parameter is optional.
`saveTimeseriesExternalId`	Stores output values to time series data points. This is only used for the `DOUBLE` value type. This parameter is optional.

Script

The script defines the execution sequence using ordered stages and steps. Each stage can contain multiple steps, and all steps within a stage execute sequentially. Steps are arranged into stages for better organization, and each stage and step has an order field that determines the execution sequence. Use the description fields to provide documentation for each step or stage.

The step types and syntax vary by simulator, and the simulator resource in CDF defines available step types and syntax.

Example

This example shows a simple routine configuration for a system calculation using a PROSPER simulator.

{
  "externalId": "SystemCalculation-LER-WELL-A2-v1",
  "routineExternalId": "SystemCalculation-LER-WELL-A2",
  "configuration": {
    "schedule": { "enabled": true, "cron_expression": "0 * * * *" },
    "dataSampling": { "enabled": true, "validationWindow": 60, "samplingWindow": 60, "granularity": 1 },
    "logicalCheck": [
      {
        "enabled": true,
        "timeseriesExternalId": "AP07-019THP-PSI2120.PV",
        "aggregate": "average",
        "operator": "ge",
        "value": 80
      }
    ],
    "steadyStateDetection": [],
    "inputs": [
      {
        "name": "RateMethod",
        "value": "2",
        "valueType": "STRING",
        "referenceId": "RateMethod",
      },
      {
        "name": "Tubing Head Pressure",
        "referenceId": "THP",
        "unit": { "name": "psig", "quantity": "Pressure" },
        "sourceExternalId": "AP07-019THP-PSI2120.PV",
        "aggregate": "average",
        "saveTimeseriesExternalId": "SystemCalculation-LER-WELL-A2-INPUT-THP"
      },
      {
        "name": "ClearSensDB",
        "value": "1",
        "valueType": "STRING",
        "referenceId": "ClearSensDB",
      }
    ],
    "outputs": [
      {
        "name": "Gas Flowrate",
        "referenceId": "GasRate",
        "unit": { "name": "MMscf/day", "quantity": "GasRate" },
        "valueType": "DOUBLE",
        "saveTimeseriesExternalId": "SystemCalculation-LER-WELL-A2-OUTPUT-GasRate"
      },
      {
        "name": "Oil Flowrate",
        "referenceId": "OilRate",
        "unit": { "name": "STB/day", "quantity": "LiqRate" },
        "valueType": "DOUBLE",
        "saveTimeseriesExternalId": "SystemCalculation-LER-WELL-A2-OUTPUT-OilRate"
      },
      {
        "name": "Water Flowrate",
        "referenceId": "WatRate",
        "unit": { "name": "STB/day", "quantity": "LiqRate" },
        "valueType": "DOUBLE",
        "saveTimeseriesExternalId": "SystemCalculation-LER-WELL-A2-OUTPUT-WatRate"
      },
      {
        "name": "Liquid Flowrate",
        "referenceId": "LiqRate",
        "unit": { "name": "STB/day", "quantity": "LiqRate" },
        "valueType": "DOUBLE",
        "saveTimeseriesExternalId": "SystemCalculation-LER-WELL-A2-OUTPUT-LiqRate"
      },
      {
        "name": "Bottom Hole Pressure",
        "referenceId": "BHP",
        "unit": { "name": "psig", "quantity": "Pressure" },
        "valueType": "DOUBLE",
        "saveTimeseriesExternalId": "SystemCalculation-LER-WELL-A2-OUTPUT-BHP"
      }
    ]
  },
  "script": [
    {
      "order": 1,
      "description": "Set Inputs",
      "steps": [
        {
          "order": 1,
          "stepType": "Set",
          "description": "Set RateMethod to Automatic",
          "arguments": { "referenceId": "RateMethod", "address": "PROSPER.ANL.SYS.RateMethod" }
        },
        {
          "order": 2,
          "stepType": "Set",
          "arguments": { "referenceId": "THP", "address": "PROSPER.ANL.SYS.Pres" }
        }
      ]
    },
    {
      "order": 2,
      "description": "Perform Calculation",
      "steps": [
        {
          "order": 1,
          "stepType": "Set",
          "description": "Clear table with sensitivity variables",
          "arguments": { "referenceId": "ClearSensDB", "address": "PROSPER.ANL.SYS.Sens.SensDB.Clear" }
        },
        {
          "order": 2,
          "stepType": "Command",
          "arguments": { "address": "PROSPER.ANL.SYS.CALC" }
        }
      ]
    },
    {
      "order": 3,
      "description": "Set Outputs",
      "steps": [
        {
          "order": 1,
          "stepType": "Get",
          "arguments": { "referenceId": "GasRate", "address": "PROSPER.OUT.SYS.Results[0].Sol.GasRate" }
        },
        {
          "order": 2,
          "stepType": "Get",
          "arguments": { "referenceId": "OilRate", "address": "PROSPER.OUT.SYS.Results[0].Sol.OilRate" }
        },
        {
          "order": 3,
          "stepType": "Get",
          "arguments": { "referenceId": "WatRate", "address": "PROSPER.OUT.SYS.Results[0].Sol.WatRate" }
        },
        {
          "order": 4,
          "stepType": "Get",
          "arguments": { "referenceId": "LiqRate", "address": "PROSPER.OUT.SYS.Results[0].Sol.LiqRate" }
        },
        {
          "order": 5,
          "stepType": "Get",
          "arguments": { "referenceId": "BHP", "address": "PROSPER.OUT.SYS.Results[0].Sol.BHP" }
        }
      ]
    }
  ]
}

Explanation

Routine revision identification

The routine revision is uniquely identified by externalId ("SystemCalculation-LER-WELL-A2-v1") and is associated with a parent routine ID, "routineExternalId": "SystemCalculation-LER-WELL-A2", which is associated with a particular simulator ("PROSPER") and a simulator model ("LER-WELL-A2").

Schedule configuration

The routine revision is configured to run on a schedule, as indicated by the "enabled": true in the "schedule" section. The "cronExpression": "0 * * * *" means that the routine will run at the beginning of every hour.

Data sampling

Data sampling is enabled for this routine. validationWindow and samplingWindow are both set to 60 minutes, with a granularity of 1 minute. This means that the connector will look for valid data within the last hour, sampling data every 1 minute.

Logical check

A logical check is configured for the tubing head pressure. It checks if the average value of time series "AP07-019THP-PSI2120.PV" is greater than 80. This ensures that the simulation only runs when the tubing head pressure is above a certain threshold.

Input configuration

The routine revision defines three inputs for the simulation. Each input is assigned a reference ID for use in the simulation script. Some inputs are configured to save their values to time series for later analysis.

Input	Description
RateMethod	A constant value of `"2"`.
Tubing Head Pressure	Sourced from the `"AP07-019THP-PSI2120.PV"` time series, using the average aggregate, with data stored in `"psig"`.
ClearSensDB	A constant value of `"1"`.

Output configuration

The routine revision defines five outputs from the simulation.

Input	Description
Gas Flowrate	In `"MMscf/day"`, to be saved to a time series.
Oil Flowrate	In `"STB/day"`, to be saved to a time series.
Water Flowrate	In `"STB/day"`, to be saved to a time series.
Liquid Flowrate	In `"STB/day"`, to be saved to a time series.
Bottom Hole Pressure	In `"psig"`, to be saved to a time series.

Simulation script

The script section defines the steps for running the simulation:

Set Inputs: The script sets all the input values into the simulation model.
Perform Calculation: The system calculation command, "PROSPER.ANL.SYS.CALC" is issued to run the simulation.
Set Outputs: The script retrieves the output values from the simulation model.

This is a configuration for a system calculation of well A2, taking into account real-time tubing head pressure data and some PROSPER configuration flags. The simulation calculates the resulting production conditions, which can be used for various purposes such as virtual metering, production optimization, and asset health.

Before you start​

Routine revision structure​

Configure input​

Configuration parameters​

Configure output​

Script​

Example​

Explanation​

Routine revision identification​

Schedule configuration​

Data sampling​

Logical check​

Input configuration​

Output configuration​

Simulation script​