Structured Equilibrium Data
The builders below create deterministic, compact problems with known equilibria, graph scale states, robustness perturbations, or heterogeneous convergence rates. They validate equations and interfaces without claiming the published source-scale benchmark results.
Operational Contract
This API surface connects structured equilibrium data contracts to the same SILVA experiment contract used by the learning pages and notebooks. Its central relation is
| Part | What must remain inspectable |
|---|---|
| State | positive vectors, transformed coordinates, graph signals, multiscale states, or cached deltas. |
| Condition | the generated sample carries the operator or perturbation needed to verify its certificate. |
| Diagnostic | certificate margin, one-sided perturbation, attention normalization, or cache error. |
| Replacement point | the synthetic source with an attributed image, graph, or geometric adapter. |
| Scale axes | sample count, node count, feature width, number of graph scales, and perturbation radius. |
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()
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
The compact run checks one defining property per family. Positivity, spectral margin, normalized attention, and delta activity are different contracts and should remain separate columns in a larger report.
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_data
Compact known-solution data for structured SILVA equilibrium families.
SILVAMonotoneOperatorBatch
dataclass
Affine source and known monotone-ReLU equilibrium regression task.
SILVAPositiveConcaveBatch
dataclass
Positive source, equilibrium, and output generated by a PC map.
SILVANonEuclideanBatch
dataclass
Nominal and perturbed inputs with exact weighted-infinity equilibria.
SILVAEfficientGraphBatch
dataclass
Chain graph, injected node features, and exact EIGNN equilibrium.
SILVAMultiscaleGraphBatch
dataclass
Graph signals and a target combining one-hop and multi-hop equilibria.
SILVADeltaConvergenceBatch
dataclass
Affine equilibrium with coordinates converging at different rates.
silva_chain_graph_operator
Return a symmetric normalized chain propagation matrix.
make_monotone_operator_dataset
Build a dense known-solution task satisfying a monotonicity margin.
make_positive_concave_dataset
Generate a bounded positive-concave tanh equilibrium.
make_non_euclidean_robustness_dataset
make_non_euclidean_robustness_dataset(*, samples=40, in_dim=4, state_dim=6, perturbation_radius=0.025, one_sided_bound=0.05, seed=83)
Generate a NEMON map and a bounded entrywise input perturbation.
make_eignn_chain_dataset
Create a long-range chain regression target from the EIGNN equation.
Where to Go Next
| Question | Page |
|---|---|
| Why does each builder have a known answer? | Structured Equilibrium Families |
| Which model consumes each batch? | Structured Equilibria API |
| Where are the executed plots and diagnostics? | Notebook Library |
| What changes at full scale? | Full-Scale SILVA |