Stable Core API

The stable core API defines the first durable contracts for production workflows:

• Problem: typed Kuramoto/XY domain descriptor.
• Backend: backend capability and hardware-submission boundary.
• Experiment: problem, backend, objective, seed, shot, and metadata contract.
• Result: status, observables, artifact, blocker, and metadata contract.
• problem_from_kuramoto / problem_to_kuramoto: adapters to the existing Kuramoto core facade.
• standard backend profiles for classical reference, hardware replay, Qiskit, QuTiP, PennyLane, and Pulser-surrogate targets.
• backend_capability_matrix() for deterministic audit/reporting of declared backend capability profiles.
• generated backend capability artefacts: data/stable_core/backend_capability_matrix.json and docs/stable_core_backend_capability_matrix.md.

These contracts are intentionally smaller than the full research surface. They are the integration point for future Qiskit, Qiskit Dynamics, QuTiP, PennyLane, Pulser-surrogate, classical-reference, benchmark, and hardware-replay adapters.

Claim boundary

The stable core API is a contract layer. It does not run circuits, submit hardware jobs, solve Lindblad dynamics, or perform optimal control by itself. Backends must declare capabilities before an Experiment can target an objective, and hardware-submission backends require preregistration metadata.

Kuramoto facade bridge

The stable core layer is wired to the existing Kuramoto core facade through lossless problem adapters:

• problem_from_kuramoto() converts a validated KuramotoProblem into a stable Problem with a required problem_id.
• problem_to_kuramoto() converts a stable Problem back into the existing KuramotoProblem facade for Hamiltonian, circuit, analog, hybrid, and trajectory compilation.

This bridge keeps the stable API useful without forcing a package layout split or changing the lower-level compiler path.

Backend profiles

Stable backend helpers encode the bridge-first strategy without claiming that every backend is natively implemented:

• classical_reference_backend() for no-QPU reference solvers.
• hardware_replay_backend() for offline hardware result-pack replay.
• qiskit_backend() for Qiskit circuit/runtime paths; hardware submission is disabled by default and still requires experiment preregistration metadata.
• qutip_backend() for open-system and Hamiltonian-dynamics adapters.
• pennylane_backend() for autodiff and hybrid-control adapters.
• pulser_surrogate_backend() for analog-surrogate and pulse-schedule adapters.

These helpers declare capability profiles only. Adapter implementations must still satisfy their own evidence, dependency, and claim-boundary gates.

backend_capability_matrix() returns the same profile set as a deterministic tuple of dictionaries. Use it for release audits, documentation generators, and multi-backend compiler preflight checks before claiming adapter support.

Stable-core capability gate

Capability claims for the stable core are bound to a one-command gate:

scpn-bench stable-core-capability-gate

The gate regenerates the committed stable-core capability payload and markdown artifacts and then compares them to committed references. This keeps stable-core capability profiles reproducible and avoids manual promotion of adapter support.

Stable-core release/repro gate

Stable-core releases and reproducibility checks now use a bundled gate:

scpn-bench stable-core-release-gate

This command is the preferred no-QPU entry point when stable-core documentation, API surfaces, or release notes touch stable-core claims. It runs component gates as a single bundle:

• scpn-bench stable-core-capability-gate
• scpn-bench stable-core-contract-gate
• scpn-bench stable-core-preflight-gate

Stable-core preflight gate

The offline preflight surface for stable-core release preparation is:

scpn-bench stable-core-preflight-gate

The gate is a no-QPU check for stable-core fixture inputs before public API or documentation changes are merged. Use it when either contract or capability fixture inputs change.

Targeted preflight files include docs/stable_core_preflight_fixtures.md.

Component commands remain available for focused checks when only one contract or capability path changes.

Stable-core contract gate

Contract drift for the stable-core first-path surfaces is controlled by:

scpn-bench stable-core-contract-gate

The gate is the offline fixture check for the stable_core contracts:

• Problem
• Backend
• Experiment
• Result
• Kuramoto adaptor helpers

It is designed for no-hardware runs and is intended to be run when contract signatures, validation rules, or adaptor mappings change before docs or API surface edits are published.

Regenerate the committed artifacts with:

PYTHONPATH=src python scripts/export_stable_core_capability_matrix.py

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.