Skip to content
polycfdPublic

About

QMOMKit: An application-agnostic C++ library for quadrature-based moment methods to represent and evolve number-density functions in phase space

Resources

Code of conduct

Contributing

Stars

7 stars

Watchers

1 watching

Forks

Repository files navigation

QMOMKit

CI-Release CI-Debug CI-Warnings-GCC CI-Indentation CI-Consumers Paper: arXiv 2610.36189 License: Apache 2.0

QMOMKit is a C++ library implementing quadrature-based moment methods to represent and evolve number density functions in phase space.

QMOMKit reconstructs quadratures, sets of weighted nodes, from the raw moments of a number density and evolves them in phase space: it solves the phase-space part of a population balance equation at one location. Transport in physical space, the mesh, the time loop and the coupling to a host code belong to the host application. Examples of how to couple QMOMKit to host application codes are maintained separately in QMOMKit-Couplings. The library has no third-party dependencies.

Capabilities

QMOMKit provides tools to:

  • reconstruct a quadrature from raw moments, with the quadrature method of moments (QMOM) [McGraw, 1997] for one phase-space coordinate and the conditional quadrature method of moments (CQMOM) [Yuan & Fox, 2011] for several;
  • reconstruct a velocity coordinate with the hyperbolic quadrature method of moments (HyQMOM) [Fox & Laurent, 2022], whose closure keeps the transport of the moments in physical space hyperbolic, and compute its characteristic speeds;
  • reconstruct more nodes than the moments determine with the generalized quadrature method of moments (GQMOM) [Fox, Laurent & Passalacqua, 2023];
  • let the quadrature reconstruction algorithm choose the number of nodes adaptively and bound the quadrature abscissas to an interval;
  • choose the CQMOM conditioning order without changing the definition of the phase space;
  • advance a state in phase space by operator splitting (Strang or Lie) of node advection and moment sources, including exchange across phase-space boundaries;
  • check whether moments are realizable on a given support;
  • rebuild states from moments that the host has transported in physical space;
  • set up a case in C++ or from a .qmom configuration file, with moments given explicitly or generated from analytical distributions, mixtures and independent products;
  • write moment and quadrature histories;
  • compare with finite-sample Monte Carlo references from the optional companion package.

A first example

Reconstructing a two-node quadrature from a raw moment sequence:

#include <qmomkit/qmom.hpp>

#include <iostream>

int main()
{
    // Raw moments m0..m3 for two nodes:
    // weights {0.4, 0.6}, abscissas {-1.0, 2.0}.
    const qmomkit::MomentSet moments({1.0, 0.8, 2.8, 4.4});
    const std::size_t node_count = 2;

    const qmomkit::QmomResult result = qmomkit::compute_qmom(moments, node_count);
    if (!result.ok())
    {
        std::cerr << "QMOM failed: " << result.message << '\n';
        return 1;
    }

    for (std::size_t node = 0; node < result.weights.size(); ++node)
    {
        std::cout << "node " << node << ": weight=" << result.weights[node]
                  << ", abscissa=" << result.abscissas[node] << '\n';
    }
}

Getting started builds on this to cover configuration and phase-space evolution.

Installation

QMOMKit requires CMake 3.16 or newer and a C++17 compiler.

From the repository root:

cmake -S . -B build
cmake --build build
cmake --install build

Unless CMAKE_INSTALL_PREFIX is set, this installs into install/ inside the repository rather than a system-wide location. The examples assume this default.

Applications using QMOMKit can link to the installed CMake target:

find_package(QMOMKit CONFIG REQUIRED)
target_link_libraries(my_application PRIVATE qmomkit::qmomkit)

Point CMAKE_PREFIX_PATH at the QMOMKit install prefix when configuring your application. See Installation and Getting started for details.

Examples and tools

The standalone examples progress from basic QMOM and CQMOM reconstruction and initialization to phase-space evolution and operator-splitting workflows, adaptive quadrature and conditioning diagnostics, demonstrations using multidimensional physical models, and matched Monte Carlo comparisons. See the examples index and the list of examples in the user guide.

Two companion tools live under tools/:

  • tools/monte_carlo/ samples populations, evolves the samples and estimates their moments, as a reference for QMOMKit; see its README.
  • tools/plotting/ provides optional plotting helpers for QMOMKit-native histories; see the plotting README.

Testing

The test suite consists of:

  • unit tests for local behavior and failure paths;
  • component regression tests for important interactions;
  • verification tests against analytical, manufactured, convergence, or reconstruction references;
  • public-header checks; the installed-package consumer check runs separately.

Build and run it in a Debug build, because the unit tests use assert():

cmake -S . -B build-tests -DCMAKE_BUILD_TYPE=Debug -DQMOMKIT_BUILD_TESTS=ON
cmake --build build-tests --parallel
ctest --test-dir build-tests --output-on-failure

See the testing guide for details.

Documentation

Repository structure

QMOMKit/
├── .github/workflows/                # Continuous integration
├── include/qmomkit/                  # Installed public C++ API
├── src/                              # Core implementation
├── cmake/                            # CMake package templates
├── docs/
│   ├── developer/                    # Developer-oriented documentation
│   ├── doxygen/                      # Doxygen documentation
│   └── user/                         # User-oriented documentation
├── examples/                         # Standalone installed-package examples
├── paper/                            # QMOMKit paper, its examples and verification
├── tests/                            # Unit, regression, and verification tests
├── tools/
│   ├── monte_carlo/                  # Monte Carlo companion code
│   ├── plotting/                     # Plotting scripts
│   └── indent-all, ...               # Formatting helpers used by CI
├── AGENTS.md                         # Instructions for AI coding agents
├── CHANGELOG.md                      # Release history
├── CMakeLists.txt
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── DEVELOPMENT_PHILOSOPHY.md         # How QMOMKit is developed and verified
├── LICENSE
└── README.md

Development philosophy and verification

Generative AI tools have been used extensively during the development of QMOMKit. Their use has reinforced a central principle of the project: confidence in scientific software should come from evidence rather than from the origin of an implementation. Neither human-written nor AI-assisted code is inherently correct.

QMOMKit therefore relies on a deliberately rigorous approach to testing, numerical verification, and documentation, so that its behavior can be checked rather than taken on trust. See DEVELOPMENT_PHILOSOPHY.md for the full statement and for where that evidence lives.

How to cite

If QMOMKit contributes to your academic work, please cite the QMOMKit paper:

Fabian Denner, Bruna Campos, and Bruno Blais, QMOMKit: A C++ library for quadrature-based moment methods, arXiv:2610.36189, 2026. doi: 10.48550/arXiv.2610.36189

@misc{qmomkit,
  author  = {Denner, Fabian and Campos, Bruna and Blais, Bruno},
  title   = {QMOMKit: A C++ library for quadrature-based moment methods},
  eprint  = {2610.36189},
  archivePrefix = {arXiv},
  year    = {2026},
  doi     = {10.48550/arXiv.2610.36189},
}

The studies behind the paper can be reproduced from this repository; see the paper studies README.

Authors

License

Copyright 2026 The QMOMKit developers.

QMOMKit is released under the Apache License 2.0. See LICENSE for details.

Funding

The authors gratefully acknowledge funding from:

  • Natural Sciences and Engineering Research Council of Canada (NSERC), funding reference numbers RGPIN-2020-04510 and RGPIN-2024-04805.
  • Canada Research Chair CRC-2022-00340.
  • Deutsche Forschungsgemeinschaft (DFG, German Research Foundation), grant number 458610925.

Contributing

Contributions are welcome. Please see CONTRIBUTING.md for development, testing, and review.

About

QMOMKit: An application-agnostic C++ library for quadrature-based moment methods to represent and evolve number-density functions in phase space

Resources

Code of conduct

Contributing

Stars

7 stars

Watchers

1 watching

Forks

Releases

Contributors

Languages