Function manipulating 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 |

CHFL_CELL *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.

Return
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_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.

Return
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. The frame will be kept alive, even if chfl_frame_free is called, until chfl_cell_free is also called on the pointer returned by this function.

The pointer returned by this function points directly inside the frame, and will be invalidated if any of the following function is called on the frame:

  • chfl_frame_set_cell

Calling any function on an invalidated pointer is undefined behavior. Even if the pointer if invalidated, it stills needs to be released with chfl_cell_free.

Return
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_cell_free.

Return
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 by volume.

Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_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.

Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_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.

Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_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.

Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_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.

Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status 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 |

Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

enum 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_status chfl_cell_shape(const CHFL_CELL *cell, chfl_cellshape *shape)

Get the unit cell shape in shape.

Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_cell_set_shape(CHFL_CELL *cell, chfl_cellshape shape)

Set the unit cell shape to shape.

Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_cell_wrap(const CHFL_CELL *cell, chfl_vector3d vector)

Wrap a vector in the unit cell.

Return
The operation status code. You can use chfl_last_error to learn about the error if the status code is not CHFL_SUCCESS.

chfl_status chfl_cell_free(const CHFL_CELL *cell)

Free the memory associated with a cell.

Return
CHFL_SUCCESS