Installation

At the bare minimum, pystella requires numpy, loopy for code generation, and pyopencl (plus an OpenCL implementation) for kernel execution. This minimal installation can be achieved with pip:

python -m pip install pystella

Optional dependencies (and what they are needed for) are:

• mpi4py (and an MPI implementation) for distributed, multi-device execution

• pycl-fft (and optionally clfft) for OpenCL Fast Fourier Transforms (pystella.fourier.pyclDFT) (e.g., to run on a GPU), and/or mpi4py_fft (and fftw) for distributed, CPU FFTs (pystella.fourier.pDFT)

• h5py (and hdf5) to use the convenience class pystella.output.OutputFile

• sympy, to interoperate with pymbolic

Fortunately, conda greatly simplifies the installation process of any of these dependencies (especially those which are not available on PyPI). The included environment file provides a complete installation.

Steps for a complete installation

1. Install miniforge or miniconda (if you haven’t already installed conda).

2. Create a pystella environment as specified by environment.yml:

   conda env create --file environment.yml
   

   • This will clone and pip-install pycl-fft, loopy, and pystella into src/. You may want to first define the environment variable PIP_SRC to set your desired source directory, e.g., to your home directory with:

     export PIP_SRC=~
     

   Alternatively, update your active environment via:

   conda env update --file environment.yml
   

3. Activate the environment (if you created a new one):

   conda activate pystella
   

You can also clone the repository from GitHub:

git clone https://github.com/zachjweiner/pystella.git
cd pystella; pip install -e .

To test that installation was successful, try running an example (e.g., python examples/scalar_preheating.py) or run the tests with pytest (if you cloned the source).

Running on other devices (GPUs, etc.)

The included environment.yml installs pocl, which provides an OpenCL implementation on most CPUs. Enabling execution on other hardware (e.g., GPUs) requires making pyopencl aware of the corresponding OpenCL driver. See pyopencl’s instructions (specifically, here). For example, installing CUDA installs the driver for NVIDIA GPUs; one must then merely copy the nvidia.icd file via:

cp /etc/OpenCL/vendors/nvidia.icd $CONDA_PREFIX/etc/OpenCL/vendors

Using an existing MPI implementation

To enable MPI support without conda installing its own MPI implementation (e.g., to use the optimized implementation already provided on a cluster, etc.), simply install mpi4py (and mpi4py_fft, if desired) from PyPI:

python -m pip install mpi4py mpi4pyfft

pip-installing mpi4py assumes that mpicc is available (check the output of which mpicc). See mpi4py’s instructions for more details.