API Reference

Complete documentation for SOEN Toolkit classes, methods, and modules

API Reference

Complete API documentation for SOEN Toolkit classes, methods, and modules.

Core Modules

soen_sim_v2.core

The core module contains the fundamental classes for building SOEN models.

SOENModelCore

Main class for creating and managing SOEN models.

from soen_sim_v2.core import SOENModelCore

model = SOENModelCore(
    layers_config=layers_config,
    connections_config=connections_config, 
    sim_config=sim_config
)

Parameters:

  • layers_config: List of LayerConfig objects defining model layers
  • connections_config: List of ConnectionConfig objects defining connections
  • sim_config: SimulationConfig object with simulation parameters

Key Methods:

  • forward(input_data, time_steps): Run forward pass through the network
  • enforce_param_constraints(): Apply parameter constraints
  • get_layer_states(): Get current state of all layers
  • reset_states(): Reset all layer states to initial values

Configuration Classes

LayerConfig

Defines configuration for individual layers.

from soen_sim_v2.core import LayerConfig

layer_config = LayerConfig(
    layer_id=0,
    layer_type="SingleDendrite",
    params={
        "dim": 128,
        "solver": "FE", 
        "gamma_plus": 1.0,
        "gamma_minus": 0.1
    }
)

ConnectionConfig

Defines connections between layers.

from soen_sim_v2.core import ConnectionConfig

conn_config = ConnectionConfig(
    from_layer=0,
    to_layer=1,
    connection_type="dense",
    params={"init_scale": 0.1}
)

SimulationConfig

Global simulation parameters.

from soen_sim_v2.core import SimulationConfig

sim_config = SimulationConfig(
    dt=100.0,
    dt_learnable=False
)

NoiseConfig & PerturbationConfig

Configure noise and perturbations for training.

from soen_sim_v2.core import NoiseConfig, PerturbationConfig

# Stochastic noise
noise_config = NoiseConfig(
    phi=0.01,
    g=0.005,
    relative=True
)

# Deterministic perturbations
perturb_config = PerturbationConfig(
    phi_mean=0.1,
    phi_std=0.02
)

Layer Classes

soen_sim_v2.layers

All layers inherit from SOENBaseLayer and implement specific dynamics.

Physical SOEN Layers

SingleDendriteLayer

Single-compartment superconducting device model.

from soen_sim_v2.layers import SingleDendriteLayer

layer = SingleDendriteLayer(
    dim=128,
    dt=100.0,
    solver="FE",
    source_func_type="tanh",
    track_power=True,
    physical_units=True
)

Dynamics: ds/dt = γ₊ × g(φ) - γ₋ × s

Parameters:

  • gamma_plus, gamma_minus: Coupling strengths
  • internal_J: Optional internal connectivity matrix
  • solver: Integration method ("FE", "adaptive", "PS")

DoubleDendrite1Layer & DoubleDendrite2Layer

Multi-compartment superconducting models with extended dynamics.

ScalingLayer

Parameter scaling and normalization.

Virtual Layers

Standard Neural Network Layers

from soen_sim_v2.layers import (
    RNNLayer, LSTMLayer, GRULayer, 
    MinGRULayer, LeakyRNNLayer
)

# Basic RNN
rnn = RNNLayer(dim=64, dt=1.0)

# LSTM with gates
lstm = LSTMLayer(dim=128, dt=1.0) 

# Minimal GRU
mingru = MinGRULayer(dim=64, dt=1.0)

InputLayer & ClassifierLayer

from soen_sim_v2.layers import InputLayer, ClassifierLayer

# Input preprocessing
input_layer = InputLayer(dim=784)

# Classification output
classifier = ClassifierLayer(
    dim=10, 
    use_batch_norm=True
)

Base Layer Interface

All layers implement the SOENBaseLayer interface:

class SOENBaseLayer(nn.Module):
    def __init__(self, dim, dt, **kwargs):
        # Core attributes
        self.dim = dim
        self.dt = dt
        self.track_power = track_power
        self.physical_units = physical_units
        
    def forward(self, phi_input, **kwargs):
        # Layer-specific forward pass
        pass
        
    def _initialize_parameters(self):
        # Initialize layer parameters
        pass
        
    def _apply_constraints(self):
        # Apply parameter constraints  
        pass

Key Attributes:

  • dim: Layer dimensionality
  • dt: Time step size
  • track_power: Enable power consumption tracking
  • physical_units: Use physical vs dimensionless units
  • source_function: Physics-based activation function

Physical Constants:

  • PHI0 = 2.067833848e-15: Flux quantum
  • Ic = 100e-6: Critical current
  • wc = 7.79e11: Characteristic frequency

Training Framework

soen_sim_v2.training

PyTorch Lightning-based training system.

ExperimentRunner

Main training orchestrator.

from soen_sim_v2.training.trainers import ExperimentRunner
from soen_sim_v2.training.utils import run_from_config

# Run from YAML configuration
run_from_config("config.yaml")

# Or create runner directly
runner = ExperimentRunner(config_dict)
runner.run()

SOENDataModule

Data loading and preprocessing.

from soen_sim_v2.training.data import SOENDataModule

datamodule = SOENDataModule(
    data_path="dataset.h5",
    batch_size=64,
    num_classes=10,
    cache_data=True
)

Loss Functions

Available loss functions:

from soen_sim_v2.training.losses import (
    CrossEntropyLoss,
    GapLoss, 
    RegularizationLoss
)

Callbacks

Custom training callbacks:

from soen_sim_v2.training.callbacks import (
    LearningRateScheduler,
    EarlyStopping,
    SequenceLengthScheduler
)

Metrics

Training and evaluation metrics:

# Available metrics
metrics = [
    "accuracy",
    "perplexity", 
    "bits_per_character",
    "top_k_accuracy",
    "autoregressive_accuracy"
]

Utility Modules

soen_sim_v2.utils

Helper functions and utilities.

Visualization

from soen_sim_v2.utils.visualization import visualize

# Visualize model structure and dynamics
visualize(model, data, save_path="plots/")

Source Functions

Physics-based activation functions:

from soen_sim_v2.core.source_functions import SOURCE_FUNCTIONS

# Available source functions
functions = [
    "tanh",
    "zero_inductance", 
    "RateArray",
    "sigmoid",
    "linear"
]

# Use in layer configuration
source_func = SOURCE_FUNCTIONS["tanh"]()

GUI Tools

Launch interactive GUI applications:

# Model creation interface
python -m soen_sim_v2.model_creation_gui

# Physical parameter mapping
python -m soen_sim_v2.physical_mappings_gui

# TensorBoard results viewer  
python -m soen_sim_v2.view_tb_results_gui

Usage Examples

Basic Model Creation

import torch
from soen_sim_v2.core import (
    SOENModelCore, LayerConfig, 
    ConnectionConfig, SimulationConfig
)

# Define layers
layers = [
    LayerConfig(
        layer_id=0,
        layer_type="Input",
        params={"dim": 784}
    ),
    LayerConfig(
        layer_id=1, 
        layer_type="SingleDendrite",
        params={
            "dim": 128,
            "solver": "FE",
            "gamma_plus": 1.0
        }
    ),
    LayerConfig(
        layer_id=2,
        layer_type="Classifier", 
        params={"dim": 10}
    )
]

# Define connections
connections = [
    ConnectionConfig(0, 1, "dense"),
    ConnectionConfig(1, 2, "dense")
]

# Create model
model = SOENModelCore(
    layers_config=layers,
    connections_config=connections,
    sim_config=SimulationConfig(dt=100.0)
)

# Forward pass
output = model(input_data, time_steps=50)

Training Script

from soen_sim_v2.training.utils import run_from_config

# Run training from YAML config
run_from_config("my_experiment.yaml")

Custom Layer Implementation

from soen_sim_v2.layers import SOENBaseLayer

class CustomLayer(SOENBaseLayer):
    def __init__(self, dim, dt, **kwargs):
        super().__init__(dim, dt, **kwargs)
        
    def _initialize_parameters(self):
        # Initialize custom parameters
        self.weight = nn.Parameter(torch.randn(self.dim, self.dim))
        
    def _apply_constraints(self):
        # Apply custom constraints
        with torch.no_grad():
            self.weight.clamp_(-1, 1)
            
    def forward(self, phi_input, **kwargs):
        # Custom forward dynamics
        return torch.tanh(phi_input @ self.weight)

Continue Exploring

View Examples → GUI Tools → Physical Modeling →