noodl physics¶

noodl physics — complex networks, differentiable by design

noodl physics is an open-source framework for differentiable network modelling of physical systems, built on PyTorch. It combines graph topology, conservation laws, and modular descriptions of physical processes to model flows, storage, transport, and reactions within a common framework. Different physical systems can be composed and coupled through shared network structures, while differentiable solvers support simulation, parameter estimation, and optimisation.

The idea in one paragraph¶

An enormous range of engineering systems are networks carrying something conserved. Air moves between the rooms of a building through leaks and doors; water falls through a sewer and is pumped through a distribution main; pollutants are carried along a street and exchanged with the air above; current divides between the branches of an electrical circuit. Each of these has its own literature and its own simulation tool, and each of those tools re-implements the same three things: a graph, a conservation law at every node, and a constitutive law on every edge. noodl physics factors that common core out once. What remains specific to a problem — the pressure-flow relation of a crack, the friction law of a pipe, the chemistry of a street canyon — is a small, replaceable object plugged into the core.

Because the core is written in PyTorch, every quantity in it is a tensor and every operation is differentiable. The same model that simulates forward will also tell you the derivative of any output with respect to any parameter, which is what turns a simulator into a tool for calibration, sensitivity analysis and design optimisation.

The noodl physics model stack: a network, then constitutive laws, drives and closures, then layers, then a Model that steps them together

What it gives you¶


One topology layer	A typed multigraph with incidence, gradient and cycle-basis operators, boundary/interior selectors, spanning forests and sign-aware upwind/downwind indexing. Edges carry a `kind`, so one network holds several physical systems at once.
Four ways to determine an edge flow	Solve for a potential (Newton on a nodal conservation residual); prescribe the flow from a driver; compute it from a closure; or clip a requested flow against arc capacity and receiver headroom. Most network tools support exactly one of these.
Composable physics layers	Kirchhoff solves, multi-species and heat transport, reactions, and capacity-limited allocation — several of them on one network, stepped together under either of two coupling schemes.
Matvec-free solvers	A `LinearOperator` contract with dense, graph-Laplacian and advection implementations; Newton with per-instance convergence; an implicit-function adjoint so gradients cost one linear solve rather than an unrolled tape.
Batching over instances	Every solve is batched. A thousand building variants, or one network under a thousand weather realisations, is one call.
Verified by code-to-code comparison	Each application is compared against a reference implementation for its domain — CONTAM, MUNICH, SWMM, EPANET, WSIMOD, the Modelica Standard Library and pandapower — with the tolerances and measured errors written down.

Applications¶

noodl physics is one generic solver for networks whose edges carry a flow and whose nodes conserve it. The applications are physical systems modelled with that solver, each a thin layer of domain physics over the shared core:

Application	Physical system	Flow determination	Entry point
Building physics	Multi-zone airflow, heat and contaminant transport	Kirchhoff: Newton on zone pressure	`build_model`
Street air quality	Urban air quality, canyon exchange and routing	Closure: flows computed from the wind aloft	`build_model`, `StreetNetwork`
Sewers	Gravity sewer hydraulics, headspace air, sulfide	Continuity on a tree for the water; Kirchhoff solve for the headspace air	`build_model`
Water distribution	Pressurised mains, pumps, tanks, demand	Kirchhoff: Newton on hydraulic head	`build_model`
Flow allocation	Requested flows clipped to arc capacity and free storage at the receiving node	Clip and allocate	`AllocatedFlowLayer`
Electrical circuits	Lumped circuits: DC, transient and AC	Kirchhoff: Modified Nodal Analysis on node voltage	`build_model`, `Circuit`
Coupling	Two models meeting at a shared boundary	Two models exchanging values, iterated to a fixed point	`union`

Reading model files¶

A model can be built directly in Python or, where a reader exists, read from a file in an established exchange format. A model read from a file can be batched, differentiated and coupled exactly like one built by hand.

Format	Reader	What it describes	Produces a model for
CONTAM `.prj` / `.wth`	`read_prj`, `project_to_model`, `read_wth`	Multi-zone building airflow, contaminants and occupants; weather	Building physics
Modelica Buildings Library (JSON + CSV export)	`read_modelica`	Multi-zone airflow models built from MBL components	Building physics
SWMM `.inp`	`read_swmm_inp`	Gravity sewer and drainage networks	Sewers
EPANET `.inp`	`read_epanet_inp`	Pressurised water distribution	Water distribution
Modelica circuits (JSON + CSV export)	`read_modelica_circuit`	Lumped circuits from the Modelica Standard Library and Buildings Library	Electrical circuits
MATPOWER `.m`	`read_matpower`	Balanced power networks: buses, lines, transformers, loads, shunts, generators	Electrical power flow

See File formats for what each reader accepts and refuses.

Where to go next¶

Installation — pip, the optional extras, and what each one buys you.
Quick start — a working two-node model in fifteen lines, then a batched one.
Concepts — how the framework fits together: networks, constitutive laws, layers, solvers, differentiability.
Using noodl — the one way every model is set up, checked, run and read, whatever its physics.
Applications — the seven worked systems.
Catalogue — every type each application offers: what it does and how to call it.
API reference — generated from the docstrings.
Theory — the background: Tellegen's theorem, port-Hamiltonian systems, differentiable physics, and the literature each application builds on.

The name¶

noodl stands for Network-Oriented Open Differentiable Library; physics says what it is for. The package is installed as noodl-physics and imported as noodl. The mark is a single continuous pipe between two nodes — flow through a network, drawn in one stroke.

Credits and licence¶

The topology layer is built on PyTorch, and the physics is implemented as nodal state-space modules with storage at nodes, typed edges, and batching over instances.