quantum-mind 3.0.0

Website and live Bloch-sphere playground · Documentation (user guide, example gallery, API reference)

The idea · COBRA · Three layers · Quick start · Bloch viewer · Validation · Status · Tutorials · Model atlas · Mathematics

Quantum Mind (pip install quantum-mind, import quantum_mind) is a Python library for quantum-probability cognition in robotics: it models how people judge, decide and trust, and how a robot should read them, with the mathematics of quantum probability (projections, interference, density matrices, generalised measurements), and it turns every belief into a cost-aware decision: hand over, wait, or ask.

It runs on ordinary computers and makes no claim of quantum computational advantage. "Quantum-like" means the probability rules are borrowed; nothing in the brain or the robot is assumed to be quantum. Every model is reported next to the classical model it has to beat, with the ablation that isolates what is new.

The idea

Classical filters treat evidence as arriving in neutral, independent pieces. People and robots do not live in that world:

• a look changes what the next hand movement means;
• a question changes the answer to the next question (order effects);
• asking a person whether they trust the robot changes their trust.

Quantum probability represents exactly this: beliefs are vectors or density matrices, evidence is a measurement, and measurements need not commute. Quantum Mind turns that into tested code in three layers: quantum-like models of people, a belief filter for the robot (COBRA), and a decision layer that never reports a belief without a cost, a calibration check and a classical baseline.

COBRA: a context-rotated belief filter

COBRA keeps the robot's belief about a person as a density matrix over hypotheses (for example the person's intent). Each sensor frame updates it with a generalised measurement whose basis is rotated by the previous frame, followed by partial dephasing:

M_t = U(x_{t-1}) · diag(exp((W x_t + b)/2)) · U(x_{t-1})†        ρ ← M_t ρ M_t / tr(·)        ρ ← (1−g) ρ + g · diag(ρ)

The probability of hypothesis z is the diagonal entry ρ_zz (Born rule). It has two built-in classical limits, so the effect of context and the effect of coherence can be separated: with no rotation it is a Bayes filter, and with full dephasing it is a classical incoherent context filter (the tests check both exactly).

import numpy as np
from quantum_mind.belief import COBRA, GaussianBayesFilter, min_cost_action

model = COBRA(n_hyp=3, n_features=3).fit(frames, intent)      # frames (N, T, 3), intent in {0, 1, 2}
belief = model.start()                                         # online, one frame at a time
for frame in sensor_stream:
    p = belief.update(frame)                                   # P(handover, retrieve, withdraw)

cost = np.array([[0, 6, 10], [1.5, 0, 0], [0.8, 0.8, 0.8]])    # hand over, wait, ask
action = min_cost_action(p, cost)[0]

_{The same hand cue after opposite previous looks. A Bayes filter adds the same evidence either way; this trained COBRA flips its evidence like the oracle that knows the generator (simulated task).}

What the benchmark says

benchmarks/context_intent_benchmark.py compares COBRA with the oracle, a Gaussian Bayes filter, logistic regression and an MLP on a synthetic intent task with a context effect, and on a control task with none. It adds an ablation without coherence, noise and dropout stress tests, and a paired sign-flip test. Mean ± std over 5 seeds, 3000 test sequences per cell:

The honest reading is in benchmarks/results/context_intent/ and on the COBRA page:

• With 250 to 1000 training sequences COBRA has the lowest cost of the learned models on the context task (about 0.02 below the Bayes filter). A paired sign-flip test on per-sequence cost is significant in only 2 of 5 seeds at each size, because training varies from seed to seed.
• With 60 training sequences COBRA is worse than the Bayes filter (0.347 against 0.280).
• On the control task, where context does not matter, COBRA is slightly worse than the Bayes filter (0.204 against 0.189 at 1000 sequences).
• Removing coherence (the ablation) loses about 0.03 to 0.04 in cost at 250 and 1000 sequences, a hint that phase interference helps; five seeds are too few to be sure.
• Under 1.5x test noise COBRA is the best calibrated model (cost 0.481 against 0.608 for the Bayes filter at 1000 sequences).
• Its l1 coherence flags its own errors barely better than chance (AUROC about 0.53); belief entropy (about 0.81) is far better.

Three layers

Around them: quantum_mind.circuits (Qiskit circuits of the families, run() on Aer, IBM Quantum and Amazon Braket), quantum_mind.quantum (the exact state-vector simulator) and quantum_mind.viz (the Bloch-sphere viewer).

What is deliberately not here. General-purpose quantum algorithms (VQE, QAOA, Grover, quantum kernels, variational classifiers) and quantum-inspired optimisers are provided and maintained far better by Qiskit, PennyLane and optimisation libraries. Version 3.0 removed the copies this library used to carry, so that it contains only what is specific to quantum cognition in robotics.

Quick start

pip install quantum-mind              # core: numpy, scipy
pip install "quantum-mind[all]"       # everything (Qiskit, cloud back ends, viewer)

Is there a question-order effect, and which model explains it?

import numpy as np
from quantum_mind import compare
from quantum_mind.families.order_effects import QuantumOrderModel4D, BayesOrderModel, AnchoringOrderModel, qq_test

counts = {'AB': np.array([212, 48, 61, 179]),   # A asked first: yes-yes, yes-no, no-yes, no-no
          'BA': np.array([240, 33, 52, 175])}   # B asked first
print(qq_test(counts))                           # parameter-free test of the quantum-like prediction
for r in compare([QuantumOrderModel4D, BayesOrderModel, AnchoringOrderModel], counts):
    print(type(r.model).__name__, round(r.bic, 1))

A human model with uncertainty, for a planner or a ROS 2 system:

from quantum_mind.applications.robotics import HumanModelService

svc = HumanModelService()
svc.add_answer({'order': 'AB', 'answers': [1, 0]})          # one person's two answers (1 = yes)
svc.query({'order': 'AB', 'ask_cost': 1.0, 'error_cost': 3.0})
# -> prediction, uncertainty (entropy, model disagreement in bits), ensemble weights, 'ask' or 'act'

See the qubits

A Qiskit circuit, gate by gate. While the qubits are entangled, their vectors leave the sphere. circuit_trajectory(qc) → animate_trajectory / animate_bloch

Trust in a robot as a qubit, over successes and failures, with dephasing. belief_trajectory(OpenSystemBelief(), events)

from qiskit import QuantumCircuit
from quantum_mind.viz import circuit_trajectory, animate_bloch, save_html, LiveBloch, bloch_tomography

qc = QuantumCircuit(2); qc.h(0); qc.cx(0, 1); qc.ry(0.6, 1)
traj = circuit_trajectory(qc, steps=15)
save_html(animate_bloch(traj), 'bell.html')        # interactive: rotate, zoom, play, slider
LiveBloch(2).show().play(traj)                     # real time in Jupyter or a Matplotlib window
bloch_tomography(qc, 'aer:FakeTorino')             # Bloch vectors measured under IBM device noise

The same views draw a person's trust belief, and the density matrix of a COBRA belief (docs/assets/cobra_density_matrix.png). The viewer README covers everything else.

Validation, as measured

Quantum Mind is a research platform, not a claim of quantum advantage. Its strongest scientific use is evaluating quantum-like models of human judgement against classical alternatives and connecting calibrated uncertainty to robot questioning, trust and ask-or-act decisions.

• Evaluation layer. Log loss, Brier score, expected calibration error, decision cost, bootstrap intervals, paired bootstrap and randomisation tests, effect sizes, Holm correction, dataset hashes, experiment manifests and model-provenance records (quantum_mind.evaluation), plus a reproducible HRI decision benchmark (benchmarks/hri_decision_benchmark.py) and the COBRA benchmark above.
• Every new idea gets a classical baseline, an ablation that isolates it, a control task where it should not help, and a paired test. Where the classical method wins the documentation says so.
• What is not validated. All robotics results use simulated people or published survey aggregates. No study with real people and a robot has been run; docs/help/validation.md lists the gaps and gives a pilot-study protocol. In several comparisons the simulated people follow the model the robot uses, which favours the order-aware method by construction; the tutorials say where.

For the workflow see docs/research_validation.md and docs/research_claims.md.

Model catalogue

The model atlas gives a block diagram, the API object, the classical baselines and the reference for every model, and labels each by origin:

The extensions that apply to every people model are bootstrap, OnlinePersonModel and rank_conditions / model_posterior. For robots: AdaptiveConformalSets (sets for a person's next answer that keep their long-run coverage), online personalisation, trust_aware_allocation and sample_people (training against populations of simulated people).

Architecture

src/quantum_mind/
├── core/           Lüders rule, density matrices, Lindblad · Model/Param · fit, compare, recovery · bootstrap, online, design
├── families/       order_effects · conjunction · interference · qlbn · dynamics · decision · contextuality · similarity · memory · concepts · perception
├── belief/         COBRA · OnlineBelief · GaussianBayesFilter · min_cost_action
├── applications/   robotics: question domains, trust, intent resolution, ensemble, ask_or_act · calibration · orchestration · questioning · handover · allocation · fusion
├── envs/           Gymnasium environments with simulated people
├── circuits/       Qiskit circuits of the families · run() on Aer, IBM Quantum, Amazon Braket
├── quantum/        exact state-vector simulator (used by the viewer and the circuit exports)
├── problems/       the QUBO container used by trust-aware allocation
├── viz/            Bloch vectors, trajectories, tomography · Matplotlib and Plotly viewers · LiveBloch
├── evaluation/     metrics, paired statistics, manifests, provenance
└── data/           published aggregate data sets
benchmarks/         COBRA context-intent benchmark · HRI decision benchmark
examples/           21 scripts        tutorials/   15 tutorials + a packaged hand-over use case
docs/               Sphinx documentation, atlas, mathematics        notebooks/   2 Jupyter notebooks
integrations/ros2/  ROS 2 node (quantum_mind_ros)        site/   project website (built by CI)

Running on quantum hardware

The circuits of the quantum-like families run on simulators and, with credentials, on hardware:

python3 examples/09_cloud_run.py --dry-run                                  # local, no account
python3 examples/09_cloud_run.py --backend ibm:least_busy --shots 4000      # IBM Quantum
python3 examples/09_cloud_run.py --backend braket:arn:aws:braket:us-east-1::device/qpu/ionq/Forte-1 --shots 1000

run(circuit, backend) accepts aer, aer:<FakeBackend>, braket_local, braket_dm:<p>, ibm:<device> and braket:<ARN>. Aer (ideal and with IBM noise models) and the Braket simulators are tested in CI; the IBM and Braket submission code is tested against local stand-ins and has not been run on hardware. Report hardware results exactly as measured, with backend, date and job identifier.

A packaged use case: trust-aware hand-over

tutorials/trust_handover_package turns one robotics model into an installable package (quantum-handover): a robot arm decides before each hand-over whether to hand over, hand over slowly, ask or wait, using the quantum-like trust model. It has a benchmark against two populations of simulated people, a PyBullet simulation recorded as a GIF, a ROS 2 node, its own tests and a requirements.txt; tutorial 15 walks through it. Results are for simulated people only.

Status and scope

Installation

From a clone: pip install -e ".[all,dev]". Python 3.10 or later.

python3 -m pytest -q --cov=quantum_mind     # 139 tests (CI requires at least 80% line coverage)
python3 benchmarks/context_intent_benchmark.py    # the COBRA benchmark, about 10 to 20 minutes on 4 cores
python3 docs/make_cobra_figures.py                # redraw the COBRA figures

Limitations

• Fitting aggregate counts assumes a homogeneous population. Individual differences can hide or mimic quantum-like structure: in example 14 a pooled fit picks the quantum-like model for a population that is half anchoring, and per-person comparison needs about 3,000 answers per person to tell the models apart.
• Several quantum-like models have been challenged by further tests, for example the Grand Reciprocity equations and conjunction-fallacy tests. The family READMEs list these.
• COBRA's advantage is shown on synthetic data built to contain a context effect. With little training data it loses to the Bayes filter, training can miss the mechanism, and its coherence is a weak error signal.
• Hardware noise distorts circuits by a few percent of total variation for small circuits, and more for deep ones.

Data

quantum_mind.data contains the only human data in the package, all of it published aggregates: the Clinton–Gore order effect (Moore, 2002), the Prisoner's Dilemma disjunction effect (Shafir and Tversky, 1992), the two-stage gamble (Tversky and Shafir, 1992) and the Linda problem (Tversky and Kahneman, 1983). Every other data set in the examples is simulated and labelled as such.

Citing and licence

To cite Quantum Mind, use CITATION.cff (GitHub's "Cite this repository" button), together with the original paper of every model you use, listed on the references by model page and in references.bib (entries without a matching Crossref record hold the text as cited and are marked UNVERIFIED). The package is released under the Apache License 2.0 (see also NOTICE). For contributing see CONTRIBUTING.md; for release history see CHANGELOG.md.

Author and maintainer: Yeshwanth Guru (yeshwanth445@gmail.com; ORCID 0009-0007-6353-4033). Security reports: see SECURITY.md.