DLA Topology Control API¶
The scpn_quantum_control.dla_topology_control package is the public BL-54
facade for finite parity-sector derivatives, fixed-active-set topology-ledger
sensitivities, a synthetic projected-gradient task, and deterministic evidence
custody.
All returned arrays are copied and read-only. Unsupported non-smooth or discrete branches raise instead of returning approximate or invented derivatives. The package performs no provider submission, QPU or hardware execution, external actuation, deployment, or error-correction action.
For equations, support tables, examples, evidence, and scientific sources, read DLA and Topology-Constrained Differentiable Control.
Support and parity contracts¶
scpn_quantum_control.dla_topology_control.schema
¶
Immutable support contracts for DLA/topology-constrained control.
DifferentiabilityKind
¶
Bases: Enum
Mathematical derivative class for one constrained operation.
ParitySector
¶
Bases: Enum
Computational-basis parity sector selected by Hamming weight.
UnsupportedDifferentiableConstraintError
¶
Bases: ValueError
Raised when a caller requests a derivative on an unsupported branch.
ConstraintSupportRow
dataclass
¶
One auditable derivative-support decision.
Parameters¶
capability:
Stable operation or constraint name.
status:
supported, unsupported, or explicitly descoped.
differentiability:
Mathematical class of the exact operation under review.
evidence:
Concrete reason or implemented derivative rule.
boundary:
What the row does not establish.
DifferentiabilityReport
dataclass
¶
Ordered derivative-support decisions for one exact projection point.
Parameters¶
rows: Non-empty, capability-unique decisions in production projection order. claim_boundary: Human-readable limit on what the local report establishes.
Notes¶
derivative_supported is true only when every row is supported. A
descoped row therefore blocks JVP/VJP execution just like an unsupported
row; callers cannot accidentally treat omitted mathematics as identity.
Parity-sector projection¶
scpn_quantum_control.dla_topology_control.parity
¶
Linear parity-sector projection with exact JVP, VJP, and leakage gradient.
ParityLeakageEvaluation
dataclass
¶
Parity leakage value and Euclidean complex gradient.
gradient represents derivatives with respect to real and imaginary
components under the real inner product. For absolute leakage mass it is
2 * outside_sector(state).
Parameters¶
value:
Absolute outside-sector squared norm or its normalised fraction.
gradient:
Read-only complex gradient with the same shape as the evaluated state.
normalised:
Whether value is divided by total state norm squared.
state_norm_squared:
Positive total squared norm used by the evaluation.
ParitySectorProjector
dataclass
¶
Project finite state vectors into one computational-basis parity sector.
Parameters¶
n_qubits: Positive number of qubits. The dense local API is capped at 20 qubits to prevent accidental exponential allocation. sector: Even or odd Hamming-weight sector.
Notes¶
The forward map delegates to the existing DLA-parity projector. It is a fixed self-adjoint linear map, so its JVP and VJP are the same projection. This does not prove that an arbitrary Hamiltonian or ansatz preserves the selected sector.
dimension
property
¶
Return the dense Hilbert-space dimension 2**n_qubits.
mask
property
¶
Return a read-only basis mask for the selected parity sector.
as_state(state, *, name='state')
¶
Validate and copy a dense vector into immutable complex custody.
Parameters¶
state:
State-like vector with shape (2**n_qubits,).
name:
Field name included in validation errors.
Returns¶
numpy.ndarray
Read-only complex128 copy; caller memory is never aliased.
Raises¶
ValueError If rank, length, or finiteness violates the dense-state contract.
project(state)
¶
Project a dense vector into this computational-basis parity sector.
The forward calculation delegates to the existing
analysis.dla_parity_theorem.project_to_parity_sector owner.
Parameters¶
state:
Finite complex vector with shape (2**n_qubits,).
Returns¶
numpy.ndarray Read-only projected complex vector of the same shape.
jvp(tangent)
¶
Apply the exact projector Jacobian to a tangent vector.
Because the parity projector is fixed and linear, the JVP is the same
parity projection. The input and read-only output both have shape
(2**n_qubits,).
vjp(cotangent)
¶
Apply the exact adjoint projector Jacobian to a cotangent.
The projector is self-adjoint, so this VJP uses the same projection as
project and jvp. The returned complex vector is read-only.
leakage_value_and_gradient(state, *, normalised=False)
¶
Return outside-sector mass or fraction and its analytic gradient.
Parameters¶
state:
Finite dense complex vector of shape (2**n_qubits,).
normalised:
If false, return absolute outside-sector squared norm. If true,
divide by total squared norm and differentiate that quotient.
Raises¶
ValueError If the state is zero, malformed, or non-finite.
Returns¶
ParityLeakageEvaluation Leakage value, exact Euclidean complex gradient, normalisation mode, and the positive total norm used by the calculation.
Topology projection sensitivity¶
scpn_quantum_control.dla_topology_control.projection
¶
Fail-closed JVP/VJP contracts around the existing topology ledger.
TopologyProjectionDifferential
dataclass
¶
One exact topology-ledger projection and its local JVP.
Arrays are copied and read-only. projected_tangent is valid only for
the fixed active set recorded by support.
Parameters¶
matrix:
Finite square primal matrix copied into the record.
tangent:
Finite square tangent with the same shape.
projected:
Output of the production TopologyConstraintLedger.project call.
projected_tangent:
Exact local JVP for the recorded fixed active set.
support:
Fully supported derivative report for the exact primal point.
content_digest:
SHA-256 binding arrays and support decisions.
claim_boundary:
Limit on discrete, physical, and operational interpretation.
topology_projection_support(ledger, matrix, *, margin=1e-08)
¶
Classify the exact active branch of TopologyConstraintLedger.project.
The report is deliberately conservative. Symmetry, masks, and frozen edges are affine. Sign and clipping branches are supported only away from kinks. Inactive total-weight intervals are supported; active rescaling and connectivity thresholds fail closed.
Parameters¶
ledger: Existing production topology constraint ledger. matrix: Finite square primal point. margin: Positive distance used to reject branch boundaries.
Returns¶
DifferentiabilityReport Ordered decisions for symmetry, sign, bounds, masks, frozen edges, total-weight policy, and algebraic-connectivity policy.
Raises¶
ValueError If the ledger, matrix, margin, or configured reference is invalid.
topology_projection_jvp(ledger, matrix, tangent, *, margin=1e-08)
¶
Return the production-ledger projection and exact local JVP.
Raises¶
UnsupportedDifferentiableConstraintError
If any exact active branch lacks a supported derivative rule.
ValueError
If matrices or margin violate their contracts.
Returns¶
TopologyProjectionDifferential Production forward projection, exact supported local JVP, immutable input custody, support report, and content digest.
topology_projection_vjp(ledger, matrix, cotangent, *, margin=1e-08)
¶
Apply the exact local adjoint Jacobian on a supported active branch.
Parameters¶
ledger:
Existing production topology constraint ledger.
matrix:
Finite square primal point at which the active set is classified.
cotangent:
Finite square output cotangent with the same shape as matrix.
margin:
Positive refusal distance around sign and clipping boundaries.
Returns¶
numpy.ndarray Read-only input cotangent produced by the exact local adjoint rule.
Raises¶
UnsupportedDifferentiableConstraintError
If any active operation has no supported derivative.
ValueError
If matrices, ledger configuration, or margin is invalid.
Synthetic protected objective¶
scpn_quantum_control.dla_topology_control.objectives
¶
Analytic synthetic objective inside a fixed DLA-parity sector.
ParityProtectedObjectiveEvaluation
dataclass
¶
Decomposed objective value and analytic gradient for one dense state.
Parameters¶
value: Non-negative total objective. target_distance: Half squared Euclidean distance from the configured target. leakage_mass: Absolute outside-sector squared norm before weighting. state: Read-only complex state copy used for this evaluation. gradient: Read-only exact Euclidean complex gradient. claim_boundary: Limit on physical and operational interpretation.
ParityProtectedQuadraticObjective
dataclass
¶
Target-distance objective with an analytic outside-sector penalty.
Parameters¶
projector: Fixed parity-sector projector defining the protected subspace. target_state: Finite non-zero vector lying entirely in the selected sector. leakage_weight: Non-negative coefficient multiplying absolute outside-sector mass.
Notes¶
For state psi and target tau, the objective is
0.5 * ||psi - tau||^2 + leakage_weight * ||Q psi||^2 where
Q = I - P. This is a synthetic differentiable task, not a physical
control Hamiltonian or a controllability certificate.
evaluate(state)
¶
Evaluate the objective and exact Euclidean complex gradient.
Parameters¶
state: Finite dense complex vector matching the configured projector.
Returns¶
ParityProtectedObjectiveEvaluation Total value, target-distance term, unweighted leakage mass, input custody, and analytic gradient.
Raises¶
ValueError
If state has the wrong shape or contains non-finite values.
__call__(state)
¶
Return the scalar objective value.
Projected-gradient loop¶
scpn_quantum_control.dla_topology_control.optimizer
¶
Deterministic projected-gradient loop for a synthetic parity-sector task.
ProjectedGradientConfig
dataclass
¶
Backtracking policy for parity-projected gradient descent.
Parameters¶
max_steps:
Maximum number of accepted or terminal proposal records.
initial_step_size:
Positive step size tried first at every iteration.
contraction:
Multiplicative factor in (0, 1) for each backtrack.
max_backtracks:
Maximum contractions before a proposal is rejected.
gradient_tolerance:
Non-negative norm threshold for convergence.
minimum_step_size:
Smallest positive step size eligible for evaluation.
ProjectedGradientStep
dataclass
¶
One accepted or fail-closed projected-gradient proposal.
The record binds proposal index, backtracking count, objective/leakage before and after projection, gradient norm, and the immutable resulting state. Rejected records use zero step size and preserve the prior value.
ParityProjectedOptimisationTrace
dataclass
¶
Immutable initial/final states and ordered projected-gradient steps.
Parameters¶
initial_state: Validated pre-optimisation state, which may contain leakage. final_state: Last accepted parity-projected state. steps: Ordered accepted steps and, if backtracking fails, one terminal rejected step. content_digest: SHA-256 binding the initial/final arrays and every scalar/state record. claim_boundary: Explicit finite synthetic and no-actuation boundary.
accepted_steps
property
¶
Return the number of strict-decrease proposals accepted.
optimise_parity_protected_state(initial_state, objective, config=None)
¶
Run local projected gradient descent with strict-decrease backtracking.
Projection occurs inside every proposal. The returned state is a local numerical value and is never applied to a circuit, provider, or device.
Parameters¶
initial_state:
Finite dense complex state matching objective.projector.
objective:
Validated parity-protected quadratic objective.
config:
Optional backtracking policy; defaults to ProjectedGradientConfig.
Returns¶
ParityProjectedOptimisationTrace Immutable initial/final states, ordered proposals, and custody digest.
Raises¶
ValueError If the objective, config, or initial state violates its public contract.
Evidence contracts¶
scpn_quantum_control.dla_topology_control.evidence
¶
Deterministic evidence custody for DLA/topology constrained control.
DlaTopologyControlEvidence
dataclass
¶
Frozen synthetic evidence and exact derivative-support rows.
Parameters¶
schema_version, generated_on: Versioned evidence schema and fixed generation date. n_qubits, sector: Dense synthetic parity problem size and selected sector. initial_objective, final_objective: Objective endpoints; construction requires strict decrease. initial_leakage_mass, final_leakage_mass: Unnormalised outside-sector mass endpoints. accepted_steps: Positive count of strict-decrease projected steps. parity_gradient_max_abs_error, parity_jvp_max_abs_error: Maximum analytic-versus-central-difference errors. topology_jvp_max_abs_error, topology_adjoint_error: Fixed-active-set finite-difference and JVP/VJP identity errors. existing_optimizer_final_violation: Final production-ledger violation from the composed existing SPSA path. topology_differential_digest, trace_digest: SHA-256 custody digests for the local topology record and optimisation trace. unsupported_blockers: Ordered unique names of deliberately refused topology branches. support: Ordered BL-54 slice decisions, including the descoped QGNN wiring row. claim_boundary: Finite synthetic, no-hardware interpretation boundary. content_digest: SHA-256 of every preceding canonical evidence field.
to_dict(*, include_digest=True)
¶
Return deterministic JSON-compatible evidence data.
Parameters¶
include_digest:
Include the top-level content_digest field when true. False is
useful when independently recomputing the canonical digest.
Returns¶
dict[str, object] Ordered semantic fields whose nested support rows contain only JSON-native values.
build_dla_topology_control_evidence(*, n_qubits=4, seed=540)
¶
Build the deterministic finite synthetic BL-54 evidence bundle.
The builder checks parity objective gradients and projector JVPs against central differences, a topology-ledger JVP against the production forward map, the JVP/VJP adjoint identity, fail-closed blocker discovery, and final constraint compliance of the existing projected SPSA optimiser.
Parameters¶
n_qubits:
Dense local parity problem size in [2, 8].
seed:
Integer seed controlling every synthetic array and SPSA perturbation.
Returns¶
DlaTopologyControlEvidence Immutable metrics, support rows, blockers, and custody digests.
Raises¶
ValueError
If n_qubits or seed violates the bounded public contract.
render_dla_topology_control_markdown(evidence)
¶
write_dla_topology_control_evidence(evidence, *, json_path, markdown_path, check=False)
¶
Write or byte-check canonical JSON and Markdown evidence files.
Parameters¶
evidence: Validated immutable evidence object. json_path, markdown_path: Destination paths for sorted UTF-8 JSON and rendered Markdown. check: If true, perform a read-only byte comparison and refuse any drift. If false, create parent directories and replace both exact artefacts.
Returns¶
tuple[pathlib.Path, pathlib.Path] JSON and Markdown paths in argument order.
Raises¶
RuntimeError In check mode when either file is absent or differs byte-for-byte. OSError If filesystem reads, directory creation, or writes fail.