DevEN
A high-performance power system study engine for loading electrical network models, configuring engineering studies, executing ultra-fast calculations, and extracting comprehensive results through the devenpy Python interface and standalone study runners.
.rawx) format. RAWX provides a modern, schema-validated structured XML/JSON representation with full IEEE floating-point precision and fast native parsing.
Installation & CLI Setup
Install the devenpy package directly from your wheel or repository:
pip install devenpy
Once installed, you can launch this interactive documentation locally or scaffold all study runners into your working directory with simple CLI commands:
# 1. Open this interactive documentation in your web browser (via local web server): devenpy --docs # 2. Export all 6 editable study runners, universal I/O parser, and benchmark grids directly to your current folder: devenpy --export-runners # You can also run via Python module: python -m devenpy --docs python -m devenpy --export-runners
Quick Start
Create a case, load a recommended .rawx network file, run an AC load-flow calculation and inspect the returned convergence status:
import devenpy
# Instantiate PyCase and load recommended RAWX network
case = devenpy.PyCase()
case.load_rawx("cases/bench.rawx") # First preference: PSS/E RAWX
# Execute AC Newton-Raphson Load Flow
status = case.solve_load_flow(
method="nr",
tol=1e-5,
max_iter=30,
enforce_q_limits=True
)
print("Converged:", status["converged"])
print("Iterations:", status["iterations"])
print("Max |dP|:", status["max_dp"])
# Inspect bus voltage and power injection
v_mag, v_ang = case.bus_voltage(1)
p_inj, q_inj = case.bus_power(1)
print(f"Bus 1: V = {v_mag:.4f} pu, P = {p_inj:.2f} MW, Q = {q_inj:.2f} MVar")Standalone Study Runners
DevEN includes 6 specialized, turnkey runner scripts designed for practical engineering workflows. Each script contains an editable in-code configuration block at the top, supports interactive file pasting, and outputs formatted console tables and CSV reports.
1. run_lfa.py — Load Flow Analysis
High-performance AC and DC power flow engine supporting Newton-Raphson, Fast Decoupled, DC Linear, Constant Jacobian, and Gauss-Seidel.
| In-Code Option | Allowed Values | Description |
|---|---|---|
METHOD | "nr", "fdlf", "dc", "dishonest", "gs" | Algorithm selection. Full NR is recommended for large grids. |
TOLERANCE | 0.0001 / 1e-5 | Power mismatch convergence tolerance (p.u.). |
MAX_ITER | 30 - 50 | Maximum iteration count before abort or fallback. |
ENFORCE_Q_LIMITS | True / False | Check generator reactive capability limits and convert PV buses to PQ when clamped. |
CHECK_VOLTAGE | True / False | Screen all buses for under/overvoltage against V_MIN_PU and V_MAX_PU. |
CUSTOM_GEN_EDITS | List of dicts | In-code modification of generator setpoints (pg, vs, qmax, qmin) before solve. |
CUSTOM_LOAD_EDITS | List of dicts | In-code modification of active and reactive load demands (pl, ql). |
python run_lfa.py
2. run_scs.py — Short Circuit Studies (IEC 60909 / ANSI C37)
Calculates symmetrical and asymmetrical short-circuit currents, equivalent X/R ratios, circuit breaker duty ratings, and branch/generator fault contributions.
| In-Code Option | Allowed Values | Description |
|---|---|---|
STUDY_MODE | "custom", "single", "scan" | Run custom list of faults, single-bus fault, or system-wide scan across all buses. |
CUSTOM_FAULTS | List of dicts | Define multiple faults in code: bus, type (3phase, slg, ll, dlg), method (iec, ansi), rf, xf, cb_mva. |
METHOD | "iec" / "ansi" | Standards: IEC 60909:2016 or ANSI/IEEE C37.010 / C37.5. |
C_FACTOR | 1.10 / 1.00 | IEC voltage factor c (1.10 for maximum short-circuit current, 1.00 for minimum). |
BREAKER_CHECK | True / False | Evaluates breaker duty percentage and CEA 80% safety margin. |
python run_scs.py
3. run_bc.py — Batch Contingency & N-1 Outage Screening
Performs high-speed parallel N-1 contingency analysis across transmission lines, transformers, and generators, checking for post-contingency voltage collapse and violations.
| In-Code Option | Allowed Values | Description |
|---|---|---|
CONTINGENCY_MODE | "custom", "auto", "both" | Run user-defined outages in CUSTOM_CONTINGENCIES, full automated N-1 sweep, or both. |
CUSTOM_CONTINGENCIES | List of dicts | Define lines (from_bus, to_bus, ckt), transformers, and generator trips (bus, id). |
METHOD | "fdlf" / "nr" | Fast Decoupled is recommended for sub-millisecond per-contingency screening. |
V_MIN_PU / V_MAX_PU | 0.90 / 1.10 | Post-contingency voltage emergency limits. |
python run_bc.py
4. run_ha.py — Harmonic Analysis & Resonance Frequency Scan
Calculates driving-point impedance profiles Z(f), identifies parallel resonance frequencies, solves multi-order harmonic penetration, and assesses IEEE 519 compliance.
| In-Code Option | Allowed Values | Description |
|---|---|---|
STUDY_TYPE | "scan", "harmonics", "both" | Execute frequency scan, multi-order harmonic flow, or both. |
F_START_HZ / F_END_HZ | 50.0 / 2500.0 | Frequency sweep range (Hz) (up to 50th harmonic order). |
CUSTOM_HARMONIC_SOURCES | List of dicts | Inject harmonic current sources: bus, name, phase, i_fund_amps, ang_deg, spectrum_type (6pulse, 12pulse, custom). |
CUSTOM_HARMONIC_FILTERS | List of dicts | Install mitigation filters: bus, name, filter_type (single_tuned, high_pass), tuning_order, q_factor, mvar_rating. |
THD_V_LIMIT_PCT | 5.0 | Maximum allowable bus voltage Total Harmonic Distortion (%) under IEEE 519. |
python run_ha.py
5. run_3ph.py — Three-Phase Unbalanced Power Flow
Full phase-coordinate (ABC+N) load flow solver for unbalanced distribution networks, DER integration, and single-phase load studies.
| In-Code Option | Allowed Values | Description |
|---|---|---|
WIRE_CONFIG | "4wire" / "3wire" | 4-wire system with explicit neutral conductor or Kron-reduced 3-wire. |
METHOD | "fcim" / "nr" | Forward Current Injection Method or 3-phase Newton-Raphson. |
CUSTOM_PHASE_LOADS | List of dicts | Specify unbalanced phase loads: bus, pa_mw, qa_mvar, pb_mw, qb_mvar, pc_mw, qc_mvar. |
MAX_VUF_PCT | 2.0 | IEEE 2% Voltage Unbalance Factor (V2/V1 %) compliance threshold. |
python run_3ph.py
6. run_af.py — Arc Flash Hazard Analysis (IEEE 1584-2018)
Evaluates arcing current, incident energy, arc flash boundary, and required personal protective equipment (PPE) category per IEEE 1584-2018 and NFPA 70E-2024.
| In-Code Option | Allowed Values | Description |
|---|---|---|
STUDY_MODE | "custom", "single", "scan" | Evaluate custom equipment list, single bus, or all energized buses. |
CUSTOM_ARC_FLASH_BUSES | List of dicts | Define equipment: bus, config (vcb, vcbb, hcb, voa, hoa), working_dist_mm, gap_mm, clearing_time. |
WORKING_DIST_MM | 457.2 / 610.0 / 914.4 | Working distance (18 inches for panels, 24 inches for switchgear, 36 inches for open yard). |
CLEARING_TIME_SEC | 0.05 - 0.20 | Total protective relay tripping + circuit breaker clearing time. |
python run_af.py
PyCase Object & Core Methods
PyCase is the master container holding the electrical topology, device models, solver states, and results.
Construct a new empty PyCase instance.
Create an independent, deep in-memory clone of the network model and solver state for contingency screening and what-if analysis.
Data Ingestion & Universal Extended I/O
Load network models from RAWX, RAW, encrypted .deven, or extended formats (MATPOWER, CDF, Excel):
First Preference: Load PSS/E RAWX format files (v35/v36 XML or JSON structured format) with high-speed schema parsing and full numeric precision.
Load standard PSS/E RAW format files (versions 30 through 36), including zero-sequence impedances and transformer grounding.
save_deven(path: str) -> None
Load or save native DevEN SQLite database files (.deven). The file is securely encrypted on disk without prompting for passwords.
Universal parser supporting MATPOWER (.m), IEEE CDF (.cdf), Excel workbooks (.xlsx, .xls), PowerWorld (.aux), UCTE (.def), and CIM/CGMES RDF XML (.xml, .zip).
Automatically detect format by file extension (.rawx, .raw, .deven, .json) and load the grid.
In-Memory Network Modifiers
Dynamically modify network components in memory without re-parsing files:
| Method | Parameters | Purpose |
|---|---|---|
chng_bus() | bus_id, vm, va, base_kv, ide, gl, bl | Modify voltage initial estimate, base kV, bus type (1=PQ, 2=PV, 3=Slack, 4=Isolated), and shunts. |
chng_load() | bus_id, id, pl, ql, status | Modify load active/reactive power demand and in-service status. |
chng_gen() | bus_id, id, pg, qg, vs, status, qmax, qmin | Modify generator active power, voltage setpoint, reactive limits, and status. |
chng_brn() | f, t, ckt, r, x, b, ratio, angle, status, rate_a | Modify branch impedance, line charging, tap ratio, phase shift, status, and MVA rating. |
scs_chng_bus() | bus_id, is_grid_infeed, sk_mva, rx_ratio, z01_ratio, cb_mva | Modify short circuit capacity, system R/X ratio, and breaker rating. |
scs_chng_gen() | bus_id, id, xd_sub, x2, x0, conn, gnd_r, gnd_x | Modify subtransient reactance Xd'', sequence reactances, and grounding impedance. |
scs_chng_brn() | f, t, ckt, r0, x0, b0, from_conn, to_conn | Modify branch zero-sequence impedance and transformer winding connections. |
Load Flow Analysis (LFA) API
Returns a dictionary containing converged (bool), iterations (int), max_dp (float), and max_dq (float).
Short Circuit Studies (SCS) API
Calculates initial symmetrical short-circuit current ik_ka, peak making current ip_ka, symmetrical breaking current ib_ka, short-circuit power sk_mva, and equivalent xr_ratio.
scs_brn_flow(f, t, ckt="") -> Dict[str, Any]
scs_breaker_duty(bus, cb_mva=None) -> Dict[str, Any]
Queries post-fault individual generator fault current, branch flow inflows, and circuit breaker interrupting duty percentage.
Results, Queries & Export
Vectorized C-speed extraction of all bus voltages ('VM', 'VA') or branch flows across the entire network.
Return complete simulation results (bus results, branch flows, generator outputs) as Python dict or serialized JSON.
Generate formatted columnar PSS/E reports (.out) and bus-by-bus active/reactive energy conservation balances (.kcl).
Master Command-Line Interface
The devenpy command line tool is built directly into the pip package and requires no external binaries:
# Scaffolding: Export all 6 runners into the active terminal folder devenpy --export-runners # Web Documentation: Launch interactive portal on local web server devenpy --docs devenpy --docs --port 8080 # Direct Simulations (RAWX First Preference) devenpy cases/bench.rawx # AC Load Flow (NR on RAWX) devenpy cases/bench.rawx --study scs --scan # Full system fault scan devenpy cases/bench.rawx --format out -o output.out # PSS/E columnar report
Supported Network Formats
Recommended standard: Schema-validated XML/JSON structured format with full floating-point precision.
Supports legacy versions 30 through 36, including zero-sequence data and FACTS devices.
Fast encrypted SQLite format storing topology, solved states, and sequence parameters.
Universal parsing of .m, .cdf, and .xlsx via deven_io module.
Direct parsing of PowerWorld .aux scripts and European UCTE transmission files.
IEC 61970 / 61968 Common Information Model profiles.