libcrystfel  0.10.1
Functions
cell-utils.h File Reference

Functions

double resolution (UnitCell *cell, signed int h, signed int k, signed int l)
 
UnitCellcell_rotate (UnitCell *in, struct quaternion quat)
 
UnitCellrotate_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)
 
UnitCellload_cell_from_pdb (const char *filename)
 
UnitCellload_cell_from_file (const char *filename)
 
void write_cell (UnitCell *cell, FILE *fh)
 
int cell_is_sensible (UnitCell *cell)
 
int validate_cell (UnitCell *cell)
 
UnitCelluncenter_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)
 
UnitCellcompare_reindexed_cell_parameters (UnitCell *cell_in, UnitCell *reference_in, const double *tols, RationalMatrix **pmb)
 

Detailed Description

Unit cell utility functions.

Function Documentation

◆ cell_get_volume()

double cell_get_volume ( UnitCell cell)
Returns
cell volume in m^3

◆ cell_rotate()

UnitCell* cell_rotate ( UnitCell in,
struct quaternion  quat 
)
Parameters
inA UnitCell to rotate
quatA 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 
)
Parameters
cellA UnitCell
referenceAnother UnitCell
tolsPointer 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 
)
Parameters
cellA UnitCell
referenceAnother UnitCell
tolsPointer 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 
)
Parameters
cell_inA UnitCell
reference_inAnother UnitCell
tolsPointer to tolerances for a,b,c (fractional), al,be,ga (radians)
cslNon-zero to look for coincidence site lattice relationships
pmbPlace 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 
)
Parameters
cellA UnitCell
referenceAnother UnitCell
tolsPointer to six tolerance values (see below)
pmbPlace 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 
)
Parameters
cell_inA UnitCell
reference_inAnother UnitCell
tolsPointer to tolerances for a,b,c (fractional), al,be,ga (radians)
pmbPlace 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 total absolute error in unit cell axis lengths.

There will usually be several transformation matrices which produce exactly the same total absolute error. If one of the matrices is an identity, that one will be used. Otherwise, the 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 
)
Parameters
cellA UnitCell
hh index to check
kk index to check
ll index to check
Returns
true if this reflection is forbidden.

◆ load_cell_from_file()

UnitCell* load_cell_from_file ( const char *  filename)
Parameters
filenameThe 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)
Parameters
filenameThe 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)
Parameters
cellA 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 
)
Parameters
inA UnitCell to rotate
omegaEuler angle about +z
phiEuler angle about +x
rotEuler 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 
)
Parameters
inA UnitCell
pCLocation at which to store the centering transformation
pCiLocation 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)
Parameters
cellA 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 
)
Parameters
cella UnitCell
fha file handle

Writes cell to fh, in CrystFEL unit cell file format