jaxdem.domains.reflect#

Reflective boundary-condition domain.

Classes

ReflectDomain(box_size, inv_box_size, ...)

A Domain implementation that enforces reflective boundary conditions.
class jaxdem.domains.reflect.ReflectDomain(box_size: Array, inv_box_size: Array, anchor: Array, restitution_coefficient: Array)#

Bases: Domain

A Domain implementation that enforces reflective boundary conditions.

When a particle moves beyond the defined box_size, the domain reflects its position back into the box. It also reverses the velocity component normal to the boundary.

restitution_coefficient: Array#
classmethod Create(dim: int, box_size: Array | None = None, anchor: Array | None = None, restitution_coefficient: float = 1.0, **kw: Any) → Self[source]#

Default factory method for the Domain class.

This method constructs a new Domain instance with a box-shaped domain of the given dimensionality. If you do not provide box_size or anchor, they default to the values below.

Parameters:

  • dim (int) – The dimensionality of the domain (e.g., 2, 3).

  • box_size (jax.Array, optional) – The size of the domain along each dimension. If not provided, defaults to an array of ones with shape (dim,).

  • anchor (jax.Array, optional) – The anchor (origin) of the domain. If not provided, defaults to an array of zeros with shape (dim,).

  • restitution_coefficient (float) – Restitution coefficient between 0 and 1 to modulate energy conservation with wall.

Returns:

A new instance of the Domain subclass with the specified or default configuration.

Return type:

ReflectDomain

Raises:

ValueError – If box_size or anchor have the wrong shape, or if restitution_coefficient is outside (0, 1].

static apply(state: State, system: System) → tuple[State, System][source]#

Apply reflective boundary conditions to particles.

The method checks particles against the domain boundaries. When a particle moves beyond a boundary, the method reflects it. The impulse-momentum equations for rigid bodies govern the reflection.

Velocity Update (Impulse)

\[\begin{split}\vec{v}' &= \vec{v} + \frac{1}{m}\vec{J} \\ \vec{\omega}' &= \vec{\omega} + \mathbf{I}^{-1} (\vec{r}_{p} \times \vec{J})\end{split}\]

where the impulse vector \(J\) is:

\[\vec{J} = \frac{-(1+e)(\vec{v}_{contact} \cdot \hat{n})}{\frac{1}{m} + [\mathbf{I}^{-1} (\vec{r}_{p} \times \hat{n})] \cdot (\vec{r}_{p} \times \hat{n})} \hat{n}\]

and the velocity of the contact point \(\vec{v}_{contact}\) is:

\[\vec{v}_{contact} = \vec{v} + \vec{\omega} \times \vec{r}_{p}\]

Verlet Time-of-Collision Correction

The shared Verlet-consistent solver jaxdem.domains._toc.verlet_collision_fraction() (also used by ReflectSphereDomain) computes the collision time fraction \(\alpha \in [0, 1]\) per clump at the contact point. Before the impulse, the method reconstructs the contact-point velocity and angular velocity at the moment of collision as \(v_{col} = v + (\alpha - 1) \Delta t\, a\). It then integrates the post-impulse velocity change over the remaining \((1 - \alpha) \Delta t\) to correct positions and orientations.

Definitions

  • \(\vec{r}_c\): Particle center of mass position (jaxdem.State.pos_c).

  • \(\vec{r}_{p}\): Vector from COM to contact sphere in the lab frame (jaxdem.State.pos_p).

  • \(\vec{v}\): Particle linear velocity (jaxdem.State.vel).

  • \(\vec{\omega}\): Particle angular velocity (jaxdem.State.ang_vel).

  • \(\hat{n}\): Boundary normal vector (pointing into the domain).

  • \(\delta\): Penetration depth (positive value).

  • \(e\): Coefficient of restitution.

Parameters:

  • state (State) – The current state of the simulation.

  • system (System) – The configuration of the simulation.

Returns:

  • Tuple[State, System] – The updated State object with reflected positions and velocities, and the System object.

  • Reference

  • ———-

  • https (//www.myphysicslab.com/engine2D/collision-en.html)