Contact Models (Ground Interaction)#

Overview#

Contact Models for Ground and Environmental Interactions.

This module provides classes and functions for modeling contact between the biomechanical model and its environment, particularly ground contact forces. Contact models are essential for simulating locomotion and other activities where the model interacts with external surfaces.

The module includes: - Base contact classes defining the common interface - Parsers for loading contact definitions from XML files - Specific contact model implementations (contact points, ground reaction forces)

Contact models handle: - Ground reaction force calculation - Contact detection and penetration - Friction and normal force computation - Contact state management during simulation

Examples

Load contact model from an XML file:

>>> import biosym.model.contact.contact_parser as parser
>>> contact = parser.get("path/to/contact.xml", body_weight=70.0)

Access contact properties:

>>> n_bodies = contact.get_n_bodies()
>>> contact_states = contact.get_n_states()
>>> bodies = contact.get_bodies()

Base Classes#

class biosym.model.contact.base_contact.BaseContact(xml_root)#

Bases: ABC

Abstract base class for contact models in biomechanical simulations.

This class defines the interface that all contact model implementations must follow. Contact models handle interactions between the biomechanical model and its environment, particularly ground contact forces during locomotion and other activities.

The base class provides a common framework for different contact formulations, such as point contacts, distributed contacts, or analytical contact models.

Parameters:

xml_root (xml.etree.ElementTree.Element) – Root element of the XML tree containing contact model definitions.

Notes

Contact models are responsible for: - Calculating ground reaction forces - Managing contact state during simulation - Providing additional states/constants for optimization - Handling contact detection and penetration - Computing friction and normal forces

Subclasses must implement all abstract methods to define specific contact behavior for different contact types (e.g., point contacts, distributed contacts).

See also

biosym.model.contact.contact_models.contact_points.ContactPoints

Point contact implementation

abstractmethod forward()#

Calculate contact forces for the current model state.

Returns:

Contact forces for all bodies in the global coordinate frame. Forces are typically organized as [Fx, Fy, Fz] for each body.

Return type:

jax.Array

Notes

This is the core computational method that evaluates the contact model given the current state of the system. The method should: - Compute contact penetrations - Calculate normal and friction forces - Transform forces to the global frame - Handle contact detection and activation

abstractmethod get_bodies()#

Get the list of bodies that can be in contact with the environment.

Returns:

Names of bodies that have contact points or can interact with the environment through this contact model.

Return type:

list of str

Notes

This method identifies which rigid bodies in the model can experience contact forces. Typically includes feet, hands, or other body segments that interact with the ground or environment.

abstractmethod 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.

abstractmethod get_n_bodies()#

Get the number of bodies that can be in contact with the environment.

Returns:

Number of bodies that can experience contact forces through this contact model.

Return type:

int

Notes

This is typically the length of the list returned by get_bodies(), but may be computed differently for efficiency in some implementations.

abstractmethod 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.

abstractmethod 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

abstractmethod 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.

abstractmethod plot(states, constants, model, mode)#

Visualize the contact model state and forces.

Parameters:

  • states (object) – Current state values for the model and contact system.

  • constants (object) – Current constant parameter values.

  • model (biosym.model.model.BiosymModel) – The biomechanical model containing this contact model.

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

Notes

Plotting mode "init" initializes axes, creates artists, and stores plotting state for later updates.

Plotting mode "update" refreshes the existing artists without recreating the whole visualization.

Contact visualizations typically show contact point locations, ground reaction force vectors, penetration indicators, and friction directions.

abstractmethod process_eom()#

Build additional equations of motion specific to the contact model.

This method is called during the symbolic equation generation phase to add contact-specific dynamics to the overall system equations.

Notes

Not all contact models require additional equations of motion. Simple contact models may only provide forces without additional dynamic states. Complex models may add: - Contact penetration dynamics - Friction state evolution - Contact mode switching logic

The default implementation should do nothing for simple contact models.

abstractmethod 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

Parser#

Parser for contact model definitions from XML files.

This module provides functionality to parse XML files containing contact model definitions and instantiate the appropriate contact model classes.

biosym.model.contact.contact_parser.get(file_path, body_weight=None)#

Parse a contact model file and return the appropriate contact instance.

This function reads XML files containing contact model definitions and creates the corresponding contact model objects based on the specified type.

Parameters:

  • file_path (str) – Path to the XML file containing contact model definitions.

  • body_weight (float, optional) – Body weight in kilograms for scaling contact forces. This is used to scale contact parameters like stiffness and damping based on the body weight of the subject being modeled.

Returns:

An instance of the appropriate contact model class based on the XML type specification.

Return type:

BaseContact

Raises:

ValueError – If the contact type specified in the XML is not recognized or supported.

Notes

Supported contact types: - “contact_points”: Point-based contact model with specified contact locations

The body_weight parameter is particularly important for contact models as it allows scaling of contact parameters to match different subject sizes. Typical usage involves providing the subject’s body weight in kg.

Examples

Load contact model for a 70kg subject:

>>> contact = get("path/to/contact.xml", body_weight=70.0)
>>> n_contacts = contact.get_n_bodies()

Load contact model with default scaling:

>>> contact = get("path/to/contact.xml")
>>> bodies = contact.get_bodies()

See also

biosym.model.contact.contact_models.contact_points.ContactPoints

Point contact implementation

Contact Implementations#

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