ETA Incerto

ETA Incerto is a Python library for modeling investment decisions under uncertainty in energy systems. It provides deterministic, stochastic, robust, regret, and antifragile optimization workflows built on eta-components (Linopy + xarray) with optional multi-objective search via pymoo.

Key Features

• Deterministic evaluation and investment sizing
• Stochastic, robust, and regret-based optimization under uncertainty
• Antifragile optimization with PCE-based evaluation
• Multi-objective optimization with pymoo
• Stress-test and global sensitivity analysis integration via eta-stress
• Results reporting, plotting, and optional results repository publishing

Overview

flowchart LR
  Config["Config file (json/toml/yaml)"] --> Eta[EtaIncerto]
  Register["Variant system registration"] --> Eta
  Eta --> Load["Load series + scenarios"]
  Load --> Opt["Optimization or evaluation"]
  Opt --> Results["HDF5 results artifacts"]
  Results --> Plots["Reports and plots"]
  Results --> Repo["Publish to results repo (optional)"]

Installation

Python >=3.11,<3.13 is required.

Recommended (development setup):

poetry install
poetry run pre-commit install

See Solver and third-party requirements for MILP solver setup.

Quick Start

Minimal usage with a config file and a registered system:

from pathlib import Path

from eta_incerto.core import EtaIncerto

# Import a variant module to register a system
import examples.antifragile.variants.variant_zero.system  # noqa: F401

root_path = Path("examples/antifragile")
experiment = EtaIncerto(root_path, "config", relpath_config=".")
experiment.antifragile_optimization()

Configuration

ETA Incerto loads configuration from JSON/TOML/YAML. Required top-level sections are:

• paths
• system
• scenario
• series

Additional sections such as solver/horizon (e.g. pyomo key for backward compatibility), pymoo, algorithm, termination, evaluate, plots, and analysis control solver, optimization, and reporting behavior.

Configs are resolved relative to root_path and relpath_config:

EtaIncerto(root_path, "config", relpath_config=".")

Examples

Antifragile optimization:

python examples/antifragile/main.py --config config

Conventional methods (stochastic/robust/regret):

python examples/conventional/main.py --config config

Deterministic evaluation:

python examples/deterministic_operation/main.py --config config

To publish results artifacts from example runs (optional):

python examples/antifragile/main.py \
  --publish-results \
  --objectives-summary "Minimize cost and latency"

CLI Tools

Unified runtime analysis (conventional + antifragile + all profilers in one call):

eta-incerto-runtime-analysis runs/2026-03-06_1344_8f8584

See docs/runtime_analysis.md for the config table and expected artifacts.

Line profiling (line-by-line timing) for antifragile optimization:

eta-incerto-profile --config examples/antifragile/config --variant variant_one --single-eval

See docs/line_profile.md for all options.

Call-stack profiling (pyinstrument) for a full antifragile run:

eta-incerto-pyinstrument --config examples/antifragile/config --html-report report.html

See docs/pyinstrument_profile.md for options.

Results repository integration:

eta-incerto-results publish --artifact outputs/results.h5 --config config/run_config.yaml

See docs/results_integration.md for publishing and pulling artifacts via the Git LFS results repository. Environment variables: RESULTS_REPO_URL, RESULTS_REPO_PATH, PUBLISH_RESULTS=1.

Documentation

Hosted documentation (GitLab Pages): eta-incerto documentation

Sphinx documentation is in docs/. Build locally:

poetry install --with docs
cd docs && make html

Feature guides, API reference, and reproducibility notes are in docs/index.rst and linked Markdown files under docs/.

Development

See CONTRIBUTING.md for setup, tests, and merge request workflow. Cross-repository development notes: cross-repo.md.

poetry install
poetry run pre-commit install

Before submitting a merge request:

poetry run pytest
poetry run pre-commit run --all-files

Developing against a local eta-components clone

Clone both repos side by side (e.g. c:\Git\eta-incerto and c:\Git\eta-components). For local co-development, point eta-components to a path dependency in pyproject.toml, then run poetry lock and poetry install. For release or CI, use a published version constraint instead.

Related software

• eta-components — MILP modeling library (required dependency)
• eta-stress — stress tests and global sensitivity analysis
• research-and-optimization-data-management-organizer — results repository tooling
• global-sensitivity-and-stress-test-analysis — dissertation application workflows

Solver and third-party requirements

MILP models are built with Linopy via eta-components. A compatible solver must be installed separately:

• Gurobi (gurobipy) — required for many default example and production paths; commercial license required
• CPLEX — optional alternative; see scripts/README_CPLEX.md
• HiGHS — open-source alternative (supported where Linopy solver interface allows)

This package is licensed under BSD-2-Clause. Solver products (Gurobi, CPLEX, etc.) are third-party software with their own licenses and terms.

Citation

For academic use, cite this repository using CITATION.cff. See AUTHORS.rst for further contributors.

License

BSD-2-Clause — see LICENSE. See also CHANGELOG.md and SECURITY.md.