diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index cbedd9d..29e1552 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -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: @@ -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: @@ -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 @@ -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() diff --git a/README.md b/README.md index 46990cb..f3346e2 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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 @@ -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). diff --git a/docs/api.md b/docs/api.md index bf397a4..cfda725 100644 --- a/docs/api.md +++ b/docs/api.md @@ -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 diff --git a/docs/finance.md b/docs/finance.md index 627fbf3..e83c014 100644 --- a/docs/finance.md +++ b/docs/finance.md @@ -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 | @@ -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 diff --git a/docs/interoperability.md b/docs/interoperability.md index f88863b..c9e9f19 100644 --- a/docs/interoperability.md +++ b/docs/interoperability.md @@ -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 @@ -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. diff --git a/docs/models.md b/docs/models.md index 6d0b5df..ccb70c2 100644 --- a/docs/models.md +++ b/docs/models.md @@ -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). diff --git a/docs/runtime.md b/docs/runtime.md index 774a0c9..43f2c6b 100644 --- a/docs/runtime.md +++ b/docs/runtime.md @@ -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; diff --git a/docs/submission-training.md b/docs/submission-training.md new file mode 100644 index 0000000..92be684 --- /dev/null +++ b/docs/submission-training.md @@ -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). diff --git a/pyproject.toml b/pyproject.toml index ee50d46..5c7d95e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -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" diff --git a/src/openqml/__init__.py b/src/openqml/__init__.py index db1e3cf..5b991b5 100644 --- a/src/openqml/__init__.py +++ b/src/openqml/__init__.py @@ -8,7 +8,7 @@ _install_aliases() -__version__ = "0.26.0" +__version__ = "0.27.0" __all__ = _PUBLIC diff --git a/src/openqml/__init__.pyi b/src/openqml/__init__.pyi index 116102c..66f0853 100644 --- a/src/openqml/__init__.pyi +++ b/src/openqml/__init__.pyi @@ -21,6 +21,7 @@ from .autodiff import adjoint as adjoint from .autodiff import geometry as geometry from .autodiff import gradients as gradients from .autodiff import optimization as optimization +from .autodiff._linearization import ShiftLinearization as ShiftLinearization from .autodiff.adjoint import AdjointPlan as AdjointPlan from .autodiff.adjoint import adjoint_jvp as adjoint_jvp from .autodiff.adjoint import adjoint_vjp as adjoint_vjp diff --git a/src/openqml/_exports.py b/src/openqml/_exports.py index 8cf2d7a..b0cac6d 100644 --- a/src/openqml/_exports.py +++ b/src/openqml/_exports.py @@ -96,6 +96,7 @@ "QuantumMetricPlan": (".autodiff.geometry", "QuantumMetricPlan"), "quantum_metric": (".autodiff.geometry", "quantum_metric"), "ShiftPlan": (".autodiff.gradients", "ShiftPlan"), + "ShiftLinearization": (".autodiff._linearization", "ShiftLinearization"), "parameter_shift": (".autodiff.gradients", "parameter_shift"), "parameter_shift_jacobian": (".autodiff.gradients", "parameter_shift_jacobian"), "parameter_shift_jvp": (".autodiff.gradients", "parameter_shift_jvp"), @@ -387,6 +388,7 @@ "plan_readout", "AdjointPlan", "ShiftPlan", + "ShiftLinearization", "adjoint_vjp", "adjoint_jvp", "ConversionPlan", diff --git a/src/openqml/autodiff/_linearization.py b/src/openqml/autodiff/_linearization.py new file mode 100644 index 0000000..1d18cf5 --- /dev/null +++ b/src/openqml/autodiff/_linearization.py @@ -0,0 +1,105 @@ +"""Explicit, per-evaluation linearizations for submission-aware quantum training.""" + +from dataclasses import dataclass +from itertools import chain, islice + +import numpy as np + +from ..compute.kernel import compute_operation, get_compute_kernel +from ..errors import ValidationError +from ..ir.core import integer +from ._common import _real_array + + +@dataclass(frozen=True) +class ShiftLinearization: + """Owned read-only primal/Jacobian arrays; products submit no further circuits. + + A linearization is valid at its original bindings only. Submission batches + count backend calls, not a provider's internal jobs or billed shot usage. + """ + + values: np.ndarray + jacobian: np.ndarray + parameters: tuple[str, ...] + circuit_evaluations: int + submission_batches: int + + @compute_operation + def vjp(self, cotangents): + value = _real_array(cotangents, self.values.shape, "Cotangents") + return _finite_product("bm,bmp->bp", value, self.jacobian) + + @compute_operation + def jvp(self, tangents): + shape = (self.values.shape[0], len(self.parameters)) + value = _real_array(tangents, shape, "Tangents") + return _finite_product("bmp,bp->bm", self.jacobian, value) + + +def _finite_product(equation, *values): + result = get_compute_kernel().einsum(equation, *values) + if not np.isfinite(result).all(): + raise ValidationError("Shift products exceed finite real precision.") + return result + + +@compute_operation +def linearize(plan, bindings, *, parameters=None, chunk_size=64, batch_size=None, **options): + """Pack primal rows and occurrence-wise shift stencils before reading results.""" + from ..sim.batch import expectations_batch + from .gradients import _coefficient, _recipe + + size = integer(chunk_size, "chunk_size", 2) + names, occurrences = plan._selection(parameters) + options = plan._options(options) + backend = plan._backend() + columns, count = plan._bindings(bindings, batch_size) + maximum = count * (1 + plan.shift_evaluations) + # Include the explicit Jacobian, numeric results and bounded cloned IR rows. + width = len(plan.observables) + objects = min(size, maximum) * (1 + sum(1 for _ in plan.lowered_circuit.walk_operations())) + get_compute_kernel().admit( + count * width * (1 + len(names)) + min(size, maximum) * width + 32 * objects, + options["max_memory_mb"], + ) + # A valid primal can still have an undefined derivative (e.g. damping=1 or + # sqrt at zero). Check every selected occurrence before charging any job. + for members in plan._groups(columns, count): + row = {name: columns[name][members[0]] for name in plan._lowered_symbols} + bound = None + for occurrence, partials in occurrences: + coefficients = tuple(_coefficient(expr, row) for _, expr in partials) + if not any(coefficients): + continue + if bound is None: + bound = plan.lowered_circuit.bind(row) + operation = bound.operation_at(occurrence.path) + _recipe(occurrence.gate, operation.params[occurrence.parameter_index].constant) + values = np.empty((count, width)) + jacobian = np.zeros((count, width, len(names))) + + def primals(): + for members in plan._groups(columns, count): + row = {name: columns[name][members[0]] for name in plan._lowered_symbols} + yield np.asarray(members), None, 1, plan.lowered_circuit.bind(row) + + tasks = iter(chain(primals(), plan._tasks(columns, count, occurrences, "jacobian", None))) + evaluations = submissions = 0 + while group := list(islice(tasks, size)): + output = expectations_batch( + [job for _, _, _, job in group], plan.observables, backend=backend, **options + ) + submissions += 1 + evaluations += len(group) + for value, (rows, coefficients, weight, _) in zip(output, group, strict=True): + if coefficients is None: + values[rows] = value + else: + for position, coefficient in coefficients: + jacobian[rows, :, position] += coefficient * weight * value + if not np.isfinite(values).all() or not np.isfinite(jacobian).all(): + raise ValidationError("Shift linearization exceeds finite real precision.") + values.setflags(write=False) + jacobian.setflags(write=False) + return ShiftLinearization(values, jacobian, names, evaluations, submissions) diff --git a/src/openqml/autodiff/gradients.py b/src/openqml/autodiff/gradients.py index de5669e..66e2afa 100644 --- a/src/openqml/autodiff/gradients.py +++ b/src/openqml/autodiff/gradients.py @@ -366,6 +366,24 @@ def jacobian(self, bindings, *, parameters=None, chunk_size=64, batch_size=None, columns, count, occurrences, "jacobian", None, result, chunk_size, options ) + def linearize(self, bindings, *, parameters=None, chunk_size=64, batch_size=None, **options): + """Evaluate primal and a bounded explicit Jacobian in shared submission batches. + + This opts into O(batch*readouts*parameters) storage to avoid a second + provider round trip when loss cotangents become available. A whole + stencil is one submission only when it fits chunk_size/provider limits. + """ + from ._linearization import linearize + + return linearize( + self, + bindings, + parameters=parameters, + chunk_size=chunk_size, + batch_size=batch_size, + **options, + ) + def vjp( self, bindings, cotangents, *, parameters=None, chunk_size=64, batch_size=None, **options ): diff --git a/src/openqml/finance/__init__.pyi b/src/openqml/finance/__init__.pyi index 2905a69..aa56993 100644 --- a/src/openqml/finance/__init__.pyi +++ b/src/openqml/finance/__init__.pyi @@ -4,6 +4,10 @@ from .allocation import AllocationResult as AllocationResult from .api import allocate as allocate from .api import price as price from .barrier import BarrierOption as BarrierOption +from .budget import ExpectileBudgetResult as ExpectileBudgetResult +from .budget import expectile_budget_projection as expectile_budget_projection +from .expectiles import expectile as expectile +from .expectiles import wasserstein_expectile as wasserstein_expectile from .models import MarketForecast as MarketForecast from .models import MarketForecastPlan as MarketForecastPlan from .models import ScenarioPlan as ScenarioPlan diff --git a/src/openqml/finance/_exports.py b/src/openqml/finance/_exports.py index b1a9a9a..e14016e 100644 --- a/src/openqml/finance/_exports.py +++ b/src/openqml/finance/_exports.py @@ -1,6 +1,10 @@ """Lazy financial API locations.""" EXPORTS = { + "expectile": (".expectiles", "expectile"), + "wasserstein_expectile": (".expectiles", "wasserstein_expectile"), + "ExpectileBudgetResult": (".budget", "ExpectileBudgetResult"), + "expectile_budget_projection": (".budget", "expectile_budget_projection"), "WassersteinMetric": (".transport", "WassersteinMetric"), "transport_dual_norm": (".transport", "transport_dual_norm"), "BarrierOption": (".barrier", "BarrierOption"), @@ -40,6 +44,10 @@ } PUBLIC = [ + "expectile", + "wasserstein_expectile", + "ExpectileBudgetResult", + "expectile_budget_projection", "WassersteinMetric", "transport_dual_norm", "BarrierOption", diff --git a/src/openqml/finance/budget.py b/src/openqml/finance/budget.py index b131a48..d09e608 100644 --- a/src/openqml/finance/budget.py +++ b/src/openqml/finance/budget.py @@ -19,6 +19,15 @@ class RiskBudgetResult(NamedTuple): budget: object +class ExpectileBudgetResult(NamedTuple): + weights: object + cash: object + scale: object + expectile: object + robust_expectile: object + budget: object + + def risk_budget_projection( weights, scenarios, @@ -32,6 +41,68 @@ def risk_budget_projection( transport_metric=None, metric_iterations=128, metric_tolerance=1e-6, +): + """Maximal funded cash-ray scaling under the weighted robust CVaR bound.""" + return _project( + weights, + scenarios, + probabilities=probabilities, + confidence=confidence, + budget=budget, + radius=radius, + cash_return=cash_return, + max_memory_mb=max_memory_mb, + transport_metric=transport_metric, + metric_iterations=metric_iterations, + metric_tolerance=metric_tolerance, + ) + + +def expectile_budget_projection( + weights, + scenarios, + *, + probabilities=None, + level=0.95, + budget=0.02, + radius=0, + cash_return=0, + max_memory_mb=256, + transport_metric=None, + metric_iterations=128, + metric_tolerance=1e-6, +): + """Maximal funded cash-ray scaling under an unrestricted-support W1 expectile.""" + return _project( + weights, + scenarios, + probabilities=probabilities, + confidence=level, + budget=budget, + radius=radius, + cash_return=cash_return, + max_memory_mb=max_memory_mb, + transport_metric=transport_metric, + metric_iterations=metric_iterations, + metric_tolerance=metric_tolerance, + risk_measure="expectile", + ) + + +def _project( + weights, + scenarios, + *, + probabilities=None, + confidence=0.95, + budget=0.02, + radius=0, + cash_return=0, + max_memory_mb=256, + transport_metric=None, + metric_iterations=128, + metric_tolerance=1e-6, + risk_measure="cvar", ): """Scale a funded long-only proposal toward cash to meet its CVaR bound. @@ -95,8 +166,14 @@ def risk_budget_projection( bound + cash_rate, bound + cash_rate >= 0, "The risk budget must admit the cash position." ) incremental = cash_rate[..., None] * total[..., None] - ops.einsum("...sn,...n->...s", r, w) - base_cvar = expected_shortfall(incremental, confidence=confidence, probabilities=p) - robust = base_cvar + radius * dual / (1 - confidence) + if risk_measure == "expectile": + from .expectiles import _expectile_root + + base_risk = _expectile_root(incremental, confidence, p, 0, max_memory_mb) + robust = _expectile_root(incremental, confidence, p, radius * dual, max_memory_mb) + else: + base_risk = expected_shortfall(incremental, confidence=confidence, probabilities=p) + robust = base_risk + radius * dual / (1 - confidence) safe_denominator = ops.xp.where(robust > target, robust, ops.array(1)) scale = ops.xp.where(robust > target, target / safe_denominator, ops.array(1)) scale = ops.check( @@ -105,11 +182,12 @@ def risk_budget_projection( "Risk-budget inputs must define finite admissible risk and cash bounds.", ) projected = w * scale[..., None] - return RiskBudgetResult( + result_type = ExpectileBudgetResult if risk_measure == "expectile" else RiskBudgetResult + return result_type( projected, ops.xp.maximum(1 - ops.sum(projected), ops.array(0)), scale, - -cash_rate + scale * base_cvar, + -cash_rate + scale * base_risk, -cash_rate + scale * robust, bound, ) diff --git a/src/openqml/finance/expectiles.py b/src/openqml/finance/expectiles.py new file mode 100644 index 0000000..0e679ec --- /dev/null +++ b/src/openqml/finance/expectiles.py @@ -0,0 +1,106 @@ +"""Sorted native expectile roots and unrestricted-support W1 portfolio risk.""" + +from ..errors import NumericalError, ValidationError +from ..ir.parameters import real +from ._array import Ops, admission, rows +from .transport import _metric_values, transport_dual_norm + + +def _expectile_root(losses, level, probabilities, margin, max_memory_mb): + level = real(level) + if not 0.5 <= level < 1: + raise ValidationError("Coherent expectile levels must be in [0.5,1).") + ops = Ops(losses, probabilities, margin) + losses, margin = ops.real(losses), ops.real(margin) + if losses.ndim < 1 or losses.shape[-1] < 1: + raise ValidationError("Expectiles require a nonempty scenario axis.") + margin = ops.check(margin, margin >= 0, "Expectile transport margins must be nonnegative.") + size = losses.shape[-1] + admission(40 * rows(losses.shape), max_memory_mb) + p = ops.probabilities(probabilities, size) + prefix = ops.broadcast_shape(losses.shape[:-1], p.shape[:-1], margin.shape) + admission(40 * rows(prefix) * size, max_memory_mb) + losses, p = (ops.broadcast(v, prefix + (size,)) for v in (losses, p)) + margin = ops.broadcast(margin, prefix) + order = ops.argsort(losses) + ordered, mass = ops.gather(losses, order), ops.gather(p, order) + + def flip(v): + return ops.xp.flip(v, dims=(-1,)) if ops.name == "torch" else ops.xp.flip(v, axis=-1) + + def suffix(v): + return ops.cat((flip(ops.cumsum(flip(v)))[..., 1:], ops.xp.zeros_like(v[..., :1])), axis=-1) + + below, above = ops.cumsum(mass), suffix(mass) + lower_sum, upper_sum = ops.cumsum(mass * ordered), suffix(mass * ordered) + denominator = (1 - level) * below + level * above + # Normalize the coefficients first: multiplying a subnormal loss by + # 1-level before dividing would lose it. No global loss scale is needed, + # so zero-mass extreme atoms cannot underflow the contributing observations. + lower_weight, upper_weight = (1 - level) / denominator, level / denominator + candidates = ( + lower_weight * lower_sum + upper_weight * upper_sum + upper_weight * margin[..., None] + ) + # The increasing piecewise-affine root lies above min(loss) for level>=1/2. + # The first interval whose upper endpoint admits its candidate is the root. + eligible = ops.cat( + (candidates[..., :-1] <= ordered[..., 1:], ops.xp.ones_like(ordered[..., :1], dtype=bool)), + axis=-1, + ) + index = ( + eligible.to(ops.xp.int64).argmax(dim=-1, keepdim=True) + if ops.name == "torch" + else ops.xp.argmax(eligible, axis=-1)[..., None] + ) + root = ops.gather(candidates, index)[..., 0] + return ops.check( + root, + ops.xp.isfinite(root), + "Expectile risk exceeds finite precision.", + error=NumericalError, + ) + + +def expectile(losses, *, level=0.95, probabilities=None, max_memory_mb=256): + """Coherent weighted expectile, with exact sorted roots and native derivatives. + + The level is an asymmetric-loss weight, not a quantile confidence or tail + probability. Derivatives are piecewise smooth away from active-set changes. + """ + return _expectile_root(losses, level, probabilities, 0, max_memory_mb) + + +def wasserstein_expectile( + weights, + scenarios, + *, + level=0.95, + probabilities=None, + radius=0, + transport_metric=None, + max_memory_mb=256, + cg_iterations=128, + tolerance=1e-6, +): + """Worst-case loss expectile over an unrestricted-support W1 ambiguity ball. + + Solve level*E[(L-q)+] -(1-level)*E[(q-L)+] + level*radius*dual_norm(w)=0. + This bound is conservative for constrained supports or additional moments. + """ + ops = Ops(weights, scenarios, probabilities, radius, *_metric_values(transport_metric)) + w, r, radius = ops.real(weights), ops.real(scenarios), ops.real(radius) + if w.ndim < 1 or r.ndim < 2 or r.shape[-1] != w.shape[-1] or min(r.shape[-2:]) < 1: + raise ValidationError("Portfolio and scenario asset axes must match and be nonempty.") + radius = ops.check(radius, radius >= 0, "Wasserstein radii must be nonnegative.") + p = ops.probabilities(probabilities, r.shape[-2]) + dual = transport_dual_norm( + w, + transport_metric, + max_memory_mb=max_memory_mb, + cg_iterations=cg_iterations, + tolerance=tolerance, + ) + prefix = ops.broadcast_shape(w.shape[:-1], r.shape[:-2], p.shape[:-1], radius.shape, dual.shape) + admission(rows(prefix) * (4 * rows(r.shape[-2:]) + 40 * r.shape[-2]), max_memory_mb) + losses = -ops.einsum("...sn,...n->...s", r, w) + return _expectile_root(losses, level, p, radius * dual, max_memory_mb) diff --git a/src/openqml/interop/adapters/_classical_predicate.py b/src/openqml/interop/adapters/_classical_predicate.py index 3455071..75af158 100644 --- a/src/openqml/interop/adapters/_classical_predicate.py +++ b/src/openqml/interop/adapters/_classical_predicate.py @@ -92,10 +92,74 @@ def truth(self, bits): return value +class _BitVectors: + """Fixed-width unsigned circuits, built from canonical Boolean operations.""" + + def __init__(self, bdd): + self.bdd = bdd + + def add(self, left, right, *, subtract=False): + self.bdd.charge(len(left)) + carry, result = int(subtract), [] + for a, b in zip(left, right, strict=True): + if subtract: + b = self.bdd.apply("xor", b, 1) + parity = self.bdd.apply("xor", a, b) + result.append(self.bdd.apply("xor", parity, carry)) + carry = self.bdd.apply( + "or", self.bdd.apply("and", a, b), self.bdd.apply("and", parity, carry) + ) + return tuple(result) # Discard the carry: Uint arithmetic is modulo 2**width. + + def multiply(self, left, right): + size = len(left) + self.bdd.charge(size * size) + result = (0,) * size + for index, bit in enumerate(right): + if bit == 0: + continue + row = (0,) * index + tuple(self.bdd.apply("and", bit, a) for a in left[: size - index]) + result = self.add(result, row) + return result + + def shift(self, bits, amount, *, left=False, index=False): + size = len(bits) + maximum = 0 + for i, bit in enumerate(amount): + if bit == 0: + continue + if i >= size.bit_length() or maximum + (1 << i) >= size: + raise conversion_error( + "CLASSICAL_INDEX_RANGE" if index else "CLASSICAL_SHIFT_RANGE", + "Every possible index/shift must be provably inside its operand width.", + self.bdd.location, + ) + maximum += 1 << i + self.bdd.charge(size * len(amount)) + for i, control in enumerate(amount): + if control == 0: + continue + step = 1 << i + shifted = (0,) * step + bits[: size - step] if left else bits[step:] + (0,) * step + if control == 1: + bits = shifted + else: + bits = tuple( + self.bdd.apply( + "xor", a, self.bdd.apply("and", control, self.bdd.apply("xor", a, b)) + ) + for a, b in zip(bits, shifted, strict=True) + ) + return bits + + def _compile(value, native, bdd): from qiskit.circuit import ClassicalRegister, Clbit from qiskit.circuit.classical import expr, types + vectors = _BitVectors(bdd) + index_type = getattr(expr, "Index", ()) + def fail(message): raise conversion_error("CLASSICAL_EXPRESSION", message, bdd.location) @@ -145,6 +209,8 @@ def expand(bits, count): descendants[identity] = ( (current.left, current.right) if isinstance(current, expr.Binary) + else (current.target, current.index) + if isinstance(current, index_type) else (current.operand,) if isinstance(current, (expr.Unary, expr.Cast)) else () @@ -157,7 +223,9 @@ def expand(bits, count): pending.extend((child, False, depth + 1) for child in children if id(child) not in memo) continue left = memo[id(children[0])] - if isinstance(current, expr.Cast): + if isinstance(current, index_type): + result = (vectors.shift(left, memo[id(children[1])], index=True)[0],) + elif isinstance(current, expr.Cast): result = ( (bdd.truth(left),) if isinstance(current.type, types.Bool) else expand(left, size) ) @@ -171,7 +239,16 @@ def expand(bits, count): else: right = memo[id(children[1])] op = current.op.name - if op in {"BIT_AND", "BIT_OR", "BIT_XOR"}: + if op in {"ADD", "SUB", "MUL"}: + a, b = expand(left, size), expand(right, size) + result = ( + vectors.multiply(a, b) + if op == "MUL" + else vectors.add(a, b, subtract=op == "SUB") + ) + elif op in {"SHIFT_LEFT", "SHIFT_RIGHT"}: + result = vectors.shift(expand(left, size), right, left=op == "SHIFT_LEFT") + elif op in {"BIT_AND", "BIT_OR", "BIT_XOR"}: operation = op.removeprefix("BIT_").lower() result = tuple( bdd.apply(operation, a, b) diff --git a/src/openqml/qml/interfaces/_jax_stencil.py b/src/openqml/qml/interfaces/_jax_stencil.py new file mode 100644 index 0000000..7404d6e --- /dev/null +++ b/src/openqml/qml/interfaces/_jax_stencil.py @@ -0,0 +1,89 @@ +"""JAX first-order linearization with a shared primal/parameter-shift callback.""" + +from functools import partial + +import jax +import jax.numpy as jnp +import numpy as np +from jax.extend import core +from jax.interpreters import ad, batching, mlir + +from ._jax_ad import _callback, _lower, _no_higher, _promote +from ._spec import broadcast_batch_shape + + +def _impure(layer): + backend = layer.shift_plan._execution_backend + return not isinstance(backend, str) and not backend.capabilities.deterministic_expectations + + +def _impl(weights, inputs, *, layer): + from ._spec import numeric_linearization + + shape = broadcast_batch_shape(weights, inputs) + (len(layer.observables),) + columns = len(layer.input_parameters) + len(layer.weight_parameters) + specs = ( + jax.ShapeDtypeStruct(shape, inputs.dtype), + jax.ShapeDtypeStruct(shape + (columns,), inputs.dtype), + ) + + def callback(w, x): + return tuple(np.asarray(v, dtype=x.dtype) for v in numeric_linearization(layer, w, x)) + + if _impure(layer): + from jax.experimental import io_callback + + return io_callback(callback, specs, weights, inputs, ordered=False) + return _callback(callback, specs, weights, inputs, vmap_method="sequential") + + +_linearization = core.Primitive("openqml_batched_shift_linearization") +_linearization.multiple_results = True +_linearization.def_impl(_impl) + + +@_linearization.def_effectful_abstract_eval +def _abstract(w, x, *, layer): + shape = broadcast_batch_shape(w, x) + (len(layer.observables),) + columns = len(layer.input_parameters) + len(layer.weight_parameters) + # Propagate the same upstream I/O effect as io_callback through this custom + # derivative boundary. Pure callbacks could erase or merge charged/noisy jobs. + from jax._src.callback import _IOEffect + + return [ + jax.core.ShapedArray(shape, x.dtype), + jax.core.ShapedArray(shape + (columns,), x.dtype), + ], ({_IOEffect} if _impure(layer) else set()) + + +mlir.register_lowering(_linearization, _lower(_impl, multiple=True)) +ad.primitive_jvps[_linearization] = _no_higher + + +def _batch(args, dimensions, *, layer): + values, _, _ = _promote(args, dimensions) + return _linearization.bind(*values, layer=layer), (0, 0) + + +batching.primitive_batchers[_linearization] = _batch + + +@partial(jax.custom_jvp, nondiff_argnums=(0,)) +def batched_shift_call(layer, weights, inputs): + return _linearization.bind(weights, inputs, layer=layer)[0] + + +@batched_shift_call.defjvp +def _jvp(layer, primals, tangents): + weights, inputs = primals + values, jacobian = _linearization.bind(weights, inputs, layer=layer) + shape = broadcast_batch_shape(weights, inputs) + dw, dx = tangents + direction = jnp.concatenate( + ( + jnp.broadcast_to(dx, shape + (dx.shape[-1],)), + jnp.broadcast_to(dw, shape + (dw.shape[-1],)), + ), + axis=-1, + ) + return values, jnp.einsum("...mp,...p->...m", jacobian, direction) diff --git a/src/openqml/qml/interfaces/_spec.py b/src/openqml/qml/interfaces/_spec.py index 17921d7..7e5b79e 100644 --- a/src/openqml/qml/interfaces/_spec.py +++ b/src/openqml/qml/interfaces/_spec.py @@ -1,12 +1,20 @@ from collections.abc import Mapping -from ...compute.kernel import _broadcast_shape +from ...compute.kernel import _broadcast_shape, get_compute_kernel from ...errors import ValidationError from ..layers import LayerCheckpoint, LayerSpec, validate_layer def default_layer_backend( - circuit, observables, backend, native, *, native_contract, limits, gradient_chunk_size=64 + circuit, + observables, + backend, + native, + *, + native_contract, + limits, + gradient_chunk_size=64, + gradient_method="auto", ): """Compare configured QPU quotes against native training work before pinning. @@ -39,6 +47,8 @@ def default_layer_backend( runtime.workload.gradient_evaluations, shifts.gradient_evaluations ), native_gradient_evaluations=1, + joint_primal_gradient=gradient_method == "batched-shift", + gradient_chunk_size=gradient_chunk_size, submission_batch_size=min( gradient_chunk_size, runtime.workload.submission_batch_size or gradient_chunk_size ), @@ -372,8 +382,15 @@ def prepare_execution( def resolve_gradient_method(circuit, backend, method, limits): """Keep native graphs by default; adjoint is an explicit NumPy simulator choice.""" - if not isinstance(method, str) or method not in {"auto", "parameter-shift", "adjoint"}: - raise ValidationError("gradient_method must be auto, parameter-shift or adjoint.") + if not isinstance(method, str) or method not in { + "auto", + "parameter-shift", + "batched-shift", + "adjoint", + }: + raise ValidationError( + "gradient_method must be auto, parameter-shift, batched-shift or adjoint." + ) native = isinstance(backend, str) and backend in {"torch", "jax"} if method == "auto": return "backprop" if native else "parameter-shift" @@ -450,7 +467,7 @@ def prepare_gradients(layer): layer.limits["max_qubits"], layer.limits["max_memory_mb"], ), None - if layer.gradient_method == "parameter-shift": + if layer.gradient_method in {"parameter-shift", "batched-shift"}: from ...autodiff.gradients import ShiftPlan plan = ShiftPlan( @@ -483,6 +500,27 @@ def numeric_columns(layer, weights, inputs): return columns, count +def numeric_linearization(layer, weights, inputs): + """Pack one primal/stencil stream, scattering columns to full source ownership.""" + import numpy as np + + columns, count = numeric_columns(layer, weights, inputs) + names = layer.input_parameters + layer.weight_parameters + get_compute_kernel().admit( + count * len(layer.observables) * (len(names) + len(layer.shift_plan.parameters) + 2), + layer.limits["max_memory_mb"], + ) + result = layer.shift_plan.linearize( + columns, batch_size=count, chunk_size=layer.gradient_chunk_size + ) + jacobian = np.zeros((count, len(layer.observables), len(names))) + positions = {name: i for i, name in enumerate(names)} + for source, name in enumerate(result.parameters): + jacobian[..., positions[name]] = result.jacobian[..., source] + shape = broadcast_batch_shape(weights, inputs) + (len(layer.observables),) + return result.values.reshape(shape), jacobian.reshape(shape + (len(names),)) + + def numeric_expectations(layer, weights, inputs): if layer.adjoint_plan is not None: columns, count = numeric_columns(layer, weights, inputs) diff --git a/src/openqml/qml/interfaces/_torch_stencil.py b/src/openqml/qml/interfaces/_torch_stencil.py new file mode 100644 index 0000000..07f4ecf --- /dev/null +++ b/src/openqml/qml/interfaces/_torch_stencil.py @@ -0,0 +1,70 @@ +"""First-order Torch transforms using one explicit quantum stencil per primal.""" + +import numpy as np +import torch + +from ._spec import broadcast_batch_shape +from ._torch_ad import _batch_values, _NumericalProduct, _numpy + + +class _CachedVJP(_NumericalProduct): + generate_vmap_rule = True + + @staticmethod + def forward(jacobian, cotangents, inputs, weights): + product = torch.einsum("...mp,...m->...p", jacobian, cotangents) + size = inputs.shape[-1] + return ( + product[..., :size].sum_to_size(inputs.shape), + product[..., size:].sum_to_size(weights.shape), + ) + + +class _CachedJVP(_NumericalProduct): + generate_vmap_rule = True + + @staticmethod + def forward(jacobian, inputs, weights, dx, dw): + shape = broadcast_batch_shape(weights, inputs) + direction = torch.cat( + (dx.expand(shape + (dx.shape[-1],)), dw.expand(shape + (dw.shape[-1],))), dim=-1 + ) + return torch.einsum("...mp,...p->...m", jacobian, direction) + + +class BatchedShiftFunction(torch.autograd.Function): + @staticmethod + def forward(inputs, weights, layer): + from ._spec import numeric_linearization + + values, jacobian = numeric_linearization(layer, _numpy(weights), _numpy(inputs)) + return tuple( + torch.tensor(np.asarray(v), dtype=inputs.dtype, device=inputs.device) + for v in (values, jacobian) + ) + + @staticmethod + def setup_context(ctx, inputs, output): + values, weights, _ = inputs + _, jacobian = output + ctx.mark_non_differentiable(jacobian) + ctx.save_for_backward(values, weights, jacobian) + ctx.save_for_forward(values, weights, jacobian) + + @staticmethod + def backward(ctx, cotangents, _jacobian_cotangents): + inputs, weights, jacobian = ctx.saved_tensors + dx, dw = _CachedVJP.apply(jacobian, cotangents, inputs, weights) + return dx, dw, None + + @staticmethod + def jvp(ctx, dx, dw, _layer_tangent): + inputs, weights, jacobian = ctx.saved_tensors + dx = torch.zeros_like(inputs) if dx is None else dx + dw = torch.zeros_like(weights) if dw is None else dw + return _CachedJVP.apply(jacobian, inputs, weights, dx, dw), None + + @staticmethod + def vmap(info, in_dims, inputs, weights, layer): + values, _ = _batch_values(info.batch_size, in_dims[:2], (inputs, weights)) + return BatchedShiftFunction.apply(*values, layer), (0, 0) diff --git a/src/openqml/qml/interfaces/jax.py b/src/openqml/qml/interfaces/jax.py index 48a5369..81acca5 100644 --- a/src/openqml/qml/interfaces/jax.py +++ b/src/openqml/qml/interfaces/jax.py @@ -45,6 +45,8 @@ class QuantumLayer(LayerSpecMixin): optimize=True preserves source ownership and returns zero gradients for eliminated symbols. circuit is executable IR; optimization holds the report. gradient_method='auto' retains native autodiff or numerical parameter shifts. + gradient_method='batched-shift' packs primal and derivatives together, + retaining a memory-admitted explicit Jacobian for the current forward call. NumPy unitary simulation also supports explicit first-order adjoint gradients. External backends support standard jvp/vjp, jacfwd/jacrev, vmap and fixed-point linearize/linear_transpose. Nonlinear higher derivatives require native JAX. @@ -105,6 +107,7 @@ def __init__( backend, "jax", gradient_chunk_size=integer(gradient_chunk_size, "gradient_chunk_size", 2), + gradient_method=gradient_method, native_contract=reduce_readout or execution_method != "auto" or checkpoint_interval is not None, @@ -272,6 +275,10 @@ def __call__(self, weights, inputs): ) return result.reshape(shape + (len(self.observables),)) if self.execution_backend != "jax": + if self.gradient_method == "batched-shift": + from ._jax_stencil import batched_shift_call + + return batched_shift_call(self, weights, inputs) return _external_layer(self, weights, inputs) bindings = { name: inputs[..., i] diff --git a/src/openqml/qml/interfaces/torch.py b/src/openqml/qml/interfaces/torch.py index 1fd6264..29382f9 100644 --- a/src/openqml/qml/interfaces/torch.py +++ b/src/openqml/qml/interfaces/torch.py @@ -46,6 +46,8 @@ class QuantumLayer(LayerSpecMixin, nn.Module): External backends support torch.func jvp/vjp, jacfwd/jacrev and vmap. Products stream without a full Jacobian; nonlinear higher derivatives require native PyTorch execution. + gradient_method='batched-shift' packs primal and derivatives together, + retaining a memory-admitted explicit Jacobian for the current forward call. reduce_readout=True compacts the declared unitary readout cone; readout_plan records provenance, while to_spec()/checkpoint() retain the full source. execution_method='pauli' compiles exact real expectation arithmetic with @@ -109,6 +111,7 @@ def __init__( backend, "torch", gradient_chunk_size=integer(gradient_chunk_size, "gradient_chunk_size", 2), + gradient_method=gradient_method, native_contract=reduce_readout or execution_method != "auto" or checkpoint_interval is not None, @@ -308,6 +311,12 @@ def functional(self, weights, inputs): .to(output_dtype) ) if self.execution_backend != "torch": + if self.gradient_method == "batched-shift": + from ._torch_stencil import BatchedShiftFunction + + return BatchedShiftFunction.apply(inputs, computation_weights, self)[0].to( + output_dtype + ) return _ExternalQuantumFunction.apply(inputs, computation_weights, self).to( output_dtype ) diff --git a/src/openqml/runtime/costs.py b/src/openqml/runtime/costs.py index 81da0a7..5a93d9b 100644 --- a/src/openqml/runtime/costs.py +++ b/src/openqml/runtime/costs.py @@ -36,8 +36,11 @@ class TrainingWorkload: execution_batches: tuple | None = None classical_seconds_per_step: float = 0 classical_cost_per_step: float = 0 + joint_primal_gradient: bool = False def __post_init__(self): + if type(self.joint_primal_gradient) is not bool: + raise ValidationError("joint_primal_gradient must be a boolean.") if self.batch_size is not None: object.__setattr__(self, "batch_size", integer(self.batch_size, "batch_size", 1)) object.__setattr__(self, "steps", integer(self.steps, "steps", 1)) @@ -352,8 +355,12 @@ def phase(count, chunk=None): for size, repeats in segments: if not repeats: continue - forward = phase(size) - gradient = phase(size * gradient_count, work.gradient_chunk_size) + if work.joint_primal_gradient: + forward = phase(size * (1 + gradient_count), work.gradient_chunk_size) + gradient = (0,) * 5 + else: + forward = phase(size) + gradient = phase(size * gradient_count, work.gradient_chunk_size) for i, (a, b) in enumerate(zip(forward, gradient, strict=True)): totals[i] += (a + b) * repeats * work.steps wall, cost, count, physical, jobs = totals diff --git a/tests/test_classical_arithmetic.py b/tests/test_classical_arithmetic.py new file mode 100644 index 0000000..7f29163 --- /dev/null +++ b/tests/test_classical_arithmetic.py @@ -0,0 +1,143 @@ +"""Exhaustive finite-width arithmetic and dynamic selector semantics.""" + +import numpy as np +import pytest + +import openqml as oq + + +def _sdk(): + qiskit = pytest.importorskip("qiskit") + from qiskit.circuit.classical import expr, types + + if not all(hasattr(expr, name) for name in ("add", "sub", "mul", "index")): + pytest.skip("The installed Qiskit predates typed arithmetic/index expressions.") + return qiskit, expr, types + + +@pytest.mark.parametrize("kind", ["add", "sub", "mul", "left", "right", "index", "nested"]) +def test_register_arithmetic_is_modular_and_branch_selection_precedes_writes(kind): + qiskit, expr, types = _sdk() + for a in range(4): + for b in range(4): + ar, br = qiskit.ClassicalRegister(2, "a"), qiskit.ClassicalRegister(2, "b") + source = qiskit.QuantumCircuit(qiskit.QuantumRegister(5), ar, br) + for i in range(4): + if ((a | (b << 2)) >> i) & 1: + source.x(i) + source.measure(i, i) + amount = expr.cast(br[0], types.Uint(1)) + if kind == "add": + predicate = expr.less(expr.add(ar, br), 2) + expected = (a + b) % 4 < 2 + elif kind == "sub": + predicate = expr.equal(expr.sub(ar, br), 3) + expected = (a - b) % 4 == 3 + elif kind == "mul": + predicate = expr.equal(expr.mul(ar, br), 2) + expected = (a * b) % 4 == 2 + elif kind == "left": + predicate = expr.equal(expr.shift_left(ar, amount), 2) + expected = (a << (b & 1)) % 4 == 2 + elif kind == "right": + predicate = expr.equal(expr.shift_right(ar, amount), 1) + expected = a >> (b & 1) == 1 + elif kind == "index": + predicate = expr.index(ar, amount) + expected = bool((a >> (b & 1)) & 1) + else: + predicate = ( + expr.logic_xor(expr.equal(ar, br), expr.equal(ar, 0)) + if hasattr(expr, "logic_xor") + else expr.bit_xor(expr.equal(ar, br), expr.equal(ar, 0)) + ) + predicate = expr.logic_and( + predicate, expr.not_equal(expr.mul(expr.add(ar, 1), br), 0) + ) + expected = ((a == b) != (a == 0)) and ((a + 1) * b) % 4 != 0 + with source.if_test(predicate) as otherwise: + source.x(4) + source.measure(4, 0) + source.measure(4, 2) + with otherwise: + source.z(4) + source.measure(4, 0) + source.measure(4, 2) + original = source.copy() + ir = oq.convert(source, target="ir").value + assert source == original + want = -1 if expected else 1 + obs = oq.PauliString("IIIIZ") + assert oq.expectation(ir, obs) == pytest.approx(want, abs=2e-12), (kind, a, b) + qasm = oq.convert(ir, target="openqasm3").value + back = oq.convert(qasm, source="openqasm3", target="ir").value + assert oq.expectation(back, obs) == pytest.approx(want, abs=2e-12) + + +def test_provable_index_and_shift_ranges_and_expanded_work_have_bounded_diagnostics(): + qiskit, expr, types = _sdk() + source = qiskit.QuantumCircuit(1, 2) + for predicate in ( + expr.index(source.cregs[0], 2), + expr.equal(expr.shift_left(source.cregs[0], 2), 0), + ): + circuit = source.copy() + with circuit.if_test(predicate): + circuit.x(0) + with pytest.raises(oq.ConversionError, match="RANGE"): + oq.convert(circuit, target="ir") + dynamic = qiskit.QuantumCircuit( + qiskit.QuantumRegister(1), + qiskit.ClassicalRegister(2, "a"), + qiskit.ClassicalRegister(2, "b"), + ) + with dynamic.if_test(expr.index(dynamic.cregs[0], dynamic.cregs[1])): + dynamic.x(0) + with pytest.raises(oq.ConversionError, match="RANGE"): + oq.convert(dynamic, target="ir") + large = qiskit.QuantumCircuit(1) + zero = expr.Value(0, types.Uint(200)) + with large.if_test(expr.equal(expr.mul(zero, zero), zero)): + large.x(0) + with pytest.raises(oq.ConversionError, match="LIMIT"): + oq.convert(large, target="ir", max_operations=1000) + + +def test_constant_unsigned_overflow_folds_phase_and_cirq_preserves_arithmetic_guards(): + qiskit, expr, types = _sdk() + source = qiskit.QuantumCircuit(1, global_phase=0.2) + one, three = expr.Value(1, types.Uint(2)), expr.Value(3, types.Uint(2)) + with source.if_test(expr.equal(expr.add(three, one), expr.Value(0, types.Uint(2)))): + source.x(0) + ir = oq.convert(source, target="ir").value + np.testing.assert_allclose(oq.statevector(ir), [0, np.exp(0.2j)], atol=2e-14) + pytest.importorskip("cirq") + source = qiskit.QuantumCircuit(3, 2) + source.h(0) + source.h(1) + source.measure(0, 0) + source.measure(1, 1) + with source.if_test(expr.equal(expr.add(source.cregs[0], 1), 0)): + source.x(2) + ir = oq.convert(source, target="ir").value + converted = oq.convert(ir, target="cirq").value + back = oq.convert(converted, source="cirq", target="ir").value + assert oq.expectation(back, oq.PauliString("IIZ")) == pytest.approx(0.5) + + +def test_lowered_arithmetic_runs_as_native_aer_equality_feedforward(): + qiskit, expr, _ = _sdk() + pytest.importorskip("qiskit_aer") + a, out = qiskit.ClassicalRegister(2, "a"), qiskit.ClassicalRegister(1, "out") + source = qiskit.QuantumCircuit(qiskit.QuantumRegister(3), a, out) + source.h(0) + source.h(1) + source.measure(0, a[0]) + source.measure(1, a[1]) + with source.if_test(expr.equal(expr.add(a, 1), 0)): + source.x(2) + source.measure(2, out[0]) + ir = oq.convert(source, target="ir").value + expected = {"000", "100", "010", "111"} + assert set(oq.sample(ir, shots=128, seed=17)) == expected + assert set(oq.sample(ir, shots=128, seed=17, backend="aer")) == expected diff --git a/tests/test_expectile_risk.py b/tests/test_expectile_risk.py new file mode 100644 index 0000000..4151024 --- /dev/null +++ b/tests/test_expectile_risk.py @@ -0,0 +1,188 @@ +"""Reference root, ambiguity witnesses and native end-to-end risk derivatives.""" + +import numpy as np +import pytest + +import openqml as oq + + +def reference(losses, probabilities, level, margin=0): + p = np.asarray(probabilities, dtype=float) + p = p / p.sum() + lo, hi = min(losses) - 1, max(losses) + 1 + level * margin / (1 - level) + for _ in range(150): + mid = (lo + hi) / 2 + residual = ( + level * np.dot(p, np.maximum(losses - mid, 0)) + - (1 - level) * np.dot(p, np.maximum(mid - losses, 0)) + + level * margin + ) + if residual > 0: + lo = mid + else: + hi = mid + return (lo + hi) / 2 + + +@pytest.mark.parametrize("level", [0.5, 0.8, 0.98]) +@pytest.mark.parametrize("radius", [0, 0.001, 0.2]) +def test_sorted_nominal_and_robust_roots_match_independent_bisection(level, radius): + f = oq.finance + losses = np.array([0.1, -0.2, 0.4, 0.1, -0.3]) + p = np.array([0.1, 0, 0.3, 0.2, 0.4]) + nominal = f.expectile(losses, level=level, probabilities=p) + robust = f.wasserstein_expectile( + [1.0], -losses[:, None], level=level, probabilities=p, radius=radius + ) + assert nominal == pytest.approx(reference(losses, p, level), abs=1e-13) + assert robust == pytest.approx(reference(losses, p, level, radius), abs=1e-13) + assert robust >= nominal - 1e-13 + assert f.expectile(3 * losses + 2, level=level, probabilities=p) == pytest.approx( + 3 * nominal + 2 + ) + + +def test_wasserstein_expectile_is_approached_by_an_explicit_adversarial_distribution(): + # Move epsilon mass from the origin to radius/epsilon. This uses exactly + # the stated W1 budget, and its expectile tends to the returned supremum. + f, level, radius = oq.finance, 0.8, 0.02 + robust = f.wasserstein_expectile([1.0], [[0.0]], level=level, radius=radius) + witness = f.expectile([0.0, radius / 1e-7], level=level, probabilities=[1 - 1e-7, 1e-7]) + assert witness <= robust + assert robust == pytest.approx(level * radius / (1 - level), abs=1e-15) + assert witness == pytest.approx(robust, rel=1e-6) + + +def test_contextual_anisotropic_risk_and_funded_scaling_are_maximal(): + f = oq.finance + w = np.array([0.4, 0.5]) + scenarios = np.array([[-0.12, -0.03], [0.04, -0.08], [0.1, 0.02], [-0.05, 0.01]]) + p = np.array([0.2, 0.3, 0.4, 0.1]) + diagonal = np.array([[0.7, 1.2], [1.1, 0.8]]) + factors = np.array([[[0.2, -0.3]], [[0.1, 0.2]]]) + metric = f.WassersteinMetric(diagonal, factors) + decision = f.expectile_budget_projection( + w, + scenarios, + probabilities=p, + level=0.8, + budget=0.01, + radius=0.002, + cash_return=0.003, + transport_metric=metric, + ) + assert decision.weights.shape == (2, 2) + for i in range(2): + matrix = np.diag(diagonal[i]) + factors[i].T @ factors[i] + dual = np.sqrt(decision.weights[i] @ np.linalg.solve(matrix, decision.weights[i])) + losses = -scenarios @ decision.weights[i] - decision.cash[i] * 0.003 + exact = reference(losses, p, 0.8, 0.002 * dual) + assert exact == pytest.approx(decision.robust_expectile[i], abs=1e-14) + assert exact <= 0.01 + 1e-14 + larger = w * (decision.scale[i] + 1e-6) + above = reference( + -scenarios @ larger - (1 - larger.sum()) * 0.003, + p, + 0.8, + 0.002 * np.sqrt(larger @ np.linalg.solve(matrix, larger)), + ) + assert above > 0.01 + + +def _objective(values, backend): + f = oq.finance + circuit = oq.Circuit(1).ry(oq.Parameter("theta"), 0) + state = oq.statevector(circuit, {"theta": values[0]}, backend=backend) + p = state.real**2 + state.imag**2 + metric = f.WassersteinMetric(values[1:3], values[3:5].reshape((1, 2))) + decision = f.expectile_budget_projection( + [0.4, 0.5], + [[-0.12, -0.03], [0.04, -0.08]], + level=0.8, + probabilities=p, + budget=0.01, + radius=values[5], + transport_metric=metric, + ) + return -0.03 * decision.weights[0] + 0.01 * decision.weights[1] + + +@pytest.mark.parametrize("backend", ["torch", "jax"]) +def test_quantum_probabilities_radius_and_metric_have_native_decision_gradients(backend): + lib = pytest.importorskip(backend) + xp = lib if backend == "torch" else lib.numpy + dtype = xp.float64 if backend == "torch" else xp.float32 + values = xp.asarray([1.4, 0.7, 1.2, 0.2, -0.3, 0.01], dtype=dtype) + if backend == "torch": + values.requires_grad_() + assert lib.autograd.gradcheck(lambda v: _objective(v, backend), (values,)) + assert lib.autograd.gradgradcheck(lambda v: _objective(v, backend), (values,)) + result = lib.autograd.grad(_objective(values, backend), values)[0].detach().numpy() + else: + result = np.asarray(lib.jit(lib.grad(lambda v: _objective(v, backend)))(values)) + base = values.detach().numpy() if backend == "torch" else np.asarray(values) + + def independent_objective(v): + p = np.array([np.cos(v[0] / 2) ** 2, np.sin(v[0] / 2) ** 2]) + w = np.array([0.4, 0.5]) + scenarios = np.array([[-0.12, -0.03], [0.04, -0.08]]) + matrix = np.diag(v[1:3]) + np.outer(v[3:5], v[3:5]) + margin = v[5] * np.sqrt(w @ np.linalg.solve(matrix, w)) + robust = reference(-scenarios @ w, p, 0.8, margin) + return (-0.03 * w[0] + 0.01 * w[1]) * min(1, 0.01 / robust) + + expected = [] + for i in range(6): + # Differentiate an independent double-precision reference; float32 + # subtraction of nearly equal native losses hides small factor gradients. + delta = np.eye(6)[i] * 1e-5 + expected.append( + (independent_objective(base + delta) - independent_objective(base - delta)) / 2e-5 + ) + assert np.isfinite(result).all() and (np.abs(result) > 1e-8).all() + np.testing.assert_allclose(result, expected, rtol=2e-3, atol=2e-8) + + +@pytest.mark.parametrize("backend", ["torch", "jax"]) +def test_compiled_risk_retains_probability_and_radius_checks(backend): + lib = pytest.importorskip(backend) + xp = lib if backend == "torch" else lib.numpy + risk = oq.finance.wasserstein_expectile + compiled = oq.compile_compute( + lambda p, r: risk( + xp.asarray([0.4, 0.5]), + xp.asarray([[-0.12, -0.03], [0.04, -0.08]]), + probabilities=p, + radius=r, + level=0.8, + ), + backend=backend, + **({"compiler": "eager", "fullgraph": True} if backend == "torch" else {}), + ) + assert np.isfinite(np.asarray(compiled(xp.asarray([0.4, 0.6]), xp.asarray(0.01)))) + with pytest.raises(oq.ValidationError): + compiled(xp.asarray([0.4, -0.6]), xp.asarray(0.01)) + with pytest.raises(oq.ValidationError): + compiled(xp.asarray([0.4, 0.6]), xp.asarray(-0.01)) + + +def test_invalid_risk_domains_and_small_memory_fail_explicitly(): + f = oq.finance + for options in ( + {"level": 0.4}, + {"level": 1}, + {"probabilities": [0, 0]}, + {"max_memory_mb": 1e-9}, + ): + with pytest.raises((oq.ValidationError, oq.ResourceError)): + f.expectile([0.1, 0.2], **options) + with pytest.raises(oq.ValidationError): + f.expectile([]) + with pytest.raises(oq.ValidationError): + f.wasserstein_expectile([1.0], [[0.1], [0.2]], radius=-1) + assert f.expectile([1e250, 1e250], level=0.99) == pytest.approx(1e250) + assert f.expectile([0.0, 0.0], level=0.99) == 0 + root = f.expectile([1e-200, 1e200], level=0.99, probabilities=[1.0, 0.0]) + assert root / 1e-200 == pytest.approx(1.0) + root = f.expectile([1e-310], level=1 - 1e-15) + assert root / 1e-310 == pytest.approx(1.0) diff --git a/tests/test_submission_training.py b/tests/test_submission_training.py new file mode 100644 index 0000000..eb1aeda --- /dev/null +++ b/tests/test_submission_training.py @@ -0,0 +1,253 @@ +"""Independent derivatives and actual submission counts for packed training.""" + +from dataclasses import replace + +import numpy as np +import pytest + +import openqml as oq + + +class CountingBackend: + name = "stencil-counter" + + def __init__(self, deterministic=False): + self.calls = [] + self.capabilities = oq.BackendCapabilities( + native_expectations=True, + exact_expectations=True, + deterministic_expectations=deterministic, + channels=True, + ) + + def expectations_batch(self, circuits, observables, *, options): + self.calls.append(len(circuits)) + return oq.expectations_batch(circuits, observables, backend="numpy") + + +@pytest.mark.parametrize("deterministic", [False, True]) +def test_linearization_matches_finite_differences_and_does_not_replay_products(deterministic): + x, y, p = (oq.Parameter(n) for n in ("x", "y", "p")) + circuit = oq.Circuit(2).ry(x * x + y, 0).crx(x, 0, 1).amplitude_damping(p, 1).ry(y, 1) + obs, backend = (oq.PauliString("ZZ"), oq.PauliString("IX")), CountingBackend(deterministic) + rows = [ + {"x": 0.2, "y": 0.3, "p": 0.4}, + {"x": 0.2, "y": 0.3, "p": 0.4}, + {"x": -0.4, "y": 0.1, "p": 0.2}, + ] + plan = oq.ShiftPlan(circuit, obs, parameters=("y", "x", "p"), backend=backend) + result = plan.linearize(rows, chunk_size=1000) + expected = np.empty((3, 2, 3)) + for i, row in enumerate(rows): + for j, name in enumerate(result.parameters): + plus, minus = dict(row), dict(row) + plus[name] += 1e-6 + minus[name] -= 1e-6 + expected[i, :, j] = ( + oq.expectations(circuit, obs, plus) - oq.expectations(circuit, obs, minus) + ) / 2e-6 + np.testing.assert_allclose(result.jacobian, expected, atol=3e-10) + np.testing.assert_allclose(result.values, oq.expectations_batch(circuit, obs, rows)) + count = (2 if deterministic else 3) * (1 + plan.shift_evaluations) + assert backend.calls == [count] and result.submission_batches == 1 + assert result.circuit_evaluations == count + tangent, cotangent = np.ones((3, 3)), np.ones((3, 2)) + np.testing.assert_allclose( + result.vjp(cotangent), np.einsum("bm,bmp->bp", cotangent, expected), atol=3e-10 + ) + np.testing.assert_allclose( + result.jvp(tangent), np.einsum("bmp,bp->bm", expected, tangent), atol=3e-10 + ) + assert backend.calls == [count] + assert not result.values.flags.writeable and not result.jacobian.flags.writeable + + +def test_linearization_preflights_all_rows_and_memory_before_external_submission(): + backend = CountingBackend() + p = oq.Parameter("p") + plan = oq.ShiftPlan( + oq.Circuit(1).amplitude_damping(p, 0), [oq.PauliString("Z")], backend=backend + ) + with pytest.raises(oq.ValidationError): + plan.linearize({"p": [0.2, -0.1]}) + with pytest.raises(oq.ValidationError): + plan.linearize({"p": [0.2, 1.0]}, chunk_size=2) + with pytest.raises(oq.ResourceError): + plan.linearize({"p": [0.2, 0.3]}, max_memory_mb=1e-8) + assert not backend.calls + result = plan.linearize({"p": [0.2, 0.3]}, parameters=(), chunk_size=2) + assert result.jacobian.shape == (2, 1, 0) and result.circuit_evaluations == 2 + + +def _layer(backend, interface): + x, w, v = (oq.Parameter(n) for n in ("x", "w", "v")) + circuit = oq.Circuit(1).ry(x * w, 0).rz(v, 0).ry(w, 0) + if interface == "torch": + import torch + + from openqml.qml.interfaces.torch import QuantumLayer + + options = {"dtype": torch.float64, "device": "cpu"} + else: + from openqml.qml.interfaces.jax import QuantumLayer + + options = {} + return QuantumLayer( + circuit, + ("x",), + ("w", "v"), + backend=backend, + gradient_method="batched-shift", + gradient_chunk_size=1000, + **options, + ) + + +def test_torch_broadcast_gradients_and_transforms_reuse_the_primal_stencil(): + torch = pytest.importorskip("torch") + backend = CountingBackend() + layer = _layer(backend, "torch") + x = torch.tensor([[0.2], [0.5], [-0.3]], dtype=torch.float64, requires_grad=True) + w = torch.tensor([[[0.4, 0.7]], [[0.2, -0.3]]], dtype=torch.float64, requires_grad=True) + reference = _layer("numpy", "torch") + reference.gradient_method = "parameter-shift" + + def objective(a, b): + return layer.functional(a, b).sin().square().sum() + + value = objective(w, x) + gradients = torch.autograd.grad(value, (w, x)) + assert len(backend.calls) == 1 + expected = torch.autograd.grad(reference.functional(w, x).sin().square().sum(), (w, x)) + for actual, want in zip(gradients, expected, strict=True): + torch.testing.assert_close(actual, want) + backend.calls.clear() + jac = torch.func.jacrev(lambda a: layer.functional(a, x))(w) + assert len(backend.calls) == 1 and torch.isfinite(jac).all() + backend.calls.clear() + forward_jacobian = torch.func.jacfwd(lambda a: layer.functional(a, x))(w) + assert len(backend.calls) == 1 + torch.testing.assert_close(forward_jacobian, jac) + backend.calls.clear() + _, tangent = torch.func.jvp(lambda a: layer.functional(a, x), (w,), (torch.ones_like(w),)) + assert len(backend.calls) == 1 and torch.isfinite(tangent).all() + backend.calls.clear() + mapped = torch.vmap(lambda a: layer.functional(a, x))(w[:, 0, :]) + assert len(backend.calls) == 1 and mapped.shape == (2, 3, 1) + gradient = torch.autograd.grad(objective(w, x), w, create_graph=True)[0] + with pytest.raises(oq.ValidationError, match="higher derivatives"): + torch.autograd.grad(gradient.sum(), w) + + +def test_jax_jit_value_gradient_jvp_and_vmap_use_one_stencil(): + jax = pytest.importorskip("jax") + xp, backend = jax.numpy, CountingBackend() + layer = _layer(backend, "jax") + x = xp.asarray([[0.2], [0.5], [-0.3]]) + w = xp.asarray([[[0.4, 0.7]], [[0.2, -0.3]]]) + + def objective(a, b): + return xp.square(xp.sin(layer(a, b))).sum() + + value, gradients = jax.jit(jax.value_and_grad(objective, argnums=(0, 1)))(w, x) + value.block_until_ready() + assert len(backend.calls) == 1 + reference = _layer("numpy", "jax") + reference.gradient_method = "parameter-shift" + expected = jax.grad(lambda a, b: xp.square(xp.sin(reference(a, b))).sum(), argnums=(0, 1))(w, x) + for actual, want in zip(gradients, expected, strict=True): + np.testing.assert_allclose(actual, want, rtol=2e-5, atol=2e-7) + backend.calls.clear() + _, tangent = jax.jit(lambda a: jax.jvp(lambda z: layer(z, x), (a,), (xp.ones_like(a),)))(w) + tangent.block_until_ready() + assert len(backend.calls) == 1 + backend.calls.clear() + mapped = jax.jit(jax.vmap(lambda a: layer(a, x)))(w[:, 0, :]) + mapped.block_until_ready() + assert len(backend.calls) == 1 and mapped.shape == (2, 3, 1) + with pytest.raises(oq.ValidationError, match="higher derivatives"): + jax.hessian(lambda a: objective(a, x))(w) + + +def test_qiskit_v2_estimator_linearization_submits_one_real_job(): + pytest.importorskip("qiskit") + from qiskit.primitives import StatevectorEstimator + + class Estimator: + calls = 0 + + def run(self, *args, **kwargs): + self.calls += 1 + return StatevectorEstimator().run(*args, **kwargs) + + estimator = Estimator() + backend = oq.QiskitEstimatorBackend(estimator, precision=0) + p = oq.ShiftPlan(oq.Circuit(1).ry(oq.Parameter("x"), 0), [oq.PauliString("Z")], backend=backend) + result = p.linearize({"x": [0.2, 0.4]}, chunk_size=64) + np.testing.assert_allclose(result.values[:, 0], np.cos([0.2, 0.4])) + np.testing.assert_allclose(result.vjp(np.ones((2, 1)))[:, 0], -np.sin([0.2, 0.4])) + assert estimator.calls == 1 + + +def test_jax_stochastic_submissions_are_effects_even_if_results_are_unused_or_equal(): + jax = pytest.importorskip("jax") + backend = CountingBackend() + layer = _layer(backend, "jax") + w, x = jax.numpy.asarray([0.4, 0.7]), jax.numpy.asarray([[0.2]]) + + def unused(weights): + layer(weights, x) + return weights.sum() * 0 + + jax.jit(unused)(w).block_until_ready() + jax.effects_barrier() + assert len(backend.calls) == 1 + backend.calls.clear() + jax.jit(lambda weights: layer(weights, x) + layer(weights, x))(w).block_until_ready() + jax.effects_barrier() + assert len(backend.calls) == 2 + + +def test_joint_workload_prices_one_submission_instead_of_separate_phases(): + from openqml.runtime.costs import estimate_cost + + profile = oq.ExecutionProfile( + circuit_seconds=0.01, queue_seconds=3, cost_per_job=1, max_batch_size=64 + ) + workload = oq.TrainingWorkload( + batch_size=5, steps=2, gradient_evaluations=10, microbatch_size=2, gradient_chunk_size=64 + ) + request = oq.SchedulingRequest( + (oq.Circuit(1),), (oq.PauliString("Z"),), "expectations", oq.ExecutionOptions(), workload + ) + separate = estimate_cost(profile, request, oq.SchedulingPolicy()) + joint = estimate_cost( + profile, + replace(request, workload=replace(workload, joint_primal_gradient=True)), + oq.SchedulingPolicy(), + ) + assert separate.provider_jobs == 12 and joint.provider_jobs == 6 + assert separate.circuit_evaluations == joint.circuit_evaluations == 110 + assert separate.physical_shots == joint.physical_shots + assert joint.cost == 6 and joint.seconds < separate.seconds + + +def test_flax_parameter_tree_trains_through_the_packed_stencil(): + pytest.importorskip("flax") + jax = pytest.importorskip("jax") + from openqml.qml.interfaces.flax import QuantumLayer + + x, w = oq.Parameter("x"), oq.Parameter("w") + circuit = oq.Circuit(1).ry(x * w, 0) + backend = CountingBackend() + layer = QuantumLayer(circuit, ("x",), ("w",), backend=backend, gradient_method="batched-shift") + inputs = jax.numpy.asarray([[0.2], [0.5]]) + parameters = layer.init(jax.random.key(3), inputs) + jax.effects_barrier() + backend.calls.clear() + value, gradient = jax.jit( + jax.value_and_grad(lambda p: jax.numpy.square(layer.apply(p, inputs)).sum()) + )(parameters) + value.block_until_ready() + assert len(backend.calls) == 1 + assert all(np.isfinite(v).all() for v in jax.tree_util.tree_leaves(gradient))