3.1.14. horton/cell.h – Unit cell code to specify periodic boundary conditions

Functions

long smart_wrap(long i, long shape, long pbc)

A standardized modulo operation that works across all compilers.

Return
i % shape if pbc is non-zero. -1 is returned otherwise.

class
#include <cell.h>

3D/2D/1D periodic boundary conditions and derived quantities.

Upon construction, an object of this class acts as a read-only representation of the periodic boundary conditions. Reciprocal cell vectors, vector lengths and spacings between planes are computed immediately. All sorts of manipulations of fractional/Cartesian coordinates are supported.

Note that this implementation is specific for 3D systems, eventhough lower- dimensional periodic boundary conditions are supported. In case of 1D or 2D PBC, the cell vectors are internally extended with orthogonal basis vectors to guarantee an invertible transformation between cartesian and fractional coordinates.

Public Functions

Cell::Cell(double *_rvecs, int _nvec)

Construct a Cell object.

Parameters
  • _rvecs -

    A pointer to 3*nvec doubles that represent the real-space vectors in row-major ordering.

  • _nvec -

    The number of cell vectors. This corresponds to the dimensionality of the periodic boundary conditions.

void Cell::mic(double *delta) const

Apply the minimum image convention to a real-space relative vector.

This is an approximate implementation that sometimes fails in very skewed cells. This is a common weakness in most implementations. For more details see: http://scicomp.stackexchange.com/questions/3107/minimum-image-convention-for-triclinic-unit-cell

Parameters
  • delta -

    A pointer to 3 doubles with the relative vector. It will be modified inplace.

void Cell::to_frac(double *cart, double *frac) const

Convert a real-space vector to fractional coordinates.

Parameters
  • cart -

    A pointer to 3 doubles containing the input real-space vector.

  • frac -

    A pointer to 3 doubles in which the output is written.

void Cell::to_cart(double *frac, double *cart) const

Convert a fractional coordinates vector to real-space coordinates. This can also be interpreted as making a linear combination of real-space cell vectors.

Parameters
  • frac -

    A pointer to 3 doubles containing the input fractional coordinates.

  • cart -

    A pointer to 3 doubles to which the output is written

void Cell::g_lincomb(double *coeffs, double *gvec) const

Construct a linear combination of reciprocal cell vectors.

Parameters
  • coeffs -

    A pointer to 3 doubles containing the coefficients for the linear combination.

  • gvec -

    A pointer to 3 doubles to which the output is written

void Cell::dot_rvecs(double *cart, double *dots) const

Compute a dot-product of a real-space vector with each cell vector.

Parameters
  • cart -

    A pointer to 3 doubles containing the input fractional coordinates.

  • dots -

    A pointer to 3 doubles to which the output is written.

void Cell::add_rvec(double *delta, long *coeffs) const

Add a linear combination of cell vectors to delta.

Parameters
  • delta -

    A pointer to 3 doubles for the real-space vector to which the linear combination is added inplace.

  • coeffs -

    A pointer to 3 doubles with the coefficients of the linear combination.

int Cell::get_nvec() const

Returns the dimensionality of the periodic boundary conditions.

double Cell::get_volume() const

Return the volume (or area or length) of the cell.

double Cell::get_rspacing(int i) const

Return the spacing between the i-th real-space crystal plane

double Cell::get_gspacing(int i) const

Return the spacing between the i-th reciprocal crystal plane

double Cell::get_rlength(int i) const

Return the length of the i-th real-space cell vector

double Cell::get_glength(int i) const

Return the length of the i-th reciprocal cell vector

void Cell::copy_rvecs(double *_rvecs) const

Write a copy of rvecs to _rvecs (3*nvec doubles)

void Cell::copy_gvecs(double *_gvecs) const

Write a copy of gvecs to _gvecs (3*nvec doubles)

void Cell::copy_rlengths(double *_rlengths) const

Write a copy of rlengths to _rlengths (nvec doubles)

void Cell::copy_glengths(double *_glengths) const

Write a copy of glengths to _glengths (nvec doubles)

void Cell::copy_rspacings(double *_rspacings) const

Write a copy of rspacings to _rspacings (nvec doubles)

void Cell::copy_gspacings(double *_gspacings) const

Write a copy of gspacings to _gspacings (nvec doubles)

void Cell::set_ranges_rcut(double *center, double rcut, long *ranges_begin, long *ranges_end) const

Get ranges of periodic images without a cutoff radius.

This function effectively defines a supercell that is guaranteed to enclose the cutoff sphere.

Parameters
  • center -

    A pointer to three doubles that specify the center of the cutoff sphere in real-space.

  • rcut -

    The cutoff radius.

  • ranges_begin -

    A pointer to nvec longs to which the begin of each range of periodic images along a periodic boundary condition is written.

  • ranges_end -

    A pointer to nvec longs to which the end of each range of periodic images along a periodic boundary condition is written. Then end values are non-inclusive as in Python ranges.

long Cell::select_inside(double *origin, double *center, double rcut, long *ranges_begin, long *ranges_end, long *shape, long *pbc, long *indexes) const

Selects a list of periodic images inside a cutoff sphere.

Return
The number of periodic images inside the cutoff sphere.
Parameters
  • origin -

    A pointer of three doubles with the origin of a supercell.

  • center -

    The center of the cutoff sphere.

  • rcut -

    The cutoff radius.

  • ranges_begin -

    As obtained with set_ranges_rcut.

  • ranges_end -

    As obtained with set_ranges_rcut.

  • shape -

    A pointer of three longs with the shape of the supercell.

  • pbc -

    A pointer to integer flags indicating the periodicity of the supercell along each periodic boundary condition.

  • indexes -

    A sufficiently large pre-allocated output array to which the indexes of the selected periodic images are written. The number of rows is the product of the lengths of the ranges specified by ranges_begin and ranges_end. The number of columns equals nvec. The elements are stored in row-major order.

Private Members

double Cell::rvecs[9]
double Cell::gvecs[9]
double Cell::rlengths[3]
double Cell::glengths[3]
double Cell::rspacings[3]
double Cell::gspacings[3]
double Cell::volume
int Cell::nvec