Quantas GUI

An interactive interface for the Quantas scientific library

Quantas GUI is the graphical companion to Quantas, a Python library for analysing solid-state properties. Quantas performs the scientific work; this package provides the forms, workflow controls, tables and interactive Plotly figures needed to use that work from a browser.

That separation is deliberate. Numerical methods, physical conventions, units, precision and native HDF5 persistence remain in Quantas. The GUI talks to the public quantas.api interface and does not call the command-line application or reach into private backend modules.

The application currently runs like a desktop program: quantas-gui starts a local Dash server and opens the default browser. The same code can also run behind a WSGI server in a controlled laboratory environment. Public multi-user deployment will require additional authentication, ownership and resource management that are not part of the current alpha.

Where the project stands

The current development package is 0.4.0a4. Elasticity and SEISMIC are both complete executable workflows. The next milestone is 0.5, which will add HA and QHA while reusing the same execution, feedback, persistence and result-handoff architecture.

The application already includes:

• a responsive shell for desktop, tablet and mobile layouts;
• Quantas Dark, Quantas Light and operating-system theme modes;
• browser-local preferences for text size, motion and table density;
• a Result Explorer for native Quantas .h5, .hdf5 and .hdf files;
• compatibility checks for the installed Quantas backend;
• a safe degraded mode when the backend is missing or incompatible;
• lazy report and plot construction through public Quantas lifecycle methods;
• Dash AG Grid tables with raw-value sorting and complete CSV downloads;
• Plotly renderers for Cartesian, contour, polar, surface, spherical and panel specifications;
• module-aware presentation for Elasticity, SEISMIC, HA, QHA, Thermoelasticity and EOS archives;
• server-side artifact caching, atomic file publication and cross-process workspace locks;
• an isolated Scientific UI Kit, started with quantas-gui --ui-kit;
• deployment-neutral contracts for background jobs and result stores;
• a local spawn process backend with typed Elasticity and SEISMIC request adapters, native HDF5 publication and Result Explorer handoff;
• an executable Elasticity form with manual, Quantas, CRYSTAL and VASP input, progress, warnings, cancellation, completion summary and downloads;
• an executable SEISMIC form with stiffness and density input, angular sampling, phase/group/enhancement levels, polarizations, numerical tolerances, progress, cancellation, summary, sampled CSV and Result Explorer handoff;
• an operational Workflows catalogue that distinguishes backend contract readiness from user-facing GUI availability.

Elasticity remains the approved 0.3.0a7 baseline. SEISMIC 0.4.0a4 is the approved second workflow baseline: it supports manual, Quantas, CRYSTAL and VASP input; phase, group and enhancement calculations; progress and cancellation; HDF5, report and CSV downloads; and direct Result Explorer handoff. Its three-dimensional views clearly separate general scalar fields from canonical phase, slowness and group acoustic surfaces.

Installation from source

Quantas GUI is not yet published on PyPI. It currently requires Quantas >=2.0.0b8,<2.1, so the backend and GUI should be installed in the same virtual environment.

Windows

git clone https://github.com/gfulian/quantas-gui.git
cd quantas-gui

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e "C:\path\to\quantas"
python -m pip install -e ".[performance]"

When a pull or update changes project dependencies, rerun the last two install commands. This is important for runtime packages such as filelock; importing the source tree is not a substitute for reinstalling the project.

Linux and macOS

git clone https://github.com/gfulian/quantas-gui.git
cd quantas-gui

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e /path/to/quantas
python -m pip install -e ".[performance]"

The Quantas path must point to the directory containing its pyproject.toml.

Running the application

With the environment active:

quantas-gui

By default the launcher binds to 127.0.0.1, looks for an available port starting at 8050, and opens the browser. Useful options include:

quantas-gui --no-browser
quantas-gui --port 8060
quantas-gui --debug
quantas-gui --url-prefix /quantas/
quantas-gui --ui-kit

The UI Kit is a development tool rather than a normal application page. Its separate profile uses the same components, themes and settings as the main GUI without appearing in the scientific navigation.

Validating a Windows checkout

The recommended command is the batch validator, which is not affected by PowerShell script-signing policies:

scripts\validate_windows.cmd "C:\path\to\quantas"

It creates or refreshes .venv, installs the backend and all constrained GUI dependencies, then runs Ruff, mypy, pytest, the Dash component audit, package builds and twine check.

The PowerShell script remains available:

powershell -NoProfile -ExecutionPolicy Bypass -File `
    .\scripts\validate_windows.ps1 `
    -QuantasPath "C:\path\to\quantas"

This changes the execution policy only for that PowerShell process. The project does not recommend weakening the machine-wide policy.

Result Explorer

The Result Explorer identifies each native result through quantas.api.registry. It can show:

• provenance, inputs, options, warnings and stored events;
• report tables built by the public module API;
• valid plot families, properties and contexts discovered from public plot inventories;
• interactive Plotly figures generated from frontend-neutral PlotSpecs;
• bounded technical information about the stored payload;
• original HDF5 files, reports, tables and supported scientific exports.

Large arrays and open HDF5 objects stay in the controlled server-side workspace. The browser receives only opaque identifiers and lightweight interface state.

EOS follows a persistent session model and is therefore different from the other modules. The generic Explorer offers read-only structural and fit-record inspection; the complete EOS interface belongs to milestone 0.7.

Running on a laboratory server

The WSGI entry point is:

quantas_gui.wsgi:server

Install the server extra and use Waitress on Windows or Gunicorn on Linux. All workers must share the configured workspace root. Workspace access is coordinated across processes, while the current artifact cache remains local to each worker.

This setup is suitable for a controlled laboratory network. It is not yet a public service: authentication, per-user ownership, quotas, retention, worker isolation and a persistent job queue still need to be added.

See Server deployment for the supported boundary and configuration examples.

Documentation

Start with the documentation index. The most useful project references are:

• Current project state
• Roadmap
• Architecture
• Architectural decisions
• Result Explorer
• Execution and concurrency
• SEISMIC workflow
• Contributing
• Changelog

Contributing

Code, tests, documentation, interface review and scientific feedback are all welcome. Please keep changes focused and preserve the boundary between the GUI and the public Quantas API. The setup, validation and pull-request process are explained in CONTRIBUTING.md.

License and citation

Quantas GUI is distributed under the BSD 3-Clause license. See LICENSE.

Citation metadata is kept in CITATION.cff and will be completed as the project approaches its first stable release.