physkan 0.1.0__tar.gz

physkan-0.1.0/.gitignore

@@ -0,0 +1 @@
+**/__pycache__/

physkan-0.1.0/.ipynb_checkpoints/demo-checkpoint.py

@@ -0,0 +1,246 @@
+# %% [markdown]
+# # Bounded-KAN: Architecture Demonstrations
+# This suite systematically proves the uncertainty-forwarding and gradient 
+# firewall mechanics of the Bounded-KAN architecture.
+
+# %%
+import torch
+import torch.nn as nn
+from physkan import KAN, KANDemonstrator, KANLinear
+
+torch.manual_seed(42)
+
+# Helper: Generate raw physical state (x)
+def generate_x_data(x_min, x_max, steps=200):
+    return torch.linspace(x_min, x_max, steps).unsqueeze(1)
+
+# Helper: Generate raw physical state (x) and angle (theta)
+def generate_x_theta_train(steps=400):
+    x = torch.rand(steps, 1) * 2 - 1
+    # Full phase [-pi, pi] to break collinearity and ensure cos(theta) spans [-1, 1]
+    theta = torch.rand(steps, 1) * 2 * torch.pi - torch.pi 
+    return torch.cat([x, theta], dim=1)
+
+def generate_x_theta_eval(x_min, x_max, steps=200):
+    x = torch.linspace(x_min, x_max, steps).unsqueeze(1)
+    # Lock theta at 1.5 rad (~85 deg) so cos(theta) is near 0.07.
+    # This specifically exposes the naive multiplication trap for evaluation.
+    theta = torch.full((steps, 1), 1.5)
+    return torch.cat([x, theta], dim=1)
+
+# %%
+# %matplotlib inline
+
+# %% [markdown]
+# # 0a. Standard KAN Vulnerability (Arbitrary OOB)
+# **Goal:** Mimic an unprotected KAN using narrow nominal bounds `(-1.0, 1.0)` and 
+# the default `SiLU` base activation. We train on the nominal range and extrapolate.
+#
+# **Result:** While our native clamp turns the violent out-of-bounds discontinuity 
+# into a plateau, the asymmetric nature of `SiLU` (linear for positive, zero for 
+# negative) makes extrapolation arbitrary. It grows on the right but flatlines on 
+# the left. 
+
+# %%
+model_0a = KANLinear(
+    in_features=1,
+    out_features=1,
+    grid_size=5, 
+    spline_order=3, 
+    grid_range=(-1.0, 1.0),
+    base_activation=nn.SiLU
+)
+demo_0a = KANDemonstrator(model=model_0a, target_fn=lambda x: x**2)
+
+demo_0a.train(generate_x_data(-1.0, 1.0, 100))
+demo_0a.plot(generate_x_data(-4.0, 4.0, 200), "0a. Narrow Bounds (Arbitrary SiLU Asymmetry)")
+
+# %% [markdown]
+# # 0b. The "Wide Grid" Fallacy (Untrained Knot Collapse)
+# **Goal:** Mimic a practitioner trying to fix 0a by expanding the bounds to cover 
+# the extrapolation limits `(-4.0, 4.0)`. We increase `grid_size` proportionally 
+# to maintain resolution.
+#
+# **Result:** B-splines have strictly local support. The knots in the `(1.0, 4.0)` 
+# region receive absolutely zero gradient updates during training. The prediction 
+# completely detaches from the physics and outputs chaotic initialization noise, 
+# proving why expanding bounds without data is mathematically unsafe.
+
+# %%
+model_0b = KANLinear(
+    in_features=1,
+    out_features=1,
+    grid_size=20,           # Increased to maintain resolution over wider bounds
+    spline_order=3, 
+    grid_range=(-4.0, 4.0), # The practitioner's "fix"
+    base_activation=nn.SiLU
+)
+demo_0b = KANDemonstrator(model=model_0b, target_fn=lambda x: x**2)
+
+demo_0b.train(generate_x_data(-1.0, 1.0, 100))
+demo_0b.plot(generate_x_data(-4.0, 4.0, 200), "0b. Wide Bounds Fallacy (Untrained Extrapolation)")
+
+# %% [markdown]
+# # 0c. The Data Sparsity Vulnerability (The Interpolation Hole)
+# **Goal:** The practitioner now tries to train across the full wide grid `(-1.0, 4.0)`. 
+# However, real physical data has gaps. We filter out all training data between `2.0` 
+# and `3.5` to simulate a sparse transition regime (e.g., ships avoiding marginal weather).
+#
+# **Result:** Even though the bounds enclose all the data, the knots *inside the hole* # receive zero gradient updates. Instead of bridging the gap smoothly, the prediction 
+# violently collapses into the void, outputting untrained noise. This proves that 
+# relying purely on splines across sparse datasets destroys physical identification.
+
+# %%
+model_0c = KANLinear(
+    in_features=1,
+    out_features=1,
+    grid_size=20,          
+    spline_order=3, 
+    grid_range=(-1.0, 4.0),
+    base_activation=nn.SiLU
+)
+demo_0c = KANDemonstrator(model=model_0c, target_fn=lambda x: x**2)
+
+# Generate full data, then explicitly mask out the (2.0 to 3.5) transition regime
+x_train_0c = generate_x_data(-1.0, 4.0, steps=200)
+x_train_sparse = x_train_0c[(x_train_0c[:, 0] < 1.5) | (x_train_0c[:, 0] > 3.5)]
+
+demo_0c.train(x_train_sparse)
+demo_0c.plot(generate_x_data(-4.0, 4.0, 200), "0c. Data Sparsity (Interpolation Hole Collapse)")
+
+# %% [markdown]
+# # 1. Spline Plateau (Symmetric Linear Track)
+# **Goal:** Show how Bounded-KAN behaves with the strict `Identity` linear baseline. 
+#
+# **Result:** Inside the bounds, the splines perfectly fit the curve. Out of bounds, 
+# the mechanical clamp safely freezes the splines to prevent chaotic oscillation. 
+# However, notice that the left-side extrapolation actually looks slightly *worse* # than the naive SiLU in Case 0a! 
+#
+# **Why?** The symmetry exists in the training data, but *we structurally 
+# enforced* an asymmetric linear asymptote by using the strict `Identity` base track. 
+# The splines easily fit the symmetric parabola locally, while the base track absorbs 
+# a slight residual slope. When the splines clamp out of bounds, that raw linear slope 
+# is exposed. We intentionally trade the arbitrary, "lucky" flatlining of SiLU for 
+# strict, predictable linear extrapolation.
+#
+# **Try this:** If you know the physical domain is symmetric, you can pass `base_activation=torch.abs` when initializing the model
+# to structurally enforce a symmetric V-shape out of bounds. While this makes the baseline extrapolation look slightly better,
+# it is still just a linear approximation. In general, the explicit feature engineering demonstrated in step 2 is the preferred
+# approach.
+
+# %%
+model_1 = KAN(layer_dims=[1, 1], grid_size=5, spline_order=3)
+demo_1 = KANDemonstrator(model=model_1, target_fn=lambda x: x**2)
+
+demo_1.train(generate_x_data(-1.0, 1.0, 100))
+demo_1.plot(generate_x_data(-4.0, 4.0, 200), "1. Spline Plateau (Symmetric Linear Track)")
+
+# %% [markdown]
+# # 2a. Linear Recovery via Feature Engineering
+# **Goal:** Provide $x^2$ as an engineered feature. Show that extrapolation now 
+# works perfectly because the unbroken linear track carries the out-of-bounds scaling.
+
+# %%
+model_2a = KAN(layer_dims=[2, 1], grid_size=5, spline_order=3)
+demo_2a = KANDemonstrator(
+    model=model_2a, 
+    target_fn=lambda x: x**2,
+    feature_fn=lambda x: torch.cat([x, x**2], dim=1)
+)
+
+demo_2a.train(generate_x_data(-1.0, 1.0, 100))
+demo_2a.plot(generate_x_data(-4.0, 4.0, 200), "2. Linear Recovery (Engineered $x^2$)")
+
+# %% [markdown]
+# # 2b. Interval Protection (The Collinearity Fix)
+# **Goal:** Use the `KANInteraction` module to compute the product using interval 
+# arithmetic. We feed the network $x^2$, $\cos(\theta)$, and their interaction.
+#
+# **Result:** Look at the bottom plot—the firewall worked perfectly! It recognized 
+# the massive out-of-bounds variance of $x$ and slammed the severity $D$ up to 6.0. 
+# However, the physical prediction (top plot) overshoots. Why? Spurious correlation.
+# During training, the network got lazy. Instead of relying purely on the interaction 
+# feature, it put weight on the raw $x^2$ feature, and used the splines to cancel 
+# out the error. When extrapolated, the splines clamped, the cancellation stopped, 
+# and the raw $x^2$ error shot up. This proves why severity tracking is non-negotiable!
+
+# %%
+model_2b = KAN(layer_dims=[1, 1], interaction_map=[[0, 0]], grid_size=5, spline_order=3)
+demo_2b = KANDemonstrator(
+    model=model_2b, 
+    target_fn=lambda x: x**2,
+    feature_fn=lambda x: x
+)
+
+demo_2b.train(generate_x_data(-1.0, 1.0, 100))
+demo_2b.plot(generate_x_data(-4.0, 4.0, 200), "2. Linear Recovery (Engineered $x^2$)")
+
+# %% [markdown]
+# # 2c. The Dropout Fix (Forcing Physical Isolation)
+# **Goal:** How do we stop the network from using splines as a crutch to hide bad 
+# linear weights? We introduce **Spline Dropout**. By randomly zeroing out the 
+# splines during training, the linear track is forced to explain as much as possible of the physical features. 
+#
+# **Result:** The linear track sets the weight of pure $x^2$ to zero, and the weight 
+# of the interaction feature to 1.0. The physical prediction is now perfectly flat 
+# (matching the true physics), AND the severity firewall remains fully active.
+
+# %%
+model_2c = KAN(layer_dims=[1, 1], interaction_map=[[0, 0]], grid_size=5, spline_order=3, spline_dropout=0.05)
+demo_2c = KANDemonstrator(
+    model=model_2c,
+    target_fn=lambda x: x**2,
+    feature_fn=lambda x: x
+)
+
+demo_2c.train(generate_x_data(-1.0, 1.0, 100))
+demo_2c.plot(generate_x_data(-4.0, 4.0, 200), "2c. The Dropout Fix (Perfect Physics + Firewall)")
+
+# %% [markdown]
+# # 3a. Protected Interaction Layer
+# **Goal:** Use the `KANInteraction` module to compute the product. 
+# The interval arithmetic accurately assesses the high variance, raises a severe dual $D$, 
+# and slams the gradient firewall shut. Extrapolation plateaus safely.
+
+# %%
+model_3a = KAN(layer_dims=[2, 1], interaction_map=[[0, 1]], grid_size=5, spline_order=3, spline_dropout=0.05)
+demo_3a = KANDemonstrator(
+    model=model_3a,
+    target_fn=lambda x: (x[:, 0:1]**2) * torch.cos(x[:, 1:2]),
+    feature_fn=lambda x: torch.cat([x[:, 0:1]**2, torch.cos(x[:, 1:2])], dim=1)
+)
+
+demo_3a.train(generate_x_theta_train())
+demo_3a.plot(generate_x_theta_eval(-4.0, 4.0), "3a. Interval Protection (Interaction Firewall)")
+
+# %% [markdown]
+# # 3b. Deep Network Feature Discovery
+# **Goal:** Remove explicit interaction mapping. Provide just $x^2$ and $\cos(\theta)$ 
+# to a deeper network (`[2, 4, 1]`) to let it learn the interaction. Show that 
+# the dual mathematically compounds through the linear matrices, protecting the entire depth.
+
+# %%
+model_3b = KAN(layer_dims=[2, 4, 1], grid_size=5, spline_order=3)
+demo_3b = KANDemonstrator(
+    model=model_3b,
+    target_fn=lambda x: (x[:, 0:1]**2) * torch.cos(x[:, 1:2]),
+    feature_fn=lambda x: torch.cat([x[:, 0:1]**2, torch.cos(x[:, 1:2])], dim=1)
+)
+
+demo_3b.train(generate_x_theta_train(steps=800), epochs=1000)
+demo_3b.plot(generate_x_theta_eval(-4.0, 4.0), "3b. Deep Discovery (Matrix Dual Routing)")
+
+# %% [markdown]
+# **The Takeaway:** The severity firewall ($D$) still spikes perfectly, alerting us that 
+# we have left the data-driven regime. However, because the deep network relies on 
+# fragile, unconstrained spline combinations to fake multiplication, the physical 
+# extrapolation shape becomes erratic. 
+#
+# This highlights a crucial philosophical point: high severity ($D$) doesn't inherently 
+# mean "danger"—it simply means the model is now relying entirely on its structural priors. 
+# If those priors are unconstrained deep networks, extrapolation is chaotic. But if we 
+# engineer those priors correctly, we can extrapolate safely and indefinitely.
+#
+# If deep KANs and automated feature discovery are part of your plans, please proceed 
+# to `demo_deep.py` to see how we leash the beast!
+# %%

physkan-0.1.0/.ipynb_checkpoints/demo_deep-checkpoint.py

@@ -0,0 +1,147 @@
+# %% [markdown]
+# # Bounded-KAN: Architecture Demonstrations
+# This suite systematically proves the uncertainty-forwarding and gradient 
+# firewall mechanics of the Bounded-KAN architecture.
+
+# %%
+import torch
+import torch.nn as nn
+from physkan import KAN, KANDemonstrator, KANLinear
+
+torch.manual_seed(42)
+
+# Helper: Generate raw physical state (x)
+def generate_x_data(x_min, x_max, steps=200):
+    return torch.linspace(x_min, x_max, steps).unsqueeze(1)
+
+# Helper: Generate raw physical state (x) and angle (theta)
+def generate_x_theta_train(steps=400):
+    x = torch.rand(steps, 1) * 2 - 1
+    # Full phase [-pi, pi] to break collinearity and ensure cos(theta) spans [-1, 1]
+    theta = torch.rand(steps, 1) * 2 * torch.pi - torch.pi 
+    return torch.cat([x, theta], dim=1)
+
+def generate_x_theta_eval(x_min, x_max, steps=200):
+    x = torch.linspace(x_min, x_max, steps).unsqueeze(1)
+    # Lock theta at 1.5 rad (~85 deg) so cos(theta) is near 0.07.
+    # This specifically exposes the naive multiplication trap for evaluation.
+    theta = torch.full((steps, 1), 1.5)
+    return torch.cat([x, theta], dim=1)
+
+# %%
+# %matplotlib inline
+
+# %% [markdown]
+# # 3b. Deep Network Feature Discovery
+# We repeat this final example from `demo.py` for context, with takeaway
+# "... high severity ($D$) doesn't inherently 
+# mean "danger"—it simply means the model is now relying entirely on its structural priors. 
+# If those priors are unconstrained deep networks, extrapolation is chaotic. But if we 
+# engineer those priors correctly, we can extrapolate safely and indefinitely.".
+
+# %%
+torch.manual_seed(42)
+model_3b = KAN(layer_dims=[2, 4, 1], grid_size=5, spline_order=3, spline_dropout=0.1)
+demo_3b = KANDemonstrator(
+    model=model_3b,
+    target_fn=lambda x: (x[:, 0:1]**2) * torch.cos(x[:, 1:2]),
+    feature_fn=lambda x: torch.cat([x[:, 0:1]**2, torch.cos(x[:, 1:2])], dim=1)
+)
+
+demo_3b.train(generate_x_theta_train(steps=800), epochs=1000)
+demo_3b.plot(generate_x_theta_eval(-4.0, 4.0), "3b. Deep Discovery (Matrix Dual Routing)")
+
+# %% [markdown]
+# # 3c. Deep Network Feature Discovery, a hybrid approach
+# ...hybrid polynomial/kan...
+
+# %%
+torch.manual_seed(42)
+model_3c = KAN(layer_dims=[2, 4, 1], grid_size=5, spline_order=3, symbolic_order=2, spline_dropout=0.8)
+demo_3c = KANDemonstrator(
+    model=model_3c,
+    target_fn=lambda x: (x[:, 0:1]**2) * torch.cos(x[:, 1:2]),
+    feature_fn=lambda x: torch.cat([x[:, 0:1]**2, torch.cos(x[:, 1:2])], dim=1)
+)
+
+demo_3c.train(generate_x_theta_train(steps=800), epochs=1000)
+demo_3c.plot(generate_x_theta_eval(-4.0, 4.0), "3b. Hybrid Deep Discovery")
+
+# %% [markdown]
+# # 4a. Multi-target Surgical Detachment
+#
+# **Goal:** Demonstrate that the Dual Severity Tracker is not a global panic button, but a surgical, node-specific diagnostic tool. 
+#
+# We will map a system with two outputs:
+# * $y_1$ relies heavily on an $x^2$ anomaly.
+# * $y_2$ is highly insulated, relying on a stable $\cos(\theta)$ feature and a tiny fractional coefficient of $x$.
+#
+# **The Expectation:** When $x$ goes violently out of bounds, the network should aggressively firewall $y_1$ (high severity) while leaving $y_2$ almost completely untouched. The severity is quarantined because the underlying linear weights strictly dictate the localized interval routing ($|W| \cdot D$).
+
+# %%
+torch.manual_seed(42)
+
+def target_multi(x):
+    # y1 is highly sensitive to the out-of-bounds explosion
+    y1 = x[:, 0:1]**2 
+    # y2 is insulated, relying mostly on bounded cos(theta)
+    y2 = (1e-3 * x[:, 0:1]) + torch.cos(x[:, 1:2])
+    return torch.cat([y1, y2], dim=1)
+
+def feature_multi(x):
+    # Provide the exact bases so the symbolic track can perfectly map the weights
+    return torch.cat([
+        x[:, 0:1],          # Raw x
+        x[:, 0:1]**2,       # The x^2 anomaly
+        torch.cos(x[:, 1:2]) # The bounded periodic feature
+    ], dim=1)
+
+# We use 3 inputs for the 3 explicit features. 
+# symbolic_order=1 lets the global skip-connection effortlessly lock onto the correct features.
+model_4a = KAN(
+    layer_dims=[3, 4, 2], 
+    grid_size=5, 
+    spline_order=3, 
+    symbolic_order=1, 
+    spline_dropout=0.8
+)
+
+demo_4a = KANDemonstrator(
+    model=model_4a,
+    target_fn=target_multi,
+    feature_fn=feature_multi
+)
+
+demo_4a.train(generate_x_theta_train(steps=800), epochs=1000)
+demo_4a.plot(generate_x_theta_eval(-4.0, 4.0), "4a. Multi-target Surgical Detachment")
+
+# %%
+# 4b. Perfect Surgical Detachment (Shallow Architecture)
+def target_multi(x):
+    # y1 is highly sensitive to the out-of-bounds explosion
+    y1 = x[:, 0:1]**2 
+    # y2 is insulated, relying mostly on bounded cos(theta)
+    y2 = (1e-3 * x[:, 0:1]) + torch.cos(x[:, 1:2])
+    return torch.cat([y1, y2], dim=1)
+
+def feature_multi(x):
+    # Provide the exact bases so the symbolic track can perfectly map the weights
+    return torch.cat([
+        x[:, 0:1],          # Raw x
+        x[:, 0:1]**2,       # The x^2 anomaly
+        torch.cos(x[:, 1:2]) # The bounded periodic feature
+    ], dim=1)
+
+model_4b = KAN(
+    layer_dims=[3, 2], # NO hidden layers. Pure direct mapping.
+    grid_size=5, 
+    spline_order=3, 
+    symbolic_order=1, 
+    spline_dropout=0.8
+)
+
+demo_4b = KANDemonstrator(model=model_4b, target_fn=target_multi, feature_fn=feature_multi)
+demo_4b.train(generate_x_theta_train(steps=800), epochs=1000)
+demo_4b.plot(generate_x_theta_eval(-4.0, 4.0), "4b. Perfect Quarantine (Shallow)")
+
+# %%

physkan-0.1.0/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.

physkan-0.1.0/PKG-INFO

@@ -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.