Metadata-Version: 2.4
Name: 4pace
Version: 0.4.0a0
Summary: Four-Quadrant Power Analysis & Computational Engine
Author-email: daniel-sakdinun <sakdinun.thewana@gmail.com>
Project-URL: Homepage, https://github.com/daniel-sakdinun/4PACE.git
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cvxopt
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: networkx
Requires-Dist: pyyaml
Dynamic: license-file

# ⚡ Four-Quadrant Power Analysis & Computational Engine (4PACE)

[![Status](https://img.shields.io/badge/Status-Early%20Access-orange.svg)]()
[![Version](https://img.shields.io/badge/version-v0.4.0a0-blue.svg)]()
[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/)
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)

> **⚠️ Early Access Notice (v0.4.0a0)**
> 
> This project has evolved into a Military-Grade Grid Simulator. 4PACE now integrates Capacity Expansion Planning (CEP) seamlessly with Security-Constrained Optimal Power Flow (SCOPF), ensuring that your most cost-effective investments can also physically survive catastrophic N-1 grid contingencies.

**4PACE** is a high-precision, commercial-grade Power System Optimization Engine designed for modern electrical grids. Built entirely in Python using cutting-edge convex optimization (CVXPY) and graph theory (NetworkX), 4PACE handles everything from radial microgrids to complex mesh networks like the IEEE 14 Bus System.

---

## 🚀 What's New in v0.4.0a0? (The Security & Resilience Leap)

* **Preventive SCOPF (Multiverse OPF):** Optimizes the Base Case (N-0) while simultaneously calculating parallel universes for every single N-1 line outage. It ensures the grid survives any single point of failure without breaking operational limits.
* **Smart ESS & Inverter Rescue Protocol:** AI automatically generates "Emergency Plans" where Battery Energy Storage Systems (BESS) inject active power, and Smart Inverters act as STATCOMs (Volt-VAR support) to prevent voltage collapse during contingencies.
* **Military-Grade Physics Auditor (`Validate_N1`):** A bulletproof N-1 Newton-Raphson validation suite featuring:
  * **Islanding Detection:** Graph-based radial line screening (`networkx`) to intelligently skip inherently unresolvable topological fractures.
  * **State Preservation ("Save/Load Game"):** Deep state caching ensures that diverged contingency calculations do not corrupt the foundational N-0 grid state.
* **Unified CEP to SCOPF Pipeline:** AI decides what to build (Solar, BESS), and immediately stress-tests those exact investments against total grid failure scenarios.

## 🌟 Core Architecture (Carried from v0.3.0)
* **Switchable Relaxation:** `relax='SOCP'` for ultra-fast radial flow models, and `relax='SDP'` (Hermitian Matrix) for complex mesh/ring network injection models.
* **Unified MPOPF Engine:** 24-hour time-series Operational Planning with energy inter-temporal constraints (SoC).
* **Robust N-R Validation:** Full AC Newton-Raphson solver to guarantee 100% physical feasibility (KCL/KVL compliance) with automatic PV-to-PQ switching during reactive power limit hits.

---

## 🛠️ Quick Start Guide

### 1. Define your grid and candidate assets (`config.yaml`)
Create a configuration file. Add `is_candidate: true` and pricing metrics to let AI dynamically size your modern assets.
```yaml
Sbase: 100.0
buses:
  - name: "Bus_14"
    Vbase: 33.0
    bus_type: PQ
    components:
      - type: Load
        name: L14
        P: 14.9
        Q: 5.0
      # AI will decide optimal MW/MWh based on CapEx vs OpEx
      - type: Battery
        name: BESS_14
        is_candidate: true
        capex_per_mw: 200000.0
        capex_per_mwh: 350000.0
        max_build_mw: 50.0
        max_build_mwh: 200.0
      # Smart Inverters act as emergency Volt-VAR support!
      - type: Inverter
        name: PV_14
        source_type: solar
        is_candidate: true
        capex_per_mw: 900000.0
        max_build_mw: 80.0
```

### 2. Run the Security & Investment Pipeline (Python)
Execute the complete workflow: Sizing -> Dispatch -> Multiverse N-1 Protection -> Physics Validation.
```python
import pandas as pd
from fourpace.psys import Grid
from fourpace.pfa import CEP, SCOPF, Validate_N1

# Load configurations & 24h profiles
grid = Grid.load('config.yaml')
profile_df = pd.read_csv('profiles.csv')

# Step 1: Investment Phase (Capacity Expansion Planning)
# AI calculates optimal sizes for candidate assets (BESS, Solar)
CEP(grid, profile_df, relax='SOCP', solver='CLARABEL')

# Step 2: Security Phase (Preventive SCOPF)
# AI dispatches the grid for peak hour while generating emergency rescue plans
rescue_plan = SCOPF(grid, peak_hour=19, relax='SOCP', solver='CLARABEL')

# Step 3: Physical Validation (The Auditor)
# Physically sever every transmission line one-by-one and simulate Newton-Raphson with the Rescue Plan
Validate_N1(grid, rescue_plan=rescue_plan)
```

---

### 🔬 Under the Hood
4PACE refuses to trust AI blindly.

Master Plan Generation: Uses Convex Relaxation (SOCP/SDP) to find the global mathematical optimum for capacity and dispatch.

Physical Check-bill: The results are strictly validated against exact non-linear AC Power Flow (Newton-Raphson). If an AI hallucination violates Kirchhoff's laws or causes a Voltage Collapse, the Auditor will flag it.

---

### 📜 License
This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3). See the LICENSE file for details. This ensures that the core mathematical engine remains open and beneficial to the entire engineering community.

---
