psforge-grid

Hub data model for the psforge power system analysis ecosystem

Core data models and I/O for power system analysis with LLM-friendly design.

Quick Start

pip install psforge-grid

from psforge_grid import System

# Load from any supported format
system = System.from_raw("ieee14.raw")              # PSS/E RAW
system = System.from_matpower("case14.m")            # MATPOWER
system = System.from_dss("network.dss")              # OpenDSS
system = System.from_json("ieee14.psfg.json")        # psforge JSON
system = System.from_file("case14.m")                # Auto-detect

# Export to any format
system.to_raw("output.raw")
system.to_matpower("output.m")
system.to_json("output.psfg.json")                   # Human/LLM-friendly
system.to_file("output.m")                           # Auto-detect

# Explore the system
print(f"Buses: {len(system.buses)}, Branches: {len(system.branches)}")
print(system.to_summary())

# Or use the CLI
psforge-grid info ieee14.raw
psforge-grid show case14.m buses -f json

Why psforge-grid?

Overview

psforge-grid serves as the Hub of the psforge ecosystem, providing:

• Common data classes (System, Bus, Branch, Generator, GeneratorCost, Load, Shunt)
• Diagram data (DiagramData, BusPosition, BranchRoute) for single-line diagram layouts and GIS coordinates
• Parsers & Writers for 7 formats (see Supported Formats)
• Factory pattern: ParserFactory / WriterFactory for format-agnostic I/O
• Scenario loading: Base case + differential modifications for N-1 / parametric studies
• OPF data support (GeneratorCost with polynomial and piecewise-linear cost models)
• Zero-sequence impedance and generator machine parameters for fault/stability analysis

Supported Formats

system = System.from_matpower("pglib_opf_case14_ieee.m")
for cost in system.generator_costs:
    print(cost.to_description())
    # "Generator Cost (polynomial, degree 2): 0.0430 * P^2 + 20.00 * P + 0.00"

# Export / Import
system.to_json("ieee14.psfg.json")
system = System.from_json("ieee14.psfg.json")

# Include all fields (with null values)
system.to_json("full.psfg.json", omit_none=False)

from psforge_grid.io import load_scenarios, write_scenario

# Define scenarios
write_scenario(
    "contingencies.psfg.json",
    base_case="ieee14.psfg.json",
    scenarios=[
        {
            "name": "N-1_Line_1-5",
            "modifications": [
                {"target": "branches", "match": {"from_bus": 1, "to_bus": 5},
                 "set": {"status": 0}}
            ]
        },
    ],
)

# Load: returns {"base": System, "N-1_Line_1-5": System, ...}
scenarios = load_scenarios("contingencies.psfg.json")

LLM Affinity Design

"Pickaxe in the Gold Rush" - psforge is designed for seamless LLM integration.

bus = system.get_bus(14)
print(bus.to_description())
# Output: "Bus 14 (LOAD_BUS): 13.8 kV, PQ type"

CLI for LLM Integration

psforge-grid info ieee14.raw              # Table format
psforge-grid info ieee14.raw -f json      # JSON for API/LLM
psforge-grid info ieee14.raw -f summary   # Compact for tokens
psforge-grid show ieee14.raw buses -f json
psforge-grid validate ieee14.raw --strict

Output Formats: table (default), json, summary, csv

See CLAUDE.md for detailed AI development guidelines.

Installation

pip install psforge-grid

# Or install from source
pip install -e .

Development

See docs/development.md for full setup instructions (pre-commit hooks, editor config, etc.).

pip install -e ".[dev]"     # Install dev dependencies
pytest tests/ -v            # Run tests
ruff check src/ tests/      # Lint
mypy src/                   # Type check

psforge Ecosystem (Hub & Spoke Architecture)

                    ┌──────────────────────┐
                    │    psforge-grid      │
                    │   (Hub: Data & I/O)  │
                    └──────────┬───────────┘
                               │
     ┌─────────────┬───────────┼───────────┬─────────────┐
     │             │           │           │             │
┌────▼────┐  ┌────▼────┐ ┌────▼─────┐ ┌───▼────┐  ┌────▼────┐
│ psforge │  │ psforge │ │ psforge- │ │psforge-│  │ psforge │
│  -flow  │  │ -fault  │ │stability │ │schedule│  │ -turbo  │
│ (Power  │  │ (Fault  │ │(Transient│ │ (Unit  │  │  (C++   │
│  Flow)  │  │Analysis)│ │Stability)│ │Commit.)│  │ Engine) │
└─────────┘  └─────────┘ └──────────┘ └────────┘  └─────────┘

All packages are developed and maintained by Manabe Lab LLC.

Contributing

To maintain the ability to offer commercial licenses and ensure the long-term sustainability of this project, we do not accept external code contributions (Pull Requests) at this time.

We still highly value your feedback — please feel free to open Issues for bug reports and feature suggestions.

License

This software is provided under a dual-licensing model:

• Individual & Educational Use: MIT License (students, researchers, non-commercial educational purposes)
• Commercial & Business Use: Requires a Commercial License

This covers the software — src/, the test code, and this documentation — which is what the published package contains. It does not cover the third-party test data in tests/fixtures/, which is other people's copyright and carries its own terms (CC BY 4.0, BSD 3-Clause, and the Texas A&M repository's terms). Those licences already permit commercial use and each requires its attribution to stay with the file; the terms are recorded file by file in tests/fixtures/NOTICE.md.

See LICENSE for details.

Developed by Manabe Lab LLC