Advanced Data API

Deterministic equation-checked data for advanced SILVA labs.

Operational Contract

This API surface connects advanced-family data contracts to the same SILVA experiment contract used by the learning pages and notebooks. Its central relation is

\[ \mathcal D=\{(x_i,y_i,c_i)\}_{i=1}^N,\qquad y_i=\mathcal G(x_i;c_i) \]

Part	What must remain inspectable
State	batch fields consumed by the monotone, generative, inverse, ODE, and DAE families.
Condition	every generated target must satisfy the same discrete equation used by its verifier.
Diagnostic	target-equation residual and tensor shape.
Replacement point	the analytic generator, boundary sampler, noise model, or public-data adapter.
Scale axes	sample count, graph or grid resolution, trajectory length, and noise level.

The relevant method lineage is recorded in [47] through [52]. 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 advanced equilibrium and physics-informed SILVA mechanisms."""

from __future__ import annotations

import torch

from silva_networks import (
    SILVABurgMirrorTransition,
    SILVAGenerativeEquilibriumTransformer,
    SILVAImplicitDAEStep,
    SILVAMonotoneGraphEquilibrium,
    SILVAPhysicsInformedEquilibrium,
    SILVAPoissonMirrorEquilibrium,
    SILVAResidualDiscriminator,
    SolverConfig,
    make_linear_dae_dataset,
    make_linear_ivp_dataset,
    make_monotone_chain_dataset,
    make_poisson_inverse_dataset,
    make_teacher_image_pairs,
    silva_adversarial_residual_loss,
    silva_distillation_loss,
)


def main() -> None:
    torch.manual_seed(25)

    chain = make_monotone_chain_dataset(nodes=8, seed=25)
    graph = SILVAMonotoneGraphEquilibrium(
        1,
        4,
        1,
        config=SolverConfig(solver="picard", max_iter=12, tol=1e-5),
    )
    graph_result = graph(chain.source, chain.edge_index, return_result=True)
    print("monotone graph:", tuple(graph_result.output.shape), graph_result.solver_result.residual)

    teacher = make_teacher_image_pairs(samples=2, height=4, width=4, seed=25)
    transformer = SILVAGenerativeEquilibriumTransformer(
        in_channels=1,
        patch_size=2,
        hidden_dim=8,
        heads=2,
        equilibrium_depth=1,
        config=SolverConfig(solver="picard", max_iter=8, tol=1e-5, anderson_batch_dims=1),
    )
    generated = transformer(teacher.noise, return_result=True)
    print(
        "equilibrium transformer:", float(silva_distillation_loss(generated.output, teacher.target))
    )

    poisson = make_poisson_inverse_dataset(samples=2, height=4, width=4, seed=25)
    mirror = SILVAPoissonMirrorEquilibrium(
        transition=SILVABurgMirrorTransition(
            forward_operator=poisson.forward_operator,
            adjoint_operator=poisson.adjoint_operator,
            step_size=0.05,
        ),
        config=SolverConfig(max_iter=8, tol=1e-5, anderson_batch_dims=1),
    )
    reconstruction = mirror(poisson.observation, return_result=True)
    print("Poisson mirror:", float(poisson.data_fidelity(reconstruction.output)))

    ivp = make_linear_ivp_dataset(points=5, rate=-0.5)
    physics_model = SILVAPhysicsInformedEquilibrium(
        3,
        1,
        config=SolverConfig(
            solver="picard",
            max_iter=8,
            tol=1e-5,
            backward_mode="implicit",
            anderson_batch_dims=1,
        ),
    )
    physics = physics_model.physics_loss(
        ivp.times,
        ivp.dynamics,
        initial_time=ivp.times[:1],
        initial_state=ivp.initial_state,
        jacobian_weight=0.01,
    )
    print("physics-informed loss:", float(physics.total))

    dae = make_linear_dae_dataset(steps=2, step_size=0.1)
    dae_result = SILVAImplicitDAEStep()(
        dae.differential[:1],
        dae.algebraic[:1],
        dae.step_size,
        dae.dynamics,
        dae.constraint,
    )
    print("implicit DAE step:", dae_result.differential.flatten().tolist(), dae_result.residual)

    discriminator = SILVAResidualDiscriminator(1, hidden_dim=8, depth=1)
    residual_losses = silva_adversarial_residual_loss(
        discriminator,
        physics.time_derivative - ivp.dynamics(ivp.times, physics.prediction),
    )
    print(
        "adversarial residual objective:",
        float(residual_losses.generator),
        float(residual_losses.discriminator),
    )


if __name__ == "__main__":
    main()

python examples/advanced_equilibria.py

Measured Compact Output

monotone graph: (8, 1) 0.023554455488920212
equilibrium transformer: 0.18536624312400818
Poisson mirror: 0.005979819223284721
physics-informed loss: 0.8003759384155273
implicit DAE step: [0.4761904776096344] 1.862645149230957e-09
adversarial residual objective: 0.7888258695602417 1.3886094093322754

Interpret the Output

The DAE residual is near machine precision, while the other values are task losses or fixed-point diagnostics with different units. They must be compared only to the matching equation and tolerance.

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.

Deterministic teaching data for advanced SILVA equilibrium mechanisms.

SILVALinearDAEBatch dataclass

Exact trajectory for y'=-y+z with algebraic constraint z=y/2.

Source code in src/silva_networks/advanced_data.py

@dataclass(frozen=True)
class SILVALinearDAEBatch:
    r"""Exact trajectory for ``y'=-y+z`` with algebraic constraint ``z=y/2``."""

    times: Tensor
    differential: Tensor
    algebraic: Tensor
    step_size: float

    @staticmethod
    def dynamics(differential: Tensor, algebraic: Tensor) -> Tensor:
        """Return the differential field ``-y+z``."""

        return -differential + algebraic

    @staticmethod
    def constraint(differential: Tensor, algebraic: Tensor) -> Tensor:
        """Return the algebraic residual ``z-y/2``."""

        return algebraic - 0.5 * differential

    def constraint_residual(self) -> Tensor:
        """Check the algebraic constraint along the exact trajectory."""

        return self.constraint(self.differential, self.algebraic)

constraint staticmethod

constraint(differential, algebraic)

Return the algebraic residual z-y/2.

Source code in src/silva_networks/advanced_data.py

@staticmethod
def constraint(differential: Tensor, algebraic: Tensor) -> Tensor:
    """Return the algebraic residual ``z-y/2``."""

    return algebraic - 0.5 * differential

constraint_residual

constraint_residual()

Check the algebraic constraint along the exact trajectory.

Source code in src/silva_networks/advanced_data.py

def constraint_residual(self) -> Tensor:
    """Check the algebraic constraint along the exact trajectory."""

    return self.constraint(self.differential, self.algebraic)

dynamics staticmethod

dynamics(differential, algebraic)

Return the differential field -y+z.

Source code in src/silva_networks/advanced_data.py

@staticmethod
def dynamics(differential: Tensor, algebraic: Tensor) -> Tensor:
    """Return the differential field ``-y+z``."""

    return -differential + algebraic

SILVALinearIVPBatch dataclass

Analytic linear ODE trajectory for physics-informed equilibrium lessons.

Source code in src/silva_networks/advanced_data.py

@dataclass(frozen=True)
class SILVALinearIVPBatch:
    """Analytic linear ODE trajectory for physics-informed equilibrium lessons."""

    times: Tensor
    target: Tensor
    initial_state: Tensor
    rate: float

    def dynamics(self, times: Tensor, state: Tensor) -> Tensor:
        """Return ``dy/dt = rate * y``."""

        if times.shape[0] != state.shape[0]:
            raise ValueError("times and state must share the sample dimension")
        return self.rate * state

    def equation_residual(self) -> Tensor:
        """Return the analytic derivative minus the ODE field."""

        derivative = self.rate * self.target
        return derivative - self.dynamics(self.times, self.target)

dynamics

dynamics(times, state)

Return dy/dt = rate * y.

Source code in src/silva_networks/advanced_data.py

def dynamics(self, times: Tensor, state: Tensor) -> Tensor:
    """Return ``dy/dt = rate * y``."""

    if times.shape[0] != state.shape[0]:
        raise ValueError("times and state must share the sample dimension")
    return self.rate * state

equation_residual

equation_residual()

Return the analytic derivative minus the ODE field.

Source code in src/silva_networks/advanced_data.py

def equation_residual(self) -> Tensor:
    """Return the analytic derivative minus the ODE field."""

    derivative = self.rate * self.target
    return derivative - self.dynamics(self.times, self.target)

SILVAMonotoneChainBatch dataclass

Chain graph whose target solves a graph elliptic system.

Source code in src/silva_networks/advanced_data.py

@dataclass(frozen=True)
class SILVAMonotoneChainBatch:
    """Chain graph whose target solves a graph elliptic system."""

    source: Tensor
    target: Tensor
    edge_index: Tensor
    diffusion: float

    def equation_residual(self, value: Tensor | None = None) -> Tensor:
        """Return ``u + diffusion * G u - source``."""

        field = self.target if value is None else value
        return (
            field
            + self.diffusion
            * normalized_laplacian_field(
                field,
                self.edge_index,
            )
            - self.source
        )

equation_residual

equation_residual(value=None)

Return u + diffusion * G u - source.

Source code in src/silva_networks/advanced_data.py

def equation_residual(self, value: Tensor | None = None) -> Tensor:
    """Return ``u + diffusion * G u - source``."""

    field = self.target if value is None else value
    return (
        field
        + self.diffusion
        * normalized_laplacian_field(
            field,
            self.edge_index,
        )
        - self.source
    )

SILVAPoissonInverseBatch dataclass

Positive images and deterministic seeded Poisson measurements.

Source code in src/silva_networks/advanced_data.py

@dataclass(frozen=True)
class SILVAPoissonInverseBatch:
    """Positive images and deterministic seeded Poisson measurements."""

    clean: Tensor
    observation: Tensor
    expected_intensity: Tensor
    exposure: float

    @staticmethod
    def forward_operator(field: Tensor) -> Tensor:
        """Apply the teaching measurement operator."""

        return periodic_blur(field)

    @staticmethod
    def adjoint_operator(field: Tensor) -> Tensor:
        """Apply the adjoint, equal to the symmetric teaching blur."""

        return periodic_blur(field)

    def expected_equation_residual(self) -> Tensor:
        """Check the noiseless intensity relation ``lambda=A x``."""

        return self.expected_intensity - self.forward_operator(self.clean)

    def data_fidelity(self, value: Tensor) -> Tensor:
        """Evaluate the Poisson KL data term for a reconstruction."""

        return poisson_kl(self.observation, self.forward_operator(value))

adjoint_operator staticmethod

adjoint_operator(field)

Apply the adjoint, equal to the symmetric teaching blur.

Source code in src/silva_networks/advanced_data.py

@staticmethod
def adjoint_operator(field: Tensor) -> Tensor:
    """Apply the adjoint, equal to the symmetric teaching blur."""

    return periodic_blur(field)

data_fidelity

data_fidelity(value)

Evaluate the Poisson KL data term for a reconstruction.

Source code in src/silva_networks/advanced_data.py

def data_fidelity(self, value: Tensor) -> Tensor:
    """Evaluate the Poisson KL data term for a reconstruction."""

    return poisson_kl(self.observation, self.forward_operator(value))

expected_equation_residual

expected_equation_residual()

Check the noiseless intensity relation lambda=A x.

Source code in src/silva_networks/advanced_data.py

def expected_equation_residual(self) -> Tensor:
    """Check the noiseless intensity relation ``lambda=A x``."""

    return self.expected_intensity - self.forward_operator(self.clean)

forward_operator staticmethod

forward_operator(field)

Apply the teaching measurement operator.

Source code in src/silva_networks/advanced_data.py

@staticmethod
def forward_operator(field: Tensor) -> Tensor:
    """Apply the teaching measurement operator."""

    return periodic_blur(field)

SILVATeacherImageBatch dataclass

Noise/target image pairs for one-step equilibrium distillation lessons.

Source code in src/silva_networks/advanced_data.py

@dataclass(frozen=True)
class SILVATeacherImageBatch:
    """Noise/target image pairs for one-step equilibrium distillation lessons."""

    noise: Tensor
    target: Tensor

    @staticmethod
    def teacher_map(noise: Tensor) -> Tensor:
        """Apply the deterministic local smoothing teacher."""

        smooth = F.avg_pool2d(noise, kernel_size=3, stride=1, padding=1)
        return torch.tanh(0.65 * smooth + 0.35 * noise)

    def equation_residual(self, value: Tensor | None = None) -> Tensor:
        """Return the deviation from the deterministic teacher map."""

        prediction = self.target if value is None else value
        return prediction - self.teacher_map(self.noise)

equation_residual

equation_residual(value=None)

Return the deviation from the deterministic teacher map.

Source code in src/silva_networks/advanced_data.py

def equation_residual(self, value: Tensor | None = None) -> Tensor:
    """Return the deviation from the deterministic teacher map."""

    prediction = self.target if value is None else value
    return prediction - self.teacher_map(self.noise)

teacher_map staticmethod

teacher_map(noise)

Apply the deterministic local smoothing teacher.

Source code in src/silva_networks/advanced_data.py

@staticmethod
def teacher_map(noise: Tensor) -> Tensor:
    """Apply the deterministic local smoothing teacher."""

    smooth = F.avg_pool2d(noise, kernel_size=3, stride=1, padding=1)
    return torch.tanh(0.65 * smooth + 0.35 * noise)

make_linear_dae_dataset

make_linear_dae_dataset(*, steps=10, dimensions=1, step_size=0.1, dtype=torch.float32)

Create the exact index-1 DAE trajectory y(t)=y0 exp(-t/2).

Source code in src/silva_networks/advanced_data.py

def make_linear_dae_dataset(
    *,
    steps: int = 10,
    dimensions: int = 1,
    step_size: float = 0.1,
    dtype: torch.dtype = torch.float32,
) -> SILVALinearDAEBatch:
    """Create the exact index-1 DAE trajectory ``y(t)=y0 exp(-t/2)``."""

    _positive_integer(steps, "steps")
    _positive_integer(dimensions, "dimensions")
    if step_size <= 0:
        raise ValueError("step_size must be positive")
    times = torch.arange(steps + 1, dtype=dtype)[:, None] * step_size
    initial = torch.linspace(0.5, 1.0, dimensions, dtype=dtype)[None]
    differential = torch.exp(-0.5 * times) * initial
    algebraic = 0.5 * differential
    return SILVALinearDAEBatch(times, differential, algebraic, float(step_size))

make_linear_ivp_dataset

make_linear_ivp_dataset(*, points=21, dimensions=1, final_time=2.0, rate=-0.5, dtype=torch.float32)

Create y(t)=y0 exp(rate*t) at evenly spaced collocation points.

Source code in src/silva_networks/advanced_data.py

def make_linear_ivp_dataset(
    *,
    points: int = 21,
    dimensions: int = 1,
    final_time: float = 2.0,
    rate: float = -0.5,
    dtype: torch.dtype = torch.float32,
) -> SILVALinearIVPBatch:
    """Create ``y(t)=y0 exp(rate*t)`` at evenly spaced collocation points."""

    _positive_integer(points, "points")
    _positive_integer(dimensions, "dimensions")
    if points < 2:
        raise ValueError("points must be at least two")
    if final_time <= 0:
        raise ValueError("final_time must be positive")
    times = torch.linspace(0.0, final_time, points, dtype=dtype)[:, None]
    initial = torch.linspace(0.5, 1.0, dimensions, dtype=dtype)[None]
    target = torch.exp(rate * times) * initial
    return SILVALinearIVPBatch(times, target, initial, float(rate))

make_monotone_chain_dataset

make_monotone_chain_dataset(*, nodes=16, channels=1, diffusion=0.5, seed=0, dtype=torch.float32)

Create a deterministic chain and exact graph-elliptic target.

Source code in src/silva_networks/advanced_data.py

def make_monotone_chain_dataset(
    *,
    nodes: int = 16,
    channels: int = 1,
    diffusion: float = 0.5,
    seed: int = 0,
    dtype: torch.dtype = torch.float32,
) -> SILVAMonotoneChainBatch:
    """Create a deterministic chain and exact graph-elliptic target."""

    _positive_integer(nodes, "nodes")
    _positive_integer(channels, "channels")
    if nodes < 2:
        raise ValueError("nodes must be at least two")
    if diffusion <= 0:
        raise ValueError("diffusion must be positive")
    generator = torch.Generator().manual_seed(seed)
    coordinates = torch.linspace(0.0, 1.0, nodes, dtype=dtype)
    phases = 2.0 * math.pi * torch.rand(channels, generator=generator, dtype=dtype)
    frequencies = torch.arange(1, channels + 1, dtype=dtype)
    source = torch.sin(2.0 * math.pi * coordinates[:, None] * frequencies[None] + phases[None])
    left = torch.arange(nodes - 1, dtype=torch.long)
    right = left + 1
    edge_index = torch.stack(
        [torch.cat([left, right]), torch.cat([right, left])],
        dim=0,
    )
    identity = torch.eye(nodes, dtype=dtype)
    laplacian_columns = []
    for index in range(nodes):
        basis = identity[:, index : index + 1]
        laplacian_columns.append(normalized_laplacian_field(basis, edge_index))
    graph_operator = torch.cat(laplacian_columns, dim=1)
    target = torch.linalg.solve(identity + diffusion * graph_operator, source)
    return SILVAMonotoneChainBatch(source, target, edge_index, float(diffusion))

make_poisson_inverse_dataset

make_poisson_inverse_dataset(*, samples=4, height=8, width=8, exposure=30.0, seed=0, dtype=torch.float32)

Create smooth positive images and seeded Poisson observations.

Source code in src/silva_networks/advanced_data.py

def make_poisson_inverse_dataset(
    *,
    samples: int = 4,
    height: int = 8,
    width: int = 8,
    exposure: float = 30.0,
    seed: int = 0,
    dtype: torch.dtype = torch.float32,
) -> SILVAPoissonInverseBatch:
    """Create smooth positive images and seeded Poisson observations."""

    for value, name in ((samples, "samples"), (height, "height"), (width, "width")):
        _positive_integer(value, name)
    if exposure <= 0:
        raise ValueError("exposure must be positive")
    y = torch.linspace(0.0, 2.0 * math.pi, height, dtype=dtype)
    x = torch.linspace(0.0, 2.0 * math.pi, width, dtype=dtype)
    grid_y, grid_x = torch.meshgrid(y, x, indexing="ij")
    fields = []
    for index in range(samples):
        phase = 2.0 * math.pi * index / samples
        field = 1.0 + 0.3 * torch.sin(grid_x + phase) * torch.cos(grid_y - phase)
        fields.append(field)
    clean = torch.stack(fields)[:, None]
    expected = periodic_blur(clean)
    generator = torch.Generator().manual_seed(seed)
    counts = torch.poisson(exposure * expected, generator=generator)
    observation = counts / exposure
    return SILVAPoissonInverseBatch(clean, observation, expected, float(exposure))

make_teacher_image_pairs

make_teacher_image_pairs(*, samples=8, channels=1, height=8, width=8, seed=0, dtype=torch.float32)

Create deterministic small image pairs without external data downloads.

Source code in src/silva_networks/advanced_data.py

def make_teacher_image_pairs(
    *,
    samples: int = 8,
    channels: int = 1,
    height: int = 8,
    width: int = 8,
    seed: int = 0,
    dtype: torch.dtype = torch.float32,
) -> SILVATeacherImageBatch:
    """Create deterministic small image pairs without external data downloads."""

    for value, name in (
        (samples, "samples"),
        (channels, "channels"),
        (height, "height"),
        (width, "width"),
    ):
        _positive_integer(value, name)
    generator = torch.Generator().manual_seed(seed)
    noise = torch.randn(samples, channels, height, width, generator=generator, dtype=dtype)
    return SILVATeacherImageBatch(noise, SILVATeacherImageBatch.teacher_map(noise))

periodic_blur

periodic_blur(field)

Apply a self-adjoint five-point periodic blur.

Source code in src/silva_networks/advanced_data.py

def periodic_blur(field: Tensor) -> Tensor:
    """Apply a self-adjoint five-point periodic blur."""

    if field.dim() != 4:
        raise ValueError("field must have shape (batch, channels, height, width)")
    return 0.5 * field + 0.125 * (
        torch.roll(field, 1, dims=-2)
        + torch.roll(field, -1, dims=-2)
        + torch.roll(field, 1, dims=-1)
        + torch.roll(field, -1, dims=-1)
    )

Where to Go Next

Question	Page
Which equations define every generated batch?	Advanced Equilibrium Datasets
How do the batches enter the public models?	Advanced Equilibria Example
Which graph and transformer classes consume them?	Advanced Equilibria API