Metadata-Version: 2.4
Name: openqml
Version: 0.4.0
Summary: Differentiable quantum layers and diagnostic-driven quantum circuit interoperability
Author: OpenQML contributors
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/OpenQML-org/OpenQML
Keywords: quantum,machine-learning,pytorch,jax,quantum-computing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: packaging>=23
Requires-Dist: psutil>=5.9
Requires-Dist: numpy>=1.24; platform_system != "Darwin" or platform_machine != "x86_64"
Requires-Dist: numpy<2,>=1.26; platform_system == "Darwin" and platform_machine == "x86_64"
Provides-Extra: torch
Requires-Dist: torch>=2.2; extra == "torch"
Provides-Extra: jax
Requires-Dist: jax>=0.4.30; extra == "jax"
Provides-Extra: qiskit
Requires-Dist: qiskit[qasm3-import]>=1.2; extra == "qiskit"
Requires-Dist: sympy>=1.12; extra == "qiskit"
Provides-Extra: aer
Requires-Dist: qiskit[qasm3-import]>=1.2; extra == "aer"
Requires-Dist: qiskit-aer>=0.15; extra == "aer"
Requires-Dist: sympy>=1.12; extra == "aer"
Provides-Extra: qasm
Requires-Dist: qiskit[qasm3-import]>=1.2; extra == "qasm"
Requires-Dist: openqasm3[parser]>=1.0; extra == "qasm"
Requires-Dist: sympy>=1.12; extra == "qasm"
Provides-Extra: flax
Requires-Dist: jax>=0.4.30; extra == "flax"
Requires-Dist: flax>=0.10; extra == "flax"
Requires-Dist: optax>=0.2; extra == "flax"
Provides-Extra: symbolic
Requires-Dist: sympy>=1.12; extra == "symbolic"
Provides-Extra: pennylane
Requires-Dist: pennylane>=0.40; extra == "pennylane"
Requires-Dist: sympy>=1.12; extra == "pennylane"
Provides-Extra: cirq
Requires-Dist: cirq-core>=1.4; extra == "cirq"
Requires-Dist: sympy>=1.12; extra == "cirq"
Provides-Extra: all
Requires-Dist: torch>=2.2; extra == "all"
Requires-Dist: jax>=0.4.30; extra == "all"
Requires-Dist: flax>=0.10; extra == "all"
Requires-Dist: optax>=0.2; extra == "all"
Requires-Dist: qiskit[qasm3-import]>=1.2; extra == "all"
Requires-Dist: qiskit-aer>=0.15; extra == "all"
Requires-Dist: pennylane>=0.40; extra == "all"
Requires-Dist: cirq-core>=1.4; extra == "all"
Requires-Dist: openqasm3[parser]>=1.0; extra == "all"
Requires-Dist: sympy>=1.12; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.11; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=6; extra == "dev"
Dynamic: license-file

# OpenQML

OpenQML adds trainable quantum layers to PyTorch and JAX models and compiles supported quantum circuits across Qiskit, PennyLane, Cirq and OpenQASM with explicit semantic checks.

## Install and use

```bash
python -m pip install openqml
```

The default install contains the native simulator, circuit IR, built-in OpenQASM
conversion and exact semantic proof kernels. It requires only NumPy, packaging
and psutil. Optional frameworks load on access through the same namespace:

```bash
python -m pip install "openqml[torch]"       # PyTorch quantum layers
python -m pip install "openqml[qiskit]"      # Native Qiskit interoperability
python -m pip install "openqml[all]"         # Full integration bundle
```

Other extras: `jax`, `flax` (includes Optax), `aer`, `pennylane`, `cirq`, `qasm`
(official SDK parser) and `symbolic`. Already-installed compatible frameworks
work directly; OpenQML never downloads dependencies at runtime.

```python
import openqml as oq

circuit = oq.Circuit(2).ry(oq.Parameter("theta"), 0).cx(0, 1)
compiled = oq.compile_verified(circuit, target="openqasm3")
plan = oq.plan_execution(circuit, (oq.PauliString("ZI"),))
values = plan.evaluate({"theta": 0.4})
```

Native APIs are available through `oq.torch`, `oq.jax`, `oq.flax`, `oq.optax`, `oq.numpy` and the SDK namespaces, including `oq.qiskit`, `oq.pennylane`, `oq.cirq` and `oq.qiskit_aer`.

## Hybrid learning

Install the `torch` extra for this example:

```python
import openqml as oq

model = oq.torch.nn.Sequential(
    oq.torch.nn.Linear(4, 2),
    oq.torch.QuantumLayer.data_reuploading(2, depth=1),
    oq.torch.nn.Linear(2, 1),
)
optimizer = oq.torch.optim.Adam(model.parameters(), lr=1e-3)
optimizer.zero_grad()
loss = model(oq.torch.randn(8, 4)).square().mean()
loss.backward()
optimizer.step()
```

One optimizer updates classical and quantum weights. JAX layers use `layer.init(key)` and `layer(weights, inputs)`; Flax and Optax are supported. Native tensor/Pauli execution preserves higher derivatives. Numerical SDK and MPS bridges provide first-order JVPs and VJPs.

## Research methods

| API | Capability |
| --- | --- |
| `oq.quantum_metric(circuit)` / `spec.metric_plan()` | Matrix-free Fubini--Study products and damped natural-gradient solves |
| `oq.shadow_estimate(...)` | Independent-pilot correlated local dual-frame shadows; reuse data with `result.reestimate(...)` |
| `oq.estimate_adaptive(...)` | Pilot-covariance shot allocation within a total budget |
| `oq.TruncatedMPSBackend(...).evaluate(...)` | Opt-in rank-limited MPS with truncation error reports |
| `oq.optimize_verified(circuit)` | Return an optimization only after exact semantic certification |

The [whole-library research record](docs/research-methods.md) links each method
to its sources, assumptions, measured evidence and assessed alternatives.
Classical state-vector geometry remains exponential in qubit count. Shadow
covariances assume the intended sampler; MPS truncation bounds exclude numerical
roundoff. Unsupported hardware/distributed methods are not claimed as implemented.

## Verifiable circuit compilation

| API | Guarantee |
| --- | --- |
| `oq.prove_equivalence(a, b)` | Bounded algebraic equivalence, including factored exact hybrid density kernels, for all valid defined parameter bindings |
| `oq.compile_verified(c, target=...)` | Exports with an algebraic certificate; refuses unproved conversions |
| `oq.plan_conversion(...).verify(mode="native")` | Independent target-runtime comparison over a complete input basis at explicit bindings |
| `oq.semantic_coverage()` | Representative framework/IR feature matrix and diagnostics |

The proof kernel uses affine Boolean phase polynomials, exact word rewrites and optional projective Clifford conjugation. Strict mode compares global phase. Projective mode explicitly ignores it. Stored floating constants remain exact binary rationals; SDK rounding or unsupported identities can leave a conversion **unproved**, which does not establish inequivalence. Certificates cover the adapter's IR interpretation; native runtime checks remain separate.

Hybrid proofs compare the full quantum output and every final classical bit,
starting with zero classical storage. They handle measurement, reset, nested
feedback, symbolic rotations and supported noise channels, adding hidden
histories before comparison. Quantum/classical dependencies from **both**
programs determine independent components. Each component defaults to at most
six active qubits, with additional term, work and exact-coefficient limits;
many independent components do not imply general large entangled-circuit capacity.
Global phase is physically unobservable in this quantum-instrument semantics.
Bounded exact operator kernels also handle the universal Hadamard/rotation gate
set in strict unitary proofs, retaining global phase when simpler forms fail.
See [the algorithm, limits and research basis](docs/semantic-kernels.md).

Arbitrary Python programs are outside automatic translation. `oq.inspect_python(text)` diagnoses source without executing it. Dynamic control, custom matrices and noise require supported IR representations. External noise models, pulse calibrations and hardware context are diagnosed rather than silently preserved.

## Adaptive execution

`oq.plan_execution(...)` reports its method, rejected candidates and memory admission before execution. Existing numerical APIs also accept `backend="auto"`.

| Method | Admission |
| --- | --- |
| Stabilizer | Named Clifford gates and bounded tableau storage |
| Pauli | Bounded exact symbolic propagation of declared readouts |
| OpenQML MPS | Nearest-neighbor one/two-wire circuits; planned full-SVD dimensions, no singular-value truncation |
| Dense vector/density | Memory-derived capacity, including classical branches |
| CUDA dense | Explicit dense device preference and sufficient available GPU memory |

Direct vector execution and quantum layers have no fixed 20-qubit ceiling. The default vector budget remains 256 MiB; `max_qubits` is an optional additional cap. Four complex128 buffers per row require:

| Qubits | Working budget |
| ---: | ---: |
| 22 | 256 MiB |
| 24 | 1 GiB |
| 26 | 4 GiB |

Adaptive plans default to one quarter of observed host/container availability, capped at 4 GiB. Autodiff tapes and backend costs still matter; admission models are not process RSS limits. Difficult non-Clifford, noisy and highly entangled circuits can exhaust every method.

## Evidence and installation cost

The [compiler/execution audit](https://github.com/OpenQML-org/OpenQML/blob/main/benchmarks/results/compiler_execution_cpu.json) records randomized differential checks, symbolic certificates, a 1,024-qubit Clifford case, independently checked 128-qubit non-Clifford MPS readouts and measured dense execution. These are representation-specific results, not general large-qubit simulation guarantees.

[CI](https://github.com/OpenQML-org/OpenQML/actions/workflows/ci.yml) separately tests
the core and full bundle. GPU execution requires suitable hardware and is
skipped on CPU runners. The earlier
[full-bundle measurement](benchmarks/results/installation_linux.json) occupies
about 6.39 GiB; it is not the new core footprint.
The [new clean Linux core measurement](benchmarks/results/core_installation_linux.json)
is about **68.7 MiB**, including its three dependencies. These are different
installation profiles and dependency versions, not a same-version compression
benchmark. The full bundle remains available and remains substantial.
`oq.environment_report(check_imports=True, include_sizes=True)` reports the core
dependency closure and optional integration availability. Pass `extras=("all",)`
or use `python -m openqml doctor --extra all --sizes` to audit the full bundle.
Missing optional SDKs do not make a core installation unhealthy.

## Architecture

![OpenQML project architecture](https://raw.githubusercontent.com/OpenQML-org/OpenQML/main/docs/architecture.svg)

[Apache license](https://github.com/OpenQML-org/OpenQML/blob/main/LICENSE)
