Metadata-Version: 2.4
Name: quantum-robot
Version: 1.3.0
Summary: A set of Python modules for quantum-like perception modelling.
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Keywords: quantum,robotics,modeling
Author: Davide Lanza
Author-email: info@davidelanza.it
Maintainer: Davide Lanza
Maintainer-email: info@davidelanza.it
Requires-Python: >=3.11,<3.15
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Development Status :: 3 - Alpha
Classifier: Natural Language :: English
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Provides-Extra: dashboard
Provides-Extra: docs
Provides-Extra: lint
Provides-Extra: model-visualization
Provides-Extra: qunits
Provides-Extra: simulator
Provides-Extra: test
Provides-Extra: visualization
Requires-Dist: black (>=25.0) ; extra == "lint"
Requires-Dist: build (>=1.2) ; extra == "lint"
Requires-Dist: dash (>=3.0) ; extra == "dashboard"
Requires-Dist: dash (>=3.0) ; extra == "test"
Requires-Dist: ipykernel (>=7.0) ; extra == "docs"
Requires-Dist: jupytext (>=1.17) ; extra == "docs"
Requires-Dist: jupytext (>=1.17) ; extra == "lint"
Requires-Dist: matplotlib (>=3.10) ; extra == "dashboard"
Requires-Dist: matplotlib (>=3.10) ; extra == "docs"
Requires-Dist: matplotlib (>=3.10) ; extra == "model-visualization"
Requires-Dist: matplotlib (>=3.10) ; extra == "simulator"
Requires-Dist: matplotlib (>=3.10) ; extra == "test"
Requires-Dist: matplotlib (>=3.10) ; extra == "visualization"
Requires-Dist: myst-nb (>=1.3) ; extra == "docs"
Requires-Dist: networkx (>=3.4) ; extra == "dashboard"
Requires-Dist: networkx (>=3.4) ; extra == "docs"
Requires-Dist: networkx (>=3.4) ; extra == "test"
Requires-Dist: networkx (>=3.4) ; extra == "visualization"
Requires-Dist: numpy (>=2.3)
Requires-Dist: pandas (>=2.3) ; extra == "docs"
Requires-Dist: pandas (>=2.3) ; extra == "model-visualization"
Requires-Dist: pandas (>=2.3) ; extra == "test"
Requires-Dist: plotly (>=6.0) ; extra == "dashboard"
Requires-Dist: plotly (>=6.0) ; extra == "docs"
Requires-Dist: plotly (>=6.0) ; extra == "test"
Requires-Dist: plotly (>=6.0) ; extra == "visualization"
Requires-Dist: pytest (>=8.4) ; extra == "test"
Requires-Dist: pytest-check (>=2.5) ; extra == "test"
Requires-Dist: pytest-cov (>=7.0) ; extra == "test"
Requires-Dist: pytest-mock (>=3.15) ; extra == "test"
Requires-Dist: qiskit (>=2.4.1,<3)
Requires-Dist: redis (>=4.3.4) ; extra == "dashboard"
Requires-Dist: redis (>=4.3.4) ; extra == "docs"
Requires-Dist: redis (>=4.3.4) ; extra == "qunits"
Requires-Dist: redis (>=4.3.4) ; extra == "simulator"
Requires-Dist: redis (>=4.3.4) ; extra == "test"
Requires-Dist: redis (>=4.3.4) ; extra == "visualization"
Requires-Dist: ruff (>=0.14) ; extra == "lint"
Requires-Dist: seaborn (>=0.13) ; extra == "docs"
Requires-Dist: seaborn (>=0.13) ; extra == "model-visualization"
Requires-Dist: seaborn (>=0.13) ; extra == "test"
Requires-Dist: sphinx (>=8.2) ; extra == "docs"
Requires-Dist: sphinx-rtd-theme (>=3.0) ; extra == "docs"
Requires-Dist: twine (>=6.1) ; extra == "lint"
Project-URL: Documentation, http://docs.quantum-robot.org/
Project-URL: Homepage, http://quantum-robot.org/
Project-URL: Repository, https://github.com/Davidelanz/quantum-robot
Description-Content-Type: text/markdown

# quantum-robot

[![Package Check](https://github.com/Davidelanz/quantum-robot/actions/workflows/package-check.yml/badge.svg)](https://github.com/Davidelanz/quantum-robot/actions/workflows/package-check.yml)
[![CodeQL](https://github.com/Davidelanz/quantum-robot/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/Davidelanz/quantum-robot/actions/workflows/codeql-analysis.yml)
[![Code coverage](https://codecov.io/gh/Davidelanz/quantum-robot/branch/master/graph/badge.svg?token=69IQEINMQU&component=supported)](https://codecov.io/gh/Davidelanz/quantum-robot)
[![Documentation Status](https://readthedocs.org/projects/quantum-robot/badge/?version=latest)](http://docs.quantum-robot.org/en/latest/)
[![Snyk Advisor](https://img.shields.io/badge/Snyk_Security-blue)](https://snyk.io/advisor/python/quantum-robot)
[![Maintainability](https://api.codeclimate.com/v1/badges/498a54bb981af54decec/maintainability)](https://codeclimate.com/github/Davidelanz/quantum-robot/maintainability)
[![License](https://img.shields.io/badge/license-GNU_GPL_v3-blue)](LICENSE)
[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.22068511-blue)](https://doi.org/10.5281/zenodo.22068511)

`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](https://scholar.google.com/citations?user=Lqx6VqEAAAAJ) as
Master's thesis research, with help from
[Fulvio Mastrogiovanni](https://scholar.google.it/citations?user=9dRRzV0AAAAJ&hl=en)
and [Paolo Solinas](https://rubrica.unige.it/personale/UkNHWllv). 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 | ![qrobot coverage](https://codecov.io/gh/Davidelanz/quantum-robot/branch/master/graph/badge.svg?token=69IQEINMQU&component=qrobot) |
| qUnits / Redis integration | `qunits` | `qrobot_qunits` | Supported | ![qrobot_qunits coverage](https://codecov.io/gh/Davidelanz/quantum-robot/branch/master/graph/badge.svg?token=69IQEINMQU&component=qrobot_qunits) |
| Graph and drawing tools | `visualization` | `qrobot_visualization` | Supported | ![qrobot_visualization coverage](https://codecov.io/gh/Davidelanz/quantum-robot/branch/master/graph/badge.svg?token=69IQEINMQU&component=qrobot_visualization) |
| Dashboard | `dashboard` | `qrobot_dashboard` | Supported | ![qrobot_dashboard coverage](https://codecov.io/gh/Davidelanz/quantum-robot/branch/master/graph/badge.svg?token=69IQEINMQU&component=qrobot_dashboard) |
| Lightweight 2-D robot simulator | `simulator` | `qrobot_simulator` | Experimental | ![qrobot_simulator coverage](https://codecov.io/gh/Davidelanz/quantum-robot/branch/master/graph/badge.svg?token=69IQEINMQU&component=qrobot_simulator) |

> [!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:

```sh
python -m pip install --upgrade quantum-robot
```

Install optional capabilities only when needed:

```sh
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`:

```sh
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](http://docs.quantum-robot.org/en/latest/getting_started/getting_started.html)
for individual extras, Redis setup, and installation checks.

## Development

Use [Poetry](https://python-poetry.org/) with any supported Python version. The following
installs every development capability into Poetry’s project environment:

```sh
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:

```sh
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:

```sh
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:

```sh
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:

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

Then run of the examples:

```sh
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:

```sh
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`:

```sh
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

```text
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](.github/CONTRIBUTING.md).
For questions, contact [the maintainer](mailto:info@davidelanza.it).

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

``` bibtex
@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:

```sh
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):
```sh
git tag -d x.y.z
git push origin :refs/tags/x.y.z
```

## License

[GPL-3.0-or-later](LICENSE)

