{"id":50937954,"url":"https://github.com/simula/physkan","last_synced_at":"2026-06-17T11:03:26.514Z","repository":{"id":362361528,"uuid":"1258694448","full_name":"simula/physkan","owner":"simula","description":"Physics-constrained Kolmogorov-Arnold Networks for stable system identification","archived":false,"fork":false,"pushed_at":"2026-06-15T07:59:18.000Z","size":87,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-15T09:12:06.233Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/simula.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-03T20:36:32.000Z","updated_at":"2026-06-15T07:59:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/simula/physkan","commit_stats":null,"previous_names":["simula/bounded-kan","simula/physkan"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/simula/physkan","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simula%2Fphyskan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simula%2Fphyskan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simula%2Fphyskan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simula%2Fphyskan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simula","download_url":"https://codeload.github.com/simula/physkan/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simula%2Fphyskan/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34445186,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-17T11:03:15.843Z","updated_at":"2026-06-17T11:03:26.506Z","avatar_url":"https://github.com/simula.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PhysKAN\n\n**Physics-constrained Kolmogorov-Arnold Networks for stable system identification**\n\nThis repository provides a structural adaptation of the B-spline Kolmogorov-Arnold Network (KAN) architecture, designed for physical system identification, digital twins, and robust regression.\nWhile 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, to handle out-of-bounds (OOB) anomalies.\nIn 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).\nUnfortunately, these standard deep learning techniques remove the spatial meaning of the network's internal variables.\nThis architecture addresses this by freezing the spatial grid and enforcing physical bounds natively, prioritizing metric stability and OOB safety over localized curve-fitting flexibility.\nIt also uses forward uncertainty propagation with interval arithmetic to track the OOB state through the network.\n\n## Core design philosophy\n\nPhysKAN is built on three central ideas, meant to bridge the gap between theoretical non-linear mapping and the fail-safes required for physical engineering:\n\n1. **Koopman-style unbending:** Rather than relying on black-box MLP node activations, the model acts as a structural filter.\nIt uses constrained B-splines to unbend the non-linear physical inputs, lifting them into a linearized latent space.\n\n2. **Embrace out-of-bounds (OOB) values:** Real-world physics do not stay neatly within standardized grids.\nInstead 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 tail.\nOOB states are clamped on the non-linear spline track and routed unclamped through a parallel linear track, ensuring stable extrapolation.\n\n## Under the hood: the out-of-bounds routing mechanism\n\nTo execute this philosophy, the network requires a specific mental model for how it routes data, especially during the backward pass.\nIn standard implementations, out-of-bounds data either falls off the spline grid entirely or requires the input to be clamped.\nHowever, if clamped without gradient detachment, the boundary knot absorbs the training loss for all out-of-bounds states.\nIt becomes a wastebasket for outlying values, compressing the long-tail distribution into a single coordinate and warping predictions for nominal operations.\nThe PhysKAN architecture routes data based on physical regimes.\nDense, expected data operates inside the grid, shaping the non-linear B-splines.\nOOB data are clamped on the non-linear track, with detached gradients to protect the nominal-range knots.\nThe excess signal flows entirely through the linear track.\nThis ensures the non-linear splines learn the nominal physics, while the linear track catches long-tail events.\n\n## Architectural constraints\n\nTo maintain the physical meaning of these latent observables during deployment, the model relies on structural constraints.\n\n### 1. Static grid boundaries\n\nKAN architectures often rely on dynamic grid updates during training.\nThis architecture disables this feature.\nDynamic updates shift the underlying coordinate system of the network mid-training, causing downstream layers to lose their physical calibration.\nBy enforcing a static grid, the model sacrifices some curve-fitting capacity to guarantee that a specific latent state retains its metric meaning from initialization to deployment.\n\n### 2. Linear skip connections as safety valves\n\nBecause the spline gradients are detached for OOB values, the network routes the excess gradients entirely through the parallel linear skip connection.\nThis serves as a safety valve.\nIt protects the non-linear splines from gradient pollution, and it ensures that OOB inputs extrapolate linearly and predictably.\nThis limits the downstream impact of anomalies, making system filtering more reliable.\n\n#### Justification for linear extrapolation\n\nWhile real-world OOB events often exhibit higher-order scaling, the model enforces a linear default for OOB extrapolation.\nThis is a deliberate design choice to prevent mathematical instability caused by sensor faults.\nTo capture higher-order OOB physics, domain knowledge should be embedded directly via feature engineering.\nAs long as the input features form a sufficient physical basis, the linear skip connection will naturally capture higher-order OOB phenomena as a linear combination of features.\nApplying a post-summation node activation (such as SiLU or tanh) sabotages this mechanism.\nA non-linear activation will warp the magnitude of the OOB event, rendering the linear skip connection unable to model it.\nFor this reason, activations are disabled by default.\n\n### 3. Target isolation in multi-output networks\n\nWhen deploying multi-output configurations, using deep hidden layers can introduce cancellation entanglement.\nThe network may fit a zero-impact relationship by balancing opposing weights across internal nodes rather than setting the weights to zero.\nWhile the physical output remains correct within nominal ranges, this hidden entanglement is unstable out-of-bounds.\nTo achieve decoupled causal isolation between targets, a shallow architecture with no hidden layers should be used.\n\n## Feature engineering and explicit interactions\n\nDeep architectures can deduce multiplicative interactions, such as computing the product of two inputs by combining multiple layers.\nForcing the network to learn these relationships from scratch consumes capacity and degrades when out-of-bounds.\nTo capture physical behaviors, domain knowledge should be embedded directly via feature engineering.\nProviding the network with a dictionary of physical basis functions allows the linear skip connection to latch onto these features as a baseline.\nThis leaves the splines to map the local residuals.\nHowever, combining features naively outside the network can mask out-of-bounds anomalies.\nIf a large wave anomaly interacts with a nominal-range cosine feature, their product may fall within nominal bounds, suppressing the anomaly signal.\nTo prevent this suppression, PhysKAN provides two orthogonal paths to define interactions internally.\nFor known asymptotic behaviors, the preferred method is passing an explicit `interaction_map` to the constructor.\nFor unknown interactions, setting `symbolic_order` greater than zero allows the network to automatically set up an internal polynomial expansion directly from the raw inputs.\n\n### Defining the nominal range: data density vs. physical limits\n\nWhen defining the grid boundaries and normalizing inputs, the ranges should reflect the density of the training data rather than the theoretical limits of the physical system.\nB-splines require consistent data distribution across their internal grid to form a stable curve.\nIf the training dataset becomes sparse well before the theoretical operational limit, setting the spline boundary to the theoretical limit forces the model to fit curves in an under-constrained region.\nThis can cause the splines to oscillate or overfit to isolated data points.\nInstead, the grid boundary should be placed where the data density drops off.\nBy treating the sparse region as out-of-bounds, the network clamps the splines in the dense region and relies on the linear track to extrapolate through the sparse tail.\n\n## Installation\n\nYou can install the package from pip:\n\n```bash\npip install physkan\n```\n\n## Usage example\n\nA shallow setup is strongly recommended, as it provides direct mapping without hidden entanglement.\n\n```python\nimport torch\nimport torch.nn as nn\nfrom physkan import KAN\n\n# Initialize a minimal shallow model.\n# layer_dims defines a direct mapping from 2 inputs to 1 output.\nmodel = KAN(\n    layer_dims=[2, 1],\n    grid_size=5,\n    spline_order=3\n)\n\n# Standard training optimization loop setup.\noptimizer = torch.optim.Adam(model.parameters(), lr=1e-3)\ncriterion = nn.MSELoss()\n\n# Nominal physical data\nx_nominal = torch.tensor([[0.5, 0.1]])\n\n# Pass data through the model\nprediction, severity_signal, _ = model(x_nominal, return_damage=True)\n\n# For an out-of-bounds event\nx_oob = torch.tensor([[4.0, 0.1]])\nprediction_oob, severity_oob, _ = model(x_oob, return_damage=True)\n\n# Severity greater than zero indicates the prediction relies on extrapolated values.\nif severity_oob.max() \u003e 0.0:\n    print(\"Warning: operating in uncharted physical regime.\")\n```\n\n## Demos\n\nTo see the out-of-bounds routing, cancellation entanglement, and hybrid symbolic architecture in action, please review the demonstrator notebooks provided in this repository, starting with `demo/demo.py`.\n\n## Attribution\n\nThis repository is an adaptation of the excellent `efficient-kan` library by Blealtan.\nThe B-spline evaluation mechanics, memory-efficient tensor formulation, and matrix operations are derived from that work.\nThe modifications introduced here are architectural, designed to constrain the network for physical system identification.\n\nCredit for the underlying efficiency and base implementation belongs to the original author.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimula%2Fphyskan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimula%2Fphyskan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimula%2Fphyskan/lists"}