Core

On the core level the electric motor environment and the interface to its submodules are defined. By using these interfaces further reference generators, reward functions, visualizations or physical models can be implemented.

Each ElectricMotorEnvironment contains the five following modules:

• PhysicalSystem

  • Specification and simulation of the physical model. Furthermore, specifies limits and nominal values for all of its state_variables.

• ReferenceGenerator

  • Calculation of reference trajectories for one or more states of the physical systems state_variables.

• ConstraintMonitor

  • Observation of the PhysicalSystems state to comply to a set of user defined constraints.

• RewardFunction

  • Calculation of the reward based on the physical systems state and the reference.* ElectricMotorVisualization

  • Visualization of the PhysicalSystems state, reference and reward for the user.

class gym_electric_motor.core.Callback

The abstract base class for Callbacks in GEM. Each of its functions gets called at one point in the ElectricMotorEnvironment. .. attribute:: _env

The GEM environment. Use it to have full control over the environment on runtime.

on_close()

Gets called at the beginning of a close

on_reset_begin()

Gets called at the beginning of each reset

on_reset_end(state, reference)

Gets called at the end of each reset

on_step_begin(k, action)

Gets called at the beginning of each step

on_step_end(k, state, reference, reward, terminated)

Gets called at the end of each step

set_env(env)

Sets the environment of the motor.

class gym_electric_motor.core.ConstraintMonitor(limit_constraints=(), additional_constraints=(), merge_violations='max')

The ConstraintMonitor is used within the ElectricMotorEnvironment to monitor the states for illegal / undesired values (e.g. overcurrents).

It consists of a list of multiple independent constraints. Each constraint gets the current observation of the environment as input and returns a violation degree within \([0.0, 1.0]\). All these are merged together and the ConstraintMonitor returns a total violation degree.

Soft Constraints:

To enable a higher flexibility, the constraints return a violation degree (float) instead of a simple violation flag (bool). So, even before the limits are violated, the reward function can take the limit violation degree into account. If the violation degree is at 0.0, no states are in a dangerous region. For values between 0.0 and 1.0 the reward will be decreased gradually so that the agent will learn to avoid these state regions. If the violation degree reaches 1.0 the episode is terminated.

Hard Constraints:

With the above concept, also hard constraints that directly terminate an episode without any “danger”-region can be modeled. Then, the violation degree of the constraint directly changes from 0.0 to 1.0, if a violation occurs.

Parameters:

• limit_constraints (list(str)/'all_states') –

  Shortcut parameter to pass all states that limits shall be observed.

  • list(str): Pass a list with state_names and all of the states will be observed to stay within

    their limits.

  • ’all_states’: Shortcut for all states are observed to stay within the limits.

• additional_constraints (list(Constraint/callable)) – Further constraints that shall be monitored. These have to be initialized first and passed to the ConstraintMonitor. Alternatively, constraints can be defined as a function that takes the current state and returns a float within [0.0, 1.0].

• merge_violations (‘max’/’product’/callable(*violation_degrees) -> float) –

  Function to merge all single violation degrees to a total violation degree.

  • ’max’: Take the maximal violation degree as total violation degree.

  • ’product’: Calculates the total violation degree as one minus the product of one minus all single

    violation degrees.

  • callable(*violation_degrees) -> float: User defined function to calculate the total violation.

check_constraints(state: ndarray)

Function to check and merge all constraints.

Parameters:

state (ndarray(float)) – The current environments state.

Returns:

The total violation degree in [0,1]

Return type:

float

property constraints

Returns the list of all constraints the ConstraintMonitor observes.

set_modules(ps: PhysicalSystem)

The PhysicalSystem of the environment is passed to save important parameters like the index of the states.

Parameters:

ps (PhysicalSystem) – The PhysicalSystem of the environment.

class gym_electric_motor.core.ElectricMotorEnvironment(physical_system, reference_generator, reward_function, visualization=(), state_filter=None, callbacks=(), constraints=(), physical_system_wrappers=(), scale_plots=False, **kwargs)

Description:

The main class connecting all modules of the gym-electric-motor environments.

Modules:

Physical System:

Containing the physical structure and simulation of the drive system as well as information about the technical limits and nominal values. Needs to be a subclass of PhysicalSystem

Reference Generator:

Generation of the reference for the motor to follow. Needs to be a subclass of ReferenceGenerator

Reward Function:

Calculation of the reward based on the state of the physical system and the generated reference and observation if the motor state is within the limits. Needs to be a subclass of RewardFunction.

Visualization:

Visualization of the motors states. Needs to be a subclass of ElectricMotorVisualization

Limits:

Returns a list of limits of all states in the observation (called in state_filter) in the same order.

State Variables:

Each environment has got a list of state variables that are defined by the physical system. These define the names and order for all further state arrays in the modules. These states are announced to the other modules by announcing the physical system to them, which contains the property state_names.

Example:

['omega', 'torque','i', 'u', 'u_sup']

Observation:

Type: Tuple(State_Space, Reference_Space)

The observation is always a tuple of the State Space of the Physical System and the Reference Space of the Reference Generator. In all current Physical Systems and Reference Generators these Spaces are normalized, continuous, multidimensional boxes in [-1, 1] or [0, 1].

Actions:

Type: Discrete() / Box()

The action space of the environments are the action spaces of the physical systems. In all current physical systems the action spaces are specified by its PowerElectronicConverter and either a continuous, multidimensional box or discrete.

Reward:

The reward and the reward range are specified by the RewardFunction. In general the reward is higher the closer the motor state follows the reference trajectories.

Starting State:

The physical system and the reference generator define the starting state.

Episode Termination:

Episode terminations can be initiated by the reference generator, or the reward function. A reference generator might terminate an episode, if the reference has ended. The reward function can terminate an episode, if a physical limit of the motor has been violated.

Setting and initialization of all environments’ modules.

Parameters:

• physical_system (PhysicalSystem) – The physical system of this environment.

• reference_generator (ReferenceGenerator) – The reference generator of this environment.

• reward_function (RewardFunction) – The reward function of this environment.

• visualization (iterable(ElectricMotorVisualization)/None) – The visualization of this environment.

• constraints (list(Constraint/str/callable) / ConstraintMonitor) –

  A list of constraints or an already initialized ConstraintMonitor object can be passed here.

  • list(Constraint/str/callable): Pass a list with initialized Constraints and/or state names. Then,

  a ConstraintMonitor object with the Constraints and additional LimitConstraints on the passed names is created. Furthermore, the string ‘all’ inside the list will create a ConstraintMonitor that observes the limit on each state. - ConstraintMonitor: Pass an initialized ConstraintMonitor object that will be used directly as

  ConstraintMonitor in the environment.

• visualization – The visualizations of this environment.

• state_filter (list(str)) – Selection of states that are shown in the observation.

• physical_system_wrappers (iterable(PhysicalSystemWrapper)) – PhysicalSystemWrapper instances to be wrapped around the physical system.

• callbacks (list(Callback)) – Callbacks being called in the environment

• **kwargs – Arguments to be passed to the modules.

close()

Called when the environment is deleted. Closes all its modules.

property constraint_monitor

The ConstraintMonitor of the environment.

Type:

Returns(ConstraintMonitor)

property limits

Returns a list of limits of all states in the observation (called in state_filter) in the same order

property nominal_state

Returns a list of nominal values of all states in the observation (called in state_filter) in that order

property physical_system

Returns: PhysicalSystem: The Physical System of the Environment

property reference_generator

Returns: ReferenceGenerator: The ReferenceGenerator of the Environment

property reference_names

Returns a list of state names of all states in the observation (called in state_filter) in the same order

render(*_, **__)

Update the visualization of the motor.

reset(seed=None, options=None, *_, **__)

Reset of the environment and all its modules to an initial state.

Returns:

The initial observation consisting of the initial state and initial reference. info(dict): Auxiliary information (optional)

property reward_function

Returns: RewardFunction: The RewardFunction of the environment

property state_names

Returns a list of state names of all states in the observation (called in state_filter) in the same order

step(action)

Perform one simulation step of the environment with an action of the action space.

Parameters:

action – Action to play on the environment.

Returns:

Tuple of the new state and the next reference. reward(float): Amount of reward received for the last step. terminated(bool): Flag, indicating if a reset is required before new steps can be taken. info(dict): Auxiliary information (optional)

Return type:

observation(Tuple(ndarray(float),ndarray(float))

property visualizations

Returns a list of all active motor visualizations.

class gym_electric_motor.core.ElectricMotorVisualization

Base class for all visualizations in GEM. The visualization is basically only a Callback that is extended by a render() function to update the figure. With the function calls that are inherited by the Callback superclass (e.g. on_step_end), the data is passed from the environment to the visualization. In the render() function the passed data can be visualized in the desired way.

render()

Function to update the user interface.

class gym_electric_motor.core.PhysicalSystem(action_space, state_space, state_names, tau)

The Physical System module encapsulates the physical model of the system as well as the simulation from one step to the next.

Parameters:

• action_space (gymnasium.Space) – The set of allowed actions on the system.

• state_space (gymnasium.Space) – The set of possible systems states.

• state_names (ndarray(str)) – The names of the systems states

• tau (float) – The systems simulation time interval.

property action_space

Returns: gymnasium.Space: An Farama Gymnasium Space that describes the possible actions on the system.

close()

Called, when the environment is closed. Close the System and all of its submodules by closing files, saving logs etc.

property k

Returns: int: The current systems time step k.

property limits

Returns: ndarray(float): An array containing the maximum allowed physical values for each state variable.

property nominal_state

Returns: ndarray(float): An array containing the nominal values for each state variable.

reset(initial_state=None)

Reset the physical system to an initial state before a new episode starts.

Returns:

The initial systems state

Return type:

element of state_space

simulate(action)

Simulation of the Physical System for one time step with the input action. This method is called in the environment in every step to update the systems state.

Parameters:

action (element of action_space) – The action to play on the system for the next time step.

Returns:

The systems state after the action was applied.

Return type:

element of state_space

property state_names

Returns: ndarray(str): Array containing the names of the systems states.

property state_positions

Returns: dict(int): Dictionary mapping the state names to its positions in the state arrays

property state_space

Returns: gymnasium.Space: An Farama Gymnasium Space that describes the possible states of the system.

property unwrapped

Returns this instance of the physical system.

If the system is wrapped into multiple PhysicalSystemWrappers this property returns directly the innermost system.

class gym_electric_motor.core.ReferenceGenerator

The abstract base class for reference generators in gym electric motor environments.

reference_space:

Space of reference observations as defined in the Farama Gymnasium Toolbox.

The reference generator is called twice per step.

Call of get_reference():

Returns the reference array which has the same shape as the state array and contains values for currently referenced state variables and a default value (e.g zero) for non-referenced variables. This reference array is used to calculate rewards.

Example:

reference_array=np.array([0.8, 0.0, 0.0, 0.0])

state_variables=['omega', 'torque', 'i', 'u', 'u_sup']

Here, the state consists of five quantities but only 'omega' is referenced during control.

Call of get_reference_observation():

Returns the reference observation, which is shown to the agent. Any shape and content is generally valid, however, values must be within the declared reference space. For example, the reference observation may contain future reference values of the next n steps.

Example:

reference_observation = np.array([0.8, 0.6, 0.4])

This reference observation may be valid for an omega-controlled environment that shows the agent not only the reference for the next time step omega_(t+1)=0.8 but also omega_(t+2)=0.6 and omega_(t+3)=0.4.

close()

Called by the environment, when the environment is deleted to close files, store logs, etc.

get_reference(state, *_, **__)

Returns the reference array of the current time step.

The reference array needs to be in the same shape as the state variables. For referenced states the reference value is passed. For unreferenced states a default value (e.g. Zero) can be set in the reference array.

Parameters:

state (ndarray(float)) – Current state array of the environment.

Returns:

Current reference array.

Return type:

ndarray(float))

get_reference_observation(state, *_, **__)

Returns the reference observation for the next time step. This observation needs to fit in the reference space.

Parameters:

state (ndarray(float)) – Current state array of the environment.

Returns:

Observation for the next reference time step.

Return type:

value in reference_space

property reference_names

Returns: reference_names(list(str)): A list containing all names of the referenced states in the reference observation.

property referenced_states

Returns: ndarray(bool): Boolean-Array with the length of the state_variables indicating which states are referenced.

reset(initial_state=None, initial_reference=None)

Reset of references for a new episode.

Parameters:

• initial_state (ndarray(float)) – The initial state array of the environment.

• initial_reference (ndarray(float)) – If not None: A desired initial reference array.

Returns:

The reference array at time step 0.

reference_observation(value in reference_space): The reference observation for the next time step.

trajectories(dict(list(float)): If available, generated trajectories for the Visualization can be passed here. Otherwise return None.

Return type:

reference_array(ndarray(float))

set_modules(physical_system)

Announcement of the PhysicalSystem to the ReferenceGenerator.

In subclasses, store all important information from the physical system to the ReferenceGenerator here. The environment announces the physical system to the ReferenceGenerator during its initialization.

Parameters:

physical_system (PhysicalSystem) – The physical system of the environment.

class gym_electric_motor.core.RewardFunction

The abstract base class for reward functions in gym electric motor environments.

The reward function is called once per step and returns reward for the current time step.

reward_range

Defining lowest and highest possible rewards.

Type:

Tuple(float, float)

close()

Called, when the environment is closed to store logs, close files etc.

reset(initial_state=None, initial_reference=None)

This function is called by the environment when reset.

Inner states of the reward function can be reset here, if necessary.

Parameters:

• initial_state (ndarray(float)) – Initial state array of the Environment

• initial_reference (ndarray(float)) – Initial reference array of the environment.

reward(state, reference, k=None, action=None, violation_degree=0.0)

Reward calculation. If limits have been violated the reward is calculated with a separate function.

Parameters:

• state (ndarray(float)) – Environments state array.

• reference (ndarray(float)) – Environments reference array.

• k (int) – Systems momentary time-step

• action (element of action space) – The previously taken action.

• violation_degree (float in [0.0, 1.0]) – Degree of violation of the constraints. 0.0 indicates that all constraints are complied. 1.0 indicates that the constraints have been so much violated, that a reset is necessary.

Returns:

Reward for this state, reference, action tuple.

Return type:

float

reward_range = (-inf, inf)

Lower and upper possible reward

Type:

Tuple(int,int)

set_modules(physical_system, reference_generator, constraint_monitor)

Setting of the physical system, to set state arrays fitting to the environments states

Parameters:

• physical_system (PhysicalSystem) – The physical system of the environment

• reference_generator (ReferenceGenerator) – The reference generator of the environment.

• constraint_monitor (ConstraintMonitor) – The constraint monitor of the environment.

class gym_electric_motor.core.SimulationEnvironment(tau: float = 0.0, step: int = 0)

class gym_electric_motor.core.Workspace