Domain

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: https://docs.lammps.org/Howto_triclinic.html

Another good resource is the inner workings of Monte Carlo codes https://doi.org/10.1080/08927022.2013.819102

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.

Arguments

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).