[org] notes on why there are two methods for updating contact points.
Some thoughts on why we ended up with two solutions, how they differ,
and why it's not so simple to move OCC to the same method as Bullet.
@@ -47,3 +47,46 @@ cd build_examples
cmake <path to siconos>/examples
make
#+END_SRC
+* Mechanics and contact points
+
+Here we note some differences in how the mechanics "collisions"
+interface and the "OCC" and "Mechanisms" interfaces differ.
+
+Collisions: Implements an InteractionManager, with
+updateInteractions() called at the beginning of Newton loop and
+updates the shapes associated with DSs, then performs broadphase
+collision. Contact points are stored relative to DSs, and the Newton
+loop can then move the DSs around and the contact points follow. The
+absolute contact points are updated in
+NewtonEulerFrom1DLocalFrameR::computeh() based on the passed-in q0
+BlockVector.
+
+OCC/Mechanisms: Use a derived TimeStepping class, OccTimeStepping, and
+DS positions are updated by a call to updateWorldFromDS(). Then a
+derived NewtonEulerFrom1DLocalFrameR, OccR, computes new distances in
+computeh() based on current DS q vectors, ignoring the q0 BlockVector
+passed in. However, these (DS->q and q0) should be the same anyway.
+
+These reflect two ways to update contact points. The first way
+updates contact points once for all DS and then keeps them up to date
+with each Newton iteration. That is, for D=number of DS, R=number of
+relations, N=number of Newton iterations, it is O(D+RN). The other
+way updates the DSs and the relations on each iteration, it is
+O((D+R)N). The advantage for the second method is that it is probably
+more accurate, since contact points can move around the contour of the
+geometry during the Newton loop, meaning it can maintain the closest
+distance at each iteration by sliding the points around relative to
+the object. However, this is mainly possible because the interactions
+between objects are permanent.
+
+In the case of using a dynamic contact engine like Bullet, we cannot
+use the second method, since if we call the contact algorithm during
+the Newton loop we may add and remove iterations which is not
+numerically sound with regards to the stability of the solver.
+Moreover, implementation-wise it is complicated since Bullet re-uses
+contact point data structures and the contact points may change role
+during the loop. One solution could be to implement it such that
+during the loop new points are only added, but never removed. This
+could be stable, but may lead to unnecessary extra contact points.
+Moreover Interactions could no longer be tracked by the "user pointer"
+available in the Bullet btManifoldPoint data structure.
