Sanitizing Contact Logic

From Yade

Introduction : rough philosophy and main actors of contact logic

The detection of contact in Yade is based on "AABB", which means Axis Aligned Bounding Boxes. Instead of testing all the possible couple of bodies to see if they are in contact (by comparing their distance to the sum of their radii), in Yade each body has a bounding volume, which is a such AABB : a parallelepipedic box containing the body (a sphere generally) itself, with sides parallel to axes. That's the BoundingVolumeMetaEngine which cares about creating these AABB.

Then for the contact detection it is in fact much faster to compare the coordinates of the extremities of the AABB to see if there are potential interactions. That is the role of colliders, InsertionSortCollider for example.

Once the potential interactions are determined (so a lot of couple of bodies which will surely not interact are disregarded) it is investigated if the bodies are really in contact or not, thanks to InteractionGeometryMetaEngine.

After that, the physical properties of the interactions, which will be used to compute contact forces (rigidities...) are set by InteractionPhysicsMetaEngine which uses classes containing the parameters of bodies and classes describing how to compute interactions properties from bodies properties (names finishing by ...RelationsShips).

And finally, the contact law is really applied : the contact forces are computed and affected to the bodies with a last Engine whose name generally finishes by ...ContactLaw. Jduriez 13:24, 23 May 2008 (UTC)

Current status (svn as of r1786 / June 2009)

No isNew/isReal, as well as no distant/non-distant interaction, transient/persistent etc.

New interaction

  • Interaction is created without interactionGeometry and interactionPhysics, by the collider under normal circumstances.
    • There is no isNew/isReal flags; the method isReal() only test that both interactionGeometry and interactionPhysics are present
    • InteractionGeometryEngineUnits know that the interaction is merely potential by looking at whether interactionGeometry is present.
    • InteractionPhysicsEngineUnits know that the interaction geometry has just been created by seeing empty interactionPhysics
    • Interaction stores internally iteration # when the interactionGeometry & physics was created. It can be compared to current iteration # using Interaction::isFresh(MetaBody*)

Updating real interaction

  • Collider may not delete a real interaction.
  • If InteractionGeometryMetaEngine returns false for an interaction that is real already, that interaction will be deleted automatically. (I would like to move that responsibility to constitutive law completely, however...)

Deleting an interaction

The constitutive law is responsible for deleting (real) interactions. It does so by calling InteractionContainer::requestErase(id1,id2), which will

  1. reset the interaction (Interaction::reset())
  2. add it to internal queue for removal
  3. At the next step, the collider will call InteractionContainer::erasePending, which calls that collider's shouldBeErased predicate to either remove the interaction completely, or just keep it in potential state.


  • Removing isReal: redundant information. (I->interactionGeometry && I->interactionPhysics) does just that. Provide Interaction::isReal() as alias for this test.
  • Removing isNew: redundant information. If the interaction exists, it is potential or isReal().
  • Not deleting interaction directly, but by InteractionContainer::requestErase(id1,id2)
    • some colliders (PersistentSAP, InsertionSort) do not see interaction unless the AABBs of the two bodies just crossed in either way. Deleting an interaction where AABBs still overlap (but bodies don't, for instance) will prevent the interaction to be created, if the bodies overlap, unless the AABBs serparate and meet again (at which point the potential interaction would be created again). This way, the collider decides, whether to delete the interaction or keep it.
    • This also gives reason why the constitutive law should delete interactions, as it always gets to see the interaction. Colliders don't.
    • (not sure) the implementation of InteractionContainer may not like removing interaction while iteration over them.

Old status

  • isReal
    • false: only bounding boxes overlap, but there is no overlap of bodies and no physical interaction.
    • true: both bounding boxes and bodies overlap (distance < 0) and/or there is a physical interaction.
  • isNew
    • true: the interaction has just been created by the collider (there is no interaction physics), or the interaction already existed but isReal was false in the previous iteration (in this later case the interaction is new in the physical sense, even if the pointer from a previous interaction between the same bodies is used again).
    • false: the contact was Real during the previous iteration

Collider-independant definitions :

  • isReal
    • false: there is no physical interaction.
    • true: there is a physical interaction.
  • isNew

same definition as before, see added comment below (bchareyre 17:53, 28 May 2008 (UTC)).


  • Consistently take distant contacts into account - eudoxos 08:34, 23 May 2008 (UTC)
    • It is the constitutive law that deletes the contact (or sets an appropriate flag); does this incur penalty if distant contacts are not used?
    • both functors for interacting geometry and colliders have "allowDistant" or similar, with the same logic
    • get rid of persistentInteractions !

YES ! Jduriez 13:24, 23 May 2008 (UTC)

  • extend set of interaction flags (isReal, isNew) - eudoxos 08:34, 23 May 2008 (UTC)
    • Sega has new cycle flag, for example; can we converge on something?

I would have left isReal and isNew unchanged. The cycle flag is added as a reserve. Me it is used for marking stale contacts, but someone else may be used for other purposes. But it is assumed that cycle has a local value for each Engine which it uses. Sega 09:20, 24 May 2008 (UTC)

  • rename isReal to something more descriptive (isOverlapping?) - eudoxos 08:34, 23 May 2008 (UTC)

Yes Jduriez 13:24, 23 May 2008 (UTC)

Bruno's update : For me, the current behaviour is quite clear in fact. I may have missed something (particularly for the case haveDistant==false) but the modified definitions of isReal and isNew that I gave above should change the context of this discussion. Yes, constitutive law should delete interactions, but we can keep 2 different behaviours : - if (hasDistantTransient), the constitutive law must delete interactions, no time penalty will result of that. - else (default), the user don't need to worry about that and the collider will delete interactions. This is exactly the current situation. Yes, lets remove persistent links and all distant classes from yade. No need to allowDistant in functors, they can handle both cases already. I won't mind if you had new flags but I wonder why exactly you need them... bchareyre 17:46, 23 May 2008 (UTC)

OK, (||c->isReal) reverted: as it turned out, PersistentSAPCollider unset isReal if !haveDistantTransient and here no penalty indeed. (but there are flashing then visualized InteractionPhysics, as GLDraw* also uses isReal, but runs in another thread.) Sega 09:07, 24 May 2008 (UTC)

Exactly, if !haveDistantTransient, this ||c->isReal has no effect at all because isReal is always false. To summarize :

- if !haveDistantTransient, isReal is true if and only if there is a geometrical interaction (overlap), one exception : isReal will always be false at the begining of each timestep, until the geometryMetaEngine set it again. The collider create/delete interactions alone, based on overlaping status.

- if haveDistantTransient, isReal is true if and only if there is a physical interaction (so that geometry is computed "if and only if" we need it). In that case, physical and geometrical interactions are uncoupled : overlap implies interaction, but interaction does not imply overlap. In this context, the collider is used to detect new interactions based on a geometrical criterion, but it will not delete interactions as the criterion to delete is not geometrical (note that the creation of interactions can include a distance factor larger than 1 if one needs to detect not only overlap but also proximity). isReal must be set false somewhere in the contact law, or the number of interactions will eventually grow up to N*N (N=number of bodies).

Thank you Sega for revert. bchareyre 15:49, 26 May 2008 (UTC)

I propose modified definitions so that the meaning of isReal and isNew is independant on the collider (not all colliders use bounding boxes). bchareyre 17:53, 28 May 2008 (UTC)