BF-SYSTEMS - State-based Systems

Ver. 1.7.3 (2023-03-08)

This module provides models and templates for state based systems.

class mlpro.bf.systems.basics.State(p_state_space: MSpace, p_initial: bool = False, p_terminal: bool = False, p_success: bool = False, p_broken: bool = False, p_timeout: bool = False)

Bases: Element, TStamp

State of a system as an element of a given state space. Additionally, the state can be labeled with various properties.

Parameters:

• p_state_space (MSpace) – State space of the related system.

• p_initial (bool) – This optional flag signals that the state is the first one after a reset. Default=False.

• p_terminal (bool) – This optional flag labels the state as a terminal state. Default=False.

• p_success (bool) – This optional flag labels the state as an objective state. Default=False.

• p_broken (bool) – This optional flag labels the state as a final error state. Default=False.

• p_timeout (bool) – This optional flag signals that the cycle limit of an episode has been reached. Default=False.

get_initial() → bool

set_initial(p_initial: bool)

get_success() → bool

set_success(p_success: bool)

get_broken() → bool

set_broken(p_broken: bool)

get_timeout() → bool

set_timeout(p_timeout: bool)

get_terminal() → bool

set_terminal(p_terminal: bool)

class mlpro.bf.systems.basics.ActionElement(p_action_space: Set, p_weight: float = 1.0)

Bases: Element

Single entry of an action. See class Action for further details.

Parameters:

• p_action_space (Set) – Related action space.

• p_weight (float) – Weight of action element. Default = 1.0.

get_weight()

set_weight(p_weight)

class mlpro.bf.systems.basics.Action(p_agent_id=0, p_action_space: Set | None = None, p_values: ndarray | None = None)

Bases: ElementList, TStamp

Objects of this class represent actions of (multi-)agents. Every element of the internal list is related to an agent, and its partial subsection. Action values for the first agent can be added while object instantiation. Action values of further agents can be added by using method self.add_elem().

Parameters:

• p_agent_id – Unique id of (first) agent to be added

• p_action_space (Set) – Action space of (first) agent to be added

• p_values (np.ndarray) – Action values of (first) agent to be added

get_agent_ids()

get_sorted_values() → ndarray

class mlpro.bf.systems.basics.FctSTrans(p_logging=True)

Bases: Log

Template class for state transition functions.

Parameters:

p_logging – Log level (see class Log for more details). Default = Log.C_LOG_ALL.

C_TYPE = 'Fct STrans'

simulate_reaction(p_state: State, p_action: Action) → State

Simulates a state transition based on a state and action. Custom method _simulate_reaction() is called.

Parameters:

• p_state (State) – System state.

• p_action (Action) – Action to be processed.

Returns:

new_state – Result state after state transition.

Return type:

State

_simulate_reaction(p_state: State, p_action: Action) → State

Custom method for a simulated state transition. See method simulate_reaction() for further details.

class mlpro.bf.systems.basics.FctSuccess(p_logging=True)

Bases: Log

Template class for functions that determine whether or not a state is a success state.

Parameters:

p_logging – Log level (see class Log for more details). Default = Log.C_LOG_ALL.

C_TYPE = 'Fct Success'

compute_success(p_state: State) → bool

Assesses the given state regarding success criteria. Custom method _compute_success() is called.

Parameters:

p_state (State) – System state.

Returns:

success – True, if given state is a success state. False otherwise.

Return type:

bool

_compute_success(p_state: State) → bool

Custom method for assessment for success. See method compute_success() for further details.

class mlpro.bf.systems.basics.FctBroken(p_logging=True)

Bases: Log

Template class for functions that determine whether or not a state is a broken state.

Parameters:

p_logging – Log level (see class Log for more details). Default = Log.C_LOG_ALL.

C_TYPE = 'Fct Broken'

compute_broken(p_state: State) → bool

Assesses the given state regarding breakdown criteria. Custom method _compute_success() is called.

Parameters:

p_state (State) – System state.

Returns:

broken – True, if given state is a breakdown state. False otherwise.

Return type:

bool

_compute_broken(p_state: State) → bool

Custom method for assessment for breakdown. See method compute_broken() for further details.

class mlpro.bf.systems.basics.Sensor(p_name_short, p_base_set='R', p_name_long='', p_name_latex='', p_unit='', p_unit_latex='', p_boundaries: list = [], p_description='', p_symmetrical: bool = False, p_logging=False, **p_kwargs)

Bases: Dimension

Template for a sensor.

C_TYPE = 'Sensor'

class mlpro.bf.systems.basics.Actuator(p_name_short, p_base_set='R', p_name_long='', p_name_latex='', p_unit='', p_unit_latex='', p_boundaries: list = [], p_description='', p_symmetrical: bool = False, p_logging=False, **p_kwargs)

Bases: Dimension

Template for an actuator.

C_TYPE = 'Actuator'

class mlpro.bf.systems.basics.Controller(p_id, p_name: str = '', p_logging: bool = True, **p_kwargs)

Bases: EventManager

Template for a controller that enables access to sensors and actuators.

Parameters:

• p_id – Unique id of the controller.

• p_name (str) – Optional name of the controller.

• p_logging – Log level (see class Log for more details). Default = Log.C_LOG_ALL.

• p_kwargs (dict) – Further keyword arguments specific to the controller.

C_EVENT_COMM_ERROR

Event that is raised on a communication error

C_TYPE = 'Controller'

C_EVENT_COMM_ERROR = 'COMM_ERROR'

reset() → bool

Resets the controller by calling custom method _reset().

Returns:

result – True, if successful. False otherwise. Additionally event C_EVENT_COMM_ERROR is raised.

Return type:

bool

_reset() → bool

Custom reset method.

Returns:

result – True, if successful. False otherwise.

Return type:

bool

add_sensor(p_sensor: Sensor)

Adds a sensor to the controller.

Parameters:

p_sensor (Sensor) – Sensor object to be added.

get_sensors() → Set

Returns the internal set of sensors.

Returns:

sensors – Set of sensors.

Return type:

Set

get_sensor(p_id) → Sensor

Returns a sensor.

get_sensor_value(p_id)

Deternines the value of a sensor by calling custom method _get_sensor_value().

Parameters:

p_id – Id of the sensor.

Returns:

Current value of the sensor or None on a communication error. In that case, event C_EVENT_COMM_ERROR is raised additionally.

Return type:

value

_get_sensor_value(p_id)

Custom method to get a sensor value. See method get_sensor_value() for further details.

Parameters:

p_id – Id of the sensor.

Returns:

Current value of the sensor or None on a communication error.

Return type:

value

add_actuator(p_actuator: Actuator)

Adds an actuator to the controller.

Parameters:

p_actuator (Actuator) – Actuator object to be added.

get_actuators() → Set

Returns the internal set of actuators.

Returns:

actuators – Set of actuators.

Return type:

Set

get_actuator(p_id) → Actuator

Returns an actuator.

set_actuator_value(p_id, p_value) → bool

Sets the value of an actuator by calling custom method _set_actuatur_value().

Parameters:

• p_id – Id of the actuator.

• p_value – New actuator value.

Returns:

successful – True, if successful. False otherwise. In that case, event C_EVENT_COMM_ERROR is raised additionally.

Return type:

bool

_set_actuator_value(p_id, p_value) → bool

Custom method to set an actuator value. See method set_sensor_value() for further details.

Parameters:

• p_id – Id of the actuator.

• p_value – New actuator value.

Returns:

successful – True, if successful. False otherwise.

Return type:

bool

class mlpro.bf.systems.basics.System(p_mode=0, p_latency: timedelta | None = None, p_fct_strans: FctSTrans | None = None, p_fct_success: FctSuccess | None = None, p_fct_broken: FctBroken | None = None, p_mujoco_file=None, p_name=None, p_frame_skip: int = 1, p_state_mapping=None, p_action_mapping=None, p_camera_conf: tuple = (None, None, None), p_visualize: bool = False, p_logging=True)

Bases: FctSTrans, FctSuccess, FctBroken, Mode, Plottable, LoadSave, ScientificObject

Base class for state based systems.

Parameters:

• p_mode – Mode of the system. Possible values are Mode.C_MODE_SIM(default) or Mode.C_MODE_REAL.

• p_latency (timedelta) – Optional latency of the system. If not provided, the internal value of constant C_LATENCY is used by default.

• p_fct_strans (FctSTrans) – Optional external function for state transition.

• p_fct_success (FctSuccess) – Optional external function for state evaluation ‘success’.

• p_fct_broken (FctBroken) – Optional external function for state evaluation ‘broken’.

• p_mujoco_file – Path to XML file for MuJoCo model.

• p_frame_skip (int) – Frame to be skipped every step. Default = 1.

• p_state_mapping – State mapping if the MLPro state and MuJoCo state have different naming.

• p_action_mapping – Action mapping if the MLPro action and MuJoCo action have different naming.

• p_use_radian (bool) – Use radian if the action and the state based on radian unit. Default = True.

• p_camera_conf (tuple) – Default camera configuration on MuJoCo Simulation (xyz position, elevation, distance).

• p_visualize (bool) – Boolean switch for env/agent visualisation. Default = False.

• p_logging – Log level (see class Log for more details). Default = Log.C_LOG_ALL.

_latency

Latency of the system.

Type:

timedelta

_state

Current state of system.

Type:

State

_prev_state

Previous state of system.

Type:

State

_last_action

Last action.

Type:

Action

_fct_strans

Internal state transition function.

Type:

FctSTrans

_fct_success

Internal function for state evaluation ‘success’.

Type:

FctSuccess

_fct_broken

Internal function for state evaluation ‘broken’.

Type:

FctBroken

C_TYPE = 'System'

C_LATENCY = datetime.timedelta(seconds=1)

C_PLOT_ACTIVE: bool = True

static setup_spaces()

Static template method to set up and return state and action space of environment.

Returns:

• state_space (MSpace) – State space object

• action_space (MSpace) – Action space object

static load(p_path, p_filename)

Loads content from the given path and file name. If file does not exist, it returns None.

Parameters:

• file (p_path Path that contains the) –

• name (p_filename File) –

Returns:

A loaded object, if file content was loaded successfully. None otherwise.

_save(p_path, p_filename) → bool

Custom method for saving an object. The default implementation is based on pickle/dill. Redefine on demand. See method save() for further details.

switch_logging(p_logging)

Sets new log level.

Parameters:

p_logging – Log level (constant C_LOG_LEVELS contains valid values)

get_latency() → timedelta

Returns latency of the system.

set_latency(p_latency: timedelta | None = None) → None

Sets latency of the system. If p_latency is None latency will be reset to internal value of attribute C_LATENCY.

Parameters:

p_latency (timedelta) – New latency value

get_state_space() → MSpace

get_action_space() → MSpace

set_random_seed(p_seed=None)

Resets the internal random generator using the given seed.

Parameters:

p_seed (int) – Seed parameter for an internal random generator

reset(p_seed=None) → None

Resets the system to an initial state. If MuJoCo is not used, the custom method _reset() is called.

Parameters:

p_seed (int) – Seed parameter for an internal random generator

_reset(p_seed=None) → None

Custom method to reset the system to an initial/defined state. Use method _set_status() to set the state.

Parameters:

p_seed (int) – Seed parameter for an internal random generator

add_controller(p_controller: Controller, p_mapping: list) → bool

Adds a controller and a related mapping of states and actions to sensors and actuators.

Parameters:

• p_controller (Controller) – Controller object to be added.

• p_mapping (list) – A list of mapping tuples following the syntax ( [Type = ‘S’ or ‘A’], [Name of state/action] [Name of sensor/actuator] )

Returns:

successful – True, if controller and related mapping was added successfully. False otherwise.

Return type:

bool

get_state() → State

Returns current state of the system.

_set_state(p_state: State)

Explicitly sets the current state of the system. Internal use only.

process_action(p_action: Action) → bool

Processes a state transition based on the current state and a given action. The state transition itself is implemented in child classes in the custom method _process_action().

Parameters:

p_action (Action) – Action to be processed

Returns:

success – True, if action processing was successfull. False otherwise.

Return type:

bool

_process_action(p_action: Action) → bool

Internal custom method for state transition with default implementation. To be redefined in a child class on demand. See method process_action() for further details.

simulate_reaction(p_state: State | None = None, p_action: Action | None = None) → State

Simulates a state transition based on a state and an action. The simulation step itself is carried out either by an internal custom implementation in method _simulate_reaction() or by an embedded external function.

Parameters:

• p_state (State) – Current state.

• p_action (Action) – Action.

Returns:

Subsequent state after transition

Return type:

State

_simulate_reaction(p_state: State, p_action: Action) → State

Custom method for a simulated state transition. Implement this method if no external state transition function is used. See method simulate_reaction() for further details.

action_to_mujoco(p_mlpro_action)

Action conversion method from converting MLPro action to MuJoCo action.

_action_to_mujoco(p_mlpro_action)

Custom method for to do transition between MuJoCo state and MLPro state. Implement this method if the MLPro state has different dimension from MuJoCo state.

Parameters:

p_mujoco_state (Numpy) – MLPro action.

Returns:

Modified MLPro action

Return type:

Numpy

state_from_mujoco(p_mujoco_state)

State conversion method from converting MuJoCo state to MLPro state.

_state_from_mujoco(p_mujoco_state)

Custom method for to do transition between MuJoCo state and MLPro state. Implement this method if the MLPro state has different dimension from MuJoCo state.

Parameters:

p_mujoco_state (Numpy) – MuJoCo state.

Returns:

Modified MuJoCo state

Return type:

Numpy

_import_state() → bool

_export_action(p_action: Action) → bool

compute_success(p_state: State) → bool

Assesses the given state whether it is a ‘success’ state. Assessment is carried out either by a custom implementation in method _compute_success() or by an embedded external function.

Parameters:

p_state (State) – State to be assessed.

Returns:

success – True, if the given state is a ‘success’ state. False otherwise.

Return type:

bool

_compute_success(p_state: State) → bool

Custom method for assessment for success. Implement this method if no external function is used. See method compute_success() for further details.

get_success() → bool

compute_broken(p_state: State) → bool

Assesses the given state whether it is a ‘broken’ state. Assessment is carried out either by a custom implementation in method _compute_broken() or by an embedded external function.

Parameters:

p_state (State) – State to be assessed.

Returns:

broken – True, if the given state is a ‘broken’ state. False otherwise.

Return type:

bool

_compute_broken(p_state: State) → bool

Custom method for assessment for breakdown. Implement this method if no external function is used. See method compute_broken() for further details.

get_broken() → bool

init_plot(p_figure: Figure | None = None, p_plot_settings: PlotSettings | None = None, **p_kwargs)

Initializes the plot functionalities of the class.

Parameters:

• p_figure (Matplotlib.figure.Figure, optional) – Optional MatPlotLib host figure, where the plot shall be embedded. The default is None.

• p_plot_settings (PlotSettings) – Optional plot settings. If None, the default view is plotted (see attribute C_PLOT_DEFAULT_VIEW).

update_plot(**p_kwargs)

Updates the plot.

Parameters:

**p_kwargs – Implementation-specific plot data and/or parameters.