quantum-mind 2.0.0

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

Three pillars · Bloch viewer · Quick start · Catalogue · Examples · Hardware · Status · Notebooks · API · Concepts

Quantum Mind (pip install quantum-mind, import quantum_mind) is one library for the three ways "quantum" enters modelling today:

• quantum-like models of how people judge, decide and trust, each paired with the classical models it must beat;
• quantum machine learning and algorithms as Qiskit circuits;
• quantum-inspired classical optimisers and tensor networks.

All three share one problem format, one fitting and comparison workflow, and one 3D Bloch-sphere viewer. Every circuit runs on Aer, IBM Quantum and Amazon Braket. The library was built for robots and AI agents that work with people, and it applies equally to surveys, finance, medicine, consumer research, physics and operations research.

Quantum-like models use the mathematics of quantum probability to describe judgements. They run on ordinary computers and do not claim that the brain is a quantum computer. Quantum models are circuits for quantum hardware. Quantum-inspired models are classical algorithms. The concepts page explains the difference and how to test each.

Three pillars

Shared layers: quantum_mind.core (fitting, BIC/AIC comparison, model recovery), quantum_mind.problems (QUBO builders for MaxCut, knapsack, multi-robot task allocation, portfolio and Ising problems) and quantum_mind.viz (the 3D Bloch-sphere viewer).

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
traj.concurrence(0, 1)                              # entanglement of the pair along the circuit

_{The same circuit as a timeline: plot_entanglement(traj) shows each qubit's Bloch-vector length and the pair's concurrence (Wootters); plot_qsphere(state) draws the Q-sphere.}

Interactive versions of both animations (rotate, zoom, play, slider) are written by examples/19 and examples/20, and shown inline in the notebooks. The viewer README covers everything else.

Quick start

pip install "quantum-mind[all]"

import numpy as np
from quantum_mind.core 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))

from quantum_mind.quantum import VariationalClassifier
from quantum_mind.circuits import run

clf = VariationalClassifier(layers=3).fit(X_train, y_train)
print(clf.score(X_test, y_test))
counts = run(clf.to_qiskit(X_test[0]), 'aer:FakeTorino', shots=4000)

from quantum_mind.problems import task_allocation
from quantum_mind.quantum import QAOA
from quantum_mind.inspired import SQA, QIEA, simulated_annealing

q = task_allocation(costs)                       # costs[robot, task]
print(q.brute_force()[1],                        # exact
      QAOA(q, p=3).run().energy,                 # quantum
      SQA(q).run().value, QIEA(q).run().value,   # quantum-inspired
      simulated_annealing(q).value)              # classical baseline

from quantum_mind.applications.robotics import HumanModelService

svc = HumanModelService()                                   # wraps HumanModelEnsemble + ask_or_act
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'

_{Generated by docs/make_assets.py from the package itself (simulated data).}

Model catalogue

Architecture

flowchart TB
    core["quantum_mind.core<br/>Model · Param · fit · compare · recovery"]
    fam["quantum_mind.families<br/>11 quantum-like families"]
    app["quantum_mind.applications<br/>robotics"]
    prob["quantum_mind.problems<br/>QUBO builders"]
    qm["quantum_mind.quantum<br/>VQC · kernels · QAOA · VQE · Grover · QFT · QAE · walks"]
    ins["quantum_mind.inspired<br/>QIEA · QPSO · SQA · MPS · QRL · QLM"]
    circ["quantum_mind.circuits<br/>circuits + run()"]
    viz["quantum_mind.viz<br/>Bloch-sphere viewer"]
    hw[("Aer · IBM Quantum · Amazon Braket")]
    core --> fam --> app
    fam --> circ
    prob --> qm
    prob --> ins
    qm --> circ
    circ --> hw
    fam --> viz
    qm --> viz
    circ --> viz

src/quantum_mind/
├── core/           Lüders rule, density matrices, Lindblad · Model/Param · fit, compare, recovery
├── families/       order_effects · conjunction · interference · qlbn · dynamics · decision · contextuality · similarity · game_theory · memory · concepts
├── applications/   robotics: question domains, questioning designs, trust, intent resolution, human-model ensemble, ask_or_act, HumanModelService
├── quantum/        statevector simulator · ansatz · classifiers · QAOA · VQE · Grover · QFT · amplitude estimation · walks
├── inspired/       QIEA · QPSO · SQA · simulated annealing · MPS classifier · QRL · quantum language model
├── problems/       QUBO builders shared by quantum and quantum-inspired solvers
├── circuits/       Qiskit circuits of the families · run() on Aer, IBM Quantum, Amazon Braket
├── viz/            Bloch vectors, trajectories, tomography · Matplotlib and Plotly viewers · LiveBloch
└── data/           published aggregate data sets
examples/           31 scripts across domains        docs/       Sphinx documentation, concepts, assets
notebooks/          2 Jupyter notebooks              tests/      63 tests
integrations/ros2/  ROS 2 node (quantum_mind_ros)
site/               project website (built and deployed to GitHub Pages by CI)
.github/            CI, release, website, CODEOWNERS, issue and pull-request templates

Examples across domains

Pillar: QL quantum-like, Q quantum, QI quantum-inspired, viz Bloch-sphere viewer.

Notebooks: 01_bloch_sphere_live (interactive and live spheres, tomography under device noise) and 02_robot_questioning_and_trust (order effects, ensemble, ask-or-act, trust on the sphere). Both run in CI.

Results printed by the examples (simulated data, this version). They illustrate the methods on small problems; they are not a benchmark, and on classification, forecasting, anomaly detection and clustering a well-specified classical model wins (bold):

Running on quantum hardware

python3 examples/11_cloud_run.py --dry-run                                  # local, no account
python3 examples/11_cloud_run.py --backend ibm:least_busy --shots 4000      # IBM Quantum
python3 examples/11_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>. Every to_qiskit() circuit in quantum_mind.quantum and every builder in quantum_mind.circuits works with it. Hardware runs cost queue time or money. Report their results exactly as measured, with backend, date and job identifier.

No hardware results are included in the package. IBM jobs use the client-side Qiskit Runtime Sampler (qiskit_ibm_runtime.executor_sampler), falling back to SamplerV2 on releases before 0.50.

Status and scope

Sizes. The simulator holds 2ⁿ amplitudes per sample, at most 22 qubits. Measured on a laptop CPU: the variational classifier trains 8 features × 400 samples in about 80 s (151 L-BFGS steps, 85 MB); QAOA on 9 variables takes seconds; brute-force QUBO solutions are limited to 22 variables. Grover's gate-level export needs about 360 CNOTs per iteration at 8 qubits and 660 at 10, against 510 and 2,040 for the diagonal-gate export, which grows exponentially.

Name. Quantum Mind began as qlcog, the quantum-like cognition library (renamed in 2.0); the quantum and quantum-inspired toolkits sit beside it so that all three can be compared on the same problems. The repository name reflects the main application, robots that work with people.

Installation

pip install quantum-mind              # core: numpy, scipy
pip install "quantum-mind[all]"       # everything (Qiskit, cloud back ends, viewer)
pip install "quantum-mind[all] @ git+https://github.com/yeshwanthguru/quantum-mind"   # latest development version

From a clone: pip install -e ".[all,dev]". Python 3.10 or later. Examples and tests also run without installing, because they add src/ to the path.

Choosing and testing a model

1. Check the phenomenon first. Look for an order effect, a violation of total probability, or asymmetric similarity. If there is none, a classical model is enough.
2. Fit quantum-like models and classical baselines together with compare. Report all of them.
3. Use each family's distinctive test: the QQ equality, total-probability bounds, Contextuality-by-Default, or the effect of an intermediate judgement.
4. Run a recovery study (quantum_mind.core.recovery) at the planned sample size before collecting data.
5. For quantum and quantum-inspired solvers, always print the exact or classical baseline, as every example does.

python3 -m pytest -q --cov=quantum_mind     # 63 tests, about 90% line coverage (CI requires at least 80%)

The tests check the simulator against Qiskit gate by gate, adjoint and parameter-shift gradients against finite differences, exported circuits against simulation, circuit builders against the analytic models, the IBM and Braket submission code against local stand-ins, Bloch trajectories against Qiskit's partial trace and the trust model, input validation and size limits. CI also lints, checks that the API reference is current, runs the docstring examples, the examples and the notebooks, builds the Sphinx documentation with warnings as errors, and builds the wheel.

Limitations

• Fitting aggregate counts assumes a homogeneous population. Individual differences can hide or mimic quantum-like structure: in example 22 a pooled fit picks the quantum-like model for a population that is half anchoring. Per-person comparison (compare_individuals) needs many answers per person (there, about 3,000) 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.
• The quantum models are small and exactly simulable. No quantum advantage is claimed: on the example classification task a classical model with quadratic features is the most accurate. Shallow QAOA concentrates little probability on the optimum (a few percent on 9-variable problems).
• "Quantum-inspired" names where an idea came from, not a speed-up. Compare against the classical baseline.
• 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 is published aggregate data:

• 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);
• 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 papers of the models used, which are listed in each README. The package is released under the Apache License 2.0 (see also NOTICE). The licence permits commercial and research use and includes an explicit patent grant. 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.

Companion manuscripts (in preparation): a systematic review of quantum-like cognition for autonomous agents, a systematic review of meta-learning orchestration on resource-constrained robots, and "Order-Aware Human Models for Robot Questioning and Trust", whose simulations use the robotics application of this library.