CHFL_CELL
¶
CHFL_CELL
¶An opaque type handling an unit cell.
A CHFL_CELL
represent the box containing the atoms, and its periodicity.
An 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 |
chfl_cell
(const chfl_vector3d lengths)¶Create an unit cell from three lengths
. The unit cell shape is CHFL_CELL_ORTHORHOMBIC
.
The cell lengths should be in Angstroms.
The caller of this function should free the associated memory using chfl_cell_free
.
CHFL_CELL* cell = chfl_cell((chfl_vector3d){10, 10, 10});
if (cell == NULL) {
/* handle error */
}
chfl_cell_free(cell);
chfl_last_error
to learn about the error.
chfl_cell_triclinic
(const chfl_vector3d lengths, const chfl_vector3d angles)¶Create an unit cell from three lengths
and three angles
. The unit cell shape is CHFL_CELL_TRICLINIC
.
The cell lengths should be in Angstroms, and the angles in degree.
The cell angles are defined as follow: alpha is the angles between the cell vector b
and c
; beta as the angle between a
and c
; and gamma as the angle between a
and b
.
The caller of this function should free the associated memory using chfl_cell_free
.
CHFL_CELL* cell = chfl_cell_triclinic((chfl_vector3d){10, 10, 10}, (chfl_vector3d){122, 97, 97});
if (cell == NULL) {
/* handle error */
}
chfl_cell_free(cell);
chfl_last_error
to learn about the error.
chfl_cell_from_frame
(const CHFL_FRAME *frame)¶Get a copy of the unit cell of a frame
.
The caller of this function should free the associated memory using chfl_cell_free
.
CHFL_FRAME* frame = chfl_frame();
CHFL_CELL* cell = chfl_cell_from_frame(frame);
if (cell == NULL) {
/* handle error */
}
chfl_cell_free(cell);
chfl_frame_free(frame);
chfl_last_error
to learn about the error.
chfl_cell_copy
(const CHFL_CELL *cell)¶Get a copy of a cell
.
The caller of this function should free the associated memory using chfl_cell_free
.
CHFL_CELL* cell = chfl_cell((chfl_vector3d){10, 10, 10});
CHFL_CELL* copy = chfl_cell_copy(cell);
if (copy == NULL) {
/* handle error */
}
chfl_cell_free(copy);
chfl_cell_free(cell);
chfl_last_error
to learn about the error.
chfl_cell_volume
(const CHFL_CELL *cell, double *volume)¶Get the unit cell volume of cell
in the double pointed to by volume
.
CHFL_CELL* cell = chfl_cell((chfl_vector3d){10, 10, 10});
double volume = 0;
chfl_cell_volume(cell, &volume);
assert(volume == 1000);
chfl_cell_free(cell);
chfl_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.
chfl_cell_lengths
(const CHFL_CELL *cell, chfl_vector3d lengths)¶Get the unit cell lengths in lengths
. The cell lengths are in Angstroms.
CHFL_CELL* cell = chfl_cell((chfl_vector3d){10, 11, 12});
chfl_vector3d lengths = {0, 0, 0};
chfl_cell_lengths(cell, lengths);
assert(lengths[0] == 10);
assert(lengths[1] == 11);
assert(lengths[2] == 12);
chfl_cell_free(cell);
chfl_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.
chfl_cell_set_lengths
(CHFL_CELL *cell, const chfl_vector3d lengths)¶Set the unit cell lengths to lengths
.
The cell lengths should be in Angstroms.
CHFL_CELL* cell = chfl_cell((chfl_vector3d){10, 10, 10});
chfl_cell_set_lengths(cell, (chfl_vector3d){42, 8, 3});
chfl_vector3d lengths = {0, 0, 0};
chfl_cell_lengths(cell, lengths);
assert(lengths[0] == 42);
assert(lengths[1] == 8);
assert(lengths[2] == 3);
chfl_cell_free(cell);
chfl_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.
chfl_cell_angles
(const CHFL_CELL *cell, chfl_vector3d angles)¶Get the cell angles in angles
. The cell angles are in degrees.
CHFL_CELL* cell = chfl_cell((chfl_vector3d){10, 10, 10});
chfl_vector3d angles = {0, 0, 0};
chfl_cell_angles(cell, angles);
assert(angles[0] == 90);
assert(angles[1] == 90);
assert(angles[2] == 90);
chfl_cell_free(cell);
chfl_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.
chfl_cell_set_angles
(CHFL_CELL *cell, const chfl_vector3d angles)¶Set the cell angles to angles
.
The cell lengths should be in degree. Trying to set cell angles on a cell which is not triclinic (does not have the CHFL_CELL_TRICLINIC
shape) is an error.
CHFL_CELL* cell = chfl_cell_triclinic((chfl_vector3d){10, 10, 10}, (chfl_vector3d){90, 90, 90});
chfl_cell_set_angles(cell, (chfl_vector3d){120, 110, 100});
chfl_vector3d angles = {0, 0, 0};
chfl_cell_angles(cell, angles);
assert(angles[0] == 120);
assert(angles[1] == 110);
assert(angles[2] == 100);
chfl_cell_free(cell);
chfl_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.
chfl_cell_matrix
(const CHFL_CELL *cell, chfl_vector3d matrix[3])¶Get the unit cell
matricial representation in matrix
.
The unit cell representation is obtained by aligning the a vector along the x axis and putting the b vector in the xy plane. This make the matrix an upper triangular matrix:
| a_x b_x c_x |
| 0 b_y c_y |
| 0 0 c_z |
CHFL_CELL* cell = chfl_cell((chfl_vector3d){10, 11, 12});
chfl_vector3d matrix[3];
chfl_cell_matrix(cell, matrix);
assert(matrix[0][0] == 10);
assert(matrix[1][1] == 11);
assert(matrix[2][2] == 12);
// Out of diagonal terms are zero
assert(matrix[2][1] == 0);
chfl_cell_free(cell);
chfl_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.
chfl_cellshape
¶Available cell shapes in chemfiles.
Values:
CHFL_CELL_ORTHORHOMBIC
= 0¶The three angles are 90°
CHFL_CELL_TRICLINIC
= 1¶The three angles may not be 90°
CHFL_CELL_INFINITE
= 2¶Cell shape when there is no periodic boundary conditions.
chfl_cell_shape
(const CHFL_CELL *cell, chfl_cellshape *shape)¶Get the unit cell
shape in shape
.
CHFL_CELL* cell = chfl_cell((chfl_vector3d){10, 10, 10});
chfl_cellshape shape;
chfl_cell_shape(cell, &shape);
assert(shape == CHFL_CELL_ORTHORHOMBIC);
chfl_cell_free(cell);
chfl_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.
chfl_cell_set_shape
(CHFL_CELL *cell, chfl_cellshape shape)¶Set the unit cell
shape to shape
.
CHFL_CELL* cell = chfl_cell((chfl_vector3d){10, 10, 10});
chfl_cell_set_shape(cell, CHFL_CELL_TRICLINIC);
chfl_cellshape shape;
chfl_cell_shape(cell, &shape);
assert(shape == CHFL_CELL_TRICLINIC);
chfl_cell_free(cell);
chfl_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.
chfl_cell_wrap
(const CHFL_CELL *cell, chfl_vector3d vector)¶Wrap a vector
in the unit cell
.
CHFL_CELL* cell = chfl_cell((chfl_vector3d){10, 10, 10});
chfl_vector3d position = {4, 12, -18};
chfl_cell_wrap(cell, position);
assert(position[0] == 4);
assert(position[1] == 2);
assert(position[2] == 2);
chfl_cell_free(cell);
chfl_last_error
to learn about the error if the status code is not CHFL_SUCCESS
.
chfl_cell_free
(CHFL_CELL *cell)¶Free the memory associated with a cell
.
CHFL_CELL* cell = chfl_cell((chfl_vector3d){10, 10, 10});
if (cell == NULL) {
/* handle error */
}
chfl_cell_free(cell);
CHFL_SUCCESS