Metadata-Version: 2.3
Name: eta-incerto
Version: 1.0.2
Summary: Library for modeling investment decisions under uncertainty
License: BSD-2-Clause License
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: License :: Other/Proprietary 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: numba (>=0.63.1)
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)
Project-URL: Homepage, https://www.ptw.tu-darmstadt.de
Description-Content-Type: text/markdown

# 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

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

### 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:

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

```bash
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](docs/runtime_analysis.md) for the config table, one-command usage, 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 and CLI examples.

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

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

See [docs/pyinstrument_profile.md](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](https://github.com/ptw-tuda/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:
   ```toml
   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.

