# 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 lenghts (a, b, c); and three angles (alpha, beta, gamma). The angles are stored in degrees, and the lenghts 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_vector_t lenghts)

Create an unit cell from three lenghts. The unit cell shape is CHFL_CELL_ORTHORHOMBIC.

The cell lenghts should be in Angstroms.

The caller of this function should free the associated memory using chfl_cell_free.

CHFL_CELL* cell = chfl_cell((chfl_vector_t){10, 10, 10});

if (cell == NULL) {
/* handle error */
}

chfl_cell_free(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_triclinic(const chfl_vector_t lenghts, const chfl_vector_t angles)

Create an unit cell from three lenghts and three angles. The unit cell shape is CHFL_CELL_TRICLINIC.

The cell lenghts 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_vector_t){10, 10, 10}, (chfl_vector_t){122, 97, 97});

if (cell == NULL) {
/* handle error */
}

chfl_cell_free(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_from_frame(const CHFL_FRAME *const 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);

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 *const 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_vector_t){10, 10, 10});
CHFL_CELL* copy = chfl_cell_copy(cell);

if (copy == NULL) {
/* handle error */
}

chfl_cell_free(copy);
chfl_cell_free(cell);

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 *const cell, double *volume)

Get the unit cell volume of cell in the double pointed to by volume.

CHFL_CELL* cell = chfl_cell((chfl_vector_t){10, 10, 10});

double volume = 0;
chfl_cell_volume(cell, &volume);
assert(volume == 1000);

chfl_cell_free(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_lengths(const CHFL_CELL *const cell, chfl_vector_t lengths)

Get the unit cell lenghts in lengths. The cell lengths are in Angstroms.

CHFL_CELL* cell = chfl_cell((chfl_vector_t){10, 11, 12});

chfl_vector_t 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);

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 *const cell, const chfl_vector_t lenghts)

Set the unit cell lenghts to lenghts.

The cell lenghts should be in Angstroms.

CHFL_CELL* cell = chfl_cell((chfl_vector_t){10, 10, 10});

chfl_cell_set_lengths(cell, (chfl_vector_t){42, 8, 3});

chfl_vector_t 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);

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 *const cell, chfl_vector_t angles)

Get the cell angles in angles. The cell angles are in degrees.

CHFL_CELL* cell = chfl_cell((chfl_vector_t){10, 10, 10});

chfl_vector_t 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);

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 *const cell, const chfl_vector_t angles)

Set the cell angles to angles.

The cell lenghts 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_vector_t){10, 10, 10}, (chfl_vector_t){90, 90, 90});

chfl_cell_set_angles(cell, (chfl_vector_t){120, 110, 100});

chfl_vector_t 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);

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 *const cell, chfl_vector_t 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_vector_t){10, 11, 12});

chfl_vector_t 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);

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_cell_shape_t

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 *const cell, chfl_cell_shape_t *const shape)

Get the unit cell shape in shape.

CHFL_CELL* cell = chfl_cell((chfl_vector_t){10, 10, 10});

chfl_cell_shape_t shape;
chfl_cell_shape(cell, &shape);
assert(shape == CHFL_CELL_ORTHORHOMBIC);

chfl_cell_free(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_set_shape(CHFL_CELL *const cell, chfl_cell_shape_t shape)

Set the unit cell shape to shape.

CHFL_CELL* cell = chfl_cell((chfl_vector_t){10, 10, 10});

chfl_cell_set_shape(cell, CHFL_CELL_TRICLINIC);

chfl_cell_shape_t shape;
chfl_cell_shape(cell, &shape);
assert(shape == CHFL_CELL_TRICLINIC);

chfl_cell_free(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(CHFL_CELL *const cell)

Free the memory associated with a cell.

CHFL_CELL* cell = chfl_cell((chfl_vector_t){10, 10, 10});

if (cell == NULL) {
/* handle error */
}

chfl_cell_free(cell);

Return
CHFL_SUCCESS