MagBotSim Documentation#

_images/visual_abstract.png


MagBotSim (Magnetic Robotics Simulation) is a library for physics-based simulation environments for motion planning and object manipulation in the field of Magnetic Robotics. The main component of every environment is a magnetic levitation (MagLev) system, which consists of two basic components, as shown in the Figure above. Firstly, dynamically actuated shuttles as passive motor modules, so-called movers, consist of a housing and a complex permanent magnet structure based on Halbach arrays on the lower side of the mover. Secondly, static motor modules, so-called tiles, are the active component of the drive system. As shown in the Figure above, the tiles enable the coil-induced emission of electromagnetic fields (yellow) that interact with the mover’s field (blue). During operation, the movers hover above the tiles and can be controlled in six dimensions by adjusting the currents in the coils contained in the tiles.

A brief summary of our MagBotSim paper “MagBotSim: Physics-Based Simulation and Reinforcement Learning Environments for Magnetic Robotics” (see Paper & Citation) is shown in the following video:


MagLev systems are already included in the first industrial applications. The most advanced systems available on the market are XBot (Planar Motor), ACOPOS 6D (B&R), XPlanar (Beckhoff Automation), and ctrlX FLOW⁶ᴰ (Bosch Rexroth). The industrial applications with MagLev systems typically focus on product transport and do not consider the manipulation of objects. However, to increase productivity and exploit the full potential of MagLev systems, material flow and manipulation should be combined in the future. Therefore, MagLev systems can be seen as a special kind of robot. Hence, we introduce the more general term Magnetic Robotics.

MagBotSim is designed to match real-world applications, so that control policies can be transferred to real MagLev systems without further training or calibration. Since the library is based on the MuJoCo physics engine, MagBotSim enables users to perform object manipulation tasks with MagLev systems. In addition, as reinforcement learning (RL) is frequently used in multi-agent path finding and object manipulation, MagBotSim includes basic environments with single-agent (Gymnasium) and multi-agent (PettingZoo) RL APIs that can serve as starting points for developing new research-specific environments. However, MagBotSim can also be used without RL and provides several utilities, such as impedance control for the movers.

The following RL agents have been trained with MagBotSim:


MagBotSim can also be used to develop trajectory planning policies that can be transferred to a real MagLev system:


Installation & License#

MagBotSim is open-source and published under the GNU General Public License v3.0. The MagBotSim package can be installed via PIP:

pip install magbotsim

To install optional dependencies, to build the documentation, or to run the tests, use:

pip install magbotsim[docs, tests]

Note

Depending on your shell, e.g. when using Zsh, you may need to use additional quotation marks:

pip install "magbotsim[docs, tests]"

Basic Usage#

The following example shows how to use a trained policy with an example environment that follows the Gymnasium API:

import gymnasium as gym
import magbotsim

gym.register_envs(magbotsim)

mover_params = {
   'shape': 'mesh',
   'mesh': {'mover_stl_path': 'beckhoff_apm4220_mover', 'bumper_stl_path': 'beckhoff_apm4220_bumper'},
   'mass': 0.639 - 0.034,
   'bumper_mass': 0.034,
}
env_kwargs = {
   'mover_params': mover_params,
   'initial_mover_zpos': 0.002,
   'render_mode': 'human',
   'render_every_cycle': True,
}

env = gym.make("StateBasedPushTEnv-v0", **env_kwargs)
observation, info = env.reset(seed=42)

for _ in range(0,100):
   terminated, truncated = False, False
   while not terminated and not truncated:
      action = env.action_space.sample()  # use custom policy instead
      observation, reward, terminated, truncated, info = env.step(action)

   observation, info = env.reset()
env.close()

Due to the use of standard RL APIs, MagBotSim is compatible with common RL libraries, such as Stable-Baselines3 or Tianshou. The library contains a collection of existing RL environments in the field of Magnetic Robotics, which will continue to be updated in the future, as well as basic single-agent and multi-agent environments that serve as starting points for the easy development of new research-specific environments.

Paper & Citation#

If you use MagBotSim for your research, please cite:

Learn More#