Metadata-Version: 2.4
Name: 4pace
Version: 0.5.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 :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cvxpy
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: networkx
Requires-Dist: pyyaml
Requires-Dist: pandas
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.5.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.5.0a0)**
> 
> The evolution continues. 4PACE has transformed from an optimization solver into a comprehensive, Commercial-Grade Grid Simulator. Version 0.5.0a0 introduces the **Ultimate Fault Analysis Engine**, capable of solving complete Sequence Networks (Positive, Negative, Zero) for both Shunt and Series faults seamlessly alongside our established CEP and SCOPF modules.

**4PACE** is a high-precision Power System Optimization and Analysis Engine designed for modern electrical grids. Built entirely in Python utilizing robust libraries (`cvxpy`, `networkx`, `numpy`), 4PACE handles everything from microgrid investment planning to asymmetrical short-circuit fault analysis on complex mesh networks like the IEEE 14 Bus System.

---

## 🚀 What's New in v0.5.0a0? (The Fault Analysis Evolution)

* **Comprehensive Short Circuit Engine (Shunt Faults):** Unified solver for Three-Phase (3PH), Single Line-to-Ground (SLG), Line-to-Line (LL), and Double Line-to-Ground (DLG) faults.
* **Open Conductor Simulator (Series Faults):** Capable of analyzing unbalanced network states caused by severed transmission lines (1-Open, 2-Open, and 3-Open conductors).
* **Full Sequence Network Integration:** Automatically constructs Positive ($Z_1$), Negative ($Z_2$), and strictly topological Zero-Sequence ($Z_0$) Y-bus matrices. It features dynamic Kronecker-delta switching logic for Transformer grounding connections (e.g., Yg-Yg, Delta-Yg).
* **Batch Orchestrator (`analyze_faults`):** "One-Click Report" generation. Scan your entire power system across all 7 fault topologies simultaneously to extract the Worst-Case (`MAX_kA`) Circuit Breaker duties and post-fault voltage sags.

## 🌟 Core Architecture (Legacy PFA Modules)
* **Capacity Expansion Planning (CEP):** Dynamically sizes Solar Inverters and BESS (MWh/MW) by co-optimizing CapEx and 24-hour OpEx.
* **Preventive SCOPF (Multiverse OPF):** Optimizes the Base Case (N-0) while ensuring survivability across all N-1 line outages, deploying AI-generated emergency BESS and Volt-VAR dispatch rescue plans.
* **Military-Grade Physics Auditor (`Validate_N1`):** A strict Newton-Raphson validation suite to check AI feasibility against actual physical KCL/KVL laws.
* **Switchable Relaxation:** Choose between `relax='SOCP'` for fast radial networks, and `relax='SDP'` (Hermitian Matrix) for complex mesh networks.

---

## 🛠️ Quick Start Guide

### Example: The "One-Click" Fault Analysis Report
Define Sequence Impedances ($X_d''$, $X_0$) and Transformer configurations (`connection_type`) directly in your `config.yaml`, then run the Ultimate Fault Analyzer.
```python
from fourpace.psys import Grid
from fourpace.fa import analyze_faults

# 1. Load system configurations (includes Sequence Network data)
grid = Grid.load('config.yaml')

# 2. Run Comprehensive Fault Analysis across ALL buses and lines
# Analyzes: 3PH, SLG, LL, DLG, 1OP, 2OP, 3OP
master_report_df = analyze_faults(grid, path="Master_Fault_Report.csv", verbose=0)
```

Output will display a terminal dashboard highlighting the MAX_kA short-circuit current per bus for immediate protective device sizing.

---

### 🔬 Design Philosophy: Minimal Dependencies
4PACE is engineered to be a lightweight, lightning-fast computational core. We strictly limit our core dependencies to 6 essential mathematical and data structures (cvxpy, numpy, scipy, networkx, pandas, pyyaml). No bloated plotting or UI libraries—4PACE generates the raw, uncompromised engineering data, leaving visualization to your preferred downstream dashboards or WebUIs.

---

### 📜 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, transparent, and beneficial to the entire engineering community.

---
