Implement rigid IBM algorithm

[mobernabeu]

Following from #569 and #684, the current algorithmic ordering in HemeLB is:

1. compute RBC forces
2. spread forces to fluid grid (new \vec{F}(\vec{x}, t))
3. interpolate velocities at Lagrangian mesh (using \vec{u}^*(\vec{x}, t-1) and \vec{F}(\vec{x}, t), see Implement changes arising from validation of RBC code against Timm's reference code #684)
4. update positions of Lagrangian mesh
5. LBM collision
6. LBM propagation
7. swap current and new (collided + propagated) populations (this is an important implementation detail: Implement changes arising from validation of RBC code against Timm's reference code #684 (comment))

Note: \vec{u}^*(\vec{x}, t-1)=1/\rho \Sum_i f_i(\vec{x}, t-1) \vec{c_i} is the collided, pre-streamed velocity in the previous timestep.

The current RBC development branch is red_blood_cells/develop. The relevant files are Code/redblood/CellController.h for the first four steps and Code/lb/lb.hpp for the last three steps. Both are subclasses of the IteratedAction infrastructure, which will require some study to understand how things are orchestratred together. Documentation is sparse so I'm happy to give more details. No harm in adding some more documentation as we go along.

There are some known issues with unit tests not passing in #693.

[otbrown]

Hi all (in particular @timmkrueger),

Apologies for the lengthy comment, but I thought it might be useful to present my notes here. I've been looking through HemeLB, and taking note of parts of the code which I may (or may not) need to modify. Having identified where the steps noted above by Miguel are implemented, I've now begun looking at how Emmanouil's algorithm would be implemented.

As you'll see I've not got terribly far, but I think it would be useful to have someone who knows HemeLB well confirm or deny my suspicions about what's already implemented. It would be also useful to discuss with Emmanouil if he thinks existing code correlates to his algorithmic steps. Is he on here? I can send this separately to him if not.

All comments and questions welcomed!

Cheers,
Oliver

Current Ordering

(Assuming HEMELB_USE_KRUEGER_ORDERING, using namespace hemelb::redblood)

Algorithmic Step	Function(s)	Call	Definition
1: Compute RBC forces	CellArmy<TRAITS>::Cell2FluidInteractions > parallel::SpreadForces::ComputeForces	CellController.h:38 > CellArmy.h:291	CellArmy.h:284 > SpreadForces.cc:40
2: Spread forces to fluid grid	CellArmy<TRAITS>::Cell2FluidInteractions > parallel::SpreadForces::SpreadLocalForces, parallel::SpreadForces::SpreadNonLocalForces	CellController.h:38 > CellArmy.h:293,297	CellArmy.h:284 > SpreadForces.h:108,123
3: Interpolate velocities at Lagrangian mesh	CellArmy<TRAITS>::Fluid2CellInteractions > parallel::IntegrateVelocities::ComputeLocalVelocitiesAndUpdatePositions > velocitiesOnMesh > interpolateVelocity	CellController.h:41 > CellArmy.h:243 > IntegrateVelocities.h:89 > GridAndCell.h:40	CellArmy.h:215 > IntegrateVelocities.h:79 > GridAndCell.h:31 > VelocityInterpolation.h:131
4: Update positions of Lagrangian mesh	CellArmy<TRAITS>::Fluid2CellInteractions > parallel::IntegrateVelocities::ComputeLocalVelocitiesAndUpdatePositions > CellBase::operator+=	CellController.h:41 > CellArmy.h:243 > IntegrateVelocities.h:90	CellArmy.h:215 > IntegrateVelocities.h:79 > CellBase.cc:132
5: LBM collision*	LBM<TRAITS>::PreSend, LBM<TRAITS>::PreReceive > LBM<TRAITS>::StreamAndCollide	During phase 1 > lb.hpp:many	lb.hpp:217, lb.hpp:255 > lb.h:132
6: LBM propagation *	LBM<TRAITS>::PreSend, LBM<TRAITS>::PreReceive > LBM<TRAITS>::StreamAndCollide	During phase 1 > lb.hpp:many	lb.hpp:217, lb.hpp:255 > lb.h:132
7: Swap current and new populations	LBM<TRAITS>::EndIteration > geometry::LatticeData::SwapOldAndNew	End of phase 1 > lb.hpp:357	lb.hpp:350 > LatticeData.h:67

* Does StreamAndCollide, so not sure it makes sense to separate these two steps. Actual StreamAndCollide operation is dependent on location (near a wall, mid-fluid, etc) and provided Streamer and Collision, see lb/streamers and lb/collisions directories.

Special mention: TODO at lb.hpp:308.

Proposed ordering

Algorithmic Step	Implemented in HemeLB?
1. Total force computation	Yes, if same as Compute RBC Forces above.
2. CoM velocity prediction	Possibly.
3. Particle Position	Yes, assuming we can use existing particle position update functions. (ComputeLocalVelocitiesAndUpdatePositions)
4. Velocity computation	Yes, assuming we can use existing velocity update functions. (ComputeLocalVelocitiesAndUpdatePositions)
5. CLBM	Collision step, yes, although may need to separate from streaming step.
6. Velocity Interpolation	Yes, interpolateVelocity.
7. Lagrangian velocity correction	Possibly, part of IntegrateVelocities?
8. Lagrangian force computation	Possibly.
9. Eulerian velocity correction	Possibly.
10. Eulerian force computation	Possibly.
11. Iteration	No, this is trivial if all iterated calculations are local, as we can confine new steps to one step (PreReceive). If communication is required could be more challenging.