class Domain

A Domain represents the spatial boundaries and constraints imposed upon the positions of the particles.

The origin is always located at the center of the domain.

By default, periodicity in each dimension is enabled when the side lengths are set.

A cuboid-shaped domain may have unique side lengths but the angles between the edges of the domain are fixed at ninety degrees. In two-dimensions, the cuboid reduces to a rectangle.

A triclinic-shaped domain is similar to cuboid-shaped except that the angles between the boundaries may different from ninety degrees. In two-dimensions, this reduces to a parallelogram.

The triclinic periodic cell is defined by a vector for each dimension. This implementation is only valid for the following two- or three-dimensions.

For the first (i.e., “x”):

\( \vec{l_x} = {l_x, 0, 0} \)

For the second (i.e., “y”):

\( \vec{l_y} = {xy, l_y, 0} \)

For the third (i.e., “z”):

\( \vec{l_z} = {xz, yz, l_z} \)

Thus, the angle, \(\alpha\), between the “x” and “y” vectors is given by

\( |l_x| |l_y| \cos\alpha = \vec{l_x} \cdot \vec{l_y}\).

For more information, see LAMMPS:

Another good resource is the inner workings of Monte Carlo codes

Public Functions

const Position &side_lengths() const

Get the side lengths.

double side_length(const int dimension) const

Get the side length.

void set_side_lengths(const Position &side_lengths)

Set the side lengths.

void set_side_length(const int dimension, const double length)

Set the side length.

void add_side_length(const double length)

Add a side length (and dimensionality) to the domain.

Domain &set_cubic(const double box_length)

Set the cubic box length. Return self for chain setting.

bool is_cubic() const

Return true if all side lengths are equal.

double xy() const

Return the xy tilt factor. By default it is zero.

double xz() const

Return the xz tilt factor.

double yz() const

Return the yz tilt factor.

void disable(const int dimension)

Disable periodicity in a given dimension.

bool periodic(const int dimension) const

Return true if given dimension is periodic.

int dimension() const

Return the dimensionality.

double volume() const

Return the volume.

Position shift(const Position &position) const

Return the shift necessary to wrap the position. This is an unoptimized version.

const Position &shift_opt(const Position &position)

Same as above, but optimized to use pre-initialized private data.

void wrap(Position *position) const

Wrap the input position. This is an unoptimized version.

Position random_position(Random *random) const

Return random position within boundaries.

void random_position(Position *position, Random *random) const

Optimized verison of the above, which allows update of existing position.

double min_side_length() const

Return the minimum side length.

double max_side_length() const

Return the maximum side length.

double inscribed_sphere_diameter() const

Return the largest possible diameter of a sphere inscribed inside domain.

void unwrap(const int dim, const int num_wrap, Position *shift) const

Return the shift for number of wraps, num_wrap, in a given dimension, dim.

std::string status_header(const std::string append = "") const

Return the header of the status for periodic output.

std::string status() const

Return the brief status for periodic output.


  • side_length[i]: set the side length of the i-th dimension. The “[i]” is to be substituted for an integer 0, 1, 2, …

  • cubic_side_length: side length of cubic perioidic boundary conditions.

  • periodic[i]: set if the i-th dimension is periodic (default: true).

  • xy: set the tilt along the x-y direction (default: 0).

  • xz: set the tilt along the x-z direction (default: 0).

  • yz: set the tilt along the y-z direction (default: 0).