scr-screen 0.1.0__tar.gz

scr_screen-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shaibu Ibrahim, P.E.
+
+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.

scr_screen-0.1.0/PKG-INFO

@@ -0,0 +1,273 @@
+Metadata-Version: 2.4
+Name: scr-screen
+Version: 0.1.0
+Summary: Short-circuit ratio (SCR/WSCR) screening for inverter-based resource interconnection
+Author-email: "Shaibu Ibrahim, P.E." <ishaibu136@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ishaibu/scr-screen
+Project-URL: Documentation, https://github.com/ishaibu/scr-screen#readme
+Project-URL: Issues, https://github.com/ishaibu/scr-screen/issues
+Project-URL: Changelog, https://github.com/ishaibu/scr-screen/blob/main/CHANGELOG.md
+Keywords: power-systems,short-circuit-ratio,grid-interconnection,inverter-based-resources
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandapower>=3.5
+Requires-Dist: openpyxl
+Requires-Dist: xlsxwriter
+Requires-Dist: matpowercaseframes
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Provides-Extra: notebook
+Requires-Dist: ipykernel; extra == "notebook"
+Dynamic: license-file
+
+# SCR-Screen
+
+[![tests](https://github.com/ishaibu/scr-screen/actions/workflows/tests.yml/badge.svg)](https://github.com/ishaibu/scr-screen/actions/workflows/tests.yml)
+![Python](https://img.shields.io/badge/python-3.10%E2%80%933.13-blue)
+![License: MIT](https://img.shields.io/badge/license-MIT-green)
+
+**Open-source short-circuit ratio (SCR) screening for solar, wind, and battery storage interconnection.**
+
+SCR-Screen helps interconnection, planning, and siting engineers find weak-grid locations **early**, before detailed studies are commissioned. It calculates short-circuit strength from a network model, screens single plants (SCR) and groups of nearby plants (WSCR), and produces a clear, self-contained HTML report.
+
+> **Screening only.** SCR-Screen provides screening-level indicators of system strength. Results do not replace interconnection studies, detailed positive-sequence or EMT analysis, or the requirements of the applicable transmission provider.
+
+---
+
+## Why use it
+
+The SCR formula is simple. Getting a trustworthy answer is not:
+
+- **Short-circuit MVA must come from the network, calculated consistently.** SCR-Screen computes it from a model, excludes inverter-based resource (IBR) contributions as NERC requires, and states the method used.
+- **Nearby plants share grid strength.** Two plants that each pass alone can be weak together. SCR-Screen screens groups with WSCR and shows the difference side by side.
+- **Siting needs every location, not one.** The bus scan ranks every bus in a model for a plant of a given size.
+- **Method choice changes answers.** SCR-Screen supports both the classical flat-start method (common U.S. planning practice) and IEC 60909, and records which one produced each result.
+- **Transparent and reproducible.** Open formulas, documented assumptions, automated tests, and a public [verification record](docs/verification.md).
+
+## Features (v0.1)
+
+| Feature | Details |
+|---|---|
+| SCR | Single plant at its point of interconnection (POI) |
+| WSCR | Groups of plants assumed fully interacting (ERCOT/NERC formulation) |
+| Rating basis | MW (default) or MVA |
+| Short-circuit methods | Classical flat-start (1.0 pu) and IEC 60909 (via pandapower) |
+| Bus scan | SCR at every bus of a network for a hypothetical plant size |
+| Flags | Very weak / weak / no flag, with user-configurable thresholds |
+| Network map | Grid drawn from bus coordinates (or an automatic layout), colored and animated by SCR flag |
+| Plant-size slider | In scan reports, drag to any plant size; every SCR, flag, chart and the map update instantly in the browser |
+| Max plant size | Largest plant each location can host before a weak flag (SCMVA ÷ weak threshold) |
+| Method comparison | Classical vs IEC 60909 for every bus, highlighting where the flag changes |
+| Cost screening | Ranks candidate buses by screening-level cost: synchronous condenser to fix weak grid, gen-tie line, POI substation (all costs are your inputs) |
+| Your own network | Reads pandapower JSON, Excel (.xlsx), and MATPOWER (.m/.mat); `check` lists anything missing before you scan |
+| Outputs | Self-contained HTML report (works offline), CSV, JSON |
+| Interfaces | Command line (`scr-screen`) and Python API |
+
+## Try it without installing
+
+- **[SCR-Screen Lite](https://ishaibu.github.io/scr-screen/lite/)**: browser calculator. Type each plant's short-circuit MVA and MW to get SCR, flags, WSCR, the largest plant before a weak flag, and condenser cost. Runs entirely in your browser.
+- **[Interactive demo report](https://ishaibu.github.io/scr-screen/demo/)**: a full IEEE 39-bus scan (assumed data, illustrative costs). Drag the plant-size slider and change the inputs.
+
+## Installation
+
+Requires Python 3.10 or newer.
+
+```bash
+python -m venv venv
+# Windows:  venv\Scripts\activate      macOS/Linux:  source venv/bin/activate
+pip install scr-screen
+```
+
+From source (for contributors):
+
+```bash
+git clone https://github.com/ishaibu/scr-screen.git
+cd scr-screen
+pip install -e ".[dev]"
+```
+
+## Quick start (command line)
+
+**Try it in one minute** with the bundled IEEE 39-bus example:
+
+```bash
+scr-screen example                      # copies example files into ./scr-screen-example
+cd scr-screen-example
+scr-screen scan ieee39_assumed.json --plant-mw 1500 --report scan.html --open
+```
+
+**Direct mode:** you already have short-circuit MVA values (from any study tool).
+
+```bash
+scr-screen template plants.csv          # creates an input file with example rows
+scr-screen run plants.csv --report report.html --out results.csv
+```
+
+**Network mode:** calculate short-circuit MVA from a [pandapower](https://www.pandapower.org/) network saved as JSON, and scan every bus.
+
+```bash
+scr-screen scan examples/ieee39_assumed.json --plant-mw 1500 --report scan.html --open
+scr-screen scan examples/ieee39_assumed.json --plant-mw 1500 --method iec60909
+```
+
+`--open` opens the report in your browser as soon as it is ready.
+
+**What-if inputs:** scan reports have an inputs panel. Change any of these and the whole report (map, charts, tables, cost ranking) recalculates instantly in the browser, with no re-run needed:
+
+- plant size (slider or typed value)
+- weak and very-weak SCR thresholds
+- with cost screening: target SCR, condenser X''d, transformer Xt, condenser $/MVA, gen-tie $/mile, and each candidate bus's gen-tie distance and POI cost (edited directly in the cost table)
+
+**Reset all** returns to the values the report was created with. Invalid entries (e.g. 0 MW) are flagged and ignored.
+
+Run `scr-screen --help` or `scr-screen run --help` for all options (`--basis MVA`, `--weak`, `--very-weak`, `--title`, `--open`, `--no-compare`).
+
+## Use your own network
+
+SCR-Screen works on any network, not just the IEEE 39-bus example.
+
+| File type | Extension | Notes |
+|---|---|---|
+| pandapower JSON | `.json` | Native format |
+| pandapower Excel | `.xlsx` | Edit in Excel: one sheet per element type (bus, line, trafo, gen, ext_grid, ...) |
+| MATPOWER | `.m`, `.mat` | Converted on load; MATPOWER has no short-circuit data, so add it (below) |
+
+**Short-circuit data needed:**
+- Grid sources (`ext_grid`): `s_sc_max_mva` and `rx_max`.
+- Synchronous generators (`gen`): `xdss_pu` (X''d on machine base) and `sn_mva`. IEC 60909 also needs `vn_kv`, `rdss_ohm`, and `cos_phi`.
+
+**Workflow:**
+
+```bash
+scr-screen check mynetwork.m                 # lists exactly what is missing
+scr-screen convert mynetwork.m mynetwork.xlsx  # open in Excel, fill in the empty short-circuit columns
+scr-screen check mynetwork.xlsx              # "Ready for Classical: yes"
+scr-screen scan mynetwork.xlsx --plant-mw 300 --report scan.html --open
+```
+
+Buses with no path to any source are skipped and listed in the report. PSS/E `.raw` import is planned.
+
+## Interconnection cost screening
+
+For a plant of a given size, SCR-Screen estimates a screening-level cost of connecting at each candidate bus:
+
+- **Target check:** buses below your target SCR are flagged, with the largest plant that meets the target (`SCMVA ÷ target SCR`) and the condenser alternative.
+- **Weak-grid mitigation:** synchronous condenser size to reach a target SCR (default: the weak threshold),
+  `condenser MVA = max(0, plant MW × target SCR − SCMVA) × (X''d + Xt)`, assuming the condenser is at the POI.
+- **Gen-tie line:** distance × your cost per mile.
+- **POI substation or switching station:** your cost per bus.
+
+```bash
+scr-screen sites-template mynetwork.xlsx sites.csv   # list of buses; fill in distance_mi, poi_cost_usd
+scr-screen scan mynetwork.xlsx --plant-mw 1500 --report scan.html --site-costs sites.csv \
+    --condenser-cost-per-mva 100000 --gen-tie-cost-per-mile 2000000 --cost-out costs.csv
+```
+
+The numbers above and in `examples/ieee39_sites_example.csv` are **illustrative only**. SCR-Screen ships no cost data; enter your own. In the report, every cost input is editable and the ranking updates instantly, so you can see the cheapest bus change as the plant grows or as costs change.
+
+> Cost screening excludes network upgrades (thermal, voltage, stability), which are often the largest interconnection cost and require power flow and interconnection-queue studies. Grid-forming inverters may mitigate weak-grid conditions at lower cost and are not costed.
+
+## Input format (direct mode)
+
+One row per plant. Column order and capitalization do not matter; files saved from Excel as **CSV UTF-8** work.
+
+| Column | Required | Description |
+|---|---|---|
+| `plant_id` | Yes | Unique label |
+| `scmva` | Yes | Three-phase short-circuit MVA at the POI, **without** IBR contribution |
+| `rating_mw` | Yes | Plant rating in MW |
+| `rating_mva` | No | Plant rating in MVA (needed only for `--basis MVA`) |
+| `group` | No | Plants sharing a group are also screened together with WSCR |
+| `poi_name` | No | Display name of the POI |
+
+Numbers must use a dot for decimals and no thousands separators (e.g. `1000`, `485.86`). Values with commas are rejected rather than guessed.
+
+## Python API
+
+```python
+from scr_screen.metrics import scr, wscr
+from scr_screen.io import read_plants_csv
+from scr_screen.screening import screen
+from scr_screen.report import write_html_report
+
+scr(500, 100)                          # 5.0
+wscr([1000, 600], [200, 100])          # 2.889
+
+plants, poi = read_plants_csv("plants.csv")
+result = screen(plants, poi_names=poi)
+write_html_report(result, "report.html")
+```
+
+Network mode:
+
+```python
+import pandapower as pp
+from scr_screen.network import scan_buses
+
+net = pp.from_json("network.json")
+for row in scan_buses(net, plant_mw=300, method="classical"):
+    print(row.bus, row.name, round(row.scr, 2), row.flag)
+```
+
+See [`examples/walkthrough.ipynb`](examples/walkthrough.ipynb) for a step-by-step tour.
+
+## Methods
+
+**SCR** = SCMVA ÷ plant rating
+**WSCR** = Σ(SCMVAᵢ × Pᵢ) ÷ (ΣPᵢ)²
+
+| Short-circuit method | Pre-fault voltage | Correction factors | Typical use |
+|---|---|---|---|
+| Classical flat-start (default) | 1.0 pu | None | Common U.S. planning practice |
+| IEC 60909 (max case) | c = 1.1 | Generator and transformer impedance correction | IEC practice |
+
+In both methods, inverter-based resources do not contribute to SCMVA.
+
+**Default flag bands** (user-configurable): below 2 **very weak**; 2 to below 3 **weak**; 3 or above **no flag**. These follow HVDC planning practice (IEEE Std 1204-1997). There is no universal weak-grid threshold.
+
+Full details: [design specification](docs/design-spec.md).
+
+## Limitations
+
+- SCR-based metrics assume **grid-following** inverters and do not replace the inverter manufacturer's minimum SCR.
+- WSCR assumes the plants in a group are fully interacting.
+- The classical method (v0.1) ignores loads, shunts, and line charging, uses nominal transformer taps, and does not yet model three-winding transformers or closed bus-bus switches. Unsupported elements stop the calculation with a clear error rather than being ignored.
+- Real transmission models are often restricted (e.g. CEII in the U.S.). SCR-Screen ships only public test data; users run it on their own models.
+- Cost screening is screening-level only and excludes network upgrades; all costs are user inputs.
+
+## Verification
+
+Every formula is covered by automated tests with hand-calculated expected values, run on each change. Independent engineering checks are recorded in [`docs/verification.md`](docs/verification.md).
+
+## Roadmap
+
+- **v0.2:** PSS/E `.raw` import, N-1 contingency worst case, generator retirement scenarios, interconnection-queue build-out, composite SCR (CSCR)
+- **v0.3:** mitigation sizing (e.g. synchronous condenser MVA needed), SCR with interaction factors (SCRIF)
+
+## Feedback and contributions
+
+Found a bug, have a question, or use SCR-Screen in your work? Please [open an issue](https://github.com/ishaibu/scr-screen/issues). Feedback from utility, ISO/RTO, developer, and consulting engineers is especially welcome.
+
+## References
+
+1. NERC, *Integrating Inverter-Based Resources into Low Short Circuit Strength Systems*, Reliability Guideline, December 2017.
+2. NERC, *Short-Circuit Modeling and System Strength*, White Paper, February 2018.
+3. Y. Zhang et al., "Evaluating system strength for large-scale wind plant integration," IEEE PES General Meeting, 2014.
+4. IEEE Std 1204-1997, *IEEE Guide for Planning DC Links Terminating at AC Locations Having Low Short-Circuit Capacities*.
+5. IEC 60909-0, *Short-circuit currents in three-phase a.c. systems*.
+
+## License and author
+
+MIT License. Created and maintained by **Shaibu Ibrahim, P.E.**

scr_screen-0.1.0/README.md

@@ -0,0 +1,239 @@
+# SCR-Screen
+
+[![tests](https://github.com/ishaibu/scr-screen/actions/workflows/tests.yml/badge.svg)](https://github.com/ishaibu/scr-screen/actions/workflows/tests.yml)
+![Python](https://img.shields.io/badge/python-3.10%E2%80%933.13-blue)
+![License: MIT](https://img.shields.io/badge/license-MIT-green)
+
+**Open-source short-circuit ratio (SCR) screening for solar, wind, and battery storage interconnection.**
+
+SCR-Screen helps interconnection, planning, and siting engineers find weak-grid locations **early**, before detailed studies are commissioned. It calculates short-circuit strength from a network model, screens single plants (SCR) and groups of nearby plants (WSCR), and produces a clear, self-contained HTML report.
+
+> **Screening only.** SCR-Screen provides screening-level indicators of system strength. Results do not replace interconnection studies, detailed positive-sequence or EMT analysis, or the requirements of the applicable transmission provider.
+
+---
+
+## Why use it
+
+The SCR formula is simple. Getting a trustworthy answer is not:
+
+- **Short-circuit MVA must come from the network, calculated consistently.** SCR-Screen computes it from a model, excludes inverter-based resource (IBR) contributions as NERC requires, and states the method used.
+- **Nearby plants share grid strength.** Two plants that each pass alone can be weak together. SCR-Screen screens groups with WSCR and shows the difference side by side.
+- **Siting needs every location, not one.** The bus scan ranks every bus in a model for a plant of a given size.
+- **Method choice changes answers.** SCR-Screen supports both the classical flat-start method (common U.S. planning practice) and IEC 60909, and records which one produced each result.
+- **Transparent and reproducible.** Open formulas, documented assumptions, automated tests, and a public [verification record](docs/verification.md).
+
+## Features (v0.1)
+
+| Feature | Details |
+|---|---|
+| SCR | Single plant at its point of interconnection (POI) |
+| WSCR | Groups of plants assumed fully interacting (ERCOT/NERC formulation) |
+| Rating basis | MW (default) or MVA |
+| Short-circuit methods | Classical flat-start (1.0 pu) and IEC 60909 (via pandapower) |
+| Bus scan | SCR at every bus of a network for a hypothetical plant size |
+| Flags | Very weak / weak / no flag, with user-configurable thresholds |
+| Network map | Grid drawn from bus coordinates (or an automatic layout), colored and animated by SCR flag |
+| Plant-size slider | In scan reports, drag to any plant size; every SCR, flag, chart and the map update instantly in the browser |
+| Max plant size | Largest plant each location can host before a weak flag (SCMVA ÷ weak threshold) |
+| Method comparison | Classical vs IEC 60909 for every bus, highlighting where the flag changes |
+| Cost screening | Ranks candidate buses by screening-level cost: synchronous condenser to fix weak grid, gen-tie line, POI substation (all costs are your inputs) |
+| Your own network | Reads pandapower JSON, Excel (.xlsx), and MATPOWER (.m/.mat); `check` lists anything missing before you scan |
+| Outputs | Self-contained HTML report (works offline), CSV, JSON |
+| Interfaces | Command line (`scr-screen`) and Python API |
+
+## Try it without installing
+
+- **[SCR-Screen Lite](https://ishaibu.github.io/scr-screen/lite/)**: browser calculator. Type each plant's short-circuit MVA and MW to get SCR, flags, WSCR, the largest plant before a weak flag, and condenser cost. Runs entirely in your browser.
+- **[Interactive demo report](https://ishaibu.github.io/scr-screen/demo/)**: a full IEEE 39-bus scan (assumed data, illustrative costs). Drag the plant-size slider and change the inputs.
+
+## Installation
+
+Requires Python 3.10 or newer.
+
+```bash
+python -m venv venv
+# Windows:  venv\Scripts\activate      macOS/Linux:  source venv/bin/activate
+pip install scr-screen
+```
+
+From source (for contributors):
+
+```bash
+git clone https://github.com/ishaibu/scr-screen.git
+cd scr-screen
+pip install -e ".[dev]"
+```
+
+## Quick start (command line)
+
+**Try it in one minute** with the bundled IEEE 39-bus example:
+
+```bash
+scr-screen example                      # copies example files into ./scr-screen-example
+cd scr-screen-example
+scr-screen scan ieee39_assumed.json --plant-mw 1500 --report scan.html --open
+```
+
+**Direct mode:** you already have short-circuit MVA values (from any study tool).
+
+```bash
+scr-screen template plants.csv          # creates an input file with example rows
+scr-screen run plants.csv --report report.html --out results.csv
+```
+
+**Network mode:** calculate short-circuit MVA from a [pandapower](https://www.pandapower.org/) network saved as JSON, and scan every bus.
+
+```bash
+scr-screen scan examples/ieee39_assumed.json --plant-mw 1500 --report scan.html --open
+scr-screen scan examples/ieee39_assumed.json --plant-mw 1500 --method iec60909
+```
+
+`--open` opens the report in your browser as soon as it is ready.
+
+**What-if inputs:** scan reports have an inputs panel. Change any of these and the whole report (map, charts, tables, cost ranking) recalculates instantly in the browser, with no re-run needed:
+
+- plant size (slider or typed value)
+- weak and very-weak SCR thresholds
+- with cost screening: target SCR, condenser X''d, transformer Xt, condenser $/MVA, gen-tie $/mile, and each candidate bus's gen-tie distance and POI cost (edited directly in the cost table)
+
+**Reset all** returns to the values the report was created with. Invalid entries (e.g. 0 MW) are flagged and ignored.
+
+Run `scr-screen --help` or `scr-screen run --help` for all options (`--basis MVA`, `--weak`, `--very-weak`, `--title`, `--open`, `--no-compare`).
+
+## Use your own network
+
+SCR-Screen works on any network, not just the IEEE 39-bus example.
+
+| File type | Extension | Notes |
+|---|---|---|
+| pandapower JSON | `.json` | Native format |
+| pandapower Excel | `.xlsx` | Edit in Excel: one sheet per element type (bus, line, trafo, gen, ext_grid, ...) |
+| MATPOWER | `.m`, `.mat` | Converted on load; MATPOWER has no short-circuit data, so add it (below) |
+
+**Short-circuit data needed:**
+- Grid sources (`ext_grid`): `s_sc_max_mva` and `rx_max`.
+- Synchronous generators (`gen`): `xdss_pu` (X''d on machine base) and `sn_mva`. IEC 60909 also needs `vn_kv`, `rdss_ohm`, and `cos_phi`.
+
+**Workflow:**
+
+```bash
+scr-screen check mynetwork.m                 # lists exactly what is missing
+scr-screen convert mynetwork.m mynetwork.xlsx  # open in Excel, fill in the empty short-circuit columns
+scr-screen check mynetwork.xlsx              # "Ready for Classical: yes"
+scr-screen scan mynetwork.xlsx --plant-mw 300 --report scan.html --open
+```
+
+Buses with no path to any source are skipped and listed in the report. PSS/E `.raw` import is planned.
+
+## Interconnection cost screening
+
+For a plant of a given size, SCR-Screen estimates a screening-level cost of connecting at each candidate bus:
+
+- **Target check:** buses below your target SCR are flagged, with the largest plant that meets the target (`SCMVA ÷ target SCR`) and the condenser alternative.
+- **Weak-grid mitigation:** synchronous condenser size to reach a target SCR (default: the weak threshold),
+  `condenser MVA = max(0, plant MW × target SCR − SCMVA) × (X''d + Xt)`, assuming the condenser is at the POI.
+- **Gen-tie line:** distance × your cost per mile.
+- **POI substation or switching station:** your cost per bus.
+
+```bash
+scr-screen sites-template mynetwork.xlsx sites.csv   # list of buses; fill in distance_mi, poi_cost_usd
+scr-screen scan mynetwork.xlsx --plant-mw 1500 --report scan.html --site-costs sites.csv \
+    --condenser-cost-per-mva 100000 --gen-tie-cost-per-mile 2000000 --cost-out costs.csv
+```
+
+The numbers above and in `examples/ieee39_sites_example.csv` are **illustrative only**. SCR-Screen ships no cost data; enter your own. In the report, every cost input is editable and the ranking updates instantly, so you can see the cheapest bus change as the plant grows or as costs change.
+
+> Cost screening excludes network upgrades (thermal, voltage, stability), which are often the largest interconnection cost and require power flow and interconnection-queue studies. Grid-forming inverters may mitigate weak-grid conditions at lower cost and are not costed.
+
+## Input format (direct mode)
+
+One row per plant. Column order and capitalization do not matter; files saved from Excel as **CSV UTF-8** work.
+
+| Column | Required | Description |
+|---|---|---|
+| `plant_id` | Yes | Unique label |
+| `scmva` | Yes | Three-phase short-circuit MVA at the POI, **without** IBR contribution |
+| `rating_mw` | Yes | Plant rating in MW |
+| `rating_mva` | No | Plant rating in MVA (needed only for `--basis MVA`) |
+| `group` | No | Plants sharing a group are also screened together with WSCR |
+| `poi_name` | No | Display name of the POI |
+
+Numbers must use a dot for decimals and no thousands separators (e.g. `1000`, `485.86`). Values with commas are rejected rather than guessed.
+
+## Python API
+
+```python
+from scr_screen.metrics import scr, wscr
+from scr_screen.io import read_plants_csv
+from scr_screen.screening import screen
+from scr_screen.report import write_html_report
+
+scr(500, 100)                          # 5.0
+wscr([1000, 600], [200, 100])          # 2.889
+
+plants, poi = read_plants_csv("plants.csv")
+result = screen(plants, poi_names=poi)
+write_html_report(result, "report.html")
+```
+
+Network mode:
+
+```python
+import pandapower as pp
+from scr_screen.network import scan_buses
+
+net = pp.from_json("network.json")
+for row in scan_buses(net, plant_mw=300, method="classical"):
+    print(row.bus, row.name, round(row.scr, 2), row.flag)
+```
+
+See [`examples/walkthrough.ipynb`](examples/walkthrough.ipynb) for a step-by-step tour.
+
+## Methods
+
+**SCR** = SCMVA ÷ plant rating
+**WSCR** = Σ(SCMVAᵢ × Pᵢ) ÷ (ΣPᵢ)²
+
+| Short-circuit method | Pre-fault voltage | Correction factors | Typical use |
+|---|---|---|---|
+| Classical flat-start (default) | 1.0 pu | None | Common U.S. planning practice |
+| IEC 60909 (max case) | c = 1.1 | Generator and transformer impedance correction | IEC practice |
+
+In both methods, inverter-based resources do not contribute to SCMVA.
+
+**Default flag bands** (user-configurable): below 2 **very weak**; 2 to below 3 **weak**; 3 or above **no flag**. These follow HVDC planning practice (IEEE Std 1204-1997). There is no universal weak-grid threshold.
+
+Full details: [design specification](docs/design-spec.md).
+
+## Limitations
+
+- SCR-based metrics assume **grid-following** inverters and do not replace the inverter manufacturer's minimum SCR.
+- WSCR assumes the plants in a group are fully interacting.
+- The classical method (v0.1) ignores loads, shunts, and line charging, uses nominal transformer taps, and does not yet model three-winding transformers or closed bus-bus switches. Unsupported elements stop the calculation with a clear error rather than being ignored.
+- Real transmission models are often restricted (e.g. CEII in the U.S.). SCR-Screen ships only public test data; users run it on their own models.
+- Cost screening is screening-level only and excludes network upgrades; all costs are user inputs.
+
+## Verification
+
+Every formula is covered by automated tests with hand-calculated expected values, run on each change. Independent engineering checks are recorded in [`docs/verification.md`](docs/verification.md).
+
+## Roadmap
+
+- **v0.2:** PSS/E `.raw` import, N-1 contingency worst case, generator retirement scenarios, interconnection-queue build-out, composite SCR (CSCR)
+- **v0.3:** mitigation sizing (e.g. synchronous condenser MVA needed), SCR with interaction factors (SCRIF)
+
+## Feedback and contributions
+
+Found a bug, have a question, or use SCR-Screen in your work? Please [open an issue](https://github.com/ishaibu/scr-screen/issues). Feedback from utility, ISO/RTO, developer, and consulting engineers is especially welcome.
+
+## References
+
+1. NERC, *Integrating Inverter-Based Resources into Low Short Circuit Strength Systems*, Reliability Guideline, December 2017.
+2. NERC, *Short-Circuit Modeling and System Strength*, White Paper, February 2018.
+3. Y. Zhang et al., "Evaluating system strength for large-scale wind plant integration," IEEE PES General Meeting, 2014.
+4. IEEE Std 1204-1997, *IEEE Guide for Planning DC Links Terminating at AC Locations Having Low Short-Circuit Capacities*.
+5. IEC 60909-0, *Short-circuit currents in three-phase a.c. systems*.
+
+## License and author
+
+MIT License. Created and maintained by **Shaibu Ibrahim, P.E.**

scr_screen-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scr-screen"
+version = "0.1.0"
+description = "Short-circuit ratio (SCR/WSCR) screening for inverter-based resource interconnection"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Shaibu Ibrahim, P.E.", email = "ishaibu136@gmail.com" }]
+keywords = ["power-systems", "short-circuit-ratio", "grid-interconnection", "inverter-based-resources"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "pandapower>=3.5",
+    "openpyxl",            # read Excel network files
+    "xlsxwriter",          # write Excel network files (scr-screen convert)
+    "matpowercaseframes",  # read MATPOWER .m files
+]
+
+[project.urls]
+Homepage = "https://github.com/ishaibu/scr-screen"
+Documentation = "https://github.com/ishaibu/scr-screen#readme"
+Issues = "https://github.com/ishaibu/scr-screen/issues"
+Changelog = "https://github.com/ishaibu/scr-screen/blob/main/CHANGELOG.md"
+
+[project.scripts]
+scr-screen = "scr_screen.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+notebook = ["ipykernel"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+scr_screen = ["data/*.json", "data/*.csv"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# Harmless notices from inside pandapower (not from SCR-Screen code).
+filterwarnings = [
+    "ignore::FutureWarning:pandapower.*",
+    "ignore:tap_dependency_table:DeprecationWarning",
+]

scr_screen-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

scr_screen-0.1.0/src/scr_screen/__init__.py

@@ -0,0 +1,3 @@
+"""SCR-Screen: short-circuit ratio screening for inverter-based resource interconnection."""
+
+__version__ = "0.1.0"

scr_screen-0.1.0/src/scr_screen/__main__.py

@@ -0,0 +1,7 @@
+"""Allow ``python -m scr_screen``."""
+
+import sys
+
+from .cli import main
+
+sys.exit(main())