Installation

Dragonfly is distributed on PyPI as dragonfly-spi and the source repository is hosted at github.com/SerialXI/dragonfly. The Python package you import is named dragonfly.

Installing the Python package builds Cython extensions, so a working compiler toolchain and the external scientific libraries used by Dragonfly must be available at install time.

Prerequisites

System dependencies:

  • MPI (OpenMPI or MPICH)

  • GSL (GNU Scientific Library)

  • HDF5

  • OpenMP (usually included with compiler)

Python dependencies:

  • Python 3.8+

  • numpy

  • scipy

  • h5py

  • mpi4py

  • cython

Install from PyPI

Install the published package with pip:

python -m pip install dragonfly-spi

This installs the dragonfly Python package and its command-line tools.

On HPC systems, load the MPI module you want to use before installation so mpi4py and the compiled extensions link against the same MPI library:

module load mpi/openmpi-x.x.x
python -m pip install dragonfly-spi

Note

The build process expects tools such as mpicc, gsl-config, and h5cc to be available on PATH.

Install from Source

Clone the repository:

git clone https://github.com/SerialXI/dragonfly.git
cd dragonfly

Install Python dependencies:

python -m pip install -r requirements.txt

Note

On managed systems, load the required compiler, MPI, HDF5, and GSL modules before running the install commands.

Install the package in editable mode:

python -m pip install -e .

If your environment has trouble with isolated builds, use:

python -m pip install -e . --no-build-isolation

Verify Installation

Check that the package imports:

python -c "import dragonfly; print(dragonfly.__file__)"

Check that MPI is available:

mpirun --version

You can also verify that the installed command-line entry points resolve:

dragonfly.init -h

Uninstall

Uninstall the PyPI or editable install with:

python -m pip uninstall dragonfly-spi

Troubleshooting

Build cannot find MPI, HDF5, or GSL

Make sure the corresponding development packages or environment modules are loaded and that mpicc, h5cc, and gsl-config are on PATH.

mpi4py installation fails or imports the wrong MPI

Reinstall after loading the MPI module you actually intend to use:

module load mpi/openmpi-x.x.x
python -m pip install --force-reinstall mpi4py dragonfly-spi

Import errors after installation

Try reinstalling with a fresh build:

python -m pip uninstall dragonfly-spi
python -m pip install -e . --no-build-isolation

Missing GSL library

Install GSL development libraries (e.g., libgsl-dev on Debian/Ubuntu).

Next Steps