Getting Started

1. Clone the git repository

git clone https://github.com/phlegethon-stellar-hydro/phlegethon.git
cd phlegethon

2.1 System dependencies (Debian-based systems)

Run the following command to install curl, an MPI-Fortran compiler, and hdf5 with parallel I/O capabilities

sudo apt install -y curl build-essential gfortran libopenmpi-dev openmpi-bin openmpi-common libhdf5-openmpi-dev hdf5-tools

2.2 System dependencies (MacOS/ Homebrew)

On MacOS, use homebrew to install the system dependencies

brew install open-mpi gcc hdf5-mpi

You will also need to enable developer mode in your OS settings.

If runs are killed immediately without a stack trace (for example killed ./run.app or signal 9 (Killed: 9) in MPI runs), see Troubleshooting FAQ: macOS process is killed immediately.

2.3 Containerized setup (Docker, optional)

For all container workflows (Docker installation, image build, Compose, Jupyter, output access, and interactive sessions), see Docker Workflow.

3. Python environment

Option 2: Using venv (standard library)

Alternatively, you can use Python’s built-in venv module:

  • Create a new virtual environment:

python3 -m venv phl_env

  • Activate the environment:

# On macOS/Linux
source phl_env/bin/activate

# On Windows
phl_env\Scripts\activate

  • Install required Python packages:

pip install --upgrade pip
pip install numpy matplotlib scipy h5py ipython meson ninja

4. Download Helmholtz EoS table and JINA REACLIB rates

In the root directory of phlegethon, run

bash data/get_data.sh

This bash script will download a 541x271 Helmholtz EoS table from Frank Timmes’ cococubed and the latest default JINA REACLIB rate library (version 24-06-2021).

5. Compile the Fortran EoS modules

The Python post-processing stack requires the compiled module eos_fort. If f2py uses the meson backend, ninja must be available (installed above).

cd miscellaneous/eos/
f2py -c eos.f90 -m eos_fort --opt='-O3'

Verify import from the active Python environment:

python -c 'import eos_fort; print(eos_fort.__file__)'

6. Set environment variables

  • Add the following variables to your .bashrc:

export PYTHONPATH=$PYTHONPATH:<path-to-phlegethon>/python/
export PYTHONPATH=$PYTHONPATH:<path-to-phlegethon>/miscellaneous/eos/
export PHLEGETHONDATA=<path-to-phlegethon>/data/
mamba activate phl_env

  • Reload the .bashrc:

source .bashrc

7. Choose a build configuration

Phlegethon uses pkg-config to auto-detect the MPI-Fortran compiler and the hdf5 library. In case you need to specify machine-dependent settings (see also Make.local/README.md):

  • Create a new build-configuration file in Make.local/, specifiying the path to the MPI-Fortran compiler and the hdf5 library

  • Edit the include path in Makefile.config to link the costum configuration, e.g.,

include ../../Make.local/Make.leidi

8. Verify setup

  • Compile and run the hotbubble-helmholtz test problem in tests:

cd tests/hotbubble-helmholtz
make clean
make
mpirun -n 4 ./run.app

If the build fails despite having installed both the MPI-Fortran compiler and HDF5 library correctly, have a look at Troubleshooting FAQ: Build fails because MPI or HDF5 cannot be found.

  • Visualize the output in python:

from phloutput import *
g = h5grid(-1)
g.gridshow(g.mach())

Reading HDF5 output in Python

In a Python session (e.g., ipython), you can load and imshow any quantity from the ith-snapshot (here sixth) like

from phloutput import *
g = h5grid(6)
g.gridshow(g.mach())

Check python/phloutput.py for a list of variables that can be accessed from the h5grid class. For 3D simulations, individual planes can be accessed with the ix, iy, and iz indices (by default, h5grid will load the full array).