Mirheo
Computational Microfluidics
Mirheo is a GPU high-performance and high-throughput code aimed at simulation of flows at milli- and microscales.
The code uses Dissipative Particle Dynamics method to describe the liquid and its interaction with cells and rigid bodies.
For more information, please refer to the online documentation: http://mirheo.readthedocs.io/
If you want to cite this repository, please use the reference of the corresponding paper [1]:
@article{alexeev2020a,
author = {Dmitry Alexeev and Lucas Amoudruz and Sergey Litvinov and Petros Koumoutsakos},
doi = {10.1016/j.cpc.2020.107298},
journal = {Computer Physics Communications},
month = {mar},
pages = {107298},
publisher = {Elsevier {BV}},
title = {Mirheo: High-performance mesoscale simulations for microfluidics},
url = {http://www.cse-lab.ethz.ch/wp-content/papercite-data/pdf/alexeev2020a.pdf},
year = {2020}
}
Installation
git clone --recursive https://github.com/cselab/Mirheo
cd Mirheo
make install
Publications
[1]
D. Alexeev, L. Amoudruz, S. Litvinov, and P. Koumoutsakos,
“Mirheo: high-performance mesoscale simulations for microfluidics,"
Comput. Phys. Commun., p. 107298, 2020
10.1016/j.cpc.2020.107298
[2]
A. Economides, G. Arampatzis, D. Alexeev, S. Litvinov, L. Amoudruz, L. Kulakova, C. Papadimitriou, and P. Koumoutsakos,
“Hierarchical bayesian uncertainty quantification for a model of the red blood cell,"
Phys. Rev. Appl., vol. 15, iss. 3, 2021.
10.1103/physrevapplied.15.034062
Gallery
|
|
Single ABF in a blood suspension |
Swarm of ABFs in a blood bifurcation |
Changelog
unreleased
- Add extended DPD interactions for visco-elastic fluids (see Ten Bosh 99)
- Add EMA plugin
- Add smooth-velocity-based visco-elastic DPD interactions
- Add compilation option to disable stacktrace (when lib-bfd is not available)
- Add sinusoid forcing term (for kolmogorov forcing)
v1.6.1
- Add ChainObjectVector to model polymers
- Add FENE interactions for ChainObjectVector
- Add Four-roll mill force plugin
- Add plugin to dump ChainObjectVector as polylines
- Allow deformable object vectors to be bounced from walls
-
bug fixes
- No duplicate ObjectVector interactions when interacting with itself through pairwise interactions
v1.6.0
- remove support for config/snapshot. Use checkpoint/restart instead.
- Add growing repulsive LJ pairwise interaction.
- Shardlow integrator: randomize loop order.
v1.5.2
- Add magnetic dipole-dipole interactions plugin
-
interface changes
- Rename magneticOrientation plugin to externalMagneticTorque.
- Stats plugin: restart now adds to the previously written stats instead of overwriting the file.
- Object Stats plugin: restart now adds to the previously written stats instead of overwriting the file.
- Object Stats plugin: takes a filename instead of the path. This allows to avoid to create a directory and is more flexible.
- Velocity control plugin: restart now adds to the previously written stats instead of overwriting the file.
v1.5.1
- Add particle averager plugin
- Add binding (spring) interaction between particle vectors
- Add Shardlow integrator for membranes
- Add pairwise Morse potential
- Docs: Add ADE model and add the corresponding reference.
-
interface changes
- remove
setSpecificPair
from pairwise interactions. The same effect can be obtained by creating more pairwise interactions instead.
- wall force collector plugin: use csv format for output.
- wall force collector plugin: add optional "detailed" dump.
- Shape Bouncers: warnings are now optional, disabled by default.
- Add cupy-compatible bindings to per particle and per object channels.
- Add DomainInfo and time states to the bindings.
- Add MIRHEO_DEBUG_LEVEL environment variable.
-
stats
plugin: reordered filename
and every
arguments. Add optional list of pvs to compute stats from.
-
bug fixes
- RDF plugin: fixed a bug that occured when the max distance was more than a third of the subdomain.
v1.5.0
- Add MSD plugin.
- update pybind11 submodule.
- update variant submodule (now supports nvcc-10.2).
- Cmake options are prepended with
MIR_
- add support for multistage simulations:
run
may be invoked multiple times
- add
Mirheo::deregisterIntegrator
and Mirheo::deregisterPlugin
-
interface changes
- the
dt
parameter was moved from the Mirheo
constructor to the run
, makeFrozenWallParticles
and makeFrozenRigidParticles
methods
-
internal changes
-
MirState::dt
may now be accessed only through MirState::getState
and only during Mirheo::run
.
v1.4.1
- Add Rdf plugin.
- Add developer documentation of plugins.
v1.4.0
- add basic structure for the development documentation
- particle checker plugin dumps all particle fields when triggered
- add experimental and partial support for saving a snapshot of the whole Mirheo state
- add
__main__.py
commands run
and compile_opt
- add classical (non-repulsive) 12-6 Lennard-Jones interaction
- add support for specifying Mirheo's unit system (based on
pint
)
- add energy minimization integrator (gradient descent)
- add VACF computation plugin
-
interface changes
-
grow_until
parameter in membrane forces must be used with initial_length_fraction
(which was hardcoded to 0.5)
- pass particle mass in
mirheo::makeFrozenWallParticles
and mirheo::makeFrozenRigidParticles
- use csv format for plugin outputs instead of txt. This allows to access more easily a given field from python.
-
internal changes
- rename
LJParams
to RepulsiveLJParams
, while LJParams
is now used for the ordinary LJ force
- renamed most private variables: now should have a trailing
_
- enabled -Wshadow_`
-
bug fix: avoid division by zero and nan in several places:
- SDPD kernel
- root finder (concerns bounce back)
-
bug fixes:
- file wrapper: move constructor (added corresponding unit test)
- file wrapper: flushOnClose was not active for special streams
v1.3.3
- Do not create checkpoint folder when not needed
-
bug fix restart for rigid object vector in multi-rank
-
bug fix restart: initial processor assignment; shift relies on redistribution
-
bug fix repulsive LJ: missing factor; add an additional check so the force is continuous at rc
-
internal changes
- state is private
- add -Wconversion for
.cpp
files (not .cu
for now because of thrust)
v1.3.2
-
bug fix: pass substep with random fluctuations had bias rng
- prepend macros with
MIRHEO_
-
interface changes:
- average flow plugins: does not need type
- changed channel names to a more consistent version
- add list of reserved channel names into docs
-
internal changes:
- more modern CMakeLists
- remove unneeded includes
- reduce compilation time: do not include
std::chrono
- reduce compilation time: do not bind all plugin classes
v1.3.1
-
interface changes
- substep integrator now takes a list of interactions
- ObjStats plugin dumps additional type id field if activated
- dump particles plugin does not need type infos
- dump particles plugin supports object and rod data
- remove dump particles rod plugin as it would now be redundant
- add membrane with type id IC
- add filtered membrane forces, which can be used in coordination with the type ids field
- make Mirheo more usable as a library:
- changed the directory structure
- added namespace
mirheo
v1.3.0
-
Add double precision support
can be compiled with CMAKE_FLAGS="-DDOUBLE_PRECISION=ON" mir.make
-
bug fixes:
- fixed cell lists sizes with domain sizes not multiple of rc
- fix in reverse force exchanger
- objectBelonging: split all persistent channels instead of positions and velocities only
-
add PlaneOutletPlugin
for removing particles that cross a given plane
-
add ParticlePortal
plugin that transfers standalone particles from one Mirheo instance to another
-
add ObjectDeleter
helper class for removing marked objects
Work in progress:
- adding
ObjectPortal
plugin that transfers objects from one Mirheo instance to another
- adding
ObjectsToParticles
plugin that destroys objects and transforms them into standalone particles once a condition is met
v1.2.1
v1.2.0
-
Interface changes:
- add function to log compile time options; this can be useful to make sure what was run exactly
- generic Pairwise forces; removed all old pairwise classes from the interface
- use
kBT
everywhere instead of kbt
- use
number_density
instead of density
- rename
mirheo
class coordinator to Mirheo
-
internal changes
- refactored pairwise interaction drivers
- more consistent naming
v1.1.2
-
internal changes:
- enable and fix warnings
- fix initialization bugs
- use forked cselab/cuda_variant
- refactor interaction manager: one for each interaction stage
v1.1.1
-
interface changes: new field
requireShift
in restart files. Newer versions will not be able to read older restart files.
- add unit tests for restart
-
internal changes:
- refactored restart for particle vectors
- fix: test for ROV
- fix: correctly assigns and shift data during restart IC
v1.1.0
-
interface changes:
- no checkpointEvery in registerParticleVector or belongingChercker
-
internal changes:
- refactoring of packers
- add persistent channels support for rod bisegment data
- allow silent log
- pack arguments: logInfo and checkpointInfo for better readability
- add unit tests for packers:
- redistribute (particles, objects, rods)
- exchange (particles, objects)
- test for bounce back reverse exchange:
- rigid
- membrane mesh
- rigid mesh
v1.0.0
-
rename to Mirheo
- add spin based state update for rods with polymorphic states (not validated yet)
-
fix was a possible deadlock for many nodes / many objects suspensions; see commit 4b65e00eba8cf163db3e99e1730e6f16c12fcd26
- add Capsule Rigid Vectors together with bonce back and belonging checkers
- tests: renaming, semantic
v0.17.0
- add CylinderRigidObjectVectors (CROVs)
- add bounce back on rods and CROVs
- add belonging checker for rods and CROVs
-
tests belonging checkers
-
internal changes:
- do not rely on hash for mpi tags in plugins
- generic kernels in belonging and bounce for RigidObjectVectors with analytical shapes
v0.16.3
-
fix MPI cleanup
-
fix restart in pvs now supports extra data
-
fix checkpoint in pvs also shifts the extra data
-
fix dump plugins for xyz, ply and grid h5 timestamp based on simulation time (hence continues after restart)
-
fix float4 data is correctly dumped in checkpoint
-
minor fix stats plugin works for 0 particles
-
interface changes anchor particle plugin accepts multiple anchors
- add pin rod extremity plugin
v0.16.2
-
fix cleanup streams
-
fix more robust filename creation
-
fix more robust parameter passing to rod forces factory
-
interace chanes rod forces:
- change
omega0
to kappa0
- remove
k_visc
- split
k_bounds
into k_s_center
and k_s_frame
- can optionally save energies and polymorphic states
- extend rod IC
- implement polymorphic states
v0.16.1
- add interaction rod-rigid
-
fix free communicator in plugins
v0.16.0
- add
particleChecker
plugin
-
interface changes: average flow plugin does not support float8 entries anymore due to internal changes; use float4 instead
-
internal changes
- particles are now separated into 2 arrays: positions and velocities; this will simplify packing/unpacking kernels
- positions and velocities are stored as other quantities in dataManagers
- old particles are only positions
- vertices are only positions
v0.15.0
-
output change
- restart time-stamps are now continuing from the previous simulation
- output dump files start at t=0
-
fix in TextIO::reader
- internal changes:
- currentStep is long long -> allow longer simulations
- forces are stored as generic arrays -> simplifies a bit cell lists
v0.14.4
-
interface change pass rod width to rod ic
- add bound viscous forces to rod
v0.14.3
-
fix issues #38 and #54
- safe check: cannot register or set objects to coordinator after setup
v0.14.2
-
interface changes Integrator: SubStepMembrane -> SubStep
- SubStep integrator supports rods
- add anchor_particle plugin
- internal changes:
- ids are stored in 64 bits integers
v0.14.1
- Add "rod aware" LJ repulsion interactions
-
interface change DPD, MDPD and LJ interactions have only one constructor each
- Safer parameters in interaction factory: treat unread parameters
v0.14.0
- Add elastic rod interactions: bounds, bending and torsion
- Add corresponding unit test
- Add corresponding regression tests
- Add particle drap plugin
-
fix (minor) dependencies for tools installation
v0.13.0
-
compilation changes require
c++ 14
and cuda 9.2
-
additional extern code include
src/extern/mpark
-
interface change linear EOS in SDPD needs an extra parameter
rho_0
-
fix SDPD: correct use of mass density
- checkpoint and restart interaction random state
- internal changes:
- cleanup some implementations from interfaces
- adding rod vectors
- remove xmacros for channel types
- use mpark::variant for membrane interaction
v0.12.3
-
interface changes
- use checkpoint instead of restart in Ymero coordinator constructor
- add checkpoint_mode parameter to Ymero coordinator constructor
- checkpoint/restart mechanism is more uniform
v0.12.2
- densities computed from pairwise interactions are now mass density
- internal changes:
- add fetcher with mass
- add type trait for self interacting pairwise kernels
v0.12.1
- add support of SDPD/MDPD for objects
-
fix belonging checkers for halo objects: needed rigid motions
-
fix reverse exchanger data taken from halo for the extra data
v0.12.0
-
fix
mirheo.restart()
will now indeed restart the simulation
-
interface change Renamed and moved parameter for MPI communicator in the mirheo constructor
-
interface change Density interaction needs a density kernel
- add SDPD interactions
- add more density kernels
-
docs: add tutorials
-
docs: minor fixes
-
internal:
- tests are more robust to DPD noise
- proper rng per time step in DPD/MDPD
- add density outlet plugin
- add rate outlet plugin
- add experimental version of density control plugin
v0.11.5
- support for RDMA communication
- membrane fluctuation forces: use uniform distribution instead of gaussian so that it is bounded
- membrane forces: more robust computation of Lim forces
- internal changes:
- simplify interface of interaction manager
- pairwise forces can contain only host memory variable and pass a separate handle to gpu
- pairwise interaction: compiled separately when template instances are created
v0.11.4
-
fix Lim shear forces bug: triangle invariant
-
fix reset accumulated quantities in Juelicher ADE model
-
fix check MPI send requests
v0.11.3
-
fix Juelicher bending forces sign
-
fix Lim shear forces sign
- add possibility to compute membrane forces in double perecision
v0.11.2
-
fix wall thickness is larger when using MDPD
- internal changes:
- cell lists do not know about special channels
- add interaction manager to manage interaction channels
v0.11.1
-
fix bounce back on multiple nodes for objects
- minor fixes in documentation
v0.11.0
- add Lim model for shear forces on membranes
- add corresponding tests
v0.10.7
-
interface change membrane interactions take only one constructor (see docs)
-
fix warp reductions: all threads participate
- internal changes:
- cosmetic changes: more consistent namespace style
- membrane interaction takes a functor for dihedral computations
- refactor membrane interactions: take functors for shear and bending forces
v0.10.6
- Internal change: add before cell list plugin task
-
fix: pvs exchanger plugin: new particles are now correctly redistributed
-
fix: velocity inlet plugin: new particles are now correctly redistributed
-
fix: communication of persistent data to empty pvs
-
fix: average plugin asynchronous message to postprocessing
v0.10.5
- add displacement plugin
- add radial velocity control plugin
-
fix reordering of extra data in celllists
-
fix pvsExchanger plugin also copies persistent channels
- add test for pvsExchanger
- add test for displacement plugin
- internal changes:
- packers can copy to another packer
- defaultStream in
core/utils/cuda_common.h
v0.10.4
- add velocity inlet plugin
- add very simple CPU marching cubes implementation in core
- clean up units
v0.10.3
- add wall force collector plugin
- automated support of multiple GPUs on single nodes
-
fix in bounce
- remove deprecate warings for python 3.7
v0.10.2
- Adds support for different stress free shape than original mesh
v0.10.1
- add plugin to save a channel of extra particle data (useful for intermediate quantities such as densities in MDPD)
-
fix reordering of persistent extra channels in primary cell lists
-
fix use local cell lists instead of primary ones in halo exchanger
v0.10.0
- Add MDPD interaction (walls and solvent fully supported only)
- internal changes:
- generic pairwise interaction fetching
- 2-steps interaction support: extended task dependency graph
- cell lists are aware of which channels to clear, accumulate and reorder
- wip: more general object reverse exchangers
-
interface change: make frozen walls takes a list of interactions
-
interface change: make frozen rigid takes a list of interactions
v0.9.7
- support for VOLTA architecture
- internal changes
- generic pairwise interaction output: accumulators
- generic pairwise_interaction: pass views
- cell lists produce views; cellinfos don not know about particles and forces
- less magic numbers
v0.9.6
-
fix: LJ potential had swapped epsilon and sigma
v0.9.5
- separate sdf grid implementation into more general core/field
- field can be initialized from std::function
- pressure plugin uses region
v0.9.4
-
fix: stress free state can be used when the cell is grown
-
fix: MembraneMesh wrapper needs GPU
v0.9.3
-
fix: the stress entries are now cleared before forces; could be cleared more by other interaction handlers
- use mirheo state inside the simulation objects; do not have current time, step and dt separate in simulation
v0.9.2
- add filtered initial conditions: allows custom regions in space to initialise uniform density particles
v0.9.1
- add sphere initial condition
- add plugin to compute total virial pressure from stresses per particle for a given pv
v0.9.0
- Add common YmrState object.
-
interface change:
- the time step is now passed to the coordinator constructor
- the time step is not passed to any other object
v0.8.0
- add checkpoint for permanent channels
- extra data managers are aware of the type
v0.7.1
- add permanent channels in extra data manager
v0.7.0
- reorganise membrane interaction kernels:
- bending force kernels now separated from other
- 2 parameter strctures
- add Juelicher bending model
- add force saver plugin to save forces in channels
v0.6.1
- rename uDeviceX to Ymero
- synchronzation bug fix
v0.6.0
- add plugin for magnetic orientation of rigid bodies
v0.5.1
- make the stress channel name customizable
v0.5.0
- add stress computation + tests
- perf improvement in sdf
- minor perf improvement in pairwise kernels
v0.4.2
- compile some units
- use gtest
v0.4.1
-
interface change: wall oscillation: period is in dpd units now
v0.4.0
- add hdf5 support for mesh dump
- allow for extra channels to be dumped together with the mesh
v0.3.1
- add compile time switch for CUDA>9 support
- add extra force plugin
v0.3.0
- proper MPI init and finalize
- communicator can be passed from python
v0.2.1
- add tools python submodule
v0.2.0
- add checkpoint/restart support for object vectors
- dumped in xdmf+hdf5 format: restart files can be viewed
v0.1.4
- add bounce tests
- wip: xdmf support for restart
v0.1.3
- bug fix: bounce back with substep integration
- xdmf reader
v0.1.2
- dump walls in xdmf format
- add tests for bounce back on mesh + rigid ellipsoids
v0.1.1
- sdf fix: merged sdf before splittinf frozen particles
v0.1.0