Simulators

SimulatorsAPI

List simulators

SimulatorsAPI.list(limit: int | None = 25) → SimulatorList

Parameters: limit (int | None) – Maximum number of results to return. Defaults to 25. Set to -1, float(“inf”) or None to return all items.
Returns: List of simulators
Return type: SimulatorList

Examples

List simulators:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.simulators.list(limit=10)

Simulator Integrations

List simulator integrations

SimulatorIntegrationsAPI.list(limit: int | None = 25, simulator_external_ids: Optional[Union[str, SequenceNotStr[str]]] = None, active: Optional[bool] = None) → SimulatorIntegrationList

Filter simulator integrations

Retrieves a list of simulator integrations that match the given criteria.

Parameters

limit (int | None) – The maximum number of simulator integrations to return, pass None to return all.
simulator_external_ids (str | SequenceNotStr[str] | None) – Filter on simulator external ids.
active (bool | None) – Filter on active status of the simulator integration.

Returns

List of simulator integrations

Return type

SimulatorIntegrationList

Examples

List a few simulator integrations:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.simulators.integrations.list(limit=10)

Filter simulator integrations by simulator external ids and active status:

>>> res = client.simulators.integrations.list(
...     simulator_external_ids=["sim1", "sim2"],
...     active=True,
... )

Delete simulator integrations

SimulatorIntegrationsAPI.delete(ids: Optional[Union[int, Sequence[int]]] = None, external_ids: Optional[Union[str, SequenceNotStr[str]]] = None) → None

Delete simulator integrations

Parameters

ids (int | Sequence[int] | None) – Id(s) of simulator integrations to delete
external_ids (str | SequenceNotStr[str] | None) – External_id(s) of simulator integrations to delete

Examples

Delete simulator integrations by id or external id:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> client.simulators.integrations.delete(ids=[1,2,3], external_ids="foo")

Simulator Models

List simulator models

SimulatorModelsAPI.list(limit: int | None = 25, simulator_external_ids: Optional[Union[str, SequenceNotStr[str]]] = None, sort: Optional[PropertySort] = None) → SimulatorModelList

Filter simulator models

Retrieves a list of simulator models that match the given criteria.

Parameters

limit (int | None) – Maximum number of results to return. Defaults to 25. Set to -1, float(“inf”) or None to return all items.
simulator_external_ids (str | SequenceNotStr[str] | None) – Filter by simulator external id(s).
sort (PropertySort | None) – The criteria to sort by.

Returns

List of simulator models

Return type

SimulatorModelList

Examples

List simulator models:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.simulators.models.list(limit=10)

Specify filter and sort order:

>>> from cognite.client.data_classes.simulators.filters import PropertySort
>>> res = client.simulators.models.list(
...     simulator_external_ids=["simulator_external_id"],
...     sort=PropertySort(
...         property="createdTime",
...         order="asc"
...     )
... )

Retrieve simulator models

SimulatorModelsAPI.retrieve(*, ids: int) → cognite.client.data_classes.simulators.models.SimulatorModel | None

SimulatorModelsAPI.retrieve(*, external_ids: str) → cognite.client.data_classes.simulators.models.SimulatorModel | None

SimulatorModelsAPI.retrieve(*, ids: Sequence[int]) → SimulatorModelList

SimulatorModelsAPI.retrieve(*, external_ids: SequenceNotStr[str]) → SimulatorModelList

Retrieve simulator models

Retrieve one or more simulator models by ID(s) or external ID(s).

Parameters

ids (int | Sequence[int] | None) – The id of the simulator model(s).
external_ids (str | SequenceNotStr[str] | None) – The external id of the simulator model(s).

Returns

Requested simulator model(s)

Return type

SimulatorModel | SimulatorModelList | None

Examples

Get simulator model by id:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.simulators.models.retrieve(ids=1)

Get simulator model by external id:

>>> res = client.simulators.models.retrieve(external_ids="model_external_id")

Get multiple simulator models by ids:

>>> res = client.simulators.models.retrieve(ids=[1,2])

Get multiple simulator models by external ids:

>>> res = client.simulators.models.retrieve(
...     external_ids=["model_external_id", "model_external_id2"]
... )

Create simulator models

SimulatorModelsAPI.create(items: SimulatorModelWrite) → SimulatorModel

SimulatorModelsAPI.create(items: Sequence[SimulatorModelWrite]) → SimulatorModelList

Create simulator models

Parameters: items (SimulatorModelWrite | Sequence[SimulatorModelWrite]) – The model(s) to create.
Returns: Created simulator model(s)
Return type: SimulatorModel | SimulatorModelList

Examples

Create new simulator models:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes.simulators import SimulatorModelWrite
>>> client = CogniteClient()
>>> models = [
...     SimulatorModelWrite(
...         name="model1", simulator_external_id="sim1", type="SteadyState",
...         data_set_id=1, external_id="model_external_id"
...     ),
...     SimulatorModelWrite(
...         name="model2", simulator_external_id="sim2", type="SteadyState",
...         data_set_id=2, external_id="model_external_id2"
...     )
... ]
>>> res = client.simulators.models.create(models)

Update simulator models

SimulatorModelsAPI.update(items: Sequence[cognite.client.data_classes.simulators.models.SimulatorModel | cognite.client.data_classes.simulators.models.SimulatorModelWrite | cognite.client.data_classes.simulators.models.SimulatorModelUpdate]) → SimulatorModelList

SimulatorModelsAPI.update(items: cognite.client.data_classes.simulators.models.SimulatorModel | cognite.client.data_classes.simulators.models.SimulatorModelWrite | cognite.client.data_classes.simulators.models.SimulatorModelUpdate) → SimulatorModel

Update simulator models

Parameters: items (SimulatorModel | SimulatorModelWrite | SimulatorModelUpdate | Sequence[SimulatorModel | SimulatorModelWrite | SimulatorModelUpdate]) – The model to update.
Returns: Updated simulator model(s)
Return type: SimulatorModel | SimulatorModelList

Examples

Update a simulator model that you have fetched. This will perform a full update of the model:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> model = client.simulators.models.retrieve(external_ids="model_external_id")
>>> model.name = "new_name"
>>> res = client.simulators.models.update(model)

Delete simulator models

SimulatorModelsAPI.delete(ids: Optional[Union[int, Sequence[int]]] = None, external_ids: Optional[Union[str, SequenceNotStr[str]]] = None) → None

Delete simulator models

Parameters

ids (int | Sequence[int] | None) – id (or sequence of ids) for the model(s) to delete.
external_ids (str | SequenceNotStr[str] | None) – external id (or sequence of external ids) for the model(s) to delete.

Examples

Delete simulator models by id or external id:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> client.simulators.models.delete(ids=[1,2,3], external_ids="model_external_id")

Simulator Model Revisions

List simulator model revisions

SimulatorModelRevisionsAPI.list(limit: int = 25, sort: Optional[PropertySort] = None, model_external_ids: Optional[Union[str, SequenceNotStr[str]]] = None, all_versions: Optional[bool] = None, created_time: Optional[TimestampRange] = None, last_updated_time: Optional[TimestampRange] = None) → SimulatorModelRevisionList

Filter simulator model revisions

Retrieves a list of simulator model revisions that match the given criteria.

Parameters

limit (int) – Maximum number of results to return. Defaults to 25. Set to -1, float(“inf”) or None to return all items.
sort (PropertySort | None) – The criteria to sort by.
model_external_ids (str | SequenceNotStr[str] | None) – The external ids of the simulator models to filter by.
all_versions (bool | None) – If True, all versions of the simulator model revisions are returned. If False, only the latest version is returned.
created_time (TimestampRange | None) – Filter by created time.
last_updated_time (TimestampRange | None) – Filter by last updated time.

Returns

List of simulator model revisions

Return type

SimulatorModelRevisionList

Examples

List simulator model revisions:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.simulators.models.revisions.list(limit=10)

Specify filter and sort order:

>>> from cognite.client.data_classes.simulators.filters import PropertySort
>>> from cognite.client.data_classes.shared import TimestampRange
>>> res = client.simulators.models.revisions.list(
...     model_external_ids=["model1", "model2"],
...     all_versions=True,
...     created_time=TimestampRange(min=0, max=1000000),
...     last_updated_time=TimestampRange(min=0, max=1000000),
...     sort=PropertySort(order="asc", property="createdTime"),
...     limit=10
... )

Retrieve simulator model revisions

SimulatorModelRevisionsAPI.retrieve(*, ids: int) → cognite.client.data_classes.simulators.models.SimulatorModelRevision | None

SimulatorModelRevisionsAPI.retrieve(*, external_ids: str) → cognite.client.data_classes.simulators.models.SimulatorModelRevision | None

SimulatorModelRevisionsAPI.retrieve(*, ids: Sequence[int]) → SimulatorModelRevisionList

SimulatorModelRevisionsAPI.retrieve(*, external_ids: SequenceNotStr[str]) → SimulatorModelRevisionList

Retrieve simulator model revisions

Retrieve one or more simulator model revisions by ID(s) or external ID(s).

Parameters

ids (int | Sequence[int] | None) – The ids of the simulator model revisions.
external_ids (str | SequenceNotStr[str] | None) – The external ids of the simulator model revisions.

Returns

Requested simulator model revision(s)

Return type

SimulatorModelRevision | SimulatorModelRevisionList | None

Examples

Get simulator model revision by id:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.simulators.models.revisions.retrieve(ids=1)

Get simulator model revision by external id:

>>> res = client.simulators.models.revisions.retrieve(
...     external_ids="revision_external_id"
... )

Get multiple simulator model revisions by ids:

>>> res = client.simulators.models.revisions.retrieve(ids=[1,2])

Get multiple simulator model revisions by external ids:

>>> res = client.simulators.models.revisions.retrieve(
...     external_ids=["revision1", "revision2"]
... )

Create simulator model revisions

SimulatorModelRevisionsAPI.create(items: SimulatorModelRevisionWrite) → SimulatorModelRevision

SimulatorModelRevisionsAPI.create(items: Sequence[SimulatorModelRevisionWrite]) → SimulatorModelRevisionList

Create simulator model revisions

Parameters: items (SimulatorModelRevisionWrite | Sequence[SimulatorModelRevisionWrite]) – The model revision(s) to create.
Returns: Created simulator model revision(s)
Return type: SimulatorModelRevision | SimulatorModelRevisionList

Examples

Create new simulator model revisions:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes.simulators import SimulatorModelRevisionWrite, SimulatorModelDependencyFileId, SimulatorModelRevisionDependency
>>> client = CogniteClient()
>>> revisions = [
...     SimulatorModelRevisionWrite(
...         external_id="revision1",
...         file_id=1,
...         model_external_id="a_1",
...     ),
...     SimulatorModelRevisionWrite(
...         external_id="revision2",
...         file_id=2,
...         model_external_id="a_2",
...         external_dependencies = [
...             SimulatorModelRevisionDependency(
...                 file=SimulatorModelDependencyFileId(id=123),
...                 arguments={
...                     "fieldA": "value1",
...                     "fieldB": "value2",
...                 },
...             )
...         ]
...     ),
... ]
>>> res = client.simulators.models.revisions.create(revisions)

Simulator Routines

List simulator routines

SimulatorRoutinesAPI.list(limit: int = 25, model_external_ids: Optional[Sequence[str]] = None, simulator_integration_external_ids: Optional[Sequence[str]] = None, sort: Optional[PropertySort] = None) → SimulatorRoutineList

Filter simulator routines

Retrieves a list of simulator routines that match the given criteria.

Parameters

limit (int) – Maximum number of results to return. Defaults to 25. Set to -1, float(“inf”) or None to return all items.
model_external_ids (Sequence[str] | None) – Filter on model external ids.
simulator_integration_external_ids (Sequence[str] | None) – Filter on simulator integration external ids.
sort (PropertySort | None) – The criteria to sort by.

Returns

List of simulator routines

Return type

SimulatorRoutineList

Examples

List simulator routines:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.simulators.routines.list(limit=10)

Specify filter and sort order:

>>> from cognite.client.data_classes.simulators.filters import PropertySort
>>> res = client.simulators.routines.list(
...     simulator_integration_external_ids=["integration_ext_id"],
...     sort=PropertySort(
...         property="createdTime",
...         order="desc"
...     )
... )

Create simulator routines

SimulatorRoutinesAPI.create(routine: Sequence[SimulatorRoutineWrite]) → SimulatorRoutineList

SimulatorRoutinesAPI.create(routine: SimulatorRoutineWrite) → SimulatorRoutine

Create simulator routines

Parameters: routine (SimulatorRoutineWrite | Sequence[SimulatorRoutineWrite]) – Simulator routine(s) to create.
Returns: Created simulator routine(s)
Return type: SimulatorRoutine | SimulatorRoutineList

Examples

Create new simulator routines:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes.simulators.routines import SimulatorRoutineWrite
>>> client = CogniteClient()
>>> routines = [
...     SimulatorRoutineWrite(
...         name="routine1",
...         external_id="routine_ext_id",
...         simulator_integration_external_id="integration_ext_id",
...         model_external_id="model_ext_id",
...     ),
...     SimulatorRoutineWrite(
...         name="routine2",
...         external_id="routine_ext_id_2",
...         simulator_integration_external_id="integration_ext_id_2",
...         model_external_id="model_ext_id_2",
...     )
... ]
>>> res = client.simulators.routines.create(routines)

Delete simulator routines

SimulatorRoutinesAPI.delete(ids: Optional[Union[int, Sequence[int]]] = None, external_ids: Optional[Union[str, SequenceNotStr[str]]] = None) → None

Delete simulator routines

Parameters

ids (int | Sequence[int] | None) – ids (or sequence of ids) for the routine(s) to delete.
external_ids (str | SequenceNotStr[str] | SequenceNotStr[str] | None) – external ids (or sequence of external ids) for the routine(s) to delete.

Examples

Delete simulator routines by id or external id:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> client.simulators.routines.delete(ids=[1,2,3], external_ids="foo")

Run simulator routines

SimulatorRoutinesAPI.run(routine_external_id: str, inputs: Optional[Sequence[SimulationInputOverride]] = None, run_time: Optional[int] = None, queue: Optional[bool] = None, log_severity: Optional[Literal['Debug', 'Information', 'Warning', 'Error']] = None, wait: bool = True, timeout: float = 60) → SimulationRun

Run a simulation

Run a simulation for a given simulator routine.

Parameters

routine_external_id (str) – External id of the simulator routine to run
inputs (Sequence[SimulationInputOverride] | None) – List of input overrides
run_time (int | None) – Run time in milliseconds. Reference timestamp used for data pre-processing and data sampling.
queue (bool | None) – Queue the simulation run when connector is down.
log_severity (Literal['Debug', 'Information', 'Warning', 'Error'] | None) – Override the minimum severity level for the simulation run logs. If not provided, the minimum severity is read from the connector logger configuration.
wait (bool) – Wait until the simulation run is finished. Defaults to True.
timeout (float) – Timeout in seconds for waiting for the simulation run to finish. Defaults to 60 seconds.

Returns

Created simulation run

Return type

SimulationRun

Examples

Create new simulation run:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> run = client.simulators.routines.run(
...     routine_external_id="routine1",
...     log_severity="Debug"
... )

Simulator Routine Revisions

List simulator routine revisions

SimulatorRoutineRevisionsAPI.list(routine_external_ids: Optional[SequenceNotStr[str]] = None, model_external_ids: Optional[SequenceNotStr[str]] = None, simulator_integration_external_ids: Optional[SequenceNotStr[str]] = None, simulator_external_ids: Optional[SequenceNotStr[str]] = None, created_time: Optional[TimestampRange] = None, all_versions: bool = False, include_all_fields: bool = False, limit: Optional[int] = None, sort: Optional[PropertySort] = None) → SimulatorRoutineRevisionList

Filter simulator routine revisions

Retrieves a list of simulator routine revisions that match the given criteria.

Parameters

routine_external_ids (SequenceNotStr[str] | None) – Filter on routine external ids.
model_external_ids (SequenceNotStr[str] | None) – Filter on model external ids.
simulator_integration_external_ids (SequenceNotStr[str] | None) – Filter on simulator integration external ids.
simulator_external_ids (SequenceNotStr[str] | None) – Filter on simulator external ids.
created_time (TimestampRange | None) – Filter on created time.
all_versions (bool) – If all versions of the routine should be returned. Defaults to false which only returns the latest version.
include_all_fields (bool) – If all fields should be included in the response. Defaults to false which does not include script, configuration.inputs and configuration.outputs in the response.
limit (int | None) – Maximum number of simulator routine revisions to return. Defaults to return all items.
sort (PropertySort | None) – The criteria to sort by.

Returns

List of simulator routine revisions

Return type

SimulatorRoutineRevisionList

Examples

List simulator routine revisions:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.simulators.routines.revisions.list(limit=10)

List simulator routine revisions with filter:

>>> res = client.simulators.routines.revisions.list(
...     routine_external_ids=["routine_1"],
...     all_versions=True,
...     sort=PropertySort(order="asc", property="createdTime"),
...     include_all_fields=True
... )

Retrieve simulator routine revisions

SimulatorRoutineRevisionsAPI.retrieve(*, ids: int) → cognite.client.data_classes.simulators.routine_revisions.SimulatorRoutineRevision | None

SimulatorRoutineRevisionsAPI.retrieve(*, external_ids: str) → cognite.client.data_classes.simulators.routine_revisions.SimulatorRoutineRevision | None

SimulatorRoutineRevisionsAPI.retrieve(*, ids: Sequence[int]) → SimulatorRoutineRevisionList

SimulatorRoutineRevisionsAPI.retrieve(*, external_ids: SequenceNotStr[str]) → SimulatorRoutineRevisionList

Retrieve simulator routine revisions

Retrieve simulator routine revisions by ID or External Id.

Parameters

ids (int | Sequence[int] | None) – Simulator routine revision ID or list of IDs
external_ids (str | SequenceNotStr[str] | None) – Simulator routine revision External ID or list of external IDs

Returns

Requested simulator routine revision

Return type

SimulatorRoutineRevision | SimulatorRoutineRevisionList | None

Examples

Get simulator routine revision by id:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.simulators.routines.revisions.retrieve(ids=123)

Get simulator routine revision by external id:

>>> res = client.simulators.routines.revisions.retrieve(external_ids="routine_v1")

Create simulator routine revisions

SimulatorRoutineRevisionsAPI.create(items: Sequence[SimulatorRoutineRevisionWrite]) → SimulatorRoutineRevisionList

SimulatorRoutineRevisionsAPI.create(items: SimulatorRoutineRevisionWrite) → SimulatorRoutineRevision

Create simulator routine revisions

Parameters: items (SimulatorRoutineRevisionWrite | Sequence[SimulatorRoutineRevisionWrite]) – Simulator routine revisions to create.
Returns: Created simulator routine revision(s)
Return type: SimulatorRoutineRevision | SimulatorRoutineRevisionList

Examples

Create new simulator routine revisions:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes.simulators.routine_revisions import (
...     SimulatorRoutineRevisionWrite,
...     SimulatorRoutineConfiguration,
...     SimulatorRoutineInputConstant,
...     SimulatorRoutineOutput,
...     SimulatorRoutineDataSampling,
...     SimulatorRoutineStep,
...     SimulatorRoutineStepArguments,
...     SimulatorRoutineStage,
...     SimulationValueUnitInput,
... )
>>> client = CogniteClient()
>>> routine_revisions = [
...     SimulatorRoutineRevisionWrite(
...         external_id="routine_rev_1",
...         routine_external_id="routine_1",
...         configuration=SimulatorRoutineConfiguration(
...             data_sampling=SimulatorRoutineDataSampling(
...                 sampling_window=15,
...                 granularity=1,
...             ),
...             inputs=[
...                 SimulatorRoutineInputConstant(
...                     name="Tubing Head Pressure",
...                     reference_id="THP",
...                     value=124.3,
...                     value_type="DOUBLE",
...                     unit=SimulationValueUnitInput(
...                         name="bar",
...                         quantity="pressure",
...                     ),
...                     save_timeseries_external_id="TEST-ROUTINE-INPUT-THP",
...                 ),
...             ],
...             outputs=[
...                 SimulatorRoutineOutput(
...                     name="Bottom Hole Pressure",
...                     reference_id="BHP",
...                     unit=SimulationValueUnitInput(
...                         name="bar",
...                         quantity="pressure",
...                     ),
...                     value_type="DOUBLE",
...                     save_timeseries_external_id="TEST-ROUTINE-OUTPUT-BHP",
...                 ),
...             ],
...         ),
...         script=[
...             SimulatorRoutineStage(
...                 order=1,
...                 description="Define simulation inputs",
...                 steps=[
...                     SimulatorRoutineStep(
...                         order=1,
...                         step_type="Set",
...                         arguments=SimulatorRoutineStepArguments(
...                             {
...                                 "referenceId": "THP",
...                                 "objectName": "WELL",
...                                 "objectProperty": "WellHeadPressure",
...                             }
...                         ),
...                     ),
...                 ],
...             ),
...             SimulatorRoutineStage(
...                 order=2,
...                 description="Solve",
...                 steps=[
...                     SimulatorRoutineStep(
...                         order=1,
...                         step_type="Command",
...                         arguments=SimulatorRoutineStepArguments(
...                             {"command": "Solve"}
...                         ),
...                     ),
...                 ],
...             ),
...             SimulatorRoutineStage(
...                 order=3,
...                 description="Define simulation outputs",
...                 steps=[
...                     SimulatorRoutineStep(
...                         order=1,
...                         step_type="Get",
...                         arguments=SimulatorRoutineStepArguments(
...                             {
...                                 "referenceId": "BHP",
...                                 "objectName": "WELL",
...                                 "objectProperty": "BottomHolePressure",
...                             }
...                         ),
...                     ),
...                 ],
...             ),
...         ],
...     ),
... ]
>>> res = client.simulators.routines.revisions.create(routine_revisions)

Simulation Runs

List simulation runs

SimulatorRunsAPI.list(limit: int | None = 25, status: Optional[str] = None, run_type: Optional[str] = None, model_external_ids: Optional[SequenceNotStr[str]] = None, simulator_integration_external_ids: Optional[SequenceNotStr[str]] = None, simulator_external_ids: Optional[SequenceNotStr[str]] = None, routine_external_ids: Optional[SequenceNotStr[str]] = None, routine_revision_external_ids: Optional[SequenceNotStr[str]] = None, model_revision_external_ids: Optional[SequenceNotStr[str]] = None, created_time: Optional[TimestampRange] = None, simulation_time: Optional[TimestampRange] = None) → SimulationRunList

Filter simulation runs

Retrieves a list of simulation runs that match the given criteria.

Parameters

limit (int | None) – The maximum number of simulation runs to return, pass None to return all.
status (str | None) – Filter by simulation run status
run_type (str | None) – Filter by simulation run type
model_external_ids (SequenceNotStr[str] | None) – Filter by simulator model external ids
simulator_integration_external_ids (SequenceNotStr[str] | None) – Filter by simulator integration external ids
simulator_external_ids (SequenceNotStr[str] | None) – Filter by simulator external ids
routine_external_ids (SequenceNotStr[str] | None) – Filter by routine external ids
routine_revision_external_ids (SequenceNotStr[str] | None) – Filter by routine revision external ids
model_revision_external_ids (SequenceNotStr[str] | None) – Filter by model revision external ids
created_time (TimestampRange | None) – Filter by created time
simulation_time (TimestampRange | None) – Filter by simulation time

Returns

List of simulation runs

Return type

SimulationRunList

Examples

List simulation runs:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.simulators.runs.list()

Filter runs by status and simulator external ids:

>>> res = client.simulators.runs.list(
...     simulator_external_ids=["PROSPER", "DWSIM"],
...     status="success"
... )

Filter runs by time ranges:

>>> from cognite.client.data_classes.shared import TimestampRange
>>> res = client.simulators.runs.list(
...     created_time=TimestampRange(min=0, max=1_700_000_000_000),
...     simulation_time=TimestampRange(min=0, max=1_700_000_000_000),
... )

Retrieve simulation runs

SimulatorRunsAPI.retrieve(ids: int) → cognite.client.data_classes.simulators.runs.SimulationRun | None

SimulatorRunsAPI.retrieve(ids: Sequence[int]) → cognite.client.data_classes.simulators.runs.SimulationRunList | None

Retrieve simulation runs by ID

Parameters: ids (int | Sequence[int]) – The ID(s) of the simulation run(s) to retrieve.
Returns: The simulation run(s) with the given ID(s)
Return type: SimulationRun | SimulationRunList | None

Examples

Retrieve a single simulation run by id:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> run = client.simulators.runs.retrieve(ids=2)

Create simulation runs

SimulatorRunsAPI.create(items: SimulationRunWrite) → SimulationRun

SimulatorRunsAPI.create(items: Sequence[SimulationRunWrite]) → SimulationRunList

Create simulation runs

Parameters: items (SimulationRunWrite | Sequence[SimulationRunWrite]) – The simulation run(s) to execute.
Returns: Created simulation run(s)
Return type: SimulationRun | SimulationRunList

Examples

Create new simulation run:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes.simulators.runs import SimulationRunWrite
>>> client = CogniteClient()
>>> run = [
...     SimulationRunWrite(
...         routine_external_id="routine1",
...         log_severity="Debug",
...         run_type="external",
...     ),
... ]
>>> res = client.simulators.runs.create(run)

List simulation run data

SimulatorRunsAPI.list_run_data(run_id: int) → SimulationRunDataList

Get simulation run data

Retrieve data associated with a simulation run by ID.

Parameters: run_id (int) – Simulation run id.
Returns: List of simulation run data
Return type: SimulationRunDataList

Examples

Get simulation run data by run id:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> res = client.simulators.runs.list_run_data(run_id=12345)

Get simulation run data directly on a simulation run object:

>>> run = client.simulators.runs.retrieve(ids=2)
>>> res = run.get_data()

Simulator Logs

Retrieve simulator logs

SimulatorLogsAPI.retrieve(ids: int) → cognite.client.data_classes.simulators.logs.SimulatorLog | None

SimulatorLogsAPI.retrieve(ids: Sequence[int]) → cognite.client.data_classes.simulators.logs.SimulatorLogList | None

Retrieve simulator logs

Simulator logs track what happens during simulation runs, model parsing, and generic connector logic. They provide valuable information for monitoring, debugging, and auditing.

Simulator logs capture important events, messages, and exceptions that occur during the execution of simulations, model parsing, and connector operations. They help users identify issues, diagnose problems, and gain insights into the behavior of the simulator integrations.

Parameters: ids (int | Sequence[int]) – The ids of the simulator log.
Returns: Requested simulator log(s)
Return type: SimulatorLogList | SimulatorLog | None

Examples

Get simulator logs by simulator model id:

>>> from cognite.client import CogniteClient
>>> client = CogniteClient()
>>> model = client.simulators.models.retrieve(ids=1)
>>> logs = client.simulators.logs.retrieve(ids=model.log_id)

Get simulator logs by simulator integration id:

>>> integrations = client.simulators.integrations.list()
>>> logs = client.simulators.logs.retrieve(ids=integrations[0].log_id)

Get simulator logs by simulation run id:

>>> run = client.simulators.runs.retrieve(ids=1)
>>> logs = client.simulators.logs.retrieve(ids=run.log_id)

Get simulator logs directly on a simulation run object:

>>> run = client.simulators.runs.retrieve(ids=2)
>>> res = run.get_logs()

Data classes

class cognite.client.data_classes.simulators.SimulationRun(id: int, simulator_external_id: str, simulator_integration_external_id: str, model_external_id: str, model_revision_external_id: str, routine_revision_external_id: str, routine_external_id: str, run_type: Literal['external', 'manual', 'scheduled'], status: Literal['ready', 'running', 'success', 'failure'], data_set_id: int, user_id: str, log_id: int, created_time: int, last_updated_time: int, status_message: str | None = None, simulation_time: int | None = None, run_time: int | None = None, cognite_client: CogniteClient | None = None)

Bases: SimulationRunCore

Every time a simulation routine executes, a simulation run object is created.

This object ensures that each execution of a routine is documented and traceable. 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 to ensure the traceability and integrity of the simulation data.

Simulation runs provide a historical record of the simulations performed, allowing users to analyze and compare different runs, track changes over time, and make informed decisions based on the simulation results.

This is the read/response format of a simulation run.

Parameters

id (int) – The id of the simulation run
simulator_external_id (str) – External id of the associated simulator
simulator_integration_external_id (str) – External id of the associated simulator integration
model_external_id (str) – External id of the associated simulator model
model_revision_external_id (str) – External id of the associated simulator model revision
routine_revision_external_id (str) – External id of the associated simulator routine revision
routine_external_id (str) – External id of the associated simulator routine
run_type (Literal['external', 'manual', 'scheduled']) – The type of the simulation run
status (Literal['ready', 'running', 'success', 'failure']) – The status of the simulation run
data_set_id (int) – The id of the dataset associated with the simulation run
user_id (str) – The id of the user who executed the simulation run
log_id (int) – The id of the log associated with the simulation run
created_time (int) – The number of milliseconds since epoch
last_updated_time (int) – The number of milliseconds since epoch
status_message (str | None) – The status message of the simulation run
simulation_time (int | None) – Simulation time in milliseconds. Timestamp when the input data was sampled. Used for indexing input and output time series.
run_time (int | None) – Run time in milliseconds. Reference timestamp used for data pre-processing and data sampling.
cognite_client (CogniteClient | None) – An optional CogniteClient to associate with this data class.

get_data() → cognite.client.data_classes.simulators.runs.SimulationRunDataItem | None

Retrieve data associated with this simulation run.

Returns: Data for the simulation run.
Return type: SimulationRunDataItem | None

get_logs() → cognite.client.data_classes.simulators.logs.SimulatorLog | None

Retrieve logs for this simulation run.

Returns: Log for the simulation run.
Return type: SimulatorLog | None

update() → None: Update the simulation run object to the latest state. Useful if the run was created with wait=False.

wait(timeout: float = 60) → None

Waits for simulation status to become either success or failure. This is generally not needed to call directly, as client.simulators.routines.run(…) will wait for the simulation to finish by default.

Parameters: timeout (float) – Time out after this many seconds. Defaults to 60 seconds.

class cognite.client.data_classes.simulators.SimulationRunList(resources: Iterable[Any], cognite_client: CogniteClient | None = None): Bases: WriteableCogniteResourceList[SimulationRunWrite, SimulationRun], IdTransformerMixin

class cognite.client.data_classes.simulators.SimulationRunWrite(routine_external_id: str, run_type: Optional[str] = None, run_time: Optional[int] = None, queue: Optional[bool] = None, log_severity: Optional[str] = None, inputs: Optional[list[cognite.client.data_classes.simulators.runs.SimulationInputOverride]] = None)

Bases: SimulationRunCore

Request to run a simulator routine asynchronously.

Parameters

routine_external_id (str) – External id of the associated simulator routine
run_type (str | None) – The type of the simulation run
run_time (int | None) – Run time in milliseconds. Reference timestamp used for data pre-processing and data sampling.
queue (bool | None) – Queue the simulation run when connector is down.
log_severity (str | None) – Override the minimum severity level for the simulation run logs. If not provided, the minimum severity is read from the connector logger configuration.
inputs (list[SimulationInputOverride] | None) – List of input overrides

dump(camel_case: bool = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters: camel_case (bool) – Use camelCase for attribute names. Defaults to True.
Returns: A dictionary representation of the instance.
Return type: dict[str, Any]

class cognite.client.data_classes.simulators.SimulationRunWriteList(resources: Iterable[Any], cognite_client: CogniteClient | None = None): Bases: CogniteResourceList[SimulationRunWrite], ExternalIDTransformerMixin

class cognite.client.data_classes.simulators.Simulator(external_id: str, id: int, name: str, file_extension_types: Sequence[str], model_types: Optional[Sequence[SimulatorModelType]] = None, model_dependencies: Optional[Sequence[SimulatorModelDependency]] = None, step_fields: Optional[Sequence[SimulatorStep]] = None, unit_quantities: Optional[Sequence[SimulatorQuantity]] = None)

Bases: CogniteResource

The simulator resource contains the definitions necessary for Cognite Data Fusion (CDF) to interact with a given simulator.

It serves as a central contract that allows APIs, UIs, and integrations (connectors) to utilize 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 tools, ensuring consistency and reliability in data handling.

This is the read/response format of the simulator.

Parameters

external_id (str) – External id of the simulator
id (int) – Id of the simulator.
name (str) – Name of the simulator
file_extension_types (Sequence[str]) – File extension types supported by the simulator
model_types (Sequence[SimulatorModelType] | None) – Model types supported by the simulator
model_dependencies (Sequence[SimulatorModelDependency] | None) – Model dependencies supported by the simulator
step_fields (Sequence[SimulatorStep] | None) – Step types supported by the simulator when creating routines
unit_quantities (Sequence[SimulatorQuantity] | None) – Quantities and their units supported by the simulator

dump(camel_case: bool = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters: camel_case (bool) – Use camelCase for attribute names. Defaults to True.
Returns: A dictionary representation of the instance.
Return type: dict[str, Any]

get_quantities() → list[str]

Get a list of quantity names available for this simulator.

Returns: List of quantity names from the simulator’s unit_quantities.
Return type: list[str]

get_units(quantity: str) → list[str]

Get a list of unit names for a specific quantity.

Parameters: quantity (str) – The name of the quantity to get units for.
Returns: List of unit names for the specified quantity.
Return type: list[str]
Raises: ValueError – If the specified quantity does not exist for this simulator.

class cognite.client.data_classes.simulators.SimulatorIntegration(id: int, external_id: str, simulator_external_id: str, heartbeat: int, data_set_id: int, connector_version: str, log_id: int, active: bool, created_time: int, last_updated_time: int, license_status: Optional[str] = None, simulator_version: Optional[str] = None, license_last_checked_time: Optional[int] = None, connector_status: Optional[str] = None, connector_status_updated_time: Optional[int] = None)

Bases: CogniteResource

The simulator integration resource represents a simulator connector in Cognite Data Fusion (CDF).

It provides information about the configured connectors for a given simulator, including their status and additional details such as dataset, name, license status, connector version, simulator version, and more. This resource is essential for monitoring and managing the interactions between CDF and external simulators, ensuring proper data flow and integration.

This is the read/response format of the simulator integration.

Parameters

id (int) – Id of the simulator integration.
external_id (str) – External id of the simulator integration
simulator_external_id (str) – External id of the associated simulator
heartbeat (int) – The interval in seconds between the last heartbeat and the current time
data_set_id (int) – The id of the dataset associated with the simulator integration
connector_version (str) – The version of the connector
log_id (int) – Id of the log associated with this simulator integration.
active (bool) – Indicates if the simulator integration is active (i.e., a connector is linked to CDF for this integration).
created_time (int) – The time when this simulator integration resource was created.
last_updated_time (int) – The last time the simulator integration resource was updated.
license_status (str | None) – The status of the license
simulator_version (str | None) – The version of the simulator
license_last_checked_time (int | None) – The time when the license was last checked
connector_status (str | None) – The status of the connector
connector_status_updated_time (int | None) – The time when the connector status was last updated

class cognite.client.data_classes.simulators.SimulatorIntegrationFilter(simulator_external_ids: Optional[Union[str, SequenceNotStr[str]]] = None, active: Optional[bool] = None): Bases: CogniteFilter

class cognite.client.data_classes.simulators.SimulatorIntegrationList(resources: Iterable[Any], cognite_client: CogniteClient | None = None): Bases: CogniteResourceList[SimulatorIntegration], IdTransformerMixin

class cognite.client.data_classes.simulators.SimulatorList(resources: Iterable[Any], cognite_client: CogniteClient | None = None): Bases: CogniteResourceList[Simulator], IdTransformerMixin

class cognite.client.data_classes.simulators.SimulatorModel(id: int, external_id: str, simulator_external_id: str, data_set_id: int, name: str, type: str, created_time: int, last_updated_time: int, description: Optional[str] = None)

Bases: SimulatorModelCore

The simulator model resource represents an asset modeled in a simulator.

This asset could range from a pump or well to a complete processing facility or refinery. The simulator model is the root of its associated revisions, routines, runs, and results. The dataset 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 a simulator model over time. Each revision ensures that modifications to models are traceable and allows users to understand the evolution of a given model.

This is the read/response format of a simulator model.

Parameters

id (int) – A unique id of a simulator model
external_id (str) – External id of the simulator model
simulator_external_id (str) – External id of the associated simulator
data_set_id (int) – The id of the dataset associated with the simulator model
name (str) – The name of the simulator model
type (str) – The type key of the simulator model
created_time (int) – The time when the simulator model was created
last_updated_time (int) – The time when the simulator model was last updated
description (str | None) – The description of the simulator model

as_write() → SimulatorModelWrite: Returns this SimulatorModel in its writing version.

class cognite.client.data_classes.simulators.SimulatorModelDependencyFileId(id: 'int'): Bases: SimulatorModelDependencyFileReference

class cognite.client.data_classes.simulators.SimulatorModelDependencyFileReference: Bases: CogniteObject

class cognite.client.data_classes.simulators.SimulatorModelList(resources: Iterable[Any], cognite_client: CogniteClient | None = None): Bases: WriteableCogniteResourceList[SimulatorModelWrite, SimulatorModel], IdTransformerMixin

class cognite.client.data_classes.simulators.SimulatorModelRevision(id: int, external_id: str, model_external_id: str, file_id: int, created_time: int, last_updated_time: int, simulator_external_id: str, data_set_id: int, created_by_user_id: str, status: str, version_number: int, log_id: int, description: str | None = None, status_message: str | None = None, external_dependencies: list[SimulatorModelRevisionDependency] | None = None, cognite_client: CogniteClient | None = None)

Bases: SimulatorModelRevisionCore

Simulator model revisions track changes and updates to a simulator model over time.

Each revision ensures that modifications to models are traceable and allows users to understand the evolution of a given model.

Parameters

id (int) – Internal id of the simulator model revision
external_id (str) – External id of the simulator model revision
model_external_id (str) – External id of the associated simulator model
file_id (int) – The id of the file associated with the simulator model revision
created_time (int) – The time when the simulator model revision was created
last_updated_time (int) – The time when the simulator model revision was last updated
simulator_external_id (str) – External id of the simulator associated with the simulator model revision
data_set_id (int) – The id of the dataset associated with the simulator model revision
created_by_user_id (str) – The id of the user who created the simulator model revision
status (str) – The status of the simulator model revision
version_number (int) – The version number of the simulator model revision
log_id (int) – The id of the log associated with the simulator model revision
description (str | None) – The description of the simulator model revision
status_message (str | None) – The current status message of the simulator model revision
external_dependencies (list[SimulatorModelRevisionDependency] | None) – A list of external dependencies for the simulator model revision
cognite_client (CogniteClient | None) – The client to associate with this object.

as_write() → SimulatorModelRevisionWrite: Returns this SimulatorModelRevision in its writing version.

get_data() → cognite.client.data_classes.simulators.models.SimulatorModelRevisionData | None

Retrieve data associated with this simulator model revision.

Returns: Data for the simulator model revision.
Return type: SimulatorModelRevisionData | None

class cognite.client.data_classes.simulators.SimulatorModelRevisionDependency(file: SimulatorModelDependencyFileReference, arguments: dict[str, str])

Bases: CogniteObject

Represents an external dependency for a simulator model revision. :param file: The file ID associated with the external dependency. :type file: int :param arguments: A dictionary that contains the key-value pairs (fields) for the external dependency. :type arguments: dict[str, str]

dump(camel_case: bool = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters: camel_case (bool) – Use camelCase for attribute names. Defaults to True.
Returns: A dictionary representation of the instance.
Return type: dict[str, Any]

class cognite.client.data_classes.simulators.SimulatorModelRevisionList(resources: Iterable[Any], cognite_client: CogniteClient | None = None): Bases: WriteableCogniteResourceList[SimulatorModelRevisionWrite, SimulatorModelRevision], IdTransformerMixin

class cognite.client.data_classes.simulators.SimulatorModelRevisionWrite(external_id: str, model_external_id: str, file_id: int, description: Optional[str] = None, external_dependencies: Optional[list[cognite.client.data_classes.simulators.models.SimulatorModelRevisionDependency]] = None)

Bases: SimulatorModelRevisionCore

as_write() → SimulatorModelRevisionWrite: Returns a writeable version of this resource

class cognite.client.data_classes.simulators.SimulatorModelRevisionWriteList(resources: Iterable[Any], cognite_client: CogniteClient | None = None): Bases: CogniteResourceList[SimulatorModelRevisionWrite], ExternalIDTransformerMixin

class cognite.client.data_classes.simulators.SimulatorModelRevisionsFilter(model_external_ids: Optional[Union[str, SequenceNotStr[str]]] = None, all_versions: Optional[bool] = None, created_time: Optional[TimestampRange] = None, last_updated_time: Optional[TimestampRange] = None): Bases: CogniteFilter

class cognite.client.data_classes.simulators.SimulatorModelWrite(external_id: str, simulator_external_id: str, data_set_id: int, name: str, type: str, description: Optional[str] = None): Bases: SimulatorModelCore

class cognite.client.data_classes.simulators.SimulatorModelsFilter(simulator_external_ids: Optional[Union[str, SequenceNotStr[str]]] = None): Bases: CogniteFilter

class cognite.client.data_classes.simulators.SimulatorStep(step_type: 'str', fields: 'Sequence[SimulatorStepField]')

Bases: CogniteObject

dump(camel_case: bool = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters: camel_case (bool) – Use camelCase for attribute names. Defaults to True.
Returns: A dictionary representation of the instance.
Return type: dict[str, Any]

class cognite.client.data_classes.simulators.SimulatorStepField(name: 'str', label: 'str', info: 'str', options: 'Sequence[SimulatorStepOption] | None' = None)

Bases: CogniteObject

dump(camel_case: bool = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters: camel_case (bool) – Use camelCase for attribute names. Defaults to True.
Returns: A dictionary representation of the instance.
Return type: dict[str, Any]

class cognite.client.data_classes.simulators.SimulatorStepOption(label: 'str', value: 'str'): Bases: CogniteObject

class cognite.client.data_classes.simulators.SimulatorUnitEntry(label: 'str', name: 'str'): Bases: CogniteObject