Metadata-Version: 2.4
Name: openqml
Version: 0.24.1
Summary: Quantum-classical hybrid AI, quantitative research and cross-framework quantum programming
Author: OpenQML contributors
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/OpenQML-org/OpenQML
Keywords: quantum,machine-learning,quantitative-finance,pytorch,jax,interoperability
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"
Requires-Dist: optax>=0.2; 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: aer-gpu
Requires-Dist: qiskit[qasm3-import]>=1.2; extra == "aer-gpu"
Requires-Dist: sympy>=1.12; extra == "aer-gpu"
Requires-Dist: qiskit-aer-gpu>=0.17; (platform_system == "Linux" and platform_machine == "x86_64") and extra == "aer-gpu"
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: compute
Requires-Dist: cotengra<0.8,>=0.7.5; (python_version < "3.11" or (platform_system == "Darwin" and platform_machine == "x86_64")) and extra == "compute"
Requires-Dist: autoray<0.8,>=0.7.2; (python_version < "3.11" or (platform_system == "Darwin" and platform_machine == "x86_64")) and extra == "compute"
Requires-Dist: cotengra>=0.8.3; (python_version >= "3.11" and (platform_system != "Darwin" or platform_machine != "x86_64")) and extra == "compute"
Requires-Dist: autoray>=0.8.4; (python_version >= "3.11" and (platform_system != "Darwin" or platform_machine != "x86_64")) and extra == "compute"
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"
Requires-Dist: cotengra<0.8,>=0.7.5; (python_version < "3.11" or (platform_system == "Darwin" and platform_machine == "x86_64")) and extra == "all"
Requires-Dist: autoray<0.8,>=0.7.2; (python_version < "3.11" or (platform_system == "Darwin" and platform_machine == "x86_64")) and extra == "all"
Requires-Dist: cotengra>=0.8.3; (python_version >= "3.11" and (platform_system != "Darwin" or platform_machine != "x86_64")) and extra == "all"
Requires-Dist: autoray>=0.8.4; (python_version >= "3.11" and (platform_system != "Darwin" or platform_machine != "x86_64")) and 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

[PyPI](https://pypi.org/project/openqml/) · [Documentation](https://github.com/OpenQML-org/OpenQML/blob/main/docs/api.md) · [CI](https://github.com/OpenQML-org/OpenQML/actions/workflows/ci.yml)

[Contributing](CONTRIBUTING.md) · [Governance](GOVERNANCE.md) · [Security](SECURITY.md)

## Quantum–classical hybrid AI

Build and train hybrid neural networks with PyTorch, JAX or Flax. Use `Model.fit` and `predict` for supervised tasks, or compose convolution, attention, graph, recurrent and generative architectures with native layers. Validation loss, early stopping and portable checkpoints keep model selection and continued training in the same workflow. [Explore hybrid AI](https://github.com/OpenQML-org/OpenQML/blob/main/docs/models.md).

## Quantum–classical hybrid quantitative research

Train scenario distributions, allocate constrained portfolios and project decisions onto explicit CVaR budgets with a funded cash position. Low-rank factor solves and native PyTorch/JAX derivatives connect financial objectives to hybrid models. Purged walk-forward refits and self-financing accounting preserve chronological evaluation, execution delays, fees and market impact. [Explore quantitative research](https://github.com/OpenQML-org/OpenQML/blob/main/docs/finance.md).

## Cross-framework quantum programming

Connect Qiskit, Cirq, PennyLane and OpenQASM through a shared circuit representation. Compile grouped switch cases, finite loops and atomic classical guards; reuse shared definitions and symbolic expressions. Prepare conversions once, stream parameter sweeps and verify their semantics against round-trip or native execution. [Explore interoperability](https://github.com/OpenQML-org/OpenQML/blob/main/docs/interoperability.md).

Simulate physical noise with amplitude/phase damping, depolarization and custom Kraus channels. Correct independent readout errors or extrapolate measured noise scales with explicit conditioning and sampling-overhead limits. Caller-initialized Qiskit V2 primitives connect real hardware; see [execution limits and mitigation](https://github.com/OpenQML-org/OpenQML/blob/main/docs/runtime.md#physical-noise-and-error-mitigation).

## Install

Python 3.10 or later:

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

The core depends on NumPy, packaging and psutil. Training frameworks, quantum SDKs and execution engines load on demand. Install the integrations you use, such as `openqml[torch]`, `openqml[jax]`, `openqml[flax]` or `openqml[qiskit,cirq]`.

For NVIDIA GPU simulation, `openqml[aer-gpu]` on supported Linux systems connects the shared IR and scheduler to Aer's C++/CUDA engine, including optional cuStateVec and cuTensorNet paths. Native PyTorch/JAX training keeps tensors and gradients on the selected GPU. Caller-initialized Qiskit V2 primitives support asynchronous QPU submission with recoverable job receipts. See [GPU and QPU execution](docs/runtime.md).

## Quick start

Allocate from observed returns:

```python
import openqml as oq

returns = [[0.01, -0.02], [-0.01, 0.03], [0.02, 0.01]]
portfolio = oq.finance.allocate(returns, caps=0.7, fees=0.001)
print(portfolio.weights)
```

Train a hybrid model after installing `openqml[torch]`:

```python
import openqml as oq

x = [[0.0, 0.0], [0.0, 1.0], [1.0, 0.0], [1.0, 1.0]] * 8
y = [0, 1, 1, 0] * 8
model = oq.Model(task="classification", hidden_features=8, depth=2)
model.fit(x, y, epochs=10)
print(model.predict(x[:2]))
```

Select `framework="jax"` or `framework="flax"` to change training frameworks. `backend` chooses circuit execution; `device` chooses native tensor placement. Qubit counts follow the selected backend's available resources.

Convert a circuit with the core installation:

```python
import openqml as oq

circuit = oq.Circuit(2).h(0).cx(0, 1)
result = oq.convert(circuit, target="openqasm3")
print(result.value)
```

`convert` imports, checks and exports in one call. Native SDK targets require
their corresponding integration. Use `plan_conversion` when repeatedly binding
or exporting the same source.

Hybrid models, financial operators and circuit execution share a
native compute kernel. It centralizes array placement, matrix products,
contraction planning, numerical checks and memory admission. Configure a common
workspace ceiling for an isolated execution scope:

```python
import openqml as oq

with oq.compute_context(policy=oq.ComputePolicy(max_memory_mb=512)):
    result = oq.expectations(oq.Circuit(1).h(0), [oq.PauliString("Z")])
```

Use `compile_compute` for checked Torch/JAX compilation. Iterative solves certify
their true residual before returning a solution. Operation-specific budgets
remain available. Shared caches hold bounded,
immutable planning metadata; trainable tensors stay in each forward pass.
[Compute policies and numerical contracts](https://github.com/OpenQML-org/OpenQML/blob/main/docs/compute.md).

`Circuit.append` shares immutable prefix chunks. Local NumPy execution fuses
single/two-wire gate groups and applies them through tensor views. Use
`compile_circuit` to compile a complete native circuit and its declared readouts.
Implementations are organized in responsibility packages; the root API and
published module imports remain available.

[API](https://github.com/OpenQML-org/OpenQML/blob/main/docs/api.md) · [Training and validation](https://github.com/OpenQML-org/OpenQML/blob/main/docs/hybrid-training.md) · [Quantitative research](https://github.com/OpenQML-org/OpenQML/blob/main/docs/finance.md) · [Interoperability](https://github.com/OpenQML-org/OpenQML/blob/main/docs/interoperability.md) · [Runtime](https://github.com/OpenQML-org/OpenQML/blob/main/docs/runtime.md)

## License

[Apache-2.0](LICENSE)
