Simulators

SimulatorsAPI

List simulators

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

List all simulators

Parameters

limit (int) – 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 = 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) – 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: None = None, external_ids: None = None) → NoReturn
SimulatorModelsAPI.retrieve(ids: int, external_ids: None = None) → cognite.client.data_classes.simulators.models.SimulatorModel | None
SimulatorModelsAPI.retrieve(ids: None, external_ids: str) → cognite.client.data_classes.simulators.models.SimulatorModel | None
SimulatorModelsAPI.retrieve(ids: collections.abc.Sequence[int] | None = None, external_ids: Optional[SequenceNotStr[str]] = None) → cognite.client.data_classes.simulators.models.SimulatorModelList | None

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: None = None, external_ids: None = None) → NoReturn
SimulatorModelRevisionsAPI.retrieve(ids: int, external_ids: None = None) → cognite.client.data_classes.simulators.models.SimulatorModelRevision | None
SimulatorModelRevisionsAPI.retrieve(ids: None, external_ids: str) → cognite.client.data_classes.simulators.models.SimulatorModelRevision | None
SimulatorModelRevisionsAPI.retrieve(ids: int | collections.abc.Sequence[int] | None = None, external_ids: Optional[Union[str, SequenceNotStr[str]]] = None) → cognite.client.data_classes.simulators.models.SimulatorModelRevision | cognite.client.data_classes.simulators.models.SimulatorModelRevisionList | None

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
>>> from cognite.client.data_classes.simulators.models import SimulatorExternalDependencyFileInternalId, SimulatorModelRevisionExternalDependency
>>> 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 = [
...             SimulatorModelRevisionExternalDependency(
...                 file=SimulatorExternalDependencyFileInternalId(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: None = None, external_ids: None = None) → NoReturn
SimulatorRoutineRevisionsAPI.retrieve(ids: int, external_ids: None = None) → cognite.client.data_classes.simulators.routine_revisions.SimulatorRoutineRevision | None
SimulatorRoutineRevisionsAPI.retrieve(ids: None, external_ids: str) → cognite.client.data_classes.simulators.routine_revisions.SimulatorRoutineRevision | None
SimulatorRoutineRevisionsAPI.retrieve(ids: collections.abc.Sequence[int] | None = None, external_ids: Optional[SequenceNotStr[str]] = None) → cognite.client.data_classes.simulators.routine_revisions.SimulatorRoutineRevisionList | None

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) → 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

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"
... )

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]

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.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: Optional[str] = None, status_message: Optional[str] = None, external_dependencies: Optional[list[cognite.client.data_classes.simulators.models.SimulatorModelRevisionExternalDependency]] = 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[SimulatorModelRevisionExternalDependency] | None) – A list of external dependencies for the simulator model revision

as_write() → SimulatorModelRevisionWrite

Returns this SimulatorModelRevision in its writing version.

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.SimulatorModelRevisionExternalDependency]] = None)

Bases: SimulatorModelRevisionCore

as_write() → SimulatorModelRevisionWrite

Returns a writeable version of this resource

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