jaxdem.forces.law_combiner#

Composite force model that sums multiple force laws.

Classes

LawCombiner([laws])

A ForceModel that sums a tuple of elementary force laws.
class jaxdem.forces.law_combiner.LawCombiner(laws: tuple[ForceModel, ...] = ())#

Bases: ForceModel

A ForceModel that sums a tuple of elementary force laws.

The total force, torque, and potential energy of the interaction between particles \(i\) and \(j\) are the sums over the contained laws:

\[F_{ij} = \sum_k F^{(k)}_{ij}, \qquad \tau_{ij} = \sum_k \tau^{(k)}_{ij}, \qquad E_{ij} = \sum_k E^{(k)}_{ij}\]

Notes

  • The combiner evaluates each sub-law with a system whose force_model is the sub-law itself. Laws that read their own configuration from jaxdem.System.force_model (including nested combiners) work correctly.

  • An empty combiner (laws=()) returns zero force, torque, and energy. ForceRouter.from_dict uses it as the default no-interaction law.

  • required_material_properties is the union of the requirements of all contained laws.

property supports_analytical_energy_gradient: bool[source]#

Whether every contained law supports analytical minimization.

property species_capacity: int | None[source]#

Smallest router capacity reachable through the contained laws.

history_shape(dim: int) → tuple[int, ...][source]#

Trailing shape of one pair’s history; stateless laws use (0,).

Composite laws flatten child histories internally and restore this shape before invoking the child law.

init_history(pair_shape: tuple[int, ...], dim: int) → Array[source]#

Initialize the history variables for this force model.

Parameters:

  • pair_shape (tuple[int, ...]) – Collider-specific pair axes, such as a flat contact pool or a dense (N, N) pair array.

  • dim (int) – Spatial dimension used by dimension-dependent history layouts.

Returns:

A zero-filled array with shape pair_shape + history_shape(dim).

Return type:

jax.Array

search_radii(state: State, system: System) → jax.Array[source]#

Conservative per-primitive reach across every contained law.

static force(i: int, j: int, pos: jax.Array, state: State, system: System, history: jax.Array, *, advance_history: bool = True, quasistatic: bool = False) → tuple[jax.Array, jax.Array, jax.Array][source]#
property required_material_properties: tuple[str, ...][source]#

Names of the material properties this force model needs.

The sorted union of the material properties required by all contained laws. Each name must be present in System.mat_table. Used for validation.

static energy(i: int, j: int, pos: jax.Array, state: State, system: System, history: jax.Array) → jax.Array[source]#

Sum the pair energies of the contained laws.

Each law receives its own slice of the concatenated pair history.

Parameters:

  • i (int) – Index of the first particle.

  • j (int) – Index of the second particle.

  • pos (jax.Array) – Particle positions used to evaluate the interaction.

  • state (State) – Current state of the simulation.

  • system (System) – Simulation system configuration.

  • history (jax.Array) – Concatenated pair history of the contained laws.

Returns:

Scalar total potential energy of the interaction between particles \(i\) and \(j\).

Return type:

jax.Array