jaxdem.domains.reflect_sphere#

Reflective boundary-condition domain.

Classes

ReflectSphereDomain(box_size, inv_box_size, ...)

A Domain implementation that enforces reflective boundary conditions only for spheres.
class jaxdem.domains.reflect_sphere.ReflectSphereDomain(box_size: Array, inv_box_size: Array, anchor: Array, restitution_coefficient: Array)#

Bases: Domain

A Domain implementation that enforces reflective boundary conditions only for spheres. This dedicated version exists for performance.

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, scaled by restitution_coefficient.

Notes

  • The reflection occurs at the boundaries defined by anchor and anchor + box_size.

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 ReflectSphereDomain class.

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 with the specified or default configuration.

Return type:

ReflectSphereDomain

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 its position back into the box. It also reverses the velocity component normal to that boundary, scaled by the restitution coefficient \(e\).

\[\begin{split}l &= a + R \\ u &= a + B - R \\ v' &= \begin{cases} -e\,v & \text{if } r < l \text{ or } r > u \\ v & \text{otherwise} \end{cases} \\ r' &= \begin{cases} 2l - r & \text{if } r < l \\ r & \text{otherwise} \end{cases} \\ r'' &= \begin{cases} 2u - r' & \text{if } r' > u \\ r' & \text{otherwise} \end{cases} \\ r &= r''\end{split}\]
where:

  • \(r\) is the current particle position (jaxdem.State.pos)

  • \(v\) is the current particle velocity (jaxdem.State.vel)

  • \(a\) is the domain anchor (Domain.anchor)

  • \(B\) is the domain box size (Domain.box_size)

  • \(R\) is the particle radius (jaxdem.State.rad)

  • \(l\) is the lower boundary for the particle center

  • \(u\) is the upper boundary for the particle center

  • \(e\) is the restitution coefficient.

Verlet Time-of-Collision Correction

The shared Verlet-consistent solver jaxdem.domains._toc.verlet_collision_fraction() (also used by ReflectDomain) computes the collision time fraction \(\alpha \in [0, 1]\) and the velocity at the moment of collision. The method reconstructs the pre-collision velocity as \(v_{col} = v + (\alpha - 1) \Delta t\, a\).

TO DO: Check correctness when adding different shape types and angular velocity

Parameters:

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

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

Returns:

The updated State object with reflected positions and velocities, and the System object.

Return type:

Tuple[State, System]

Note

  • Only works for states with ONLY spheres.