DLA and Topology-Constrained Differentiable Control¶

BL-54 exposes a bounded local derivative surface for two different constrained objects:

a fixed computational-basis parity projector associated with the repository's DLA-parity work; and
the existing coupling-graph TopologyConstraintLedger on projection branches whose active set is fixed and differentiable.

The implementation does not equate Hilbert-space parity with graph topology. It also does not duplicate the existing projected SPSA/COBYLA optimisers or persistent-homology objectives.

What the product does¶

The public scpn_quantum_control.dla_topology_control facade supports:

immutable even/odd parity-sector projectors for finite dense state vectors;
exact projector Jacobian-vector and vector-Jacobian products;
absolute or normalised outside-sector leakage with analytic gradients;
a synthetic target-distance objective with an outside-sector penalty;
strict-decrease projected gradient descent with projection inside every proposal;
fixed-active-set JVP/VJP records around the production topology ledger;
explicit support reports that reject non-smooth or discrete branches;
deterministic JSON/Markdown evidence and byte checks.

Every returned array is copied and read-only. Nothing is submitted, actuated, deployed, or applied to a circuit or device.

DLA, parity, and topology are distinct¶

A dynamical Lie algebra (DLA) is generated by repeated commutators of the available Hamiltonian generators. Its block structure can reveal invariant subspaces and subspace controllability. BL-54 does not calculate or classify a DLA. It composes the repository's existing DLA-parity result: the relevant XY Hamiltonian terms preserve global computational-basis parity.

For \(n\) qubits, define

\[ P = \bigotimes_{j=1}^{n} Z_j, \qquad P_s = \frac{I + (-1)^s P}{2}, \qquad s\in\{0,1\}. \]

ParitySector.EVEN uses \(s=0\); ParitySector.ODD uses \(s=1\). The public projector delegates its forward map to the existing analysis.dla_parity_theorem.project_to_parity_sector owner. Because \(P_s\) is a fixed self-adjoint linear map,

\[ \operatorname{JVP}_{P_s}(v)=P_s v, \qquad \operatorname{VJP}_{P_s}(\bar v)=P_s\bar v. \]

This proves the derivative of the projector. It does not prove that an arbitrary Hamiltonian, ansatz, noise channel, or hardware execution preserves the sector.

Graph topology is a separate object: a real coupling matrix constrained by bounds, signs, masks, frozen edges, budgets, or connectivity requirements. Persistent homology and algebraic connectivity diagnose graph structure; they are not synonyms for DLA blocks or parity sectors.

Scientific basis¶

Wiersema, Kökcü, Kemper, and Bakalov classify DLAs of 2-local spin systems and discuss symmetry blocks and subspace controllability: npj Quantum Information 10, 110 (2024), DOI 10.1038/s41534-024-00900-2.
Bonet-Monroig, Sagastizabal, Singh, and O'Brien study conserved-symmetry verification: Physical Review A 98, 062339 (2018), DOI 10.1103/PhysRevA.98.062339.
Amos and Kolter derive sensitivity through a supported constrained optimisation layer in “OptNet”, ICML/PMLR 70 (2017), paper.
Agrawal et al. describe differentiable disciplined convex programmes and their affine-solver-affine form, arXiv:1910.12430.

These sources constrain terminology and the derivative boundary. They do not validate repository thresholds, hardware protection, error correction, controllability, an arbitrary solver derivative, or an application claim.

Minimal parity-protected workflow¶

import numpy as np

from scpn_quantum_control.dla_topology_control import (
    ParityProtectedQuadraticObjective,
    ParitySector,
    ParitySectorProjector,
    ProjectedGradientConfig,
    optimise_parity_protected_state,
)

projector = ParitySectorProjector(3, ParitySector.EVEN)
target = projector.project(
    np.array([1.0, 0.0, 0.0, 0.0, 0.0, 0.5j, -0.2, 0.0])
)
target = target / np.linalg.norm(target)

objective = ParityProtectedQuadraticObjective(
    projector,
    target,
    leakage_weight=2.0,
)
initial = target + 0.25 * np.arange(projector.dimension)
trace = optimise_parity_protected_state(
    initial,
    objective,
    ProjectedGradientConfig(max_steps=16, initial_step_size=0.5),
)

assert objective(trace.final_state) < objective(initial)
assert objective.evaluate(trace.final_state).leakage_mass == 0.0
assert not trace.final_state.flags.writeable

The trace is a local numerical record. “Protected” means that hard projection keeps accepted candidate vectors inside one selected synthetic parity sector; it does not mean error-corrected, noise-protected, or hardware-protected.

Objective and leakage gradients¶

Let \(Q_s=I-P_s\), target \(\tau\) lie in the selected sector, and state \(\psi\) be an arbitrary finite vector. The synthetic objective is

\[ L(\psi)=\frac{1}{2}\lVert\psi-\tau\rVert_2^2 + \lambda\lVert Q_s\psi\rVert_2^2, \]

with Euclidean complex gradient, represented as real/imaginary coordinate derivatives,

\[ \nabla L(\psi)=\psi-\tau+2\lambda Q_s\psi. \]

leakage_value_and_gradient(..., normalised=False) returns the absolute outside-sector mass and gradient \(2Q_s\psi\). With normalised=True, it returns \(\lVert Q_s\psi\rVert^2/\lVert\psi\rVert^2\) and differentiates the quotient. A zero state raises because that fraction is undefined.

Topology projection derivative boundary¶

topology_projection_support(ledger, matrix) analyses the exact primal point before a derivative is returned. The JVP/VJP wrapper calls the production TopologyConstraintLedger.project; it does not implement a second forward projection.

Ledger operation	Local derivative rule	Failure boundary
Symmetrise + zero diagonal	Fixed self-adjoint linear map	None for finite square matrices
`signed` policy	Identity	Policy changes are discrete
`nonnegative` policy	Fixed positive/negative branch	Exact or near-zero kink raises
`fixed_sign` policy	Fixed-sign absolute-value branch	Missing/mismatched reference or zero kink raises
Uniform bounds	Identity or zero on a fixed clip branch	Lower/upper boundary raises
Hardware edge mask	Fixed elementwise linear mask	Changing the edge set is not differentiated
Frozen edges	Affine overwrite; zero tangent	Changing edge identity/value is not differentiated
Total-weight interval	Identity only when strictly inactive	Active rescaling or interval boundary raises
Algebraic-connectivity minimum	No projection derivative exposed	Positive threshold is unsupported
Persistent-homology objective	No derivative exposed	Discrete/non-smooth PH branch is unsupported

The active-set margin defaults to 1e-8. It is a numerical refusal margin, not a theorem about distance from every possible degeneracy.

Topology JVP/VJP example¶

import numpy as np

from scpn_quantum_control.dla_topology_control import (
    topology_projection_jvp,
    topology_projection_vjp,
)
from scpn_quantum_control.topology_control import (
    CouplingGraphBounds,
    TopologyConstraintLedger,
)

ledger = TopologyConstraintLedger(
    bounds=CouplingGraphBounds(-2.0, 2.0),
    sign_policy="signed",
    hardware_edges={(0, 1), (1, 2), (2, 3), (0, 3)},
    frozen_edges={(0, 1): 0.25},
)
matrix = np.array(
    [
        [0.0, 0.4, -0.6, 0.7],
        [0.2, 0.0, 0.5, -0.4],
        [-0.3, 0.8, 0.0, 0.6],
        [0.9, -0.7, 0.2, 0.0],
    ]
)
tangent = np.ones((4, 4))
cotangent = np.eye(4)

differential = topology_projection_jvp(ledger, matrix, tangent)
adjoint = topology_projection_vjp(ledger, matrix, cotangent)

assert differential.support.derivative_supported
assert differential.projected.shape == (4, 4)
assert differential.projected_tangent.shape == (4, 4)
assert adjoint.shape == (4, 4)

At a nonnegative zero kink, active budget rescaling, or positive connectivity threshold, require_supported() raises UnsupportedDifferentiableConstraintError and names the blocking capability.

Existing optimiser composition¶

The older topology_control package already supplies ProjectedSPSAOptimizer and ProjectedScipyOptimizer. Both call the ledger inside their optimisation loop, so hard graph projection is not merely a post-hoc witness. Those methods optimise a non-smooth PH objective and do not claim analytic or automatic differentiation. BL-54 evidence runs the existing SPSA path and checks zero final ledger violation; it does not replace or relabel that optimiser.

Shapes, custody, and errors¶

Surface	Input	Output	Main refusal conditions
`ParitySectorProjector`	`n_qubits` in `[1, 20]`, enum sector	Dense mask `(2**n,)`	Unsafe size, wrong enum
`project`, `jvp`, `vjp`	Finite complex `(2**n,)`	Read-only complex `(2**n,)`	Wrong rank/length, non-finite
`leakage_value_and_gradient`	Non-zero finite complex `(2**n,)`	Scalar + read-only gradient	Zero norm, malformed state
`ParityProtectedQuadraticObjective`	In-sector non-zero target	Scalar/decomposition/gradient	Target outside sector, invalid weight
`optimise_parity_protected_state`	State, objective, config	Immutable trace	Invalid config or no strict decrease
`topology_projection_support`	Ledger + finite square `(N,N)`	Ordered support report	Invalid ledger/matrix/margin
`topology_projection_jvp`	Primal + tangent `(N,N)`	Projection + tangent + digest	Any unsupported active branch
`topology_projection_vjp`	Primal + cotangent `(N,N)`	Read-only adjoint tangent	Any unsupported active branch

Frozen evidence¶

The committed evidence uses four qubits, the even sector, seed 540, and a four-node masked/frozen-edge topology ledger.

Metric	Value
Initial objective	5.06651816681
Final objective	8.65715781265e-25
Initial outside-sector mass	1.60797013733
Final outside-sector mass	0
Accepted projected steps	40
Parity objective gradient max error	3.59233087721e-10
Parity projector JVP max error	9.98454884353e-11
Topology-ledger JVP max error	3.93055310521e-11
Topology adjoint-identity error	8.881784197e-16
Existing projected optimiser final violation	0

Evidence content digest: 0db6000ec6307389ffc4ddeda2f5a065a8cc481e9fe2defdbae0e9a1c14c926e. The exact JSON and rendered rows are in data/dla_topology_control/evidence.md.

Regenerate and byte-check locally:

PYTHONPATH=src:oscillatools/src python scripts/run_dla_topology_control_evidence.py
PYTHONPATH=src:oscillatools/src python scripts/run_dla_topology_control_evidence.py --check

Notebook 51_dla_topology_constrained_control.ipynb uses the public facade and local production ledger only.

Slice decisions¶

S54.0–S54.4 and S54.6 are implemented with exact local evidence. S54.5 is explicitly descoped: the current BL-42 QGNN surface consumes graph structure, while this product's DLA-parity projector acts on Hilbert-space amplitudes. No typed consumer maps those objects, so wiring them would create a false scientific correspondence.

Public API map¶

Responsibility	Public symbols
Support schema	`ConstraintSupportRow`, `DifferentiabilityKind`, `DifferentiabilityReport`, `UnsupportedDifferentiableConstraintError`
Parity sectors	`ParitySector`, `ParitySectorProjector`, `ParityLeakageEvaluation`
Topology sensitivity	`TopologyProjectionDifferential`, `topology_projection_support`, `topology_projection_jvp`, `topology_projection_vjp`
Synthetic objective	`ParityProtectedQuadraticObjective`, `ParityProtectedObjectiveEvaluation`
Projected loop	`ProjectedGradientConfig`, `ProjectedGradientStep`, `ParityProjectedOptimisationTrace`, `optimise_parity_protected_state`
Evidence	`DlaTopologyControlEvidence`, `build_dla_topology_control_evidence`, `render_dla_topology_control_markdown`, `write_dla_topology_control_evidence`

See the complete API reference for per-symbol parameters, returns, exceptions, shapes, and boundaries.

Scope and non-claims¶

BL-54 is finite synthetic derivative and software-custody evidence. It does not establish:

a full DLA classification or DLA dimension;
global, subspace, or hardware controllability;
differentiability of persistent homology or changing graph topology;
a derivative through active total-weight rescaling;
error correction, error mitigation, or noise protection;
hardware preservation of a parity signal;
QGNN, biological, EEG, plasma, grid, or other domain validity;
provider, QPU, hardware, deployment, advantage, or market efficacy.

Those claims require separate theory, protocols, data, and owner-authorised evidence.