# e2niee/pandapipes architecture

> Architecture diagram of the GitHub repository e2niee/pandapipes, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/e2niee/pandapipes
- Repository: https://github.com/e2niee/pandapipes

## Overview

1. **Repository purpose**
   - `pandapipes` is a Python library for hydraulic/thermal pipeflow simulation in gas, water, and heat networks.
   - It complements `pandapower` by modeling multi-energy grid elements such as pipes, pumps, valves, sources, sinks, heat exchangers, and controllers.

2. **Core domain model: network tables**
   - The central runtime object is a pandapipes network stored as structured tables, not as a custom graph class.
   - Network creation helpers live in `src/pandapipes/create.py`, `pandapipes_net.py`, and the component modules.
   - Each element type has its own component model that contributes input tables, result tables, and solver-relevant metadata.

3. **Component subsystem**
   - `src/pandapipes/component_models/` contains the element implementations: junctions, pipes, pumps, compressors, valves, sources, sinks, external grids, pressure/flow controls, heat exchangers, consumers, and storage.
   - Abstract base classes under `abstract_models/` define shared behavior for node elements, branch elements, branch elements with internals, and constant-flow or circulation-pump behavior.
   - This is the layer that maps engineering objects into the solver’s node/branch representation.

4. **Pipeflow solver boundary**
   - The numerical solver is isolated in `src/pandapipes/pf/`.
   - Key responsibilities here are building the system matrix, calculating derivatives, handling internal variables, extracting results, and preparing each pipeflow run.
   - `src/pandapipes/pipeflow.py` is the high-level entry point that orchestrates solver setup and execution.

5. **Runtime data flow for a simulation**
   - A typical flow is: create a network → add component tables/standard types → configure fluid and options → run pipeflow → populate result tables.
   - The solver consumes branch/node tables plus fluid/property data and writes back results such as pressure, mass flow, velocity, Reynolds number, and temperature-related outputs.
   - Result-oriented files under `src/pandapipes/test/data/` and the component-specific CSVs in `doc/source/components/*` reflect these table contracts.

6. **Fluid and material property subsystem**
   - `src/pandapipes/properties/` stores tabulated physical properties for fluids such as water, air, methane, hydrogen, and biomethane variants.
   - `properties.py`/`properties_toolbox.py` provide access to density, viscosity, compressibility, heat capacity, molar mass, and heating values.
   - This subsystem is a hard dependency for gas and thermal calculations and is separate from network topology and solver mechanics.

7. **Standard types and reusable parameter libraries**
   - `src/pandapipes/std_types/` and the CSV library under `std_types/library/` provide reusable pipe and pump types.
   - Standard types act as parameter templates for component creation and are part of the user-facing data model.
   - Documentation in `doc/source/standard_types/` suggests this is a stable abstraction boundary for model setup.

8. **Topology and graph utilities**
   - `src/pandapipes/topology/` contains graph creation and graph-search helpers.
   - These utilities support connectivity analysis, path searches, and network structure queries, but are separate from the numerical solver.
   - They are used for tasks like identifying active parts of the network and supporting higher-level algorithms.

9. **Controllers and time series**
   - `src/pandapipes/control/` and `src/pandapipes/timeseries/` add dynamic execution over multiple time steps.
   - Controllers adjust setpoints or component behavior during repeated pipeflow runs.
   - The time-series layer is an orchestration boundary: it repeatedly applies profiles, runs the solver, and stores time-dependent results.

10. **Multi-energy network coupling**
   - `src/pandapipes/multinet/` handles coupled simulations with multiple network domains.
   - It introduces multinet objects, multinet controllers, and a time-series runner for coordinated execution across subsystems.
   - This is the main integration boundary between pandapipes and other network models, including pandapower-style coupling patterns.

11. **Import/export and external format conversion**
   - `src/pandapipes/io/` handles saving/loading and format conversion.
   - `src/pandapipes/converter/stanet/` converts STANET networks into pandapipes structures, including preprocessing and valve/pipe transformations.
   - This layer is the main ingress/egress path for external engineering data.

12. **Predefined networks and reference models**
   - `src/pandapipes/networks/` and its JSON files contain ready-made example networks and test networks for gas, water, and heat cases.
   - These assets serve as fixtures for documentation, regression tests, and comparisons against reference tools such as OpenModelica and STANET.
   - They are not runtime logic, but they define canonical model shapes used throughout the repository.

13. **Plotting and result visualization**
   - `src/pandapipes/plotting/` provides graph/layout helpers and simple plotting of networks and pipeflow results.
   - The plotting layer depends on network structure and result tables, not on the solver internals.
   - It is a consumer of solved data, useful for inspection and documentation rather than computation.

14. **Quality, verification, and documentation support**
   - `src/pandapipes/test/` contains extensive tests covering API, solver internals, converter behavior, multinet behavior, plotting, properties, topology, and external comparisons.
   - `doc/` and `tutorials/` show that the repository is organized as a library with strong documentation and reproducible examples, not as an application service.
   - GitHub workflows in `.github/workflows/` indicate automated tests and release packaging as part of the delivery pipeline.

Main entry points: [`src/pandapipes/pf/pipeflow_setup.py`](https://github.com/e2niee/pandapipes/blob/develop/src/pandapipes/pf/pipeflow_setup.py) (Setup), [`src/pandapipes/pandapipes_net.py`](https://github.com/e2niee/pandapipes/blob/develop/src/pandapipes/pandapipes_net.py) (Net model), [`src/pandapipes/pipeflow.py`](https://github.com/e2niee/pandapipes/blob/develop/src/pandapipes/pipeflow.py) (Pipeflow API), [`src/pandapipes/pf/derivative_calculation.py`](https://github.com/e2niee/pandapipes/blob/develop/src/pandapipes/pf/derivative_calculation.py) (Derivatives)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core model"]
  node_pandapipes_net[("Net model<br/>network tables<br/>[pandapipes_net.py]")]
  node_create_api["Create API<br/>network setup<br/>[create.py]"]
  node_components["Components<br/>element models"]
  node_abstract_models["Abstracts<br/>component base"]
end

subgraph group_solver["Pipeflow"]
  node_pipeflow_entry["Pipeflow API<br/>orchestration<br/>[pipeflow.py]"]
  node_setup["Setup<br/>solver prep<br/>[pipeflow_setup.py]"]
  node_matrix["Matrix<br/>system assembly"]
  node_derivatives["Derivatives<br/>solver math"]
  node_internals["Internals<br/>state helpers"]
  node_results["Results<br/>result extraction"]
end

subgraph group_physics["Physics"]
  node_properties["Fluids<br/>fluid properties"]
end

subgraph group_integration["Integration"]
  node_control["Control"]
  node_timeseries["Time series<br/>multi-step runner"]
  node_multinet["Multinet<br/>coupling layer"]
  node_io["I/O<br/>save load"]
  node_stanet_converter["STANET<br/>external converter"]
end

subgraph group_support["Support"]
  node_std_types["Std types<br/>parameter library"]
  node_topology["Topology<br/>graph utilities"]
  node_plotting["Plotting<br/>visualization"]
  node_networks["Examples<br/>reference networks"]
end

node_create_api -->|"builds"| node_pandapipes_net
node_components -->|"populate"| node_pandapipes_net
node_abstract_models -->|"base for"| node_components
node_components -->|"feeds"| node_setup
node_pipeflow_entry -->|"orchestrates"| node_setup
node_setup -->|"prepares"| node_matrix
node_setup -->|"prepares"| node_derivatives
node_matrix -->|"uses"| node_derivatives
node_derivatives -->|"updates"| node_internals
node_matrix -->|"solves into"| node_results
node_internals -->|"extracts"| node_results
node_properties -->|"supplies"| node_setup
node_properties -->|"informs"| node_derivatives
node_std_types -->|"templates"| node_create_api
node_topology -->|"analyzes"| node_pandapipes_net
node_plotting -->|"visualizes"| node_pandapipes_net
node_control -->|"drives"| node_pipeflow_entry
node_timeseries -->|"applies"| node_control
node_timeseries -->|"repeats"| node_pipeflow_entry
node_multinet -->|"extends"| node_timeseries
node_io -->|"persists"| node_pandapipes_net
node_stanet_converter -->|"ingests"| node_io
node_networks -->|"examples for"| node_create_api
node_networks -->|"benchmarks"| node_pipeflow_entry

click node_pandapipes_net "https://github.com/e2niee/pandapipes/blob/develop/src/pandapipes/pandapipes_net.py"
click node_create_api "https://github.com/e2niee/pandapipes/blob/develop/src/pandapipes/create.py"
click node_components "https://github.com/e2niee/pandapipes/tree/develop/src/pandapipes/component_models"
click node_abstract_models "https://github.com/e2niee/pandapipes/tree/develop/src/pandapipes/component_models/abstract_models"
click node_pipeflow_entry "https://github.com/e2niee/pandapipes/blob/develop/src/pandapipes/pipeflow.py"
click node_setup "https://github.com/e2niee/pandapipes/blob/develop/src/pandapipes/pf/pipeflow_setup.py"
click node_matrix "https://github.com/e2niee/pandapipes/blob/develop/src/pandapipes/pf/build_system_matrix.py"
click node_derivatives "https://github.com/e2niee/pandapipes/blob/develop/src/pandapipes/pf/derivative_calculation.py"
click node_internals "https://github.com/e2niee/pandapipes/blob/develop/src/pandapipes/pf/internals_toolbox.py"
click node_results "https://github.com/e2niee/pandapipes/blob/develop/src/pandapipes/pf/result_extraction.py"
click node_properties "https://github.com/e2niee/pandapipes/tree/develop/src/pandapipes/properties"
click node_std_types "https://github.com/e2niee/pandapipes/tree/develop/src/pandapipes/std_types"
click node_topology "https://github.com/e2niee/pandapipes/tree/develop/src/pandapipes/topology"
click node_plotting "https://github.com/e2niee/pandapipes/tree/develop/src/pandapipes/plotting"
click node_control "https://github.com/e2niee/pandapipes/tree/develop/src/pandapipes/control"
click node_timeseries "https://github.com/e2niee/pandapipes/tree/develop/src/pandapipes/timeseries"
click node_multinet "https://github.com/e2niee/pandapipes/tree/develop/src/pandapipes/multinet"
click node_io "https://github.com/e2niee/pandapipes/tree/develop/src/pandapipes/io"
click node_stanet_converter "https://github.com/e2niee/pandapipes/tree/develop/src/pandapipes/converter/stanet"
click node_networks "https://github.com/e2niee/pandapipes/tree/develop/src/pandapipes/networks"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_pandapipes_net,node_create_api,node_components,node_abstract_models toneBlue
class node_pipeflow_entry,node_setup,node_matrix,node_derivatives,node_internals,node_results toneAmber
class node_properties toneMint
class node_control,node_timeseries,node_multinet,node_io,node_stanet_converter toneRose
class node_std_types,node_topology,node_plotting,node_networks toneIndigo
```

## Components

### Core model

Network tables, component models, and creation helpers.

- [Net model](https://github.com/e2niee/pandapipes/blob/develop/src/pandapipes/pandapipes_net.py): network tables · Central network object stored as structured element and result tables. · `src/pandapipes/pandapipes_net.py`
- [Create API](https://github.com/e2niee/pandapipes/blob/develop/src/pandapipes/create.py): network setup · Helpers for assembling networks and adding component tables. · `src/pandapipes/create.py`
- [Components](https://github.com/e2niee/pandapipes/tree/develop/src/pandapipes/component_models): element models · Concrete junction, pipe, pump, valve, source, sink, exchanger, storage, and control elements. · `src/pandapipes/component_models`
- [Abstracts](https://github.com/e2niee/pandapipes/tree/develop/src/pandapipes/component_models/abstract_models): component base · Shared node, branch, internal-branch, constant-flow, and circulation-pump behavior. · `src/pandapipes/component_models/abstract_models`

### Pipeflow

Numerical setup, matrix assembly, derivatives, and result extraction.

- [Pipeflow API](https://github.com/e2niee/pandapipes/blob/develop/src/pandapipes/pipeflow.py): orchestration · High-level entry point that prepares and runs a pipeflow simulation. · `src/pandapipes/pipeflow.py`
- [Setup](https://github.com/e2niee/pandapipes/blob/develop/src/pandapipes/pf/pipeflow_setup.py): solver prep · Prepares options, in-service state, and inputs for a solve run. · `src/pandapipes/pf/pipeflow_setup.py`
- [Matrix](https://github.com/e2niee/pandapipes/blob/develop/src/pandapipes/pf/build_system_matrix.py): system assembly · Builds the system matrix and branch/node coupling for Newton-style solving. · `src/pandapipes/pf/build_system_matrix.py`
- [Derivatives](https://github.com/e2niee/pandapipes/blob/develop/src/pandapipes/pf/derivative_calculation.py): solver math · Computes derivatives and linearization terms for hydraulic and thermal relations. · `src/pandapipes/pf/derivative_calculation.py`
- [Internals](https://github.com/e2niee/pandapipes/blob/develop/src/pandapipes/pf/internals_toolbox.py): state helpers · Handles internal variables and branch internals used during solving. · `src/pandapipes/pf/internals_toolbox.py`
- [Results](https://github.com/e2niee/pandapipes/blob/develop/src/pandapipes/pf/result_extraction.py): result extraction · Collects solved pressures, flows, velocities, Reynolds numbers, and temperatures into result tables. · `src/pandapipes/pf/result_extraction.py`

### Physics

Fluid and material property data used by hydraulic and thermal calculations.

- [Fluids](https://github.com/e2niee/pandapipes/tree/develop/src/pandapipes/properties): fluid properties · Tabulated thermophysical property subsystem for gases, liquids, and mixtures. · `src/pandapipes/properties`

### Integration

Controllers, multinet coupling, import/export, and conversion boundaries.

- [Control](https://github.com/e2niee/pandapipes/tree/develop/src/pandapipes/control): single-run control · Controllers that modify setpoints or component behavior across repeated solves. · `src/pandapipes/control`
- [Time series](https://github.com/e2niee/pandapipes/tree/develop/src/pandapipes/timeseries): multi-step runner · Orchestrates repeated runs over profiles and stores time-dependent results. · `src/pandapipes/timeseries`
- [Multinet](https://github.com/e2niee/pandapipes/tree/develop/src/pandapipes/multinet): coupling layer · Coordinates coupled simulations across multiple network domains. · `src/pandapipes/multinet`
- [I/O](https://github.com/e2niee/pandapipes/tree/develop/src/pandapipes/io): save load · Persistence and format conversion for network models. · `src/pandapipes/io`
- [STANET](https://github.com/e2niee/pandapipes/tree/develop/src/pandapipes/converter/stanet): external converter · Imports and preprocesses STANET networks into pandapipes structures. · `src/pandapipes/converter/stanet`

### Support

Topology, plotting, reusable standard types, example networks, and documentation assets.

- [Std types](https://github.com/e2niee/pandapipes/tree/develop/src/pandapipes/std_types): parameter library · Reusable pipe and pump templates for network creation. · `src/pandapipes/std_types`
- [Topology](https://github.com/e2niee/pandapipes/tree/develop/src/pandapipes/topology): graph utilities · Connectivity, graph creation, and path-search helpers for network structure queries. · `src/pandapipes/topology`
- [Plotting](https://github.com/e2niee/pandapipes/tree/develop/src/pandapipes/plotting): visualization · Network drawing and pipeflow result visualization helpers. · `src/pandapipes/plotting`
- [Examples](https://github.com/e2niee/pandapipes/tree/develop/src/pandapipes/networks): reference networks · Ready-made example and comparison networks stored as JSON assets. · `src/pandapipes/networks`

## Connections

- Create API → Net model: builds · Creates and initializes network table structures.
- Components → Net model: populate · Add element-specific input and result tables to the network.
- Abstracts → Components: base for · Shared behavior is specialized by concrete component models.
- Components → Setup: feeds · Component tables and metadata are consumed during solver preparation.
- Pipeflow API → Setup: orchestrates · Coordinates solve preparation.
- Setup → Matrix: prepares · Produces data needed for system assembly.
- Setup → Derivatives: prepares · Provides state and options for derivative evaluation.
- Matrix → Derivatives: uses · Assembly depends on calculated relations and sensitivities.
- Derivatives → Internals: updates · Internal variables are maintained during linearization and iteration.
- Matrix → Results: solves into · Solved state is mapped back to result tables.
- Internals → Results: extracts · Internal variables contribute to output quantities.
- Fluids → Setup: supplies · Fluid properties are required for hydraulic and thermal setup.
- Fluids → Derivatives: informs · Property tables affect derivative calculations.
- Std types → Create API: templates · Reusable parameter sets are used when creating components.
- Topology → Net model: analyzes · Derives connectivity and active subnetwork structure from the network tables.
- Plotting → Net model: visualizes · Consumes network structure and solved results.
- Control → Pipeflow API: drives · Adjusts setpoints and component behavior between solve calls.
- Time series → Control: applies · Runs controllers across successive time steps.
- Time series → Pipeflow API: repeats · Executes the solver for each profile step.
- Multinet → Time series: extends · Adds coordinated time-series execution across coupled networks.
- I/O → Net model: persists · Saves and loads the network table model.
- STANET → I/O: ingests · External STANET data is converted into pandapipes-compatible structures.
- Examples → Create API: examples for · Reference networks illustrate and validate model creation.
- Examples → Pipeflow API: benchmarks · Example cases are used to exercise the solver.