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.0b7

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.0b7
File Size Uploaded Provenance Actions
esther-0.1.0b7.tar.gz 164.7 kB Without provenance Details for esther-0.1.0b7.tar.gz

Built distribution (wheel)

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

Total release size: 322.5 kB

Release files / esther-0.1.0b7.tar.gz

Download URL esther-0.1.0b7.tar.gz
Size 164.7 kB
Tags Source
SHA-256 checksum
How to use checksums
c1508f786a0f5708644a805568b222e1e33ac56023e116d28e52f61c2d7c79f1
BLAKE2b-256 checksum
How to use checksums
d7d21a78edad3e14d463926b936239371b44428f020d81628addddbecdd499b6
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.0b7-py3-none-any.whl

Download URL esther-0.1.0b7-py3-none-any.whl
Size 157.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f9432d083e135a8a7ce79292246a8badb67864717638d97d43e009c0ec5f8907
BLAKE2b-256 checksum
How to use checksums
4d3aec5fcb59ee8bc565a3c57e3037d9cf98a39f9d4e5ba31499e89f354841ec
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.0b7

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