Overview#

Core contact framework including base classes and parsers.

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

Parsers#

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()