Metadata-Version: 2.5
Name: esther-ui
Version: 0.1.0b1
Summary: Graphical interface for the esther API
Project-URL: Repository, https://gitlab.com/esther4254519/esther-ui
Author-email: LEPRIEUR Tom <tomleptl@gmail.com>
License-Expression: CECILL-2.1
License-File: LICENSE
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.11
Requires-Dist: esther>=0.1.0b7
Requires-Dist: nicegui<4,>=3.17
Requires-Dist: numpy>=2
Requires-Dist: plotly>=7
Requires-Dist: watchfiles>=1
Description-Content-Type: text/markdown

<div align="center">
  <img src="https://gitlab.com/esther4254519/esther-ui/-/raw/main/esther_ui/static/logo_500x500.png" alt="ESTHER UI logo" width="160">

  # ESTHER UI

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

  [![PyPI](https://img.shields.io/pypi/v/esther-ui)](https://pypi.org/project/esther-ui/)
  [![Python](https://img.shields.io/pypi/pyversions/esther-ui)](https://pypi.org/project/esther-ui/)
  [![License: CeCILL-2.1](https://img.shields.io/badge/license-CeCILL--2.1-blue.svg)](https://gitlab.com/esther4254519/esther-ui/-/blob/main/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)
- [Standalone builds](#standalone-builds)
- [Development](#development)
- [Troubleshooting](#troubleshooting)
- [License](#license)

---

## Requirements

- Python ≥ 3.11
- The [esther](https://pypi.org/project/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

```bash
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](#standalone-builds).

---

## Quick start

```bash
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

<table>
<tr>
<td width="20%"><strong>Input &amp; run</strong></td>
<td>The cases of the input directory as a tree, refreshed as files appear or change. Each case opens in an editor, with completion of the <code>mc_complet</code> keywords, beside a tab for each of its associated files. <strong>Save as</strong> copies a case with its associated files, <strong>Convert</strong> switches between TOML and ESTHER's native <code>.txt</code> deck, <strong>Validate</strong> checks it, and the parametric variants it declares are listed under it. The cases ticked in the tree run side by side, one per CPU core but one.</td>
</tr>
<tr>
<td><strong>Log</strong></td>
<td>The runs of this launch and of former ones, with their progress, the live log of the one selected and a live plot of its outputs as they are written. A run can be stopped from there, and the overall progress shows behind the tab's title from anywhere in the app.</td>
</tr>
<tr>
<td><strong>Output</strong></td>
<td>Plot tabs over one or more cases of the output directory, to compare them: spatial profiles at a given time, time series at a given cell, and 2-D maps, split by layer if needed, each axis with its own unit, bounds and scale. Plot styles can be saved as themes, and each plot exported as PNG or its data as CSV.</td>
</tr>
<tr>
<td><strong>Data</strong></td>
<td>esther's material database, file by file: an editor for each file and a plot of the tables of numbers it holds, on linear or log axes.</td>
</tr>
<tr>
<td><strong>Config</strong></td>
<td>esther's paths (root, input, output and data directories, <code>mc_complet</code>, executable, documentation), its message channels and units, saved together; the appearance of the interface (System, Light or Dark), applied at once.</td>
</tr>
<tr>
<td><strong>Docs</strong></td>
<td>The user documentation shipped with ESTHER, searchable, inside the interface.</td>
</tr>
</table>

---

## Standalone builds

Each [release](https://gitlab.com/esther4254519/esther-ui/-/releases) 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.

| System | Archive | Launch |
| --- | --- | --- |
| Windows 10, 11 | `esther-ui-<version>-windows-x64.zip` | `esther-ui\ESTHER.exe` |
| Linux | `esther-ui-<version>-linux-x64.tar.gz` | `esther-ui/ESTHER` |

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:

```bash
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

```bash
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.

| Path | Purpose |
| --- | --- |
| `main.py` | Launcher of the sources, reloaded on changes; the script PyInstaller packages |
| `esther_ui/launch.py` | One app at a time, UTF-8 mode, window or browser tab |
| `esther_ui/page.py` | The page: header, tabs, and the routes it uses |
| `esther_ui/tab_*.py` | One module per tab |
| `esther_ui/__main__.py` | The `esther-ui` command |
| `packaging/` | PyInstaller spec and build script |

A standalone build is made on the system it targets:

```bash
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](#standalone-builds).
- **The Windows build shows nothing**: its log is `esther.log` in `%APPDATA%\esther-nicegui`.

---

## License

CeCILL v2.1. See [LICENSE](https://gitlab.com/esther4254519/esther-ui/-/blob/main/LICENSE).
