esther 0.1.0b1

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

ESTHER

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

---

Table of contents

• Requirements
• Installation
• Quick start
• Features
• Examples
• Documentation
• 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

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:

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:

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

---

Features

Input management	Inputs are TOML files, edited through CRUD-style methods (add, get, set, pop), with layer and energy-deposition management that shifts indices automatically. Every keyword is checked against mc_complet.txt before writing, and parametric studies are declared directly in the TOML, either as a lockstep sweep or a full cartesian grid.
Fortran conversion	toml_to_txt and txt_to_toml convert both ways between the TOML format and ESTHER's native .txt deck, so existing Fortran inputs can be brought into the API and new ones exported back out.
Run management	Run accepts a TOML path, an Input object, or a legacy .txt file, and executes one case or many in parallel with max_workers. Progress is shown as a live terminal bar or, inside Jupyter, an HTML widget; status(), success, duration, and get_error_message() report how each run went.
Output reading	Output loads a result directory lazily, exposing 1D and 2D variables as NumPy arrays through attribute access. A single global unit system (esther.unit) applies unit preferences across every load, while each Variable can also be converted individually without touching the global setting.
Plotting	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.

---

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/. Open docs/esther.html in a browser to browse it locally.

---

License

CeCILL v2.1. See LICENSE.