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:

cmake -S <path-to-mfix> -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:

ctest --test-dir build/ -N

Run all tests:

ctest --test-dir build/

Run a specific test by name:

ctest --test-dir build/ -R DEM01

Run a specific test by index:

ctest --test-dir build/ -I 3,3

Run selected the signle-grid serial DEM tests in the y direction:

ctest --test-dir build/ -R "DEM(01|03|04|05|06)-y_SGS|DEM07_SGS"

Running Unit Tests

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.

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.