.. _Chap:CITesting: Continuous Integration (CI) =========================== MFIX-Exa uses a GitLab-based Continuous Integration (CI) pipeline to ensure code quality, portability, and correctness across multiple compilers, GPU backends, and build configurations. This page describes what the CI runs, how to reproduce CI behavior locally, and provides a high-level overview of the MFIX-Exa test suite. When the CI Pipeline Runs ------------------------- The CI pipeline is triggered under the following conditions: * **Merge requests** – runs linting, warnings builds, and multi-backend builds. * **Commits to the ``develop`` branch** – runs the full test pipeline. * **Tag pushes** – used for releases. * **Manual runs** – triggered from the GitLab web interface. CI Pipeline Structure --------------------- The MFIX-Exa CI is organized into two distinct execution paths: * **Merge Request (MR) pipelines** – run on every push to a merge request. These pipelines focus on code quality, portability, and build correctness. They include the **Lint**, **Warnings**, and **Build** stages. * **Post-merge pipelines** – run only after changes are merged into the ``develop`` branch. These pipelines run the full **CTest-based test suite** and the specialized **Ascent** and **MPMD** tests. This separation ensures fast feedback during code review while reserving the more expensive tests for post-merge validation. Merge Request Pipeline Stages ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **Lint** Static analysis and formatting checks: * Shell scripts (``shellcheck``) * Spelling (``codespell``) * Tabs and trailing whitespace removal * Python linting (``pylint``) for the GUI **Warnings Builds** Compiler-strict builds using GCC and Clang in both Debug and Release modes. These builds enable extensive warning flags (``-Wall``, ``-Wextra``, ``-Werror``, etc.) to catch portability and correctness issues early. **Builds** Multiple configurations are compiled to ensure portability across compilers and GPU backends: * CPU-only builds * GPU-enabled builds (CUDA, HIP, SYCL) * CSG-enabled builds * MPMD-enabled builds * Unit tests These MR-stage jobs verify that MFIX-Exa builds cleanly and consistently before code is merged. Post-Merge Test Pipeline ~~~~~~~~~~~~~~~~~~~~~~~~ After changes are merged into the ``develop`` branch, the CI runs the full MFIX-Exa test suite. These jobs are triggered by ``rules:`` blocks that restrict execution to the ``develop`` branch. The post-merge pipeline includes: **CTest-based MFIX-Exa Test Suite** Tests are grouped by label: * ``SGS`` – single-grid serial tests * ``MGS`` – multi-grid serial tests * ``TGS`` – tiled-grid serial tests * ``MGP`` – multi-grid parallel tests * ``TGPO`` – tiled-grid parallel OpenMP tests * ``TGSO`` – tiled-grid serial OpenMP tests **Ascent Visualization Test** Runs a small HCS benchmark with Ascent enabled and verifies image output. **MPMD Tutorial Test** Runs the MPMD tutorial example and checks numerical output and generated images. How to Reproduce CI Locally --------------------------- Building MFIX-Exa ~~~~~~~~~~~~~~~~~ A typical local build mirrors the CI configuration. For example: .. code-block:: bash cmake -S -B build \ -DCMAKE_BUILD_TYPE=Release \ -G Ninja cmake --build build --target build_tests unit_tests Additional options (e.g., enabling MPI, OpenMP, GPU backends, or CSG) can be added as needed. Running the MFIX-Exa Test Suite ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ CTest is used to run the MFIX-Exa test suite. All tests are available locally, regardless of which subset the CI runs. List all tests: .. code-block:: bash ctest --test-dir build/ -N Run all tests: .. code-block:: bash ctest --test-dir build/ Run a specific test by name: .. code-block:: bash ctest --test-dir build/ -R DEM01 Run a specific test by index: .. code-block:: bash ctest --test-dir build/ -I 3,3 Run selected the signle-grid serial DEM tests in the ``y`` direction: .. code-block:: bash ctest --test-dir build/ -R "DEM(01|03|04|05|06)-y_SGS|DEM07_SGS" Running Unit Tests ~~~~~~~~~~~~~~~~~~ .. code-block:: bash cmake --build build --target unit_tests ctest --test-dir build/ -R unit_test -V Summary of MFIX-Exa Test Categories ----------------------------------- The MFIX-Exa test suite includes fluid-only tests, particle-only tests, and coupled fluid/particle tests. The CI runs a representative subset of these, while the full suite is available locally. Below is a high-level summary of the test categories and representative cases. .. list-table:: :header-rows: 1 :widths: 15 20 65 * - Test - Type - Description * - ``FLD01`` - Fluid - 2D channel (Poiseuille) flow in a periodic domain. * - ``FLD02`` - Fluid - 2D Couette flow in a channel. * - ``FLD03`` - Fluid - Pressure-driven channel flow with specified pressure boundaries. * - ``DEM01`` - DEM - Freely falling particle with wall collision; verifies spring-dashpot model. * - ``DEM02`` - DEM - Repeated particle bouncing; compares rebound height to theory. * - ``DEM03`` - DEM - Two compressed particles between walls; tests multi-particle contact. * - ``DEM04`` - DEM - Rolling/slipping particle on a rough surface; tests friction model. * - ``DEM05`` - DEM - Oblique particle collisions with a flat wall; tests tangential restitution. * - ``DEM06`` - Coupled - Single particle terminal velocity in a fluid; tests drag models. * - ``DEM07`` - Coupled - Homogeneous Cooling System (HCS); tests granular temperature decay. Details for each case are available in ``tests/README.md``. Relationship to Regression Tests -------------------------------- The CI pipeline **does not** run the CCSE regression suite. * The **Regression Tests** page documents the CCSE/AMReX regression framework. * The CI page documents the **CTest-based MFIX-Exa Test Suite** and infrastructure tests. These two systems are complementary: * CI ensures build correctness and basic functional behavior. * Regression tests ensure numerical consistency across platforms and versions. Developer Expectations ---------------------- * All CI jobs must pass before merging into ``develop``. * Lint and warnings jobs help maintain code quality. * Build jobs ensure portability across compilers and GPU backends. * Test jobs ensure functional correctness. * CI artifacts contain detailed logs for debugging failures.