Contributing#

Contributions of models, baselines, circuits, data sets and examples are welcome.

Principles#

  1. Every quantum-like model ships with the classical model it must beat. A new family needs at least one classical baseline and a README section on how to tell them apart.

  2. Only published human data. Data sets in src/quantum_mind/data must be aggregate values from a cited source; simulated data must be labelled as simulated wherever they appear.

  3. Circuits must match their model. A new circuit needs a test that compares its output with the analytic prediction (statevector-exact where possible).

  4. One interface. Quantum-like models subclass quantum_mind.core.Model, declare PARAMS, LOSS and predict(design). Belief filters follow fit / predict_proba / start (see quantum_mind.belief).

  5. Stay in scope. The three threads of quantum robotics (robot problems on quantum computers, quantum sensing for robots, quantum-probability models of people and robot beliefs) and what is needed to show or run them. General-purpose quantum algorithms and quantum-inspired optimisers belong in Qiskit, PennyLane and optimisation libraries, not here; connect to them instead (see quantum_mind.computing).

  6. Always compare, and ablate. A new model is reported next to a classical baseline with the same budget, with the ablation that isolates what is new, a control task where it should not help, and a paired test.

Workflow#

git clone https://github.com/yeshwanthguru/Quantum-mind
cd quantum-mind
pip install -e ".[all,dev,docs]"
pytest -q
pytest -q --doctest-modules src/quantum_mind            # the examples in the docstrings
ruff check src tests examples docs site
QUANTUM_MIND_DOCS_FAST=1 python -m sphinx -b html docs docs/_build/html   # documentation preview

Documentation#

Every public class, function and method has a NumPy-style docstring (a one-line summary, then Parameters, Returns, Raises and, where useful, Examples that run as doctests). Formulas use :math:. The API reference in the documentation and docs/API.md are generated from these docstrings; regenerate the latter with python3 docs/make_api.py.

Examples in examples/ are also the documentation’s example gallery. Start each script with a docstring whose first line is a title underlined with =, and split the code into steps with # %% comment blocks that explain what each step does; the gallery shows them as text between the code cells.

Open a pull request against develop with tests, a README entry for the model, and an example if the change adds a new use case. If figures in the README change, regenerate them with python3 docs/make_assets.py. Please describe how the model was checked against its original paper.

Branches and releases#

Branch

Purpose

develop

All day-to-day work. Push here, or open pull requests against it. CI runs on every push.

main

Released code only. It changes only through a pull request from develop, and every merge is a release. The website and documentation are deployed from main.

Release steps:

  1. On develop, update the version in pyproject.toml, src/quantum_mind/__init__.py and CITATION.cff, and move the changelog entries under a new version heading.

  2. Open a pull request from develop to main; merge it when CI is green.

  3. Create a GitHub release from main with the tag v<version> (for example v1.6.0). The release workflow checks that the tag matches the package version, builds the package and publishes it to PyPI.

  4. Bring develop up to date with main if anything was changed during the release.

Reporting problems#

Use the issue templates (bug report; model or data request).