Metadata-Version: 2.3
Name: eta-incerto
Version: 1.3.4
Summary: Library for modeling investment decisions. Conventional uncertainty-aware approaches like stochastic, robust and regret. Metaheuristic approach for antifragile optimization.
License: BSD-2-Clause
Keywords: investment,uncertainty,modeling,robust,regret,stochastic
Author: Technical University of Darmstadt, Institute for Production Management, Technology and Machine Tools (PTW)
Author-email: m.frank@ptw.tu-darmstadt.de
Requires-Python: >=3.11, <3.13
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Manufacturing
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Dist: adjusttext (>=1.3.0,<2.0.0)
Requires-Dist: attrs (>=25.3.0,<26.0.0)
Requires-Dist: backports-datetime-fromisoformat (==2.0.0)
Requires-Dist: chaospy (>=4.3.20,<5.0.0)
Requires-Dist: eta-components (>=1.0.2,<2.0.0)
Requires-Dist: gurobipy (>=12.0.3,<13.0.0)
Requires-Dist: hplib (>=1.9,<2.0)
Requires-Dist: line_profiler (>=4.2.0,<5.0.0)
Requires-Dist: manim (>=0.20.1,<0.21.0)
Requires-Dist: numba (>=0.63.1)
Requires-Dist: pandas (>=3.0.0,<4.0.0)
Requires-Dist: pyarrow (>=22.0.0,<23.0.0)
Requires-Dist: pydantic (>=2.11.7,<3.0.0)
Requires-Dist: pydot (>=4.0.1,<5.0.0)
Requires-Dist: pymoo (>=0.6.1.5,<0.7.0.0)
Requires-Dist: rheia (>=1.1.13,<2.0.0)
Requires-Dist: salib (>=1.5.2,<2.0.0)
Requires-Dist: seaborn (>=0.13.2,<0.14.0)
Requires-Dist: stable_baselines3 (>=2.1,<3.0)
Requires-Dist: tables (>=3.10.2,<4.0.0)
Requires-Dist: toml (>=0.10.2,<0.11.0)
Requires-Dist: tsam (>=2.3.9,<3.0.0)
Requires-Dist: typing-extensions (>=4.14.1)
Requires-Dist: xarray (>=2026.2.0,<2027.0.0)
Project-URL: Bug Tracker, https://git.ptw.maschinenbau.tu-darmstadt.de/eta-fabrik/public/eta-incerto/-/issues
Project-URL: Changelog, https://git.ptw.maschinenbau.tu-darmstadt.de/eta-fabrik/public/eta-incerto/-/blob/publication-adaptions/CHANGELOG.md
Project-URL: Documentation, https://git.ptw.maschinenbau.tu-darmstadt.de/eta-fabrik/public/eta-incerto/-/pages
Project-URL: Homepage, https://www.ptw.tu-darmstadt.de
Project-URL: Repository, https://git.ptw.maschinenbau.tu-darmstadt.de/eta-fabrik/public/eta-incerto
Description-Content-Type: text/markdown

# ETA Incerto

[![pipeline](https://git.ptw.maschinenbau.tu-darmstadt.de/eta-fabrik/public/eta-incerto/badges/main/pipeline.svg)](https://git.ptw.maschinenbau.tu-darmstadt.de/eta-fabrik/public/eta-incerto/-/commits/main)
[![license](https://img.shields.io/badge/License-BSD--2--Clause-blue.svg)](LICENSE)

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](https://git.ptw.maschinenbau.tu-darmstadt.de/eta-fabrik/public/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](https://git.ptw.maschinenbau.tu-darmstadt.de/eta-fabrik/public/eta-stress)
- Results reporting, plotting, and optional results repository publishing

## Overview

```mermaid
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](#solver-and-third-party-requirements) for MILP solver setup.

## Quick Start

Minimal usage with a config file and a registered system:

```python
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):

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

See [docs/runtime_analysis.md](docs/runtime_analysis.md) for the config table and expected artifacts.

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

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

See [docs/line_profile.md](docs/line_profile.md) for all options.

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

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

See [docs/pyinstrument_profile.md](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](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](https://git.ptw.maschinenbau.tu-darmstadt.de/eta-fabrik/public/eta-incerto/-/pages)

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](CONTRIBUTING.md) for setup, tests, and merge request workflow. Cross-repository
development notes: [cross-repo.md](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](https://git.ptw.maschinenbau.tu-darmstadt.de/eta-fabrik/public/eta-components) — MILP modeling library (required dependency)
- [eta-stress](https://git.ptw.maschinenbau.tu-darmstadt.de/eta-fabrik/public/eta-stress) — stress tests and global sensitivity analysis
- [research-and-optimization-data-management-organizer](https://git.ptw.maschinenbau.tu-darmstadt.de/dissertation/planning-of-decentralized-energy-converters-of-industrial-energy-systems-at-brownfield-production-sites-under-deep-uncertainty/research-and-optimization-data-management-organizer) — results repository tooling
- [global-sensitivity-and-stress-test-analysis](https://git.ptw.maschinenbau.tu-darmstadt.de/dissertation/planning-of-decentralized-energy-converters-of-industrial-energy-systems-at-brownfield-production-sites-under-deep-uncertainty/global-sensitivity-and-stress-test-analysis) — dissertation application workflows

## Solver and third-party requirements

MILP models are built with **Linopy** via [eta-components](https://git.ptw.maschinenbau.tu-darmstadt.de/eta-fabrik/public/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](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](CITATION.cff). See [AUTHORS.rst](AUTHORS.rst)
for further contributors.

## License

BSD-2-Clause — see [LICENSE](LICENSE). See also [CHANGELOG.md](CHANGELOG.md) and [SECURITY.md](SECURITY.md).

