SimulatorClient

class pystclient.clients.SimulatorClient(session: Session)

Bases: BaseClient

Client for creating, controlling, and monitoring simulators on the STC platform.

Manages the full simulator lifecycle: creation, readiness polling, start/stop control, result recording, and graceful termination. Long-running operations such as waiting for readiness are executed asynchronously via a thread pool.

__init__(session: Session) → None

Methods

__init__(session)
create(model)	Provision one or more simulators on the STC platform from a configuration.
end_simulation(simulator_id)	Gracefully end a simulation and asynchronously wait for result data.
finished(*simulator_ids)	Determine whether all specified simulators have completed their runs.
ready(simulator_id)	Check whether a simulator has completed initialization and is ready to start.
start(simulator_id, *[, record])	Begin executing a simulator that is in the ready state.
start_logging(simulator_id)	Begin recording simulation results for a running simulator.
status(simulator_id)	Retrieve the current status of a running or recently stopped simulator.
stop(simulator_id)	Pause a running simulator without ending the simulation.
stop_logging(simulator_id)	Stop recording simulation results and upload them to the platform.
terminate(simulator_id)	Terminate a simulator and release its server-side resources.
wait_until_ready(*simulator_ids[, timeout])	Block until all specified simulators have finished initializing and are ready to run.

Attributes

session

create(model: SimulationConfig) → tuple[list[SimulatorStatus], Future[bool]]

Provision one or more simulators on the STC platform from a configuration.

Sends the simulation configuration to the API and returns immediately with the initial statuses. A background Future is also returned that resolves to True once all created simulators are ready to accept start commands.

Parameters:

model – The simulation configuration describing which models, parameters, and connections to use

Returns:

A tuple of (initial simulator statuses, a future that resolves to True when all simulators are ready)

Raises:

PyStclientError – If the API returns no simulator statuses

end_simulation(simulator_id: Annotated[str | UUID, PlainSerializer(func=str, return_type=str, when_used=always)]) → Future[SimulationResults | None]

Gracefully end a simulation and asynchronously wait for result data.

Sends the end-simulation command to the simulator and starts a background thread that polls for measurement results. The returned Future resolves to a SimulationResults iterator once results are available, or None if results do not appear within the timeout.

Parameters:

simulator_id – ID of the simulator whose simulation to end

Returns:

A future that resolves to a results iterator, or None on timeout

finished(*simulator_ids: Annotated[str | UUID, PlainSerializer(func=str, return_type=str, when_used=always)]) → bool

Determine whether all specified simulators have completed their runs.

A simulator is considered finished if its simulation time has reached the configured end time, or if it has already been cleaned up by the platform (HTTP 404 or 410).

Parameters:

*simulator_ids – One or more simulator IDs to check

Returns:

True if every simulator has finished, False otherwise

ready(simulator_id: Annotated[str | UUID, PlainSerializer(func=str, return_type=str, when_used=always)]) → bool

Check whether a simulator has completed initialization and is ready to start.

A simulator is considered ready when it is connected to the platform and has progressed past the "initialized" state.

Parameters:

simulator_id – ID of the simulator to check

Returns:

True if the simulator is ready to accept commands

start(simulator_id: Annotated[str | UUID, PlainSerializer(func=str, return_type=str, when_used=always)], *, record: bool = False) → bool

Begin executing a simulator that is in the ready state.

Optionally starts recording simulation results at the same time. Use record=True to combine the start and record-results commands into a single API call.

Parameters:

• simulator_id – ID of the simulator to start

• record – If True, automatically begin recording results upon start, by default False

Returns:

True if the start command was accepted by the server

start_logging(simulator_id: Annotated[str | UUID, PlainSerializer(func=str, return_type=str, when_used=always)]) → bool

Begin recording simulation results for a running simulator.

Recorded results can later be retrieved via the measurement API. To stop recording and trigger an upload, call stop_logging().

Parameters:

simulator_id – ID of the simulator to start recording for

Returns:

True if the record command was accepted by the server

status(simulator_id: Annotated[str | UUID, PlainSerializer(func=str, return_type=str, when_used=always)]) → SimulatorStatus

Retrieve the current status of a running or recently stopped simulator.

Returns detailed information including connection state, simulation time, and the simulator’s lifecycle phase.

Parameters:

simulator_id – ID of the simulator to query

Returns:

Current status snapshot of the simulator

stop(simulator_id: Annotated[str | UUID, PlainSerializer(func=str, return_type=str, when_used=always)]) → bool

Pause a running simulator without ending the simulation.

The simulator can be resumed later with start().

Parameters:

simulator_id – ID of the simulator to stop

Returns:

True if the stop command was accepted by the server

stop_logging(simulator_id: Annotated[str | UUID, PlainSerializer(func=str, return_type=str, when_used=always)]) → bool

Stop recording simulation results and upload them to the platform.

After this call, the recorded data becomes available through the measurement and query APIs.

Parameters:

simulator_id – ID of the simulator to stop recording for

Returns:

True if the stop-and-upload command was accepted by the server

terminate(simulator_id: Annotated[str | UUID, PlainSerializer(func=str, return_type=str, when_used=always)]) → bool

Terminate a simulator and release its server-side resources.

Unlike end_simulation(), this does not wait for results to be persisted. Use this to clean up simulators that are stuck or no longer needed.

Parameters:

simulator_id – ID of the simulator to terminate

Returns:

True if the server accepted the termination request

wait_until_ready(*simulator_ids: Annotated[str | UUID, PlainSerializer(func=str, return_type=str, when_used=always)], timeout: int = 120) → bool

Block until all specified simulators have finished initializing and are ready to run.

Polls each simulator’s status in sequence. Returns True as soon as all simulators report ready, or False if the timeout is exceeded before all are ready.

Parameters:

• *simulator_ids – One or more simulator IDs to wait for

• timeout – Maximum time to wait in seconds, by default 120

Returns:

True if all simulators became ready within the timeout, False otherwise