hermes.scripting.api.SimulationAPI Class Reference

Public Member Functions
None	__init__ (self, str shm_name)
None	connect (self)
None	disconnect (self)
float	get (self, str signal)
None	set (self, str signal, float value)
int	get_frame (self)
float	get_time (self)
int	get_time_ns (self)
bool	wait_frame (self, int target, float timeout=10.0)
bool	wait_time (self, float target, float timeout=10.0)
bool	wait_time_ns (self, int target_ns, float timeout=10.0)
None	inject (self, dict[str, float] values)
dict[str, float]	sample (self, list[str] signals)
list[str]	list_signals (self)
SimulationAPI	__enter__ (self)
None	__exit__ (self, *object args)

Protected Attributes
	_shm_name = shm_name
	_shm = SharedMemoryManager(shm_name)
bool	_attached = False

Detailed Description

Python API for interacting with running simulations.

Connects to a Hermes simulation via shared memory and provides
methods for reading and writing signal values.

Constructor & Destructor Documentation

__init__()

None hermes.scripting.api.SimulationAPI.__init__	(		self,
		str	shm_name )

Initialize simulation API.

Args:
    shm_name: Shared memory segment name (e.g., "/hermes_sim")

Member Function Documentation

__enter__()

SimulationAPI hermes.scripting.api.SimulationAPI.__enter__

(

self

)

__exit__()

None hermes.scripting.api.SimulationAPI.__exit__	(		self,
		*object	args )

connect()

None hermes.scripting.api.SimulationAPI.connect

(

self

)

Connect to the simulation's shared memory.

Raises:
    RuntimeError: If already connected
    posix_ipc.ExistentialError: If simulation not running

disconnect()

None hermes.scripting.api.SimulationAPI.disconnect

(

self

)

Disconnect from the simulation.

get()

float hermes.scripting.api.SimulationAPI.get	(		self,
		str	signal )

Get signal value by qualified name.

Args:
    signal: Full signal path (module.signal)

Returns:
    Current signal value

Raises:
    RuntimeError: If not connected
    KeyError: If signal not found

get_frame()

int hermes.scripting.api.SimulationAPI.get_frame

(

self

)

Get current simulation frame number.

Returns:
    Current frame number

Raises:
    RuntimeError: If not connected

get_time()

float hermes.scripting.api.SimulationAPI.get_time

(

self

)

Get current simulation time in seconds.

This is derived from `get_time_ns()` for API convenience.
For deterministic comparisons, use `get_time_ns()` instead.

Returns:
    Current simulation time in seconds

Raises:
    RuntimeError: If not connected

get_time_ns()

int hermes.scripting.api.SimulationAPI.get_time_ns

(

self

)

Get current simulation time in nanoseconds.

This is the authoritative time value for deterministic simulations.
Use this for exact comparisons and reproducibility.

Returns:
    Current simulation time in nanoseconds

Raises:
    RuntimeError: If not connected

inject()

None hermes.scripting.api.SimulationAPI.inject	(		self,
		dict[str, float]	values )

Inject multiple values at once.

Args:
    values: Dictionary mapping signal names to values

Raises:
    RuntimeError: If not connected
    KeyError: If any signal not found

list_signals()

list[str] hermes.scripting.api.SimulationAPI.list_signals

(

self

)

Get list of all available signals.

Returns:
    List of qualified signal names

Raises:
    RuntimeError: If not connected

sample()

dict[str, float] hermes.scripting.api.SimulationAPI.sample	(		self,
		list[str]	signals )

Sample multiple signals at once.

Args:
    signals: List of signal names

Returns:
    Dictionary mapping signal names to values

Raises:
    RuntimeError: If not connected
    KeyError: If any signal not found

set()

None hermes.scripting.api.SimulationAPI.set	(		self,
		str	signal,
		float	value )

Set signal value by qualified name.

Args:
    signal: Full signal path (module.signal)
    value: Value to set

Raises:
    RuntimeError: If not connected
    KeyError: If signal not found

wait_frame()

bool hermes.scripting.api.SimulationAPI.wait_frame	(		self,
		int	target,
		float	timeout = 10.0 )

Wait until simulation reaches target frame.

Args:
    target: Target frame number
    timeout: Maximum seconds to wait

Returns:
    True if target reached, False if timeout

Raises:
    RuntimeError: If not connected

wait_time()

bool hermes.scripting.api.SimulationAPI.wait_time	(		self,
		float	target,
		float	timeout = 10.0 )

Wait until simulation reaches target time in seconds.

Note: Uses floating-point comparison. For deterministic behavior,
use `wait_time_ns()` instead.

Args:
    target: Target simulation time in seconds
    timeout: Maximum wall-clock seconds to wait

Returns:
    True if target reached, False if timeout

Raises:
    RuntimeError: If not connected

wait_time_ns()

bool hermes.scripting.api.SimulationAPI.wait_time_ns	(		self,
		int	target_ns,
		float	timeout = 10.0 )

Wait until simulation reaches target time in nanoseconds.

This is the deterministic version - uses integer comparison for
exact reproducibility.

Args:
    target_ns: Target simulation time in nanoseconds
    timeout: Maximum wall-clock seconds to wait

Returns:
    True if target reached, False if timeout

Raises:
    RuntimeError: If not connected

Member Data Documentation

_attached

bool hermes.scripting.api.SimulationAPI._attached = False

protected

_shm

hermes.scripting.api.SimulationAPI._shm = SharedMemoryManager(shm_name)

protected

_shm_name

hermes.scripting.api.SimulationAPI._shm_name = shm_name

protected

---

The documentation for this class was generated from the following file:

• src/hermes/scripting/api.py