{"id":49027035,"url":"https://github.com/amptimal/surge","last_synced_at":"2026-04-23T05:01:24.552Z","repository":{"id":347880627,"uuid":"1195631262","full_name":"amptimal/surge","owner":"amptimal","description":"AC/DC power flow solver","archived":false,"fork":false,"pushed_at":"2026-04-19T04:38:26.000Z","size":15150,"stargazers_count":4,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-19T07:20:14.634Z","etag":null,"topics":["energy","opf","power-flow","power-systems","rust"],"latest_commit_sha":null,"homepage":"https://amptimal.com","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amptimal.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"docs/support-compatibility.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-29T22:29:05.000Z","updated_at":"2026-04-19T04:26:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/amptimal/surge","commit_stats":null,"previous_names":["amptimal/surge"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/amptimal/surge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amptimal%2Fsurge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amptimal%2Fsurge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amptimal%2Fsurge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amptimal%2Fsurge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amptimal","download_url":"https://codeload.github.com/amptimal/surge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amptimal%2Fsurge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32166660,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-23T02:19:40.750Z","status":"ssl_error","status_checked_at":"2026-04-23T02:17:55.737Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["energy","opf","power-flow","power-systems","rust"],"created_at":"2026-04-19T07:11:26.901Z","updated_at":"2026-04-23T05:01:24.493Z","avatar_url":"https://github.com/amptimal.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Surge\n\n[![License: PolyForm Noncommercial 1.0.0](https://img.shields.io/badge/license-PolyForm%20NC%201.0.0-blue)](LICENSE)\n[![Docs](https://img.shields.io/badge/docs-repo-informational)](docs/index.md)\n\nSurge is a Rust-native power-systems analysis workspace for transmission-focused\nsteady-state studies. The repository covers network interchange, AC/DC power\nflow, HVDC coupling, sensitivities, contingency analysis, optimal power flow,\ntransfer capability workflows, topology rebuild, a CLI, and a Python package.\n\nThis repository exposes three supported interfaces:\n\n- Rust crates in a workspace rooted here\n- the `surge-solve` CLI from `src/surge-bindings`\n- the `surge` Python package built from `src/surge-py`\n\nSurge is source-available under PolyForm Noncommercial 1.0.0. Commercial use\nrequires a separate license from Amptimal. See [LICENSE](LICENSE),\n[COMMERCIAL-LICENSE.md](COMMERCIAL-LICENSE.md), and\n[license-notes.md](docs/license-notes.md).\n\n## Workspace Map\n\n| Crate | Role |\n|---|---|\n| `surge-network` | Shared network model and equipment/domain types |\n| `surge-solution` | Shared result contracts and replay-friendly solved outputs |\n| `surge-sparse` | Sparse matrix and factorization helpers |\n| `surge-io` | Canonical file import/export APIs |\n| `surge-topology` | Node-breaker rebuild and topology processing |\n| `surge-dc` | DC power flow, PTDF/LODF/OTDF, and prepared DC studies |\n| `surge-ac` | AC Newton-Raphson, fast-decoupled power flow, and AC-side controls |\n| `surge-hvdc` | HVDC power flow for point-to-point links and explicit DC grids |\n| `surge-contingency` | N-1, N-2, screening, and follow-on contingency workflows |\n| `surge-opf` | DC-OPF, AC-OPF, and SCOPF |\n| `surge-transfer` | ATC/AFC and reusable transfer capability studies |\n| `surge-dispatch` | Unified SCED/SCUC kernel — DC/AC, period-by-period or time-coupled, with reserves, security screening, and SCED-AC Benders |\n| `surge-market` | Canonical market-formulation layer — reserve catalogues, multi-stage workflows, AC SCED setup, retry/refinement runtime, GO C3 adapter |\n| `surge-bindings` | `surge-solve` CLI |\n| `surge-py` | Python bindings and typed package layer |\n\n## Current Capabilities\n\n- AC power flow with Newton-Raphson and fast-decoupled methods\n- DC power flow, PTDF, LODF, OTDF, and batched N-2 sensitivities\n- HVDC solves for point-to-point links and explicit VSC/LCC DC-network models\n- Branch and generator contingency analysis with screening options\n- DC-OPF, AC-OPF, and SCOPF\n- Transfer capability workflows including NERC-style ATC\n- SCED and SCUC dispatch with reserve products, N-1 screening, and AC redispatch\n- Multi-stage market workflows (canonical DC SCUC → AC SCED) with GO C3 adapter\n- Node-breaker topology rebuild and mapping\n- Rust, CLI, and Python access to the same core analysis stack\n\n## Quick Start\n\n### Python\n\nInstall the prebuilt package from PyPI:\n\n```bash\npip install surge-py\n```\n\n```python\nimport surge\n\nnet = surge.load(\"examples/cases/ieee118/case118.surge.json.zst\")\nac = surge.solve_ac_pf(net)\nprint(ac.converged, ac.iterations, ac.max_mismatch)\n```\n\nTo build from source instead, see [Building from source](#building-from-source)\nbelow.\n\n### CLI\n\nBuilding the CLI requires a [Rust toolchain](https://rustup.rs/) (stable 1.87+)\nand native dependencies listed in [Build Notes](#build-notes). If you don't have\nRust installed:\n\n```bash\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\nsource \"$HOME/.cargo/env\"\n```\n\nThen build and run:\n\n```bash\ncargo build --release --workspace --exclude surge-py\n./target/release/surge-solve --help\n```\n\nRun a few common studies:\n\n```bash\n./target/release/surge-solve examples/cases/ieee118/case118.surge.json.zst --method acpf\n./target/release/surge-solve examples/cases/ieee118/case118.surge.json.zst --method contingency --screening lodf\n./target/release/surge-solve examples/cases/ieee118/case118.surge.json.zst --method dc-opf --output json\n```\n\n### Building from source\n\nBuilding the Python package from source requires a\n[Rust toolchain](https://rustup.rs/) (stable 1.87+) and native dependencies\nlisted in [Build Notes](#build-notes).\n\n```bash\npython3 -m venv .venv\nsource .venv/bin/activate\npip install maturin numpy\ncd src/surge-py\nmaturin develop --release\ncd ../..\npython -c \"import surge; print(surge.version())\"\n```\n\nFor repository scripts and ad hoc debugging, prefer the repo launcher:\n\n```bash\n./py -c \"import surge; print(surge.version())\"\n./py markets/go_c3.py --help\n```\n\n`./py` always uses the repository `.venv` and fails loudly if `surge` has not\nbeen built into that environment yet.\n\nFor rebuilding the Python extension, prefer the repo build launcher:\n\n```bash\n./py-build\n./py-build check\n```\n\n`./py-build` always uses the repository `.venv` `maturin` and, when\n`COPT_HOME` is configured, requires the packaged COPT NLP shim so the build\nfails fast instead of silently producing the wrong Python extension.\n\nIf `COPT_HOME` points to a COPT 8.x install when the package is built, the\nPython package bundles the Surge COPT NLP shim into the wheel and configures it\nautomatically at import time. Python users still need a working COPT runtime\ninstallation and license to run `nlp_solver=\"copt\"`.\n\n### Rust\n\n```rust\nuse std::path::Path;\n\nuse anyhow::Result;\nuse surge_ac::{solve_ac_pf, AcPfOptions};\nuse surge_io::load;\n\nfn main() -\u003e Result\u003c()\u003e {\n    let net = load(Path::new(\"examples/cases/ieee118/case118.surge.json.zst\"))?;\n    let sol = solve_ac_pf(\u0026net, \u0026AcPfOptions::default())?;\n    println!(\"iterations={} mismatch={:.2e}\", sol.iterations, sol.max_mismatch);\n    Ok(())\n}\n```\n\n## File And Data Support\n\nAt the repository level, Surge currently includes:\n\n- canonical load/save paths for MATPOWER, PSS/E RAW, XIIDM, UCTE, OpenDSS,\n  GE EPC, Surge JSON, and Surge BIN\n- additional import/export modules for CGMES/CIM, PSS/E RAWX, DYR, sequence\n  data, IEEE CDF, and related sidecar formats\n- packaged native example cases under [examples/README.md](examples/README.md)\n\nWhen a format has specialized behavior, prefer the format-specific APIs in\n`surge-io` over secondary prose.\n\n## Build Notes\n\nThe shortest path to a working build is documented in\n[docs/quickstart.md](docs/quickstart.md). Supported versions, platforms, and\nnative dependency expectations live in\n[docs/support-compatibility.md](docs/support-compatibility.md).\n\nCommon native requirements:\n\n- Rust stable 1.87+\n- SuiteSparse / KLU development libraries for AC workflows\n- HiGHS C library for `surge-opf` (install via package manager or set `HIGHS_LIB_DIR`)\n- Ipopt C library for open-source AC-OPF (install via package manager or set `IPOPT_LIB_DIR`)\n- COPT 8.x if you want the commercial AC-OPF backend; `surge-py` wheels built\n  with `COPT_HOME` bundle the Surge NLP shim automatically\n\n\u003e **Note:** `pip install highspy` and `pip install cyipopt` do **not** provide\n\u003e the C shared libraries Surge needs. Install HiGHS and Ipopt via your system\n\u003e package manager (`brew install highs ipopt` /\n\u003e `apt install libhighs-dev coinor-libipopt-dev`).\n\n## Documentation\n\n- [docs/quickstart.md](docs/quickstart.md)\n- [docs/data-model.md](docs/data-model.md)\n- [docs/support-compatibility.md](docs/support-compatibility.md)\n- [docs/architecture.md](docs/architecture.md)\n- [docs/glossary.md](docs/glossary.md)\n- [docs/references.md](docs/references.md)\n- [docs/performance.md](docs/performance.md)\n- [docs/tutorials/](docs/tutorials/)\n- [docs/notebooks/README.md](docs/notebooks/README.md)\n- [docs/crates/](docs/crates/)\n- [examples/README.md](examples/README.md)\n\n## Repository Process\n\n- [CONTRIBUTING.md](CONTRIBUTING.md)\n- [SECURITY.md](SECURITY.md)\n- [RELEASING.md](RELEASING.md)\n\nCross-tool validation and benchmark harnesses live primarily in the separate\n`surge-bench` repository. Public docs in this repository should only make\nclaims that can be traced to the current codebase or to maintained evidence in\nthat benchmark repository.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famptimal%2Fsurge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famptimal%2Fsurge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famptimal%2Fsurge/lists"}