powergridforge 1.1.3__tar.gz

powergridforge-1.1.3/.github/workflows/docs.yml

@@ -0,0 +1,25 @@
+name: Publish Docs
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - docs/**
+      - mkdocs.yml
+      - .github/workflows/docs.yml
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install mkdocs mkdocs-material pymdown-extensions
+      - run: mkdocs gh-deploy --force

powergridforge-1.1.3/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.py[codz]
+*$py.class
+*.pyc
+.ipynb_checkpoints/
+.pytest_cache/
+.venv/
+build/
+site/
+# *.xlsx
+14bus_data/
+data/bus_data/
+data/raw_data.zip
+data/Data_public/
+*.egg-info/
+examples/14bus_uc/*.png
+examples/14bus_uc/*.html
+examples/14bus_uc/14bus_data_assignment_resolved.yaml
+.DS_Store
+.codex

powergridforge-1.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wangkun Xu and GridForge contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

powergridforge-1.1.3/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: powergridforge
+Version: 1.1.3
+Summary: Power system configuration and optimization toolkit.
+Author: Wangkun Xu
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=1.5
+Requires-Dist: pyyaml>=6
+Requires-Dist: tqdm>=4.60
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: cvxpy>=1.3
+Requires-Dist: PYPOWER>=5.1
+Requires-Dist: cvxpy-summary>=0.1.2
+Provides-Extra: gurobi
+Requires-Dist: gurobipy; extra == "gurobi"
+Provides-Extra: viz
+Requires-Dist: networkx>=2.8; extra == "viz"
+Requires-Dist: matplotlib>=3.6; extra == "viz"
+Requires-Dist: plotly>=5; extra == "viz"
+Provides-Extra: app
+Requires-Dist: streamlit>=1.28; extra == "app"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.5; extra == "docs"
+Requires-Dist: mkdocs-material>=9; extra == "docs"
+Requires-Dist: pymdown-extensions>=10; extra == "docs"
+Provides-Extra: full
+Requires-Dist: streamlit>=1.28; extra == "full"
+Requires-Dist: networkx>=2.8; extra == "full"
+Requires-Dist: matplotlib>=3.6; extra == "full"
+Requires-Dist: plotly>=5; extra == "full"
+Dynamic: license-file
+
+# GridForge
+
+<p align="center">
+  <img src="docs/image/gridforge.png" alt="GridForge Logo" width="250"/>
+</p>
+
+**GridForge** helps build optimization-ready power-system cases from standard
+PYPOWER/MATPOWER grids. It lets you describe grid edits in YAML, generate a
+structured Excel workbook, attach bus-level time-series data, and load the
+result into Python for your own optimization model.
+
+GridForge is useful when a standard test case is not enough: for example, when
+you need custom assets such as load, solar, wind, or storage, time-series data
+attached to selected buses, and convenient access to the final case in CVXPY.
+
+Read the full documentation at
+[xuwkk.github.io/gridforge](https://xuwkk.github.io/gridforge/).
+
+## Workflow
+
+```text
+base PYPOWER/MATPOWER case
+  -> grid configuration YAML
+  -> generated Excel workbook
+  -> bus-data assignment YAML
+  -> bus_<BUS_IDX>.csv files
+  -> Grid(...) and Data(...) classes for efficient access to the case and data
+  -> user-defined optimization model
+```
+
+The grid configuration YAML can be written manually or created with the visual
+app. The bus-data assignment step is separate because it depends on the
+generated `BUS_IDX` values in the workbook.
+
+## Installation
+
+Install the latest release from PyPI:
+
+```bash
+pip install powergridforge
+```
+
+To run the examples and edit the docs, clone the repository:
+
+```bash
+git clone https://github.com/xuwkk/gridforge.git
+cd gridforge
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[full]"
+```
+
+## What You Need First
+
+GridForge does not invent the grid design automatically. Before constructing a
+case, prepare:
+
+- a **grid configuration YAML** that selects a base case and describes static grid edits, see [configuration.md](docs/configuration.md) for details.
+- a **bus-data assignment YAML** that declares which time-series signals should be mapped to generated buses, see [bus-data-assignment.md](docs/bus-data-assignment.md) for details.
+- source CSV files if you want to materialize time-series data.
+
+For a first run, use the prepared 14-bus example in a source checkout of this
+repository.
+
+## 14-Bus Example
+
+The worked unit-commitment example is in
+[`examples/14bus_uc/`](examples/14bus_uc/).
+
+Important files:
+
+- [`14bus_config.yaml`](examples/14bus_uc/14bus_config.yaml): grid
+  configuration rules.
+- [`14bus_config.xlsx`](examples/14bus_uc/14bus_config.xlsx): generated static
+  workbook.
+- [`14bus_data_assignment.yaml`](examples/14bus_uc/14bus_data_assignment.yaml):
+  bus-data signal template used to generate bus assignments.
+- [`14bus_data/`](examples/14bus_uc/14bus_data/): generated
+  `bus_<BUS_IDX>.csv` files.
+- [`14bus_example.py`](examples/14bus_uc/14bus_example.py): runnable
+  end-to-end example.
+- [`14bus_uc.ipynb`](examples/14bus_uc/14bus_uc.ipynb): interactive notebook
+  for inspecting the case, data, topology, and UC model setup.
+
+Run the example from the repository root:
+
+```bash
+python examples/14bus_uc/14bus_example.py
+```
+
+Or open the notebook:
+
+```bash
+jupyter lab examples/14bus_uc/14bus_uc.ipynb
+```
+
+The same workflow can be called from Python:
+
+```python
+from gridforge.construct import construct_grid_config
+from gridforge.data import (
+    load_bus_data_assignment,
+    prepare_bus_data,
+)
+from gridforge.opt import Grid, Data
+
+config_yaml = "examples/14bus_uc/14bus_config.yaml"
+config_xlsx = "examples/14bus_uc/14bus_config.xlsx"
+assignment_yaml = "examples/14bus_uc/14bus_data_assignment.yaml"
+resolved_assignment_yaml = "examples/14bus_uc/14bus_data_assignment_resolved.yaml"
+data_dir = "examples/14bus_uc/14bus_data"
+source_data_dir = "data/bus_data"
+
+construct_grid_config(config_yaml, config_xlsx, random_seed=404)
+
+assignment_template = load_bus_data_assignment(assignment_yaml)
+assignment, _ = prepare_bus_data(
+    grid_xlsx_path=config_xlsx,
+    source_data_dir=source_data_dir,
+    signals=assignment_template["signals"],
+    output_data_dir=data_dir,
+    resolved_assignment_path=resolved_assignment_yaml,
+    random_seed=404,
+)
+
+grid = Grid(config_xlsx, verbose=0)
+data = Data(
+    grid_xlsx_path=config_xlsx,
+    data_dir=data_dir,
+    sheet_names=["load", "solar", "wind"],
+)
+
+print(grid.gen.pmax)
+print(grid.branch.ptdf.shape)
+print(grid.load.Cbus.shape)
+print(data.get_series("load").shape)
+```
+
+## Visual Config App
+
+The visual app helps create and inspect the grid configuration YAML used in the
+first stage.
+
+<p align="center">
+  <img src="docs/image/visual-app/overview.png" alt="GridForge Visual Config App" width="850"/>
+</p>
+
+Launch it after installing the app dependencies, for example with
+`pip install -e ".[full]"` from a source checkout:
+
+```bash
+gridforge-app
+```
+
+From a local checkout:
+
+```bash
+streamlit run gridforge/config_app.py
+```
+
+## Documentation
+
+The published documentation is available at
+[xuwkk.github.io/gridforge](https://xuwkk.github.io/gridforge/).
+
+- [Workflow](https://xuwkk.github.io/gridforge/workflow/): complete YAML -> Excel -> bus data -> Python
+  pipeline.
+- [Visual config app](https://xuwkk.github.io/gridforge/visual-app/): Streamlit builder for grid YAML.
+- [Configuration reference](https://xuwkk.github.io/gridforge/configuration/): GridForge YAML schema.
+- [Bus-data assignment](https://xuwkk.github.io/gridforge/bus-data-assignment/): assign source CSV
+  profiles to generated buses.
+- [Grid and Data access](https://xuwkk.github.io/gridforge/grid-data-access/): entries exposed by
+  `Grid(...)` and `Data(...)`.
+- [TX-123BT workflow](https://xuwkk.github.io/gridforge/tx123bt/): optional public source-data
+  preparation.
+- [Examples](https://xuwkk.github.io/gridforge/examples/): runnable examples included in this repository.
+
+The source Markdown files for the site live in [`docs/`](docs/).

powergridforge-1.1.3/docs/bus-data-assignment.md

@@ -0,0 +1,187 @@
+# Bus Data Assignment
+
+> The visual app currently helps build the static grid YAML. Bus-data assignment
+> is handled by this YAML/Python workflow. TX-123BT is one optional source-data
+> example; see [tx123bt.md](tx123bt.md).
+
+GridForge separates static grid construction from time-series assignment.
+
+The grid workbook decides which assets exist and which generated buses they are
+attached to. A bus-data assignment file then decides which source CSV profile is
+used for each generated bus that needs data.
+
+This step happens after the Excel workbook has been generated. The assignment
+tools read the workbook to discover which generated `BUS_IDX` values need data.
+The output CSV files can contain more than asset profiles. For example, a bus
+CSV may also contain calendar, weather, or other contextual columns.
+
+## Assignment File
+
+An assignment template has three parts:
+
+- where to find candidate source CSV files as `source_data_dir`,
+- which signals require time-series columns as `signals`,
+- optionally, where GridForge should write case-specific bus CSV files as
+  `output_data_dir`.
+
+```yaml
+source_data_dir: data/bus_data
+output_data_dir: examples/14bus_uc/14bus_data
+signals:
+  load:
+    workbook_sheet: load   # the data is related to the load sheet in the workbook
+    source_column: load    # the column name in the source CSV file that contains the time-series data for the load
+    output_column: load    # the column name in the output CSV file that contains the time-series data for the load
+    scale_to:
+      column: PMAX
+      method: max
+  solar:
+    workbook_sheet: solar
+    source_column: solar
+    output_column: solar
+    scale_to:
+      column: PMAX
+      method: max
+  wind:
+    workbook_sheet: wind
+    source_column: wind
+    output_column: wind
+    scale_to:
+      column: PMAX
+      method: max
+```
+
+This template is not yet materializable because it does not say which generated
+bus should use which source file. Use `prepare_bus_data(...)` after the workbook
+exists to produce a resolved assignment with a `buses` mapping and materialize
+the case-specific bus CSVs.
+
+## What The User Provides
+
+The user controls:
+
+- `source_data_dir`: directory of candidate source CSV files. Each file is a
+  time-series table with shape `(T, n_features)`, where rows are time steps and
+  columns are signals or context features such as `load`, `solar`, `wind`,
+  weather, or calendar fields.
+- `output_data_dir`: directory where GridForge writes the case-specific
+  `bus_<BUS_IDX>.csv` files.
+- `signals`: named time-series signals. Each signal states which workbook sheet
+  supplies required `BUS_IDX` values, which source CSV column to read, and which
+  output CSV column to write.
+- `buses`: optional mapping from generated GridForge `BUS_IDX` values to source
+  CSV filenames. In the common workflow this is generated by `prepare_bus_data(...)`
+  after the workbook exists. See [Prepare Bus Data](#prepare-bus-data) for more details.
+
+## How Required Buses Are Found
+
+GridForge does not assume that every custom sheet needs time-series data. Only
+sheets referenced by `signals.<name>.workbook_sheet` are data-backed.
+
+For each signal, GridForge reads `BUS_IDX` from the referenced workbook sheet.
+The union of those bus IDs becomes the set of buses that need source CSV
+assignments.
+
+## Scaling
+
+For a signal like:
+
+```yaml
+load:
+  workbook_sheet: load
+  source_column: load
+  output_column: load
+  scale_to:
+    column: PMAX
+    method: max
+```
+
+GridForge:
+
+1. reads the assigned source CSV's `load` column,
+2. finds the generated bus's `load.PMAX` value in the workbook,
+3. scales the source profile so `max(load)` equals `PMAX`,
+4. writes the scaled profile into the case-specific output CSV.
+
+The current scaling method is `max`. This matches the peak of the source profile
+to a static workbook value such as peak demand or installed capacity.
+
+> More options will be supported in the future.
+
+`scale_to` uses the signal's `workbook_sheet` by default.
+
+## Prepare Bus Data
+
+The user can use `prepare_bus_data(...)` to generate a resolved assignment,
+optionally save it, and write the case-specific `bus_<BUS_IDX>.csv` files. A
+complete example is shown below:
+
+```python
+from gridforge.data import prepare_bus_data
+
+# Assignment config without buses mapping
+signals = {
+    "load": {
+        "workbook_sheet": "load",
+        "source_column": "load",
+        "output_column": "load",
+        "scale_to": {"column": "PMAX", "method": "max"},
+    },
+    "solar": {
+        "workbook_sheet": "solar",
+        "source_column": "solar",
+        "output_column": "solar",
+        "scale_to": {"column": "PMAX", "method": "max"},
+    },
+    "wind": {
+        "workbook_sheet": "wind",
+        "source_column": "wind",
+        "output_column": "wind",
+        "scale_to": {"column": "PMAX", "method": "max"},
+    },
+}
+
+# GridForge suggests a mapping and materializes the required bus CSVs.
+assignment, materialized = prepare_bus_data(
+    grid_xlsx_path="examples/14bus_uc/14bus_config.xlsx",
+    source_data_dir="data/bus_data",
+    signals=signals,
+    output_data_dir="examples/14bus_uc/14bus_data",
+    resolved_assignment_path="examples/14bus_uc/14bus_data_assignment_resolved.yaml",
+    random_seed=404,
+)
+```
+
+## Materialize A Saved Assignment
+
+If you want to inspect or edit a resolved assignment before writing bus CSVs, use
+the lower-level `suggest_bus_data_assignment(...)` and
+`materialize_bus_data_assignment(...)` helpers separately.
+
+```python
+from gridforge.data import materialize_bus_data_assignment
+
+materialize_bus_data_assignment(
+    grid_xlsx_path="examples/14bus_uc/14bus_config.xlsx",
+    assignment_path="examples/14bus_uc/14bus_data_assignment_resolved.yaml",
+    output_data_dir="examples/14bus_uc/14bus_data",
+)
+```
+
+This reads the assigned source files, _scales_ requested columns when configured,
+and writes files such as:
+
+```text
+examples/14bus_uc/14bus_data/bus_2.csv
+examples/14bus_uc/14bus_data/bus_3.csv
+examples/14bus_uc/14bus_data/bus_8.csv
+```
+
+The output filenames use generated GridForge bus IDs. The source files can come
+from any CSV pool that contains the required columns.
+
+## Next Step
+
+After materialization, load the generated `bus_<BUS_IDX>.csv` files with
+`Data(...)`. For sheet-backed profile matrices and contextual CSV columns, see
+[Grid And Data Access](grid-data-access.md#5-time-series-data-data).