hemocell
Loading...
Searching...
No Matches
Public Types | Public Member Functions | Public Attributes | Private Member Functions | Private Attributes | List of all members
hemo::HemoCell Class Reference

#include <hemocell.h>

Collaboration diagram for hemo::HemoCell:
Collaboration graph
[legend]

Public Types

enum class  MPIHandle { Internal , External }
 Switch to indicate if the MPI instance is managed externally. The MPI instance is typically invoked when initialising the HemoCell class through the plb::plbInit routine. However, in some scenarios we might want to manually control the MPI environment and do not want HemoCell to setup MPI environment. More...
 

Public Member Functions

 HemoCell (const std::string &configFileName, int argc, char *argv[], HemoCell::MPIHandle mpi_handle=HemoCell::MPIHandle::Internal, const char *caseConfiguration=HEMOCELL_BUILD_CONFIGURATION)
 Create the simulation object (and initialise MPI through Palabos).
 
 ~HemoCell ()
 
void latticeEquilibrium (T rho, hemo::Array< T, 3 > vel)
 Initialise every fluid node at equilibrium.
 
void initializeCellfield ()
 Create the cell fields and the particle field on the current lattice. Collective. Call after the lattice is created and initialised, before adding cell types.
 
template<class Mechanics >
void addCellType (std::string name, int constructType)
 Add a cell type with constitutive model Mechanics.
 
void setOutputs (std::string name, std::vector< int > outputs)
 Select the cell fields written by writeOutput() for a cell type.
 
void setRepulsion (T repulsionConstant, T repulsionCutoff)
 Enable repulsion between vertices of different cells.
 
void setMaterialTimeScaleSeparation (std::string name, unsigned int separation)
 Evaluate the constitutive model of a cell type every separation iterations (default 1). Must be a multiple of the velocity update interval (setParticleVelocityUpdateTimeScaleSeparation()).
 
void enableSolidifyMechanics (std::string name)
 
void setParticleVelocityUpdateTimeScaleSeparation (unsigned int separation)
 Interpolate the fluid velocity to the vertices (and synchronise the particle envelopes) every separation iterations (default 1). It must divide the material, repulsion and interior-viscosity intervals. Separations > 1 introduce a numerical error.
 
void setRepulsionTimeScaleSeperation (unsigned int separation)
 
void setSolidifyTimeScaleSeperation (unsigned int separation)
 Run the solidification step every separation iterations (default 1).
 
void setInteriorViscosityTimeScaleSeperation (unsigned int separation, unsigned int separation_entire_grid)
 
void enableBoundaryParticles (T boundaryRepulsionConstant, T boundaryRepulsionCutoff, unsigned int timestep=1)
 Enable repulsion between vertices and wall (solid) nodes. Collective (detects the wall nodes next to fluid). Same force law and cap as setRepulsion().
 
void setInitialMinimumDistanceFromSolid (std::string name, T distance)
 Reject initial vertices of a cell type closer than distance to a solid node: vertices within floor(distance / dx) lattice nodes of a wall are not placed and their cells are removed. Call before loadParticles().
 
void setPlaceCellsAcrossPeriodicBoundaries (bool place)
 Also place the cells of the .pos files that cross a periodic boundary (default: off, such cells are skipped and counted in the log).
 
void setFluidOutputs (std::vector< int > outputs)
 Select the fluid fields written by writeOutput() (OUTPUT_* constants).
 
void setCEPACOutputs (std::vector< int > outputs)
 Select the CEPAC fields written by writeOutput() (OUTPUT_* constants).
 
void setSystemPeriodicity (unsigned int axis, bool bePeriodic)
 Set periodicity of the fluid and the particle field together. Call after initializeCellfield() and before loadParticles().
 
void setSystemPeriodicityLimit (unsigned int axis, int limit)
 Number of periodic images of a cell distinguishable along axis (default 100 for each axis). Periodic copies of a cell get IDs shifted by multiples of the cell count; the shifts per axis are 1, limit[0] and limit[0]*limit[1], and the largest shift times the number of cells must fit in an int (checked before the first step). Lower the limits for runs with more than about 200,000 cells.
 
void loadParticles ()
 Place the cells listed in the <name>.pos files (positions in micrometre, rotations in degrees, applied in X, Y, Z order). Collective. Cells that do not fit the domain are removed.
 
void loadCheckPoint ()
 
void saveCheckPoint ()
 Save a checkpoint to <outputDirectory>/<checkpointDirectory>/. Collective.
 
void writeOutput ()
 
void iterate ()
 Advance the coupled fluid and cells by one time step. Collective. The lattice force is reset at the end: a case driven by a body force must set it again after every call.
 
void checkExitSignals ()
 Act on a caught exit signal (SIGINT, SIGTERM, SIGHUP, SIGQUIT, SIGUSR1, SIGUSR2).
 
T calculateFractionalLoadImbalance ()
 Calculate and return the fractional load imbalance.
 
void doLoadBalance ()
 Load balance the domain (only necessary with nAtomic blocks > nMpi processors, also checkpoints.
 
void doRestructure (bool checkpoint_avail=true)
 Restructure the grid, has an optional argument to specify whether a checkpoint from this iteration is available, default is YES!
 
void initializeLattice (plb::MultiBlockManagement3D const &management)
 Initialize the fluid field with the given management, should be done after specifing the pre inlets and before initializing the cellfields.
 
void initializeLatticeFromFlagMatrix (plb::MultiBlockManagement3D const &management, plb::MultiScalarField3D< int > &flagMatrix)
 Create the fluid lattice of a voxelised geometry without a pre-inlet.
 
unsigned int getLastOutputIteration () const
 
void setLastOutputIteration (unsigned int iteration)
 Restore the last output iteration (used when loading a checkpoint).
 

Public Attributes

bool repulsionEnabled = false
 
bool boundaryRepulsionEnabled = false
 
bool leesEdwardsBC = false
 
double * LEcurrentDisplacement = 0
 
bool outputInSiUnits = true
 Write output in SI units (default) or in lattice units.
 
unsigned int exitSignalCheckInterval = 100
 Iterations between collective exit-signal checks in iterate() (0 disables them).
 
bool checkpointOnExitSignal = true
 Save a checkpoint before exiting on a caught signal.
 
PreInlet * preInlet = 0
 
bool partOfpreInlet = false
 
std::map< plint, plint > BlockToMpi
 
LoadBalancer * loadBalancer = 0
 
plb::MultiBlockLattice3D< T, DESCRIPTOR > * lattice = 0
 The fluid lattice.
 
plb::MultiBlockLattice3D< T, DESCRIPTOR > * preinlet_lattice = 0
 
plb::MultiBlockLattice3D< T, DESCRIPTOR > * domain_lattice = 0
 
plb::MultiBlockManagement3D * preinlet_lattice_management = 0
 
plb::MultiBlockManagement3D * domain_lattice_management = 0
 
Config * cfg = 0
 
HemoCellFields * cellfields = 0
 The cellfields contains the particle field and all celltypes.
 
unsigned int iter = 0
 
plb::XMLreader * documentXML = 0
 

Private Member Functions

void sanityCheck ()
 To be run right before the first iteration, all checking should move here.
 

Private Attributes

bool loadParticlesIsCalled = false
 
unsigned int lastOutputAt = 0
 Store the last time (iteration) output occured.
 
std::chrono::high_resolution_clock::duration lastOutput = std::chrono::high_resolution_clock::duration::zero()
 
bool sanityCheckDone = false
 Checked in iteration, do sanity check when not yet done.
 

Detailed Description

The HemoCell class contains all the information, data and methods to set up a basic HemoCell simulation.

Most importantly:

After everything is set HemoCell::iterate() is used to iterate the simulation.

Member Enumeration Documentation

◆ MPIHandle

enum class hemo::HemoCell::MPIHandle
strong

Switch to indicate if the MPI instance is managed externally. The MPI instance is typically invoked when initialising the HemoCell class through the plb::plbInit routine. However, in some scenarios we might want to manually control the MPI environment and do not want HemoCell to setup MPI environment.

Enumerator
Internal 
External 

Constructor & Destructor Documentation

◆ HemoCell()

HemoCell::HemoCell ( const std::string &  configFileName,
int  argc,
char *  argv[],
HemoCell::MPIHandle  mpi_handle = HemoCell::MPIHandle::Internal,
const char *  caseConfiguration = HEMOCELL_BUILD_CONFIGURATION 
)

Create the simulation object (and initialise MPI through Palabos).

Parameters
configFileNamemain configuration file (or a checkpoint.xml to restart), relative to the working directory
argc,argvcommand-line arguments, passed on to plb::plbInit()
mpi_handleMPIHandle::External if MPI is already initialised (e.g. by the test runner); plb::plbInit() is then not called.
caseConfigurationleave the default: it is evaluated where the case calls the constructor, so it carries the compile-time configuration (config/constant_defaults.h) the case was compiled with. A case compiled with another configuration than the library (e.g. linked against the wrong library variant) is a fatal error.

◆ ~HemoCell()

HemoCell::~HemoCell ( )

Member Function Documentation

◆ addCellType()

template<class Mechanics >
void hemo::HemoCell::addCellType ( std::string  name,
int  constructType 
)
inline

Add a cell type with constitutive model Mechanics.

Example: addCellType<RbcHighOrderModel>("RBC", RBC_FROM_SPHERE).

Parameters
nameidentifier of the type; its material is read from <name>.xml and its initial positions from <name>.pos (relative to the working directory). Use the same name in the per-type setters below.
constructTypeshape of the reference mesh: RBC_FROM_SPHERE, ELLIPSOID_FROM_SPHERE (platelet), WBC_SPHERE or MESH_FROM_STL (constants in constant_defaults.h).

◆ calculateFractionalLoadImbalance()

T HemoCell::calculateFractionalLoadImbalance ( )

Calculate and return the fractional load imbalance.

◆ checkExitSignals()

void HemoCell::checkExitSignals ( )

Act on a caught exit signal (SIGINT, SIGTERM, SIGHUP, SIGQUIT, SIGUSR1, SIGUSR2).

Collective: must be called by all ranks. The ranks agree whether any of them caught a signal; if so a checkpoint is saved (unless checkpointOnExitSignal is false) and the program exits with code 1. iterate() calls this every exitSignalCheckInterval iterations.

◆ doLoadBalance()

void hemo::HemoCell::doLoadBalance ( )

Load balance the domain (only necessary with nAtomic blocks > nMpi processors, also checkpoints.

◆ doRestructure()

void HemoCell::doRestructure ( bool  checkpoint_avail = true)

Restructure the grid, has an optional argument to specify whether a checkpoint from this iteration is available, default is YES!

◆ enableBoundaryParticles()

void HemoCell::enableBoundaryParticles ( T  boundaryRepulsionConstant,
T  boundaryRepulsionCutoff,
unsigned int  timestep = 1 
)

Enable repulsion between vertices and wall (solid) nodes. Collective (detects the wall nodes next to fluid). Same force law and cap as setRepulsion().

Parameters
boundaryRepulsionConstantk [pN], >= 0 (converted with param::df)
boundaryRepulsionCutoffr_c [micrometre], > 0
timestepupdate interval [iterations]; equal to the particle repulsion interval if that is enabled too

◆ enableSolidifyMechanics()

void hemo::HemoCell::enableSolidifyMechanics ( std::string  name)
inline

◆ getLastOutputIteration()

unsigned int hemo::HemoCell::getLastOutputIteration ( ) const
inline

Iteration of the last writeOutput() call. Residence times are advanced by the number of iterations since then, so it is stored in checkpoints.

◆ initializeCellfield()

void HemoCell::initializeCellfield ( )

Create the cell fields and the particle field on the current lattice. Collective. Call after the lattice is created and initialised, before adding cell types.

◆ initializeLattice()

void HemoCell::initializeLattice ( plb::MultiBlockManagement3D const &  management)

Initialize the fluid field with the given management, should be done after specifing the pre inlets and before initializing the cellfields.

◆ initializeLatticeFromFlagMatrix()

void HemoCell::initializeLatticeFromFlagMatrix ( plb::MultiBlockManagement3D const &  management,
plb::MultiScalarField3D< int > &  flagMatrix 
)

Create the fluid lattice of a voxelised geometry without a pre-inlet.

The lattice gets the blocks of management (usually voxelizedDomain->getMultiBlockManagement()) and BGK dynamics with Guo forcing (relaxation time param::tau); the nodes where flagMatrix is 0 become bounce-back walls. Periodicity and internal statistics are switched off and the fluid is at rest with density 1. Call lattice->initialize() afterwards, after adding any further boundary conditions or periodicity. The lattice parameters (param::lbm_*_parameters()) must be computed first. Collective.

◆ iterate()

void HemoCell::iterate ( )

Advance the coupled fluid and cells by one time step. Collective. The lattice force is reset at the end: a case driven by a body force must set it again after every call.

◆ latticeEquilibrium()

void HemoCell::latticeEquilibrium ( T  rho,
hemo::Array< T, 3 >  vel 
)

Initialise every fluid node at equilibrium.

Parameters
rhodensity [lattice units, typically 1]
velvelocity [lattice units]

◆ loadCheckPoint()

void HemoCell::loadCheckPoint ( )

Load the checkpoint given as configuration (see the case's cfg->checkpointed branch). Collective.

◆ loadParticles()

void HemoCell::loadParticles ( )

Place the cells listed in the <name>.pos files (positions in micrometre, rotations in degrees, applied in X, Y, Z order). Collective. Cells that do not fit the domain are removed.

◆ sanityCheck()

void HemoCell::sanityCheck ( )
private

To be run right before the first iteration, all checking should move here.

◆ saveCheckPoint()

void HemoCell::saveCheckPoint ( )

Save a checkpoint to <outputDirectory>/<checkpointDirectory>/. Collective.

◆ setCEPACOutputs()

void HemoCell::setCEPACOutputs ( std::vector< int >  outputs)

Select the CEPAC fields written by writeOutput() (OUTPUT_* constants).

◆ setFluidOutputs()

void HemoCell::setFluidOutputs ( std::vector< int >  outputs)

Select the fluid fields written by writeOutput() (OUTPUT_* constants).

◆ setInitialMinimumDistanceFromSolid()

void HemoCell::setInitialMinimumDistanceFromSolid ( std::string  name,
T  distance 
)

Reject initial vertices of a cell type closer than distance to a solid node: vertices within floor(distance / dx) lattice nodes of a wall are not placed and their cells are removed. Call before loadParticles().

Parameters
namecell type name (as given to addCellType())
distance[micrometre]

◆ setInteriorViscosityTimeScaleSeperation()

void HemoCell::setInteriorViscosityTimeScaleSeperation ( unsigned int  separation,
unsigned int  separation_entire_grid 
)

Interior viscosity: update the nodes near membranes every separation iterations and redetect all interior nodes (expensive) every separation_entire_grid iterations; both multiples of the velocity update interval.

◆ setLastOutputIteration()

void hemo::HemoCell::setLastOutputIteration ( unsigned int  iteration)
inline

Restore the last output iteration (used when loading a checkpoint).

◆ setMaterialTimeScaleSeparation()

void HemoCell::setMaterialTimeScaleSeparation ( std::string  name,
unsigned int  separation 
)

Evaluate the constitutive model of a cell type every separation iterations (default 1). Must be a multiple of the velocity update interval (setParticleVelocityUpdateTimeScaleSeparation()).

◆ setOutputs()

void HemoCell::setOutputs ( std::string  name,
std::vector< int >  outputs 
)

Select the cell fields written by writeOutput() for a cell type.

Parameters
namecell type name (as given to addCellType())
outputsOUTPUT_* constants from constant_defaults.h, e.g. {OUTPUT_POSITION, OUTPUT_TRIANGLES, OUTPUT_FORCE}

◆ setParticleVelocityUpdateTimeScaleSeparation()

void HemoCell::setParticleVelocityUpdateTimeScaleSeparation ( unsigned int  separation)

Interpolate the fluid velocity to the vertices (and synchronise the particle envelopes) every separation iterations (default 1). It must divide the material, repulsion and interior-viscosity intervals. Separations > 1 introduce a numerical error.

◆ setPlaceCellsAcrossPeriodicBoundaries()

void HemoCell::setPlaceCellsAcrossPeriodicBoundaries ( bool  place)

Also place the cells of the .pos files that cross a periodic boundary (default: off, such cells are skipped and counted in the log).

A cell whose centre lies in the domain but whose surface crosses a periodic boundary is placed as during a run: as images on both sides of the boundary (shifted by the domain length, with the cell ID shifted as by a crossing). Enable this only for .pos files packed periodically for this domain (e.g. by tools/packCells with the domain size): a file packed for another box size gives overlapping cells at opposite ends. Call after initializeCellfield() and setSystemPeriodicity(), before loadParticles().

◆ setRepulsion()

void HemoCell::setRepulsion ( T  repulsionConstant,
T  repulsionCutoff 
)

Enable repulsion between vertices of different cells.

Force k * r_c / d along the connecting line for d < r_c (k at the cutoff, growing as the vertices approach). The repulsion force of a vertex (with wall repulsion, if enabled) is capped at FORCE_LIMIT. The neighbour search covers adjacent lattice nodes only (cutoffs above one lattice spacing are partially effective). Call after the lattice parameters are computed (param::lbm_*_parameters()).

Parameters
repulsionConstantk [pN], >= 0 (converted with param::df)
repulsionCutoffr_c [micrometre], > 0

◆ setRepulsionTimeScaleSeperation()

void HemoCell::setRepulsionTimeScaleSeperation ( unsigned int  separation)

Recompute repulsion every separation iterations (default 1); a multiple of the velocity update interval and, if wall repulsion is enabled too, equal to its interval.

◆ setSolidifyTimeScaleSeperation()

void HemoCell::setSolidifyTimeScaleSeperation ( unsigned int  separation)

Run the solidification step every separation iterations (default 1).

◆ setSystemPeriodicity()

void HemoCell::setSystemPeriodicity ( unsigned int  axis,
bool  bePeriodic 
)

Set periodicity of the fluid and the particle field together. Call after initializeCellfield() and before loadParticles().

Parameters
axis0 (x), 1 (y) or 2 (z)
bePeriodicwhether the domain is periodic along axis

◆ setSystemPeriodicityLimit()

void HemoCell::setSystemPeriodicityLimit ( unsigned int  axis,
int  limit 
)

Number of periodic images of a cell distinguishable along axis (default 100 for each axis). Periodic copies of a cell get IDs shifted by multiples of the cell count; the shifts per axis are 1, limit[0] and limit[0]*limit[1], and the largest shift times the number of cells must fit in an int (checked before the first step). Lower the limits for runs with more than about 200,000 cells.

◆ writeOutput()

void HemoCell::writeOutput ( )

Write the selected cell, fluid and CEPAC fields (HDF5) and the cell CSV summary for the current iteration. Collective; does not change the simulation state.

Member Data Documentation

◆ BlockToMpi

std::map<plint, plint> hemo::HemoCell::BlockToMpi

◆ boundaryRepulsionEnabled

bool hemo::HemoCell::boundaryRepulsionEnabled = false

◆ cellfields

HemoCellFields* hemo::HemoCell::cellfields = 0

The cellfields contains the particle field and all celltypes.

◆ cfg

Config* hemo::HemoCell::cfg = 0

◆ checkpointOnExitSignal

bool hemo::HemoCell::checkpointOnExitSignal = true

Save a checkpoint before exiting on a caught signal.

◆ documentXML

plb::XMLreader* hemo::HemoCell::documentXML = 0

◆ domain_lattice

plb::MultiBlockLattice3D<T, DESCRIPTOR> * hemo::HemoCell::domain_lattice = 0

◆ domain_lattice_management

plb::MultiBlockManagement3D * hemo::HemoCell::domain_lattice_management = 0

◆ exitSignalCheckInterval

unsigned int hemo::HemoCell::exitSignalCheckInterval = 100

Iterations between collective exit-signal checks in iterate() (0 disables them).

◆ iter

unsigned int hemo::HemoCell::iter = 0

◆ lastOutput

std::chrono::high_resolution_clock::duration hemo::HemoCell::lastOutput = std::chrono::high_resolution_clock::duration::zero()
private

◆ lastOutputAt

unsigned int hemo::HemoCell::lastOutputAt = 0
private

Store the last time (iteration) output occured.

◆ lattice

plb::MultiBlockLattice3D<T, DESCRIPTOR>* hemo::HemoCell::lattice = 0

The fluid lattice.

◆ LEcurrentDisplacement

double* hemo::HemoCell::LEcurrentDisplacement = 0

Current Lees-Edwards displacement, owned by the LeesEdwardsBC object (helper/leesEdwardsBC.h), which sets this pointer.

◆ leesEdwardsBC

bool hemo::HemoCell::leesEdwardsBC = false

◆ loadBalancer

LoadBalancer* hemo::HemoCell::loadBalancer = 0

◆ loadParticlesIsCalled

bool hemo::HemoCell::loadParticlesIsCalled = false
private

◆ outputInSiUnits

bool hemo::HemoCell::outputInSiUnits = true

Write output in SI units (default) or in lattice units.

◆ partOfpreInlet

bool hemo::HemoCell::partOfpreInlet = false

◆ preInlet

PreInlet* hemo::HemoCell::preInlet = 0

◆ preinlet_lattice

plb::MultiBlockLattice3D<T, DESCRIPTOR> * hemo::HemoCell::preinlet_lattice = 0

◆ preinlet_lattice_management

plb::MultiBlockManagement3D* hemo::HemoCell::preinlet_lattice_management = 0

◆ repulsionEnabled

bool hemo::HemoCell::repulsionEnabled = false

◆ sanityCheckDone

bool hemo::HemoCell::sanityCheckDone = false
private

Checked in iteration, do sanity check when not yet done.