ContactSurface.h

Go to the documentation of this file.

#ifndef SimTK_SIMBODY_CONTACT_SURFACE_H_
#define SimTK_SIMBODY_CONTACT_SURFACE_H_

/* -------------------------------------------------------------------------- *
 *                      SimTK Core: SimTK Simbody(tm)                         *
 * -------------------------------------------------------------------------- *
 * This is part of the SimTK Core biosimulation toolkit originating from      *
 * Simbios, the NIH National Center for Physics-Based Simulation of           *
 * Biological Structures at Stanford, funded under the NIH Roadmap for        *
 * Medical Research, grant U54 GM072970. See https://simtk.org.               *
 *                                                                            *
 * Portions copyright (c) 2008 Stanford University and the Authors.           *
 * Authors: Peter Eastman                                                     *
 * Contributors:                                                              *
 *                                                                            *
 * Permission is hereby granted, free of charge, to any person obtaining a    *
 * copy of this software and associated documentation files (the "Software"), *
 * to deal in the Software without restriction, including without limitation  *
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,   *
 * and/or sell copies of the Software, and to permit persons to whom the      *
 * Software is furnished to do so, subject to the following conditions:       *
 *                                                                            *
 * The above copyright notice and this permission notice shall be included in *
 * all copies or substantial portions of the Software.                        *
 *                                                                            *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR *
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,   *
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL    *
 * THE AUTHORS, CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,    *
 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR      *
 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE  *
 * USE OR OTHER DEALINGS IN THE SOFTWARE.                                     *
 * -------------------------------------------------------------------------- */

#include "SimTKcommon.h"
#include "simbody/internal/common.h"
#include "simbody/internal/ContactGeometry.h"

#include <algorithm>

namespace SimTK {

class ContactGeometry;

SimTK_DEFINE_UNIQUE_INDEX_TYPE(ContactCliqueId);



//==============================================================================
//                               CONTACT MATERIAL
//==============================================================================
class SimTK_SIMBODY_EXPORT ContactMaterial {
public:
ContactMaterial() {clear();}

ContactMaterial(Real stiffness, Real dissipation, 
                Real staticFriction, Real dynamicFriction,
                Real viscousFriction = 0) {
    setStiffness(stiffness);
    setDissipation(dissipation);
    setFriction(staticFriction, dynamicFriction, viscousFriction);
}

bool isValid() const {return m_stiffness > 0;}

Real getStiffness() const 
{   SimTK_ERRCHK(isValid(), "ContactMaterial::getStiffness()",
        "This is an invalid ContactMaterial.");
    return m_stiffness; }
Real getStiffness23() const 
{   SimTK_ERRCHK(isValid(), "ContactMaterial::getStiffness23()",
        "This is an invalid ContactMaterial.");
    return m_stiffness23; }
Real getDissipation() const 
{   SimTK_ERRCHK(isValid(), "ContactMaterial::getDissipation()",
        "This is an invalid ContactMaterial.");
    return m_dissipation; }
Real getStaticFriction() const 
{   SimTK_ERRCHK(isValid(), "ContactMaterial::getStaticFriction()",
        "This is an invalid ContactMaterial.");
    return m_staticFriction; }
Real getDynamicFriction() const 
{   SimTK_ERRCHK(isValid(), "ContactMaterial::getDynamicFriction()",
        "This is an invalid ContactMaterial.");
    return m_dynamicFriction; }
//TODO: should this be (force/area)/velocity?
Real getViscousFriction() const 
{   SimTK_ERRCHK(isValid(), "ContactMaterial::getViscousFriction()",
        "This is an invalid ContactMaterial.");
    return m_viscousFriction; }

ContactMaterial& setStiffness(Real stiffness) {
    SimTK_ERRCHK1_ALWAYS(stiffness >= 0, "ContactMaterial::setStiffness()",
        "Stiffness %g is illegal; must be >= 0.", stiffness);
    m_stiffness = stiffness;
    m_stiffness23 = std::pow(m_stiffness, Real(2./3.));
    return *this;
}

ContactMaterial& setDissipation(Real dissipation) {
    SimTK_ERRCHK1_ALWAYS(dissipation >= 0, "ContactMaterial::setDissipation()",
        "Dissipation %g (in 1/speed) is illegal; must be >= 0.", dissipation);
    m_dissipation = dissipation;
    return *this;
}

ContactMaterial& setFriction(Real staticFriction,
                             Real dynamicFriction,
                             Real viscousFriction = 0)
{
    SimTK_ERRCHK1_ALWAYS(0 <= staticFriction, "ContactMaterial::setFriction()",
        "Illegal static friction coefficient %g.", staticFriction);
    SimTK_ERRCHK2_ALWAYS(0<=dynamicFriction && dynamicFriction<=staticFriction, 
        "ContactMaterial::setFriction()",
        "Dynamic coefficient %g illegal; must be between 0 and static"
        " coefficient %g.", dynamicFriction, staticFriction);
    SimTK_ERRCHK1_ALWAYS(0 <= viscousFriction, "ContactMaterial::setFriction()",
        "Illegal viscous friction coefficient %g.", viscousFriction);

    m_staticFriction  = staticFriction;
    m_dynamicFriction = dynamicFriction;
    m_viscousFriction = viscousFriction;
    return *this;
}

static Real calcPlaneStrainStiffness(Real youngsModulus, 
                                     Real poissonsRatio) 
{
    SimTK_ERRCHK2_ALWAYS(youngsModulus >= 0 &&
                         -1 < poissonsRatio && poissonsRatio < 0.5,
                         "ContactMaterial::calcStiffnessForSolid()",
        "Illegal material properties E=%g, v=%g.", 
        youngsModulus, poissonsRatio);

    return youngsModulus / (1-square(poissonsRatio)); 
}


static Real calcConfinedCompressionStiffness(Real youngsModulus, 
                                             Real poissonsRatio) 
{
    SimTK_ERRCHK2_ALWAYS(youngsModulus >= 0 &&
                         -1 < poissonsRatio && poissonsRatio < 0.5,
                         "ContactMaterial::calcStiffnessForSolid()",
        "Illegal material properties E=%g, v=%g.", 
        youngsModulus, poissonsRatio);

    return youngsModulus*(1-poissonsRatio) 
        / ((1+poissonsRatio)*(1-2*poissonsRatio)); 
}

static Real calcDissipationFromObservedRestitution
   (Real restitution, Real speed) {
    if (restitution==1) return 0;
    SimTK_ERRCHK2(0<=restitution && restitution<=1 && speed>0,
        "ContactMaterial::calcDissipationFromRestitution()",
        "Illegal coefficient of restitution or speed (%g,%g).",
        restitution, speed);
    return (1-restitution)/speed;
}

void clear() {
    m_stiffness   = NaN; // unspecified
    m_stiffness23 = NaN;
    m_restitution = NaN; // unspecified
    m_dissipation = 0;  // default; no dissipation
    // default; no friction
    m_staticFriction=m_dynamicFriction=m_viscousFriction = 0;
}

//--------------------------------------------------------------------------
private:

// For compliant contact models.
Real    m_stiffness;        // k: stress/%strain=(force/area)/%strain
Real    m_stiffness23;      // k^(2/3) in case we need it
Real    m_dissipation;      // c: %normalForce/normalVelocity

// For impulsive collisions.
Real    m_restitution;      // e: unitless, e=(1-cv)

// Friction.
Real    m_staticFriction;   // us: unitless
Real    m_dynamicFriction;  // ud: unitless
Real    m_viscousFriction;  // uv: %normalForce/slipVelocity
};



//==============================================================================
//                               CONTACT SURFACE
//==============================================================================
class SimTK_SIMBODY_EXPORT ContactSurface {
public:
ContactSurface() {}
ContactSurface(const ContactGeometry& shape, const ContactMaterial& material)
:   m_shape(shape), m_material(material) {}

ContactSurface& setShape(const ContactGeometry& shape) 
{   m_shape = shape; return *this; }

ContactSurface& setMaterial(const ContactMaterial& material,
                            Real thickness = Infinity) 
{   m_material = material; setThickness(thickness); return *this; }

ContactSurface& setThickness(Real thickness)
{   m_thickness = thickness; return *this; }

const ContactGeometry& getShape()    const {return m_shape;}

const ContactMaterial& getMaterial() const {return m_material;}

Real getThickness() const {return m_thickness;}

ContactGeometry& updShape()    {return m_shape;}

ContactMaterial& updMaterial() {return m_material;}

ContactSurface& joinClique(ContactCliqueId clique) {
    // Although this is a sorted list, we expect it to be very short so 
    // are using linear search to find where this new clique goes.
    Array_<ContactCliqueId,short>::iterator p;
    for (p = m_cliques.begin(); p != m_cliques.end(); ++p) {   
        if (*p==clique) return *this; // already a member
        if (*p>clique) break;
    }
    // insert just before p (might be at the end)
    m_cliques.insert(p, clique);
    return *this;
}

void leaveClique(ContactCliqueId clique) {   
    // We expect this to be a very short list so are using linear search.
    Array_<ContactCliqueId,short>::iterator p =
        std::find(m_cliques.begin(), m_cliques.end(), clique);
    if (p != m_cliques.end()) m_cliques.erase(p); 
}

bool isInSameClique(const ContactSurface& other) const 
{   if (getCliques().empty() || other.getCliques().empty()) return false;//typical
    return cliquesIntersect(getCliques(), other.getCliques()); }

const Array_<ContactCliqueId,short>& getCliques() const {return m_cliques;}

static bool cliquesIntersect(const Array_<ContactCliqueId,short>& a,
                             const Array_<ContactCliqueId,short>& b)
{
    Array_<ContactCliqueId,short>::const_iterator ap = a.begin();
    Array_<ContactCliqueId,short>::const_iterator bp = b.begin();
    // Quick checks: empty or non-overlapping.
    if (ap==a.end() || bp==b.end()) return false;
    if (*ap > b.back() || *bp > a.back()) 
        return false; // disjoint
    // Both lists have elements and the elements overlap numerically.
    while (true) {
        if (*ap==*bp) return true;
        // Increment the list with smaller front element.
        if (*ap < *bp) {++ap; if (ap==a.end()) break;}
        else           {++bp; if (bp==b.end()) break;}
    }
    // One of the lists ran out of elements before we found a match.
    return false;
}

static ContactCliqueId createNewContactClique()
{   static AtomicInteger nextAvailableContactClique = 1;
    return ContactCliqueId(nextAvailableContactClique++); }

//----------------------------------------------------------------------
                                 private:

ContactGeometry                 m_shape;
ContactMaterial                 m_material;
Real                            m_thickness; // default=Infinity
Array_<ContactCliqueId,short>   m_cliques;   // sorted
};



} // namespace SimTK

#endif // SimTK_SIMBODY_CONTACT_SURFACE_H_