vectorgrid 0.2.0

Power system analysis you can read, audit, and trust.

VectorGrid

Power system analysis you can read, audit, and trust.

Website · Documentation · Privacy

---

VectorGrid is a Python library for power system analysis. It ships a Newton-Raphson power flow solver and IEC 60909 short-circuit analysis, with optimal power flow and more on the way.

Every matrix assembly, every iteration, every convergence check is readable code — not a black box. Built on NumPy and SciPy. No wrappers around legacy Fortran. No opaque binaries.

Installation

pip install vectorgrid

Requires Python 3.10+.

Quick Start

from vectorgrid import Network

net = Network(sb_mva=100, f_hz=50)

# Create buses
b1 = net.add_bus(vr_kv=110.0)
b2 = net.add_bus(vr_kv=20.0)

# Add a transformer
net.add_transformer_2w(bus_1=b1, bus_2=b2, sr_mva=40, vk_percent=12.0,
                       pcu_kw=50, pfe_kw=30, j0_percent=0.1)

# External grid (slack bus)
net.add_external_grid(bus=b1, v_percent=102, sk_max_mva=2000, rx_ratio=0.1)

# Load
net.add_load(bus=b2, p_mw=20, q_mvar=10)

# Run power flow
results = net.run_power_flow(method="nr", tolerance=1e-8, max_iterations=30)

print(results["converged"])
print(results["buses"])
print(results["lines"])

# Short-circuit analysis
from vectorgrid import ShortCircuit

sc = ShortCircuit(net)

# IEC 60909 — all-bus sweep
sc_results = sc.run_iec60909(fault_type='3ph', case='max')
print(sc_results["buses"])

# IEC 60909 — single bus, detailed
sc_detail = sc.run_iec60909(fault_type='lg', case='max', fault_bus=b2)
print(sc_detail["fault"])

# Superposition method
sc_super = sc.run_superposition(fault_type='3ph', fault_bus=b2)
print(sc_super["fault"])

Features

Power Flow (v0.1)

• Newton-Raphson — full Jacobian with sparse direct solver
• Decoupled Newton-Raphson — P-theta / Q-V separation with LU factorization
• Voltage-dependent load models (constant power, ZIP, exponential)
• Transformer tap changers and phase shifters
• Configurable convergence tolerance and iteration limits

Short-Circuit Analysis (v0.2)

• IEC 60909 — standards-based calculation for equipment rating (Ik'', ip, Ib, Ith)
• Superposition method — physically accurate fault analysis using pre-fault power flow
• Three-phase, line-to-ground, line-to-line, and line-to-line-to-ground faults
• Voltage correction factors, generator/transformer correction factors (KG, KS)
• All-bus sweep or single-bus detailed analysis
• Sequence-domain modeling (positive, negative, zero) with transformer vector group handling

Coming Soon

• Optimal Power Flow — generation dispatch, voltage setpoints, and reactive power optimization
• Hosting Capacity Analysis — assess grid capacity for solar, wind, storage, and EV chargers
• Volt/VAR Optimization — optimal placement and sizing of reactive compensation
• Network Reconfiguration — topology optimization to minimize losses

Why VectorGrid?

Power system engineers routinely make decisions worth millions of dollars based on simulation results from tools they cannot inspect. VectorGrid takes a different approach:

• Read the solver. Every line of the Newton-Raphson implementation, Jacobian assembly, and admittance matrix construction is source code you can open, read, and understand.
• Validate the math. Compare results against IEEE test cases, pandapower, or hand calculations. The test suite does this systematically.
• Use it freely. Research, education, internal engineering work — no restrictions. Build scripts, automate studies, integrate into your workflows.

Dependencies

• NumPy >= 1.24
• SciPy >= 1.10

No other runtime dependencies.

License

VectorGrid is source-available under the Business Source License 1.1.

• Free to use for research, education, and internal engineering work
• Cannot be used to build a competing commercial power system analysis product
• Converts to Apache License 2.0 on May 7, 2030

For commercial licensing inquiries, contact [e-mail].

Links

• Documentation
• Desktop Application — GUI with interactive single-line diagrams
• Report an Issue