jaxdem.forces.law_combiner#

Composite force model that sums multiple force laws.

Classes

LawCombiner([laws])

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

Bases: ForceModel

A ForceModel implementation 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

  • Each sub-law is evaluated with a system whose force_model is the sub-law itself, so 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 requires_history: bool[source]#

Indicates whether this force model requires persistent pair history.

init_history(shape: tuple[int, ...]) → Any[source]#
static force_and_history(i: int, j: int, pos: jax.Array, state: State, system: System, history: Any) → tuple[jax.Array, jax.Array, Any][source]#
property required_material_properties: tuple[str, ...][source]#

A static tuple of strings specifying the material properties required by this force model.

The sorted union of the material properties required by all contained laws. These properties must be present in the System.mat_table for the model to function correctly. This is used for validation.

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

Compute the total force and torque acting on particle \(i\) due to particle \(j\) by summing all contained laws.

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.

Returns:

A tuple (force, torque) with the sums of the forces and torques of all contained laws acting on particle \(i\) due to particle \(j\).

Return type:

Tuple[jax.Array, jax.Array]

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

Compute the total potential energy of the interaction between particle \(i\) and particle \(j\) by summing all contained laws.

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.

Returns:

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

Return type:

jax.Array