UCLCHEM Astrochemical Modeling GUI

Panel-based web interface for running UCLCHEM astrochemical models, plotting selected species abundances, running parameter grids, and saving/loading model configuration and result files.

The GUI currently exposes these UCLCHEM model types:

• Cloud
• Collapse
• JShock
• CShock
• PrestellarCore

Sequential models (Collapse, JShock, CShock, and PrestellarCore) can run with a Cloud pre-run, or reuse the last loaded/run model as previous_model.

Requirements

• Python 3.12 for this GUI environment (setup.sh checks for or installs it)
• A Fortran compiler (gfortran) to build UCLCHEM
• On Linux/WSL manual or venv setups: make, python3-pip, and python3-venv
• UCLCHEM cloned into this repository as UCLCHEM/

Native Windows is not officially supported by UCLCHEM. Use Windows Subsystem for Linux (WSL) instead.

UCLCHEM itself currently requires Python >=3.11,<3.14, but this repository's setup scripts use Python 3.12. The setup script uses the UCLCHEM git tag v4.0.0-rc4 and installs that checkout into the selected Python environment.

Installation

Clone the GUI and then clone UCLCHEM inside it:

git clone https://github.com/ludev-nl/2026-33-Astrochemical_Modeling_GUI.git
cd 2026-33-Astrochemical_Modeling_GUI
git clone https://github.com/uclchem/UCLCHEM.git

Quick Setup (Reccomended)

Run the setup script from the project root:

./setup.sh

The script asks whether to use:

• conda: recommended for macOS and also supported on Linux
• venv: standard Python virtual environment

It installs GUI dependencies from requirements.txt, checks out UCLCHEM v4.0.0-rc4, and builds/installs the backend chemical engine.

Manual Setup

If the quick setup does not fit your system, install the system dependencies and then install the Python packages yourself.

On Linux or WSL:

sudo apt update
sudo apt install make python3-pip python3-venv gfortran
python3.12 -m venv venv
source venv/bin/activate

On macOS with Homebrew:

brew install gcc
python3.12 -m venv venv
source venv/bin/activate

Then install the GUI and UCLCHEM:

python -m pip install --upgrade pip
python -m pip install --upgrade -r requirements.txt
cd UCLCHEM
git checkout v4.0.0-rc4
python -m pip install --no-cache-dir .
cd ..

Running the App

Start the GUI from the project root:

./run_gui.sh

run_gui.sh automatically detects a local venv/ first. If no venv/ exists, it looks for the conda environment created by setup.sh.

You can also start Panel directly:

PYTHONPATH=. panel serve src/main.py --show --autoreload

Using the GUI

The sidebar has three main tabs:

• Single Model: choose a model, edit model and simulation parameters, select species, and run one simulation. For sequential models, the tab also exposes the Cloud pre-run settings and can reuse the last loaded/run model as previous_model.
• Grid Runner: build a chain of one or more models, vary parameters with linear or logarithmic grids, and view all model outputs or a selected grid result.
• Save/Load: load HDF5 model results, save the latest model result, and save/load YAML parameter configurations.

The main panel shows the simulation log, an interactive Plotly abundance plot, and an advanced live Fortran output stream.

Outputs

Generated files are written under output/:

• output/states/: saved YAML parameter configurations
• output/results/: saved HDF5 model results
• output/abundances/: abundance files saved through the initial abundances UI

Project Layout

src/main.py                    Panel application entry point
src/backend/engine.py          Isolated UCLCHEM execution and grid helpers
src/backend/io_handler.py      Output directory and YAML state helpers
src/config/                    Model, species, and parameter metadata
src/frontend/ui_layout.py      Panel widget and template construction
src/frontend/ui_callbacks.py   UI event handling, plotting, save/load logic
tests/                         Pytest coverage for UI/backend helpers