Benchmark Utils#

Corrective Movement Measurement (Overshoot and Distance Corrections)#

class magbotsim.utils.benchmark_utils.CorrectiveMovementMeasurement(distance_func: Callable[[ndarray, ndarray], ndarray], threshold: float = 0.05)[source]#

A utility class to measure corrective movements (overshoot and distance corrections) within one episode.

Parameters:

  • distance_func –

    a function to measure the distance between the current position of the object and its goal position.

    • Inputs: 2 numpy arrays containing the current positions of the object and the object’s goal positions each with shape (1, length position vector) or (length position vector,).

    • Outputs: a single float value or a numpy array with shape (1,) containing the distance values

  • threshold_pos – the threshold used to determine whether the object has reached its goal position, defaults to 0.05

get_current_num_distance_corrections() → int[source]#

Return the current number of distance corrections measured within the current episode.

Returns:

the current number of distance corrections measured within the current episode

get_current_num_overshoot_corrections() → int[source]#

Return the current number of overshoot corrections measured within the current episode.

Returns:

the current number of overshoot corrections measured within the current episode

reset() → None[source]#

Reset counters etc. Should be called at environment reset to measure the number of corrective movements per episode.

update_distance_corrections(current_object_pose: ndarray, object_target_pose: ndarray) → None[source]#

Check whether a distance correction occurred and increase the counter if necessary.

Parameters:

  • current_object_pose – a numpy array containing the current position of the object. Shape: (1, length position vector) or (length position vector,)

  • object_target_pose – a numpy array containing the target position of the object. Shape: (1, length position vector) or (length position vector,)

update_overshoot_corrections(current_object_pose: ndarray, object_target_pose: ndarray) → None[source]#

Check whether an overshoot correction occurred and increase the counter if necessary.

Parameters:

  • current_object_pose – a numpy array containing the current position of the object. Shape: (1, length position vector) or (length position vector,)

  • object_target_pose – a numpy array containing the target position of the object. Shape: (1, length position vector) or (length position vector,)

Energy Efficiency Measurement#

class magbotsim.utils.benchmark_utils.EnergyEfficiencyMeasurement(weight_jerk: float = 15.0, weight_acceleration: float = 5.0, weight_velocity: float = 1.0, num_movers: int = 1, dt: float = 0.01)[source]#

A utility class to measure energy efficiency \(W\) based on weighted sum of jerk, acceleration, and velocity.

\[W = \sum_{m=0}^{M} w_j\cdot |j(m,t)| + w_a\cdot |a(m,t)| + w_v \cdot |v(m,t)|,\]

where \(w_j, w_a, w_v \in\mathbb{R}\) are the weights and \(M\in\mathbb{N}\) is the number of movers for which to measure the energy efficiency.

This class computes a weighted sum of the absolute values of jerk, acceleration, and velocity for all movers to assess energy efficiency. Lower values indicate more energy-efficient movements.

Parameters:

  • weight_jerk – weight for jerk component in the energy efficiency metric, defaults to 1.0

  • weight_acceleration – weight for acceleration component in the energy efficiency metric, defaults to 1.0

  • weight_velocity – weight for velocity component in the energy efficiency metric, defaults to 1.0

  • num_movers – number of movers in the system

  • dt – time step size for numerical differentiation, defaults to 0.01

property average_energy_metric: float#

Get the average energy efficiency metric per step for the current episode.

Returns:

average energy efficiency metric per step, or 0.0 if no steps recorded

property cumulative_energy_metric: float#

Get the cumulative energy efficiency metric for the current episode.

Returns:

cumulative energy efficiency metric

property max_energy_metric: float#

Get the minimum energy efficiency metric per step for the current episode.

Returns:

minimum energy efficiency metric per step, or None if no steps recorded

property min_energy_metric: float#

Get the minimum energy efficiency metric per step for the current episode.

Returns:

minimum energy efficiency metric per step, or None if no steps recorded

reset() → None[source]#

Reset all measurements. Should be called at environment reset.

update(velocities: ndarray, accelerations: ndarray = None, jerk: ndarray = None) → None[source]#

Update the cumulative energy efficiency measurement.

Parameters:

  • velocities – velocity array of shape (num_movers, 2) containing x,y velocities

  • accelerations – acceleration array of shape (num_movers, 2), can be None if jerk is provided

  • jerk – jerk array of shape (num_movers, 2), can be None (will be computed from acceleration)