Skip to content

Geometry Constraints

Purpose

Geometry constraints project the coupling matrix K_nm into a feasible set after each modification. This enforces structural invariants that the supervisor's ControlActions cannot violate.

Constraint Catalogue

Constraint Effect Idempotent Implementation
SymmetryConstraint K' = 0.5 * (K + K^T) Yes coupling/geometry_constraints.py
NonNegativeConstraint K' = max(K, 0) Yes coupling/geometry_constraints.py

Constraints are applied in order via project_knm(knm, constraints). The composition of idempotent projections is not generally idempotent, but the alternating-projection pattern converges to the intersection of convex sets (Bauschke & Combettes, 2011).

Projection API

project_knm(knm: NDArray, constraints: list[GeometryConstraint]) -> NDArray

Returns a new array; the input is not mutated.

Binding Spec Configuration

geometry_prior:
  constraint_type: symmetric_non_negative
  params: {}

The constraint_type string is parsed as a keyword bag:

  • Contains "symmetric" → SymmetryConstraint added.
  • Contains "non_negative" or "nonneg" → NonNegativeConstraint added.

Integration Point

When binding_spec.geometry_prior is present, the CLI run loop applies project_knm to the effective K_nm after imprint modulation and before each UPDE step.

Properties

  • Symmetry: after projection, K_nm == K_mn to machine precision.
  • Non-negativity: after projection, K_nm >= 0 elementwise.
  • Diagonal: diagonal of K_nm is not modified by these constraints. Domainpacks that require zero self-coupling should set diag(K) = 0 in the coupling builder.

Operations rationale

Geometry constraints are a safety surface between a mathematically designed control policy and deployment reality:

  • Symmetric projection removes asymmetry that can be introduced by estimation noise.
  • Non-negativity preserves physically interpretable excitatory coupling in the standard production profile.
  • Projections are deterministic and ordered, so audit evidence can attribute later changes to explicit constraints rather than optimizer side effects.

References

  • src/scpn_phase_orchestrator/coupling/geometry_constraints.py — constraint classes.
  • H. H. Bauschke & P. L. Combettes (2011). Convex Analysis and Monotone Operator Theory in Hilbert Spaces. Springer. — alternating projections convergence.

Why geometry projection is a production gate

Geometry projection is one of the few places where numerical updates become governance decisions. It is deliberately placed on the control path because it normalises effective couplings before physics integration, reducing surprise from late-bound estimator noise.

This constraint stack is intentionally small and interpretable: it does not hide optimization logic, but it does prevent accidental topology pathologies from reaching downstream integration.

In deployment, this is typically where an incident review starts: if simulation diverges but constraints were applied deterministically, the issue is more likely in policy, monitoring, or binding intent than in numerical plumbing.