Metadata-Version: 2.4
Name: esther
Version: 0.1.0b1
Summary: Python API for building, running, and reading esther simulations.
Author-email: LEPRIEUR Tom <tomleptl@gmail.com>, LECHERBOURG Ludovic <Ludovic.LECHERBOURG@cea.fr>, LAGRÉE Mathurin <Mathurin.LAGREE@cea.fr>
License: CeCILL
License-File: LICENSE
Keywords: esther,simulation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: CEA CNRS Inria Logiciel Libre License, version 2.1 (CeCILL-2.1)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.11
Requires-Dist: matplotlib>=3.5
Requires-Dist: numpy>=1.21
Description-Content-Type: text/markdown

<div align="center">
  <img src="https://gitlab.com/uploads/-/system/project/avatar/74142834/api-logo-esther.png" alt="ESTHER logo" width="368">

  # ESTHER

  Python API for building, running, and reading esther simulations.

  [![PyPI](https://img.shields.io/pypi/v/esther)](https://pypi.org/project/esther/)
  [![Python](https://img.shields.io/pypi/pyversions/esther)](https://pypi.org/project/esther/)
  [![License: CeCILL-2.1](https://img.shields.io/badge/license-CeCILL--2.1-blue.svg)](LICENSE)
  [![Status](https://img.shields.io/badge/status-beta-orange.svg)](#)
</div>

---

## Table of contents

- [Requirements](#requirements)
- [Installation](#installation)
- [Quick start](#quick-start)
- [Features](#features)
- [Examples](#examples)
- [Documentation](#documentation)
- [License](#license)

---

## Requirements

- Python ≥ 3.11 (the API uses the standard library `tomllib`)
- `numpy` ≥ 1.21, `matplotlib` ≥ 3.5 (installed automatically as dependencies)
- A working ESTHER installation

This package is a client for ESTHER: it does not ship the solver itself.

## Installation

```bash
pip install esther
```

---

## Quick start

On first import, ESTHER looks for a config file at `~/.config/esther/config.toml` and prints setup instructions if none exists yet. Create it once:

```python
import esther

cfg = esther.Config()
cfg.set("paths", "esther_root", "/path/to/ESTHER", autopath=True)
cfg.save()
```

An interactive terminal wizard that walks through the whole setup (installation root, display theme, default units) is also available in `examples/Usage guide/config_assistant.py`.

Everything it sets, ESTHER binary paths, temporary directories, the display theme, verbosity, and unit presets, is stored as TOML under `~/.config/esther/` and persists across sessions. It can all be read and changed later through `esther.Config` and `esther.unit`:

```python
cfg = esther.Config()
cfg.get("paths", "esther_root")   # read back a setting
cfg.set("display", "theme", "matrix")
cfg.save()
```

---

## Features

<table>
<tr>
<td width="20%"><strong>Input management</strong></td>
<td>Inputs are TOML files, edited through CRUD-style methods (<code>add</code>, <code>get</code>, <code>set</code>, <code>pop</code>), with layer and energy-deposition management that shifts indices automatically. Every keyword is checked against <code>mc_complet.txt</code> before writing, and parametric studies are declared directly in the TOML, either as a lockstep sweep or a full cartesian grid.</td>
</tr>
<tr>
<td><strong>Fortran conversion</strong></td>
<td><code>toml_to_txt</code> and <code>txt_to_toml</code> convert both ways between the TOML format and ESTHER's native <code>.txt</code> deck, so existing Fortran inputs can be brought into the API and new ones exported back out.</td>
</tr>
<tr>
<td><strong>Run management</strong></td>
<td><code>Run</code> accepts a TOML path, an <code>Input</code> object, or a legacy <code>.txt</code> file, and executes one case or many in parallel with <code>max_workers</code>. Progress is shown as a live terminal bar or, inside Jupyter, an HTML widget; <code>status()</code>, <code>success</code>, <code>duration</code>, and <code>get_error_message()</code> report how each run went.</td>
</tr>
<tr>
<td><strong>Output reading</strong></td>
<td><code>Output</code> loads a result directory lazily, exposing 1D and 2D variables as NumPy arrays through attribute access. A single global unit system (<code>esther.unit</code>) applies unit preferences across every load, while each <code>Variable</code> can also be converted individually without touching the global setting.</td>
</tr>
<tr>
<td><strong>Plotting</strong></td>
<td>A thin layer over matplotlib adds ESTHER-specific behaviour on top: automatic time axes, unit-aware labels, and dispatch between time series, spatial profiles, and time × space heatmaps depending on the variable's shape.</td>
</tr>
</table>

---

## Examples

The `examples/` directory is split in two.

**`examples/Usage guide/`** is reference material, illustrating the API's usage patterns rather than something meant to be run as-is.

| File | Purpose |
| --- | --- |
| `config_assistant.py` | Walkthrough of the configuration options |
| `user_guide.ipynb` | Tour of the main API |

**`examples/Working examples/`** are complete, runnable cases.

| File | Purpose |
| --- | --- |
| `basic_example.py` | Full build-run-read cycle |
| `complete_workflow.ipynb` | End-to-end notebook workflow |

---

## Documentation

Full API reference documentation is included in the repository under [`docs/`](docs/esther.html). Open `docs/esther.html` in a browser to browse it locally.

---

## License

CeCILL v2.1. See [LICENSE](LICENSE).
