ESTHER UI

Graphical interface for building, running, and reading esther simulations.

Table of contents

• Requirements
• Installation
• Quick start
• Features
• Standalone builds
• Development
• Troubleshooting
• License

Requirements

• Python ≥ 3.11
• The esther API, NiceGUI, plotly and numpy (installed automatically as dependencies)
• A working ESTHER installation
• A recent web browser

Like the esther API it is built on, this package does not ship the solver itself.

Installation

pip install esther-ui

Builds that need no Python and open in their own window are also available for Windows and Linux: see Standalone builds.

Quick start

esther-ui

The interface opens in a browser tab on http://localhost:8080 (or the next free port up to 8089; ESTHER_PORT sets another one). It only listens on this machine. Launching it again while it runs opens the running one instead of a second, and Ctrl+C in the terminal stops it.

On first launch, open the Config tab, set the esther root, let Auto path fill in the other paths, and save. These settings are esther's own (~/.config/esther/config.toml), shared with the Python API: a configuration made with esther.Config is picked up as is.

What the interface keeps on its own between launches, the tab shown, the runs, the cases and plots open, the appearance, is stored in an esther-nicegui folder of the user's config directory.

Features

Standalone builds

Each release comes with a Windows and a Linux build, made with PyInstaller. They need no Python, open in their own window instead of a browser tab, and work the same way otherwise.

On Windows the window uses the WebView2 runtime, preinstalled on Windows 11 and on an up-to-date Windows 10.

On Linux (Ubuntu 24.04, Debian 13, Fedora 40 or later), the window is the system's GTK WebKit, which the archive does not include:

sudo apt install libgirepository-2.0-0 gir1.2-gtk-3.0 gir1.2-webkit2-4.1   # Ubuntu, Debian
sudo dnf install webkit2gtk4.1                                             # Fedora

Without it, the build opens in the browser instead.

Development

git clone https://gitlab.com/esther4254519/esther-ui.git
cd esther-ui
python -m venv venv
venv/bin/pip install -e .
venv/bin/python main.py

main.py serves the interface on http://localhost:8080 and reloads it on each change of the sources. NiceGUI only reloads a script: python -m esther_ui, like the esther-ui command, runs without reload.

A standalone build is made on the system it targets:

pip install . --group build
python packaging/build.py

It lands in dist/esther-ui/, archived beside it.

Pushing a version tag (v1.2.3) runs the GitLab pipeline: the package goes to PyPI, its version read from the tag, and the Windows and Linux builds to a release of the tag.

Troubleshooting

• Firefox crashes during a live run: set gfx.webrender.software to true in about:config.
• The Linux build opens in the browser: GTK WebKit is missing, see Standalone builds.
• The Windows build shows nothing: its log is esther.log in %APPDATA%\esther-nicegui.

License

CeCILL v2.1. See LICENSE.