Development of Thermal Feature in XLB

[Steriva]

Contributing Guidelines

• I have read and understood the CONTRIBUTING.md guidelines

Description

Adds thermal (scalar) transport and buoyancy-driven (Boussinesq) flow to XLB, along with a set of tutorial notebooks that teach the library step by step, from a basic isothermal flow through fully two-way coupled thermal-flow simulations.

Core library (xlb/): everything tested in JAX

• New scalar/thermal solver: ThermalStepper, ScalarDirichletBC, ScalarNeumannBC, ScalarOutflowBC, LinearEquilibrium, ScalarSource, and an omega_from_diffusivity helper.
• New velocity sets: D2Q5 (cheap stencil for scalar transport) and D3Q7.
• Two-way coupling support: ForcedCollision and ExactDifferenceForce now accept a force vector supplied at call time (not just construction time), which is what lets a temperature-dependent Boussinesq buoyancy force be injected into the flow's collision step every time step without breaking JAX's JIT caching.
• Fix for the outflow boundary condition for scalar fields.

Examples (examples/thermal/):

• Standalone heat conduction (heat_conduction_2d.py), one-way coupled thermal lid-driven cavity, and a 3D flow-past-sphere thermal case.

Tutorials (examples/tutorials/):

• Seven notebooks, each pairing runnable code with explanatory markdown, building in complexity:
  1. 01_lid_driven_cavity_2d — velocity set (D2Q9), boundary conditions, convergence detection, validated against the classic Ghia, Ghia & Shin (1982) benchmark
  2. 02_heat_conduction — scalar solver (D2Q5), Dirichlet/Neumann BCs, no flow
  3. 03_flow_past_cylinder_2d — external unsteady flow, momentum transfer, Strouhal number
  4. 04_pass_scalar_transp_cavity_2d — one-way thermal-flow coupling, Péclet/Nusselt numbers
  5. 05_flow_past_square_thermal_2d — cold obstacle in warm external flow
  6. 06_buoyant_cavity — two-way coupling, Boussinesq force, differentially-heated vertical cavity
  7. 07_rayleighbenard — two-way coupling, bottom-heated Rayleigh–Bénard convection, validated against a Nusselt-number/Rayleigh-number scaling law
• 01_lid_driven_cavity_2d's benchmark comparison uses JSON reference data under examples/cfd/data/cavity-ghia/ (converted from tabulated PDF data via a companion tool, extract-ghia) for Re in {1000, 2500, 5000, 7500, 10000, 12500, 20000, 25000, 30000}; an unsupported Re is handled gracefully rather than failing.
• examples/tutorials/README.md and the top-level README.md updated to list all seven tutorials and point new users there.

Tests (tests/):

• New coverage for the thermal stepper (JAX backends) and the linear equilibrium operator.

Type of change

• New feature (non-breaking change which adds functionality)
• Documentation update

How Has This Been Tested?

• New unit tests added under tests/thermal/ (JAX backends) and tests/equilibrium/ for the new operators.

• All seven tutorial notebooks run end-to-end on the JAX backend (CPU); outputs and figures were inspected manually for physical plausibility (e.g. lid-driven-cavity velocity profiles against Ghia et al., Rayleigh–Bénard convection rolls and Nusselt number against the expected scaling law).

• JAX pytest tests pass

Linting and Code Formatting

Make sure the code follows the project's linting and formatting standards. This project uses Ruff for linting.

To run Ruff, execute the following command from the root of the repository:

ruff check .

• Ruff passes

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[hsalehipour]

Looks great! thank you

[Steriva]

I have read the CLA Document and I hereby sign the CLA