Skip to content

Requirements - LedaFlow Multiphase Simulator API

Scope

This document defines the API requirements for a LedaFlow-based multiphase flow simulator in a cloud setting. It describes the functional requirements to enable smooth integration with Kongsberg Digital's digital twin platform and potentially other, 3rd party data platforms.

Documentation

The API should be self-documenting and tooling compatible (code generation, testing, mocking).

Why required: Mandating that the API is self-documenting and tooling-compatible allows any client or orchestrator to discover and consume the simulator's API. Furthermore, this avoids the documentation being out-of-band or outdated.

An example standard that incorporates this practice is OpenAPI standard.

The API should be implemented non-blocking, so that it responds timely even if the simulator is doing a heavy, long running task.

Interaction during simulation runtime with the API

Multiphase flow simulations are often computationally expensive and can require substantial time for processing. Function wise, it is required to communicate with the API and receive replies quickly also during ongoing computation (non-blocking), to enable failure detection and status monitoring.

Authorization & Authentication

There are no requirements towards LedaFlow providing authorization or authentication. Such are anyhow implemented on the data-platform level that hosts the simulation instances.

Start of Simulator

The API shall support starting the simulation software without a loaded case and providing the simulation configuration through the API after startup.

The API may additionally support providing a pointer/path to the configuration for the simulation at startup, but that is not the primary requirement for this variant.

Why required: This startup mode is useful when the orchestrator or workflow needs to inspect the simulator first, choose a case dynamically, or assemble configuration at runtime rather than binding it to the container start command.

Info

  • Simulator software (name, e.g. LedaFlow)
  • Simulator version
  • API version
  • Short description about simulator software and what it does

Why required: Allows operators and orchestrators to identify what they are talking to. The explicit API version is critical so that clients can select compatible behavior as the spec evolves.

Deployment Health Status

The status of the software: - API ready [true,false] - license status - get-log (should be limited to a meaningful amount of event log) - optional subscribe to logging (e.g. OpenTelemetry)

Why required: Answers whether the software deployment is operational, independent of whether a simulation is actively running. The bounded log view gives operators enough context to diagnose startup, licensing, or runtime faults without direct container access.

Case Control

A simulation scenario is called "case" in LedaFlow. It includes the topology, parameters, input variables, configuration for the type of simulation (steady-state or dynamic) and many more. Functionally, the API shall provide capabilities to interact with such cases:

  • available cases
  • start/run
  • stop/shut-down
  • step (one tick/time-step)
  • load file/case/snapshot
  • save file/case/snapshot
  • pause
  • download file/case/snapshot
  • upload file/case/snapshot
  • delete file/case/snapshot
  • multi-case run with argument that represents list of cases to execute. The cases shall be provided as a flat list (array / tuple) of input scenarios, each entry containing all relevant scenario inputs

Why required: Provides full programmatic control over the simulation lifecycle. - start/run, stop/shut-down, pause allow orchestrators to drive the simulation state machine without manual intervention. - step / single tick enables deterministic and reproducible execution, which is important for debugging transient multiphase behaviour and validating external control logic. - load/save file/case/snapshot enable reproducible test scenarios and checkpointing. - upload/download file/case/snapshot decouple case management from the host machine and allow CI pipelines or orchestration services to push inputs and retrieve results without shared filesystem access. - delete file/case/snapshot prevents unbounded disk growth in long-running automated environments. - multi-case run allows a batch of flow cases or scenarios to be executed as a single operation, reducing orchestration round-trips and simplifying study workflows.

Case Status

The running status of the simulation itself: - general simulation status: [running, stopped, loading, uninitialized] - achieved speed - uptime (has been running for x amount of time) - currently loaded/running case(s)/model(s) - subscribe on status variables

Why required: Answers what the simulation is doing right now. Real-time status and status subscriptions let orchestrators and dashboards detect stalls, load transitions, and execution progress without relying on log parsing or inefficient polling.

Data Access

  • available types (describes which kind of units, nodes, devices, boundaries, control elements, or other model objects the simulator contains, and which attributes and functions each object provides)
  • available units of measurement per attribute
  • topology (structure of available model objects; this should be implemented in such a way that it returns a meaningful amount of data. It is not helpful to send thousands of API calls to retrieve a simple topology structure, but for large models it is also not smart to return the entire topology at once. The API should therefore provide something like a limit, recurse, or similar)
  • read momentary value for a specific attribute/variable
  • set/write value for a specific attribute/variable
  • subscribe on a list/set of attributes/variables/values, possibly with option for providing the target for publishing the data to. Subscriptions should either die out automatically after a certain period, or be handled in an alternative reliable way that tolerates that clients die without notification without creating an endless overhead (e.g. keep-alive).

Why required: Makes the simulator's internal state observable and controllable by external systems. - available types allow generic tooling to understand the LedaFlow object model without hard-coded simulator-specific assumptions. - available units of measurement ensure that pressures, temperatures, phase fractions, flowrates, and other engineering values are interpreted correctly. - topology lets clients traverse large well, pipeline, equipment, and network structures efficiently. - read momentary value provides access to live simulation outputs and state variables. - set/write value enables closed-loop scenarios where external controllers or test harnesses inject runtime inputs. - subscription is required because high-frequency process data should be pushed efficiently rather than polled aggressively.