physkan 0.1.0__py3-none-any.whl

physkan/__init__.py

@@ -0,0 +1,16 @@
+"""PhysKAN: Physics-Informed Kolmogorov-Arnold Networks.
+
+A neural architecture designed for safety-critical system identification and control.
+PhysKAN enforces rigorous physical extrapolation by combining bounded B-splines,
+neuro-symbolic polynomial skip-connections, and interval arithmetic to mathematically
+track out-of-bounds (OOB) severity.
+
+Key Features:
+- Bounded Spline Grids: Mechanical clamping outside the nominal data range.
+- Dual Severity Tracking: Mathematical compounding of out-of-bounds errors.
+- Hybrid Symbolic Routing: Automated discovery of stable macro-physics via polynomials.
+"""
+
+from .demonstrator import KANDemonstrator as KANDemonstrator
+from .kan import KAN as KAN
+from .kan import KANLinear as KANLinear

physkan/demonstrator.py

@@ -0,0 +1,92 @@
+import matplotlib.pyplot as plt
+import torch
+import torch.nn as nn
+
+
+class KANDemonstrator:
+    """A utility class for training and visualizing PhysKAN models,
+    specifically designed to analyze out-of-bounds (OOB) dual severity tracking.
+    """
+
+    def __init__(self, model, target_fn, feature_fn=None):
+        self.model = model
+        self.target_fn = target_fn
+        # If no feature engineering is provided, pass raw features through
+        self.feature_fn = feature_fn if feature_fn else lambda x: x
+
+    def train(self, x_raw_train, epochs=500, lr=0.05, weight_decay=1e-4):
+        """Trains the model using the provided raw input tensors."""
+        y_train = self.target_fn(x_raw_train)
+        features = self.feature_fn(x_raw_train)
+
+        optimizer = torch.optim.AdamW(self.model.parameters(), lr=lr, weight_decay=weight_decay)
+        criterion = nn.MSELoss()
+
+        self.model.train()
+        for _ in range(epochs):
+            optimizer.zero_grad()
+            # Expecting the network to return (primal_prediction, dual_severity)
+            y_pred, d_pred = self.model(features, return_dual=True)
+            loss = criterion(y_pred, y_train)
+            loss.backward()
+            optimizer.step()
+
+        return loss.item()
+
+    def predict(self, x_raw):
+        """Evaluates the model without tracking gradients."""
+        self.model.eval()
+        features = self.feature_fn(x_raw)
+        with torch.no_grad():
+            y_pred, d_pred = self.model(features, return_dual=True)
+        return y_pred, d_pred
+
+    def plot(self, x_raw_eval, title="KAN Demonstration", x_axis_idx=0):
+        """Plots the physical prediction (primal) and severity tracking (dual).
+        x_axis_idx dictates which raw feature column to plot on the x-axis.
+        """
+        # Sort by the primary plotting axis for clean lines
+        sort_idx = torch.argsort(x_raw_eval[:, x_axis_idx])
+        x_raw_eval = x_raw_eval[sort_idx]
+
+        y_true = self.target_fn(x_raw_eval)
+        y_pred, d_pred = self.predict(x_raw_eval)
+
+        x_plot = x_raw_eval[:, x_axis_idx].numpy()
+
+        fig, (ax1, ax2) = plt.subplots(2, 1, figsize=(10, 8), sharex=True)
+        fig.suptitle(title, fontsize=14)
+
+        # 1. Primal Plot (Physics)
+        for i in range(y_true.shape[1]):
+            label_true = f"True $y_{i}$" if y_true.shape[1] > 1 else "True Physics"
+            label_pred = f"Pred $y_{i}$" if y_true.shape[1] > 1 else "KAN Prediction"
+            ax1.plot(x_plot, y_pred[:, i].numpy(), "-", linewidth=2, label=label_pred)
+            ax1.plot(x_plot, y_true[:, i].numpy(), "k--", alpha=0.7, label=label_true)
+
+        ax1.axvspan(-1.0, 1.0, color="gray", alpha=0.1, label="Nominal Range")
+        ax1.set_ylabel("Physical Value")
+        ax1.legend()
+        ax1.grid(True, alpha=0.3)
+
+        # 2. Dual Plot (Severity)
+        num_targets = d_pred.shape[1]
+
+        # Use a color palette that stands out for warnings (reds, oranges, purples)
+        severity_colors = ["#ff0000", "#ff7f0e", "#800080", "#d62728"]
+
+        for i in range(num_targets):
+            severity = d_pred[:, i].numpy()
+            label_str = "Dual Severity ($D$)" if num_targets == 1 else f"Severity $y_{i}$"
+            color = severity_colors[i % len(severity_colors)]
+
+            ax2.plot(x_plot, severity, color=color, linestyle="-", linewidth=2, label=label_str)
+
+        ax2.axvspan(-1.0, 1.0, color="gray", alpha=0.1)
+        ax2.set_ylabel("OOB Severity")
+        ax2.set_xlabel(f"Raw Input (Feature index {x_axis_idx})")
+        ax2.legend()
+        ax2.grid(True, alpha=0.3)
+
+        plt.tight_layout()
+        plt.show()

physkan/interaction.py

@@ -0,0 +1,116 @@
+import itertools
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+
+class KANInteraction(torch.nn.Module):
+    """Computes explicit feature interactions and their OOB duals.
+
+    Args:
+        interaction_map (list[list[int]]): List of index lists defining the multiplicative terms.
+            Example: [[0, 0], [0, 1]] means add (feats[:,0]^2 and (feats[:,0] * feats[:,1]).
+        grid_range (tuple): The nominal boundaries to compute the dual.
+    """
+
+    def __init__(self, interaction_map: list[list[int]], grid_range=(-1.0, 1.0)):
+        super().__init__()
+        self.interaction_map = interaction_map
+        self.grid_range = grid_range
+
+    def extra_repr(self) -> str:
+        return f"interaction_map={self.interaction_map}, grid_range={self.grid_range}"
+
+    def forward(self, x: torch.Tensor):
+        # 1. Genesis: Calculate initial OOB severity of raw inputs
+        lower_bound, upper_bound = self.grid_range
+        d = F.relu(x - upper_bound) + F.relu(lower_bound - x)
+        if not self.interaction_map:
+            return x, d
+
+        out_x = [x]
+        out_d = [d]
+        for term_indices in self.interaction_map:
+            # Gather the columns for the current interaction (e.g., [0, 0, 1])
+            x_gather = x[:, term_indices]
+            d_gather = d[:, term_indices]
+            x_abs_gather = x_gather.abs()
+            # --- Primal Physics ---
+            # Multiply the physical features together
+            x_interact = torch.prod(x_gather, dim=1, keepdim=True)
+            # --- Dual Severity ---
+            # Total Uncertainty Volume minus Nominal Volume
+            total_vol = torch.prod(x_abs_gather + d_gather, dim=1, keepdim=True)
+            nominal_vol = torch.prod(x_abs_gather, dim=1, keepdim=True)
+            d_interact = total_vol - nominal_vol
+
+            out_x.append(x_interact)
+            out_d.append(d_interact)
+
+        # Concatenate and return the augmented (primal, dual) tuple
+        return torch.cat(out_x, dim=1), torch.cat(out_d, dim=1)
+
+
+class PolynomialSkip(nn.Module):
+    def __init__(self, in_features, out_features, order=2):
+        super().__init__()
+
+        # 1. Generate all multi-indices for polynomials up to 'order'
+        # e.g., for inputs [0, 1] order 2: (0,), (1,), (0,0), (0,1), (1,1)
+        self.combinations = []
+        for d in range(1, order + 1):
+            combos = itertools.combinations_with_replacement(range(in_features), d)
+            self.combinations.extend(list(combos))
+
+        num_features = len(self.combinations)
+
+        # 2. The standard linear weights
+        self.weights = nn.Parameter(torch.randn(out_features, num_features) * 0.1)
+
+        # 3. The Probationary Gates
+        self.gates = nn.Parameter(1.0 * torch.ones(out_features, num_features))
+
+    def forward(self, x, dual_input=None):
+        poly_features = []
+        poly_duals = []
+
+        # --- A. Compute Polynomials & Interval Duals ---
+        for combo in self.combinations:
+            term = torch.ones_like(x[:, 0:1])
+            term_dual = torch.zeros_like(x[:, 0:1]) if dual_input is not None else None
+
+            for idx in combo:
+                x_i = x[:, idx : idx + 1]
+
+                # Interval Multiplication for the Dual Severity
+                if dual_input is not None:
+                    d_i = dual_input[:, idx : idx + 1]
+                    # Severity of a product: (|A| + D_A) * (|B| + D_B) - |A * B|
+                    new_dual = (torch.abs(term) + term_dual) * (torch.abs(x_i) + d_i) - torch.abs(
+                        term * x_i
+                    )
+                    term_dual = new_dual
+
+                term = term * x_i
+
+            poly_features.append(term)
+            if dual_input is not None:
+                poly_duals.append(term_dual)
+
+        P_x = torch.cat(poly_features, dim=1)
+
+        # --- B. Apply the -5.0 Sigmoid Gate ---
+        active_weights = self.weights * torch.sigmoid(self.gates - 5.0)
+
+        # --- C. Route the Physical Prediction ---
+        out = F.linear(P_x, active_weights)
+
+        # --- D. Route the Dual Severity (The Abs-Weighted Path) ---
+        if dual_input is not None:
+            D_x = torch.cat(poly_duals, dim=1)
+            # You called it: the dual routes through the absolute value of the active weights!
+            out_dual = F.linear(D_x, torch.abs(active_weights))
+            return out, out_dual
+
+        return out

physkan/kan.py

@@ -0,0 +1,260 @@
+import copy
+import inspect
+import math
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+from .interaction import KANInteraction, PolynomialSkip
+
+
+class KANLinear(torch.nn.Module):
+    def __init__(
+        self,
+        in_features,
+        out_features,
+        grid_size=5,
+        spline_order=3,
+        base_activation=torch.nn.Identity,
+        grid_range=(-1.0, 1.0),
+        spline_dropout=0.0,
+        pure_spline_mode=False,
+        _quiet_init=False,
+    ):
+        super().__init__()
+        self.in_features = in_features
+        self.out_features = out_features
+        self.grid_size = grid_size
+        self.spline_order = spline_order
+        self.grid_range = grid_range
+        self.spline_dropout = spline_dropout
+        self.pure_spline_mode = pure_spline_mode
+
+        if inspect.isclass(base_activation):
+            self.base_activation = base_activation()
+        elif isinstance(base_activation, nn.Module):
+            # Deepcopy guarantees isolation if passed to multiple layers!
+            self.base_activation = copy.deepcopy(base_activation)
+        elif callable(base_activation):
+            self.base_activation = base_activation
+        else:
+            raise ValueError("base_activation must be a class, module instance, or callable.")
+
+        # Static grid formulation
+        h = (grid_range[1] - grid_range[0]) / grid_size
+        grid = (
+            (torch.arange(-spline_order, grid_size + spline_order + 1) * h + grid_range[0])
+            .expand(in_features, -1)
+            .contiguous()
+        )
+        self.register_buffer("grid", grid)
+
+        # The two parallel tracks
+        if not self.pure_spline_mode:
+            self.base_weight = torch.nn.Parameter(torch.Tensor(out_features, in_features))
+        self.spline_weight = torch.nn.Parameter(
+            torch.Tensor(out_features, in_features, grid_size + spline_order)
+        )
+
+        self.reset_parameters(_quiet_init)
+
+    def reset_parameters(self, quiet=False):
+        if not self.pure_spline_mode:
+            torch.nn.init.kaiming_uniform_(self.base_weight, a=math.sqrt(5))
+            # Force zero intercept error by mean-centering each row.
+            # This guarantees that the row-sum of base_weight is EXACTLY 0.0,
+            # meaning the effective weight row-sum is EXACTLY 1.0 across all channels.
+            with torch.no_grad():
+                self.base_weight -= self.base_weight.mean(dim=1, keepdim=True)
+                if quiet:
+                    self.base_weight /= 100.0
+        torch.nn.init.zeros_(self.spline_weight)
+
+    def extra_repr(self) -> str:
+        return (
+            f"in_features={self.in_features}, "
+            f"out_features={self.out_features}, "
+            f"grid_size={self.grid_size}, "
+            f"spline_order={self.spline_order}, "
+            f"grid_range={self.grid_range}"
+        )
+
+    def b_splines(self, x: torch.Tensor):
+        """Compute the B-spline bases for the given input tensor.
+
+        Args:
+            x (torch.Tensor): Input tensor of shape (batch_size, in_features).
+
+        Returns:
+            torch.Tensor: B-spline bases tensor of shape (batch_size, in_features, grid_size + spline_order).
+        """
+        assert x.dim() == 2 and x.size(1) == self.in_features
+
+        grid: torch.Tensor = self.grid
+        x = x.unsqueeze(-1)
+
+        # Determine active spline basis
+        bases = ((x >= grid[:, :-1]) & (x < grid[:, 1:])).to(x.dtype)
+        for k in range(1, self.spline_order + 1):
+            bases = (
+                (x - grid[:, : -(k + 1)]) / (grid[:, k:-1] - grid[:, : -(k + 1)]) * bases[:, :, :-1]
+            ) + ((grid[:, k + 1 :] - x) / (grid[:, k + 1 :] - grid[:, 1:(-k)]) * bases[:, :, 1:])
+
+        assert bases.size() == (
+            x.size(0),
+            self.in_features,
+            self.grid_size + self.spline_order,
+        )
+        return bases.contiguous()
+
+    def forward_internal(self, x: torch.Tensor, d: torch.Tensor):
+        """Internal forward pass computing both primal (physics) and dual (severity)."""
+        assert x.size(-1) == self.in_features
+        original_shape = x.shape
+        x = x.reshape(-1, self.in_features)
+        d = d.reshape(-1, self.in_features)
+
+        # 1. Linear track (primal and dual)
+        if self.pure_spline_mode:
+            base_output = 0.0
+            dual_output = 0.0
+        else:
+            effective_weight = self.base_weight + (1.0 / self.in_features)
+            base_output = F.linear(self.base_activation(x), effective_weight)
+            # Dual severity propagates purely through absolute weights
+            dual_output = F.linear(d, effective_weight.abs())
+
+        # 2. Spline track (*clamped* primal only)
+        lower_bound, upper_bound = self.grid_range
+        if self.spline_order == 0:
+            # Deg-0 splines lack padding knots, so force the interval open
+            upper_bound -= 1e-6
+        if torch.jit.is_tracing() or x.min() < lower_bound or x.max() > upper_bound:
+            x = x.clamp(lower_bound, upper_bound)
+
+        spline_output = F.linear(
+            self.b_splines(x).view(x.size(0), -1),
+            self.spline_weight.view(self.out_features, -1),
+        )
+        if self.spline_dropout > 0.0:
+            spline_output = F.dropout(spline_output, p=self.spline_dropout, training=self.training)
+
+        if torch.is_grad_enabled() and dual_output.max() > 1e-6:
+            # Gaussian drop-off: exp(-(x * 2.5)^2)
+            # 0.01 -> 99.9% trust (noise is ignored)
+            # 0.10 -> 93.9% trust (minor leakage allowed)
+            # 0.50 -> 20.9% trust (aggressively pinching off)
+            # 1.00 ->  0.1% trust (hard detach)
+            trust = torch.exp(-((dual_output.detach() * 2.5) ** 2))
+            spline_output = trust * spline_output + (1.0 - trust) * spline_output.detach()
+
+        # 3. Combine and return tuple
+        x_final = (base_output + spline_output).reshape(*original_shape[:-1], self.out_features)
+        d_final = dual_output.reshape(*original_shape[:-1], self.out_features)
+        return x_final, d_final
+
+    def forward(self, x: torch.Tensor, return_dual: bool = False):
+        """Public API. Assumes zero incoming severity if used as a standalone layer."""
+        d = torch.zeros_like(x)
+        x_out, d_out = self.forward_internal(x, d)
+        return (x_out, d_out) if return_dual else x_out
+
+
+class KAN(torch.nn.Module):
+    """Kolmogorov-Arnold Network (KAN) macro-architecture composed of sequentially stacked KANLinear layers.
+
+    Coordinates deep layer propagation by chaining self-contained Bounded KAN blocks. If
+    `pure_spline_mode` is False, the underlying layers maintain an internal scale-preserving
+    uniform baseline that seamlessly conserves signal magnitude across dimensional changes
+    (expansions/contractions) during extreme out-of-bounds anomalies.
+
+    Args:
+        layer_dims: Architectural dimensions mapping from input to output features (e.g., [input_dim, hidden_dim, output_dim]).
+        grid_size: Number of inner intervals partitioning the spline domain
+        spline_order: Polynomial degree of the local B-spline bases.
+        base_activation: Activation function applied exclusively to the linear track. Change with caution - see README!
+        grid_range: Physical bounds `(lower, upper)` defining the spline evaluation domain.
+        pure_spline_mode: If True, completely disables the linear track across all child layers, forcing hard
+            saturation/clipping at boundaries instead of proportional linear extrapolation.
+        spline_dropout: Dropout probability, to encourage asymptote learning.
+        interaction_map: Multiplicative feature interaction indices. Use to define explicit cross-terms while preserving
+            strict OOB propagation.
+    """
+
+    def __init__(
+        self,
+        layer_dims: list[int],
+        grid_size: int = 5,
+        spline_order: int = 3,
+        base_activation: torch.nn.Module = torch.nn.Identity,
+        grid_range: tuple[float, float] = (-1.0, 1.0),
+        pure_spline_mode: bool = False,
+        spline_dropout: float = 0.0,
+        interaction_map: list[list[int]] = [],
+        symbolic_order: int = 0,
+    ):
+        super().__init__()
+        self.interactor = KANInteraction(interaction_map, grid_range)
+        self.layer_dims = layer_dims
+        eff_layer_dims = list(layer_dims)
+        eff_layer_dims[0] += len(interaction_map)
+
+        self.layers = torch.nn.ModuleList()
+        for in_features, out_features in zip(eff_layer_dims, eff_layer_dims[1:]):
+            self.layers.append(
+                KANLinear(
+                    in_features,
+                    out_features,
+                    grid_size=grid_size,
+                    spline_order=spline_order,
+                    base_activation=base_activation,
+                    grid_range=grid_range,
+                    spline_dropout=spline_dropout,
+                    pure_spline_mode=pure_spline_mode,
+                    _quiet_init=symbolic_order > 0,
+                )
+            )
+
+        # 2. The Shallow Polynomial Skip Connection
+        self.symbolic_order = symbolic_order
+        if self.symbolic_order > 0:
+            self.poly_skip = PolynomialSkip(
+                in_features=eff_layer_dims[0], out_features=eff_layer_dims[-1], order=symbolic_order
+            )
+
+    def extra_repr(self) -> str:
+        # Most information is already in the layers, just add the pre-interactions dim
+        return f"in_features={self.layer_dims[0]}"
+
+    def forward(
+        self, x: torch.Tensor | tuple[torch.Tensor, torch.Tensor], return_dual: bool = False
+    ):
+        if isinstance(x, tuple):
+            if self.interactor.interaction_map:
+                raise ValueError(
+                    "Both explicit and implicit interactions supplied. This is not supported."
+                )
+            x, d = x
+            if x.shape[1] != self.layers[0].in_features:
+                raise ValueError(
+                    f"Wrong input dimension {x.shape[1]}, expected {self.layers[0].in_features}"
+                )
+        else:
+            if x.shape[1] != self.layer_dims[0]:
+                raise ValueError(
+                    f"Wrong input dimension {x.shape[1]}, expected {self.layer_dims[0]}"
+                )
+            x, d = self.interactor(x)
+
+        if self.symbolic_order > 0:
+            poly_out, poly_dual = self.poly_skip(x, d)
+
+        # Route features along with dual through the layers
+        for layer in self.layers:
+            x, d = layer.forward_internal(x, d)
+        if self.symbolic_order > 0:
+            x = x + poly_out
+            d = d + poly_dual
+
+        return (x, d) if return_dual else x

physkan-0.1.0.dist-info/METADATA

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: physkan
+Version: 0.1.0
+Summary: A physics-constrained Kolmogorov-Arnold Network with bounded latent spaces.
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: torch>=2.9.0
+Provides-Extra: dev
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# PhysKAN
+
+**Physics-constrained Kolmogorov-Arnold Networks for stable system identification**
+
+This repository provides a structural adaptation of the B-spline Kolmogorov-Arnold Network (KAN) architecture, designed for physical system identification, digital twins, and robust regression.
+
+While standard KANs perform well at function approximation in purely mathematical domains, applying them to physical telemetry often requires interventions, like dynamic grid updates or statistical normalization such as LayerNorm, to handle out-of-bounds (OOB) anomalies.
+In this context, OOB refers to any data point that exceeds the nominal operational range of the system, whether caused by a real but long-tail phenomenon (e.g., unseen weather regimes) or a transient sensor failure (e.g., signal spikes).
+Unfortunately, these standard deep learning techniques remove the spatial meaning of the network's internal variables.
+
+This architecture addresses this by freezing the spatial grid and enforcing strict physical bounds natively, prioritizing metric stability and OOB safety over localized curve-fitting flexibility.
+It also uses forward uncertainty propagation with interval arithmetic to track the OOB state through the network.
+
+
+## Core design philosophy
+
+PhysKAN is built on three central ideas, meant to bridge the gap between theoretical non-linear mapping and the robust fail-safes required for physical engineering:
+
+1. **Progressive Koopman-style unbending:** Rather than relying on black-box MLP node activations, the model acts as a structural filter.
+It uses constrained B-splines to progressively unbend non-linear physical inputs layer-by-layer, lifting them into a linearized latent space (analogous to finding "observables" in Koopman Operator Theory).
+
+2. **Embrace out-of-bounds (OOB) values:** Real-world physics do not stay neatly within standardized grids.
+Instead of arbitrarily squashing long-tail events or sensor glitches with clamps or global activations, the architecture uses the grid range to explicitly define the boundary between the dense, well-modeled operational regime and the sparse, asymptotic tail.
+OOB states are safely clamped on the non-linear spline track and routed unclamped through a parallel linear track, ensuring mathematically stable extrapolation.
+
+3. **Epistemic uncertainty tracking:** The network computes a continuous dual property alongside the physical prediction.
+This signal forward-propagates the mathematical severity of any out-of-bounds state, providing a deterministic measure of when the network is forced to extrapolate.
+
+---
+
+## Under the hood: the OOB routing mechanism
+
+To safely execute this philosophy, the network requires a specific mental model for how it routes data—especially during the backward pass.
+
+In standard implementations, out-of-bounds data either "falls off" the spline grid entirely (dropping to zero) or requires the input to be clamped or bounded.
+However, if clamped *without* gradient detachment, the boundary knot absorbs the training loss for all out-of-bounds states.
+It becomes a wastebasket for outlying values, compressing the long-tail distribution into a single coordinate and warping predictions for nominal operations.
+
+The PhysKAN architecture acts as a traffic cop for physical regimes:
+* **The nominal regime (non-linear track):** Dense, expected data operates inside the grid, shaping the non-linear B-splines.
+* **The out-of-bounds regime (linear track):** OOB data are clamped on the non-linear track (with detached gradients to protect the nominal-range knots).
+The excess signal flows entirely through the linear track.
+
+This ensures the non-linear splines strictly learn the nominal physics, while the linear track safely catches long-tail events.
+
+## Architectural constraints
+
+To maintain the absolute physical meaning of these latent observables during deployment, the model relies on two structural constraints:
+
+### 1. Static grid boundaries
+
+KAN architectures often rely on dynamic grid updates (knot insertion or movement) during training.
+This architecture disables this.
+Dynamic updates shift the underlying coordinate system of the network mid-training, causing downstream layers to lose their physical calibration.
+By enforcing a static grid, the model sacrifices some theoretical curve-fitting capacity to guarantee that a specific latent state retains its exact metric meaning from initialization to deployment.
+
+### 2. Linear skip connections as safety valves
+Because the spline gradients are detached for OOB values, the network routes the excess gradients entirely through the parallel linear skip connection.
+This serves as a vital safety valve: it protects the non-linear splines from gradient pollution, and it ensures that OOB inputs extrapolate linearly and predictably.
+This limits the downstream impact of anomalies, making system filtering more reliable.
+
+#### Justification for linear extrapolation (physical basis functions)
+
+While real-world OOB events often exhibit higher-order scaling (e.g., cubic wave resistance), the model enforces a linear default for OOB extrapolation.
+This is a deliberate design choice to prevent mathematical instability caused by sensor faults. 
+
+To safely capture higher-order OOB physics, domain knowledge should be embedded directly via feature engineering.
+As long as the input features form a sufficient physical basis, particularly for asymptotic behaviours, the linear skip connection will naturally capture higher-order OOB phenomena as a linear combination of features without compromising the nominal operating region.
+
+Applying a post-summation node activation (such as `SiLU` or `tanh`) fundamentally sabotages this mechanism.
+A non-linear activation will warp the magnitude of the OOB event, rendering the linear skip connection unable to model it.
+For this reason, activations are disabled by default (using `Identity`).
+Other activations may be selected, but beware that the guarantees provided by "standard" PhysKAN may be weakened or destroyed.
+
+## Feature engineering and explicit interactions
+
+Deep architectures can theoretically learn multiplicative interactions (such as computing `x * y` by combining multiple layers).
+Making the network deduce these relationships from scratch consumes capacity and degrades poorly when out-of-bounds.
+Instead, to capture known physical behaviors, domain knowledge should be embedded directly via feature engineering.
+Providing the network with a dictionary of physical basis functions (e.g., `x^2` or `cos(θ)`) allows the linear skip connection to latch onto these engineered features as a stable baseline.
+This leaves the splines to map the local residuals, ensuring safe extrapolation when the splines saturate.
+
+However, combining features naively can mask out-of-bounds anomalies.
+If you manually pre-compute an interaction like `wave_height * cos(wind_dir)` and pass it to the network as a raw input, the anomaly signal is suppressed.
+For instance, if `wave_height` is OOB (e.g., twice nominal range) but `cos(wave_dir)` is near zero, their product is well within nominal bounds.
+The model treats this as a regular in-bounds prediction, and uses the data point to update its nominal-range spline.
+
+To prevent this suppression, the network requires interaction terms to be defined internally via an `interaction_map` rather than expanded manually beforehand.
+
+The network computes a continuous dual property alongside the standard physical prediction.
+This dual represents the mathematical severity of the out-of-bounds state. 
+* The *physical prediction* is computed using the non-linear splines and the linear track.
+* The *dual severity* strictly bypasses the splines and propagates via the absolute values of the linear weights, ensuring that uncertainties compound and never cancel out.
+
+By defining interactions explicitly through the `interaction_map`, the model correctly applies the uncertainty product rule to the input features before they enter the network.
+If a large wave anomaly interacts with a nominal-range cosine, the resulting interaction term inherits a proportional severity score.
+This deterministic distress signal persists through the entire depth of the network, ensuring that the non-linear splines are firewalled from learning from the anomaly, while the linear track safely handles the extrapolated magnitude.
+It also provides downstream consumers with a clear indicator of when the model is operating on dodgy data.
+
+### Defining the nominal range: data density vs. physical limits
+
+When defining the `grid_range` and normalizing inputs, the boundaries should reflect the density of the training data rather than the theoretical limits of the physical system.
+
+B-splines require consistent data distribution across their internal grid to form a stable curve.
+If for example a physical feature (such as wave height) has a theoretical operational limit of 5.0 meters, but the training dataset becomes sparse above 2.0 meters, setting the spline boundary to 5.0 meters forces the model to fit curves in an under-constrained region.
+This often causes the splines to oscillate or overfit to a handful of isolated data points.
+
+Instead, the grid boundary should be placed where the data density noticeably drops off (e.g., at 2.0 meters).
+By treating the sparse region as out-of-bounds, the network safely clamps the splines in the dense region and relies on the linear track to extrapolate smoothly through the sparse tail.
+The working principle is to treat the nominal range strictly as the bounds of the dense training data.
+
+## Installation
+
+You can install the package directly from GitHub:
+
+```bash
+pip install git+[https://github.com/simula/physkan.git](https://github.com/simula/physkan.git)
+
+## Usage example
+
+The model handles explicit feature expansion and interval arithmetic internally. A standard linear layer should be used as the final readout.
+
+```python
+import torch
+import torch.nn as nn
+from physkan import KAN
+
+# Define explicit cross-terms using indices
+# e.g., for features [wave, wind, cos_dir]:
+# [0, 0] adds wave^2
+# [0, 2] adds wave * cos_dir
+interactions = [[0, 0], [0, 2]]
+
+# The KAN model automatically expands the initial input dimension
+# and sets up the continuous dual routing.
+kan_encoder = KAN(
+    layers_dims=[3, 16, 8], # Input dim is 3 (wave, wind, cos_dir)
+    grid_range=(0.0, 1.0),
+    interaction_map=interactions
+)
+
+# The readout: Linear combination of the final observables of a zero-at-rest (unbiased) system
+linear_mixer = nn.Linear(in_features=8, out_features=1, bias=False)
+
+model = nn.Sequential(
+    kan_encoder,
+    linear_mixer
+)
+
+# Nominal physical data
+x_nominal = torch.tensor([[0.5, 0.8, 0.1]])
+
+# Pass data through the encoder, requesting the dual distress signal
+latent_features, severity_signal = kan_encoder(x_nominal, return_dual=True)
+prediction = linear_mixer(latent_features)
+
+# For an out-of-bounds event (e.g., wave height sensor reads 5.0)
+x_oob = torch.tensor([[5.0, 0.8, 0.1]])
+latent_oob, severity_oob = kan_encoder(x_oob, return_dual=True)
+
+# severity_oob > 0 indicates the prediction relies on mathematically 
+# extrapolated values, allowing downstream logic to trigger heuristics.
+if severity_oob.mean() > 0.0:
+    print("Warning: operating in uncharted physical regime.")
+```
+
+## Attribution
+
+This repository is an adaptation of the excellent **[efficient-kan](https://github.com/Blealtan/efficient-kan)** library by Blealtan.
+
+The core B-spline evaluation mechanics, memory-efficient tensor formulation, and foundational matrix operations are directly derived from `efficient-kan`.
+The modifications introduced here are strictly architectural (specifically the detached routing, strict boundary clamping, interval arithmetic dual, and default identity activations) designed to constrain the network for physical system identification.
+Full credit for the underlying efficiency and base implementation belongs to the original author.

physkan-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+physkan/__init__.py,sha256=RRNVtHe-4aeA8CqQGi_dS6-JCkkj8DUPTlfvIL6jHKo,736
+physkan/demonstrator.py,sha256=TWom4dYMxyZ5I6gkFyEYJ4-0zDIFUW9IpLnSKwETR3Y,3637
+physkan/interaction.py,sha256=9Y5k2H0q60m-tKexvTmDS3BQ473RsciTWW4MRVQEIb8,4423
+physkan/kan.py,sha256=67YDX_IjKiN7f0k8r9YO4or1kwBy2OHgAcLWX--fqMY,10727
+physkan-0.1.0.dist-info/METADATA,sha256=T_QzvnGvIFKtk0-K_5Ja9Q-21eX40GuTwcUWrbJeMxM,12274
+physkan-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+physkan-0.1.0.dist-info/licenses/LICENSE,sha256=cKUELmUqTmMhIckxOzk8eFnSKbq7D8KUfZLnMuOg_MQ,1153
+physkan-0.1.0.dist-info/RECORD,,

physkan-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

physkan-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Based on efficient-kan, copyright (c) 2024 Huanqi Cao.
+Modifications copyright (c) 2026 Simula Research Laboratory.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.