The Spacegroups class stores basic data about crystal spacegroups. More...

#include <avogadro/core/spacegroups.h>

Static Public Member Functions
static unsigned short	hallNumber (const std::string &spaceGroup)
static unsigned short	hallNumberFromHallSymbol (const std::string &hallSymbol)
static std::string	normalizeHallSymbol (const std::string &hallSymbol)
static unsigned short	hallNumberFromTransforms (const std::vector< std::string > &operations)
static unsigned short	internationalNumberFromString (const std::string &spaceGroup)
static bool	setSpaceGroup (Molecule &molecule, const std::string &spaceGroup)
static const char *	internationalNumberKey ()
static CrystalSystem	crystalSystem (unsigned short hallNumber)
static bool	cellLooksPrimitive (unsigned short hallNumber, const UnitCell &cell)
static unsigned short	internationalNumber (unsigned short hallNumber)
static const char *	schoenflies (unsigned short hallNumber)
static const char *	hallSymbol (unsigned short hallNumber)
static const char *	international (unsigned short hallNumber)
static const char *	internationalFull (unsigned short hallNumber)
static const char *	internationalShort (unsigned short hallNumber)
static const char *	setting (unsigned short hallNumber)
static unsigned short	transformsCount (unsigned short hallNumber)
static Array< Vector3 >	getTransforms (unsigned short hallNumber, const Vector3 &v)
static void	fillUnitCell (Molecule &mol, unsigned short hallNumber, double cartTol=1e-5, bool wrapToCell=true, bool allCopies=false)
static bool	fillUnitCellFromOperations (Molecule &mol, const std::vector< std::string > &operations, double cartTol=1e-5, bool wrapToCell=true, bool allCopies=false)
static void	fillTranslationalCopies (Molecule &mol, double cartTol=1e-5)
static void	reduceToAsymmetricUnit (Molecule &mol, unsigned short hallNumber, double cartTol=1e-5)
static Array< Index >	translationalUniqueAtoms (const Molecule &mol, double tolerance=0.001)

Static Public Attributes
static constexpr unsigned short	lastHallNumber = 530

Detailed Description

The spacegroups class gives a simple interface to basic data about crystal spacegroups. The data is generated from information in spglib.

Member Function Documentation

◆ hallNumber()

unsigned short hallNumber ( const std::string & spaceGroup )

static

Returns: The hall number of the matching space group string or 0 if not found

Besides the strings in the table (Hall symbol, international symbols), this accepts the spellings other programs write: screw axes without the underscore ("P 63 m c", "P 1 21/c 1"), a trailing setting that selects an origin choice or the hexagonal / rhombohedral axes ("F d -3 m :2", "R -3 m :H"), the pre-1983 cubic notation ("I m 3 m") and a bare international table number ("229").

A symbol or number that fits several settings (origin choice, axes) is not guessed: 0 is returned. See internationalNumberFromString().

◆ hallNumberFromHallSymbol()

unsigned short hallNumberFromHallSymbol ( const std::string & hallSymbol )

static

Returns: the hall number whose Hall symbol is exactly hallSymbol, or 0 if there is none.

Unlike hallNumber(), the international symbols and numbers are not accepted: a string that is not a Hall symbol of the table gives 0. Runs of white space are collapsed and a double quote is read as '=', as in the table, so "-P 2yn" and "P 3 2\"" (the table's "P 3 2=") match.

◆ normalizeHallSymbol()

std::string normalizeHallSymbol ( const std::string & hallSymbol )

static

Returns: hallSymbol in the spelling of the table: runs of white space (spaces, tabs and line endings) collapsed to one space, the ends trimmed, and '=' where a file has a double quote. The result is not checked against the table.

◆ hallNumberFromTransforms()

unsigned short hallNumberFromTransforms ( const std::vector< std::string > & operations )

static

Returns: the hall number of the space group whose symmetry operations are exactly operations, or 0 if no entry of the table has this set.

This is how most crystallography programs resolve a setting: the symmetry operations a CIF file lists identify the origin choice and axes (which an H-M symbol often leaves out), and cannot disagree with the coordinates.

Each operation is written like "x,y,z", "-x+1/2,y,-z", "1/2+x,y,z" or "x-y,x,z+1/6". Letters may be upper case, spaces and quotes are ignored, and constants may be decimals (0.5, 0.3333, 0.6667) if they are close to a multiple of 1/12. Translations are taken modulo one. The order of the operations and repeats do not matter. All operations must be present and none may be extra. Text that is not an operation, or an empty list, gives 0.

Three pairs of entries in the table (hall numbers 322 and 324, 326 and 328, 330 and 332, all group 68) have the same operations and the same Hall symbol, and differ only in a setting label. The lower number is returned.

◆ internationalNumberFromString()

unsigned short internationalNumberFromString ( const std::string & spaceGroup )

static

Returns: the international table number (1-230) that the string refers to, even if hallNumber() cannot pick one setting for it (e.g. "74"), or 0 if the string is not recognized.

◆ setSpaceGroup()

bool setSpaceGroup	(	Molecule &	molecule,
		const std::string &	spaceGroup )

static

Record the space group that a file gives as a string (a symbol, with or without a setting, or a bare international table number) in molecule.

If the string identifies one setting, the Hall number of the molecule is set (see hallNumber()). If it only identifies the group, because several settings fit (origin choice, axes), the international table number is kept in the data map under internationalNumberKey(), so that the user can be asked for just those settings. A Hall number set later removes it.

The string is resolved once. A space group that is not recognized leaves the molecule unchanged.

Returns: true if the Hall number or the international number was set.

◆ internationalNumberKey()

const char * internationalNumberKey ( )

static

Returns: the key of the Molecule data map entry (an int) in which file readers keep the international table number of a space group whose Hall number is ambiguous. Molecule::setHallNumber() removes it once a Hall number is known. It is never written to files: the file writers and the molecular properties table skip it.

◆ crystalSystem()

CrystalSystem crystalSystem ( unsigned short hallNumber )

static

Returns: an enum representing the crystal system for a given hall number. If an invalid hall number is given, None will be returned.

◆ cellLooksPrimitive()

bool cellLooksPrimitive	(	unsigned short	hallNumber,
		const UnitCell &	cell )

static

Returns: true if cell looks like a primitive cell although the space group (hallNumber) has a centred lattice (F, I, A, B or C), i.e. the cell is probably not the conventional cell the group's operations expect.

The test is on the cell angles, with a tolerance of 5 degrees from 90. It depends on the crystal system, because conventional cells of some systems legitimately have angles other than 90:

monoclinic: suspicious only if more than one angle deviates (one non-90 angle is the normal conventional setting, e.g. C2/c);
orthorhombic, tetragonal, cubic: suspicious if any angle deviates;
all other systems (and primitive lattices, R lattices, or an invalid hall number) are never judged: false is returned.

◆ internationalNumber()

unsigned short internationalNumber ( unsigned short hallNumber )

static

Returns: the international number for a given hall number. If an invalid hall number is given, 0 will be returned.

◆ schoenflies()

const char * schoenflies ( unsigned short hallNumber )

static

Returns: the Schoenflies symbol for a given hall number. If an invalid hall number is given, an empty string will be returned.

◆ hallSymbol()

const char * hallSymbol ( unsigned short hallNumber )

static

Returns: the Hall symbol for a given hall number. '=' is used instead of '"'. If an invalid hall number is given, an empty string will be returned.

◆ international()

const char * international ( unsigned short hallNumber )

static

Returns: the international symbol for a given hall number. If an invalid hall number is given, an empty string will be returned.

◆ internationalFull()

const char * internationalFull ( unsigned short hallNumber )

static

Returns: the full international symbol for a given hall number. If an invalid hall number is given, an empty string will be returned.

◆ internationalShort()

const char * internationalShort ( unsigned short hallNumber )

static

Returns: the short international symbol for a given hall number. If an invalid hall number is given, an empty string will be returned.

◆ setting()

const char * setting ( unsigned short hallNumber )

static

Returns: the setting for a given hall number. If an invalid hall number is given, an empty string will be returned. An empty string may also be returned if there are no settings for this space group.

◆ transformsCount()

unsigned short transformsCount ( unsigned short hallNumber )

static

Returns: the number of transforms for a given hall number. If an invalid hall number is given, 0 will be returned.

◆ getTransforms()

Array< Vector3 > getTransforms	(	unsigned short	hallNumber,
		const Vector3 &	v )

static

Returns: an array of transforms for a given hall number and a vector v. The vector should be in fractional coordinates. If an invalid hall number is given, an empty array will be returned.

◆ fillUnitCell()

void fillUnitCell	(	Molecule &	mol,
		unsigned short	hallNumber,
		double	cartTol = 1e-5,
		bool	wrapToCell = true,
		bool	allCopies = false )

static

Fill a crystal with atoms by using transforms from a hall number. Nothing will be done if the molecule does not have a unit cell. The cartesian tolerance is used to check if an atom is already present at that location. If there is another atom within that distance, the new atom will not be placed there.

◆ fillUnitCellFromOperations()

bool fillUnitCellFromOperations	(	Molecule &	mol,
		const std::vector< std::string > &	operations,
		double	cartTol = 1e-5,
		bool	wrapToCell = true,
		bool	allCopies = false )

static

Fill a crystal with atoms by applying a list of symmetry operations written like "x,y,z" or "-x+1/2,y+1/2,-z" (the grammar of hallNumberFromTransforms()), as given by a file, instead of the ones of a table entry. The operations are applied as listed; the set is not closed to a group, and need not be one. Identity operations and any atom that would land within cartTol of an existing atom are skipped, so applying the operations to a structure that is already expanded adds nothing.

Returns: false, and leave mol unchanged, if the molecule has no unit cell or any operation cannot be parsed. An empty list is accepted and adds nothing.

◆ fillTranslationalCopies()

void fillTranslationalCopies	(	Molecule &	mol,
		double	cartTol = 1e-5 )

static

Add translational copies of atoms on the unit cell boundary. For atoms at fractional coordinate ~0, a copy is placed at ~1 and vice versa, plus edge and corner combinations. No symmetry operations are applied.

◆ reduceToAsymmetricUnit()

void reduceToAsymmetricUnit	(	Molecule &	mol,
		unsigned short	hallNumber,
		double	cartTol = 1e-5 )

static

Reduce a cell to its asymmetric unit. Nothing will be done if the molecule does not have a unit cell. The cartesian tolerance is used to check if an atom is present at a location within the tolerance distance. If an atom is present, the atom gets removed.

◆ translationalUniqueAtoms()

Array< Index > translationalUniqueAtoms	(	const Molecule &	mol,
		double	tolerance = 0.001 )

static

Get indices of translationally unique atoms, filtering out duplicates. Atoms with fractional coordinates near 1.0 that duplicate atoms near 0.0 (due to periodic boundary conditions) are excluded.

Parameters

mol	The molecule with a unit cell
tolerance	Fractional coordinate tolerance for duplicate detection

Returns: Array of atom indices to include (empty if no unit cell)

Member Data Documentation

◆ lastHallNumber

unsigned short lastHallNumber = 530

staticconstexpr

The highest Hall number. The Hall numbers run from 1 to this value; 0 means "no space group" throughout this class.

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

spacegroups.h

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Function Documentation

◆ hallNumber()

◆ hallNumberFromHallSymbol()

◆ normalizeHallSymbol()

◆ hallNumberFromTransforms()

◆ internationalNumberFromString()

◆ setSpaceGroup()

◆ internationalNumberKey()

◆ crystalSystem()

◆ cellLooksPrimitive()

◆ internationalNumber()

◆ schoenflies()

◆ hallSymbol()

◆ international()

◆ internationalFull()

◆ internationalShort()

◆ setting()

◆ transformsCount()

◆ getTransforms()

◆ fillUnitCell()

◆ fillUnitCellFromOperations()

◆ fillTranslationalCopies()

◆ reduceToAsymmetricUnit()

◆ translationalUniqueAtoms()

Member Data Documentation

◆ lastHallNumber