fzj-iek3-vsa/fine

Purpose and entry points

ETHOS.FINE is a Python library for cost-optimal, multi-region and multi-commodity energy-system design and operation. Users construct an energy-system model, add technology components, optimize through Pyomo, then inspect/export results. The public package root is fine/__init__.py; the orchestration entry point is fine/energySystemModel.py. Executable usage is primarily notebook/script based, e.g. examples/00_Tutorial/00_Tutorial.ipynb and examples/01_1node_Energy_System_Workflow/getData.py.

Model orchestration and optimization boundary

EnergySystemModel owns global model dimensions—locations, commodities, time steps, and investment periods—and coordinates component registration, constraint assembly, optimization, and result handling. It is the boundary between FINE’s domain model and the Pyomo optimization model. Optimization minimizes NPV (or TAC for one investment period), subject to technical/environmental constraints.

Paths: fine/energySystemModel.py, fine/component.py, fine/enums.py.

Component model hierarchy

The component framework provides shared parameter validation, sets, variables, constraints, and result interfaces; concrete component families formulate their own Pyomo contributions. Sources/sinks represent supply and demand, conversions transform commodities, storage couples charge/discharge over time, and transmission links locations. Specialized subclasses add dynamic conversion, part-load behavior, and linear optimal power flow.

Paths: fine/component.py, fine/sourceSink.py, fine/conversion.py, fine/storage.py, fine/transmission.py, fine/subclasses/lopf.py.

Primary execution flow

A user supplies scalar, tabular, temporal, and spatial inputs; instantiates EnergySystemModel; creates and adds components; optionally reduces/aggregates inputs; then invokes model optimization against a selected solver. Each component injects its indexed decision variables and constraints into the central Pyomo problem. Solved capacities, operations, costs, and shadow-price-related outputs are collected back into component/model result structures.

Paths: fine/energySystemModel.py, fine/component.py, fine/utils.py.

Temporal, pathway, and uncertainty extensions

The core supports full-resolution time series and temporal aggregation via typical periods. Extension modules implement multi-stage temporal aggregation, transformation-path/perfect-foresight optimization across investment periods, and piecewise-linear cost formulations. Stochastic and pathway-oriented workflows are exposed through the same central model/component abstraction rather than a separate service.

Paths: fine/expansionModules/optimizeTSAmultiStage.py, fine/expansionModules/transformationPath.py, fine/expansionModules/piecewiseLinearCostFunction.py.

Input/output and reproducibility

I/O adapters bridge the in-memory model to dictionary, conventional tabular/Excel-oriented, and xarray/netCDF representations. This is a material boundary: external datasets are normalized into FINE inputs, while full model inputs/results can be persisted reproducibly as netCDF. Example data includes Excel workbooks, netCDF, and GIS shapefiles.

Paths: fine/IOManagement/dictIO.py, fine/IOManagement/standardIO.py, fine/IOManagement/xarrayIO.py.

Model-size reduction

Spatial aggregation groups regions and adapts associated model inputs, including network/spatial data; technology aggregation consolidates similar technologies. These preprocessing capabilities reduce optimization dimensionality before the central model is formulated.

Paths: fine/aggregations/spatialAggregation/manager.py, fine/aggregations/spatialAggregation/aggregation.py, fine/aggregations/technologyAggregation/techAggregation.py.

Runtime and infrastructure

Runtime is Python, packaged via pyproject.toml, with Pyomo as the optimization interface. A MILP solver is required; supported/tested solver integrations include Gurobi, HiGHS, and GLPK. The project is distributed through PyPI and conda-forge, containerized by Dockerfile, and uses GitHub Actions/GitLab CI for validation. Documentation is MkDocs/Read the Docs based.

Paths: pyproject.toml, Dockerfile, .github/workflows/test_push.yml, mkdocs.yml.