Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

ESTHER logo

ESTHER

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

PyPI Python License: CeCILL-2.1 Status


Table of contents


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.

Metadata

Release files for esther 0.1.0b8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for esther 0.1.0b8
File Size Uploaded Provenance Actions
esther-0.1.0b8.tar.gz 166.3 kB Without provenance Details for esther-0.1.0b8.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for esther 0.1.0b8
File Interpreter ABI Platform Actions
esther-0.1.0b8-py3-none-any.whl Python 3 none any Details for esther-0.1.0b8-py3-none-any.whl

Total release size: 325.9 kB

Release files / esther-0.1.0b8.tar.gz

Download URL esther-0.1.0b8.tar.gz
Size 166.3 kB
Tags Source
SHA-256 checksum
How to use checksums
23ff24a1aa6d44ba52f4d4c334cae876d4872e39ac36340b0db19e4a351ba7af
BLAKE2b-256 checksum
How to use checksums
303a4940e5f471efb5b6a2e2cfb0a4632ffeb76f38184fc65e6bb43b55b378f6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.12.16

Release files / esther-0.1.0b8-py3-none-any.whl

Download URL esther-0.1.0b8-py3-none-any.whl
Size 159.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2d6bce9c56554c049ed8b93bb3ee14a326e0c1d4bcd2d6d4d9e8f65ccbb1d99a
BLAKE2b-256 checksum
How to use checksums
b42e820c0ce322711825bc095de17120a5f03d7c72b7efed4ffe659767e7ca74
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.12.16

Security for esther 0.1.0b8

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page