Recent Equilibrium Dataset API
Deterministic field, graph, homotopy, and empirical-measure datasets for the recent SILVA equilibrium families.
The builders return typed batches with equation or moment checks. See the dataset-backed labs for derivations, training examples, and benchmark handoff guidance.
Operational Contract
This API surface connects operator, graph, homotopy, and measure data to the same SILVA experiment contract used by the learning pages and notebooks. Its central relation is
| Part | What must remain inspectable |
|---|---|
| State | regular-grid fields, graph states, continuation pairs, or variable-cardinality samples. |
| Condition | the batch must retain enough source information to recompute its equation or discrepancy. |
| Diagnostic | equation residual, analytic continuation error, or measure discrepancy. |
| Replacement point | the exact compact generator with an official split and preprocessing adapter. |
| Scale axes | resolution, graph size, continuation steps, particle count, and batch size. |
The relevant method lineage is recorded in [31] and [43] through [46]. 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.
"""Small reproducible runs for four recent SILVA equilibrium families."""
from __future__ import annotations
import torch
from torch import nn
from silva_networks import (
SILVAFNODEQ,
SILVADistributionalDEQ,
SILVAHomotopyEquilibrium,
SILVAPhysicsGuidedGraphDEQ,
SolverConfig,
make_affine_homotopy_dataset,
make_graph_transport_dataset,
make_periodic_elliptic_dataset,
make_variable_measure_dataset,
)
class AffineTransition(nn.Module):
"""Transition with the analytic fixed point z_star = 2 x."""
def forward(self, state: torch.Tensor, condition: torch.Tensor) -> torch.Tensor:
return 0.5 * state + condition
def run_fourier_equilibrium() -> dict[str, float | tuple[int, ...]]:
data = make_periodic_elliptic_dataset(
samples=1,
height=8,
width=8,
modes=2,
seed=31,
)
model = SILVAFNODEQ(
1,
4,
1,
modes_height=3,
modes_width=3,
state_scale=0.05,
config=SolverConfig(max_iter=12, tol=1e-6, alpha=1.0),
)
result = model(data.forcing, return_result=True)
return {
"shape": tuple(result.output.shape),
"residual": result.solver_result.residual,
"dataset_equation_residual": float(data.equation_residual().abs().max()),
}
def run_physics_graph_equilibrium() -> dict[str, float | tuple[int, ...]]:
data = make_graph_transport_dataset(samples=1, nodes=6, seed=32)
model = SILVAPhysicsGuidedGraphDEQ(
3,
5,
1,
config=SolverConfig(max_iter=20, tol=1e-6, alpha=0.8),
)
result = model(
data.x,
data.edge_index,
edge_weight=data.edge_weight,
edge_velocity=data.edge_velocity,
return_result=True,
)
return {
"shape": tuple(result.output.shape),
"residual": result.solver_result.residual,
"dataset_equation_residual": float(data.equation_residual().abs().max()),
}
def run_homotopy_equilibrium() -> dict[str, float | tuple[int, ...]]:
data = make_affine_homotopy_dataset(
samples=2,
dimension=1,
contraction=0.5,
seed=33,
)
model = SILVAHomotopyEquilibrium(
1,
1,
1,
transition=AffineTransition(),
readout=nn.Identity(),
steps=48,
horizon=10.0,
learnable_initial=False,
)
result = model(data.condition, return_result=True)
error = torch.max(torch.abs(result.output - data.target))
return {
"shape": tuple(result.output.shape),
"terminal_residual": result.terminal_residual,
"analytic_error": float(error.detach()),
}
def run_distributional_equilibrium() -> dict[str, float | tuple[int, ...]]:
data = make_variable_measure_dataset(
samples=1,
min_particles=4,
max_particles=6,
dimension=2,
seed=34,
)
model = SILVADistributionalDEQ(
2,
4,
particles=5,
heads=2,
kernel="gaussian",
step_size=0.2,
max_iter=5,
)
result = model(
data.context,
context_mask=data.context_mask,
return_result=True,
)
return {
"shape": tuple(result.state.shape),
"initial_discrepancy": result.discrepancies[0],
"final_discrepancy": result.discrepancies[-1],
}
def main() -> None:
torch.manual_seed(31)
print("SILVA Fourier equilibrium:", run_fourier_equilibrium())
print("SILVA physics graph equilibrium:", run_physics_graph_equilibrium())
print("SILVA homotopy equilibrium:", run_homotopy_equilibrium())
print("SILVA distributional equilibrium:", run_distributional_equilibrium())
if __name__ == "__main__":
main()
Measured Compact Output
SILVA Fourier equilibrium: {'shape': (1, 1, 8, 8), 'residual': 1.6093609644940443e-07, 'dataset_equation_residual': 5.960464477539062e-07}
SILVA physics graph equilibrium: {'shape': (6, 1), 'residual': 5.127419058226224e-07, 'dataset_equation_residual': 5.960464477539063e-08}
SILVA homotopy equilibrium: {'shape': (2, 1), 'terminal_residual': 0.00807332992553711, 'analytic_error': 0.01614689826965332}
SILVA distributional equilibrium: {'shape': (1, 5, 4), 'initial_discrepancy': 0.48991382122039795, 'final_discrepancy': 0.453036904335022}
Interpret the Output
The Fourier and graph batches satisfy their generating equations to about single-precision tolerance. The homotopy and distributional rows report finite-discretization behavior and therefore require a step or particle-count sweep.
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.frontier_data
Deterministic teaching datasets for recent SILVA equilibrium families.
SILVAPeriodicEllipticBatch
dataclass
SILVAGraphTransportBatch
dataclass
SILVAAffineHomotopyBatch
dataclass
SILVAVariableMeasureBatch
dataclass
make_periodic_elliptic_dataset
make_periodic_elliptic_dataset(*, samples=12, height=16, width=16, modes=3, mass=1.0, seed=0, dtype=torch.float32, device=None)
Generate exact periodic solutions of \((-\Delta+m)u=f\).
Random forcing fields are projected onto low Fourier modes. The target is obtained by dividing each retained coefficient by \(|k|^2+m\), so the discretized equation is satisfied up to transform roundoff.
make_graph_transport_dataset
make_graph_transport_dataset(*, samples=6, nodes=12, reaction_scale=0.05, diffusion_scale=0.2, advection_scale=0.05, seed=0, dtype=torch.float32, device=None)
Generate periodic graph solutions for a steady transport equation.
Each graph solves
The graphs share a ring discretization and differ in their smooth source.
Where to Go Next
| Question | Page |
|---|---|
| How is each generated dataset derived? | Dataset-Backed Equilibrium Labs |
| Which models consume these tensors? | Recent Equilibrium API |
| How are the four mechanisms related? | Recent Equilibrium Families |