Metadata-Version: 2.4
Name: padopauli
Version: 2.0.0
Summary: GPU-accelerated, differentiable Pauli-propagation surrogate (PPS) engine
Author-email: Hyunwoo Kim <hw_kim@norma.co.kr>, Youngseok Lee <ys_lee@norma.co.kr>
License: NORMA Binary License 1.0 (proprietary; see LICENSE). Third-party notices in NOTICE.
Classifier: License :: Other/Proprietary License
Requires-Python: <3.13,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: numpy>=2.0
Requires-Dist: torch<2.13,>=2.10; sys_platform != "win32"
Requires-Dist: torch<2.13,>=2.11; sys_platform == "win32"
Requires-Dist: scipy>=1.13
Requires-Dist: tqdm
Provides-Extra: reference
Requires-Dist: pennylane<0.46,>=0.45; extra == "reference"
Dynamic: license-file

# padopauli

**PADO-Pauli** (shipped as the Python package **`padopauli`**) is a GPU-accelerated,
differentiable **Pauli-propagation surrogate (PPS) engine** for simulating
expectation values of parameterized quantum circuits. Instead of
evolving a state vector, it propagates observables through the circuit in the Pauli
basis and compiles the result into a reusable tensor program — compile once, then
evaluate expectation values and gradients many times at different parameters.

- **Differentiable**: expectation values are PyTorch tensors; gradients flow to circuit
  parameters (and to classical layers feeding them) via a built-in manual VJP, or
  equivalently through host autograd (`diff_mode="autograd"`).
- **GPU-accelerated**: execution presets `"cpu"`, `"gpu"`, and `"hybrid"` choose where
  compilation and evaluation run. There is no vendor-specific code — the torch build you
  install (CUDA or ROCm) selects the GPU; on ROCm builds the `"cuda"` device maps to AMD
  GPUs.
- **Compile once, evaluate many**: batched parameters and data-embedding angles reuse the
  same compiled program; a quasi-sampler is available for sampling workloads.
- **Noise-aware**: depolarizing and amplitude-damping channels can be placed in the
  circuit.
- Optional cross-checks against PennyLane for small systems (`pip install
  padopauli[reference]`).

## Requirements

| OS / arch | Python | torch | Supported presets |
|---|---|---|---|
| Linux x86-64 | 3.11 / 3.12 | 2.10 – 2.12 | `cpu`, `gpu`, `hybrid` |
| macOS Apple Silicon (arm64) | 3.11 / 3.12 | 2.10 – 2.12 | `cpu` |
| Windows x64 | 3.11 / 3.12 | 2.11 – 2.12 | `cpu` |

**Linux GPU users (NVIDIA/CUDA or AMD/ROCm)**: install a matching GPU build of torch
first, then install padopauli. The declared dependency is already satisfied and pip will
not replace your torch.

macOS GPU execution is not supported because the engine has no MPS path. Windows
NVIDIA execution is not part of the supported 2.0.0 surface until it is validated on
real GPU hardware.

## Install

```bash
pip install padopauli
```

## Quickstart

```python
import torch
from padopauli import Circuit

qc = Circuit(n_qubits=4)
qc.rx(0, param_idx=0).ry(1, param_idx=1)
qc.cnot(0, 1)
qc.rzz(1, 2, param_idx=2)
qc.compile(observables=[("Z", [0])], preset="cpu")  # or preset="gpu"

thetas = torch.tensor([0.1, 0.2, 0.3], dtype=torch.float64, requires_grad=True)
vals = qc.expvals(thetas)   # shape (n_observables,)
vals.sum().backward()      # gradients in thetas.grad
```

`observables` accepts `(pauli, qubits[, coeff])` term tuples or prebuilt `PauliSum`
objects. The public API is the top-level namespace only
(`from padopauli import ...`); subpackages are implementation details.

## License

Proprietary — NORMA Binary License 1.0 (the bundled LICENSE). Noncommercial use is
free regardless of organizational type or research funding source, including
company-sponsored academic research. Each user must obtain the wheel from the official
distribution source; redistribution, internal sharing, modification and reverse
engineering are not permitted. Commercial use of the software or its outputs requires
prior approval and a separate written agreement executed by both parties — contact
<contact@norma.co.kr>. Third-party notices are in the bundled NOTICE file.

Developed and maintained by Hyunwoo Kim (<hw_kim@norma.co.kr>,
<kimhw7537@gmail.com>) and Youngseok Lee (<ys_lee@norma.co.kr>) at NORMA, Inc.

© 2026 NORMA, Inc.
