How e2niee/pandapipes works
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: pipeflow_setup.py Setup · pandapipes_net.py Net model · pipeflow.py Pipeflow API · derivative_calculation.py Derivatives
Components 20
Core model
Network tables, component models, and creation helpers.
- Net model · Central network object stored as structured element and result tables.
src/pandapipes/pandapipes_net.py - Create API · Helpers for assembling networks and adding component tables.
src/pandapipes/create.py - Components · Concrete junction, pipe, pump, valve, source, sink, exchanger, storage, and control elements.
src/pandapipes/component_models - Abstracts · 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 · High-level entry point that prepares and runs a pipeflow simulation.
src/pandapipes/pipeflow.py - Setup · Prepares options, in-service state, and inputs for a solve run.
src/pandapipes/pf/pipeflow_setup.py - Matrix · Builds the system matrix and branch/node coupling for Newton-style solving.
src/pandapipes/pf/build_system_matrix.py - Derivatives · Computes derivatives and linearization terms for hydraulic and thermal relations.
src/pandapipes/pf/derivative_calculation.py - Internals · Handles internal variables and branch internals used during solving.
src/pandapipes/pf/internals_toolbox.py - Results · 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 · Tabulated thermophysical property subsystem for gases, liquids, and mixtures.
src/pandapipes/properties
Integration
Controllers, multinet coupling, import/export, and conversion boundaries.
- Control · Controllers that modify setpoints or component behavior across repeated solves.
src/pandapipes/control - Time series · Orchestrates repeated runs over profiles and stores time-dependent results.
src/pandapipes/timeseries - Multinet · Coordinates coupled simulations across multiple network domains.
src/pandapipes/multinet - I/O · Persistence and format conversion for network models.
src/pandapipes/io - STANET · 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 · Reusable pipe and pump templates for network creation.
src/pandapipes/std_types - Topology · Connectivity, graph creation, and path-search helpers for network structure queries.
src/pandapipes/topology - Plotting · Network drawing and pipeflow result visualization helpers.
src/pandapipes/plotting - Examples · Ready-made example and comparison networks stored as JSON assets.
src/pandapipes/networks
Connections 24
- 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.