|
hemocell
|
#include <hemocell.h>

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. | |
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.
|
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 | |
| 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).
| configFileName | main configuration file (or a checkpoint.xml to restart), relative to the working directory |
| argc,argv | command-line arguments, passed on to plb::plbInit() |
| mpi_handle | MPIHandle::External if MPI is already initialised (e.g. by the test runner); plb::plbInit() is then not called. |
| caseConfiguration | leave 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 | ( | ) |
|
inline |
Add a cell type with constitutive model Mechanics.
Example: addCellType<RbcHighOrderModel>("RBC", RBC_FROM_SPHERE).
| name | identifier 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. |
| constructType | shape of the reference mesh: RBC_FROM_SPHERE, ELLIPSOID_FROM_SPHERE (platelet), WBC_SPHERE or MESH_FROM_STL (constants in constant_defaults.h). |
| T HemoCell::calculateFractionalLoadImbalance | ( | ) |
Calculate and return the fractional load imbalance.
| 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.
| void hemo::HemoCell::doLoadBalance | ( | ) |
Load balance the domain (only necessary with nAtomic blocks > nMpi processors, also checkpoints.
| 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!
| 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().
| boundaryRepulsionConstant | k [pN], >= 0 (converted with param::df) |
| boundaryRepulsionCutoff | r_c [micrometre], > 0 |
| timestep | update interval [iterations]; equal to the particle repulsion interval if that is enabled too |
|
inline |
|
inline |
Iteration of the last writeOutput() call. Residence times are advanced by the number of iterations since then, so it is stored in checkpoints.
| 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.
| 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.
| 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.
| 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.
| void HemoCell::latticeEquilibrium | ( | T | rho, |
| hemo::Array< T, 3 > | vel | ||
| ) |
Initialise every fluid node at equilibrium.
| rho | density [lattice units, typically 1] |
| vel | velocity [lattice units] |
| void HemoCell::loadCheckPoint | ( | ) |
Load the checkpoint given as configuration (see the case's cfg->checkpointed branch). Collective.
| 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.
|
private |
To be run right before the first iteration, all checking should move here.
| void HemoCell::saveCheckPoint | ( | ) |
Save a checkpoint to <outputDirectory>/<checkpointDirectory>/. Collective.
| void HemoCell::setCEPACOutputs | ( | std::vector< int > | outputs | ) |
Select the CEPAC fields written by writeOutput() (OUTPUT_* constants).
| void HemoCell::setFluidOutputs | ( | std::vector< int > | outputs | ) |
Select the fluid fields written by writeOutput() (OUTPUT_* constants).
| 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().
| name | cell type name (as given to addCellType()) |
| distance | [micrometre] |
| 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.
|
inline |
Restore the last output iteration (used when loading a checkpoint).
| 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()).
| void HemoCell::setOutputs | ( | std::string | name, |
| std::vector< int > | outputs | ||
| ) |
Select the cell fields written by writeOutput() for a cell type.
| name | cell type name (as given to addCellType()) |
| outputs | OUTPUT_* constants from constant_defaults.h, e.g. {OUTPUT_POSITION, OUTPUT_TRIANGLES, OUTPUT_FORCE} |
| 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.
| 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().
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()).
| repulsionConstant | k [pN], >= 0 (converted with param::df) |
| repulsionCutoff | r_c [micrometre], > 0 |
| 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.
| void HemoCell::setSolidifyTimeScaleSeperation | ( | unsigned int | separation | ) |
Run the solidification step every separation iterations (default 1).
| void HemoCell::setSystemPeriodicity | ( | unsigned int | axis, |
| bool | bePeriodic | ||
| ) |
Set periodicity of the fluid and the particle field together. Call after initializeCellfield() and before loadParticles().
| axis | 0 (x), 1 (y) or 2 (z) |
| bePeriodic | whether the domain is periodic along axis |
| 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.
| 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.
| bool hemo::HemoCell::boundaryRepulsionEnabled = false |
| HemoCellFields* hemo::HemoCell::cellfields = 0 |
The cellfields contains the particle field and all celltypes.
| Config* hemo::HemoCell::cfg = 0 |
| bool hemo::HemoCell::checkpointOnExitSignal = true |
Save a checkpoint before exiting on a caught signal.
| plb::XMLreader* hemo::HemoCell::documentXML = 0 |
| plb::MultiBlockLattice3D<T, DESCRIPTOR> * hemo::HemoCell::domain_lattice = 0 |
| plb::MultiBlockManagement3D * hemo::HemoCell::domain_lattice_management = 0 |
| unsigned int hemo::HemoCell::exitSignalCheckInterval = 100 |
Iterations between collective exit-signal checks in iterate() (0 disables them).
| unsigned int hemo::HemoCell::iter = 0 |
|
private |
|
private |
Store the last time (iteration) output occured.
| plb::MultiBlockLattice3D<T, DESCRIPTOR>* hemo::HemoCell::lattice = 0 |
The fluid lattice.
| double* hemo::HemoCell::LEcurrentDisplacement = 0 |
Current Lees-Edwards displacement, owned by the LeesEdwardsBC object (helper/leesEdwardsBC.h), which sets this pointer.
| bool hemo::HemoCell::leesEdwardsBC = false |
| LoadBalancer* hemo::HemoCell::loadBalancer = 0 |
|
private |
| bool hemo::HemoCell::outputInSiUnits = true |
Write output in SI units (default) or in lattice units.
| bool hemo::HemoCell::partOfpreInlet = false |
| PreInlet* hemo::HemoCell::preInlet = 0 |
| plb::MultiBlockLattice3D<T, DESCRIPTOR> * hemo::HemoCell::preinlet_lattice = 0 |
| plb::MultiBlockManagement3D* hemo::HemoCell::preinlet_lattice_management = 0 |
| bool hemo::HemoCell::repulsionEnabled = false |
|
private |
Checked in iteration, do sanity check when not yet done.