# 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)

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_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_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_free(frame) is called, until chfl_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.

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