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
18 changes: 15 additions & 3 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,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_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_compilation_portability.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 @@ -119,7 +119,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_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_compilation_portability.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 All @@ -138,9 +138,21 @@ jobs:
with:
python-version: ${{ matrix.python }}
- run: python -m pip install ".[all,dev]" --report install-report.json
- name: Activate the Windows C++ toolchain for TorchInductor
if: runner.os == 'Windows'
shell: pwsh
run: |
$vswhere = "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe"
$installation = & $vswhere -latest -products * -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 -property installationPath
if (-not $installation) { throw "Visual Studio C++ Build Tools are required for Inductor integration tests." }
& "$installation\Common7\Tools\Launch-VsDevShell.ps1" -SkipAutomaticLocation -Arch amd64 -HostArch amd64
if (-not (Get-Command cl -ErrorAction SilentlyContinue)) { throw "MSVC activation did not expose cl.exe." }
foreach ($name in 'PATH', 'INCLUDE', 'LIB', 'LIBPATH') {
"$name=$([Environment]::GetEnvironmentVariable($name))" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
}
- 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_native_fusion.py
- run: python -m pytest -q tests/test_compilation_portability.py tests/test_native_fusion.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_register_programs.py tests/test_accelerators.py tests/test_native_gpu.py tests/test_precision_regressions.py tests/test_audit_regressions.py tests/test_switch_lowering.py tests/test_risk_budget.py tests/test_tensor_streaming.py tests/test_model_checkpoint.py tests/test_model_selection.py tests/test_walk_forward.py tests/test_conversion_sweeps.py tests/test_finance_execution.py tests/test_simple_api.py tests/test_adaptive_amplitude.py tests/test_amplitude.py tests/test_finance.py tests/test_frontier_models.py tests/test_algorithmic_execution.py tests/test_network_operators.py tests/test_architecture.py tests/test_deep_learning.py tests/test_cost_scheduling.py tests/test_calibration.py tests/test_distributed_compute.py tests/test_multiscale_execution.py tests/test_gradient_accumulation.py tests/test_program_compilation.py tests/test_distributed_training.py tests/test_compute_contractions.py tests/test_contraction_compiler.py tests/test_runtime.py tests/test_hybrid_training.py tests/test_sparse_scaling.py tests/test_research_methods.py tests/test_public_api.py tests/test_package_scope.py tests/test_package_layout.py tests/test_execution_hotpaths.py tests/test_mitigation.py tests/test_model_streaming.py tests/test_backends.py tests/test_providers.py tests/test_shared_readouts.py tests/test_conversion_plan.py tests/test_resource_audit.py tests/test_source_boundaries.py tests/test_resource_profiles.py tests/test_environment_report.py tests/test_scientific_scale.py tests/test_semantic_compiler.py tests/test_adaptive_execution.py
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
if: always()
Expand Down
6 changes: 6 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,12 @@ The core depends on NumPy, packaging and psutil. Training frameworks, quantum SD

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

OpenQML implements circuit lowering, fusion planning, readout arithmetic and resource
scheduling. Aer owns the integrated C++/CUDA simulator; PyTorch/JAX and their compilers
provide tensor kernels for OpenQML's own execution algorithms. These are separate
execution paths. `AerBackend.execution_info()` and `CUDABackend.execution_info()`
describe the configured engine and kernel provider without initializing hardware.

## Quick start

Allocate from observed returns:
Expand Down
18 changes: 18 additions & 0 deletions docs/compute.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,24 @@ register program before tracing. Compiled Torch transforms require PyTorch
2.4 or later; ordinary autograd through compiled circuit values works on the
base Torch version. OpenQML does not change process-global compiler settings.

Torch 2.2's Dynamo requires Python 3.10 or 3.11; use a newer Torch release for
compilation on Python 3.12. Expression dtype and broadcast checks use static
type/shape guards so full-graph tracing retains real-domain validation on the
supported legacy versions, including native readouts and checkpointed circuits.

TorchInductor also requires a working C++ toolchain for generated CPU code.
On Windows, install Visual Studio Build Tools with **Desktop development with
C++**, then start Python in an **x64 Native Tools Command Prompt** where `cl`
is available. See [PyTorch's Windows setup](https://docs.pytorch.org/tutorials/unstable/inductor_windows.html).
An observed missing compiler raises `ResourceError` with setup instructions;
unrelated compiler failures retain their original exceptions. OpenQML does not
silently switch compilation backends. Explicitly pass `compiler="aot_eager"`
to `compile_compute` or `compile_circuit` for graph execution/autodiff without
C++ code generation, or `compiler="eager"` to debug Dynamo capture. These modes
do not provide Inductor kernel fusion or CUDA Graph replay.
`environment_report()["cxx_compiler"]` reports executable discovery only;
it does not certify a working compiler, SDK, linker or accelerator.

Compilation has an initial cost, and small circuits can remain faster eagerly.
TorchInductor can delegate unsupported complex operators to native kernels.
Fusion benefit depends on locality, gate mix and reuse. These mechanisms do not
Expand Down
12 changes: 12 additions & 0 deletions docs/runtime.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,18 @@ Readout execution returns observables without exporting the complete state.
This is an integration with Aer/cuQuantum, not a separately implemented
OpenQML C++ statevector simulator.

| Execution path | OpenQML's implementation | External kernel/runtime provider |
| --- | --- | --- |
| `AerBackend(device="GPU")` | IR export, parameter batching, memory admission, dispatch | Qiskit Aer C++/CUDA; requested cuStateVec/cuTensorNet support depends on its build |
| `CUDABackend()` | Circuit/readout planning, register schedules, tensor evolution | PyTorch CUDA tensor kernels |
| `CUDABackend(compile_mode="default")` | Shared readout program, packed parameters, bounded graph cache | PyTorch TorchInductor code generation |

Both adapters expose `execution_info()` without loading an SDK or accessing a
device. This describes configuration and provenance. `requested_accelerator`
on Aer records a request, and `execution_verified=False` explicitly prevents
treating that configuration as evidence that a vendor accelerator ran.
OpenQML currently has no independently implemented C++/CUDA kernel engine.

On supported Linux x86-64 systems, install `openqml[aer-gpu]` with a compatible
NVIDIA driver/runtime. Use an environment containing the GPU Aer distribution;
do not install both `qiskit-aer` and `qiskit-aer-gpu`, which share a Python
Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"

[project]
name = "openqml"
version = "0.25.0"
version = "0.25.1"
description = "Quantum-classical hybrid AI, quantitative research and cross-framework quantum programming"
readme = "README.md"
requires-python = ">=3.10"
Expand Down
2 changes: 1 addition & 1 deletion src/openqml/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

_install_aliases()

__version__ = "0.25.0"
__version__ = "0.25.1"
__all__ = _PUBLIC


Expand Down
34 changes: 30 additions & 4 deletions src/openqml/autodiff/compilation.py
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,31 @@ def _leaves(value):
yield np.asarray(value)


def _check_compiler_error(error):
"""Translate only an observed missing compiler, preserving unrelated failures."""
from torch._inductor.exc import InvalidCxxCompiler

pending, seen = [error], set()
while pending:
current = pending.pop()
if not isinstance(current, BaseException) or id(current) in seen:
continue
seen.add(id(current))
if isinstance(current, InvalidCxxCompiler):
raise ResourceError(
"TorchInductor could not find a working C++ compiler. On Windows, install "
"Visual Studio Build Tools with Desktop development with C++ and run from "
"an x64 Native Tools command prompt (cl must be available). On other systems, "
"configure a supported C++ toolchain. For graph execution without C++ code "
"generation, explicitly select compiler='aot_eager' or compiler='eager'; "
"these backends do not provide Inductor kernel fusion or CUDA Graph replay. "
"For CUDABackend, leave compile_mode=None to use eager GPU execution."
) from error
pending.extend(
(current.__cause__, current.__context__, getattr(current, "inner_exception", None))
)


def compile_compute(
function, *, backend, compiler=None, kernel=None, check_outputs=True, **options
):
Expand Down Expand Up @@ -83,10 +108,11 @@ def call(*args, **kwargs):
with compute_context(kernel=kernel):
try:
result = graph(*args, **kwargs)
except (RuntimeError, AssertionError) as exc:
if "[OpenQML:" not in str(exc):
raise
_raise(str(exc))
except Exception as exc:
_check_compiler_error(exc)
if isinstance(exc, (RuntimeError, AssertionError)) and "[OpenQML:" in str(exc):
_raise(str(exc))
raise
if check_outputs:
flags = {}
for value in _leaves(result):
Expand Down
19 changes: 19 additions & 0 deletions src/openqml/interop/aer.py
Original file line number Diff line number Diff line change
Expand Up @@ -142,6 +142,25 @@ def clear_cache(self):
self._compiled.clear()
self._cache_stats.update(hits=0, misses=0)

def execution_info(self):
"""Describe configured implementation sources without importing/probing Aer."""
return {
"engine": "qiskit-aer",
"algorithm_owner": "Qiskit Aer",
"kernel_provider": "qiskit-aer",
"device": self.device,
"method": self.method,
"precision": self.precision,
"requested_accelerator": (
"cuStateVec"
if self.cu_statevec
else "cuTensorNet"
if self.method == "tensor_network"
else None
),
"execution_verified": False,
}

def is_available(self):
"""Query the installed native engine without submitting simulation work."""
from ..errors import MissingDependencyError
Expand Down
16 changes: 11 additions & 5 deletions src/openqml/ir/parameters.py
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,9 @@ def _checked(value):
backend = _array_backend(value)
if backend == "torch":
xp = _namespace(value)
if value.dtype != xp.bool and not value.is_complex():
# Dynamo 2.2 cannot trace Tensor.is_complex() returning a Python bool.
# Direct dtype comparisons are static guards, including under torch.func.
if value.dtype not in (xp.bool, xp.complex32, xp.complex64, xp.complex128):
return value
elif backend == "jax":
xp = _namespace(value)
Expand All @@ -84,10 +86,14 @@ def _checked(value):


def _broadcast_operands(left, right):
if hasattr(left, "shape") and hasattr(right, "shape"):
from ..compute.kernel import _broadcast_shape

_broadcast_shape((tuple(left.shape), tuple(right.shape)))
# Operands have already passed _checked. Scalars broadcast to every shape;
# every other admitted value is an array. Avoid hasattr on native tensors,
# which breaks fullgraph capture in older Dynamo versions.
if isinstance(left, (Real, np.generic)) or isinstance(right, (Real, np.generic)):
return
from ..compute.kernel import _broadcast_shape

_broadcast_shape((tuple(left.shape), tuple(right.shape)))


_ARITY = {
Expand Down
14 changes: 14 additions & 0 deletions src/openqml/runtime/environment.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
import importlib.metadata as metadata
import os
import platform
import shutil
import stat
import subprocess
import sys
Expand Down Expand Up @@ -31,6 +32,18 @@
}


def _compiler_report():
command = os.environ.get("CXX") or ("cl" if platform.system() == "Windows" else "c++")
path = shutil.which(command)
return {
"command": command,
"path": path,
"status": "located" if path else "not_found",
"execution_checked": False,
"graph_backends_without_cxx": ["aot_eager", "eager"],
}


def _probe_import(module, timeout):
"""A broken binary import cannot terminate or alter the caller's SDK state."""
code = "import importlib; importlib.import_module(" + repr(module) + ")"
Expand Down Expand Up @@ -232,6 +245,7 @@ def environment_report(*, check_imports=False, include_sizes=False, import_timeo
"isolated_import_checks": check_imports,
"runtime_probe_coverage": probe_coverage,
"accelerator_execution_checked": False,
"cxx_compiler": _compiler_report(),
"dependency_count": len(dependencies),
"dependencies": dict(sorted(dependencies.items())),
"integrations": integrations,
Expand Down
13 changes: 13 additions & 0 deletions src/openqml/sim/_cuda.py
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,19 @@ def clear_cache(self):
self._cache.clear()
self._compiled.clear()

def execution_info(self):
"""Describe OpenQML algorithms and their external tensor/codegen runtime."""
return {
"engine": "openqml-tensor",
"algorithm_owner": "OpenQML",
"kernel_provider": "pytorch",
"device": self.device or "cuda",
"precision": self.precision,
"compiler": "torchinductor" if self.compile_mode is not None else None,
"compile_mode": self.compile_mode,
"execution_verified": False,
}

def _compiled_readout(self, plan, rows, like):
from ..compute.kernel import get_compute_kernel
from .dense import _TensorOps
Expand Down
12 changes: 8 additions & 4 deletions src/openqml/sim/pauli.py
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
import numpy as np

from ..compute._program import lower_program
from ..compute.kernel import get_compute_kernel, memory_budget
from ..compute.kernel import _broadcast_shape, get_compute_kernel, memory_budget
from ..errors import Diagnostic, ResourceError, ValidationError, conversion_error
from ..ir.compiler import _check_circuit_limits, circuit_stats, decompose
from ..ir.core import Circuit, integer
Expand Down Expand Up @@ -488,6 +488,10 @@ def _prepare_bindings(
if prototype is not None:
ops = _TensorOps(backend, prototype)
for value in bindings.values():
if backend == "torch" and isinstance(value, ops.xp.Tensor):
if value.dtype in (ops.xp.bool, ops.xp.complex32, ops.xp.complex64, ops.xp.complex128):
raise ValidationError("Pauli bindings must be real numeric values.")
continue
dtype = getattr(value, "dtype", None)
kind = getattr(dtype, "kind", None)
if (
Expand All @@ -502,11 +506,11 @@ def _prepare_bindings(
for n, v in bindings.items()
}
try:
shape = np.broadcast_shapes(*(tuple(v.shape) for v in local.values()))
shape = _broadcast_shape(tuple(tuple(v.shape) for v in local.values()))
if batch_shape is not None:
target = tuple(integer(n, "batch dimension") for n in batch_shape)
shape = np.broadcast_shapes(shape, target)
except (TypeError, ValueError) as exc:
shape = _broadcast_shape((shape, target))
except (TypeError, ValueError, ValidationError) as exc:
raise ValidationError("Pauli parameter batch shapes cannot be broadcast together.") from exc
return ops, local, shape

Expand Down
Loading
Loading