jaxdem.bonded_forces

Bonded-force interfaces independent of the collider.

Classes

BondedForceModel()

Abstract interface for bonded interaction containers.

class jaxdem.bonded_forces.BondedForceModel

Bases: Factory, ABC

Abstract interface for bonded interaction containers.

Design intent

• System stores one concrete bonded container instance.

• The container exposes bonded force/energy callables through force_and_energy_fns.

• The ForceManager gets and runs these callables to compute bonded contributions at each time step.

• The bonded data stays accessible through System, so the force/energy callables can read what they need.

update_reference_state(pos: jax.Array, state: State, system: System) → BondedForceModel

Return a model with reference data advanced by one physical time step.

System calls this hook exactly once after the integrator drift and before force evaluation. Implementations must return a model without mutating self. Elastic bonded models return themselves, so the no-op specializes away. Direct force and energy evaluations, including minimization, do not call this hook and keep the reference configuration fixed.

property force_and_energy_fns: tuple[ForceFunction, EnergyFunction, bool]

Build the bonded force/energy callables for the force manager.

Returns:

(force_fn, energy_fn, is_com_force) where:

• force_fn computes bonded force and torque contributions.

• energy_fn computes bonded potential-energy contributions.

• is_com_force tells where the force acts: True for the center of mass, False for the contact point. It has no effect on spheres.

Return type:

Tuple[ForceFunction, EnergyFunction, bool]

abstractmethod compute_potential_energy(pos: jax.Array, state: State, system: System) → jax.Array

Compute the total bonded potential energy of the system.

abstractmethod static merge(model1: BondedForceModel, model2: BondedForceModel | Sequence[BondedForceModel]) → BondedForceModel

Merge two or more bonded-force models into one.

The merge concatenates topology, reference, and coefficient arrays. It shifts vertex indices and body IDs automatically so references stay consistent. When one side has a term that the other does not, the merge pads missing coefficients with 0 and missing reference values with 1.

Parameters:

• model1 (BondedForceModel) – Base model.

• model2 (BondedForceModel or Sequence[BondedForceModel]) – Model(s) to merge into model1.

Returns:

A new model containing all bodies from both sides.

Return type:

BondedForceModel

abstractmethod static add(model: BondedForceModel, **kwargs: Any) → BondedForceModel

Create a new body from raw arrays and merge it into an existing model.

This is a convenience wrapper equivalent to calling the concrete Create constructor followed by merge().

Parameters:

• model (BondedForceModel) – Existing model to extend.

• **kwargs – Constructor arguments forwarded to the concrete Create method (e.g. vertices, elements, coefficients, …).

Returns:

The extended model.

Return type:

BondedForceModel

classmethod stack(models: Sequence[BondedT]) → BondedT

classmethod unstack(model: BondedT) → list[BondedT]

Modules

deformable_particle	Implementation of the deformable particle model.
plastic_bending_deformable_particle	Implementation of the deformable particle model with plastic bending angles.
plastic_deformable_particle	Implementation of the plastic deformable particle model.
plastic_perimeter_deformable_particle	Implementation of the plastic perimeter deformable particle model.