Justinaquino: "Add Pandapower and ONLYOFFICE Nextcloud analysis pages"

2026-03-09T16:22:27Z

"Add Pandapower and ONLYOFFICE Nextcloud analysis pages"

New page

= Pandapower Web GUI — Product Requirements Document =

{{Quote|Incremental functional requirements for building a web-based GUI for pandapower.
Milestones are ordered from most commonly used features to specialized ones.
Each milestone is self-contained and delivers user value.}}

----

== Guiding Principles ==

# '''Incremental delivery''' — each milestone ships a usable feature
# '''Most-used first''' — power flow before OPF, OPF before short-circuit
# '''PDF reports at every stage''' — each analysis milestone includes report generation
# '''pandapower as engine''' — the GUI is a thin wrapper; all computation stays in pandapower
# '''JSON as transport''' — <code>pp.to_json()</code> / <code>pp.from_json()</code> for all network data
# '''Plotly for visualization''' — leverage pandapower's built-in Plotly integration

----

== Milestone 0: Project Foundation ==

=== M0.1 — Backend Skeleton ===
* ☐ FastAPI (or Flask) project with CORS, health endpoint
* ☐ pandapower installed as dependency
* ☐ Session management: one <code>pandapowerNet</code> per session (in-memory to start)
* ☐ <code>POST /api/network</code> — create empty network, return session ID
* ☐ <code>GET /api/network</code> — return full network as JSON (<code>pp.to_json</code>)
* ☐ <code>DELETE /api/network</code> — clear session

=== M0.2 — Frontend Skeleton ===
* ☐ React (or Vue/Svelte) SPA with router
* ☐ Basic layout: sidebar navigation, main content area, status bar
* ☐ API client module wrapping all backend calls
* ☐ Toast/notification system for errors and success messages

=== M0.3 — Network Import/Export ===
* ☐ <code>POST /api/network/import</code> — accept JSON file upload → <code>pp.from_json()</code>
* ☐ <code>GET /api/network/export?format=json</code> — download as JSON
* ☐ <code>GET /api/network/export?format=xlsx</code> — download as Excel
* ☐ Frontend: Import dialog with drag-and-drop
* ☐ Frontend: Export buttons (JSON, Excel)

=== M0.4 — Built-In Example Networks ===
* ☐ <code>GET /api/networks/examples</code> — list available test networks
* ☐ <code>POST /api/networks/examples/{name}</code> — load a test network (e.g., <code>case_ieee30</code>, <code>mv_oberrhein</code>, <code>simple_four_bus_system</code>)
* ☐ Frontend: "Load Example" picker in new-network flow

----

== Milestone 1: Network Editor (CRUD) ==

=== M1.1 — Bus Management ===
* ☐ Table view of all buses (<code>net.bus</code> DataFrame)
* ☐ Create bus: form with <code>vn_kv</code>, <code>name</code>, <code>type</code>, <code>zone</code>, <code>geodata</code>
* ☐ Edit bus parameters inline or via modal
* ☐ Delete bus (with validation — warn if connected elements exist)
* ☐ Bulk operations: select multiple, delete, change zone

=== M1.2 — Line Management ===
* ☐ Table view of all lines (<code>net.line</code>)
* ☐ Create line: select <code>from_bus</code>, <code>to_bus</code>, <code>length_km</code>, <code>std_type</code> (dropdown from <code>net.std_types["line"]</code>)
* ☐ Create line from parameters: <code>r_ohm_per_km</code>, <code>x_ohm_per_km</code>, <code>c_nf_per_km</code>, <code>max_i_ka</code>
* ☐ Edit/delete lines
* ☐ Show standard type library with search/filter

=== M1.3 — Transformer Management ===
* ☐ Table view of 2-winding transformers (<code>net.trafo</code>)
* ☐ Create trafo: <code>hv_bus</code>, <code>lv_bus</code>, <code>std_type</code> (dropdown from <code>net.std_types["trafo"]</code>)
* ☐ Create from parameters: <code>sn_mva</code>, <code>vn_hv_kv</code>, <code>vn_lv_kv</code>, <code>vk_percent</code>, <code>vkr_percent</code>, etc.
* ☐ Tap changer configuration: <code>tap_pos</code>, <code>tap_min</code>, <code>tap_max</code>, <code>tap_step_percent</code>
* ☐ 3-winding transformers (<code>net.trafo3w</code>) as advanced option

=== M1.4 — Load & Generation ===
* ☐ Create/edit/delete loads: <code>bus</code>, <code>p_mw</code>, <code>q_mvar</code>, <code>type</code> (wye/delta), <code>const_z/i/p_percent</code>
* ☐ Create/edit/delete generators: <code>bus</code>, <code>p_mw</code>, <code>vm_pu</code>, <code>min_p_mw</code>, <code>max_p_mw</code>
* ☐ Create/edit/delete static generators (sgen): <code>bus</code>, <code>p_mw</code>, <code>q_mvar</code>, <code>type</code>
* ☐ Create/edit/delete external grids: <code>bus</code>, <code>vm_pu</code>, <code>va_degree</code>
* ☐ Table views for each element type

=== M1.5 — Switches & Shunts ===
* ☐ Switch management: create between bus-bus or bus-element, toggle open/closed
* ☐ Shunt management: <code>bus</code>, <code>p_mw</code>, <code>q_mvar</code>, <code>vn_kv</code>
* ☐ Storage management: <code>bus</code>, <code>p_mw</code>, <code>max_e_mwh</code>, <code>soc_percent</code>
* ☐ Impedance management: <code>from_bus</code>, <code>to_bus</code>, <code>rft_pu</code>, <code>xft_pu</code>

=== M1.6 — Network Diagram (View Only) ===
* ☐ <code>GET /api/plot/network</code> — return Plotly figure JSON using <code>pp.plotting.plotly.simple_plotly()</code>
* ☐ Render Plotly figure in frontend
* ☐ Auto-generate geodata if missing (<code>pp.plotting.create_generic_coordinates()</code>)
* ☐ Color buses by voltage level
* ☐ Hover tooltips showing element details
* ☐ Zoom, pan, select

----

== Milestone 2: Power Flow Analysis (AC/DC) ==

{{Quote|'''This is the #1 most-used pandapower feature.''' Everything else builds on this.}}

=== M2.1 — Run Power Flow ===
* ☐ <code>POST /api/analysis/powerflow</code> with options:
** <code>algorithm</code>: "nr" (default), "bfsw", "gs", "fdbx", "fdxb"
** <code>init</code>: "auto", "flat", "dc", "results"
** <code>max_iteration</code>, <code>tolerance_mva</code>
** <code>calculate_voltage_angles</code>: true/false/"auto"
** <code>enforce_q_lims</code>: true/false
** <code>trafo_model</code>: "t" / "pi"
** <code>voltage_depend_loads</code>: true/false
** <code>distributed_slack</code>: true/false
* ☐ Return convergence status, iteration count, elapsed time
* ☐ Frontend: "Run Power Flow" button with collapsible options panel

=== M2.2 — Results Dashboard ===
* ☐ Bus results table: <code>vm_pu</code>, <code>va_degree</code>, <code>p_mw</code>, <code>q_mvar</code> — color-code voltage violations
* ☐ Line results table: <code>loading_percent</code>, <code>i_from_ka</code>, <code>i_to_ka</code>, <code>pl_mw</code>, <code>ql_mvar</code> — highlight overloads
* ☐ Transformer results table: <code>loading_percent</code>, <code>pl_mw</code>, <code>ql_mvar</code>
* ☐ Generator results table: <code>p_mw</code>, <code>q_mvar</code>, <code>vm_pu</code>
* ☐ Summary cards: total generation, total load, total losses, max loading, min/max voltage

=== M2.3 — Results Visualization ===
* ☐ Network diagram colored by bus voltage magnitude (heatmap)
* ☐ Network diagram colored by line/trafo loading percentage
* ☐ Use <code>pp.plotting.plotly.pf_res_plotly()</code> or custom Plotly traces
* ☐ Legend showing color scale
* ☐ Toggle between voltage view and loading view

=== M2.4 — DC Power Flow ===
* ☐ <code>POST /api/analysis/dcpowerflow</code> — calls <code>pp.rundcpp()</code>
* ☐ Same results dashboard as AC but with DC-specific fields
* ☐ Frontend toggle: AC / DC power flow

=== M2.5 — Power Flow PDF Report ===
* ☐ <code>GET /api/report/powerflow</code> — generate PDF
* ☐ Report contents:
** Network summary (# buses, lines, trafos, gens, loads)
** Solver settings used
** Convergence info
** Bus voltage table (sorted by violation severity)
** Line loading table (sorted by loading %)
** Transformer loading table
** Total generation vs total load vs losses
** Network diagram screenshot (server-side Plotly image export)
** Voltage profile chart (vm_pu vs bus index)
** Loading bar chart (top 10 most loaded branches)
* ☐ PDF library: WeasyPrint or ReportLab on backend

----

== Milestone 3: Optimal Power Flow (OPF) ==

=== M3.1 — Cost Function Setup ===
* ☐ UI to define polynomial costs per generator/load: <code>cp0_eur</code>, <code>cp1_eur_per_mw</code>, <code>cp2_eur_per_mw2</code>
* ☐ UI to define piecewise-linear costs
* ☐ Set <code>controllable=True</code> on generators/loads/storage
* ☐ Set min/max P and Q limits on controllable elements
* ☐ Set voltage limits on buses: <code>min_vm_pu</code>, <code>max_vm_pu</code>
* ☐ Set loading limits on lines/trafos: <code>max_loading_percent</code>

=== M3.2 — Run OPF ===
* ☐ <code>POST /api/analysis/opf</code> — calls <code>pp.runopp()</code>
* ☐ <code>POST /api/analysis/dcopf</code> — calls <code>pp.rundcopp()</code>
* ☐ Options: <code>init</code>, <code>verbose</code>, <code>delta</code>
* ☐ Return objective value, convergence, dispatch schedule

=== M3.3 — OPF Results Dashboard ===
* ☐ Optimal dispatch table: generator P/Q setpoints
* ☐ Cost breakdown per generator
* ☐ Binding constraints highlighted (voltage limits, loading limits, P/Q limits)
* ☐ Comparison view: base case vs OPF dispatch

=== M3.4 — OPF PDF Report ===
* ☐ Network & cost setup summary
* ☐ Optimal dispatch schedule
* ☐ Total cost
* ☐ Binding constraints
* ☐ Voltage/loading compliance tables
* ☐ Generation dispatch bar chart

----

== Milestone 4: Short-Circuit Analysis ==

=== M4.1 — Run Short-Circuit ===
* ☐ <code>POST /api/analysis/shortcircuit</code> with options:
** <code>fault</code>: "3ph", "2ph", "1ph"
** <code>case</code>: "max", "min"
** <code>ip</code>: true/false (aperiodic current)
** <code>ith</code>: true/false (thermal equivalent)
** <code>tk_s</code>: fault clearing time
** <code>lv_tol_percent</code>: 6 or 10
** <code>r_fault_ohm</code>, <code>x_fault_ohm</code>: fault impedance
** <code>branch_results</code>: true/false
* ☐ Calls <code>pp.shortcircuit.calc_sc(net, ...)</code>

=== M4.2 — Short-Circuit Results ===
* ☐ Bus SC table: <code>ikss_ka</code> (symmetrical), <code>ip_ka</code> (peak), <code>ith_ka</code> (thermal)
* ☐ Branch SC table (if branch_results=True): currents through lines/trafos
* ☐ Highlight buses exceeding equipment ratings
* ☐ Network diagram colored by SC current magnitude

=== M4.3 — Short-Circuit PDF Report ===
* ☐ Fault type & case settings
* ☐ Bus short-circuit current table (sorted by magnitude)
* ☐ Branch currents (if calculated)
* ☐ Equipment rating comparison (SC current vs breaker rating)
* ☐ Network diagram with SC current overlay
* ☐ Bar chart: top 10 highest SC currents

----

== Milestone 5: Network Diagnostics & Topology ==

=== M5.1 — Network Diagnostics ===
* ☐ <code>POST /api/diagnostic</code> — calls pandapower diagnostic functions
* ☐ Check for: isolated buses, duplicate lines, disconnected elements, missing impedance, impossible switch configs
* ☐ Return categorized issues with severity (error, warning, info)
* ☐ Frontend: diagnostic panel with expandable issue groups
* ☐ Quick-fix suggestions where possible

=== M5.2 — Topology Analysis ===
* ☐ <code>GET /api/topology</code> — network graph analysis
* ☐ Connected components (islands)
* ☐ Unsupplied buses
* ☐ Stubs, bridges, articulation points
* ☐ Meshed vs radial classification
* ☐ Frontend: highlight topology features on network diagram

=== M5.3 — Diagnostics PDF Report ===
* ☐ Issue summary by category
* ☐ Detailed issue list with element references
* ☐ Topology summary
* ☐ Connectivity diagram

----

== Milestone 6: State Estimation ==

=== M6.1 — Measurement Management ===
* ☐ Create/edit/delete measurements: <code>meas_type</code> (v, p, q, i), <code>element_type</code>, <code>element</code>, <code>value</code>, <code>std_dev</code>
* ☐ Table view of all measurements
* ☐ Visual overlay: show measurement locations on network diagram

=== M6.2 — Run State Estimation ===
* ☐ <code>POST /api/analysis/estimation</code> with options:
** <code>algorithm</code>: "wls", "wls_with_zero_constraint", "irwls", "opt", "lp"
** <code>init</code>: "flat", "results", "slack"
** <code>tolerance</code>, <code>maximum_iterations</code>
** <code>zero_injection</code>: handling of zero-injection buses
* ☐ Calls <code>pp.estimation.estimate(net, ...)</code>

=== M6.3 — Estimation Results ===
* ☐ Estimated vs measured values comparison table
* ☐ Residual analysis (measurement residuals)
* ☐ Bad data detection indicators
* ☐ Estimated voltage profile overlay on network diagram

=== M6.4 — State Estimation PDF Report ===
* ☐ Measurement summary
* ☐ Estimated state table
* ☐ Residual statistics
* ☐ Bad data flags
* ☐ Voltage profile comparison (estimated vs measured)

----

== Milestone 7: Time Series Simulation ==

=== M7.1 — Time Series Data Setup ===
* ☐ Upload CSV/Excel time-varying profiles (load P/Q, generation P/Q per timestep)
* ☐ Map profiles to network elements (which profile → which load/generator)
* ☐ Preview profiles as time-series charts
* ☐ Built-in profile templates (daily load curve, solar generation curve)

=== M7.2 — Run Time Series ===
* ☐ <code>POST /api/analysis/timeseries</code> with options:
** <code>time_steps</code>: range or list
** <code>continue_on_divergence</code>: true/false
** <code>output_variables</code>: which results to record
* ☐ Progress indicator (WebSocket or SSE for long simulations)
* ☐ Cancel running simulation

=== M7.3 — Time Series Results ===
* ☐ Time-series charts: voltage at selected buses over time
* ☐ Time-series charts: loading at selected branches over time
* ☐ Heatmap: all bus voltages over all timesteps
* ☐ Statistical summary: min, max, mean, std for each element
* ☐ Identify timesteps with violations

=== M7.4 — Time Series PDF Report ===
* ☐ Simulation setup summary
* ☐ Key statistics table
* ☐ Voltage and loading time-series charts
* ☐ Violation summary (which timesteps, which elements)
* ☐ Daily/hourly aggregated tables

----

== Milestone 8: Contingency Analysis ==

=== M8.1 — Contingency Definition ===
* ☐ Define contingency set: which lines/trafos/generators to trip
* ☐ N-1 auto-generation: all single-element outages
* ☐ Custom contingency lists
* ☐ Import/export contingency definitions

=== M8.2 — Run Contingency Analysis ===
* ☐ <code>POST /api/analysis/contingency</code> — calls <code>pp.contingency.run_contingency()</code>
* ☐ Parallel execution for large contingency sets
* ☐ Progress indicator

=== M8.3 — Contingency Results ===
* ☐ Table: each contingency case → worst voltage violation, worst loading
* ☐ Highlight critical contingencies (non-convergent or with violations)
* ☐ Drill-down: click a contingency to see full results
* ☐ Network diagram: overlay worst-case loading

=== M8.4 — Contingency PDF Report ===
* ☐ Contingency set summary
* ☐ Critical contingencies table
* ☐ Per-contingency results (top N worst cases)
* ☐ Comparison charts: base case vs contingency loading
* ☐ Pass/fail summary

----

== Milestone 9: Advanced Features ==

=== M9.1 — Controller Configuration ===
* ☐ List active controllers in network
* ☐ Configure tap changer controllers: target voltage, deadband, side
* ☐ Configure DER controllers: droop settings, reactive power modes
* ☐ Run power flow with controllers enabled (<code>run_control=True</code>)
* ☐ Show controller convergence info

=== M9.2 — Protection Devices ===
* ☐ Fuse configuration and coordination
* ☐ Overcurrent relay settings
* ☐ Protection coordination diagrams (time-current curves)
* ☐ Protection PDF report

=== M9.3 — Grid Equivalents ===
* ☐ Define internal/external zones
* ☐ Generate REI or Ward equivalents
* ☐ Compare full network vs equivalent results
* ☐ Export equivalent network

=== M9.4 — Three-Phase Analysis ===
* ☐ Asymmetric load/generator creation
* ☐ Run 3-phase unbalanced power flow (<code>runpp_3ph</code>)
* ☐ Phase-specific results (A, B, C voltages/currents)
* ☐ Unbalance factor visualization

=== M9.5 — FACTS Devices ===
* ☐ SVC, TCSC, SSC, VSC creation and configuration
* ☐ Results with FACTS devices in power flow
* ☐ FACTS device operating point visualization

----

== Milestone 10: Project Management & Collaboration ==

=== M10.1 — Project Save/Load ===
* ☐ Save network + settings + results to project file
* ☐ Load project file to restore full state
* ☐ Auto-save / recovery
* ☐ Project metadata: name, description, author, date

=== M10.2 — Scenario Comparison ===
* ☐ Save named scenarios (snapshots of network state)
* ☐ Compare two scenarios side-by-side
* ☐ Diff view: what changed between scenarios
* ☐ Comparison PDF report

=== M10.3 — User Management (if multi-user) ===
* ☐ Authentication
* ☐ Project sharing / permissions
* ☐ Audit log of changes

----

== Milestone 11: Format Converters ==

=== M11.1 — Import Formats ===
* ☐ MATPOWER <code>.m</code> files → <code>pp.converter.from_mpc()</code>
* ☐ PYPOWER case dicts → <code>pp.converter.from_ppc()</code>
* ☐ CIM/CGMES XML → <code>pp.converter.cim.from_cim()</code>
* ☐ PowerFactory <code>.dgs</code> → <code>pp.converter.powerfactory.from_pf()</code>
* ☐ UCTE <code>.uct</code> files → <code>pp.converter.ucte.from_ucte()</code>

=== M11.2 — Export Formats ===
* ☐ MATPOWER format export
* ☐ PYPOWER format export
* ☐ CIM export (where supported)

----

== Report Generation Strategy ==

Every analysis milestone includes PDF report generation. The approach:

=== Backend PDF Pipeline ===
<syntaxhighlight lang="text">
Analysis Results (DataFrames)
│
├─→ Jinja2 HTML template (styled tables, charts)
│ │
│ ├─→ Plotly server-side image export (kaleido)
│ │
│ └─→ WeasyPrint → PDF
│
└─→ Alternative: ReportLab for direct PDF generation
</syntaxhighlight>

=== Report Template Structure ===
Every report shares a common structure:
# '''Header''': Report title, date, network name, pandapower version
# '''Network Summary''': Element counts, voltage levels, total generation/load
# '''Analysis Settings''': Parameters used
# '''Results Tables''': Sorted by severity/importance, color-coded
# '''Charts/Diagrams''': Network plots, bar charts, profiles
# '''Footer''': Page numbers, generation timestamp

=== PDF Generation Priority ===
{| class="wikitable"
|-
! Priority !! Report !! Milestone
|-
| 1 || Power Flow Report || M2.5
|-
| 2 || Short-Circuit Report || M4.3
|-
| 3 || OPF Report || M3.4
|-
| 4 || Diagnostics Report || M5.3
|-
| 5 || Time Series Report || M7.4
|-
| 6 || Contingency Report || M8.4
|-
| 7 || State Estimation Report || M6.4
|-
| 8 || Protection Report || M9.2
|-
| 9 || Scenario Comparison Report || M10.2
|}

----

== Non-Functional Requirements ==

=== Performance ===
* Power flow on networks up to 10,000 buses should complete in < 5 seconds
* PDF report generation should complete in < 30 seconds
* Time series: show progress for simulations > 100 timesteps
* Use <code>recycle</code> option for repeated power flows

=== Usability ===
* Responsive layout (desktop primary, tablet secondary)
* Keyboard shortcuts for common actions (Ctrl+R = run power flow)
* Undo/redo for element creation/modification
* Contextual help linking to pandapower documentation

=== Reliability ===
* Graceful handling of non-convergent power flows (show diagnostic info)
* Input validation before sending to backend
* Auto-save network state every 5 minutes
* Session recovery after browser refresh

=== Security ===
* Input sanitization on all API endpoints
* File upload size limits and type validation
* No arbitrary code execution from user input
* Rate limiting on analysis endpoints

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

Pandapower GUI PRD - Revision history

Justinaquino: "Add Pandapower and ONLYOFFICE Nextcloud analysis pages"