eta-incerto 1.3.0

Library for modeling investment decisions under uncertainty

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 using Pyomo models and 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 + Pyomo
• Results reporting, plotting, and optional results repository publishing

Workflow 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)"]

Results repository integration

See docs/results_integration.md for publishing and pulling optimization run artifacts via the Git LFS results repository, including the eta-incerto-results console entry point.

Installation

Python >=3.11,<3.13 is required.

Recommended (development setup):

poetry install
poetry run pre-commit install

Solver note: Pyomo requires an available solver. This project includes gurobipy as a dependency, but you can use any compatible Pyomo solver configured on your system.

Adding dependencies

poetry add <package-name>@latest

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. Example usage:

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

Config files are read from the run folder by a fixed naming convention (config, config_debug_minimal, config_line_profile, config_pyinstrument, config_job_profile). See docs/runtime_analysis.md for the config table, one-command usage, 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 and CLI examples.

Call-stack profiling (pyinstrument) for a full antifragile run (sampling profiler, HTML report):

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

See docs/pyinstrument_profile.md for options. Use line profiling for per-line hotspots; use pyinstrument for high-level call-stack and full-run timing. The pyinstrument package is a dev dependency (poetry install includes it in development).

Results repository integration:

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

See docs/results_integration.md for details on publishing and pulling artifacts.

Results Repository Integration

The results repository integration is opt-in and uses Git LFS to store large artifacts. Environment variables:

• RESULTS_REPO_URL
• RESULTS_REPO_PATH
• PUBLISH_RESULTS=1

Development

poetry install
poetry run pre-commit install

Developing against a local eta-components clone

ETA Incerto depends on eta-components. To work on both repos in parallel (e.g. in a multi-root Cursor workspace), use an editable install so changes in eta-components are picked up without reinstalling.

1. Clone both repos side by side, e.g. c:\Git\eta-incerto and c:\Git\eta-components.
2. In this repo’s pyproject.toml, eta-components is already set to a path dependency:

   eta-components = { path = "../eta-components", develop = true }
   

3. Run poetry lock and poetry install in this repo. Your environment will use the local eta-components clone.

For release or CI (e.g. publishing to PyPI or running in a clean environment), change that line back to a version constraint, e.g. eta-components = "^0.0.6", and rely on the published package.

License

BSD-2-Clause License.