jaxdem.domains.periodic#

Periodic boundary-condition domain.

Classes

PeriodicDomain(box_size, inv_box_size, ...)

A Domain implementation that enforces periodic boundary conditions.
class jaxdem.domains.periodic.PeriodicDomain(box_size: Array, inv_box_size: Array, anchor: Array, *, box_rate: Array = <factory>)#

Bases: Domain

A Domain implementation that enforces periodic boundary conditions.

Particles that move out of one side of the simulation box re-enter from the opposite side. The domain computes the displacement vector between particles with the minimum image convention.

box_rate is the time derivative of box_size. Periodic images of a particle move at image * box_rate, which relative_velocity subtracts. Time stepping does not advance box_size; set box_rate when a protocol changes the box continuously, and leave it zero otherwise. Discrete rescaling goes through Domain.resize.

search_geometry: ClassVar[SearchGeometry | None] = 'orthogonal'#
box_rate: Array#

Time derivative of box_size, shape (dim,).

A periodic image of particle j sits at pos_j + image * box_size and moves at image * box_rate when the box changes. Contact laws read the relative velocity through relative_velocity, which subtracts that image velocity; without it a pair interacting across a boundary would see the change of its image offset as sliding and wind up its tangential spring. Domain.resize sets this rate for the duration of its history update and zero means a fixed box.

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

Construct a periodic box; box_rate defaults to zero.

rates_between(old: Domain, dt: Array) → Domain[source]#

Set box_rate from the box change since old.

static relative_velocity(ri: jax.Array, rj: jax.Array, vi: jax.Array, vj: jax.Array, system: System) → jax.Array[source]#

Subtract the velocity of the image selected by displacement.

search_geometry_snapshot() → Array[source]#

Return periodic box geometry used by search caches.

search_geometry_drift(previous: Array, old_pos: Array) → Array[source]#

Bound periodic image motion for changes along any box axes.

property periodic: bool[source]#

Whether the domain enforces periodic boundary conditions.

static displacement(ri: jax.Array, rj: jax.Array, system: System) → jax.Array[source]#

Compute the minimum image displacement vector between two particles \(r_i\) and \(r_j\).

For periodic boundary conditions, the displacement is the shortest vector that connects \(r_j\) to \(r_i\), possibly by crossing periodic boundaries.

Parameters:

  • ri (jax.Array) – Position vector of the first particle \(r_i\).

  • rj (jax.Array) – Position vector of the second particle \(r_j\).

  • system (System) – The configuration of the simulation, containing the domain instance with anchor and box_size for periodicity.

Returns:

The minimum image displacement vector:

\[\begin{split}& r_{ij} = (r_i - a) - (r_j - a) \\ & r_{ij} = r_{ij} - B \cdot \text{round}(r_{ij}/B)\end{split}\]
where:

Return type:

jax.Array

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

Wrap particles back into the primary simulation box.

\[r = r - B \cdot \text{floor}((r - a)/B)\]
where:
Parameters:

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

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

Returns:

The updated State object with wrapped particle positions, and the System object.

Return type:

Tuple[State, System]