Metadata-Version: 2.4
Name: vectorgrid
Version: 0.2.0
Summary: Power system analysis you can read, audit, and trust.
Author-email: VectorGrid team <info@vectorgrid.me>
License-Expression: LicenseRef-BSL-1.1
Project-URL: Homepage, https://vectorgrid.me
Project-URL: Documentation, https://docs.vectorgrid.me
Project-URL: Repository, https://github.com/vectorgrid-me/vectorgrid
Project-URL: Issues, https://github.com/vectorgrid-me/vectorgrid/issues
Keywords: power systems,power flow,load flow,Newton-Raphson,short-circuit,IEC 60909
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/vectorgrid-me/vectorgrid/main/assets/logo.png" alt="VectorGrid" width="48" height="48" />
</p>

<h1 align="center">VectorGrid</h1>

<p align="center">
  <strong>Power system analysis you can read, audit, and trust.</strong>
</p>

<p align="center">
  <a href="https://vectorgrid.me">Website</a> &middot;
  <a href="https://docs.vectorgrid.me">Documentation</a> &middot;
  <a href="https://vectorgrid.me/privacy">Privacy</a>
</p>

---

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

```bash
pip install vectorgrid
```

Requires Python 3.10+.

## Quick Start

```python
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](https://numpy.org/) >= 1.24
- [SciPy](https://scipy.org/) >= 1.10

No other runtime dependencies.

## License

VectorGrid is source-available under the [Business Source License 1.1](LICENSE).

- **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 [info@vectorgrid.me](mailto:info@vectorgrid.me).

## Links

- [Documentation](https://docs.vectorgrid.me)
- [Desktop Application](https://vectorgrid.me) — GUI with interactive single-line diagrams
- [Report an Issue](https://github.com/vectorgrid-me/vectorgrid/issues)
