Skip to content

SPDX-License-Identifier: AGPL-3.0-or-later

Commercial license available

© Concepts 1996–2026 Miroslav Šotek. All rights reserved.

© Code 2020–2026 Miroslav Šotek. All rights reserved.

ORCID: 0009-0009-3560-0851

Contact: www.anulum.li | protoscience@anulum.li

scpn-quantum-control — Stable Facades API

Stable Facades API

Stable facades are the first-path API surfaces for users who want to build a workflow without depending on low-level module layout. Prefer these symbols in tutorials, notebooks, and inter-repository contracts.

Stable Core Contracts

The stable core contracts define the durable Problem, Backend, Experiment, and Result surfaces that bridge domain problems, backend capability checks, experiment preregistration, and result artifacts.

scpn_quantum_control.stable_core

Stable first-path contracts for SCPN quantum-control workflows.

The contracts in this module are intentionally small. They define the durable shape that higher-level compilers, backend adapters, benchmark harnesses, and hardware result-pack replay paths can share without depending on low-level module layout.

Problem dataclass

Stable domain problem contract.

__post_init__()

Validate stable problem invariants.

to_dict()

Return a JSON-compatible problem payload.

Backend dataclass

Stable backend capability contract.

__post_init__()

Validate stable backend invariants.

supports(capability)

Return whether the backend declares one capability.

to_dict()

Return a JSON-compatible backend payload.

Experiment dataclass

Stable experiment contract tying a problem to a backend and objective.

__post_init__()

Validate stable experiment invariants.

to_dict()

Return a JSON-compatible experiment payload.

Result dataclass

Stable result contract for experiment outputs.

__post_init__()

Validate stable result invariants.

to_dict()

Return a JSON-compatible result payload.

backend_capability_matrix()

Return the stable backend capability matrix.

The matrix is intentionally descriptive. It records declared capability profiles and hardware-submission boundaries; it does not imply that every adapter implementation is complete.

stable_core_capability_payload()

Return a JSON-compatible stable core capability payload.

stable_core_capability_markdown(data)

Render a public backend capability matrix summary.

write_stable_core_capability_artifacts(*, json_path, doc_path)

Write deterministic stable core capability artifacts and return digests.

build_problem(*, problem_id, coupling_matrix, omega, initial_state=None, metadata=None)

Build a stable Kuramoto/XY problem contract.

build_backend(*, backend_id, kind, capabilities, hardware_submission_allowed=False, metadata=None)

Build a stable backend capability contract.

build_experiment(*, experiment_id, problem, backend, objective, seed, shots=None, metadata=None)

Build a stable experiment contract.

build_result(*, experiment_id, backend_id, status, observables, artifacts=(), blockers=(), metadata=None)

Build a stable result contract.

classical_reference_backend(backend_id='classical-reference', *, metadata=None)

Build the stable no-QPU classical-reference backend profile.

hardware_replay_backend(backend_id='hardware-replay', *, metadata=None)

Build the stable no-submit hardware-result replay backend profile.

qiskit_backend(backend_id='qiskit-runtime', *, hardware_submission_allowed=False, metadata=None)

Build the stable Qiskit backend profile.

Hardware submission remains disabled by default. Callers must opt in and still provide experiment preregistration metadata before a hardware-enabled experiment can be built.

qutip_backend(backend_id='qutip-dynamics', *, metadata=None)

Build the stable QuTiP/open-system dynamics backend profile.

pennylane_backend(backend_id='pennylane-autodiff', *, metadata=None)

Build the stable PennyLane/autodiff backend profile.

pulser_surrogate_backend(backend_id='pulser-surrogate', *, metadata=None)

Build the stable Pulser-surrogate analog backend profile.

problem_from_kuramoto(kuramoto_problem, *, problem_id, initial_state=None, metadata=None)

Convert a Kuramoto facade problem into the stable problem contract.

problem_to_kuramoto(problem)

Convert a stable problem contract into the Kuramoto facade problem.

The stable-core contracts are also covered by reproducibility gates:

  • stable-core-capability-gate for adapter capability profiles.
  • stable-core-contract-gate for contract fixture drift on core contract types and adaptor mappings.

Kuramoto Core

The Kuramoto core facade accepts arbitrary symmetric K_nm matrices, heterogeneous omega vectors, and serialisable metadata. It returns validated problem objects, sparse/dense Hamiltonians, Trotter circuits, and order-parameter measurements.

scpn_quantum_control.kuramoto_core

Small public facade for Kuramoto-XY problems.

KuramotoProblem dataclass

Validated coupling matrix, frequencies, and serialisable metadata.

n_oscillators property

Number of oscillators/qubits represented by the problem.

to_metadata()

Return serialisable metadata for result artifacts.

build_kuramoto_problem(K_nm, omega, metadata=None)

Create a validated Kuramoto-XY problem from arbitrary arrays.

validate_kuramoto_inputs(K_nm, omega)

Validate and copy a symmetric Kuramoto coupling problem.

compile_hamiltonian(problem)

Compile a Kuramoto problem into the XY SparsePauliOp Hamiltonian.

compile_dense_hamiltonian(problem, *, max_dense_gib=None)

Compile a dense Hamiltonian, using the Rust engine when installed.

compile_trotter_circuit(problem, time, trotter_steps=10, trotter_order=1)

Compile a Trotterised gate-model evolution circuit.

measure_order_parameter(problem, statevector)

Measure the Kuramoto order parameter from a statevector.