{"id":50837656,"url":"https://github.com/net-zero-horizon/esfex","last_synced_at":"2026-06-14T05:02:12.683Z","repository":{"id":362010538,"uuid":"1256767759","full_name":"Net-Zero-Horizon/ESFEX","owner":"Net-Zero-Horizon","description":"Integrated framework for Energy System modelling ","archived":false,"fork":false,"pushed_at":"2026-06-10T08:55:51.000Z","size":8920,"stargazers_count":4,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-10T10:23:07.605Z","etag":null,"topics":["energy","energy-system","optimal-power-flow","optimization","pathway-analysis","power-system-simulation","power-systems","power-systems-analysis"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Net-Zero-Horizon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing/development-setup.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":".zenodo.json","notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-02T04:29:56.000Z","updated_at":"2026-06-10T08:56:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Net-Zero-Horizon/ESFEX","commit_stats":null,"previous_names":["msotocalvo/esfex","net-zero-horizon/esfex"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Net-Zero-Horizon/ESFEX","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Net-Zero-Horizon%2FESFEX","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Net-Zero-Horizon%2FESFEX/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Net-Zero-Horizon%2FESFEX/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Net-Zero-Horizon%2FESFEX/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Net-Zero-Horizon","download_url":"https://codeload.github.com/Net-Zero-Horizon/ESFEX/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Net-Zero-Horizon%2FESFEX/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34309655,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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","energy-system","optimal-power-flow","optimization","pathway-analysis","power-system-simulation","power-systems","power-systems-analysis"],"created_at":"2026-06-14T05:02:11.782Z","updated_at":"2026-06-14T05:02:12.674Z","avatar_url":"https://github.com/Net-Zero-Horizon.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/esfex.png\" alt=\"ESFEX Logo\" width=\"460\"/\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eESFEX — Energy System Flexibility Studio\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eA framework for power system capacity expansion and operational dispatch under high renewable penetration\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/Net-Zero-Horizon/ESFEX/actions/workflows/ci.yml\"\u003e\n    \u003cimg src=\"https://github.com/Net-Zero-Horizon/ESFEX/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://codecov.io/gh/Net-Zero-Horizon/ESFEX\"\u003e\n    \u003cimg src=\"https://codecov.io/gh/Net-Zero-Horizon/ESFEX/branch/main/graph/badge.svg?flag=python\" alt=\"codecov (python)\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://esfex.readthedocs.io/\"\u003e\n    \u003cimg src=\"https://readthedocs.org/projects/esfex/badge/?version=latest\" alt=\"Documentation\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://doi.org/10.5281/zenodo.20504838\"\u003e\n    \u003cimg src=\"https://zenodo.org/badge/DOI/10.5281/zenodo.20504838.svg\" alt=\"DOI\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/esfex/\"\u003e\n    \u003cimg src=\"https://img.shields.io/pypi/pyversions/esfex.svg\" alt=\"Python versions\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://julialang.org/\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Julia-1.9%2B-9558B2.svg\" alt=\"Julia\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://jump.dev/\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/optimization-JuMP-2C8C3C.svg\" alt=\"JuMP\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/License-Apache%202.0-blue.svg\" alt=\"License\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://api.reuse.software/info/github.com/Net-Zero-Horizon/ESFEX\"\u003e\n    \u003cimg src=\"https://api.reuse.software/badge/github.com/Net-Zero-Horizon/ESFEX\" alt=\"REUSE status\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.bestpractices.dev/projects/13101\"\u003e\n    \u003cimg src=\"https://www.bestpractices.dev/projects/13101/badge\" alt=\"OpenSSF Best Practices\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/astral-sh/ruff\"\u003e\n    \u003cimg src=\"https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json\" alt=\"Ruff\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/esfex/\"\u003e\n    \u003cimg src=\"https://img.shields.io/pypi/v/esfex.svg\" alt=\"PyPI\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://pepy.tech/project/esfex\"\u003e\n    \u003cimg src=\"https://static.pepy.tech/badge/esfex\" alt=\"Downloads\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/Net-Zero-Horizon/ESFEX/commits/main\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/last-commit/Net-Zero-Horizon/ESFEX.svg\" alt=\"Last commit\"\u003e\n  \u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/status-alpha-orange.svg\" alt=\"Status\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/Net-Zero-Horizon/ESFEX/releases/latest\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Download-ESFEX%20Studio%20for%20Windows-0078D6?style=for-the-badge\u0026logo=windows\u0026logoColor=white\" alt=\"Download ESFEX Studio for Windows\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#overview\"\u003eOverview\u003c/a\u003e •\n  \u003ca href=\"#key-features\"\u003eFeatures\u003c/a\u003e •\n  \u003ca href=\"#installation\"\u003eInstallation\u003c/a\u003e •\n  \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e •\n  \u003ca href=\"#the-studio\"\u003eStudio\u003c/a\u003e •\n  \u003ca href=\"#documentation\"\u003eDocumentation\u003c/a\u003e •\n  \u003ca href=\"#citation\"\u003eCitation\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Overview\n\n**ESFEX** (Energy System Flexibility) is an open-source power system planning framework that co-optimizes generation, storage, and transmission investment over multi-decade horizons while explicitly capturing the operational flexibility constraints that arise in systems with high shares of variable renewable energy.\n\nIt couples a strategic **capacity expansion planner** (Master Problem) with a detailed **operational dispatch engine** through a two-stage decomposition — bridging the gap between long-term investment planning tools and short-term production cost models. Investment decisions are validated operationally (ramp rates, minimum stable generation, storage cycling, demand response, sector coupling) *before* being accepted, so the plan that ESFEX produces is one the system can actually operate.\n\nESFEX is implemented as a hybrid system: **Python** handles configuration, data management, orchestration, the GIS Studio, and post-processing; **Julia** (via [JuMP](https://jump.dev/)) handles the mathematical optimization, leveraging its compiled performance for large-scale LP and MIP problems. The two communicate through [`juliacall`](https://github.com/JuliaPy/PythonCall.jl). The architecture is modular: seven interlinked optimization models can be selectively enabled depending on the study scope.\n\n### Target Applications\n\n- **Island power systems and isolated grids** transitioning from diesel dependence to high RE penetration\n- **Regional transmission planning** with DC and AC power flows, N-1 security, and transmission investment\n- **Sector coupling studies** combining electricity, hydrogen (electrolyzer), fuel logistics (primary energy), and electric vehicles (V2G)\n- **Policy analysis** evaluating RE targets, CO₂ budgets, storage mandates, and technology cost trajectories\n- **Near-optimal space exploration** via MGA (Hop-Skip-Jump) or SPORES (per-objective sweep) for robust investment strategies under uncertainty\n- **Academic research** in energy systems optimization, flexibility quantification, and capacity expansion methodology\n\n---\n\n## Key Features\n\n### Optimization Architecture\n\n- **Two-stage decomposition** — Master Problem (all years simultaneously, representative days/periods) + Operational Dispatch (year-by-year, full chronological year). Investments are operationally validated before acceptance.\n- **Rolling horizon dispatch** — Configurable overlapping time windows with boundary-condition propagation (battery SOC, generator status) and automatic result stitching.\n- **Three simulation modes** — `development` (LP, continuous commitment + investment), `economic_dispatch` (LP, fixed fleet), `unit_commitment` (MIP, binary startup/shutdown with min up/down times).\n- **Unit decommissioning planning** — Age-based retirement plus NPV-based retirement for flexible phase-out / retention of the unit inventory.\n\n### Power System Modeling\n\n- **DC power flow** — KCL/KVL constraints with a cycle-based formulation for meshed networks, voltage angle variables, piecewise-linear losses, and transmission investment.\n- **AC optimal power flow** — Four selectable ACOPF formulations: SOC relaxation (convex W-space), QC relaxation (McCormick envelopes), Polar NLP (exact V-θ), and Rectangular NLP (exact e-f), solved with Ipopt. Models voltage magnitudes, reactive balance, apparent-power limits (`P² + Q² ≤ S²`).\n- **AC power flow verification** — Post-DC Newton-Raphson AC power flow (native Julia solver + pandapower bridge for IEC 60909 short-circuit analysis) to validate voltage profiles and detect violations the DC approximation misses.\n- **N-1 security** — Automatic critical-contingency identification with post-contingency flow redistribution for generation and transmission, in both DC and AC.\n- **Frequency stability** — Post-contingency ROCOF, frequency nadir, and steady-state frequency via a center-of-inertia (COI) model, with N-1 screening of online generators.\n- **Battery storage** — Cyclic SOC, charge/discharge efficiency, calendar + throughput degradation, power/energy co-optimization with duration bounds.\n- **Flexible demand** — Multi-sector decomposition with criticality-weighted load shedding and intra-day shifting of deferrable loads.\n\n### Sector Coupling\n\nESFEX treats sector coupling as a first-class architectural principle. Any energy end-use — electrical, thermal, chemical, or kinetic — can be represented as a demand with its own temporal profile, criticality, and coupling constraints, so arbitrary power-to-X / X-to-power pathways can be modeled without touching the core formulation.\n\n- **Electrolyzer (P2H₂)** — Power-to-hydrogen with capacity investment, load-dependent efficiency, ramp constraints, and coupling to both the electrical balance and hydrogen demand.\n- **Primary energy supply chain** — Multi-fuel import nodes, storage tanks, and transport links (pipelines/tankers) coupled to generator fuel consumption.\n- **Electric vehicles** — Multi-method fleet adoption, multi-category vehicles (passenger, bus, truck…), time-of-day charging, and bidirectional V2G optimization, via [evrex](https://github.com/Net-Zero-Horizon/evrex).\n- **Rooftop solar** — Stochastic adoption with behind-the-meter generation modeled as negative demand, via [rooftex](https://github.com/Net-Zero-Horizon/rooftex).\n- **Flexible sectoral demand** — Sector-specific criticality and temporal flexibility for demand-side participation in system balancing.\n\n### Planning and Analysis\n\n- **MGA and SPORES** — Near-optimal alternatives under a shared cost-slack envelope: classical Hop-Skip-Jump diversity (MGA) and per-objective sweeps (SPORES: minimum build, technology equity, regional equity, evolutionary distance).\n- **Stochastic programming** — Scenario-based expansion with probability-weighted costs and shared investment variables (EVPI/VSS analysis).\n- **Sobol sensitivity analysis** — Global sensitivity indices quantifying how input uncertainty (costs, demand growth, availability) propagates to investment decisions and system cost.\n- **Progressive RE targets** — Linear interpolation from initial to target RE penetration with annual increment bounds and constraint-based curtailment limits.\n\n### Tools and Interface\n\n- **GIS-based Studio** — A PySide6 + Leaflet.js map for visually building power systems: place nodes, generators, batteries, and transmission lines with polyline routing. Includes resource-assessment wizards for rooftop solar, utility-scale PV ([solarex](https://github.com/Net-Zero-Horizon/solarex)), wind ([windrex](https://github.com/Net-Zero-Horizon/windrex)), and OTEC ([OTEX](https://github.com/Net-Zero-Horizon/OTEX)) availability profiles.\n- **Plugin system** — Directory-based plugins with simulation lifecycle hooks, GUI integration, and Julia overlay modules for custom constraints.\n- **CLI** — `run`, `validate`, `export`, `studio`, `precompile`, `info` and `plugin` commands (plus `train-demand-model` / `build-demand-dataset` demand-data utilities) with Rich formatting and progress tracking.\n- **HDF5 output** — Structured results with derived metrics (LCOE, VALCOE, capacity factor) exportable to CSV, Excel, and JSON.\n\n---\n\n## Feature Comparison\n\n| Feature | ESFEX | PyPSA | GenX | Calliope | TIMES | OSeMOSYS |\n|---------|:-----:|:-----:|:----:|:--------:|:-----:|:--------:|\n| Capacity expansion | ● | ● | ● | ● | ● | ● |\n| Operational dispatch (hourly) | ● | ● | ● | ● | Time slices | Time slices |\n| Two-stage decomposition | ● | ○ | ○ | ○ | ○ | ○ |\n| Rolling horizon dispatch | ● | ● | ○ | ● | ○ | ○ |\n| DC power flow (KCL/KVL) | ● | ● | ○ | ○ | ○ | ○ |\n| AC optimal power flow | ● | ◐* | ○ | ○ | ○ | ○ |\n| Battery cyclic SOC | ● | ● | ● | ● | Simplified | Simplified |\n| EV fleet modeling (V2G) | ● | Limited | ○ | ○ | ● | ○ |\n| Primary energy supply chain | ● | Limited | ○ | Limited | ● | Partial |\n| Electrolyzer / P2H₂ | ● | ● | ● | ● | ● | Limited |\n| Stochastic programming | ● | ● | ○ | ○ | ● | ○ |\n| N-1 security constraints | ● | ● | ○ | ○ | ○ | ○ |\n| MGA / near-optimal | MGA + SPORES | MGA | MGA | SPORES | ○ | ○ |\n| Sobol sensitivity | ● | ○ | ○ | ○ | ○ | ○ |\n| GIS-based Studio | ● | ○ | ○ | ○ | ○ | ○ |\n| Plugin / extension system | ● | ○ | ○ | ○ | ○ | ○ |\n| Solver backend | JuMP | Linopy | JuMP | Pyomo | GAMS | GLPK/CBC |\n\n\u003csub\u003e● full support · ◐ partial · ○ not supported. *PyPSA performs an AC power flow via Newton-Raphson, not a full ACOPF. See [`docs/index.md`](docs/index.md) for the extended comparison and citations.\u003c/sub\u003e\n\n---\n\n## Installation\n\nESFEX is a hybrid Python/Julia package. Python ≥ 3.10 and a working Julia ≥ 1.9 installation are required; the Julia dependencies are managed automatically through `juliacall` on first run.\n\n### Windows installer (no Python/Julia required)\n\nFor Windows users who don't want to manage a Python/Julia toolchain, a native\n`.exe` installer bundles everything (Python, Qt, Julia, the GDAL stack) and adds\nan **\"ESFEX Studio\"** Start Menu shortcut — no `pip`, no `PATH` setup. Download\nit from the [latest release](https://github.com/Net-Zero-Horizon/ESFEX/releases/latest)\n(`ESFEX-\u003cversion\u003e-Windows-x86_64.exe`). Build details: [`installer/`](installer/).\n\n### From PyPI\n\n```bash\npip install esfex\n```\n\n### Conda / Mamba\n\nCreate an environment where conda-forge supplies the native dependencies (Qt,\nthe Julia bridge, HDF5, BLAS) and ESFEX is installed from PyPI on top:\n\n```bash\nconda env create -f environment.yml   # or: mamba env create -f environment.yml\nconda activate esfex\nesfex info\n```\n\n### From source (development mode)\n\n```bash\ngit clone https://github.com/Net-Zero-Horizon/ESFEX.git\ncd ESFEX\npip install -e .\n```\n\nThe GIS Studio (PySide6) is included in the core install — no extra is required.\n\n### Windows: if `esfex` is \"not recognized\"\n\n`esfex` is a console script that pip installs into your environment's\n`Scripts\\` folder. **pip does not modify `PATH`** — if that folder is not\nalready on `PATH`, the `esfex` command will not be found (pip prints a yellow\n*\"installed in '…\\Scripts' which is not on PATH\"* warning). This is common on\nWindows when Python was installed without **\"Add Python to PATH\"**, when the\ninstall fell back to a per-user location (`%AppData%\\Roaming\\Python\\…\\Scripts`),\nor with the Microsoft Store build of Python.\n\nThe robust, `PATH`-independent way to launch ESFEX is to run it as a module —\nthis only needs `python` itself on `PATH`:\n\n```bash\npython -m esfex studio          # equivalent to: esfex studio\npython -m esfex run -c my_system.yaml\n```\n\nAlternatively, install into a virtual environment and **activate it** (then\n`Scripts\\` is on `PATH` for that shell), and remember that `PATH` changes are\nonly picked up by **newly opened** terminals:\n\n```powershell\npython -m venv .venv\n.\\.venv\\Scripts\\activate\npip install esfex\nesfex studio\n```\n\n### Optional dependency groups\n\nAll runtime features — visualization, sensitivity analysis, resource\nworkflows, benchmarking, and the ML/DL demand models — ship as **core\ndependencies**, so a plain `pip install esfex` already includes them.\nThe only optional group is the developer tooling:\n\n```bash\npip install -e \".[dev]\"          # pytest, pytest-cov, ruff, black, mypy\n```\n\n### Julia backend\n\nThe Julia optimization models live in [`src/esfex/julia/`](src/esfex/julia/) with their own `Project.toml`. On the first `esfex run`, `juliacall` instantiates the Julia environment automatically. To build a sysimage for faster startup:\n\n```bash\nesfex precompile\n```\n\n### Solvers\n\nESFEX supports ten solver backends, selectable per run (`--solver`) or in the config: **HiGHS** (default), CBC, GLPK, Gurobi, CPLEX, SCIP, and Xpress for LP/MIP problems; Clarabel and SCS for conic relaxations; and Ipopt for the nonlinear ACOPF formulations.\n\nOnly the **open-source** solvers are bundled (HiGHS, GLPK, Clarabel, SCS,\nIpopt). The **commercial** solvers (Gurobi, CPLEX, Xpress) are *not* installed by\ndefault — they require a license that is the user's responsibility. They remain\nselectable: install the corresponding Julia package into the ESFEX Julia\nenvironment and ESFEX loads it on demand, e.g.\n\n```julia\n# with a valid license/GRB_LICENSE_FILE already configured\nusing Pkg; Pkg.activate(joinpath(dirname(pathof(ESFEX)))); Pkg.add(\"Gurobi\")\n```\n\nThis keeps the default install smaller and free of license-locked binaries.\n\n---\n\n## Quick Start\n\n```bash\n# Validate a configuration file\nesfex validate -c my_system.yaml\n\n# Run a 25-year capacity expansion + dispatch simulation\nesfex run -c my_system.yaml --years 25 --verbose\n\n# Run in unit-commitment (MIP) mode with a specific solver\nesfex run -c my_system.yaml --mode unit_commitment --solver gurobi\n\n# Export results to CSV\nesfex export -r results/output.h5 -f csv\n\n# Show version and system information\nesfex info\n```\n\n### Python API\n\n```python\nfrom esfex import load_config\nfrom esfex.runner import Orchestrator\n\nconfig = load_config(\"my_system.yaml\")\norchestrator = Orchestrator(config, output_dir=\"./results\")\nresults = orchestrator.run(years=25)\n\nfor year in results:\n    print(f\"Year {year.year}: RE={year.re_penetration:.1%}, \"\n          f\"Cost=${year.objective:,.0f}\")\n```\n\n---\n\n## The Studio\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/studio-screenshot.png\" alt=\"ESFEX Studio — GIS-based power system designer\" width=\"900\"/\u003e\n\u003c/p\u003e\n\nESFEX ships with an interactive, map-based **Studio** for building and editing power-system configurations visually instead of hand-writing YAML.\n\n```bash\nesfex studio                     # start from a blank canvas\nesfex studio -c my_system.yaml   # open an existing configuration\n```\n\n\u003e On Windows, if `esfex` is \"not recognized\", launch it as a module instead:\n\u003e `python -m esfex studio`. See [Installation → Windows](#windows-if-esfex-is-not-recognized).\n\nPlace nodes, generators, batteries, and transmission lines directly on a Leaflet map with geographic routing, edit element parameters through validated forms, and run resource-assessment wizards (rooftop solar, utility PV via [solarex](https://github.com/Net-Zero-Horizon/solarex), wind via [windrex](https://github.com/Net-Zero-Horizon/windrex), OTEC via [OTEX](https://github.com/Net-Zero-Horizon/OTEX)) to generate availability profiles. The Studio writes standard ESFEX YAML that the CLI and Python API consume unchanged.\n\n---\n\n## Configuration\n\nESFEX is driven by a single YAML configuration describing the system topology, technologies, temporal settings, and solver options. Key sections:\n\n| Section | Purpose |\n|---------|---------|\n| `simulation_mode` | `development`, `economic_dispatch`, or `unit_commitment` |\n| `temporal` | Resolution, rolling-horizon window/overlap, investment resolution |\n| `solver` | Solver name, threads, gap, time limit, numerical options |\n| `nodes` / `buses` | Network topology and demand assignment |\n| `generators` | Thermal, renewable, and conversion technologies |\n| `batteries` | Storage with degradation and duration bounds |\n| `transmission` | Lines, transformers, converters; DC/AC power flow settings |\n| `development_zones` | Candidate sites for new generation investment |\n\nSee the [Configuration Reference](docs/reference/config-reference.md) and the [User Guide](docs/user-guide/configuration.md) for the full schema.\n\n---\n\n## Project Structure\n\n```\nESFEX/\n├── src/esfex/\n│   ├── cli.py                  # Typer CLI entry point\n│   ├── runner.py               # Orchestrator (two-stage run loop)\n│   ├── config/                 # Pydantic schema + YAML loader\n│   ├── bridge/                 # Python↔Julia bridge (juliacall adapters)\n│   ├── julia/                  # Julia optimization models (JuMP)\n│   │   └── src/ESFEX.jl        # Power system, master problem, AC/DC flow, …\n│   ├── models/                 # EV, rooftop solar, demand estimation\n│   ├── io/                     # Demand loading, HDF5/CSV/Excel export\n│   ├── topology/               # Network construction and reduction\n│   ├── sensitivity/            # Sobol / sensitivity analysis\n│   ├── analysis/               # Post-processing and derived metrics\n│   ├── visualization/          # PySide6 GIS Studio + result charts\n│   ├── plugins/                # Plugin framework and discovery\n│   └── paths.py                # Central data-path registry\n├── tests/                      # Test suite (pytest)\n├── docs/                       # MkDocs documentation\n├── mkdocs.yml                  # Documentation site config\n└── pyproject.toml              # Package + dependency configuration\n```\n\n---\n\n## Documentation\n\nFull documentation is built with MkDocs and lives under [`docs/`](docs/).\n\n| Section | Description |\n|---------|-------------|\n| [Getting Started](docs/getting-started/installation.md) | Installation, quickstart, architecture, core concepts |\n| [Tutorials](docs/tutorials/single-system.md) | Single-system, multi-node, EV, stochastic, sensitivity |\n| [User Guide](docs/user-guide/cli.md) | CLI, configuration, master problem, data formats |\n| [GUI Editor](docs/gui/overview.md) | Interactive map-based grid editor (Studio) |\n| [Mathematical Formulation](docs/formulation/overview.md) | Master problem, dispatch, DC/AC flow, primary energy, electrolyzer |\n| [API Reference](docs/api/index.md) | Python and Julia public API |\n| [Reference](docs/reference/config-reference.md) | Config fields, HDF5 schema, constraint catalog, glossary |\n\nTo serve the docs locally:\n\n```bash\npip install mkdocs-material\nmkdocs serve\n```\n\n---\n\n## Requirements\n\n- **Python** ≥ 3.10 (3.10, 3.11, 3.12 supported)\n- **Julia** ≥ 1.9 (managed via `juliacall`)\n- Core Python: NumPy, Pandas, SciPy, h5py, Pydantic, NetworkX, Typer, Rich, PySide6\n- A supported solver: HiGHS (default, open-source), or Gurobi / CPLEX / CBC / GLPK / SCIP / Xpress / Clarabel / SCS / Ipopt\n\n---\n\n## Citation\n\nIf you use ESFEX in academic work, please cite:\n\n```bibtex\n@software{esfex2026,\n  title   = {ESFEX: Energy System FlEXibility — Power System Optimization},\n  author  = {Soto Calvo, Manuel and Lee, Han Soo},\n  year    = {2026},\n  url     = {https://github.com/Net-Zero-Horizon/ESFEX},\n  version = {0.1.3},\n  license = {Apache-2.0}\n}\n```\n\n---\n\n## Contributing\n\nContributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) for the requirements for acceptable contributions (coding standard, tests, and the pull-request process), with [Development Setup](docs/contributing/development-setup.md) for the development environment and [Testing](docs/contributing/testing.md) for the test workflow. Bug reports and feature requests go to the [GitHub issue tracker](https://github.com/Net-Zero-Horizon/ESFEX/issues).\n\n---\n\n## License\n\nESFEX is released under the **Apache License 2.0** — see [LICENSE](LICENSE) for the full text.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnet-zero-horizon%2Fesfex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnet-zero-horizon%2Fesfex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnet-zero-horizon%2Fesfex/lists"}