The HemoCell API

Contents

The HemoCell API#

This page is a task-oriented guide to the hemo::HemoCell class — the object you drive from a case’s main(). It groups the most commonly used methods by what you do with them. For full signatures, overloads, and the rest of the C++ API, see the auto-generated Doxygen reference.

A minimal case follows the same skeleton in every example (see Creating your own HemoCell Case for the full walk-through):

HemoCell hemocell(argv[1], argc, argv);   // 1. construct
hemocell.initializeLattice(management);   // 2. set up the fluid
hemocell.initializeCellfield();           // 3. set up the cells
hemocell.addCellType<RbcHighOrderModel>("RBC", RBC_FROM_SPHERE);
hemocell.setOutputs("RBC", { /* ... */ });
hemocell.setFluidOutputs({ /* ... */ });
hemocell.loadParticles();                 // 4. place the cells
while (hemocell.iter < tmax) {            // 5. run
    hemocell.iterate();
    if (hemocell.iter % tmeas == 0) hemocell.writeOutput();
}

Construction and lifecycle#

Member	Purpose
`HemoCell(configFile, argc, argv)`	Construct the simulation from a `config.xml`. `argc`/`argv` are passed through to Palabos for MPI initialisation.
`HemoCell(configFile, argc, argv, MPIHandle::External)`	Same, but for when MPI is initialised outside HemoCell (HemoCell then skips `plbInit`).
`iter`	The current iteration counter (read it to drive your main loop).
`cfg`	The parsed configuration; read values with `(*hemocell.cfg)["domain"]["dx"].read<T>()`.

Setting up the fluid#

Member	Purpose
`initializeLattice(management)`	Create the fluid lattice from a Palabos `MultiBlockManagement3D`. Call after defining any pre-inlets and before `initializeCellfield()`.
`lattice`	The underlying Palabos `MultiBlockLattice3D` (set periodicity, boundaries, driving force, … directly on it).
`latticeEquilibrium(rho, vel)`	Initialise every fluid node to a density and velocity (lattice units).
`setSystemPeriodicity(axis, bool)`	Make the whole system periodic along an axis.
`setSystemPeriodicityLimit(axis, limit)`	Limit how many times a particle may wrap around a periodic axis.

Setting up the cells#

Member	Purpose
`initializeCellfield()`	Create the cell-fields / particle-field container. Call before adding cell types.
`addCellType<Model>(name, constructType)`	Register a cell type with a mechanical model and a construction method. The `name` must match the `name.xml` / `name.pos` files.
`loadParticles()`	Load the initial cell positions from the `*.pos` files. Call after all cell types, outputs, and periodicity are configured.
`setInitialMinimumDistanceFromSolid(name, d)`	Keep cells at least `d` away from solids at initialisation. Must be called before `loadParticles()`.

Controlling cost (time-scale separation)#

See Time-scale separation for the concept.

Member	Purpose
`setMaterialTimeScaleSeparation(name, n)`	Re-evaluate this cell type’s mechanical model every `n` fluid steps.
`setParticleVelocityUpdateTimeScaleSeparation(n)`	Interpolate fluid velocity to particles every `n` fluid steps.
`setRepulsionTimeScaleSeperation(n)`	Update cell–cell repulsion every `n` fluid steps.
`setInteriorViscosityTimeScaleSeperation(n, n_grid)`	Update interior viscosity every `n` steps, with a full-grid pass every `n_grid` steps.

Optional physics#

Member	Purpose
`setRepulsion(constant, cutoff)`	Enable and parameterise short-range cell–cell repulsion. See Repulsive forces.
`enableBoundaryParticles(constant, cutoff, timestep)`	Enable repulsion between cells and solid boundaries.
`enableSolidifyMechanics(name)`	Enable solidification (clotting) for a cell type. Requires the `SOLIDIFY_MECHANICS` build (see config/constant_defaults.h).

Output and checkpointing#

Member	Purpose
`setOutputs(name, {...})`	Choose which per-cell fields to write for a cell type. See Output fields.
`setFluidOutputs({...})`	Choose which fluid fields to write.
`setCEPACOutputs({...})`	Choose outputs for the advection–diffusion (CEPAC) field, when used.
`outputInSiUnits`	`true` (default) writes output in SI units; `false` writes lattice units.
`writeOutput()`	Write the requested HDF5/CSV output for the current iteration.
`saveCheckPoint()` / `loadCheckPoint()`	Write / restore a full checkpoint (see Resuming from a checkpoint).

Running and load balancing#

Member	Purpose
`iterate()`	Advance the coupled fluid + cells by one fluid time step. If you drive the flow with an external force vector, re-apply it after every `iterate()`.
`checkExitSignals()`	Check whether an exit signal (e.g. from the scheduler) was caught.
`calculateFractionalLoadImbalance()`	Return the current fractional load imbalance across processes.
`doLoadBalance()` / `doRestructure()`	Rebalance / restructure the domain across processes. See Load balancing.