Structured Equilibrium Families

These public classes implement monotone, positive-concave, non-Euclidean, spectral graph, multiscale graph, and delta-cached SILVA equilibria. Operators, sources, activations or proximal maps, readouts, solvers, and diagnostics remain independently configurable.

Source-Aligned Options

• SILVAPositiveConcaveEquilibrium(..., weight_parameterization="source_weight_norm") exposes the reference direction/magnitude parameterization. Call project_nonnegative_() after every optimizer update.
• SILVAMultiscaleGraphImplicitNetwork(..., graph_source=module) accepts a callable module(features, graph_operator) for a configurable \(f(X,G)\) injection. The default source remains a feature-only projection.
• SILVADeltaEquilibrium follows full-map training and delta-cached evaluation by default. Explicit delta-forward training requires implicit or phantom differentiation and evaluates backward sensitivity with the exact full map.

These options preserve the existing defaults. Source benchmark equivalence still requires the cited task architecture, data split, preprocessing, checkpoint or training schedule, and metric protocol.

Operational Contract

This API surface connects structured equilibrium operators to the same SILVA experiment contract used by the learning pages and notebooks. Its central relation is

\[ F_\theta(z;x)=z-\mathcal T_\theta(z;x)=0,\qquad C_\theta(z,x)\geq 0 \]

Part	What must remain inspectable
State	the equilibrium state together with the family certificate or operator statistics.
Condition	the returned certificate must be recomputable from public state, operator, and configuration fields.
Diagnostic	exact residual and the named structural certificate.
Replacement point	the dense or factorized operator, activation, graph spectrum, scale mixer, or delta policy.
Scale axes	operator rank, state width, graph scale, solver tolerance, and cache threshold.

The relevant method lineage is recorded in [75] through [80]. Those references define the source mechanisms; this API exposes them through SILVA objects so a reader can inspect, replace, solve, differentiate, and scale the construction.

Complete Compact Study

Run the complete repository program below from the project root. The page uses the same file that is exercised by the test suite, so the displayed call is not an isolated fragment.

"""Run the six structured SILVA equilibrium families on compact exact data."""

from __future__ import annotations

import torch
from torch import nn

from silva_networks import (
    SILVADeltaEquilibrium,
    SILVAEfficientInfiniteGraphEquilibrium,
    SILVAMonotoneOperatorEquilibrium,
    SILVAMultiscaleGraphImplicitNetwork,
    SILVANonEuclideanEquilibrium,
    SILVAPositiveConcaveEquilibrium,
    SolverConfig,
    make_delta_heterogeneous_dataset,
    make_eignn_chain_dataset,
    make_mgnni_multiscale_dataset,
    make_monotone_operator_dataset,
    make_non_euclidean_robustness_dataset,
    make_positive_concave_dataset,
)


def compact_config(*, graph: bool = False) -> SolverConfig:
    """Return a deterministic configuration suitable for the compact examples."""

    return SolverConfig(
        solver="picard",
        max_iter=80,
        tol=1e-6,
        anderson_batch_dims=0 if graph else 1,
        backward_mode="unrolled",
    )


def run_monotone_operator() -> None:
    data = make_monotone_operator_dataset(samples=8)
    model = SILVAMonotoneOperatorEquilibrium(
        4,
        6,
        2,
        splitting="peaceman_rachford",
        step_size=0.5,
        margin=0.5,
        config=compact_config(),
    )
    result = model(data.inputs, return_result=True)
    print(
        "monotone operator",
        result.output.shape,
        "certificate",
        float(result.monotonicity_certificate),
    )


def run_positive_concave() -> None:
    data = make_positive_concave_dataset(samples=8)
    model = SILVAPositiveConcaveEquilibrium(
        3,
        5,
        1,
        variant=1,
        activation="softsign",
        config=compact_config(),
    )
    result = model(data.inputs, return_result=True)
    print(
        "positive concave",
        result.output.shape,
        "minimum state",
        float(result.state.min()),
    )


def run_non_euclidean() -> None:
    data = make_non_euclidean_robustness_dataset(samples=8)
    model = SILVANonEuclideanEquilibrium(
        4,
        6,
        2,
        one_sided_bound=0.05,
        config=compact_config(),
    )
    result = model(data.inputs, return_result=True)
    print(
        "non-Euclidean",
        result.output.shape,
        "one-sided bound",
        float(result.one_sided_lipschitz),
    )


def run_efficient_graph() -> None:
    data = make_eignn_chain_dataset(nodes=12, state_dim=3)
    model = SILVAEfficientInfiniteGraphEquilibrium(
        3,
        3,
        1,
        gamma=data.gamma,
        solve_mode="closed_form",
        config=compact_config(graph=True),
    )
    result = model(data.inputs, data.graph_operator, return_result=True)
    print(
        "efficient infinite graph",
        result.output.shape,
        "spectral margin",
        float(result.denominator_margin),
    )


def run_multiscale_graph() -> None:
    data = make_mgnni_multiscale_dataset(
        nodes=12,
        state_dim=3,
        scales=(1, 2),
    )
    model = SILVAMultiscaleGraphImplicitNetwork(
        3,
        3,
        1,
        scales=(1, 2),
        gamma=data.gamma,
        config=compact_config(graph=True),
    )
    result = model(data.inputs, data.graph_operator, return_result=True)
    print(
        "multiscale graph",
        result.output.shape,
        "attention sums",
        result.attention_weights.sum(dim=1)[:3],
    )


def run_delta_equilibrium() -> None:
    data = make_delta_heterogeneous_dataset(samples=8, state_dim=4)
    recurrent = nn.Linear(4, 4, bias=False)
    with torch.no_grad():
        recurrent.weight.copy_(torch.diag(data.rates))
    model = SILVADeltaEquilibrium(
        3,
        4,
        1,
        recurrent=recurrent,
        delta_threshold=1e-3,
        config=SolverConfig(
            solver="picard",
            max_iter=160,
            tol=1e-6,
            backward_mode="unrolled",
        ),
    )
    model.eval()
    result = model(data.inputs, return_result=True)
    print(
        "delta equilibrium",
        result.output.shape,
        "mean active fraction",
        result.mean_active_fraction,
        "exact residual",
        result.exact_residual,
    )


def main() -> None:
    torch.manual_seed(91)
    run_monotone_operator()
    run_positive_concave()
    run_non_euclidean()
    run_efficient_graph()
    run_multiscale_graph()
    run_delta_equilibrium()


if __name__ == "__main__":
    main()

python examples/structured_equilibria.py

Measured Compact Output

monotone operator torch.Size([8, 2]) certificate 0.5005146265029907
positive concave torch.Size([8, 1]) minimum state 0.042785972356796265
non-Euclidean torch.Size([8, 2]) one-sided bound 0.04999999701976776
efficient infinite graph torch.Size([12, 1]) spectral margin 0.44062745571136475
multiscale graph torch.Size([12, 1]) attention sums tensor([1.0000, 1.0000, 1.0000])
delta equilibrium torch.Size([8, 1]) mean active fraction 0.2036637931034483 exact residual 0.0014585574390366673

Interpret the Output

All six outputs retain their own certificate. This prevents a low task loss from hiding a failed positivity, monotonicity, spectral, multiscale, or cache contract.

For a controlled experiment, retain the compact call as a regression case and change one scale axis at a time. Record the resolved constructor, data source and split, preprocessing, seed, forward and backward solver settings, task metric, normalized residual, iteration count, runtime, peak memory, and any failed convergence case. A larger run becomes evidence only when its own resolved configuration and outputs are archived; the compact output above is evidence for the executable mechanism and its stated invariants.

silva_networks.structured_equilibria

Guaranteed, multiscale, and accelerated equilibrium families in SILVA.

The implementations in this module express six published mechanisms through ordinary PyTorch modules and SILVA solver contracts. Every model keeps its source injection, recurrent operator, numerical method, activation or proximal map, and readout replaceable so compact checks and source-scale experiments use the same public surface.

SILVAMonotoneDenseOperator

Bases: Module

Dense monotone operator parameterized as in monDEQ.

\[ W=(1-m)I-A^\mathsf{T}A+B-B^\mathsf{T},\qquad m>0. \]

The symmetric part of I-W is bounded below by m I. The class supplies multiplication and the linear resolvent required by Peaceman-Rachford splitting.

matrix

matrix()

Materialize the recurrent matrix W.

resolvent

resolvent(values, step_size)

Apply ((1+a)I-aW)^{-1} to row-major state vectors.

monotonicity_certificate

monotonicity_certificate()

Return the smallest eigenvalue of the symmetric part of I-W.

SILVAMonotoneOperatorOutput dataclass

Readout, latent equilibrium, trace, and monotonicity certificate.

SILVAMonotoneOperatorEquilibrium

Bases: Module

General monotone-operator equilibrium with two published splittings.

The latent inclusion is

\[ 0\in (I-W)z-Ux-b+\partial f(z), \]

whose fixed point is z = prox(W z + U x + b). The default proximal map is ReLU. operator may be replaced by a structured module implementing forward(state), resolvent(values, step_size), and monotonicity_certificate().

SILVAPositiveConcaveTransition

Bases: Module

Nonnegative linear or convolutional map followed by a PC activation.

softplus is a smooth SILVA parameterization. projected uses a direct projected weight. source_weight_norm separates positive direction and magnitude parameters as in the reference implementation. Call :meth:project_nonnegative_ after each optimizer update for either projection-based mode.

positive_weight

positive_weight()

Return the differentiable nonnegative recurrent weight.

project_nonnegative_

project_nonnegative_()

Project the stored recurrent weights onto the nonnegative orthant.

SILVAPositiveConcaveOutput dataclass

Prediction, positive state, trace, and nonnegative-weight certificate.

SILVAPositiveConcaveEquilibrium

Bases: Module

Positive-concave equilibrium with linear and convolutional variants.

\[ z^\star=\phi(W_+z^\star+x_+),\qquad W_+\geq0,\quad x_+\geq0. \]

Variant 1 accepts tanh, softsign, or relu6 after a strictly positive source injection. Variant 2 uses sigmoid after a nonnegative source injection. A custom transition may replace the packaged positive operator while preserving the same solver and readout contract.

project_nonnegative_

project_nonnegative_()

Apply a source-style nonnegative projection after an optimizer step.

SILVANonEuclideanDenseOperator

Bases: Module

Dense NEMON parameterization with a weighted infinity certificate.

With D=diag(exp(d)) and free A, the recurrent matrix is

\[ W=mI+D^{-1}AD-\operatorname{diag}(|A|\mathbf 1). \]

Therefore mu_inf(D W D^{-1}) <= m.

weighted_matrix_measure

weighted_matrix_measure()

Return mu_inf(D W D^-1) computed from the current parameters.

diagonal_lower_bound

diagonal_lower_bound()

Lower bound on diagonal derivatives of relu(Wz+b).

recommended_averaging

recommended_averaging()

Return alpha*=1/(1-diagL) from the weighted-infinity result.

SILVANonEuclideanOutput dataclass

Prediction, equilibrium, trace, and weighted robustness diagnostics.

SILVANonEuclideanEquilibrium

Bases: Module

NEMON-style weighted-infinity equilibrium and sensitivity bound.

The averaged iteration preserves the equilibrium of z = relu(W z + U x + b):

\[ z_{k+1}=(1-\alpha)z_k+\alpha\operatorname{ReLU}(Wz_k+Ux+b). \]

SILVAGraphSpectrum dataclass

Eigenvalues and eigenvectors of a symmetric graph propagation matrix.

SILVAEfficientGraphOutput dataclass

Graph prediction, equilibrium, numerical record, and spectral margin.

SILVAEfficientInfiniteGraphEquilibrium

Bases: Module

EIGNN closed-form or iterative infinite-depth graph equilibrium.

In node-major notation,

\[ Z^\star=\gamma S^\mathsf{T}Z^\star g(F)^\mathsf{T}+X. \]

Symmetric dense graph operators can use the eigendecomposed closed form. Sparse or directed operators use the same equation through a SILVA solver.

precompute_spectrum staticmethod

precompute_spectrum(graph_operator)

Compute and validate a reusable symmetric graph eigendecomposition.

SILVAMultiscaleGraphOutput dataclass

Fused graph output, per-scale states, traces, and nodewise weights.

SILVAMultiscaleGraphImplicitNetwork

Bases: Module

MGNNI parallel graph equilibria with nodewise scale fusion.

Each scale m solves

\[ Z_m^\star=\gamma g(F_m)Z_m^\star S^m+f(X,G), \]

followed by beta_mi=q^T tanh(W_a z_mi+b_a) and a softmax over scales. Node-major tensors are used by the public API.

SILVADeltaOperatorStats dataclass

Activity retained by one thresholded delta update.

SILVADeltaOperator

Bases: Module

Cache a linear or convolutional operator and update it from state deltas.

For a linear map L(z)=Wz+b and thresholded Delta z_k = mask(|z_k-z_{k-1}|>tau)(z_k-z_{k-1}), the cache obeys

\[ c_k=c_{k-1}+W\Delta z_k. \]

tau=0 is algebraically equivalent to full recomputation. Standard Linear and Conv1d/2d/3d modules are supported directly; a custom module should be bias-free or expose a tensor bias attribute.

reset

reset()

Clear state and output caches before a new independent solve.

full

full(values)

Evaluate the wrapped operator without reading or changing the cache.

SILVADeltaEquilibriumOutput dataclass

Prediction, state, trace, delta activity, and exact residual.

SILVADeltaEquilibrium

Bases: Module

DEQ with thresholded cached recurrent evaluations during inference.

The source-aligned route trains with the full SILVA fixed-point map and uses cached recurrent evaluations at inference. SILVA additionally permits a delta-cached forward solve during training when implicit or phantom differentiation is configured; its backward sensitivity is evaluated with the exact full map. Unrolled differentiation is intentionally rejected for that extension because the cache mutates across forward iterations.

silva_normalized_gram

silva_normalized_gram(factor, epsilon=1e-12)

Return the normalized positive-semidefinite map used by EIGNN and MGNNI.

\[ g(F)=\frac{F^\mathsf{T}F}{\lVert F^\mathsf{T}F\rVert_F+\epsilon_F}. \]

Where to Go Next

Question	Page
How are the equations derived?	Structured Equilibrium Families
Which compact data have known solutions?	Structured Equilibrium Data
How are the six mechanisms run together?	Structured Equilibria Example
How do compact checks become source-scale studies?	Reconstructing Paper Experiments