Emerging Equilibrium Data
These deterministic builders supply compact known-solution problems for consistency trajectories, mixed-boundary Poisson graphs, heterogeneous material operators, articulated forward skinning, typed mesh inference, and physics-guided diffusion. The same module also provides an exact periodic elasticity cell for the thermodynamic operator family and seeded latent fields with an analytic timestep-conditioned target for fixed-point diffusion. Source image datasets retain their independent access terms.
Operational Contract
This API surface connects emerging-family data generators to the same SILVA experiment contract used by the learning pages and notebooks. Its central relation is
| Part | What must remain inspectable |
|---|---|
| State | boundary graphs, coefficient fields, canonical points, mesh observations, and diffusion trajectories. |
| Condition | each batch keeps the coordinates, masks, conditions, and targets required to recompute its governing residual. |
| Diagnostic | boundary error, constitutive error, root residual, or energy. |
| Replacement point | the compact generator with a source-dataset adapter that returns the same named fields. |
| Scale axes | mesh density, spatial resolution, number of poses, diffusion steps, and stored trajectory count. |
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 exact checks expose different invariants: zero boundary error, a small deformation root residual, a small strain error, and the declared reverse-step count. The diffusion energy is an objective value and is not expected to be zero after this compact run.
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_data
Compact, deterministic data for emerging SILVA equilibrium families.
SILVAPsiPoissonBatch
dataclass
Mixed-boundary finite-difference graph with an analytic solution.
SILVAIFNOMaterialBatch
dataclass
Heterogeneous bar fields for coefficient-to-displacement learning.
SILVASNARFStickBatch
dataclass
Two-bone articulated stick with known forward correspondences.
SILVAConsistencyTeacherBatch
dataclass
Conditions and exact equilibria for a contractive affine teacher.
SILVAMeshGaussianBatch
dataclass
Typed linear-Gaussian evidence on a directed communication mesh.
SILVAPoissonDiffusionBatch
dataclass
Unit-square Poisson field with exact homogeneous Dirichlet data.
SILVATherINOBatch
dataclass
Periodic uncoupled elastic cell with an exact constant-stress solution.
SILVAFixedPointDiffusionBatch
dataclass
Seeded latent fields and exact timestep-conditioned denoising targets.
make_psi_poisson_grid
Build -Delta u = f with Dirichlet x-faces and Neumann y-faces.
The exact field u(x,y)=sin(pi*x) has zero values on x=0,1 and
homogeneous normal derivative on y=0,1. The sparse graph is represented
by all nonzero off-diagonal entries in the finite-difference matrix.
make_ifno_material_dataset
make_ifno_material_dataset(samples=8, height=8, width=16, *, seed=0, dtype=torch.float32, device=None)
Build heterogeneous 1D bars embedded on a 2D operator grid.
For unit cross section and traction T, equilibrium gives
du/dx=T/E(x). The exact displacement is its cumulative integral with
u(0)=0. Inputs include x, y, modulus, and traction fields.
make_snarf_stick_dataset
Build the paper's compact two-bone articulated-stick mechanism.
make_consistency_teacher_dataset
make_consistency_teacher_dataset(samples=16, state_dim=4, condition_dim=3, *, seed=0, dtype=torch.float32, device=None)
Create an affine contraction with a closed-form equilibrium.
make_mesh_gaussian_dataset
Build a carrier-connected typed chain with heterogeneous evidence.
make_poisson_diffusion_dataset
Build -Delta u=f with u=0 and u=sin(pi*x)sin(pi*y).
finite_difference_poisson_energy
Return the mean-squared interior residual of -Delta u = forcing.
project_homogeneous_dirichlet
Project every outer grid face to zero without mutating the input.
make_therino_elastic_dataset
make_therino_elastic_dataset(samples=8, size=12, strain_components=3, *, contrast=8.0, seed=0, dtype=torch.float32, device=None)
Build a periodic diagonal elastic cell with prescribed bulk strain.
Each uncoupled component satisfies constant stress. For compliance
S_i(x)=1/C_i(x), the exact stress and strain are
sigma_i=macro_i/mean(S_i) and epsilon_i(x)=S_i(x)*sigma_i.
make_fixed_point_diffusion_dataset
make_fixed_point_diffusion_dataset(samples=8, channels=2, size=12, *, seed=0, dtype=torch.float32, device=None)
Build latent fields with the exact target 0.5 noise + 0.1 time.
The target is the fixed point of the compact contraction used by the fixed-point diffusion tests and tutorial. It verifies timestep broadcasting, state shape, solver allocation, reuse, and gradient routing without claiming to replace an image-generation dataset.
Where to Go Next
| Question | Page |
|---|---|
| How is each compact problem derived? | Emerging Equilibrium Methods |
| How do I replace compact data with a source benchmark? | Reconstructing Paper Experiments |
| Which public models consume these batches? | Emerging Equilibria API |
| Where are the retained simulations and plots? | Notebook Library |