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
9 changes: 5 additions & 4 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ jobs:
- run: python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
- run: python -m pip install . pytest
- run: python -m pytest -q tests/test_contraction_compiler.py tests/test_distributed_compute.py
- run: python -m pytest -q tests/test_hybrid_qnm.py -k distributed_hybrid_qnm
hybrid-quant-compiler:
runs-on: ubuntu-latest
timeout-minutes: 12
Expand All @@ -51,7 +52,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_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
- run: python -m pytest -q tests/test_distance_aware.py tests/test_execution_risk.py tests/test_hybrid_qnm.py tests/test_submission_training.py tests/test_expectile_risk.py tests/test_integer_division.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 +125,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_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
- run: python -m pytest -q tests/test_distance_aware.py tests/test_execution_risk.py tests/test_hybrid_qnm.py 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 +135,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_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
- run: python -m pytest -q tests/test_distance_aware.py tests/test_execution_risk.py tests/test_hybrid_qnm.py 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 +175,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_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_distance_aware.py tests/test_execution_risk.py tests/test_hybrid_qnm.py tests/test_submission_training.py tests/test_expectile_risk.py tests/test_integer_division.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
2 changes: 1 addition & 1 deletion .github/workflows/gpu-integration.yml
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ jobs:
OPENQML_HARDWARE_REPORT_DIR: ${{ runner.temp }}/openqml-hardware
run: python -m pytest -q tests/test_distributed_compute.py -k physical_multi_gpu
- name: Verify resident native quantum geometry
run: python -m pytest -q tests/test_native_geometry.py -k physical_cuda
run: python -m pytest -q tests/test_native_geometry.py tests/test_distance_aware.py -k physical_cuda
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
if: always()
with:
Expand Down
3 changes: 2 additions & 1 deletion MANIFEST.in
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
include README.md LICENSE CONTRIBUTING.md GOVERNANCE.md SECURITY.md CODE_OF_CONDUCT.md
include README.md LICENSE
exclude CONTRIBUTING.md GOVERNANCE.md SECURITY.md CODE_OF_CONDUCT.md
prune tests
prune docs
prune .github
Expand Down
24 changes: 12 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,21 +8,20 @@

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

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.
Train native quantum blocks with resumable, distance-aware Quantum Natural Muon
and classical blocks with AdamW through one `hybrid_qnm` optimizer. Microbatch
accumulation and DDP share an empirical, matrix-free quantum Fisher metric.
External Torch/JAX layers can pack forward and parameter-shift rows into one
provider submission and reuse their linearization during backward.

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

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.
Learn scenario probabilities, Wasserstein radii and anisotropic transport metrics.
`ScenarioPlan.execution_loss` connects proper-score calibration to after-cost
decisions. Exact piecewise quadratic projections fund proportional fees and
market impact while enforcing CVaR or expectile budgets.

## Cross-framework quantum programming

Expand All @@ -31,8 +30,9 @@ 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.
Fixed-width unsigned arithmetic includes division with symbolically proved
nonzero divisors. Correlated selector proofs admit bounded dynamic shifts and
bit indexing while preserving atomic branch selection.

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
12 changes: 12 additions & 0 deletions docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,18 @@ 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.

`DistanceAwareQNM` returns `DistanceAwareResult(step, state, natural, radius,
alignment, restarted)`. `DistanceAwareState` is an explicit native tensor tree.
`hybrid_qnm(model, ...)` creates a Torch optimizer for native unitary
`QuantumLayer` weights and classical parameters. It is also available from
`openqml.autodiff`; importing its factory does not load Torch.

`finance.execution_risk_projection` returns `ExecutionRiskResult`, including
pre-trade positions, post-cost target weights, cash, costs and risk certificates.
`ScenarioPlan.execution_decision` supplies its scenario atoms;
`execution_loss` returns a `ScenarioDecisionResult` containing the decision,
per-example objective, calibration score and realized net return.

`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).
Expand Down
79 changes: 79 additions & 0 deletions docs/finance.md
Original file line number Diff line number Diff line change
Expand Up @@ -554,6 +554,85 @@ over known probabilities is O(S). Compare complete workloads including table
loading, transpilation, error correction, queue time and classical variance
reduction or quasi-Monte-Carlo execution.

## Execution-cost-aware scenario decisions

`execution_risk_projection` finds the largest feasible scale `s` of a funded,
long-only proposal. Unlike a risk-only cash allocation, its constraints include
proportional fees and quadratic market impact from current holdings. For
pre-trade NAV fractions `w` and `previous`, trades are `s*w - previous`, costs
are `C(s)=sum(fees*abs(trades)+impact*trades**2)`, and cash is
`1-s*sum(w)-C(s)`. The CVaR or coherent expectile budget applies to the
**after-cost** loss, including the return on the remaining cash.

```python
import openqml as oq

plan = oq.finance.ScenarioPlan(
[
[-0.12, -0.03],
[0.04, -0.08],
[0.10, 0.02],
[-0.05, 0.01],
]
)
decision = plan.execution_decision(
[0.25, 0.25, 0.25, 0.25],
[0.4, 0.5],
previous=[0.3, 0.2],
fees=0.001,
impact=0.01,
confidence=0.8,
budget=0.015,
radius=0.001,
)
print(decision.weights, decision.cash, decision.costs, decision.robust_risk)
```

`positions`, `cash` and `costs` are fractions of pre-trade NAV and sum to one.
`weights=positions/(1-costs)` are **post-cost** target weights, the units accepted
by `SelfFinancingPlan`. Using `positions` as its target would charge different
trades. CVaR uses `confidence` in `[0,1)`; coherent expectile mode uses
`risk_measure="expectile"` and `confidence` in `[0.5,1)`. An anisotropic
`transport_metric` uses the same native dual-norm operator as the existing
Wasserstein risk layers.

Sorted trade sign changes partition `C(s)` into convex quadratics. Closed-form,
scale-stable quadratic roots locate the binding risk or funding constraint in
O(A log A + S log S) work, with linear workspace for A assets and S scenarios.
There is no optimization-iteration tape or dense asset matrix. Torch/JAX retain
gradients through probabilities, proposals, holdings, costs, radius and transport
parameters, away from active-set, ordering and norm singularities. Zero initial
impact retains its one-sided derivative. Returned risk and funding constraints
are checked against native numerical tolerances.

Both proposal and current holdings must be funded and long-only; fees and
impact must be nonnegative, with `max(fees)+2*max(impact)<1`. Scenarios and cash
returns are arithmetic returns of at least -1. Full liquidation must itself meet
funding and the risk budget. If liquidation is infeasible, the operator raises
`ValidationError`; it does not assume that fees can be borrowed. The feasible
scale interval is convex under these conditions.

For decision-focused hybrid training, call
`plan.execution_loss(probabilities, proposal, observations, ...)`. Its per-example
loss is `calibration_weight*energy_score - decision_weight*realized_net_return`.
Predicted probabilities alone determine the scenario risk decision; observations
enter only the proper calibration score and realized training objective. Native
gradients connect both a quantum Born distribution and a classical allocation
head to this loss. A temporal scenario plan with no `step` describes one initial
trade held over the compounded horizon. Observations and `cash_return` must
refer to that same horizon; `execution_loss` rejects a partial-step decision.

This certifies the supplied discrete model and cost assumptions. Recompute from
marked holdings and current cost estimates at fill time if an execution delay
changes them. Future scenario errors, liquidity and delayed price moves are not
covered by an earlier decision's certificate. No orders are submitted and no
investment-performance or quantum-speedup claim follows from these operators.

The integrated predictive/decision objective follows the direction of
[Financially Guided Deep Portfolio Optimization](https://arxiv.org/abs/2605.28853),
with OpenQML's own exact cash-ray projection. It does not reproduce that paper's
full model or reported market results.

## Method sources

- [Learning Predictive Ambiguity Sets for Decision-Focused Distributionally
Expand Down
63 changes: 63 additions & 0 deletions docs/hybrid-training.md
Original file line number Diff line number Diff line change
Expand Up @@ -150,6 +150,69 @@ topology, chunk equivalence, Torch compile/func transforms and JAX JIT/vmap/Opta
CUDA tests execute when hardware is available. Measure throughput on the target
device with the intended architecture, precision, batch size and execution path.

## Joint AdamW and Quantum Natural Muon

`hybrid_qnm` owns a complete Torch module. Classical parameters use AdamW;
active weights of native, unitary `QuantumLayer` modules use the stateful
distance-aware quantum Fisher method. For example, after constructing a model
with a quantum submodule named `quantum` containing four active weights:

```python
import openqml as oq
from openqml.qml.interfaces.torch import HybridTrainer

optimizer = oq.hybrid_qnm(
model,
lr=1e-3,
quantum_lr=0.02,
block_shapes={"quantum": ((2, 2),)},
quantum_options={"damping": 0.05, "momentum": 0.9},
)
trainer = HybridTrainer(model, optimizer, microbatch_size=16)


def objective(network, batch):
features, targets = batch
return (network(features) - targets).square().mean()


trainer.step((features, targets), objective)
trainer.save("training.pt")
optimizer.close()
```

Only layer calls participating in backward contribute geometry. Unused forward
passes and inference do not enter the empirical metric. Feature snapshots span
all participating calls and microbatches until `step` or `zero_grad`; their
memory is admitted against layer and shared compute budgets. Do not mutate
inputs between forward and backward. This metric uses uniform mass per captured
feature row, independently of loss weighting; repeated uses contribute repeated
rows. Classical layers influence the loss gradient but their full cross-block
Fisher information is not computed.

For `DistributedDataParallel`, construct the optimizer with the wrapped model.
Block-shape keys follow its module names, such as `module.quantum`. Metric-vector
products are reduced with each rank's actual feature-row count. The same global
Fisher system is solved on each rank, without gathering a dense metric.
`HybridTrainer` also weights the objective by global sample count, including
unequal rank sizes. Ranks must execute the same optimizer groups and collectives.
This path uses simulator state derivatives, not finite-shot hardware geometry.

Quantum master weights must use float32 or float64. `HybridTrainer` can use AMP
for the surrounding model, and its existing finite-gradient checks apply before
either optimizer updates. Quantum groups receive no AdamW weight decay; each
group's `lr` supports ordinary schedulers and zero-rate freezing. Spectral shapes
must cover active circuit coordinates in `weight_parameters` order. With no
shape mapping, each quantum vector uses a single-row block, retaining natural
momentum without nontrivial polar redistribution.

`trainer.state_dict()` and its save/load helpers retain classical moments,
quantum momentum, initial coordinates, trajectory distance, counters, scheduler
and random state. Restore into the same circuit and optimizer configuration;
identity is checked before trainer model mutation. Call `optimizer.close()`
when replacing it to remove its hooks. Capturable, differentiable, fused and
maximizing optimizer steps are outside this integration.

## Validation and early stopping

The high-level `Model` interface provides a held-out loss monitor for Torch,
Expand Down
Loading
Loading