Last updated: 2026-08-03 15 min read

Introduction

What is Boreas FFD?

Boreas is an FFD (Fast Fluid Dynamics) solver for quickly screening temperature, velocity, and contaminant distributions in indoor airflows — data center rack layouts, HVAC, cleanrooms, vehicle cabins, and similar spaces. FFD is a method established by Zuo & Chen (2009), adapting Stam's Stable Fluids (1999) for indoor airflow; Boreas is clew's own implementation, adding techniques such as an octree grid and GPU acceleration. It does not aim for "full-CFD" accuracy; instead, while providing a level of accuracy adequate for engineering judgment, it targets a practical screening tool that always converges stably even with coarse grids and large time steps. The grid is a cell-octree Cartesian mesh (similar to OpenFOAM snappyHexMesh's castellated stage), and walls and solid surfaces are handled as stair-steps rather than body-fitted.

Boreas was originally built for a customer who needed airflow modeling and a digital twin for a semiconductor fab process line. With a small enough grid it can run close to real time, and with a coarse grid it can sweep dozens to hundreds of cases for comparison. It's designed for teams where commercial CFD license cost and compute time become the bottleneck — semiconductor fab facilities teams, IDC/HVAC EPC firms, and similar — to quickly screen candidate designs or to serve as a digital twin's simulation engine.

Key features

  • Arbitrary-shaped domains: meshes only the interior space (an STL boundary), not just a box — cabins, bent-corridor rooms, etc.
  • Three-tier precision: fp32 fields + fp64 accumulation/geometry (guards against drift and geometric robustness issues)
  • Physics models: buoyancy (Boussinesq) · Chen/LVEL turbulence · rack/CRAC/ circulator recirculation · multi-species · age-of-air · volumetric heat sources · time-averaging · conservative upwind advection (for heat/contaminant balance reports)
  • Unconditionally stable time integration: semi-Lagrangian advection (no CFL restriction) + implicit diffusion/projection

Good fit for

  • Quickly screening temperature, velocity, and contaminant distributions in indoor HVAC, data center rack halls, cleanrooms, and similar spaces
  • Sweeping many layout options (diffuser placement, rack arrangement, circulator capacity, etc.) with a coarse grid and many runs
  • Checking steady-state heat/contaminant balances (rack heat generation = heat removed, CO₂ generation = exhaust outflow, etc.)

Not a good fit for

  • Cases that need finely resolved boundary layers near walls — at indoor-scale Reynolds numbers (Re ~ 10⁴–10⁵), boundary layers are millimeter-thick, which the screening grids used here (cm–dm) cannot resolve. The default turbulence model (laminar) only accounts for molecular viscosity, so wall deceleration and jet spreading can be largely absent, producing an essentially inviscid-like solution.
  • Cases that need accurate representation of curved geometry — walls are always stair-stepped; body-fitted/cut-cell meshing is not supported.
  • Cases that need error under ~10% against literature benchmarks — that's roughly Boreas's own validated error range (see "Notes on interpreting results" below). This is not a substitute for high-fidelity CFD.
  • Domains large enough to require distributed execution across multiple nodes — this is single-node only (no MPI).

System requirements

Runs on Windows or Linux. Both GPU and CPU are supported. OpenMP can be used to take advantage of multiple cores (--threads N, optional — results are bit-identical regardless of thread count).

Installation

Get the prebuilt package from your distribution channel and unzip it — no compilation needed.

Windows

  1. Unzip the distribution package (zip) into a folder of your choice (e.g. C:\Boreas)
  2. (Optional) Add that folder to PATH if you don't want to type the full path every time
  3. Verify the install:
    bat
    boreas2.exe version

Linux

sh
tar -xzf boreas2--linux64.tar.gz
cd boreas2
./boreas2 version   # verify the install

Quick-start tutorial

Step 1: Write a case file

Boreas defines the domain, boundary conditions, physical properties, and run options in a single JSONC (JSON-with-comments) case file. The example below is a minimal 5m × 5m × 5m room with a ceiling diffuser supplying cool air and two floor corner outlets exhausting it:

jsonc
// 5m room + ceiling circular diffuser (cylinder patch) supply + 2 floor corner outlets
{
  "grid": { "h0": 0.25, "cells": [20, 20, 20], "bands": [] },
  "params": {
    "dt": 0.5, "turbulence": "chen", "init_temp": 26,
    "buoyancy": { "beta": 3.4e-3, "t_ref": 26 },
    "pressure": { "max_cycles": 60, "tol": 1e-10 }
  },
  "bc": [
    // r=0.5 circular diffuser at ceiling center — cool air discharged downward (cylinder patch)
    { "type": "inlet", "region": { "type": "cylinder", "center": [2.5, 2.5, 5.0],
                                   "r": 0.5, "h": 0.02 }, "speed": 1.5, "temp": 18 },
    { "type": "outlet", "region": { "type": "box", "center": [0.5, 0.5, 0],
                                    "size": [1, 1, 0] } },
    { "type": "outlet", "region": { "type": "box", "center": [4.5, 4.5, 0],
                                    "size": [1, 1, 0] } }
  ],
  "run": { "steps": 120, "log_every": 40,
           "vtk_flow": "flow.vtu", "fluid_only": true }
}

The full schema (every key, default value, and comments) is in docs/case-reference.jsonc.

Step 2: Run it

sh
boreas2 my_case.jsonc --threads 4

--threads N sets the number of OpenMP threads (default 1 = serial).

Step 3: Check the results

Running the case creates a /_NNN/ folder (the number increments on every rerun, preserving prior results) containing:

  • flow.vtu (+ snapshot .pvd) — the full flow field
  • slice.vtu — a cross-section
  • monitors.csv — time series at the monitor points you specified
  • run.log — the run log

Open these files in ParaView to inspect the flow structure (streamlines, velocity vectors, temperature distribution, etc.).

Notes on interpreting results

  • "Stable" does not mean "accurate." Unconditional stability here means the solver won't diverge — not that the result is physically accurate. If dt is set too large or the grid too fine relative to it (diffusion number ν·dt/h² ≫ 1), the pressure/diffusion solver may advance to the next step before fully converging, losing effective viscosity — this can inflate natural-convection velocities by 20% or more. If a result looks unexpectedly large or small, check pressure.tol/max_cycles first.
  • Choose the advection scheme to match your goal. The default advection: "semi" (semi-Lagrangian) is fast but non-conservative, so heat/mass balances can drift by a few percent over long runs. If your goal is a steady-state balance report — rack heat generation = heat removed, CO₂ generation = exhaust outflow, etc. — switch to advection: "upwind".
  • Choose the turbulence model based on whether near-wall effects matter. The default laminar only accounts for molecular viscosity, so wall deceleration and jet spreading can be missing. If near-wall behavior matters — diffuser discharge, wall cooling, etc. — use chen (zero-equation, wall-distance based) or lvel (wall-function based, naturally reverts to laminar at low velocities). Note that chen stiffens diffusion and can noticeably increase per-step cost (sometimes more than 2×).
  • Align equipment/wall surfaces to grid faces. Keep box surface coordinates for equipment such as racks and circulators aligned to multiples of the grid size (h0). Misalignment can shift the stair-stepped surface onto a different grid face than intended, causing zero-thickness inlet/outlet patches to miss their target — this has happened in practice.
  • Through-flow equipment needs a solid body. Inlet/outlet patches work by promoting a solid's surface to a wall, so "bladeless" patches without an underlying solid body are not supported.
  • Use early steady-state termination. Enabling run.stop_when_steady detects when the flow reaches steady state and can cut the step count substantially (64% fewer steps than a fixed step count in one real case).
  • Validated error range. Results have been validated against literature benchmarks (lid-driven cavity, natural convection, etc.) to within roughly 10% error — see the "Validation" documents on this site for details.

Next steps

  • Full case file options: docs/case-reference.jsonc (recirculators, species, time-averaging, etc.)
  • Validation against literature benchmarks: the "Validation" documents on this site (lid-driven cavity, natural convection, indoor forced/mixed convection, etc.)
  • Running many cases at once: the batch-run script included in the distribution package