Requirements - K-Spice Dynamic Process Simulator API¶

Scope¶

This document defines the API requirements for a K-Spice-based dynamic process simulator.

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.

Why required: Dynamic process simulation can involve expensive model loading, initialization, solver execution, and data exchange. A blocking API would stall callers during these operations, potentially causing false-positive failure detection, watchdog restarts, or cascading timeouts in the wider system. Non-blocking design ensures the API remains responsive at all times, independent of simulation workload.

From our perspective, we prefer a fully open API without authorization on simulator side, as we can implement user-authorization on a different level. If the simulator API wants to implement detailed authorization, it should be compatible with industry standard authentication solutions (RBAC, OAuth...)

Note: Simulator-side authorization remains optional. If a deployment requires simulator-level authentication, it should use industry-standard schemes so that it remains interoperable.

Start of Simulation¶

The simulator should be configurable at startup by providing a config file. The config file should be a local file available on the system where K-Spice is running. The path to this file could be provided through e.g. CLI option or an environment variable.

The API is expected to rely on startup-time configuration rather than post-start API configuration for this variant.

Why required: This startup mode is critical for orchestrated and containerized environments. If the container crashes and restarts, the orchestrator can relaunch it with the same configuration without manual intervention, enabling resilience, repeatability, and automation.

Info¶

Simulator software (name, e.g. K-Spice)
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 behaviour 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) - subscribe to logging. For example, K-Spice can implement an OpenTelemetry client that pushes logs to a configured endpoint

Why required: Answers whether the software deployment is operational, independent of whether a simulation is actively running. The required log subscription allows central observability platforms to receive startup, licensing, warning, and fault events proactively rather than relying on periodic log scraping.

Simulator Status¶

The running status of the simulation itself: - general simulation status: [running, stopped, loading, uninitialized] - achieved speed - requested speed - uptime - model-time (clock) - 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, HMIs, and automation services detect execution state changes immediately without relying on log parsing or inefficient polling.

Simulator Control¶

start/run
stop/shut-down
set speed
step (one tick/time-step)
set time/simulator-clock
load file/case/snapshot
save file/case/snapshot
pause
download file/case/snapshot
upload file/case/snapshot
delete file/case/snapshot

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. - set speed allows the orchestrator or test harness to control the real-time factor so that studies can be accelerated, slowed down, or synchronized with external systems. - step / single tick enables deterministic and reproducible replay, which is essential for debugging, validation, and controller testing. - set time / simulator clock allows the simulator to jump, reset, or align execution to a specific model time without replaying from the beginning. - 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.

Data Access¶

available types (describes which kind of units, modules, nodes, blocks, devices, and control elements the simulator contains, and which attributes and functions each object provides)
available units of measurement per attribute
topology (structure of available units, modules, streams, signals, and other 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 modules, streams, signals, and device-level capabilities without hard-coded assumptions. - available units of measurement ensure that engineering values are interpreted correctly. - topology lets clients traverse complex process 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 and control values should be pushed efficiently rather than polled aggressively.