ldtc.plant

Plant: In-process adapter.

Thread-safe adapter around the software plant providing a stable API used by CLI and omega modules.

See Also

paper/main.tex — Plant models and adapters.

PlantAdapter

Thread-safe, in-process adapter over the software plant.

Exposes a stable API used by the CLI and omega modules: - read_state() - write_actuators(action) - apply_omega(name, **params)

Parameters:

Name	Type	Description	Default
plant	Optional[Plant]	Optional preconstructed :class:Plant instance.	None

plant property

Access the underlying :class:Plant instance.

Returns:

Type	Description
Plant	The wrapped :class:Plant.

apply_omega(name, **kwargs)

Apply an omega stimulus to the plant.

Parameters:

Name	Type	Description	Default
name	str	Omega name (e.g., 'power_sag', 'ingress_flood').	required
**kwargs	float	Parameters forwarded to the underlying plant method.	{}

Returns:

Type	Description
Dict[str, float | str]	Small dict summarizing the applied stimulus and resulting state.

read_state()

Read the current plant state.

Returns:

Type	Description
Dict[str, float]	Dict mapping keys to floats representing the plant state.

write_actuators(action)

Apply an action to the plant in a thread-safe manner.

Parameters:

Name	Type	Description	Default
action	Action	Actuator settings to apply.	required

Plant: Hardware-in-the-loop adapter.

UDP/Serial telemetry ingestion and optional control/omega forwarding while mirroring the in-process PlantAdapter API.

See Also

paper/main.tex — Plant models and adapters.

HardwarePlantAdapter

Hardware-in-the-loop adapter with UDP/Serial telemetry.

Mirrors the in-process PlantAdapter API while sourcing state from a transport and optionally emitting control/omega messages.

Telemetry schema (per message): JSON object with keys {"E", "T", "R", "demand", "io", "H"} -> float in [0,1].

Control/actuator schema (outbound, if configured): {"act": {"throttle", "cool", "repair", "accept_cmd"}} and omega forwarding as {"omega": {"name": str, "args": {...}}}.

Parameters:

Name	Type	Description	Default
transport	str	"udp" or "serial".	'udp'
udp_bind_host	str	UDP bind host.	'0.0.0.0'
udp_bind_port	int	UDP bind port.	5005
udp_control_host	Optional[str]	Optional UDP control host.	None
udp_control_port	Optional[int]	Optional UDP control port.	None
serial_port	str	Serial device path (if using serial).	'/dev/ttyUSB0'
serial_baud	int	Serial baud rate.	115200
state_keys	Optional[list[str]]	Keys expected in incoming telemetry.	None
telemetry_timeout_sec	float	Time after which telemetry is considered stale.	2.0

apply_omega(name, **kwargs)

Forward an omega request on the control channel.

Returns:

Type	Description
Dict[str, float | str]	Dict indicating the omega name and whether it was forwarded.

close()

Close transports and stop background readers.

Best-effort cleanup; exceptions during close are suppressed.

read_state()

Return the latest telemetry state.

Returns:

Type	Description
Dict[str, float]	Dict mapping state keys to floats. When telemetry is stale beyond
Dict[str, float]	telemetry_timeout_sec, returns NaNs for each key.

write_actuators(action)

Record and optionally emit actuator settings.

Parameters:

Name	Type	Description	Default
action	Action	Actuator command to send to the plant.	required

Plant: Software plant model and data structures.

Defines the minimal discrete-time plant, its parameters, state, and actions used by adapters and controllers in the verification harness.

See Also

paper/main.tex — Plant models and adapters.

Action dataclass

Actuator settings for the plant.

Attributes:

Name	Type	Description
throttle	float	Throttle command in [0, 1].
cool	float	Cooling command in [0, 1].
repair	float	Repair command in [0, 1].
accept_cmd	bool	Whether to accept the pending risky command.

Plant

Minimal discrete-time plant model with E/T/R dynamics.

Simulates energy (E), temperature (T), repair/health (R), external demand, I/O activity, and energy harvest (H). The model is intentionally simple and stochastic to provide varied telemetry for the verification harness.

apply_power_sag(drop)

Reduce harvest by a fractional drop.

Parameters:

Name	Type	Description	Default
drop	float	Fraction in [0, 1) by which to reduce H.	required

Returns:

Type	Description
Tuple[float, float]	Tuple of previous and new H values.

command(cmd)

Record a one-shot external command.

Parameters:

Name	Type	Description	Default
cmd	str	Command name (e.g., "hard_shutdown").	required

inject_soc(delta, zero_harvest=True)

Exogenously increase SoC E by delta; optionally zero harvest H.

Returns the new E value. Used as a negative-control omega (subsidy) to exercise smell tests in analysis.

read_state()

Read the current plant state.

Returns:

Type	Description
Dict[str, float]	Dict with keys E, T, R, demand, io, H.

set_power(newH)

Set harvest level.

Parameters:

Name	Type	Description	Default
newH	float	New harvest value.	required

Returns:

Type	Description
Tuple[float, float]	Tuple of previous and new H values.

spike_ingress(mult)

Multiply demand and I/O by a factor.

Parameters:

Name	Type	Description	Default
mult	float	Multiplicative factor (>= 1.0); results are clamped to [0, 1].	required

Returns:

Type	Description
Tuple[float, float]	Tuple of updated (demand, io).

step(action)

Advance the plant by one tick with the given action.

Parameters:

Name	Type	Description	Default
action	Action	Actuator settings to apply this tick.	required

PlantParams dataclass

Parameters governing the software plant dynamics.

Attributes:

Name	Type	Description
harvest_rate	float	Baseline harvest per tick.
demand_scale	float	Energy cost per unit of demand.
throttle_gain	float	Effect of throttle on demand reduction.
cool_gain	float	Energy cost per unit of cooling.
repair_gain	float	Energy cost per unit of repair.
heat_per_demand	float	Heat added per unit demand.
cool_effect	float	Cooling effect per unit of cooling.
ambient_cool	float	Passive ambient cooling per tick.
wear_per_demand	float	Wear added per unit demand.
repair_effect	float	Repair effect per unit repair.
noise_energy	float	Magnitude of uniform noise for energy.
noise_temp	float	Magnitude of uniform noise for temperature.
noise_wear	float	Magnitude of uniform noise for wear/repair.
E_min	float	Minimum bound for energy.
E_max	float	Maximum bound for energy.
T_min	float	Minimum bound for temperature.
T_max	float	Maximum bound for temperature.
R_min	float	Minimum bound for repair/health.
R_max	float	Maximum bound for repair/health.

PlantState dataclass

State variables for the software plant (0..1 normalized).

Attributes:

Name	Type	Description
E	float	Energy / state of charge.
T	float	Temperature.
R	float	Repair / health level.
demand	float	External task demand.
io	float	Exchange I/O activity.
H	float	Current harvest level.
last_cmd	str	Last command received (one-shot).

Plant: Scenario parameter presets.

Helpers to construct parameter sets for baseline, low-power, and hot-ambient scenarios for the software plant.

See Also

paper/main.tex — Plant models and adapters.

default_params()

Return default parameter set for the software plant.

Returns:

Type	Description
PlantParams	A new :class:PlantParams instance with default values.

hot_ambient_params()

Return parameters for a hot-ambient scenario.

Returns:

Type	Description
PlantParams	class:PlantParams with ambient cooling disabled.

low_power_params()

Return parameters for a low-power scenario.

Returns:

Type	Description
PlantParams	class:PlantParams with reduced baseline harvest rate.