Emerging Equilibrium Families
The public classes below implement eight additional equilibrium mechanisms with replaceable transitions, physical operators, numerical methods, and readouts. The compact defaults support inspection and tests; the same constructors accept benchmark-scale modules and data.
Operational Contract
This API surface connects emerging equilibrium mechanisms to the same SILVA experiment contract used by the learning pages and notebooks. Its central relation is
| Part | What must remain inspectable |
|---|---|
| State | a family-specific implicit state with an explicit condition bundle. |
| Condition | calling the transition again at the returned state must reproduce that state within the solver tolerance. |
| Diagnostic | family invariant plus normalized fixed-point residual. |
| Replacement point | every default backbone, processor, increment, deformation, energy, constitutive map, or denoiser. |
| Scale axes | state dimension, discretization size, trajectory depth, solver policy, and checkpoint schedule. |
The relevant method lineage is recorded in [59] through [64], [73], and [74]. 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 compact known-solution checks for eight emerging SILVA families."""
from __future__ import annotations
import torch
from torch import nn
from silva_networks import (
SILVAIFNO,
SILVASNARF,
SILVAConsistencyDEQ,
SILVAFixedPointDenoiser,
SILVAFixedPointDiffusionModel,
SILVAMeshInference,
SILVAPhysicsGuidedDiffusionPDE,
SILVAPsiGNN,
SILVATherINO,
SolverConfig,
finite_difference_poisson_energy,
make_consistency_teacher_dataset,
make_fixed_point_diffusion_dataset,
make_ifno_material_dataset,
make_mesh_gaussian_dataset,
make_poisson_diffusion_dataset,
make_psi_poisson_grid,
make_snarf_stick_dataset,
make_therino_elastic_dataset,
project_homogeneous_dirichlet,
)
class AffineTeacher(nn.Module):
def __init__(self, matrix: torch.Tensor, source: torch.Tensor, bias: torch.Tensor):
super().__init__()
self.register_buffer("matrix", matrix)
self.register_buffer("source", source)
self.register_buffer("bias", bias)
def forward(self, state: torch.Tensor, condition: torch.Tensor) -> torch.Tensor:
return state @ self.matrix.T + condition @ self.source.T + self.bias
class StickWeights(nn.Module):
def forward(self, points: torch.Tensor) -> torch.Tensor:
left = torch.sigmoid(-8.0 * points[..., 0])
return torch.stack([left, 1.0 - left], dim=-1)
class StickOccupancy(nn.Module):
def forward(self, points: torch.Tensor, pose: torch.Tensor | None = None) -> torch.Tensor:
del pose
return torch.sigmoid(20.0 * (0.12 - points[..., 1].abs())).unsqueeze(-1)
class MaterialRelaxation(nn.Module):
def __init__(self, target: torch.Tensor):
super().__init__()
self.register_buffer("target", target)
def forward(self, encoded: torch.Tensor) -> torch.Tensor:
state = encoded[:, : self.target.shape[1]]
return 0.2 * state + 0.8 * self.target
class TimestepRelaxation(nn.Module):
def forward(
self,
state: torch.Tensor,
injection: torch.Tensor,
time: torch.Tensor,
condition: torch.Tensor | None = None,
) -> torch.Tensor:
del condition
target = 0.5 * injection + 0.1 * time.reshape(-1, 1, 1, 1).to(state)
return 0.25 * state + 0.75 * target
def compact_results() -> dict[str, dict[str, float | tuple[int, ...]]]:
teacher_data = make_consistency_teacher_dataset(samples=4, state_dim=3, condition_dim=2)
consistency = SILVAConsistencyDEQ(
3,
2,
teacher_transition=AffineTeacher(
teacher_data.matrix, teacher_data.source_matrix, teacher_data.bias
),
teacher_config=SolverConfig(max_iter=20, tol=1e-7, anderson_batch_dims=1),
)
teacher = consistency.teacher_trajectory(teacher_data.condition)
accelerated = consistency(teacher_data.condition, steps=2, return_result=True)
psi_data = make_psi_poisson_grid(size=5)
psi = SILVAPsiGNN(
4,
config=SolverConfig(solver="picard", max_iter=8, backward_mode="unrolled"),
)
psi_result = psi(
psi_data.initial_solution,
psi_data.forcing,
psi_data.coordinates,
psi_data.edge_index,
psi_data.node_types,
boundary_values=psi_data.boundary_values,
normals=psi_data.normals,
return_result=True,
)
material = make_ifno_material_dataset(samples=2, height=4, width=8)
ifno = SILVAIFNO(4, 6, 1, depth=3, modes_height=2, modes_width=3)
ifno_result = ifno(material.inputs, return_result=True)
stick = make_snarf_stick_dataset(points=7)
snarf = SILVASNARF(
coordinate_dim=2,
bones=2,
weight_field=StickWeights(),
occupancy_field=StickOccupancy(),
correspondence_tol=2e-3,
config=SolverConfig(solver="broyden", max_iter=30, tol=1e-7, return_best=True),
)
snarf_result = snarf(stick.deformed_points, stick.transforms, return_result=True)
mesh_data = make_mesh_gaussian_dataset(nodes=5, fields=2)
mesh = SILVAMeshInference(
SolverConfig(solver="picard", max_iter=500, tol=1e-8, return_best=True)
)
mesh_result = mesh(
mesh_data.anchors,
mesh_data.anchor_precision,
mesh_data.observations,
mesh_data.observation_precision,
mesh_data.admission,
emission=mesh_data.emission,
return_result=True,
)
pde_data = make_poisson_diffusion_dataset(size=8)
def energy(field: torch.Tensor, condition: torch.Tensor | None) -> torch.Tensor:
if condition is None:
raise ValueError("the Poisson forcing is required")
return finite_difference_poisson_energy(field, condition, pde_data.spacing)
diffusion = SILVAPhysicsGuidedDiffusionPDE(
energy,
project_homogeneous_dirichlet,
steps=8,
guidance_step=2e-5,
prior_strength=0.0,
smoothing_sigma=0.6,
)
diffusion_result = diffusion(
pde_data.initial,
condition=pde_data.forcing,
return_result=True,
)
mechanics = make_therino_elastic_dataset(samples=2, size=6, seed=64)
therino = SILVATherINO(
update=MaterialRelaxation(mechanics.target_strain),
config=SolverConfig(solver="picard", max_iter=10, tol=1e-8),
)
therino_result = therino(
mechanics.stiffness,
mechanics.macro_strain,
return_result=True,
)
denoiser = SILVAFixedPointDenoiser(
1,
transition=TimestepRelaxation(),
config=SolverConfig(solver="picard", max_iter=12, tol=1e-7),
)
fixed_point_diffusion = SILVAFixedPointDiffusionModel(
denoiser,
(4, 2, 1, 0),
allocations=(4, 6, 8),
)
latent_data = make_fixed_point_diffusion_dataset(
samples=2, channels=1, size=6, seed=64
)
fixed_point_result = fixed_point_diffusion(latent_data.noise, return_result=True)
return {
"consistency": {
"shape": tuple(accelerated.output.shape),
"teacher_error": float((teacher.equilibrium - teacher_data.equilibrium).abs().max()),
},
"psi_gnn": {
"shape": tuple(psi_result.output.shape),
"boundary_error": float(psi_result.boundary_error.detach()),
},
"ifno": {
"shape": tuple(ifno_result.output.shape),
"final_increment": ifno_result.increment_norms[-1],
},
"snarf": {
"shape": tuple(snarf_result.occupancy.shape),
"root_residual": float(snarf_result.residuals.min(dim=1).values.max()),
},
"mesh": {
"shape": tuple(mesh_result.output.shape),
"centralized_error": float(mesh_result.agreement_error.detach()),
},
"physics_diffusion": {
"shape": tuple(diffusion_result.output.shape),
"final_energy": diffusion_result.energies[-1],
},
"therino": {
"shape": tuple(therino_result.output.shape),
"strain_error": float(
(therino_result.strain - mechanics.target_strain).abs().max()
),
},
"fixed_point_diffusion": {
"shape": tuple(fixed_point_result.output.shape),
"reverse_steps": len(fixed_point_result.solver_results),
},
}
def main() -> None:
torch.manual_seed(64)
for family, values in compact_results().items():
print(f"{family}: {values}")
if __name__ == "__main__":
main()
Measured Compact Output
consistency: {'shape': (4, 3), 'teacher_error': 5.960464477539063e-08}
psi_gnn: {'shape': (25, 1), 'boundary_error': 0.0}
ifno: {'shape': (2, 1, 4, 8), 'final_increment': 3.803837776184082}
snarf: {'shape': (7, 1), 'root_residual': 8.068445911391109e-10}
mesh: {'shape': (5, 2), 'centralized_error': 1.8730469264482963e-07}
physics_diffusion: {'shape': (1, 1, 8, 8), 'final_energy': 40.260433197021484}
therino: {'shape': (2, 3, 6, 6), 'strain_error': 1.4901161193847656e-08}
fixed_point_diffusion: {'shape': (2, 1, 6, 6), 'reverse_steps': 3}
Interpret the Output
The program validates all eight mechanisms independently. Each reported quantity has a family-specific meaning, so a scale study must retain both the shared fixed-point residual and the named physical or structural check.
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.emerging_equilibria
Emerging equilibrium mechanisms expressed through SILVA contracts.
The classes in this module are independent implementations of published mechanisms. They expose the transition, numerical method, physical operators, and readout as replaceable PyTorch modules or callables so compact examples and benchmark-scale studies use the same public interfaces.
SILVAConsistencyBackbone
Bases: Module
Vector refiner used by the default consistency equilibrium model.
SILVAConsistencyTrajectory
dataclass
Fixed solver trajectory used as a consistency-distillation teacher.
SILVAConsistencyOutput
dataclass
Few-step consistency prediction and its complete inference trajectory.
SILVAConsistencyLoss
dataclass
Local, global, optional task, and combined consistency losses.
SILVAConsistencyDEQ
Bases: Module
Distill a SILVA equilibrium trajectory into one- or few-step inference.
For virtual time t the consistency map is
with c_skip=((t-epsilon)/(T-epsilon))**gamma and
c_out=1-c_skip. A two-state Anderson-structured refinement is used
whenever a previous state is available.
boundary_coefficients
Return terminally anchored skip and output coefficients.
teacher_trajectory
Generate the fixed, solver-induced trajectory used for distillation.
SILVAPsiGNNProcessor
Bases: Module
Boundary-aware message processor for Poisson-like graph equilibria.
Node types use integer codes 0 (interior), 1 (Dirichlet), and 2
(Neumann). Dirichlet latent states are clamped to their encoded initial
values; interior and Neumann states use separate message and update maps.
SILVAPsiGNNOutput
dataclass
Physical solution, latent equilibrium, and boundary-aware diagnostics.
SILVAPsiGNNLoss
dataclass
Complete Psi-GNN residual, stabilization, and autoencoder objective.
SILVAPsiGNN
Bases: Module
Poisson-specific graph equilibrium with mixed-boundary processing.
transition
Expose the complete processor transition for diagnostics or reuse.
SILVAIFNOIncrement
Bases: Module
Layer-independent IFNO increment sigma(W h + K h + c).
SILVAIFNOOutput
dataclass
Material field prediction and explicit or equilibrium integration trace.
SILVAIFNO
Bases: Module
Implicit Fourier neural operator with tied residual increments.
The faithful finite-depth update is
mode="unrolled" evaluates this update for depth shared steps.
mode="equilibrium" solves for a zero increment using a SILVA root
solver, which is useful for studying the deep limit.
SILVABlendWeightField
Bases: Module
Pose-independent canonical blend-weight field.
SILVACanonicalOccupancy
Bases: Module
Canonical occupancy field with optional pose conditioning.
SILVASNARFOutput
dataclass
Deformed occupancy and all multi-start canonical correspondences.
SILVASNARF
Bases: Module
Differentiable forward skinning with multi-start canonical root search.
deform
Map canonical points to posed space with learned forward weights.
initial_correspondences
Initialize one canonical root candidate from every inverse bone transform.
correspondences
Find canonical correspondences and return per-candidate validity.
SILVAMatrixCertificate
dataclass
Numerical checks for the directed M-matrix relaxation operator.
SILVAMeshInferenceOutput
dataclass
Distributed relaxation result, centralized comparison, and certificate.
SILVAMeshInference
Bases: Module
Typed, directed, center-free linear-Gaussian mesh relaxation.
For field f and receiver i, the Jacobi transition is
where private anchors contribute lambda, admitted observations
contribute tau, and the receiver-autonomous admission/emission policy
supplies nonnegative directed weights w.
effective_weights
staticmethod
Return directed per-field weights with source emission applied.
system
staticmethod
Build per-field M-matrices, right-hand sides, and directed weights.
centralized_solution
staticmethod
Solve the centralized system used to verify distributed relaxation.
SILVAZeroNoisePredictor
Bases: Module
Neutral diffusion prior for isolating physics-guidance behavior.
SILVAPhysicsGuidedDiffusionOutput
dataclass
Sampled PDE field and complete energy/residual inference trace.
SILVAPhysicsGuidedDiffusionPDE
Bases: Module
Reverse diffusion with residual-energy guidance and hard projection.
Every reverse step performs four explicit operations: a learned prior update, Gaussian smoothing, descent on a supplied PDE residual energy, and a supplied boundary projection. The prior and physical problem remain independent, so one prior can be evaluated on several equations.
SILVAThermodynamicEncoder
Bases: Module
Encode strain through constitutive stress, energy, and bulk loading.
The stiffness field uses (B, D, D, H, W) layout and the symmetric
strain field uses (B, D, H, W). The resulting channels are
SILVAThermodynamicUpdate
Bases: Module
Fourier update from thermodynamic features to a candidate strain.
SILVATherINOOutput
dataclass
Strain equilibrium, constitutive diagnostics, and root-solver result.
SILVATherINOLoss
dataclass
Strain, stress, energy, and combined material-response objectives.
SILVATherINO
Bases: Module
Thermodynamically informed equilibrium in physical strain space.
The model solves
where the constitutive encoder is fixed and update is replaceable. A
bulk-strain projection can enforce periodic-cell loading after every update.
SILVATimestepFixedPointBlock
Bases: Module
Default timestep-conditioned transition for a fixed-point denoiser.
SILVAFixedPointDenoiserOutput
dataclass
Denoised output, equilibrium feature, input injection, and solver trace.
SILVAFixedPointDenoiser
Bases: Module
Pre/injection/equilibrium/post denoiser with a replaceable transition.
SILVAFixedPointDiffusionOutput
dataclass
Sequential samples and per-timestep equilibrium diagnostics.
SILVAFixedPointDiffusionModel
Bases: Module
Sequence of related fixed-point denoising problems with solution reuse.
silva_consistency_loss
silva_consistency_loss(current_prediction, equilibrium, *, adjacent_prediction=None, global_weight=0.5, task_loss=None, task_weight=0.0)
Combine global, local, and task-level consistency objectives.
update_silva_ema
Update an exponential-moving-average consistency target in place.
silva_forward_skinning
Apply linear blend skinning to arbitrary leading point dimensions.
Where to Go Next
| Question | Page |
|---|---|
| How are the equations derived and connected to SILVA? | Emerging Equilibrium Methods |
| Which datasets and full-scale settings are required? | Reconstructing Paper Experiments |
| Where are the executable compact studies? | Notebook Overview |