cleave.api package¶

Submodules¶

cleave.api.cli module¶

cleave.api.controller module¶

class cleave.api.controller.Controller¶

Bases: ABC

Base class for controllers, which defines a a simple interface that extending subclasses need to implement.

abstract process(sensor_values: Mapping[str, Union[int, float, bool]]) → Mapping[str, Union[int, float, bool]]¶

Processes samples and produces a control command.

Samples arrive in the form of a dictionary of mappings from sensor property name to measured value. Actuator commands should be returned in the same fashion, in a dictionary of mappings from actuated property name to actuated value.

This method needs to be implemented by extending subclasses with their respective logic.

Parameters: sensor_values – A mapping of sensor property names to measured values.
Returns: A mapping of actuated property names to desired values.
Return type: PhyPropMapping

cleave.api.plant module¶

exception cleave.api.plant.UnrecoverableState(prop_values: Mapping[str, Union[int, float, bool]])¶: Bases: Exception

class cleave.api.plant.ControllerParameter(value: Any, record: bool = False)¶

Bases: BaseSemanticVariable

Note: Parameter from plant to controller is not yet implemented.

A semantically significant variable corresponding to an initialization parameter for a controller interacting with this plant.

Variables of this type will automatically be provided to the controller on initialization

Parameters

value – The initial value for this variable.
record – Whether this variable should be recorded or not (WIP) TODO: record variables
sanity_check – A callable which takes a single input value and returns a boolean. If this value is not None, the callable give will be invoked with the updated value of the semantic variable after every tick of the plant. If the callable returns false, the simulation will fail with an UnrecoverableState error.

class cleave.api.plant.SensorVariable(value: Any, record: bool = True, sanity_check: Optional[Callable[[Any], bool]] = None)¶

Bases: BaseSemanticVariable

A semantically significant variable corresponding to a property measured by a sensor. Variables of this type will automatically be paired with the corresponding Sensor during emulation.

Parameters

value – The initial value for this variable.
record – Whether this variable should be recorded or not (WIP) TODO: record variables
sanity_check – A callable which takes a single input value and returns a boolean. If this value is not None, the callable give will be invoked with the updated value of the semantic variable after every tick of the plant. If the callable returns false, the simulation will fail with an UnrecoverableState error.

class cleave.api.plant.ActuatorVariable(value: Any, record: bool = True, sanity_check: Optional[Callable[[Any], bool]] = None)¶

Bases: BaseSemanticVariable

A semantically significant variable corresponding to a property measured by an actuator. Variables of this type will automatically be paired with the corresponding Actuator during emulation.

Parameters

value – The initial value for this variable.
record – Whether this variable should be recorded or not (WIP) TODO: record variables
sanity_check – A callable which takes a single input value and returns a boolean. If this value is not None, the callable give will be invoked with the updated value of the semantic variable after every tick of the plant. If the callable returns false, the simulation will fail with an UnrecoverableState error.

class cleave.api.plant.State¶

Bases: StateBase, ABC

Abstract core class defining an interface for Plant state evolution over the course of a simulation. Implementing classes need to extend the advance() method to implement their logic, as this method will be called by the plant on each emulation time step.

abstract advance(delta_t: float) → None¶

Called by the plant on every time step to advance the emulation. Needs to be implemented by subclasses.

Parameters: delta_t – Time elapsed since the previous call to this method. This value will be 0 the first time this method is called.

initialize() → None¶: Called by the plant at the beginning of the emulation.

shutdown() → None¶: Called by the plant on shutdown.

class cleave.api.plant.Sensor(prop_name: str, sample_freq: int)¶

Bases: ABC

This class defines an interface for sensors attached to a simulated plant. Implementations should override the process_sample() method with their logic.

Parameters

prop_name – Name of the property this sensor measures.
sample_freq – Sampling frequency of this sensor.

property measured_property_name: str¶

Returns: Name of the property monitored by this sensor.
Return type: str

property sampling_frequency: int¶

Returns: Sampling frequency of this sensor, expressed in Hertz.
Return type: int

abstract process_sample(value: Union[int, float, bool]) → Union[int, float, bool]¶

Processes the measured value. This method should be implemented by subclasses to include sensor-specific behaviors.

Parameters: value – The latest measurement of the monitored property.
Returns: A possibly transformed value of the monitored property, according to the internal parameters of this sensor.
Return type: PhyPropType

class cleave.api.plant.SimpleSensor(prop_name: str, sample_freq: int)¶

Bases: Sensor

Simplest implementation of a sensor, which performs no processing on the read value and returns it as-is.

Parameters

prop_name – Name of the property this sensor measures.
sample_freq – Sampling frequency of this sensor.

process_sample(value: Union[int, float, bool]) → Union[int, float, bool]¶

Processes the measured value. This method should be implemented by subclasses to include sensor-specific behaviors.

Parameters: value – The latest measurement of the monitored property.
Returns: A possibly transformed value of the monitored property, according to the internal parameters of this sensor.
Return type: PhyPropType

class cleave.api.plant.Actuator(prop_name: str)¶

Bases: ABC

Abstract core class for actuators. Implementations should override the set_value() and get_actuation() methods with their logic.

Parameters: prop_name – Name of the property actuated upon by this actuator.

property actuated_property_name: str¶

Returns: Name of the property actuated upon by this actuator.
Return type: str

abstract set_value(desired_value: Union[int, float, bool]) → None¶

Called to set the target value for this actuator. This method should be implemented by extending classes.

Parameters: desired_value – Target value for this actuator.

abstract get_actuation() → Union[int, float, bool]¶

Returns the next value for the actuation processed governed by this actuator. This method should be implemented by extending classes.

Returns: A value for the actuated property.
Return type: PhyPropType

class cleave.api.plant.SimpleConstantActuator(initial_value: Union[int, float, bool], prop_name: str)¶

Bases: Actuator

Implementation of a perfect actuator which keeps its value after being read (i.e. can be thought of as applying a constant force/actuation on the target variable).

Parameters: prop_name – Name of the property actuated upon by this actuator.

set_value(desired_value: Union[int, float, bool]) → None¶

Sets the value of the actuated property governed by this actuator.

Parameters: desired_value – The value of the actuated property.

get_actuation() → Union[int, float, bool]¶

Returns: The current value of the actuated property.
Return type: PhyPropType

class cleave.api.plant.SimpleImpulseActuator(prop_name: str, default_value: Union[int, float, bool])¶

Bases: Actuator

Implementation if a perfect actuator which resets its value after being read (i.e. can be thought as an actuator which applies impulses to the target variable).

Parameters: prop_name – Name of the property actuated upon by this actuator.

set_value(desired_value: Union[int, float, bool]) → None¶

Sets the next value returned by this actuator.

Parameters: desired_value – Value returned in the next call to get_actuation().

get_actuation() → Union[int, float, bool]¶

Returns the internally stored value, and then resets it to the default value.

Returns: The actuation value.
Return type: PhyPropType

class cleave.api.plant.GaussianConstantActuator(prop_name: str, g_mean: float, g_std: float, initial_value: Optional[Union[int, float, bool]] = None, prealloc_size: int = 1000000)¶

Bases: SimpleConstantActuator

Implementation of an actuator with Gaussian noise in its output.

Parameters: prop_name – Name of the property actuated upon by this actuator.

set_value(desired_value: Union[int, float, bool]) → None¶

Sets the value of the actuated property governed by this actuator.

Parameters: desired_value – The value of the actuated property.

cleave.api.util module¶

cleave.api.util.PhyPropType¶

Type of properties that can be handled by sensors and actuators.

alias of Union[int, float, bool]