The CrystalTools class contains a collection of static functions that perform common crystallographic operations on a Core::Molecule.

#include <avogadro/core/crystaltools.h>

Classes
struct	PeriodicBond
	A single bond of a periodic structure. More...

Public Types
enum	Option { None = 0x0 , TransformAtoms = 0x1 , RightHanded = 0x2 , PerceivePeriodicBonds = 0x4 }
	The Option enum provides bitwise option flags for the various algorithms. More...
using	Options = int

Static Public Member Functions
static bool	wrapAtomsToUnitCell (Molecule &molecule)
static bool	rotateToStandardOrientation (Molecule &molecule, Options opts=None)
static bool	setVolume (Molecule &molecule, Real newVolume, Options opts=None)
static bool	niggliReduce (Molecule &molecule, Options opts=None)
static bool	isNiggliReduced (const Molecule &mol)
static Array< PeriodicBond >	perceivePeriodicBonds (const Molecule &molecule, double tolerance=0.45)
static bool	buildSupercell (Molecule &molecule, unsigned int a, unsigned int b, unsigned int c, Options opts=None)
static bool	buildSupercell (Molecule &molecule, const Vector3 &rangeMin, const Vector3 &rangeMax, Options opts=None)
static bool	setCellMatrix (Molecule &molecule, const Matrix3 &newCellColMatrix, Options opt=None)
static bool	fractionalCoordinates (const UnitCell &unitCell, const Array< Vector3 > &cart, Array< Vector3 > &frac)
static bool	fractionalCoordinates (const Molecule &molecule, Array< Vector3 > &coords)
static bool	setFractionalCoordinates (Molecule &molecule, const Array< Vector3 > &coords)

Member Enumeration Documentation

◆ Option

enum Option

Enumerator
None	No options specified.
TransformAtoms	Transform atoms along with the unit cell.
RightHanded	Enforce right-handed system
PerceivePeriodicBonds	Bond the replicated cells to each other across periodic boundaries.

Member Function Documentation

◆ wrapAtomsToUnitCell()

bool wrapAtomsToUnitCell ( Molecule & molecule )

static

Adjust the atomic positions in molecule so that the fractional (lattice) coordinates of all atoms are in the range [0, 1].

Returns: True on success, false otherwise.

◆ rotateToStandardOrientation()

bool rotateToStandardOrientation	(	Molecule &	molecule,
		Options	opts = None )

static

This function will rotate the input molecule so that the unit cell's 'a' vector is aligned to the x-axis, and the 'b' axis is in the xy-plane. It does not use trig functions or the cell parameters, since such implementations are fragile and cannot handle negative cell angles. The derivation of this algorithm can be found at http://xtalopt.openmolecules.net/misc/rotateToStdOrientation.pdf.

Parameters

opts	If TransformAtoms is specified, the atoms in molecule are rotated along with the unit cell.

Returns: True on success, false otherwise.

◆ setVolume()

bool setVolume	(	Molecule &	molecule,
		Real	newVolume,
		Options	opts = None )

static

Isotropically scale the volume of the unit cell in molecule to newVolume (in cubic angstrom).

Parameters

opts	If TransformAtoms is specified, the atoms in molecule are adjusted so that their fractional (lattice) coordinates are preserved.

Returns: True on success, false on failure.

◆ niggliReduce()

bool niggliReduce	(	Molecule &	molecule,
		Options	opts = None )

static

Perform a Niggli reduction on molecule's unit cell. This produces a canonical unit cell representation that strives to be as cubic as possible.

Note: Implements the niggli reduction algorithm detailed in: Grosse-Kunstleve RW, Sauter NK, Adams PD. Numerically stable algorithms for the computation of reduced unit cells. Acta Crystallographica Section A Foundations of Crystallography. 2003;60(1):1-6.

Parameters

opts	If TransformAtoms is specified, the atom positions are modified to ensure that the same extended atomic structure from the input is represented by the output.

Returns: True on success, false on failure.

◆ isNiggliReduced()

bool isNiggliReduced ( const Molecule & mol )

static

Return true if the unit cell in molecule is already Niggli-reduced. This method checks the conditions listed in the paper Gruber B.. Acta Cryst. A. 1973;29(4):433-440.

◆ perceivePeriodicBonds()

Array< PeriodicBond > perceivePeriodicBonds	(	const Molecule &	molecule,
		double	tolerance = 0.45 )

static

Work out the full bond topology of a periodic structure, including the bonds that cross a cell boundary and are therefore missing from the molecule itself: once the atoms have been wrapped into the cell their periodic neighbours sit a whole cell away in Cartesian space, so ordinary distance-based perception never sees them.

The molecule's own bonds come first in the returned list, in molecule bond order, followed by any that this pass perceived.

Every bond already in molecule comes back with its order intact and with the lattice offset of whichever image of the second atom lies nearest the first, so a bond stored stretched across the cell is reported as the short bond it really is. Further bonds are perceived only where they cross a cell boundary, using covalent radii plus tolerance. Pairs lying wholly inside the cell are left to the molecule's own connectivity, so this never second-guesses the bonding that a file specified.

If molecule has no unit cell, or has no coordinates, its bonds are returned unchanged with zero offsets.

Parameters

tolerance Added to the sum of the two covalent radii.

◆ buildSupercell() [1/2]

bool buildSupercell	(	Molecule &	molecule,
		unsigned int	a,
		unsigned int	b,
		unsigned int	c,
		Options	opts = None )

static

Build a supercell by expanding upon the unit cell of molecule. It will only return false if the molecule does not have a unit cell or if a, b, or c is set to zero.

Parameters

a	The number of units along lattice vector a for the supercell
b	The number of units along lattice vector b for the supercell
c	The number of units along lattice vector c for the supercell
opts	If PerceivePeriodicBonds is specified, the copies are bonded to each other across the cell boundaries they share.

Returns: True on success, false on failure.

◆ buildSupercell() [2/2]

bool buildSupercell	(	Molecule &	molecule,
		const Vector3 &	rangeMin,
		const Vector3 &	rangeMax,
		Options	opts = None )

static

Build a supercell by replicating the unit cell of molecule over a fractional range along each lattice vector, e.g. -0.5 to 0.5, or 0.0 to 1.5.

If every limit is an integer the result is a true supercell: the range is treated as half-open, the cell vectors are scaled by (max - min), and the atoms are shifted so that rangeMin lands on the new origin. Passing (0, 0, 0) and (a, b, c) is therefore identical to the integer form above.

A non-integer limit cannot describe a lattice, so in that case the unit cell is left untouched and the replicated atoms simply extend beyond it - the usual crystal packing view. The range is then treated as closed, so atoms lying on either bounding face are included.

Parameters

rangeMin	The lower fractional limit along a, b and c.
rangeMax	The upper fractional limit along a, b and c.
opts	If PerceivePeriodicBonds is specified, the copies are bonded to each other across the cell boundaries they share, so that a molecule split by a boundary is drawn whole wherever both of its halves are present.

Returns: True on success, false if molecule has no unit cell or if any axis has an empty range (max <= min).

◆ setCellMatrix()

bool setCellMatrix	(	Molecule &	molecule,
		const Matrix3 &	newCellColMatrix,
		Options	opt = None )

static

Set the unit cell in molecule to represent the real-space column-vector unit cell description in newCellColMatrix. A unit cell is created if needed.

Parameters

opt	If TransformAtoms is specified, the atoms in molecule are adjusted so that their fractional (lattice) coordinates are preserved. This option is ignored if the input molecule has no unit cell.

Returns: True on success, false otherwise.

◆ fractionalCoordinates() [1/2]

bool fractionalCoordinates	(	const UnitCell &	unitCell,
		const Array< Vector3 > &	cart,
		Array< Vector3 > &	frac )

static

Populate the frac vector with the fractional representation of the cartesian coordinates in cart, using unitCell to perform the coordinate transformation.

Returns: True on success, false otherwise.

◆ fractionalCoordinates() [2/2]

bool fractionalCoordinates	(	const Molecule &	molecule,
		Array< Vector3 > &	coords )

static

Populate the coords vector with the fractional coordinates of the atoms in molecule, using the unit cell of molecule to perform the coordinate transformation. Coordinates are ordered the same as the Molecule::atomPositions3d() result.

Returns: True on success, false otherwise.

◆ setFractionalCoordinates()

bool setFractionalCoordinates	(	Molecule &	molecule,
		const Array< Vector3 > &	coords )

static

Set the atomic positions of molecule to the fractional coordinates in coords, using the unit cell of molecule to perform the coordinate transformation.

The documentation for this class was generated from the following file:

crystaltools.h

Classes

Public Types

Static Public Member Functions

Member Enumeration Documentation

◆ Option

Member Function Documentation

◆ wrapAtomsToUnitCell()

◆ rotateToStandardOrientation()

◆ setVolume()

◆ niggliReduce()

◆ isNiggliReduced()

◆ perceivePeriodicBonds()

◆ buildSupercell() [1/2]

◆ buildSupercell() [2/2]

◆ setCellMatrix()

◆ fractionalCoordinates() [1/2]

◆ fractionalCoordinates() [2/2]

◆ setFractionalCoordinates()