quantum-robot

quantum-robot provides quantum-like perception models for robotics. It supports Python 3.11 through 3.14 and exposes a small backend interface; Qiskit is the bundled backend implementation.

The project was started in 2019 by Davide Lanza as Master's thesis research, with help from Fulvio Mastrogiovanni and Paolo Solinas. It is maintained by Davide Lanza.

The project is one Poetry distribution with a dependency-light qrobot core and optional extension import packages:

Capability	Install extra	Import package	Status	Coverage
Core models and Qiskit backend	—	qrobot	Supported
qUnits / Redis integration	qunits	qrobot_qunits	Supported
Graph and drawing tools	visualization	qrobot_visualization	Supported
Dashboard	dashboard	qrobot_dashboard	Supported
Lightweight 2-D robot simulator	simulator	qrobot_simulator	Experimental

[!WARNING] qrobot_simulator is an experimental extension. Its public interfaces, configuration, and output may change between minor releases while its contracts are being defined.

Install

Install the published core package:

python -m pip install --upgrade quantum-robot

Install optional capabilities only when needed:

python -m pip install --upgrade "quantum-robot[model-visualization,qunits,visualization,simulator,dashboard]"

Python 3.11 or newer (up to 3.14) is required. For an isolated installation, create and activate a virtual environment before running pip:

python3.14 -m venv .venv # we suggest python 3.14
source .venv/bin/activate  # Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install --upgrade pip

See the getting-started guide for individual extras, Redis setup, and installation checks.

Development

Use Poetry with any supported Python version. The following installs every development capability into Poetry’s project environment:

git clone https://github.com/Davidelanz/quantum-robot.git
cd quantum-robot
poetry env use 3.14 # we suggest python 3.14
poetry install --all-extras

Run the standard quality checks through that environment:

poetry check
poetry run ruff check src tests scripts
poetry run python scripts/check_docstrings.py src
poetry run black --check src tests scripts
poetry run python scripts/format_notebooks.py --check
poetry run mypy src
poetry run pytest --cov=qrobot --cov-fail-under=100
poetry build

Apply the formatter when needed:

poetry run black src tests scripts
poetry run python scripts/format_notebooks.py

The notebook formatter converts each numbered MyST notebook through Jupytext, runs Ruff over its Python cells, and writes it back without creating committed .ipynb files.

The qUnits integration tests and the executable qUnits tutorial require Redis on localhost:6379. Start a disposable local instance when running them:

docker run --rm --name qrobot-redis -p 6379:6379 -d redis:7-alpine
poetry run pytest

Stop it with docker stop qrobot-redis.

Run the examples

In order to run the examples, furst start a local instance of redis:

docker run --rm --name qrobot-redis -p 6379:6379 -d redis:7-alpine

Then run of the examples:

poetry run python examples/grasping_robot.py
poetry run python examples/bug_world.py

grasping_robot presents an approaching ball, distance and touch interfaces, and a qBrain-controlled gripper. bug_world opens a predator/prey chessboard where the qBrain drives five behavioral actuator interfaces. Both are small live 2-D simulations; the foundational model demonstrations remain executable inside the notebooks.

To monitor the qBrain in the dashboard, start:

poetry run python -m qrobot_dashboard

The dashboard will be exposed at http://127.0.0.1:8050. It discovers qUnits from Redis automatically and refreshes every second. Stop the dashboard with Ctrl+C.

Documentation

The documentation source is MyST Markdown, including tutorials. Building it runs those tutorials, renders MathJax formulas, and writes the resulting site to docs/_build/html:

docker run --rm --name qrobot-redis -p 6379:6379 -d redis:7-alpine
poetry run python scripts/build_docs.py

Open docs/_build/html/index.html directly in a browser.

Project layout

src/
  qrobot/                 # core package and backend interface
  qrobot_qunits/          # optional qUnits Redis-based extension
  qrobot_visualization/   # optional graph/drawing extension
  qrobot_simulator/       # grasping_robot and bug_world 2-D simulators
  qrobot_dashboard/       # optional dashboard extension
examples/                 # exactly two embodied example runners
tests/
  core/
  extensions/
docs/                     # MyST API docs and tutorials

Contributing and citation

Contributions are welcome; see the contributing guide. For questions, contact the maintainer.

If you use quantum-robot in research, we would appreciate citations to the following:

@misc{lanza2020quantum,
    author={Lanza, Davide},
    title={Quantum-like Modeling of Cognitive Architectures for Robotics},
    year={2020},
    publisher={Zenodo},
    doi={10.5281/zenodo.22068511},
    url={https://doi.org/10.5281/zenodo.22068511},
    note={Master's thesis for the EMARO+ (European Master on Advanced Robotics) programme.},
}
@misc{lanza2020multisensory,
    title={Multi-sensory Integration in a Quantum-Like Robot Perception Model},
    author={Davide Lanza and Paolo Solinas and Fulvio Mastrogiovanni},
    year={2020},
    eprint={2006.16404},
    archivePrefix={arXiv},
    primaryClass={cs.RO},
    note={preprint at \url{https://arxiv.org/abs/2006.16404}},
}

Release on PyPi

To publish a new release on PyPi:

git tag -a x.y.z -m "quantum-robot x.y.z"
git push origin x.y.z

To remove a failed tag (before a new attempt):

git tag -d x.y.z
git push origin :refs/tags/x.y.z

License

GPL-3.0-or-later