Getting Started¶

Python quick start¶

To install µGrid’s Python bindings, run

$ pip install muGrid

Note that on most platforms this will install a binary wheel that was compiled with a minimal configuration. To compile for your specific platform use

$ pip install -v --force-reinstall --no-cache --no-binary muGrid muGrid

which will compile the code. µGrid will autodetect MPI. For I/O, it will try to use Unidata NetCDF for serial builds and PnetCDF for MPI-parallel builds. Monitor output to see which of these options were automatically detected. You should see something like:

--------------------
muGrid configuration
  Version        : 0.95.0-328-gc99adf21
  Eigen          : 5.0.1 (fetched)
  CUDA           : OFF
  HIP            : OFF
  MPI            : ON - MPI 3.1
  Parallel NetCDF: ON - PnetCDF 1.13.0
  Python bindings: ON - Python 3.14.2
  pybind11       : 2.13.6 (fetched)
  Tests          : ON
  Examples       : ON
--------------------

Obtaining µGrid’s source code¶

µGrid is hosted on a git repository on GitHub. To clone it, run

$ git clone https://github.com/muSpectre/muGrid.git

or if you prefer identifying yourself using a public ssh-key, run

$ git clone git@github.com:muSpectre/muGrid.git

The latter option requires you to have a user account on GitHub.

Building µGrid¶

µGrid uses CMake (3.18 or higher) as its build system.

The current (and possibly incomplete list of) dependencies are:

CMake (3.18 or higher)
git
Python3 (3.10 or higher) including the header files
numpy

The following dependencies are fetched automatically if not found:

pybind11 (2.11 or higher)
Eigen (5.0.1 or higher)
DLPack (for GPU array exchange)

The following dependencies are optional:

Boost unit test framework
Unidata NetCDF (for serial I/O)
PnetCDF (for parallel I/O with MPI)
CUDA Toolkit (for NVIDIA GPU support)
ROCm/HIP (for AMD GPU support)

Recommended:

Sphinx and Breathe (necessary if you want to build the documentation (turned off by default)

µGrid requires a relatively modern compiler as it makes heavy use of C++20 features.

To compile for development, i.e. with debug options turned on, first setup the build folder:

$ cmake -DCMAKE_BUILD_TYPE=Debug -B build-debug
$ cmake --build build-debug

To compile for production, i.e. with code optimizations turned on, setup the build folder while specifying the Release build type:

$ cmake -DCMAKE_BUILD_TYPE=Release -B build-release
$ cmake --build build-release

You can also use ninja as the build backend for faster compilation:

$ cmake -DCMAKE_BUILD_TYPE=Release -G Ninja -B build-release
$ cmake --build build-release

Enabling and disabling features¶

By default, CMake autodetects features for you. The build system will print a configuration summary showing what features are enabled:

--------------------
muGrid configuration
  Version        : v0.96.0
  Eigen          : 5.0.1
  CUDA           : OFF
  HIP            : OFF
  MPI            : ON - MPI 3.1
  Parallel NetCDF: ON - PnetCDF 1.12.3
  Python bindings: ON - Python 3.11
  pybind11       : 2.13.6
  Tests          : ON
  Examples       : ON
--------------------

You can manually enable or disable specific features using CMake options. Here are the available options:

Core features:

# Disable MPI (build serial version)
$ cmake -DMUGRID_ENABLE_MPI=OFF ..

# Disable NetCDF I/O
$ cmake -DMUGRID_ENABLE_NETCDF=OFF ..

# Disable Python bindings
$ cmake -DMUGRID_ENABLE_PYTHON=OFF ..

# Disable tests
$ cmake -DMUGRID_ENABLE_TESTS=OFF ..

# Disable examples
$ cmake -DMUGRID_ENABLE_EXAMPLES=OFF ..

GPU support:

GPU support is disabled by default and must be explicitly enabled. See the GPU Computing documentation for detailed usage information.

# Enable NVIDIA CUDA support
$ cmake -DMUGRID_ENABLE_CUDA=ON ..

# Enable AMD ROCm/HIP support
$ cmake -DMUGRID_ENABLE_HIP=ON ..

# Specify CUDA target architectures (70=V100, 80=A100, 90=H100)
$ cmake -DMUGRID_ENABLE_CUDA=ON -DCMAKE_CUDA_ARCHITECTURES="70;80;90" ..

# Specify HIP target architectures (gfx906=MI50, gfx90a=MI200, gfx942=MI300)
$ cmake -DMUGRID_ENABLE_HIP=ON -DCMAKE_HIP_ARCHITECTURES="gfx906;gfx90a" ..

Combining options:

You can combine multiple options in a single command:

# Build with CUDA but without MPI
$ cmake -DMUGRID_ENABLE_CUDA=ON -DMUGRID_ENABLE_MPI=OFF -DCMAKE_BUILD_TYPE=Release ..

# Build minimal version (no MPI, no NetCDF, no tests)
$ cmake -DMUGRID_ENABLE_MPI=OFF -DMUGRID_ENABLE_NETCDF=OFF -DMUGRID_ENABLE_TESTS=OFF ..

Getting help and reporting bugs¶

µGrid is under active development and the documentation may be spotty. If you run into trouble, please contact us by opening an issue and someone will answer as soon as possible. You can also check the API NumPy reference.

Contribute¶

We welcome contributions both for new features and bug fixes. New features must be documented and have unit tests. Please submit merge requests for review.