CHFL_CELL
¶

typedef struct 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 
Here is the full list of functions acting on CHFL_CELL
:

CHFL_CELL *chfl_cell(const chfl_vector3d lengths, const chfl_vector3d angles)¶
Create an unit cell using the optional
lengths
andangles
parametersIf both
lengths
andangles
are NULL, this creates an infinite unit cell. Ifangles
is NULL, it defaults to[90, 90, 90]
.The shape of the cell depends on the angles: it will be ORTHORHOMBIC if the three angles are 90°, TRICLINIC otherwise.
The cell lengths should be in Angstroms, and the angles in degree.
The caller of this function should free the associated memory using
chfl_free
. Returns:
A pointer to the unit cell, or NULL in case of error. You can use
chfl_last_error
to learn about the error.

CHFL_CELL *chfl_cell_from_matrix(const chfl_vector3d matrix[3])¶
Create an unit cell from the unit cell matrix.
If
matrix
contains only zeros, then an infinite cell is created. If only the diagonal of the matrix is nonzero, then the cell isORTHORHOMBIC
. Else aTRICLINIC
cell is created. The matrix entries should be in Angstroms.The caller of this function should free the associated memory using
chfl_free
. Returns:
A pointer to the unit cell, or NULL in case of error. You can use
chfl_last_error
to learn about the error.

CHFL_CELL *chfl_cell_from_frame(CHFL_FRAME *frame)¶
Get access to the cell of a
frame
Any modification to the cell will be reflected in the
frame
. Theframe
will be kept alive, even ifchfl_free(frame)
is called, untilchfl_free
is also called on the pointer returned by this function.If
chfl_frame_set_cell
is called, this pointer will point to the new cell. Returns:
A pointer to the unit cell, or NULL in case of error. You can use
chfl_last_error
to learn about the error.

CHFL_CELL *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_free
. Returns:
A pointer to the new cell, or NULL in case of error. You can use
chfl_last_error
to learn about the error.

chfl_status chfl_cell_volume(const CHFL_CELL *cell, double *volume)¶
Get the unit cell volume of
cell
in the double pointed to byvolume
. Returns:
The operation status code. You can use
chfl_last_error
to learn about the error if the status code is notCHFL_SUCCESS
.

chfl_status chfl_cell_lengths(const CHFL_CELL *cell, chfl_vector3d lengths)¶
Get the unit cell lengths in
lengths
. The cell lengths are in Angstroms. Returns:
The operation status code. You can use
chfl_last_error
to learn about the error if the status code is notCHFL_SUCCESS
.

chfl_status 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.
This function reset cell orientation!
After the call, the cell is aligned such that the first cell vector is along the x axis, and the second cell vector is in the xy plane.
 Returns:
The operation status code. You can use
chfl_last_error
to learn about the error if the status code is notCHFL_SUCCESS
.

chfl_status chfl_cell_angles(const CHFL_CELL *cell, chfl_vector3d angles)¶
Get the cell angles in
angles
. The cell angles are in degrees. Returns:
The operation status code. You can use
chfl_last_error
to learn about the error if the status code is notCHFL_SUCCESS
.

chfl_status 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.This function reset cell orientation!
After the call, the cell is aligned such that the first cell vector is along the x axis, and the second cell vector is in the xy plane.
 Returns:
The operation status code. You can use
chfl_last_error
to learn about the error if the status code is notCHFL_SUCCESS
.

chfl_status chfl_cell_matrix(const CHFL_CELL *cell, chfl_vector3d matrix[3])¶
Get the unit
cell
matricial representation inmatrix
. Returns:
The operation status code. You can use
chfl_last_error
to learn about the error if the status code is notCHFL_SUCCESS
.

enum chfl_cellshape¶
Available cell shapes in chemfiles.
Values:

enumerator CHFL_CELL_ORTHORHOMBIC¶
The three angles are 90°

enumerator CHFL_CELL_TRICLINIC¶
The three angles may not be 90°

enumerator CHFL_CELL_INFINITE¶
Cell shape when there is no periodic boundary conditions.

enumerator CHFL_CELL_ORTHORHOMBIC¶

chfl_status chfl_cell_shape(const CHFL_CELL *cell, chfl_cellshape *shape)¶
Get the unit
cell
shape inshape
. Returns:
The operation status code. You can use
chfl_last_error
to learn about the error if the status code is notCHFL_SUCCESS
.

chfl_status chfl_cell_set_shape(CHFL_CELL *cell, chfl_cellshape shape)¶
Set the unit
cell
shape toshape
. Returns:
The operation status code. You can use
chfl_last_error
to learn about the error if the status code is notCHFL_SUCCESS
.

chfl_status chfl_cell_wrap(const CHFL_CELL *cell, chfl_vector3d vector)¶
Wrap a
vector
in the unitcell
. Returns:
The operation status code. You can use
chfl_last_error
to learn about the error if the status code is notCHFL_SUCCESS
.