Unit Cell class

class chemfiles::UnitCell

An UnitCell represent the box containing the atoms, and its periodicity

A unit cell is fully represented by three lengths (a, b, c); and three angles (alpha, beta, gamma). The angles are stored in degrees, and the lengths in Angstroms.

A cell also has a matricial representation, by projecting the three base vector into an orthonormal base. We choose to represent such matrix as an upper triangular matrix:

| a_x   b_x   c_x |
|  0    b_y   c_y |
|  0     0    c_z |

Public Types

enum chemfiles::UnitCellCellShape

Possible shapes for the unit cell.

Values:

chemfiles::UnitCellORTHORHOMBIC = 0

Orthorhombic cell, with the three angles equals to 90°

chemfiles::UnitCellTRICLINIC = 1

Triclinic cell, with any values for the angles.

chemfiles::UnitCellINFINITE = 2

Infinite cell, to use when there is no cell.

Public Functions

UnitCellUnitCell()

Construct an INFINITE unit cell, with all lengths set to 0

auto cell = UnitCell();

assert(cell.shape() == UnitCell::INFINITE);

assert(cell.a() == 0);
assert(cell.b() == 0);
assert(cell.c() == 0);

assert(cell.alpha() == 90);
assert(cell.beta() == 90);
assert(cell.gamma() == 90);

UnitCellUnitCell(double a)

Construct a cubic unit cell of side size a

auto cell = UnitCell(32);

assert(cell.shape() == UnitCell::ORTHORHOMBIC);

assert(cell.a() == 32);
assert(cell.b() == 32);
assert(cell.c() == 32);

assert(cell.alpha() == 90);
assert(cell.beta() == 90);
assert(cell.gamma() == 90);

UnitCellUnitCell(double a, double b, double c)

Construct an ORTHOROMBIC unit cell of side size a, b, c

auto cell = UnitCell(11, 22, 33);

assert(cell.shape() == UnitCell::ORTHORHOMBIC);

assert(cell.a() == 11);
assert(cell.b() == 22);
assert(cell.c() == 33);

assert(cell.alpha() == 90);
assert(cell.beta() == 90);
assert(cell.gamma() == 90);

UnitCellUnitCell(double a, double b, double c, double alpha, double beta, double gamma)

Construct an unit cell of side size a, b, c, and cell angles alpha, beta, gamma.

If all of alpha, beta and gamma are 90.0, then the cell is ORTHOROMBIC. Else a TRICLINIC cell is created.

auto cell = UnitCell(11, 22, 33);

assert(cell.shape() == UnitCell::ORTHORHOMBIC);

assert(cell.a() == 11);
assert(cell.b() == 22);
assert(cell.c() == 33);

assert(cell.alpha() == 90);
assert(cell.beta() == 90);
assert(cell.gamma() == 90);

Matrix3D chemfiles::UnitCellmatrix() const

Get the cell matrix, defined as the upper triangular matrix

| a_x   b_x   c_x |
|  0    b_y   c_y |
|  0     0    c_z |

auto cell = UnitCell(11, 22, 33);
auto matrix = cell.matrix();

assert(matrix[0][0] == 11);
assert(matrix[1][1] == 22);
assert(matrix[2][2] == 33);

assert(fabs(matrix[0][1]) < 1e-12);
assert(fabs(matrix[0][2]) < 1e-12);
assert(fabs(matrix[1][2]) < 1e-12);

assert(matrix[1][0] == 0);
assert(matrix[2][0] == 0);
assert(matrix[2][1] == 0);

CellShape chemfiles::UnitCellshape() const

Get the cell shape

auto cell = UnitCell(11, 22, 33);
assert(cell.shape() == UnitCell::ORTHORHOMBIC);

cell.set_shape(UnitCell::TRICLINIC);
assert(cell.shape() == UnitCell::TRICLINIC);

void UnitCellset_shape(CellShape shape)

Set the cell shape to shape

auto cell = UnitCell(11, 22, 33);
assert(cell.shape() == UnitCell::ORTHORHOMBIC);

cell.set_shape(UnitCell::TRICLINIC);
assert(cell.shape() == UnitCell::TRICLINIC);

Exceptions
  • Error: if shape is ORTHORHOMBIC and some angles are not 90°, or if shape is INFINITE and some lengths are not 0.0.

double chemfiles::UnitCella() const

Get the first lenght (a) of the cell

auto cell = UnitCell(11, 22, 33);

assert(cell.a() == 11);
assert(cell.b() == 22);
assert(cell.c() == 33);

cell.set_a(111);
cell.set_b(222);
cell.set_c(333);

assert(cell.a() == 111);
assert(cell.b() == 222);
assert(cell.c() == 333);

void UnitCellset_a(double val)

Set the first lenght (a) of the cell

auto cell = UnitCell(11, 22, 33);

assert(cell.a() == 11);
assert(cell.b() == 22);
assert(cell.c() == 33);

cell.set_a(111);
cell.set_b(222);
cell.set_c(333);

assert(cell.a() == 111);
assert(cell.b() == 222);
assert(cell.c() == 333);

Exceptions
  • Error: if the cell shape is INFINITE.

double chemfiles::UnitCellb() const

Get the second lenght (b) of the cell

auto cell = UnitCell(11, 22, 33);

assert(cell.a() == 11);
assert(cell.b() == 22);
assert(cell.c() == 33);

cell.set_a(111);
cell.set_b(222);
cell.set_c(333);

assert(cell.a() == 111);
assert(cell.b() == 222);
assert(cell.c() == 333);

void UnitCellset_b(double val)

Set the second lenght (b) of the cell

auto cell = UnitCell(11, 22, 33);

assert(cell.a() == 11);
assert(cell.b() == 22);
assert(cell.c() == 33);

cell.set_a(111);
cell.set_b(222);
cell.set_c(333);

assert(cell.a() == 111);
assert(cell.b() == 222);
assert(cell.c() == 333);

Exceptions
  • Error: if the cell shape is INFINITE.

double chemfiles::UnitCellc() const

Get the third lenght (c) of the cell

auto cell = UnitCell(11, 22, 33);

assert(cell.a() == 11);
assert(cell.b() == 22);
assert(cell.c() == 33);

cell.set_a(111);
cell.set_b(222);
cell.set_c(333);

assert(cell.a() == 111);
assert(cell.b() == 222);
assert(cell.c() == 333);

void UnitCellset_c(double val)

Set the third lenght (c) of the cell

auto cell = UnitCell(11, 22, 33);

assert(cell.a() == 11);
assert(cell.b() == 22);
assert(cell.c() == 33);

cell.set_a(111);
cell.set_b(222);
cell.set_c(333);

assert(cell.a() == 111);
assert(cell.b() == 222);
assert(cell.c() == 333);

Exceptions
  • Error: if the cell shape is INFINITE.

double chemfiles::UnitCellalpha() const

Get the first angle (alpha) of the cell

auto cell = UnitCell(1, 1, 1, 60, 80, 123);

assert(cell.alpha() == 60);
assert(cell.beta() == 80);
assert(cell.gamma() == 123);

cell.set_alpha(91);
cell.set_beta(92);
cell.set_gamma(93);

assert(cell.alpha() == 91);
assert(cell.beta() == 92);
assert(cell.gamma() == 93);

void UnitCellset_alpha(double val)

Set the first angle (alpha) of the cell

auto cell = UnitCell(1, 1, 1, 60, 80, 123);

assert(cell.alpha() == 60);
assert(cell.beta() == 80);
assert(cell.gamma() == 123);

cell.set_alpha(91);
cell.set_beta(92);
cell.set_gamma(93);

assert(cell.alpha() == 91);
assert(cell.beta() == 92);
assert(cell.gamma() == 93);

Exceptions
  • Error: if the cell shape is not TRICLINIC.

double chemfiles::UnitCellbeta() const

Get the second angle (beta) of the cell

auto cell = UnitCell(1, 1, 1, 60, 80, 123);

assert(cell.alpha() == 60);
assert(cell.beta() == 80);
assert(cell.gamma() == 123);

cell.set_alpha(91);
cell.set_beta(92);
cell.set_gamma(93);

assert(cell.alpha() == 91);
assert(cell.beta() == 92);
assert(cell.gamma() == 93);

void UnitCellset_beta(double val)

Set the second angle (beta) of the cell if possible

auto cell = UnitCell(1, 1, 1, 60, 80, 123);

assert(cell.alpha() == 60);
assert(cell.beta() == 80);
assert(cell.gamma() == 123);

cell.set_alpha(91);
cell.set_beta(92);
cell.set_gamma(93);

assert(cell.alpha() == 91);
assert(cell.beta() == 92);
assert(cell.gamma() == 93);

Exceptions
  • Error: if the cell shape is not TRICLINIC.

double chemfiles::UnitCellgamma() const

Get the third angle (gamma) of the cell

auto cell = UnitCell(1, 1, 1, 60, 80, 123);

assert(cell.alpha() == 60);
assert(cell.beta() == 80);
assert(cell.gamma() == 123);

cell.set_alpha(91);
cell.set_beta(92);
cell.set_gamma(93);

assert(cell.alpha() == 91);
assert(cell.beta() == 92);
assert(cell.gamma() == 93);

void UnitCellset_gamma(double val)

Set the third angle (gamma) of the cell if possible

auto cell = UnitCell(1, 1, 1, 60, 80, 123);

assert(cell.alpha() == 60);
assert(cell.beta() == 80);
assert(cell.gamma() == 123);

cell.set_alpha(91);
cell.set_beta(92);
cell.set_gamma(93);

assert(cell.alpha() == 91);
assert(cell.beta() == 92);
assert(cell.gamma() == 93);

Exceptions
  • Error: if the cell shape is not TRICLINIC.

double UnitCellvolume() const

Get the unit cell volume

auto cell = UnitCell(11, 22, 33);
assert(cell.volume() == 11 * 22 * 33);

Vector3D UnitCellwrap(const Vector3D &vector) const

Wrap the vector in the unit cell, using periodic boundary conditions.

For an orthorombic unit cell, this make sure that all the vector components are between -L/2 and L/2 where L is the corresponding cell length.

auto cell = UnitCell(11, 22, 33);
assert(cell.wrap(Vector3D(14, -12, 5)) == Vector3D(3, 10, 5));