gridpf 0.1.0__tar.gz

gridpf-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,120 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint (pre-commit)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      # Runs every hook from .pre-commit-config.yaml (ruff, ruff-format,
+      # whitespace/eof/yaml/toml checks). The commit-msg-stage commitizen
+      # hook is skipped automatically in --all-files mode.
+      - uses: pre-commit/action@v3.0.1
+
+  typecheck:
+    name: Type check (mypy)
+    runs-on: ubuntu-latest
+    # Required gate: mypy must be clean before merge (see branch protection).
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # setuptools_scm needs full history + tags for the version
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install -e ".[dev]"
+      - run: mypy gridpf
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # setuptools_scm needs full history + tags for the version
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[test]"
+      - run: pytest tests/ --cov=gridpf --cov-report=xml --cov-report=term
+      - uses: actions/upload-artifact@v4
+        if: matrix.python-version == '3.11'
+        with:
+          name: coverage-xml
+          path: coverage.xml
+
+  build:
+    name: Build (sdist + wheel)
+    runs-on: ubuntu-latest
+    needs: [lint, typecheck, test]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install build
+      - run: python -m build
+      - run: pipx run twine check dist/*
+      # Release readiness: the distributable wheel must install into a clean
+      # environment and actually solve a real case — not merely pass metadata
+      # checks. Run from /tmp so `import gridpf` resolves to the INSTALLED
+      # wheel, not the source tree in the workspace.
+      - name: Smoke-test built wheel in a clean environment
+        run: |
+          python -m venv /tmp/smoke-env
+          /tmp/smoke-env/bin/pip install --upgrade pip
+          /tmp/smoke-env/bin/pip install "$(ls dist/*.whl)"
+          cd /tmp
+          /tmp/smoke-env/bin/python - <<'PY'
+          import numpy as np
+          import gridpf
+          from gridpf import PFInput, PFOptions, solve
+
+          print("gridpf version:", gridpf.__version__)
+          # Минимальная 2-узловая сеть: slack(0) — PQ(1) с нагрузкой 0.5+j0.2 p.u.
+          z = 0.02 + 0.06j
+          net = PFInput(
+              n_bus=2, n_branch=1,
+              bus_ids=np.array([10, 11], dtype=np.int64),
+              bus_vn_kv=np.array([110.0, 110.0]),
+              bus_type=np.array([2, 0], dtype=np.int8),
+              slack_idx=0,
+              branch_ids=np.array([100], dtype=np.int64),
+              from_idx=np.array([0], dtype=np.int64),
+              to_idx=np.array([1], dtype=np.int64),
+              branch_r=np.array([z.real]), branch_x=np.array([z.imag]),
+              branch_g=np.zeros(1), branch_b=np.zeros(1),
+              branch_g_from=np.zeros(1), branch_b_from=np.zeros(1),
+              branch_g_to=np.zeros(1), branch_b_to=np.zeros(1),
+              tap_ratio=np.array([1.0]), phase_shift=np.zeros(1),
+              bus_g_shunt=np.zeros(2), bus_b_shunt=np.zeros(2),
+              bus_p_injection=np.array([0.0, -0.5]),
+              bus_q_injection=np.array([0.0, -0.2]),
+          )
+          res = solve(net, PFOptions())
+          assert res.converged, "PF failed to converge on the 2-bus smoke case"
+          print(f"wheel smoke OK - converged={res.converged} "
+                f"it_nr={res.iterations_nr} |V|={np.abs(res.V).round(4).tolist()}")
+          PY
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*

gridpf-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,76 @@
+name: Release
+
+# Publish to PyPI when a version tag is pushed.
+#
+# Versioning is handled by setuptools_scm (the tag IS the version) and tags are
+# created from Conventional Commits with `cz bump` (run locally, then
+# `git push --follow-tags`). This workflow only builds and publishes.
+#
+# Publishing uses PyPI Trusted Publishing (OIDC) — no API token in secrets.
+# One-time setup on PyPI: add this repository as a trusted publisher for the
+# `gridpf` project, workflow `release.yml`, environment `pypi`.
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install build
+      - run: python -m build
+      - run: pipx run twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: GitHub Release
+    # Independent of PyPI publish: depends only on a good build, so a GitHub
+    # Release (with attached artifacts) is created even if the PyPI step is
+    # not yet wired (e.g. before the trusted publisher is configured). Re-run
+    # the publish job separately once PyPI is set up.
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # create the release + upload assets
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # full history so --generate-notes can diff against the previous tag
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - name: Create GitHub Release with auto-generated notes
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "${GITHUB_REF_NAME}" \
+            --title "${GITHUB_REF_NAME}" \
+            --generate-notes \
+            dist/*

gridpf-0.1.0/.gitignore

@@ -0,0 +1,95 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# mypy / ruff / pytype caches
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+.ruff_cache/
+
+# IDE / OS
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+
+# Sensitive
+.env*
+secrets.json
+credentials.json
+*.key
+*.pem
+*.p12
+private_key*
+id_rsa*
+id_dsa*
+id_ecdsa*
+id_ed25519*
+
+# setuptools_scm generated version file
+gridpf/_version.py
+
+# Local settings and Claude memory (not committed)
+.claude/
+
+# One-off debug scripts
+scripts/
+
+# Local-only specs / extracted material
+.specs/

gridpf-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,40 @@
+# Pre-commit hooks for gridpf.
+#
+# Install:
+#   .venv/bin/pip install pre-commit
+#   .venv/bin/pre-commit install
+#
+# The same hooks run in CI (.github/workflows/ci.yml -> pre-commit/action).
+# The ruff version here must match the pin in pyproject.toml ([dev]), otherwise
+# the local hook and CI may diverge on rules.
+
+exclude: '^(tests/test_data/|\.venv/|build/|dist/)'
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-json
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: ['--maxkb=3000']
+      - id: mixed-line-ending
+        args: ['--fix=lf']
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.12
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v4.10.0
+    hooks:
+      - id: commitizen
+        stages: [commit-msg]

gridpf-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+Releases are cut from Conventional Commits via `cz bump`; the git tag is the
+authoritative version (`setuptools_scm`).
+
+## [Unreleased]
+
+### Added
+
+- Initial public release: pure-Python Power Flow engine (`gridpf`) extracted from
+  the eris-pf adapter.
+  - Opaque per-unit data contract `PFInput` / `PFOptions` / `PFResult`
+    (`gridpf.contract`), versioned (`CONTRACT_VERSION`) with `.npz` serialization.
+  - Model-free `solve(net, options, *, init_v=None)`: Gauss-Seidel warm-start +
+    Newton-Raphson with optional Q-limit outer loop, DC and soft fallbacks,
+    polynomial voltage-dependent load (СХН), warm-start, and controllable-bus
+    setpoints (`bus_v_set` / `bus_va_set`) clamped over the start vector.
+  - Power-flow numerics adapted from pandapower / PYPOWER (BSD 3-Clause; see
+    LICENSE).

gridpf-0.1.0/LICENSE

@@ -0,0 +1,93 @@
+MIT License
+
+Copyright (c) 2026 Evgeny Istomin
+
+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.
+
+================================================================================
+THIRD-PARTY SOFTWARE NOTICES
+================================================================================
+
+This project contains code adapted from the open-source projects listed below.
+The adapted code retains the original copyright notice as required by its
+license.
+
+--------------------------------------------------------------------------------
+pandapower / PYPOWER
+--------------------------------------------------------------------------------
+
+The power-flow numerics are adapted from pandapower, which in turn bundles
+PYPOWER (a port of MATPOWER, PSERC). Both are distributed under the BSD 3-Clause
+License (full text below).
+
+Copyright (c) 2016-2025 by University of Kassel and Fraunhofer Institute for
+Energy Economics and Energy System Technology (IEE), Kassel. All rights
+reserved. (pandapower)
+
+Copyright (c) 1996-2015, PSERC, and individual contributors (PYPOWER / MATPOWER).
+
+Upstream: https://github.com/e2nIEE/pandapower
+          https://github.com/rwl/PYPOWER
+
+Files adapted from pandapower / PYPOWER into this project:
+
+    pandapower/pypower/makeYbus.py
+        -> gridpf/algebra/ybus.py            (Ybus / Yf / Yt assembly)
+    pandapower/pypower/dSbus_dV.py
+        -> gridpf/algebra/jacobian.py        (power-mismatch Jacobian blocks)
+    pandapower/pypower/newtonpf.py
+        -> gridpf/solvers/newton_raphson.py  (Newton-Raphson iteration)
+    pandapower/pypower/gausspf.py
+        -> gridpf/solvers/gauss_seidel.py    (Gauss-Seidel warm-start)
+    pandapower/pypower/dcpf.py
+        -> gridpf/solvers/dc_pf.py           (DC power-flow warm-start)
+
+Adaptation summary: the PYPOWER layer (ppc_conversion, idx_bus, idx_brch,
+ppoption) was removed; the code operates on this project's own opaque per-unit
+contract (gridpf/contract/types.py::PFInput) instead of the PYPOWER case format,
+and carries no print side effects.
+
+BSD 3-Clause License
+....................
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from this
+   software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

gridpf-0.1.0/Makefile

@@ -0,0 +1,83 @@
+# Makefile for gridpf
+
+VENV := .venv
+PYTHON := python3
+ifeq ($(OS),Windows_NT)
+    VENV_BIN := $(VENV)/Scripts
+else
+    VENV_BIN := $(VENV)/bin
+endif
+VENV_PYTHON := $(VENV_BIN)/python
+VENV_PIP := $(VENV_BIN)/pip
+
+HAS_VENV := $(shell test -d $(VENV) && echo 1 || echo 0)
+
+.PHONY: help venv check-venv install install-dev test test-cov lint format type-check clean build setup
+
+venv:
+	@echo "Creating virtual environment..."
+	$(PYTHON) -m venv $(VENV)
+	$(VENV_PIP) install --upgrade pip setuptools wheel
+	@echo "Activate it: source $(VENV_BIN)/activate"
+
+check-venv:
+ifeq ($(HAS_VENV),0)
+	@echo "Virtual environment not found. Create it: make venv"
+	@exit 1
+endif
+
+install: check-venv
+	$(VENV_PIP) install -e .
+
+install-dev: check-venv
+	$(VENV_PIP) install -e ".[dev,test]"
+	$(VENV_BIN)/pre-commit install
+
+test: check-venv
+	$(VENV_BIN)/pytest tests/ -v
+
+test-cov: check-venv
+	$(VENV_BIN)/pytest tests/ -v --cov=gridpf --cov-report=html --cov-report=term
+
+lint: check-venv
+	$(VENV_BIN)/ruff check gridpf tests
+	$(VENV_BIN)/ruff format --check gridpf tests
+
+format: check-venv
+	$(VENV_BIN)/ruff format gridpf tests
+	$(VENV_BIN)/ruff check --fix gridpf tests
+
+type-check: check-venv
+	$(VENV_BIN)/mypy gridpf
+
+clean:
+	rm -rf build/ dist/ *.egg-info
+	rm -rf .coverage htmlcov/ .pytest_cache/ .mypy_cache/ .ruff_cache/
+	find . -type d -name __pycache__ -not -path './.venv/*' -exec rm -rf {} +
+	find . -type f -name "*.pyc" -not -path './.venv/*' -delete
+
+build: check-venv
+	$(VENV_PYTHON) -m build
+
+check: format lint type-check test
+	@echo "All checks passed."
+
+setup:
+	@$(MAKE) venv
+	@$(MAKE) install-dev
+	@echo "Environment ready. Activate it: source $(VENV_BIN)/activate"
+
+help:
+	@echo "Available targets:"
+	@echo "  make setup        Full setup for a new developer"
+	@echo "  make venv         Create the virtual environment"
+	@echo "  make install      Install the package"
+	@echo "  make install-dev  Install with dev/test extras and pre-commit hooks"
+	@echo "  make test         Run the test suite"
+	@echo "  make test-cov     Run tests with a coverage report"
+	@echo "  make lint         Style check (ruff)"
+	@echo "  make format       Auto-format"
+	@echo "  make type-check   Type check (mypy)"
+	@echo "  make check        format + lint + type-check + test"
+	@echo "  make clean        Remove temporary files"
+	@echo "  make build        Build the package"