Add paper-aligned two-way HGFD and fluidized-bed validation

[Galigeigei-Z]

What changed

• add a two-dimensional, isothermal, laminar HGFD fluid participant with fluid-fraction-weighted conservative momentum transport and variable-porosity pressure projection
• implement paper-aligned Gidaspow Wen--Yu/Ergun layer drag, exponential particle relaxation, beta-weighted field aggregation, and equal-and-opposite momentum exchange
• implement four-direction stochastic HGFD transport, strict P_tot < 0.5, rejected-event velocity handling, and the virtual-displacement momentum budget
• preserve the paper's staggered HGD-then-CFD update order on a co-located cell-centred grid
• add the three Case 1 single-particle settling configurations and a repeatable validation plot script
• add the runnable gas-fluidized-bed example, diagnostics, saved fields, and regenerated animated visualization
• document exact parity, paper inconsistencies, and inputs that are not publicly available

Previews

Field assets: MP4 · ParaView PVD

Why

The public HGD implementation does not contain the 2026 paper's inertial fluid coupling. This PR reconstructs the published equations and validation inputs while keeping the uncoupled defaults unchanged. It also makes the reproducibility boundary explicit: the authors' extended OpenFOAM pisoFoam participant, preCICE configuration, and complete Cases 2--4 inputs have not been published.

Two printed details in the paper require a physically consistent interpretation to reproduce Figure 4: the heterarchical coordinate carries mass density rho_p / M, and the fluid source must be equal and opposite to the particle drag. Both choices and their rationale are documented.

Validation

• python -m pytest -q test/test_fluid.py test/test_helpers.py test/test_operators.py -- 17 tests pass

• black --check HGD/fluid.py HGD/motion/hgfd.py scripts/plot_hgfd_case1.py test/test_fluid.py

• flake8 HGD/fluid.py HGD/initial.py HGD/motion/hgfd.py scripts/plot_hgfd_case1.py test/test_fluid.py

• mkdocs build -- succeeds; strict mode only reports pre-existing repository warnings

• all three full two-way-coupled Case 1 runs complete at 4,000 steps each

• terminal-speed differences from the paper HGFD curves: +0.36% (0.5 mm), +0.11% (1.5 mm), +0.07% (2.0 mm)

• fluidized-bed example completes 600 deterministic steps

• final weighted-continuity residual: 3.14e-12 1/s

• maximum stochastic transition probability: 0.0128 < 0.5

• ParaView export: 31 monotonic time steps, with 10 validated particle/fluid cell arrays

• generated GIF and H.264 MP4 both pass full-stream decode

Scope

The bundled fluid participant matches the published governing equations and named spatial schemes, but it is not matrix-, PISO-iteration-, or binary-identical to the unpublished OpenFOAM/preCICE participant. The implementation is a 2-D laminar research solver, not a validated industrial bubbling, slugging, turbulent, or reacting fluidized-bed model.