hummingbird

Solving the self-adjoint angular flux transport equation using spectral elements on Cartesian geometry.

Installation

Hummingbird uses pixi to manage its build tools and dependencies, so no manual installation of cmake, compilers, or third-party libraries is required.

pixi is a cross-platform package and workspace manager built on the conda ecosystem. It resolves all of the project's dependencies (compilers, cmake, ninja, and libraries like armadillo and vtk) from conda-forge into a self-contained environment under .pixi/, pinned by a lockfile (pixi.lock) so every contributor and CI run builds against identical dependency versions. This means:

• No system-wide installation of build tools or libraries, and no risk of conflicting with other projects' dependencies on your machine.
• Reproducible builds, since the lockfile guarantees everyone resolves the same dependency versions instead of "works on my machine" drift.
• A single command (pixi install) sets up everything needed to build, test, and generate documentation for the project.

Installing pixi

If you don't already have pixi installed, install it with:

curl -fsSL https://pixi.sh/install.sh | bash

See the pixi documentation for other installation methods (Homebrew, Winget, etc.).

Setting up the environment

From the repository root, run:

pixi install

This reads pixi.toml / pixi.lock and creates a local environment (in .pixi/) containing all the dependencies listed below, resolved from the conda-forge channel. Supported platforms are linux-64 and osx-arm64.

Usage

Hummingbird defines its build/test/documentation steps as pixi tasks, which run inside the pixi-managed environment.

pixi run dev

Runs the full development workflow (cmake --workflow --preset dev), which:

1. Configures the project with CMake (debug preset).
2. Builds all targets, including the test_hummingbird test binary.
3. Tests the build by running the full test suite with CTest (test-all preset), stopping on the first failure and printing output for any failures.

pixi run dev

pixi run docs

Builds the Doxygen HTML documentation into docs/documentation.html:

pixi run docs

Testing

Tests are written with GoogleTest and discovered automatically via CTest (gtest_discover_tests). pixi run dev builds and runs the entire suite in one step. If you've already configured/built the project and just want to re-run the tests:

ctest --test-dir build --output-on-failure

Manual CMake configuration

For editor/IDE integration (e.g. CLion, VS Code with the CMake Tools extension), a pixi CMake preset is also provided, which points CMake at the compilers and tools installed by pixi (.pixi/envs/default/bin) instead of using pixi run directly:

cmake --preset pixi

Dependencies

All dependencies below are installed automatically by pixi install (see pixi.toml for exact version constraints):

Package	Purpose
cmake	Build configuration
ninja	Build system used by CMake
armadillo	Linear algebra
doxygen	Documentation generation
graphviz	Diagrams for generated documentation
gtest	Unit testing framework
nlohmann_json	JSON parsing for simulation input files
gmsh	Mesh generation/import
vtk	Visualization output
fmt	String formatting

Acknowledgements

This project contains code either directly copied or repurposed from starling, licensed under BSD 3-Clause.

Third Party

This project contains code from TinyExpr++, the C++ version of the TinyExpr library. These include tinyexpr.h and tinyexpr.cpp. TinyExpr++ is licensed under zlib, the language for which can be found here. No part of this code has been modified from its original source aside from the include path in tinyexpr.cpp to the header file and a reformatting by clang-format to match the project.