Simulators

SimulatorsAPI

List simulators

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

List all simulators

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: collections.abc.Sequence[cognite.client.data_classes.simulators.runs.SimulationInputOverride] | None = None, run_time: int | None = None, queue: bool | None = None, log_severity: Optional[Literal['Debug', 'Information', 'Warning', 'Error']] = None, wait: bool = True, timeout: float = 60) → SimulationRun

SimulatorRoutinesAPI.run(*, routine_revision_external_id: str, model_revision_external_id: str, inputs: collections.abc.Sequence[cognite.client.data_classes.simulators.runs.SimulationInputOverride] | None = None, run_time: int | None = None, queue: bool | None = 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. Supports two modes: 1. By routine external ID only 2. By routine revision external ID + model revision external ID

Parameters

• routine_external_id (str | None) – External id of the simulator routine to run. Cannot be specified together with routine_revision_external_id and model_revision_external_id.

• routine_revision_external_id (str | None) – External id of the simulator routine revision to run. Must be specified together with model_revision_external_id.

• model_revision_external_id (str | None) – External id of the simulator model revision. Must be specified together with routine_revision_external_id.

• 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 using routine external ID:

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

Create new simulation run using routine and model revision external IDs:

>>> run = client.simulators.routines.run(
...     routine_revision_external_id="routine_revision1",
...     model_revision_external_id="model_revision1",
... )

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, sort: Optional[SimulationRunsSort] = 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

• sort (SimulationRunsSort | None) – The criteria to sort by.

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.SimulationInput(reference_id: str, value: str | int | float | list[str] | list[int] | list[float], value_type: Literal['STRING', 'DOUBLE', 'STRING_ARRAY', 'DOUBLE_ARRAY'], unit: Optional[SimulationValueUnitName] = None, simulator_object_reference: Optional[dict[str, str]] = None, timeseries_external_id: Optional[str] = None, overridden: Optional[bool] = None)

Bases: SimulationValueBase

This class is used to define the value and its type. The value can be a string, double, array of strings or array of doubles.

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.SimulationInputOverride(reference_id: 'str', value: 'str | int | float | list[str] | list[int] | list[float]', unit: 'SimulationValueUnitName | 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.SimulationOutput(reference_id: str, value: str | int | float | list[str] | list[int] | list[float], value_type: Literal['STRING', 'DOUBLE', 'STRING_ARRAY', 'DOUBLE_ARRAY'], unit: Optional[SimulationValueUnitName] = None, simulator_object_reference: Optional[dict[str, str]] = None, timeseries_external_id: Optional[str] = None)

Bases: SimulationValueBase

This class is used to return the outputs generated during the simulation. The value can be a string, double, array of strings or array of doubles.

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.SimulationRunDataItem(run_id: int, inputs: list[cognite.client.data_classes.simulators.runs.SimulationInput], outputs: list[cognite.client.data_classes.simulators.runs.SimulationOutput])

Bases: CogniteResource

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]

to_pandas() → pandas.DataFrame

Convert the simulation run data to a pandas DataFrame.

Returns

The dataframe.

Return type

pandas.DataFrame

class cognite.client.data_classes.simulators.SimulationRunDataList(resources: Iterable[Any], cognite_client: CogniteClient | None = None)

Bases: CogniteResourceList[SimulationRunDataItem], IdTransformerMixin

to_pandas() → pandas.DataFrame

Convert the simulation run data list to a pandas DataFrame.

Returns

The dataframe.

Return type

pandas.DataFrame

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: Optional[str] = None, routine_revision_external_id: Optional[str] = None, model_revision_external_id: Optional[str] = None, 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.

This class supports two modes of running simulations: 1. By routine external ID only 2. By routine revision external ID + model revision external ID

Parameters

• routine_external_id (str | None) – External id of the associated simulator routine. Cannot be specified together with routine_revision_external_id and model_revision_external_id.

• routine_revision_external_id (str | None) – External id of the associated simulator routine revision. Must be specified together with model_revision_external_id.

• model_revision_external_id (str | None) – External id of the associated simulator model revision. Must be specified together with routine_revision_external_id.

• 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.SimulationValueUnit(name: 'str | None' = None, external_id: 'str | None' = None)

Bases: SimulationValueUnitName

class cognite.client.data_classes.simulators.SimulationValueUnitInput(name: str, quantity: Optional[str] = None)

Bases: CogniteObject

The unit of the simulation value.

Parameters

• name (str) – The name of the unit.

• quantity (str | None) – The quantity of the unit.

class cognite.client.data_classes.simulators.SimulationValueUnitName(name: 'str | None' = None)

Bases: CogniteObject

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.SimulatorFlowsheet(simulator_object_nodes: 'list[SimulatorFlowsheetObjectNode]', simulator_object_edges: 'list[SimulatorFlowsheetObjectEdge]', thermodynamics: 'SimulatorFlowsheetThermodynamic')

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.SimulatorFlowsheetGraphicalObject(position: 'SimulatorFlowsheetPosition | None', height: 'float | None', width: 'float | None', scale_x: 'float | int | None', scale_y: 'float | int | None', angle: 'float | None', active: 'bool | 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.SimulatorFlowsheetObjectEdge(id: 'str', name: 'str | None', source_id: 'str', target_id: 'str', connection_type: "Literal['Material', 'Energy', 'Information']")

Bases: CogniteObject

class cognite.client.data_classes.simulators.SimulatorFlowsheetObjectNode(id: 'str', name: 'str | None', type: 'str', graphical_object: 'SimulatorFlowsheetGraphicalObject | None', properties: 'list[SimulatorFlowsheetProperty]')

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.SimulatorFlowsheetPosition(x: 'float', y: 'float')

Bases: CogniteObject

class cognite.client.data_classes.simulators.SimulatorFlowsheetProperty(name: 'str', reference_object: 'dict[str, str]', value_type: "Literal['STRING', 'DOUBLE', 'STRING_ARRAY', 'DOUBLE_ARRAY']", value: 'str | float | list[str] | list[float]', unit: 'SimulationValueUnitReference | None', read_only: 'bool | 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.SimulatorFlowsheetThermodynamic(property_packages: 'list[str]', components: 'list[str]')

Bases: CogniteObject

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.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.SimulatorLog(id: int, data: Sequence[SimulatorLogData], created_time: int, last_updated_time: int, data_set_id: int, severity: Optional[Literal['Debug', 'Information', 'Warning', 'Error']])

Bases: CogniteResource

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

• id (int) – A unique id of a simulator resource log.

• data (Sequence[SimulatorLogData]) – Log data of the simulator resource.

• created_time (int) – The number of milliseconds since epoch.

• last_updated_time (int) – The number of milliseconds since epoch.

• data_set_id (int) – Dataset id of the resource.

• severity (Severity | None) – Minimum severity level of the log data. This overrides connector configuration minimum severity level and can be used for more granular control.

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.SimulatorLogData(timestamp: int, message: str, severity: Literal['Debug', 'Information', 'Warning', 'Error'])

Bases: CogniteObject

Simulator log data represents a single log entry in a simulator log.

Parameters

• timestamp (int) – Timestamp of the log message.

• message (str) – Log message.

• severity (Severity) – Log severity level.

class cognite.client.data_classes.simulators.SimulatorLogList(resources: Iterable[Any], cognite_client: CogniteClient | None = None)

Bases: CogniteResourceList[SimulatorLog], 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.SimulatorModelRevisionData(model_revision_external_id: str, created_time: int, last_updated_time: int, data_set_id: int, flowsheets: list[cognite.client.data_classes.simulators.models.SimulatorFlowsheet] | None, info: dict[str, str] | None)

Bases: CogniteResource

Extracted metadata from a simulator model file associated with a model revision.

When a model revision is created, connectors can optionally parse the simulator file to extract structured information about the model’s internal structure and configuration. This data resource stores the parsed information, which may include flowsheet details, process equipment, operating parameters, connections between blocks, and visualization data.

Note: The availability and extent of this data depends entirely on the connector implementation and simulator type. Some connectors may: - Not implement this feature at all (no data extraction) - Partially implement it (e.g., only populate ‘info’ or only ‘flowsheets’) - Fully implement it with comprehensive model details

Parameters

• model_revision_external_id (str) – External id of the associated model revision

• created_time (int) – The time when the simulator model revision data was created

• last_updated_time (int) – The time when the simulator model revision data was last updated

• data_set_id (int) – The id of the dataset associated with the simulator model revision data

• flowsheets (list[SimulatorFlowsheet] | None) – Extracted flowsheet information, if supported by the connector. May include blocks, equipment, properties, and connections

• info (dict[str, str] | None) – Additional metadata extracted from the simulator file, if supported by the connector

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.SimulatorModelRevisionDataList(resources: Iterable[Any], cognite_client: CogniteClient | None = None)

Bases: CogniteResourceList[SimulatorModelRevisionData], ExternalIDTransformerMixin

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.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.SimulatorModelWriteList(resources: Iterable[Any], cognite_client: CogniteClient | None = None)

Bases: CogniteResourceList[SimulatorModelWrite], ExternalIDTransformerMixin

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

Bases: SimulatorRoutineCore

The simulator routine resource defines instructions on interacting with a 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.

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

Parameters

• id (int) – A unique id of a simulator routine

• external_id (str) – External id of the simulator routine

• model_external_id (str) – External id of the associated simulator model

• simulator_integration_external_id (str) – External id of the associated simulator integration

• name (str) – The name of the simulator routine

• data_set_id (int) – The id of the dataset associated with the simulator routine

• simulator_external_id (str) – External id of the associated simulator

• created_time (int) – The time when the simulator routine was created

• last_updated_time (int) – The time when the simulator routine was last updated

• description (str | None) – The description of the simulator routine

as_write() → SimulatorRoutineWrite

Returns a writeable version of this resource

class cognite.client.data_classes.simulators.SimulatorRoutineConfiguration(inputs: cognite.client.data_classes.simulators.routine_revisions.SimulatorRoutineInputList | collections.abc.Sequence[cognite.client.data_classes.simulators.routine_revisions.SimulatorRoutineInput] | None, outputs: cognite.client.data_classes.simulators.routine_revisions.SimulatorRoutineOutputList | collections.abc.Sequence[cognite.client.data_classes.simulators.routine_revisions.SimulatorRoutineOutput] | None, logical_check: Optional[Sequence[SimulatorRoutineLogicalCheck]] = None, steady_state_detection: Optional[Sequence[SimulatorRoutineSteadyStateDetection]] = None, schedule: Optional[SimulatorRoutineSchedule] = None, data_sampling: Optional[SimulatorRoutineDataSampling] = None)

Bases: CogniteObject

The simulator routine configuration defines the configuration of a simulator routine revision.

Learn more about simulator routine configuration <https://docs.cognite.com/cdf/integration/guides/simulators/simulator_routines>.

Parameters

• inputs (SimulatorRoutineInputList | Sequence[SimulatorRoutineInput] | None) – The inputs of the simulator routine revision. Each element can be either a constant or a timeseries input.

• outputs (SimulatorRoutineOutputList | Sequence[SimulatorRoutineOutput] | None) – The outputs of the simulator routine revision.

• logical_check (Sequence[SimulatorRoutineLogicalCheck] | None) – Logical check configuration.

• steady_state_detection (Sequence[SimulatorRoutineSteadyStateDetection] | None) – Steady state detection configuration.

• schedule (SimulatorRoutineSchedule | None) – Schedule configuration.

• data_sampling (SimulatorRoutineDataSampling | None) – Data sampling configuration. Learn more about data sampling <https://docs.cognite.com/cdf/integration/guides/simulators/about_data_sampling>.

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.SimulatorRoutineDataSampling(sampling_window: int, granularity: int, validation_window: Optional[int] = None)

Bases: CogniteObject

The data sampling configuration of the simulator routine revision.

Learn more about data sampling <https://docs.cognite.com/cdf/integration/guides/simulators/about_data_sampling>.

Parameters

• sampling_window (int) – Sampling window of the data sampling. Represented in minutes

• granularity (int) – The granularity of the data sampling in minutes.

• validation_window (int | None) – Validation window of the data sampling. Represented in minutes. Used when either logical check or steady state detection is enabled.

class cognite.client.data_classes.simulators.SimulatorRoutineInput(name: str, reference_id: str, save_timeseries_external_id: Optional[str] = None, unit: Optional[SimulationValueUnitInput] = None)

Bases: CogniteObject, ABC

The input of the simulator routine revision.

Parameters

• name (str) – The name of the input.

• reference_id (str) – The reference ID of the input.

• save_timeseries_external_id (str | None) – The external ID of the timeseries to save the input. If not provided, the input is not saved to a timeseries.

• unit (SimulationValueUnitInput | None) – The unit of the input.

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.SimulatorRoutineInputConstant(name: str, reference_id: str, value: str | int | float | list[str] | list[int] | list[float], value_type: Literal['STRING', 'DOUBLE', 'STRING_ARRAY', 'DOUBLE_ARRAY'], unit: Optional[SimulationValueUnitInput] = None, save_timeseries_external_id: Optional[str] = None)

Bases: SimulatorRoutineInput

The constant input of the simulator routine revision.

Parameters

• name (str) – The name of the input.

• reference_id (str) – The reference ID of the input.

• value (str | int | float | list[str] | list[int] | list[float]) – The value of the input.

• value_type (Literal["STRING", "DOUBLE", "STRING_ARRAY", "DOUBLE_ARRAY"]) – The value type of the input.

• unit (SimulationValueUnitInput | None) – The unit of the input.

• save_timeseries_external_id (str | None) – The external ID of the timeseries to save the input. If not provided, the input is not saved to a timeseries.

class cognite.client.data_classes.simulators.SimulatorRoutineInputList(initlist: Optional[Sequence[SimulatorRoutineInput]] = None)

Bases: UserList[SimulatorRoutineInput]

List of simulator routine inputs with pandas conversion capabilities.

to_pandas() → pandas.DataFrame

Convert the list of inputs to a pandas DataFrame.

Returns

DataFrame with input information.

Return type

pandas.DataFrame

class cognite.client.data_classes.simulators.SimulatorRoutineInputTimeseries(name: str, reference_id: str, source_external_id: str, aggregate: Optional[Literal['average', 'interpolation', 'stepInterpolation']] = None, save_timeseries_external_id: Optional[str] = None, unit: Optional[SimulationValueUnitInput] = None)

Bases: SimulatorRoutineInput

The timeseries input of the simulator routine revision.

Parameters

• name (str) – The name of the input.

• reference_id (str) – The reference ID of the input.

• source_external_id (str) – The external ID of the source timeseries.

• aggregate (Literal["average", "interpolation", "stepInterpolation"] | None) – The aggregation method to use for the timeseries.

• save_timeseries_external_id (str | None) – The external ID of the timeseries to save the input. If not provided, the input is not saved to a timeseries.

• unit (SimulationValueUnitInput | None) – The unit of the input.

class cognite.client.data_classes.simulators.SimulatorRoutineList(resources: Iterable[Any], cognite_client: CogniteClient | None = None)

Bases: WriteableCogniteResourceList[SimulatorRoutineWrite, SimulatorRoutine], IdTransformerMixin

class cognite.client.data_classes.simulators.SimulatorRoutineLogicalCheck(aggregate: Literal['average', 'interpolation', 'stepInterpolation'], operator: Literal['eq', 'ne', 'gt', 'ge', 'lt', 'le'], value: float, timeseries_external_id: Optional[str] = None)

Bases: CogniteObject

The logical check configuration of the simulator routine revision.

Learn more about logical checks <https://docs.cognite.com/cdf/integration/guides/simulators/about_data_sampling/#data-validation-methods>.

Parameters

• aggregate (Literal["average", "interpolation", "stepInterpolation"]) – The aggregation method to use for the time series.

• operator (Literal["eq", "ne", "gt", "ge", "lt", "le"]) – The operator to use for the logical check.

• value (float) – The value to use for the logical check.

• timeseries_external_id (str | None) – The external ID of the time series to check.

class cognite.client.data_classes.simulators.SimulatorRoutineOutput(name: str, reference_id: str, value_type: str, unit: Optional[SimulationValueUnitInput] = None, save_timeseries_external_id: Optional[str] = None)

Bases: CogniteObject

The output of the simulator routine revision.

Parameters

• name (str) – The name of the output.

• reference_id (str) – The reference ID of the output.

• value_type (str) – The value type of the output.

• unit (SimulationValueUnitInput | None) – The unit of the output.

• save_timeseries_external_id (str | None) – The external ID of the timeseries to save the output. If not provided, the output is not saved to a timeseries.

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.SimulatorRoutineOutputList(initlist: Optional[Sequence[SimulatorRoutineOutput]] = None)

Bases: UserList[SimulatorRoutineOutput]

List of simulator routine outputs with pandas conversion capabilities.

to_pandas() → pandas.DataFrame

Convert the list of outputs to a pandas DataFrame.

Returns

DataFrame with output information.

Return type

pandas.DataFrame

class cognite.client.data_classes.simulators.SimulatorRoutineRevision(id: int, external_id: str, simulator_external_id: str, simulator_integration_external_id: str, routine_external_id: str, model_external_id: str, version_number: int, created_time: int, data_set_id: int, created_by_user_id: str, configuration: Optional[SimulatorRoutineConfiguration] = None, script: Optional[Union[SimulatorRoutineStageList, Sequence[SimulatorRoutineStage]]] = None)

Bases: SimulatorRoutineRevisionCore

The simulator routine resource defines instructions on interacting with a simulator model.

A simulator routine includes:

Inputs (values set into the simulator model) Commands (actions to be performed by the simulator) 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.

Parameters

• id (int) – The unique identifier of the simulator routine revision.

• external_id (str) – The external ID provided by the client. Must be unique for the resource type.

• simulator_external_id (str) – The external ID of the simulator.

• simulator_integration_external_id (str) – The external ID of the simulator integration.

• routine_external_id (str) – The external ID of the simulator routine.

• model_external_id (str) – The external ID of the simulator model.

• version_number (int) – The version number of the simulator routine revision. Unique for each simulator routine.

• created_time (int) – The timestamp of when the simulator routine revision was created.

• data_set_id (int) – The ID of the data set associated with the simulator routine revision.

• created_by_user_id (str) – The ID of the user who created the simulator routine revision.

• configuration (SimulatorRoutineConfiguration | None) – The configuration of the simulator routine revision.

• script (SimulatorRoutineStageList | Sequence[SimulatorRoutineStage] | None) – The script of the simulator routine revision.

as_write() → SimulatorRoutineRevisionWrite

Returns a writeable version of this resource

class cognite.client.data_classes.simulators.SimulatorRoutineRevisionList(resources: Iterable[Any], cognite_client: CogniteClient | None = None)

Bases: WriteableCogniteResourceList[SimulatorRoutineRevisionWrite, SimulatorRoutineRevision], IdTransformerMixin

class cognite.client.data_classes.simulators.SimulatorRoutineRevisionWrite(external_id: str, routine_external_id: str, configuration: Optional[SimulatorRoutineConfiguration] = None, script: Optional[Union[SimulatorRoutineStageList, Sequence[SimulatorRoutineStage]]] = None)

Bases: SimulatorRoutineRevisionCore

The simulator routine resource defines instructions on interacting with a simulator model. This is a writeable version of a simulator routine revision, it is used when creating simulator routine revisions.

Parameters

• external_id (str) – The external ID provided by the client. Must be unique for the resource type.

• routine_external_id (str) – The external ID of the simulator routine.

• configuration (SimulatorRoutineConfiguration | None) – The configuration of the simulator routine revision.

• script (SimulatorRoutineStageList | Sequence[SimulatorRoutineStage] | None) – The script of the simulator routine revision.

as_write() → SimulatorRoutineRevisionWrite

Returns a writeable version of this resource

class cognite.client.data_classes.simulators.SimulatorRoutineRevisionWriteList(resources: Iterable[Any], cognite_client: CogniteClient | None = None)

Bases: CogniteResourceList[SimulatorRoutineRevisionWrite], ExternalIDTransformerMixin

class cognite.client.data_classes.simulators.SimulatorRoutineSchedule(cron_expression: str)

Bases: CogniteObject

The schedule configuration of the simulator routine revision.

Parameters

cron_expression (str) – The cron expression of the schedule.

class cognite.client.data_classes.simulators.SimulatorRoutineStage(order: int, steps: list[cognite.client.data_classes.simulators.routine_revisions.SimulatorRoutineStep], description: str | None)

Bases: CogniteObject

The stage of the simulator routine revision. This is a way to organize the steps of the simulator routine revision.

Parameters

• order (int) – Represents the order in which the stage is executed compared to other stages in the script.

• steps (list[SimulatorRoutineStep]) – The steps of the stage.

• description (str | None) – The description of the stage.

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.SimulatorRoutineStageList(initlist: Optional[Sequence[SimulatorRoutineStage]] = None)

Bases: UserList[SimulatorRoutineStage]

List of simulator routine stages with pandas conversion capabilities.

to_pandas() → pandas.DataFrame

Convert the list of stages to a pandas DataFrame.

Returns

DataFrame with stage and step information.

Return type

pandas.DataFrame

class cognite.client.data_classes.simulators.SimulatorRoutineSteadyStateDetection(aggregate: Literal['average', 'interpolation', 'stepInterpolation'], min_section_size: int, var_threshold: float, slope_threshold: float, timeseries_external_id: Optional[str] = None)

Bases: CogniteObject

The steady state detection configuration of the simulator routine revision.

Learn more about steady state detection <https://docs.cognite.com/cdf/integration/guides/simulators/about_data_sampling/#data-validation-methods>.

Parameters

• aggregate (Literal["average", "interpolation", "stepInterpolation"]) – The aggregation method to use for the time series.

• min_section_size (int) – The minimum number of consecutive data points that must meet the steady state criteria.

• var_threshold (float) – The maximum variance allowed for the steady state region.

• slope_threshold (float) – The maximum slope allowed for the steady state region.

• timeseries_external_id (str | None) – The external ID of the time series to check.

class cognite.client.data_classes.simulators.SimulatorRoutineStep(step_type: Literal['Get', 'Set', 'Command'], arguments: SimulatorRoutineStepArguments, order: int, description: Optional[str] = None)

Bases: CogniteObject

The step of the simulator routine revision.

Parameters

• step_type (str) – The type of the step. Can be “Get”, “Set”, or “Command”.

• arguments (SimulatorRoutineStepArguments) – The arguments of the step.

• order (int) – Represents the order in which the step is executed compared to other steps in the stage.

• description (str | None) – The description of the step.

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.SimulatorRoutineStepArguments(data: dict[str, str])

Bases: CogniteObject, dict, MutableMapping[str, str]

The arguments of the simulator routine step.

Depending on the step type and simulator, the arguments can be different. For “Get” and “Set” step type the reference ID is required.

Parameters

data (dict[str, str]) – The step arguments.

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.SimulatorRoutineWrite(external_id: str, model_external_id: str, simulator_integration_external_id: str, name: str, description: Optional[str] = None)

Bases: SimulatorRoutineCore

The simulator routine resource defines instructions on interacting with a 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.

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

Parameters

• external_id (str) – External id of the simulator routine

• model_external_id (str) – External id of the associated simulator model

• simulator_integration_external_id (str) – External id of the associated simulator integration

• name (str) – The name of the simulator routine

• description (str | None) – The description of the simulator routine

as_write() → SimulatorRoutineWrite

Returns a writeable version of this resource

class cognite.client.data_classes.simulators.SimulatorRoutineWriteList(resources: Iterable[Any], cognite_client: CogniteClient | None = None)

Bases: CogniteResourceList[SimulatorRoutineWrite], ExternalIDTransformerMixin

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