Units and scaling

Units and scaling#

HemoCell works internally in lattice (LBM) units, but you specify your problem in physical (SI) units. Understanding the mapping between the two is the single most important thing for setting up a stable, meaningful simulation.

The two quantities that anchor the mapping are set in the <domain> block of your config.xml (see Config.xml):

  • <dx> — the physical length of one lattice cell, in metres.

  • <dt> — the physical duration of one LBM time step, in seconds.

Together with the fluid density <rhoP> and kinematic viscosity <nuP>, these fix the conversion factors between SI and lattice units for every other quantity (velocity, force, viscosity, …). HemoCell computes the derived lattice-Boltzmann parameters for you through the Parameters helper (aliased as param in case files), for example:

param::lbm_pipe_parameters((*hemocell.cfg), 50);
param::printParameters();

Always call param::printParameters() early in a case so you can check the resulting lattice values before committing to a long run.

Note

<dx> defaults to 0.5 µm in the example cases. Positions in .pos files are given in micrometres, so a cell centre listed as 10 12 24 lands at lattice node 20 24 48 when dx = 0.5 µm. This frequently surprises new users — see the FAQ.

Choosing dx and dt for stability#

The lattice Boltzmann method is only stable and accurate within a limited range of its internal parameters. Two rules of thumb apply to essentially every HemoCell simulation:

  • keep the lattice velocity low: u_lbm < 0.1 (well below the lattice speed of sound), and

  • keep the relaxation time above its singular point: tau > 0.5 (values comfortably above 0.5, e.g. ~1.0, are safest).

Because tau is determined by nuP, dx and dt, you tune stability primarily by adjusting the resolution dx and the time step dt. A negative <dt> tells HemoCell to set tau = 1 and back-calculate the corresponding time step, which is a convenient starting point.

If a run shows jiggling cells, travelling waves, exploding densities, or cells being deleted, the LBM parameters are the first thing to check — see Numerical instabilities.

Time-scale separation#

The fluid time step required for LBM stability is often much smaller than the time step the cell mechanics would need on their own. Recomputing the membrane constitutive model and re-interpolating velocities every single fluid step would therefore be wasteful. HemoCell exploits this with time-scale separation: expensive steps are run only once every N fluid iterations.

The relevant controls, set from a case file, are:

Call

Effect

HemoCell::setMaterialTimeScaleSeparation()

Re-evaluate a cell type’s mechanical model every N fluid steps (the most expensive step).

HemoCell::setParticleVelocityUpdateTimeScaleSeparation()

Interpolate the fluid velocity onto the particles every N fluid steps.

HemoCell::setRepulsionTimeScaleSeperation()

Update the cell–cell repulsion force every N fluid steps.

HemoCell::setInteriorViscosityTimeScaleSeperation()

Update the interior-viscosity correction every N steps (and the expensive full-grid ray-tracing pass less frequently still).

Typical values in the examples are around 20 for the material model and 5 for the velocity update, but the right separation depends on your dt and flow conditions.

Rule of thumb

Larger separations run faster but introduce a longer delay before cells “feel” the fluid (and vice versa). If you increase a separation and the simulation becomes unstable or cells lag the flow, reduce it again.

Force limiting#

To keep a simulation stable even when a cell is momentarily subjected to extreme deformation, the maximum force the constitutive model may exert on the fluid is capped at compile time by FORCE_LIMIT (default 50 pN per surface point, see config/constant_defaults.h). This trades a little physical fidelity for unconditional stability of the fluid coupling; it does not make an otherwise wrong model correct.