HemoCell Getting Started¶
Setting up HemoCell from source¶
The following packages are requirements for compiling and/or running HemoCell from source.
Required package |
Tested versions |
|---|---|
4.1.6 |
|
12.3.0 |
|
3.28.3 |
|
1.10.10 |
|
2.7.6 |
|
2.6.0 |
|
2.2.1 |
|
Parmetis (optional) |
4.0.3 |
Note
The currently tested versions are listed. Older/newer versions might work as well. Avoid OpenMPI 2.0.X as in our experience it introduces memory leaks.
On Ubuntu 24.04 these dependencies can be installed by running:
sudo apt-get install -y \
make \
cmake \
g++-12 \
libopenmpi-dev \
libhdf5-dev \
patch \
python3-h5py
The main external dependency Palabos has to be added and patched.
We currently support the v2.2.1 version with an additional small patch. This can be done in two ways.
1. To automatically download this specific Palabos version and apply our patch, run the setup script
hemocell/setup.sh:
# from the hemocell/ root directory execute
./setup.sh
At this point HemoCell should be ready for compilation and development, you can move on to the next section below.
2. Alternatively, you can opt to manually download Palabos through their releases. This is useful if you want to use a different version. After downloading, Palabos
should be extracted to ./hemocell/palabos:
tar -xzf palabos-v2.2.1.tar.gz
mv palabos-v2.2.1 ./hemocell/palabos
After this Palabos must be patched, see hemocell/patch/patchPLB.sh. This can be
done by running ./patchPLB.sh from the ./hemocell/patch/ directory, like
so:
cd hemocell/patch && ./patchPLB.sh
The patching should succeed even though there might be an offset in some files. At this point HemoCell should be ready for compilation and development.
(Optional) Parmetis is used for upcoming load-balancing routines (in development atm.).
It can be installed via adding libparmetis-dev on Ubuntu, or it can be downloaded from their downloads. Due to the
license of Parmetis we cannot distribute it with hemocell. The Parmetis
download should be copied to the ./hemocell/external/ directory. If you
need it because you want load balancing to be enabled you have to extract it
with:
cd hemocell/external && tar -xzf parmetis-4.0.3.tar.gz
Compiling HemoCell from source¶
HemoCell can be compiled from source using CMake. In the root directory
./hemocell/, execute the following instructions to configure and compile
the HemoCell library:
# within ./hemocell/
mkdir build
cd build
cmake ..
cmake --build .
By default only the standard hemocell library is compiled.
This operation can take a while, we suggest a coffee. Note: there might be a set of warning depending
on the versions of the dependencies you are using.
To compile specific examples (that link to the library), you should specify their corresponding compile targets.
These targets are defined for each example and match the example’s directory
name. Thus, to compile the example given in hemocell/examples/pipeflow/pipeflow.cpp
you would compile the target pipeflow. After compilation, the executable
pipeflow is placed under hemocell/examples/pipeflow/. You can indicate
the desired compilation target to CMake through its --target flag:
cmake --build . --target pipeflow
If you intend to compile multiple targets, you can repeat the previous command for
each individual target. Alternatively, if you have CMake version >=3.15,
you can specify a space-separated list of all targets directly, e.g. to compile both
the pipeflow and parachuting examples:
cmake --build . --target pipeflow parachuting
To speed up the compilation process, CMake can exploit parallelism by
providing the --parallel flag. For instance, to use all available cores on
your machine:
cmake --build . --target pipeflow parachuting --parallel $(nproc)
Afterwards, the pipeflow and parachuting executables are placed within
the corresponding example’s directories, i.e. examples/pipeflow and
examples/parachuting.
To test if the library is successfully compiled, you can evaluate the defined tests:
make test
Generating initial positions for cells¶
At some point you might want to run a slightly different geometry, or run your
simulation with a different concentration of cells. For this we offer the
packCells tool which can be found in the ./hemocell/packCells directory.
This tool has a CMake file and can be build with:
cd ./tools/packCells
mkdir build && cd build
cmake ../
make
The result should be a packCells binary. This program offers a rich suite of
options to generate initial conditions for cells. Type ./packCells --help
for an overview of the possible parameters.
The resulting *.pos files can be copied to the case where you want to use
them.
Note
The domain size is defined in microns, not in lattice units. This is to remain independent of the numerical resolution.
Running a HemoCell case¶
A HemoCell case should be run within the folder containing the .xml and
.pos files. You can specify the number of desired processors with
mpirun. The only argument for the case should be the config.xml file.
A typical command looks like this:
cd hemocell/examples/pipeflow
mpirun -n 4 ./pipeflow config.xml
Case output folder¶
The output of a case is usually written to the <case>/tmp folder. The
checkpoints are the .xml and .dat files. When a new checkpoint is
created they are moved to .xml.old and ``.dat.old. The hdf5 output is stored
per timestep in tmp/hdf5 and the csv output in tmp/csv. See
Post-processing the output of a HemoCell case and hemocell/scripts/batchPostProcess.sh for more info.
Post-processing the output of a HemoCell case¶
A HemoCell case produces multiple types of output by default. The simplest is the csv
output which consists of all the information about cells in csv files.
On older HemoCell versions you might want to merge the csv files into a single one per time-step with the script hemocell/scripts/CellInfoMergeCSV.sh
in the tmp directory. Note: HemoCell now does this automatically.
The more detailed output on both the fluid field and particle field is stored in compressed
hdf5 format. We recommend using the XDMF format to make these
readable for visualization tools such as Paraview . To generate *.xmf files run the hemocell/scripts/batchPostProcess.sh
script, e.g. from the folder of a case:
../../scripts/batchPostProcess.sh
When you have created the *.xmf files, they can be opened in Paraview.
Please select the Legacy XDMF file format when loading them in.
Note
The HemoCell .xmf files are not yet XDMF3 compatible. Opening it with an XDMF3 reader might crash the visualization app.
Resuming from a checkpoint¶
To resume from a checkpoint you should run the executable from the directory you
ran it originally from (so the directory with the .xml and .pos files
visible. The first argument should be tmp{_x}/checkpoint/checkpoint.xml instead of
config.xml. HemoCell should then automatically resume from the last saved
checkpoint.
Note
The number of processors used when reusing from a checkpoint does not need to be the same as the number of processors used for the initial run.
