Installation of radprocess

Requirements

  • Python 3.12 (3.11 may work, but 3.13+ is not yet supported due to pymses)

  • A working installation of pymses (provided internally, see below)

  • Optional: POLARIS and RADMC-3D executables, needed only for running Steps 4, 6, and 8 of the pipeline

How to obtain radprocess

Clone the GitHub repository, create a virtual environment, and install in editable mode:

git clone https://github.com/sachagavino/radprocess.git
cd radprocess
python -m venv .venv --prompt radprocess
source .venv/bin/activate
python -m pip install -e .

This creates a virtual environment (.venv/) inside the radprocess/ directory, activates it, and installs radprocess with all its Python dependencies (numpy, scipy, zarr, matplotlib, astropy, etc.).

Note

Always use python -m pip instead of bare pip. On some systems, pip may point to a different Python environment than the one activated by the venv, which leads to packages being installed in the wrong place.

If you also want the Gradio web interface:

python -m pip install -e ".[gui]"

Every time you open a new terminal and want to use radprocess, you need to activate the environment first:

cd /path/to/radprocess
source .venv/bin/activate

To update your local copy later:

git pull
python -m pip install -e .

Alternative: using uv

If you have uv installed:

git clone https://github.com/sachagavino/radprocess.git
cd radprocess
uv venv --python 3.12
source .venv/bin/activate
uv pip install -e .

Installing pymses

pymses is not available on PyPI and must be installed from the local source directory. The up-to-date version lives on the server (typically in the shared software folder). To install it, activate the radprocess environment first, then install pymses into it:

# Activate the radprocess environment
source /path/to/radprocess/.venv/bin/activate

# Go to the pymses source directory on the server
cd /path/to/pymses

# Install pymses (--no-build-isolation ensures it uses the numpy
# and Cython already installed in the environment)
python -m pip install -e . --no-build-isolation

This compiles the Cython extensions against the correct numpy version and registers pymses so that Python can find it.

Warning

Do not use $PYTHONPATH or $PATH as an alternative.

  • $PATH only affects executables, not Python imports.

  • $PYTHONPATH bypasses pip, can cause version conflicts across projects, and may lead to crashes if pymses was compiled against a different numpy.

Using radprocess from a notebook

Make sure the notebook kernel uses the same Python environment where radprocess is installed. You can verify from a notebook cell:

import sys
print(sys.executable)

and compare with the output of which python in the terminal where you ran python -m pip install -e ..

Registering the environment as a Jupyter kernel

If your notebook uses a different default kernel, register the radprocess environment explicitly:

# From the terminal, with the radprocess venv activated:
python -m pip install ipykernel
python -m ipykernel install --user --name radprocess --display-name "Python (radprocess)"

Then select Python (radprocess) as the kernel in your notebook.

Running the Gradio interface

If installed with the [gui] extra, radprocess can be launched as a Gradio-based graphical interface:

radprocess

One or more URLs will be displayed in the terminal.

  • On a local machine, open the local URL.

  • On a remote server, use the public (share) URL if available, or set up SSH tunneling:

    ssh -L 7860:localhost:7860 user@server

    then open http://localhost:7860 in your browser.

Verifying the installation

from radprocess.pipeline.Pipeline import Pipeline

pipe = Pipeline()
pipe.configparams.ramsesoutput.ramses_output_dir = "/path/to/output_00940/"
pipe.set_working_dir("/path/to/working_directory")

# Check that RAMSES output is readable:
print(pipe.read_hydro_descriptor())
print(pipe.read_sink_info())

Troubleshooting

“No module named pymses”

pymses must be installed separately into the radprocess environment. See the section above.

zarr import errors or “BloscCodec not found”

radprocess requires zarr v3. Check your installed version:

python -c "import zarr; print(zarr.__version__)"

If it shows 2.x, upgrade with python -m pip install "zarr>=3.0".

“No module named gradio”

Gradio is optional. Install it with python -m pip install -e ".[gui]" or python -m pip install gradio. It is only needed for the web interface, not for notebook or script usage.

numpy/Cython build errors when installing pymses

pymses requires Cython at build time. Make sure Cython is installed (python -m pip install cython) before installing pymses. If you still get errors about deprecated numpy C API, the internal pymses fork should handle this.

pip points to the wrong environment

If which pip shows a path outside .venv/, always use python -m pip instead. This guarantees you are using the pip that matches the active Python interpreter.