Functions
double	resolution (UnitCell *cell, signed int h, signed int k, signed int l)

UnitCell *	cell_rotate (UnitCell *in, struct quaternion quat)

UnitCell *	rotate_cell (UnitCell *in, double omega, double phi, double rot)

void	cell_print (UnitCell *cell)

void	cell_print_oneline (UnitCell *cell)

void	cell_print_full (UnitCell *cell)

UnitCell *	load_cell_from_pdb (const char *filename)

UnitCell *	load_cell_from_file (const char *filename)

void	write_cell (UnitCell cell, FILE fh)

int	cell_is_sensible (UnitCell *cell)

int	validate_cell (UnitCell *cell)

UnitCell *	uncenter_cell (UnitCell in, IntegerMatrix pC, RationalMatrix *pCi)

int	bravais_lattice (UnitCell *cell)

int	has_unique_axis (LatticeType l)

int	right_handed (UnitCell *cell)

const char *	str_lattice (LatticeType l)

LatticeType	lattice_from_str (const char *s)

int	forbidden_reflection (UnitCell *cell, signed int h, signed int k, signed int l)

double	cell_get_volume (UnitCell *cell)

double	lowest_reflection (UnitCell *cell)

int	compare_cell_parameters (UnitCell cell, UnitCell reference, const double *tols)

int	compare_cell_parameters_and_orientation (UnitCell cell, UnitCell reference, const double *tols)

int	compare_permuted_cell_parameters_and_orientation (UnitCell cell, UnitCell reference, const double tols, IntegerMatrix *pmb)

int	compare_derivative_cell_parameters (UnitCell cell, UnitCell reference, const double tols, int csl, RationalMatrix *pmb)

UnitCell *	compare_reindexed_cell_parameters (UnitCell cell_in, UnitCell reference_in, const double tols, RationalMatrix *pmb)

SymOpList *	get_lattice_symmetry (UnitCell *cell)

Detailed Description

Unit cell utility functions.

Function Documentation

◆ cell_get_volume()

double cell_get_volume ( UnitCell * cell )

extern

Returns: cell volume in m^3

◆ cell_rotate()

UnitCell * cell_rotate	(	UnitCell *	in,
		struct quaternion	quat )

extern

Parameters

in	A UnitCell to rotate
quat	A quaternion

Rotate a UnitCell using a quaternion.

Returns: a newly allocated rotated copy of in.

◆ compare_cell_parameters()

int compare_cell_parameters	(	UnitCell *	cell,
		UnitCell *	reference,
		const double *	tols )

extern

Parameters

cell	A UnitCell
reference	Another UnitCell
tols	Pointer to tolerances for a,b,c (fractional), al,be,ga (radians)

Compare the two unit cells. If the real space parameters match to within the specified tolerances, and the centering matches, this function returns 1. Otherwise 0.

This function considers the cell parameters and centering, but ignores the orientation of the cell. If you want to compare the orientation as well, use compare_cell_parameters_and_orientation() instead.

Returns: non-zero if the cells match.

◆ compare_cell_parameters_and_orientation()

int compare_cell_parameters_and_orientation	(	UnitCell *	cell,
		UnitCell *	reference,
		const double *	tols )

extern

Parameters

cell	A UnitCell
reference	Another UnitCell
tols	Pointer to six tolerance values (see below)

Compare the two unit cells. If the axes match in length (to within the specified tolerances), this function returns non-zero.

This function compares the orientation of the cell as well as the parameters. If you just want to see if the parameters are the same, use compare_cell_parameters() instead.

The comparison is done by checking that the lengths of the unit cell axes are the same between the two cells, and that the axes have similar directions in 3D space. The first three tolerance values are the maximum allowable fractional differences between the a,b,c axis lengths (respectively) of the two cells. The last three tolerance values are the maximum allowable angles, in radians, between the directions of the a,b,c axes of the two cells.

cell and reference must have the same centering. Otherwise, this function always returns zero.

Returns: non-zero if the cells match.

◆ compare_derivative_cell_parameters()

int compare_derivative_cell_parameters	(	UnitCell *	cell_in,
		UnitCell *	reference_in,
		const double *	tols,
		int	csl,
		RationalMatrix **	pmb )

extern

Parameters

cell_in	A UnitCell
reference_in	Another UnitCell
tols	Pointer to tolerances for a,b,c (fractional), al,be,ga (radians)
csl	Non-zero to look for coincidence site lattice relationships
pmb	Place to store pointer to matrix

Compare the cell_in with reference_in. If cell is a derivative lattice of reference, within fractional axis length differences tols[0..2] and absolute angle difference tols[3..5] (in radians), this function returns non-zero and stores the transformation which needs to be applied to cell_in at pmb.

Note that the tolerances will be applied to the primitive unit cell. If the reference cell is centered, a primitive unit cell will first be calculated.

Subject to the tolerances, this function will find the transformation which gives the best match to the reference cell, using the Euclidian norm in G6 [see e.g. Andrews and Bernstein, Acta Cryst. A44 (1988) p1009].

Only the cell parameters will be compared. The relative orientations are irrelevant.

If csl is zero, the lattices must be derivatives of one another. If non-zero, a coincidence site lattice relationship will be searched for, meaning that the lattice points of the transformed version of cell_in might not coincide with lattice points of reference_in.

This function is used by CrystFEL's cell_tool program to find non-obvious relationships between crystal lattices. For most routine comparisons, this function is probably not the one you need!

Returns: non-zero if the cells match, zero for no match or error.

◆ compare_permuted_cell_parameters_and_orientation()

int compare_permuted_cell_parameters_and_orientation	(	UnitCell *	cell,
		UnitCell *	reference,
		const double *	tols,
		IntegerMatrix **	pmb )

extern

Parameters

cell	A UnitCell
reference	Another UnitCell
tols	Pointer to six tolerance values (see below)
pmb	Place to store pointer to matrix

Compare the two unit cells. If, using any permutation of the axes, the axes can be made to match in length and the axes aligned in space, this function returns non-zero and stores the transformation which must be applied to cell at pmb.

A "permutation" means a transformation represented by a matrix with all elements equal to +1, 0 or -1, having determinant +1 or -1. That means that this function will find the relationship between a left-handed and a right- handed basis.

Note that the orientations of the cells must match, not just the parameters. The comparison is done after reindexing using compare_cell_parameters_and_orientation(). See that function for more details.

cell and reference must have the same centering. Otherwise, this function always returns zero.

Returns: non-zero if the cells match.

◆ compare_reindexed_cell_parameters()

UnitCell * compare_reindexed_cell_parameters	(	UnitCell *	cell_in,
		UnitCell *	reference_in,
		const double *	tols,
		RationalMatrix **	pmb )

extern

Parameters

cell_in	A UnitCell
reference_in	Another UnitCell
tols	Pointer to tolerances for a,b,c (fractional), al,be,ga (radians)
pmb	Place to store pointer to matrix, or NULL if not needed

Compare the cell_in with reference_in. If they represent the same lattice, this function returns a copy of cell_in transformed to look similar to reference_in. Otherwise, it returns NULL.

If \pmb is non-NULL, the transformation which needs to be applied to cell_in will be stored there.

Only the cell parameters will be compared. The relative orientations are irrelevant. The tolerances will be applied to the transformed copy of cell_in, i.e. the version of the input cell which looks similar to reference_in. Subject to the tolerances, the cell will be chosen which has the lowest distance measured in G^6 unit cell space.

There will usually be several transformation matrices which produce exactly the same total absolute error. A matrix will be selected at random from the possibilities. This avoids skewed distributions of unit cell parameters, e.g. the angles always being greater than 90 degrees.

This is the right function to use for deciding if an indexing solution matches a reference cell or not.

Returns: A newly allocated UnitCell, or NULL.

◆ forbidden_reflection()

int forbidden_reflection	(	UnitCell *	cell,
		signed int	h,
		signed int	k,
		signed int	l )

extern

Parameters

cell	A UnitCell
h	h index to check
k	k index to check
l	l index to check

Returns: true if this reflection is forbidden.

◆ get_lattice_symmetry()

SymOpList * get_lattice_symmetry ( UnitCell * cell )

extern

Parameters

cell	A UnitCell

Determines the chiral point group of the lattice, based on the lattice type and unique axis of cell (the lattice parameters are not checked).

This point group is often needed within indexing algorithms.

Returns: a newly allocated SymOpList.

◆ load_cell_from_file()

UnitCell * load_cell_from_file ( const char * filename )

extern

Parameters

filename The filename from which to load the cell

Loads a unit cell from a file of any type (PDB or CrystFEL format)

Returns: a newly allocated UnitCell.

◆ load_cell_from_pdb()

UnitCell * load_cell_from_pdb ( const char * filename )

extern

Parameters

filename The filename from which to load the cell

Loads a unit cell from the CRYST1 line of a PDB file.

Returns: a newly allocated UnitCell.

◆ lowest_reflection()

double lowest_reflection ( UnitCell * cell )

extern

Parameters

cell	A UnitCell

Returns: the value of 1/d for the lowest order reflection that is not systematically absent according to the centering.

◆ rotate_cell()

UnitCell * rotate_cell	(	UnitCell *	in,
		double	omega,
		double	phi,
		double	rot )

extern

Parameters

in	A UnitCell to rotate
omega	Euler angle about +z
phi	Euler angle about +x
rot	Euler angle about new +z

Rotate a UnitCell using Euler angles

Returns: a newly allocated rotated copy of in.

◆ uncenter_cell()

UnitCell * uncenter_cell	(	UnitCell *	in,
		IntegerMatrix **	pC,
		RationalMatrix **	pCi )

extern

Parameters

in	A UnitCell
pC	Location at which to store the centering transformation
pCi	Location at which to store the inverse centering transformation

Turns any cell into a primitive one, e.g. for comparison purposes.

The transformation which was used is stored at Ci. The centering transformation, which is the transformation you should apply if you want to get back the original cell, will be stored at C. Either or both of these can be NULL if you don't need that information.

Returns: a primitive version of in.

◆ validate_cell()

int validate_cell ( UnitCell * cell )

extern

Parameters

cell	A UnitCell to validate

Perform some checks for crystallographic validity cell, such as that the lattice is a conventional Bravais lattice. Warnings are printied if any of the checks are failed.

Returns: zero if the cell is fine, 1 if it is unconventional but otherwise OK (e.g. left-handed or not a Bravais lattice), and 2 if there is a serious problem such as the parameters being physically impossible.

◆ write_cell()

void write_cell	(	UnitCell *	cell,
		FILE *	fh )

extern

Parameters

cell	a UnitCell
fh	a file handle

Writes cell to fh, in CrystFEL unit cell file format

Functions

Detailed Description

Function Documentation

◆ cell_get_volume()

◆ cell_rotate()

◆ compare_cell_parameters()

◆ compare_cell_parameters_and_orientation()

◆ compare_derivative_cell_parameters()

◆ compare_permuted_cell_parameters_and_orientation()

◆ compare_reindexed_cell_parameters()

◆ forbidden_reflection()

◆ get_lattice_symmetry()

◆ load_cell_from_file()

◆ load_cell_from_pdb()

◆ lowest_reflection()

◆ rotate_cell()

◆ uncenter_cell()

◆ validate_cell()

◆ write_cell()