Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ jobs:
python-version: '3.12'
- run: python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
- run: python -m pip install ".[jax,qiskit,dev]"
- run: python -m pytest -q tests/test_native_geometry.py tests/test_transport_geometry.py tests/test_classical_predicates.py tests/test_compilation_portability.py tests/test_package_layout.py
- run: python -m pytest -q tests/test_submission_training.py tests/test_expectile_risk.py tests/test_classical_arithmetic.py tests/test_native_geometry.py tests/test_transport_geometry.py tests/test_classical_predicates.py tests/test_compilation_portability.py tests/test_package_layout.py
public-types:
runs-on: ubuntu-latest
steps:
Expand Down Expand Up @@ -124,7 +124,7 @@ jobs:
- run: python -m pip install "torch==2.2.2" --index-url https://download.pytorch.org/whl/cpu
- run: python -m pip install "numpy==1.26.4" "jax==0.4.30" "jaxlib==0.4.30" "optax==0.2.3" "chex==0.1.87"
- run: python -m pip install ".[dev]"
- run: python -m pytest -q tests/test_compilation_portability.py tests/test_native_geometry.py tests/test_transport_geometry.py tests/test_native_fusion.py tests/test_execution_hotpaths.py tests/test_package_layout.py tests/test_compute_kernel.py tests/test_reliability.py tests/test_entry_contracts.py tests/test_prepared_workflows.py tests/test_register_programs.py tests/test_accelerators.py tests/test_native_gpu.py tests/test_native_constant_cache.py
- run: python -m pytest -q tests/test_submission_training.py tests/test_expectile_risk.py tests/test_compilation_portability.py tests/test_native_geometry.py tests/test_transport_geometry.py tests/test_native_fusion.py tests/test_execution_hotpaths.py tests/test_package_layout.py tests/test_compute_kernel.py tests/test_reliability.py tests/test_entry_contracts.py tests/test_prepared_workflows.py tests/test_register_programs.py tests/test_accelerators.py tests/test_native_gpu.py tests/test_native_constant_cache.py
compiled-transforms:
runs-on: ubuntu-latest
steps:
Expand All @@ -134,7 +134,7 @@ jobs:
python-version: '3.11'
- run: python -m pip install "torch==2.4.1" --index-url https://download.pytorch.org/whl/cpu
- run: python -m pip install "numpy==1.26.4" . pytest
- run: python -m pytest -q tests/test_compilation_portability.py tests/test_native_geometry.py tests/test_transport_geometry.py tests/test_native_fusion.py tests/test_activation_checkpointing.py tests/test_execution_hotpaths.py tests/test_package_layout.py
- run: python -m pytest -q tests/test_submission_training.py tests/test_expectile_risk.py tests/test_compilation_portability.py tests/test_native_geometry.py tests/test_transport_geometry.py tests/test_native_fusion.py tests/test_activation_checkpointing.py tests/test_execution_hotpaths.py tests/test_package_layout.py
portable-install:
strategy:
fail-fast: false
Expand Down Expand Up @@ -174,7 +174,7 @@ jobs:
}
- run: python -m pip check
- run: python -m openqml doctor --extra all --check-imports --sizes --output environment-report.json
- run: python -m pytest -q tests/test_compilation_portability.py tests/test_native_fusion.py tests/test_register_programs.py tests/test_native_geometry.py tests/test_transport_geometry.py tests/test_classical_predicates.py
- run: python -m pytest -q tests/test_submission_training.py tests/test_expectile_risk.py tests/test_classical_arithmetic.py tests/test_compilation_portability.py tests/test_native_fusion.py tests/test_register_programs.py tests/test_native_geometry.py tests/test_transport_geometry.py tests/test_classical_predicates.py
- run: python -m pytest -q tests/test_compute_kernel.py tests/test_reliability.py tests/test_entry_contracts.py tests/test_prepared_workflows.py tests/test_accelerators.py tests/test_native_gpu.py tests/test_precision_regressions.py tests/test_audit_regressions.py tests/test_switch_lowering.py tests/test_risk_budget.py tests/test_tensor_streaming.py tests/test_model_checkpoint.py tests/test_model_selection.py tests/test_walk_forward.py tests/test_conversion_sweeps.py tests/test_finance_execution.py tests/test_simple_api.py tests/test_adaptive_amplitude.py tests/test_amplitude.py tests/test_finance.py tests/test_frontier_models.py tests/test_algorithmic_execution.py tests/test_network_operators.py tests/test_architecture.py tests/test_deep_learning.py tests/test_cost_scheduling.py tests/test_calibration.py tests/test_distributed_compute.py tests/test_multiscale_execution.py tests/test_gradient_accumulation.py tests/test_program_compilation.py tests/test_distributed_training.py tests/test_compute_contractions.py tests/test_contraction_compiler.py tests/test_runtime.py tests/test_hybrid_training.py tests/test_sparse_scaling.py tests/test_research_methods.py tests/test_public_api.py tests/test_package_scope.py tests/test_package_layout.py tests/test_execution_hotpaths.py tests/test_mitigation.py tests/test_model_streaming.py tests/test_backends.py tests/test_providers.py tests/test_shared_readouts.py tests/test_conversion_plan.py tests/test_resource_audit.py tests/test_source_boundaries.py tests/test_resource_profiles.py tests/test_environment_report.py tests/test_scientific_scale.py tests/test_semantic_compiler.py tests/test_adaptive_execution.py
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
if: always()
Expand Down
6 changes: 6 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ Build and train hybrid neural networks with PyTorch, JAX or Flax. Use `Model.fit
Native quantum metric products and certified natural-gradient solves retain
PyTorch/JAX tensors and device placement. An optional geometry-first spectral
step balances circuit parameter blocks after preconditioning.
External Torch/JAX layers can pack forward and parameter-shift rows together,
reusing one linearization during backward to reduce provider round trips.

## Quantum–classical hybrid quantitative research

Expand All @@ -19,6 +21,8 @@ Train scenario distributions, allocate constrained portfolios and project decisi
Learn contextual Wasserstein radii and anisotropic transport metrics alongside
quantum scenario probabilities. Factor-space implicit derivatives connect the
robust risk bound and funded cash allocation to the predictive model.
Coherent expectile risk and Wasserstein expectile budgets provide an additional
native decision objective with exact sorted roots.

## Cross-framework quantum programming

Expand All @@ -27,6 +31,8 @@ Connect Qiskit, Cirq, PennyLane and OpenQASM through a shared circuit representa
Typed Qiskit logical, bitwise and unsigned comparison predicates lower to bounded
shared decision graphs. Their branch selection completes before either payload
executes, including payloads that overwrite a measured predicate input.
Fixed-width unsigned arithmetic, bounded shifts and dynamic bit indexing retain
the same atomic branch-selection contract.

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).

Expand Down
4 changes: 4 additions & 0 deletions docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,10 @@ operate on native Torch/JAX parameter vectors. Their result types are
`NativeMetricResult` and `SpectralStepResult`. See [native quantum geometry](native-geometry.md)
for the metric convention, spectral block order, residual certificates and scope.

`ShiftPlan.linearize` returns `ShiftLinearization` with forward values, an
explicit Jacobian and submission counts. External Torch/JAX layers opt in with
`gradient_method="batched-shift"`; see [submission-aware training](submission-training.md).

## Circuit conversion

```python
Expand Down
46 changes: 46 additions & 0 deletions docs/finance.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,9 @@ data, broker connection or extra core dependency is installed.
| Factor risk | `factor_risk(returns, probabilities)` | Weighted centered factors plus shrinkage diagonal |
| Differentiable allocation | `AllocationPlan.solve(mean, risk, ...)` | Long-only capped allocation with funding and turnover costs |
| Tail risk | `expected_shortfall`, `wasserstein_cvar` | Fractional weighted CVaR and a Wasserstein robustness margin |
| Expectile risk | `expectile`, `wasserstein_expectile` | Coherent asymmetric-loss risk and an unrestricted-support W1 supremum |
| Decision risk budgets | `risk_budget_projection(weights, scenarios, ...)` | Maximal funded cash-ray scaling under weighted robust CVaR |
| Expectile decision budgets | `expectile_budget_projection(weights, scenarios, ...)` | Maximal funded cash-ray scaling under robust expectile risk |
| Funded execution | `SelfFinancingPlan.rollout(...)` | Delayed decisions, cash, proportional fees and quadratic impact |
| Chronological validation | `PurgedWalkForward.split(times, label_end)` | Past-only training with overlapping labels removed |
| Rolling model selection | `walk_forward(factory, inputs, targets, ...)` | Fresh hybrid models, nested validation and aligned out-of-sample predictions |
Expand Down Expand Up @@ -229,6 +231,50 @@ rejects unresolved financing rather than returning weights outside the budget.

## Differentiable decision risk budgets

`expectile(losses, level=0.95, probabilities=None)` adds a coherent, elicitable
risk measure. Its level is an asymmetric-loss weight, not a quantile confidence
or the fraction of observations in a tail. Supported levels lie in `[0.5,1)`;
level `0.5` returns the weighted mean. A sorted piecewise-affine root uses
`O(S log S)` work and `O(S)` workspace for `S` scenarios. Native derivatives
are piecewise smooth; ties and active-set transitions can be nonsmooth.

`wasserstein_expectile(weights, scenarios, level=..., radius=...,
transport_metric=...)` returns the worst-case loss expectile over an
unrestricted-support W1 ball. With `L=-returns@weights` and
`delta=radius*transport_dual_norm(weights, metric)`, it solves
`level*E[(L-q)+] -(1-level)*E[(q-L)+] +level*delta=0`.
The robustness penalty depends on the tail mass at the root. Zero radius
recovers the nominal expectile. The supremum can require transporting arbitrarily
small mass arbitrarily far; support or moment constraints can make this bound
conservative.

`expectile_budget_projection` uses `level` and otherwise shares the funded cash,
scenario, probability, radius, metric and memory arguments of the CVaR budget
layer. `ExpectileBudgetResult` exposes `weights`, `cash`, `scale`, `expectile`,
`robust_expectile` and `budget`. Positive homogeneity and cash translation make
its admitted cash-ray scale maximal. It scales a supplied proposal; it does not
optimize unrestricted portfolio directions or fit market data.

```python
import openqml as oq

decision = oq.finance.expectile_budget_projection(
[0.4, 0.5],
[[-0.12, -0.03], [0.04, -0.08], [0.1, 0.02]],
level=0.8,
budget=0.015,
radius=0.001,
)
```

The robust root specializes the envelope mechanism of
[Multi-period Mean-Expectile Portfolio Optimization under Wasserstein Ambiguity (October 2026)](https://arxiv.org/abs/2610.11917).
It implements a one-period unrestricted-support risk layer, excluding the
paper's fixed-mean constraints and multi-period optimization programs.
Calibrate radius and geometry using past-only held-out data, then evaluate with
the existing purged walk-forward and self-financing ledger. The paper's empirical
portfolio results are not OpenQML performance evidence.

`WassersteinMetric(diagonal, factors=None)` defines the anisotropic ground norm
`||delta||_M`, where `M = diag(diagonal) + factors.T @ factors`. The diagonal
must be strictly positive; factors have shape `[...,rank,assets]`. Both may be
Expand Down
15 changes: 12 additions & 3 deletions docs/interoperability.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,8 +77,15 @@ The Qiskit IR route additionally accepts pure `Bool`/`Uint` expressions over
declared classical bits/registers: `logic_not`, `logic_and`, `logic_or`,
`bit_not`, `bit_and`, `bit_or`, `bit_xor`, equality/inequality and all unsigned
ordered comparisons. Bool/Uint casts implement nonzero truth conversion,
unsigned truncation and zero extension. Standalone mutable variables, signed
arithmetic, stores, timing and other unsupported expression operations retain
unsigned truncation and zero extension. Uint addition, subtraction and
multiplication use the expression's declared width, including modulo `2**width`
overflow. Logical shifts and bit indexing accept constant selectors or dynamic
selectors whose full bit-vector range is provably inside the operand width.
Barrel-select networks lower dynamic selectors without enumerating valuations.
Out-of-range or unproven selectors retain range diagnostics.

Standalone mutable variables, signed/float arithmetic, division, stores, timing
and other unsupported expression operations retain
explicit diagnostics or require the existing native program route.

A bit-vector compiler lowers these predicates into reduced ordered binary
Expand All @@ -91,7 +98,9 @@ subset remains compatible with OpenQASM and Cirq export/reimport paths.

`max_operations` bounds expression/bit-vector work, BDD construction and the
expanded decision/payload cost; `max_depth` bounds expression, guard and payload
nesting. Variable order follows declared bit indices. Some Boolean functions
nesting. Ripple-carry arithmetic, truncated multiplication and selector networks
charge their Boolean work before expansion, including constant expressions.
Variable order follows declared bit indices. Some Boolean functions
have large decision or expanded output representations and are rejected at the
budget boundary. This is an expanded representable subset, not universal host
Python or general classical-program translation.
Expand Down
5 changes: 5 additions & 0 deletions docs/models.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,10 @@
# Structured quantum–classical models

External `QuantumLayer` instances support `gradient_method="batched-shift"`
to pack forward readouts and their derivative stencil before the first result.
See [submission-aware training](submission-training.md) for the Jacobian-memory
tradeoff, Torch/JAX transforms and QPU submission accounting.

For KAN, recurrent memory, Born generators, autoregressive sequence models and
quantum-state diffusion, see [Stateful and generative models](frontier-models.md).

Expand Down
5 changes: 4 additions & 1 deletion docs/runtime.md
Original file line number Diff line number Diff line change
Expand Up @@ -138,11 +138,14 @@ the actual transpiled layout, provider grouping and calibration regime.
| `native_devices` | Platforms supporting native autodiff; other platforms include parameter-shift work |
| `submission_batch_size` | Client chunking limit, combined with provider batch limits |
| `microbatch_size`, `gradient_chunk_size` | Sequential training microbatches and shifted-row submission chunks |
| `joint_primal_gradient` | Pack primal and shifted rows in one phase for eager linearization |
| `classical_seconds_per_step`, `classical_cost_per_step` | Encoder, optimizer and other classical work |
| `ExecutionProfile` | Queue, job latency, circuit/shot time, prices, concurrency, groups, mitigation overhead and uncertainty |
| `SchedulingPolicy` | Cost/deadline/error limits, time/cost/error preferences and uncertainty margin |

Forward and gradient phases are sequential; optimizer steps cannot borrow
Forward and gradient phases are sequential by default. With
`joint_primal_gradient=True`, a packed linearization combines their rows before
submission; see [submission-aware training](submission-training.md). Optimizer steps cannot borrow
parallel capacity from future steps. Queue/latency apply to each job wave.
Billing sums total device use, even when jobs overlap. All quotes use the
policy's currency. QPU quotes require explicit queue, pricing and noise values;
Expand Down
88 changes: 88 additions & 0 deletions docs/submission-training.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
# Submission-aware quantum training

Cloud latency can dominate a small variational circuit. `ShiftPlan.linearize`
packs the current readouts and their occurrence-wise parameter-shift stencil
before reading any result. It supports nonlinear shared angles, controlled
rotations and supported noise-channel derivative recipes.

| Field or operation | Meaning |
| --- | --- |
| `values` | Read-only NumPy `[batch,readouts]` forward expectations |
| `jacobian` | Read-only `[batch,readouts,parameters]` derivatives in `parameters` order |
| `vjp(cotangents)`, `jvp(tangents)` | Products without further circuit execution |
| `circuit_evaluations` | Actually submitted logical circuit rows |
| `submission_batches` | OpenQML backend batch calls |

One stencil uses one backend call when it fits `chunk_size` and provider limits.
A provider can split or bill that call further. Packing does not reduce circuit
rows or guarantee shot-cost savings. Single-occurrence Pauli rotations need
`2P+1` rows per example for `P` selected angles; other recipes count occurrences.

```python
import numpy as np
import openqml as oq

x, w = oq.Parameter("x"), oq.Parameter("w")
circuit = oq.Circuit(1).ry(x * w, 0).rz(w, 0)
plan = oq.ShiftPlan(circuit, [oq.PauliString("Z")], backend="numpy")
linearization = plan.linearize({"x": [0.2, 0.4], "w": 0.3}, chunk_size=64)
targets = np.array([[0.1], [-0.2]])
cotangents = 2 * (linearization.values - targets) / len(targets)
gradient = linearization.vjp(cotangents)
```

## Torch and JAX layers

`gradient_method="batched-shift"` opts an external `QuantumLayer` into this
linearization. Forward includes derivatives for active input and weight
coordinates. First-order backward/JVP operations reuse its Jacobian. Leading
input/weight batches broadcast, and shared gradients reduce to original shapes.
Flax uses the same mode through its JAX quantum layer.

```python
from openqml.qml.interfaces.torch import QuantumLayer


def provider_layer(estimator):
return QuantumLayer(
circuit,
input_parameters=("x",),
weight_parameters=("w",),
backend=oq.QiskitEstimatorBackend(estimator),
gradient_method="batched-shift",
gradient_chunk_size=256,
device="cpu",
)
```

Supply a caller-initialized estimator and use an ordinary Torch/JAX optimizer.
External execution crosses a host boundary; returning a Tensor on a chosen
device does not turn provider execution into a native GPU kernel. Higher quantum
derivatives require a native framework backend and fail explicitly here.

The memory tradeoff is `O(batch * readouts * parameters)`, plus cloned IR rows
and backend buffers. Working-memory admission precedes external submission.
The default `parameter-shift` mode retains streamed products. Batch/microbatch
splitting can create further submissions. A linearization belongs to its
original bindings and lives only in its returned object or current autodiff
residual. Numeric results are never retained in a global cache.

Deterministic backends can reuse equal binding rows. Statistical backends keep
separate rows. Finite-shot derivatives remain statistical estimates; evaluating
nonlinear loss cotangents at noisy forward values can introduce finite-shot bias.
JAX marks nondeterministic provider calls as I/O effects so JIT
cannot erase unused submissions or merge equal calls. Callback errors retain
JAX's runtime error boundary; OpenQML does not replay a failed submission.
Upstream I/O effects propagate through the custom derivative primitive, checked
at the supported JAX floor and current release.

`TrainingWorkload(joint_primal_gradient=True, ...)` models the combined phase.
Queue waves, provider limits, gradient chunks and sequential microbatches still
apply. General layers selecting from configured quotes pass this flag when
batched shifting is requested.

This adopts fixed-stencil job packing from
[Training quantum neural networks one job at a time (November 2026)](https://arxiv.org/abs/2611.16365).
It excludes the paper's sinusoid-search optimizer and does not reproduce its
hardware accuracy or job-count comparisons. Callback behavior follows the
[JAX I/O contract](https://docs.jax.dev/en/latest/_autosummary/jax.experimental.io_callback.html).
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"

[project]
name = "openqml"
version = "0.26.0"
version = "0.27.0"
description = "Quantum-classical hybrid AI, quantitative research and cross-framework quantum programming"
readme = "README.md"
requires-python = ">=3.10"
Expand Down
Loading
Loading