Justinaquino: "Add Pandapower and ONLYOFFICE Nextcloud analysis pages"

2026-03-09T16:22:25Z

"Add Pandapower and ONLYOFFICE Nextcloud analysis pages"

New page

= Pandapower Architecture & Codebase Guide =

{{Quote|A newcomer's guide to understanding how pandapower is organized and how to build a web-based GUI on top of it.}}

----

== 1. What Is Pandapower? ==

Pandapower is a Python library for '''power system modeling and analysis'''. It lets you:

* Build electrical network models (buses, lines, transformers, generators, loads, etc.)
* Run simulations (power flow, optimal power flow, short-circuit, state estimation, time series)
* Visualize results (static plots, interactive Plotly maps)
* Import/export networks (JSON, Excel, SQL, MATPOWER, CIM, PowerFactory)

Everything is built on '''pandas DataFrames''' — each network element type is a table, indexed by element ID. This makes it straightforward to serialize to/from JSON for a web API.

----

== 2. Project Root Layout ==

<syntaxhighlight lang="text">
pandapower/
├── pandapower/ # Main Python package (the library itself)
├── tutorials/ # 60 Jupyter notebooks — examples & learning material
├── doc/ # Sphinx RST documentation
├── .github/ # CI/CD workflows
├── pyproject.toml # Dependencies, build config, Python 3.10–3.14
├── setup.py # Minimal setuptools entry
├── README.rst
├── CHANGELOG.rst
├── AUTHORS
├── CITATION.bib
├── architecture.md # ← This file
└── GUI_PRD.md # Functional requirements for the web GUI
</syntaxhighlight>

----

== 3. Core Package Structure (<code>pandapower/pandapower/</code>) ==

=== 3.1 Network Creation & Data Model ===

{| class="wikitable"
! Path !! Purpose
|-
| <code>create/</code> || Element creation functions — one file per element type
|-
| <code>create/__init__.py</code> || Re-exports all <code>create_*()</code> functions
|-
| <code>create/bus_create.py</code> || <code>create_bus()</code>, <code>create_buses()</code>
|-
| <code>create/line_create.py</code> || <code>create_line()</code>, <code>create_line_from_parameters()</code>
|-
| <code>create/gen_create.py</code> || <code>create_gen()</code>, <code>create_gens()</code>
|-
| <code>create/load_create.py</code> || <code>create_load()</code>, <code>create_loads()</code>
|-
| <code>create/sgen_create.py</code> || <code>create_sgen()</code> — static generators (solar/wind)
|-
| <code>create/ext_grid_create.py</code> || <code>create_ext_grid()</code> — slack/reference bus
|-
| <code>create/impedance_create.py</code> || <code>create_impedance()</code> — series impedance
|-
| <code>create/shunt_create.py</code> || <code>create_shunt()</code> — capacitor banks
|-
| <code>create/switch_create.py</code> || <code>create_switch()</code> — breakers/isolators
|-
| <code>create/storage_create.py</code> || <code>create_storage()</code> — batteries
|-
| <code>create/motor_create.py</code> || <code>create_motor()</code> — async motors
|-
| <code>create/cost_create.py</code> || <code>create_poly_cost()</code>, <code>create_pwl_cost()</code> — OPF costs
|-
| <code>create/measurement_create.py</code> || <code>create_measurement()</code> — for state estimation
|-
| <code>create/network_create.py</code> || <code>create_empty_network()</code> — the starting point
|-
| <code>create/group_create.py</code> || <code>create_group()</code> — element grouping
|-
| <code>create/source_create.py</code> || DC elements, FACTS (SVC, TCSC, SSC, VSC)
|}

'''Key concept:''' A <code>pandapowerNet</code> is a dict-like object where each key (e.g., <code>net.bus</code>, <code>net.line</code>, <code>net.load</code>) is a pandas DataFrame. Results go into <code>net.res_bus</code>, <code>net.res_line</code>, etc.

=== 3.2 Analysis Engines ===

{| class="wikitable"
! Path !! Function !! What It Does
|-
| <code>run.py</code> || <code>runpp()</code> || '''AC Power Flow''' — the most-used function
|-
| <code>run.py</code> || <code>rundcpp()</code> || DC Power Flow (linearized approximation)
|-
| <code>run.py</code> || <code>runopp()</code> || AC Optimal Power Flow
|-
| <code>run.py</code> || <code>rundcopp()</code> || DC Optimal Power Flow
|-
| <code>run.py</code> || <code>runpp_3ph()</code> || Three-phase unbalanced power flow
|-
| <code>run.py</code> || <code>runpp_pgm()</code> || Power flow via C++ PowerGridModel backend
|-
| <code>powerflow.py</code> || Internal || Power flow orchestration
|-
| <code>optimal_powerflow.py</code> || Internal || OPF orchestration
|-
| <code>pf/</code> || Internal || Newton-Raphson, backward-forward sweep, Gauss-Seidel, fast-decoupled solvers
|-
| <code>shortcircuit/</code> || <code>calc_sc()</code> || Short-circuit analysis (IEC 60909)
|-
| <code>estimation/</code> || <code>estimate()</code> || State estimation (WLS, IRWLS, LP)
|-
| <code>timeseries/</code> || <code>run_time_series()</code> || Multi-timestep simulation
|-
| <code>contingency/</code> || <code>run_contingency()</code> || N-1 contingency analysis
|-
| <code>opf/</code> || Internal || OPF via PYPOWER / PowerModels.jl
|}

=== 3.3 Results ===

{| class="wikitable"
! Path !! Purpose
|-
| <code>results.py</code> || Main result extraction orchestrator
|-
| <code>results_bus.py</code> || Bus results: voltage magnitude/angle, P/Q injection
|-
| <code>results_branch.py</code> || Line & trafo results: loading%, current, losses
|-
| <code>results_gen.py</code> || Generator results: P/Q output
|}

'''Result tables populated after analysis:'''

{| class="wikitable"
! Table !! Key Columns
|-
| <code>net.res_bus</code> || <code>vm_pu</code>, <code>va_degree</code>, <code>p_mw</code>, <code>q_mvar</code>
|-
| <code>net.res_line</code> || <code>loading_percent</code>, <code>i_from_ka</code>, <code>i_to_ka</code>, <code>pl_mw</code>, <code>ql_mvar</code>
|-
| <code>net.res_trafo</code> || <code>loading_percent</code>, <code>pl_mw</code>, <code>ql_mvar</code>
|-
| <code>net.res_load</code> || <code>p_mw</code>, <code>q_mvar</code>
|-
| <code>net.res_gen</code> || <code>p_mw</code>, <code>q_mvar</code>, <code>vm_pu</code>
|-
| <code>net.res_sgen</code> || <code>p_mw</code>, <code>q_mvar</code>
|-
| <code>net.res_bus_sc</code> || <code>ikss_ka</code>, <code>ip_ka</code>, <code>ith_ka</code> (short-circuit)
|-
| <code>net.res_bus_est</code> || <code>vm_pu</code>, <code>va_degree</code> (state estimation)
|}

=== 3.4 I/O & Converters ===

{| class="wikitable"
! Path !! Purpose
|-
| <code>file_io.py</code> || <code>to_json()</code>, <code>from_json()</code>, <code>to_excel()</code>, <code>from_excel()</code>
|-
| <code>sql_io.py</code> || <code>to_sql()</code>, <code>from_sql()</code> — PostgreSQL, SQLite
|-
| <code>io_utils.py</code> || Serialization helpers
|-
| <code>converter/matpower/</code> || MATPOWER format import/export
|-
| <code>converter/pypower/</code> || PYPOWER format
|-
| <code>converter/cim/</code> || IEC Common Information Model
|-
| <code>converter/powerfactory/</code> || DIgSILENT PowerFactory
|-
| <code>converter/ucte/</code> || UCTE exchange format
|-
| <code>converter/jao/</code> || JAO format
|-
| <code>converter/pandamodels/</code> || Julia PowerModels.jl bridge
|}

=== 3.5 Visualization & Plotting ===

{| class="wikitable"
! Path !! Purpose
|-
| <code>plotting/simple_plot.py</code> || <code>simple_plot()</code> — Matplotlib static plots
|-
| <code>plotting/collections.py</code> || Styled element collections (buses, lines, trafos)
|-
| <code>plotting/powerflow_results.py</code> || Color-coded result overlays
|-
| <code>plotting/geo.py</code> || Geographic coordinate handling
|-
| <code>plotting/to_html.py</code> || Export to standalone HTML
|-
| <code>plotting/plotly/</code> || '''Interactive Plotly plots''' (most relevant for web GUI)
|-
| <code>plotting/plotly/simple_plotly.py</code> || <code>simple_plotly()</code> — interactive network diagram
|-
| <code>plotting/plotly/mapbox_plot.py</code> || <code>mapbox_plot()</code> — geographic map overlay
|-
| <code>plotting/plotly/pf_res_plotly.py</code> || <code>pf_res_plotly()</code> — interactive results
|}

=== 3.6 Topology & Diagnostics ===

{| class="wikitable"
! Path !! Purpose
|-
| <code>topology/create_graph.py</code> || Convert network to NetworkX graph
|-
| <code>topology/graph_searches.py</code> || Connected components, shortest paths, unsupplied buses
|-
| <code>diagnostic/</code> || Network validation: isolated buses, duplicate lines, impossible configs
|}

=== 3.7 Advanced Features ===

{| class="wikitable"
! Path !! Purpose
|-
| <code>control/</code> || Controller framework — tap changers, DER, shunt, PQ control
|-
| <code>protection/</code> || Protection device modeling — fuses, relays
|-
| <code>grid_equivalents/</code> || Network reduction (REI, Ward equivalents)
|-
| <code>groups.py</code> || Batch operations on element groups
|-
| <code>std_types.py</code> || Standard component library (line types, trafo types)
|-
| <code>toolbox/</code> || Grid modification, element selection, data manipulation
|}

=== 3.8 Internal Infrastructure ===

{| class="wikitable"
! Path !! Purpose
|-
| <code>__init__.py</code> || Public API — imports everything users need
|-
| <code>auxiliary.py</code> || Helpers, ADict class, logging
|-
| <code>build_bus.py</code> || Internal bus matrix construction
|-
| <code>build_branch.py</code> || Internal branch matrix construction
|-
| <code>build_gen.py</code> || Internal generator matrix construction
|-
| <code>pd2ppc.py</code> || Convert pandapower → PYPOWER internal format
|-
| <code>convert_format.py</code> || Version migration between pandapower versions
|-
| <code>network_schema/</code> || Pandera DataFrame validation schemas
|-
| <code>pypower/</code> || Embedded PYPOWER solver algorithms
|}

----

== 4. Built-In Test Networks (<code>pandapower/networks/</code>) ==

These are ready-made networks useful for testing the GUI:

{| class="wikitable"
! Function !! Description !! Size
|-
| <code>simple_four_bus_system()</code> || Tiny test network || 4 buses
|-
| <code>panda_four_load_branch()</code> || Small LV feeder || ~10 buses
|-
| <code>case_ieee30()</code> || IEEE 30-bus test case || 30 buses
|-
| <code>case118()</code> || IEEE 118-bus test case || 118 buses
|-
| <code>case300()</code> || IEEE 300-bus test case || 300 buses
|-
| <code>mv_oberrhein()</code> || Real German MV grid || ~300 buses
|-
| <code>create_cigre_network_mv()</code> || CIGRE MV benchmark || ~15 buses
|-
| <code>create_kerber_*()</code> || Synthetic LV grids || Various
|}

----

== 5. Tutorials (<code>tutorials/</code>) ==

60 Jupyter notebooks organized by topic:

{| class="wikitable"
! Category !! Key Notebooks
|-
| '''Getting Started''' || <code>minimal_example.ipynb</code>, <code>create_simple.ipynb</code>, <code>create_advanced.ipynb</code>
|-
| '''Power Flow''' || <code>powerflow.ipynb</code>, <code>convergence_powerflow.ipynb</code>, <code>three_phase_loadflow_tutorial_simple.ipynb</code>
|-
| '''OPF''' || <code>opf_basic.ipynb</code>, <code>opf_curtail.ipynb</code>, <code>opf_dcline.ipynb</code>
|-
| '''Short Circuit''' || <code>shortcircuit.ipynb</code>
|-
| '''State Estimation''' || <code>state_estimation.ipynb</code>
|-
| '''Time Series''' || <code>time_series.ipynb</code>, <code>time_series_advanced_output.ipynb</code>
|-
| '''Contingency''' || <code>contingency_analysis.ipynb</code>
|-
| '''Visualization''' || <code>plotting_basic.ipynb</code>, <code>plotly_built-in.ipynb</code>, <code>plotly_maps.ipynb</code>
|-
| '''Controls''' || <code>control_loop.ipynb</code>, <code>building_a_controller.ipynb</code>, <code>DER_control_tutorial.ipynb</code>
|-
| '''Protection''' || <code>protection/fuse.ipynb</code>, <code>protection/oc_relay.ipynb</code>
|-
| '''Converters''' || <code>cim2pp.ipynb</code>, <code>converter_powerfactory.ipynb</code>
|}

----

== 6. Dependencies ==

'''Core (always required):'''
* <code>pandas ~= 2.3</code> — DataFrames (the foundation)
* <code>numpy >= 1.26</code> — Numerical arrays
* <code>scipy < 1.17</code> — Sparse matrices, solvers
* <code>networkx ~= 3.4</code> — Graph/topology algorithms
* <code>tqdm ~= 4.67</code> — Progress bars
* <code>geojson ~= 3.2</code> — GeoJSON support
* <code>pandera ~= 0.26</code> — DataFrame validation

'''Visualization (relevant for GUI):'''
* <code>plotly ~= 6.3</code> — Interactive web-based plots
* <code>matplotlib ~= 3.10</code> — Static plots
* <code>geopandas ~= 1.1</code> — Geographic data

'''Performance:'''
* <code>numba ~= 0.61</code> — JIT-compiled solvers
* <code>lightsim2grid ~= 0.12</code> — C++ power flow backend

'''I/O:'''
* <code>xlsxwriter</code>, <code>openpyxl</code> — Excel
* <code>psycopg ~= 3.2</code> — PostgreSQL
* <code>lxml ~= 6.0</code> — XML parsing

----

== 7. How Pandapower Works (The Computation Flow) ==

<syntaxhighlight lang="text">
┌─────────────────────────────────────────────────────┐
│ 1. CREATE NETWORK │
│ net = pp.create_empty_network() │
│ pp.create_bus(net, vn_kv=110) │
│ pp.create_line(net, from_bus=0, to_bus=1, ...) │
│ pp.create_load(net, bus=1, p_mw=10) │
│ ... │
│ → net.bus, net.line, net.load are DataFrames │
└───────────────────────┬─────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 2. RUN ANALYSIS │
│ pp.runpp(net) # Power flow │
│ pp.runopp(net) # Optimal power flow │
│ pp.shortcircuit.calc_sc(net) # Short circuit │
│ pp.estimation.estimate(net) # State est. │
│ │
│ → Internally: DataFrames → sparse matrices → │
│ solver → results back to DataFrames │
└───────────────────────┬─────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 3. READ RESULTS │
│ net.res_bus → voltage, power at each bus │
│ net.res_line → loading, current, losses │
│ net.res_trafo → loading, losses │
│ net.converged → True/False │
│ │
│ → All results are pandas DataFrames │
└───────────────────────┬─────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 4. VISUALIZE / EXPORT │
│ pp.plotting.simple_plotly(net) # Web plot │
│ pp.to_json(net) # Serialize │
│ pp.to_excel(net, "network.xlsx") # Export │
└─────────────────────────────────────────────────────┘
</syntaxhighlight>

----

== 8. Key Architecture Facts for GUI Developers ==

=== 8.1 Everything Is a DataFrame ===
* Input data: <code>net.bus</code>, <code>net.line</code>, <code>net.trafo</code>, <code>net.load</code>, <code>net.gen</code>, <code>net.sgen</code>, <code>net.ext_grid</code>, <code>net.switch</code>, <code>net.shunt</code>, <code>net.storage</code>, etc.
* Result data: <code>net.res_bus</code>, <code>net.res_line</code>, <code>net.res_trafo</code>, etc.
* Both are pandas DataFrames — trivially convertible to JSON via <code>.to_dict(orient="records")</code> or <code>.to_json()</code>.

=== 8.2 JSON Serialization Is Built In ===
<syntaxhighlight lang="python">
json_str = pp.to_json(net) # Network → JSON string
net = pp.from_json(json_str) # JSON string → Network
</syntaxhighlight>
This is the natural transport format for a REST API.

=== 8.3 Analysis Is Stateless (Almost) ===
* Call <code>runpp(net)</code> → results appear in <code>net.res_*</code> tables
* Call it again → previous results are overwritten
* The <code>net</code> object carries all state — pass it around as the single source of truth

=== 8.4 Plotly Is Already Web-Ready ===
* <code>pandapower.plotting.plotly</code> generates Plotly figures
* Plotly figures serialize to JSON natively
* They can be rendered directly in a browser via <code>plotly.js</code>

=== 8.5 Standard Types Are a Built-In Library ===
* <code>net.std_types["line"]</code> — DataFrame of line types with impedance/capacity data
* <code>net.std_types["trafo"]</code> — DataFrame of transformer types
* When creating elements, pass <code>std_type="NAYY 4x50 SE"</code> to auto-populate parameters
* GUI should present these as dropdowns

=== 8.6 Controllers Run Inside Power Flow ===
* <code>runpp(net, run_control=True)</code> activates the controller loop
* Controllers (tap changers, DER control) iterate until convergence
* For the GUI: expose controller configuration as a settings panel

----

== 9. Recommended Web GUI Tech Stack ==

For a Python-backend web GUI wrapping pandapower:

<syntaxhighlight lang="text">
┌──────────────────────────────────────┐
│ Frontend (Browser) │
│ - React / Vue / Svelte │
│ - Plotly.js for network diagrams │
│ - AG Grid or similar for tables │
│ - PDF generation (jsPDF / pdfmake) │
└──────────────┬───────────────────────┘
│ REST / WebSocket
▼
┌──────────────────────────────────────┐
│ Backend (Python) │
│ - FastAPI or Flask │
│ - pandapower as the engine │
│ - Endpoints for CRUD + analysis │
│ - Session/project management │
└──────────────────────────────────────┘
</syntaxhighlight>

'''API Design Sketch:'''

{| class="wikitable"
! Endpoint !! Method !! Purpose
|-
| <code>/api/network</code> || POST || Create new empty network
|-
| <code>/api/network</code> || GET || Get current network as JSON
|-
| <code>/api/network/import</code> || POST || Import from JSON/Excel/MATPOWER
|-
| <code>/api/network/export</code> || GET || Export to JSON/Excel
|-
| <code>/api/element/{type}</code> || POST || Create element (bus, line, load...)
|-
| <code>/api/element/{type}/{id}</code> || PUT || Update element parameters
|-
| <code>/api/element/{type}/{id}</code> || DELETE || Remove element
|-
| <code>/api/analysis/powerflow</code> || POST || Run power flow
|-
| <code>/api/analysis/opf</code> || POST || Run optimal power flow
|-
| <code>/api/analysis/shortcircuit</code> || POST || Run short-circuit analysis
|-
| <code>/api/analysis/estimation</code> || POST || Run state estimation
|-
| <code>/api/analysis/timeseries</code> || POST || Run time series
|-
| <code>/api/analysis/contingency</code> || POST || Run contingency analysis
|-
| <code>/api/results/{type}</code> || GET || Get result tables
|-
| <code>/api/plot/network</code> || GET || Get Plotly figure JSON
|-
| <code>/api/report/{type}</code> || GET || Generate PDF report
|-
| <code>/api/stdtypes/{element}</code> || GET || List standard types
|-
| <code>/api/diagnostic</code> || POST || Run network diagnostics
|-
| <code>/api/topology</code> || GET || Get topology info
|}

----

== 10. Quick Reference: Most Important Files ==

If you're building a GUI and need to understand pandapower, read these files in order:

# '''<code>pandapower/__init__.py</code>''' — See every public function
# '''<code>pandapower/run.py</code>''' — Power flow & OPF entry points
# '''<code>pandapower/create/__init__.py</code>''' — All element creation functions
# '''<code>pandapower/file_io.py</code>''' — JSON/Excel serialization
# '''<code>pandapower/results.py</code>''' — How results are extracted
# '''<code>pandapower/plotting/plotly/simple_plotly.py</code>''' — Interactive visualization
# '''<code>pandapower/shortcircuit/calc_sc.py</code>''' — Short-circuit entry point
# '''<code>pandapower/estimation/state_estimation.py</code>''' — State estimation entry point
# '''<code>pandapower/timeseries/run_time_series.py</code>''' — Time series entry point
# '''<code>pandapower/networks/power_system_test_cases.py</code>''' — Built-in test networks

[[Category:Open Source]]
[[Category:Software Analysis]]
[[Category:Pandapower]]

Pandapower Architecture - Revision history

Justinaquino: "Add Pandapower and ONLYOFFICE Nextcloud analysis pages"