Contact Points#

Point-based contact model for ground interaction forces.

class biosym.model.contact.contact_models.contact_points.ContactPoints(xml_root, body_weight=1)#

Bases: BaseContact

Point-based contact model for ground reaction force calculation.

This class implements a contact model based on discrete contact points attached to specified bodies. Each contact point can generate normal and friction forces when in contact with the ground, using a spring-damper model with Coulomb friction.

Parameters:

  • xml_root (xml.etree.ElementTree.Element) – Root element of the XML tree containing contact point definitions. Should contain ‘contact_point’ elements with position and parameter specs.

  • body_weight (float, default=1) – Body weight in arbitrary units for scaling contact parameters. Contact stiffness and damping are scaled by body_weight * 9.81.

cps#

Dictionary mapping contact point names to their properties.

Type:

dict

bodies#

List of body names that have contact points.

Type:

list of str

body_mapping#

Array mapping contact points to their parent bodies.

Type:

numpy.ndarray

k#

Contact stiffness values for each contact point.

Type:

list of float

b#

Contact damping values for each contact point.

Type:

list of float

mu#

Friction coefficients for each contact point.

Type:

list of float

p_cy_0#

Transition region sizes for position (penetration depth).

Type:

list of float

v_cx_0#

Transition region sizes for velocity (sliding).

Type:

list of float

Notes

The contact model uses: - Hunt-Crossley contact mechanics for normal forces - Coulomb friction with smooth transitions - Penetration-based contact detection - Body-weight scaling for force parameters

Contact forces are calculated as: - Normal force: F_n = k * penetration * (1 + b * penetration_velocity) - Friction force: F_f = mu * F_n * tanh(velocity / v_cx_0)

XML Format#

Expected XML structure:

<contact type="contact_points">
    <default>
        <contact_point k="1000" b="10" mu="0.8"/>
    </default>
    <contact_point name="heel_r" body="foot_r" pos="0 0 -0.05"/>
    <contact_point name="toe_r" body="foot_r" pos="0.15 0 -0.05"/>
</contact>

Examples

Create contact model from XML:

>>> import xml.etree.ElementTree as ET
>>> root = ET.parse("contact.xml").getroot()
>>> contact = ContactPoints(root, body_weight=70.0)

Get contact information:

>>> bodies = contact.get_bodies()
>>> n_points = len(contact.cps)
>>> forces = contact.forward(states, constants, model)

See also

biosym.model.contact.base_contact.BaseContact

Base contact interface

forward(states, constants, model)#

Return aggregated contact forces and moments for all contact bodies.

Parameters:

  • states (object) – State container for the current model evaluation.

  • constants (object) – Constant parameter container for the current model evaluation.

  • model (biosym.model.model.BiosymModel) – Model instance used to evaluate the contact model.

Returns:

Aggregated body forces and moments in the global frame.

Return type:

tuple[jax.Array, jax.Array]

get_bodies()#

Returns the list of bodies that can be in contact.

get_constants()#

Get the list of additional constant parameter names for the contact model.

Returns:

Names of additional constant parameters needed during optimization that are specific to this contact model.

Return type:

list of str

Notes

The returned list should have length equal to get_n_constants(). Constant names are used for identification in optimization and analysis.

get_cp_forces(states, constants, model)#

Return contact forces for all contact points in the global frame.

Parameters:

  • states (object) – State container for the current model evaluation.

  • constants (object) – Constant parameter container for the current model evaluation.

  • model (biosym.model.model.BiosymModel) – Model instance used to evaluate the contact-force functions.

Returns:

Contact forces for all contact points in the global frame.

Return type:

jax.Array

get_cp_moment_arms(states, constants, model, return_positions=False)#

Returns the moment arms for every contact point wrt to the body origin.

get_n_bodies()#

Returns the number of bodies that can be in contact.

get_n_constants()#

Get the number of additional constants required by the contact model.

Returns:

Number of additional constant parameters needed during optimization or simulation that are specific to the contact model.

Return type:

int

Notes

Contact models may require additional constants beyond the basic mechanical parameters. Examples include: - Contact stiffness parameters - Friction coefficients - Contact geometry parameters - Material properties

get_n_constraints(*args, **kwargs)#

Get the number of constraints imposed by the contact model.

Returns:

Number of constraints that the contact model adds to the system.

Return type:

int

Notes

Contact models may impose constraints on the system dynamics, such as non-penetration conditions or friction limits. The default implementation returns 0, but subclasses can override this method to specify the actual number of constraints.

get_n_states()#

Get the number of additional states required by the contact model.

Returns:

Number of additional state variables needed during optimization or simulation that are specific to the contact model.

Return type:

int

Notes

Contact models may require additional states beyond the basic mechanical states (positions, velocities) to properly represent contact dynamics. Examples include: - Contact penetration depths - Sliding velocities - Contact activation states - Internal contact model variables

get_states()#

Get the list of additional state variable names for the contact model.

Returns:

Names of additional state variables needed during optimization that are specific to this contact model.

Return type:

list of str

Notes

The returned list should have length equal to get_n_states(). State names are used for identification in optimization and analysis.

plot(states, model, mode, ax, **kwargs)#

Plot contact points, body connections, and optional force vectors.

Parameters:

  • states (object) – State container or list of state containers to visualize.

  • model (biosym.model.model.BiosymModel) – Model instance used to compute contact-point positions.

  • mode (str) – Plotting mode, either "init" or "update".

  • ax (matplotlib.axes.Axes) – Axes object that receives the contact visualization.

  • **kwargs – Additional plotting options such as case and non_zero_axes.

process_eom(model, **kwargs)#

Build the eom for the contact model with symbolic variables.

reset()#

Reset the contact model to its initial state.

Notes

This method is called at the beginning of simulations to ensure the contact model starts from a clean state. Implementations should: - Reset any internal state variables - Clear contact history - Initialize contact detection flags - Reset accumulated contact energies or impulses