SPILSNet-Torch

A high-performance PyTorch implementation of SPILSNet (Spatiotemporal Physics-derived Internal Latent Space Network).

SPILSNet is designed for modeling complex dynamical systems where preserving physical structure (like spatial relationships and temporal consistency) is critical. It combines convolutional encoders for spatial feature extraction with a Gated Recurrent Unit (GRU) core to capture temporal evolution, while maintaining a learned skip-connection architecture to preserve high-frequency details.

Features

• Unified Non-Pickle Serialization: Industry-standard safetensors format for weights and metadata (config, scalers), ensuring cross-platform safety and performance.
• Graph Neural Network (PyG) Integration: SPILSNetGraph architecture for handling 3D unstructured meshes and arbitrary domain interface topologies using Graph Convolutions (GraphSAGE / GCN).
• Physics-derived Temporal Dynamics: GRU-based core for robust state-space modeling.
• Flexible Scaling: Built-in support for Scikit-learn scalers and custom transformers (e.g., CubeRoot).
• Professional Engineering: Full type hinting, Google-style docstrings, and robust serialization.
• Extensible Loss: Custom spils_loss including Laplacian smoothness terms for spatial consistency.

Installation

Install via pip:

pip install spilsnet-torch

For development:

git clone https://github.com/andinoboerst/spilsnet-torch.git
cd spilsnet-torch
pip install -e ".[dev]"

Quick Start

1. Standard 2D Structured Model (Convolutional Encoder)

import numpy as np
import torch
from spilsnet import SPILSNet
from sklearn.preprocessing import StandardScaler

# 1. Configure the architecture
model_config = {
    "dimension": 2,                # 2D coordinates (x, y)
    "input_size": 102,             # 51 nodes * 2 dimensions
    "internal_state_size": 16,     # Size of physical internal states
    "encoder_structure": [
        {"out": 32, "k": 3, "s": 1, "p": 1},
        {"out": 16, "k": 3, "s": 1, "p": 1},
    ],
    "bottleneck_pool_size": 4,
    "latent_dim": 32,
    "gru_hidden_size": 64,
    "latent_encoder_mlp": [64, 64],
    "internal_input_mlp": [32],
    "internal_output_mlp": [32],
    "dropout_rate": 0.1,
}

# 2. Initialize the wrapper
model = SPILSNet(
    model_config=model_config,
    input_scaler_class=StandardScaler(),
    internal_in_scaler_class=StandardScaler(),
    internal_out_scaler_class=StandardScaler(),
    output_scaler_class=StandardScaler()
)

# 3. Fit the model
# X: [Sims, Steps, Input_Size], Y: [Sims, Steps, Output_Size], I: [Sims, Steps, Internal_Size]
X, Y, I = np.random.randn(10, 50, 102), np.random.randn(10, 50, 102), np.random.randn(10, 50, 16)
model.fit(X, Y, I)

# 4. Sequential Inference
model.initialize_memory_variables()
current_x = np.random.randn(102)
next_y = model.predict(current_x)

print(f"Predicted next state shape: {next_y.shape}")

2. 3D Unstructured Mesh / Interface Model (Graph Neural Network Encoder)

import numpy as np
import torch
from spilsnet import SPILSNetGraph, connectivity_to_edge_index
from sklearn.preprocessing import StandardScaler

# 1. Define mesh element connectivity & node spatial coordinates
# connectivity shape: [Num_Elements, Nodes_Per_Element] (0-indexed node indices)
connectivity = np.array([
    [0, 1, 2],
    [1, 2, 3],
    [2, 3, 4]
])
edge_index = connectivity_to_edge_index(connectivity)

# Optional: pass static node spatial coordinates [Num_Nodes, Coord_Dim] for GNN spatial awareness
node_coordinates = np.random.randn(50, 3)

# 2. Configure the GNN architecture
model_config = {
    "dimension": 3,                # 3D nodal state features (x, y, z)
    "input_size": 150,             # 50 nodes * 3 dimensions
    "internal_state_size": 16,
    "conv_type": "SAGE",           # GraphSAGE ("SAGE") or GCN ("GCN")
    "encoder_structure": [
        {"out": 32},
        {"out": 64},
    ],
    "skip_target_nodes": 4,
    "latent_dim": 32,
    "gru_hidden_size": 64,
    "latent_encoder_mlp": [64, 64],
    "internal_input_mlp": [32],
    "internal_output_mlp": [32],
    "latent_decoder_structure": [256, 512],
    "use_decoder_conv": True,
    "dropout_rate": 0.1,
}

# 3. Initialize SPILSNetGraph (with optional node_coordinates)
model = SPILSNetGraph(
    edge_index=edge_index,
    node_coordinates=node_coordinates,
    model_config=model_config,
    input_scaler_class=StandardScaler(),
    internal_in_scaler_class=StandardScaler(),
    internal_out_scaler_class=StandardScaler(),
    output_scaler_class=StandardScaler()
)

# 4. Fit the model
X = np.random.randn(10, 50, 150)
Y = np.random.randn(10, 50, 150)
I = np.random.randn(10, 50, 16)
model.fit(X, Y, I)

# 5. Sequential Inference
model.initialize_memory_variables()
current_x = np.random.randn(150)
next_y = model.predict(current_x)

print(f"Predicted next state shape: {next_y.shape}")

Testing

Run the test suite using pytest:

pytest

To run with coverage:

pytest --cov=spilsnet

License

This project is licensed under the AGPL 3.0 License - see the LICENSE file for details.

Citation

If you use this code in your research, please cite the associated paper and this repository.

Paper Citation

@article{boerst_2026_spilsnet,
  title={Accelerating Transient Structural Dynamics via SPILS-Net, a Physics-Derived Latent Space Subdomain Surrogate},
  author={Börst, Andino and Díez, Pedro and Zlotnik, Sergio and Cavaliere, Fabiola and Curtosi, Gabriel and Larráyoz, Xabier},
  journal={Computer Methods in Applied Mechanics and Engineering},
  year={2026},
  doi={10.1016/j.cma.2026.119234}
}

Software Citation

(this repository, spilsnet-torch, available on PyPI):

@software{boerst_2026_spilsnet_torch,
  author={Börst, Andino},
  title={spilsnet-torch: PyTorch Implementation of SPILS-Net},
  year={2026},
  publisher={Zenodo},
  url={https://doi.org/10.5281/zenodo.21236780},
  doi={10.5281/zenodo.21236780},
  version={1.1.0}
}

For machine-readable citation metadata, see CITATION.cff.