CubePy

This repository contains code for studying reconfiguration of homogeneous pivoting cube modular robots in two dimensions with local sensing constraints. In particular, it contains:

• A gym environment for the task of reconfiguring pivoting cube ensembles.
• Code for training a neural network for controlling cube actions using PPO (with action masking).
• The implemented neural network is a convolutional neural network, imitating that every cube locally hosts the same neural network. Actions are calculated using knowledge about other cubes in a cube's local neighbourhood only.
• We provide convolutional neural network architectures with additional group symmetries, such as rotation- and mirror-invariance.

Code

Installation

To use our code, install the provided package CubePy via pip

pip install -e .

from the folder containing the setup.py. The source code is located in CubePy/. Some example notebooks are provided in Examples/. The script used for training models as well as the testing data (start configurations) is in Experiments/

Training and Testing Models

Creating a Testset

The CubePy\data\generating_dummy_data.py script can be used for the generation of a testset of random configurations. The dataset is stored in a .pkl file with name testset_{nr_modules}modules where nr_modules is one of the arguments given to the script. Example usage:
python generating_dummy_data.py --nr_modules 10 --nr_configs 500
would generate 500 random configurations with 10 modules.

Training and Prediction

The Experiments\run_experiment.py script can be used to train models, save them in the end of training and evaluate them with an existing testset. The results of the evaluation are stored in a .csv file with name results_{target} where target is one of the arguments given when calling the script. Example usage:
python train_script.py --kernel_size 3 --neuron_counts 1,64,512,32 --nr_layers 2 --nr_cubes 9 --steps_per_ep 750 --total_steps 100000 --main_seeds 70852,97245,12345 --alpha 0.7 --gamma 1.2 --reward balanced --target chair_9 --train True
would train three 2-layer models for 100k total steps (750 per episode) with the target shape being chair. The list of all possible target configurations is included in the script file. Gamma and alpha are parameters of the reward function.

Optionally, the --rinv True argument can be provided to use rotation-invariant CNNs, and --mrinv True to use rotation- and mirror invariant CNNs instead of an ordinary CNN. If the --train argument is omitted, the code assumes a model with the given parameters has already been trained and simply loads it for testing. Optionally, the --curriculum True argument can be provided to use curriculum learning. Currently that will make use of a hardcoded setting (50 warmup episodes, difficulty increasing every second episode), but in the future that can be made into additional parameters to pass to the script.

Acknowledgments

This project heavily used and modified implementations from stable-baselines3. We further acknowledge the usage of NN_CGInvariance, and scikit-image. The cube environment is based on the implementation provided during the GECCO 2023 Space Optimisation Competition (SpOC) organised by ESA's Advanced Concepts Team.

Related work

• Nisser M, Cheng L, Makaram Y, Suzuki R, Mueller S. (2022). ElectroVoxel: Electromagnetically actuated pivoting for scalable modular self-reconfigurable robots. In *2022 International Conference on Robotics and Automation (ICRA),*4254–4260. https://doi.org/10.1109/ICRA46639.2022.9811746

• Zhang Y, Wang W, Zhang P, Huang P. (2021). Reinforcement-learning-based task planning for self-reconfiguration of cellular satellites. IEEE Aerospace and Electronic Systems Magazine, 37(6): 38–47. https://doi.org/10.1109/MAES.2021.3089252

• Song, Q., Ye, D., Sun, Z., & Wang, B. (2021). Autonomous reconfiguration of homogeneous pivoting cube modular satellite by deep reinforcement learning. Proceedings of the Institution of Mechanical Engineers. Part I, Journal of Systems & Control Engineering, 235(10), 1777–1786. https://doi.org/10.1177/0959651820956738

• Sung, C., Bern, J., Romanishin, J., & Rus, D. (2015). Reconfiguration planning for pivoting cube modular robots. 2015 IEEE International Conference on Robotics and Automation (ICRA). https://doi.org/10.1109/ICRA.2015.7139451

Citation

If you use the provided code, or find it helpful for your own work, please cite

@article{dobreva2025decentralised,
  title={Decentralised self-organisation of pivoting cube ensembles using geometric deep learning},
  author={Dobreva, Nadezhda and Blazquez, Emmanuel and Grover, Jai and Izzo, Dario and Qin, Yuzhen and Dold, Dominik},
  journal={arXiv preprint arXiv:2509.03140},
  year={2025}
}