DLA and Topology-Constrained Differentiable Control

This package exposes a bounded local derivative surface for two different constrained objects:

1. a fixed computational-basis parity projector associated with the repository's DLA-parity work; and
2. 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. This package 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. The deterministic 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: b97043be4bb4b5d3060d30c61f3afc25b290bd18520c60410e6eed4c887e4c5b. 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.

Capability decisions

The differentiability boundary, existing-contract inventory, projections, constrained optimiser, deterministic evidence, and constraint-versus-witness documentation are implemented with exact local evidence. Optional QGNN wiring is explicitly descoped: the current 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

This 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.