occ::crystal::Crystal Class Reference

A class representing a crystal structure. More...

#include <crystal.h>

Public Member Functions
	Crystal (const AsymmetricUnit &asymmetric_unit, const SpaceGroup &space_group, const UnitCell &unit_cell)
	Constructs a crystal lattice from the given asymmetric unit, space group, and unit cell.
const std::vector< std::string > &	labels () const
	Returns the labels of the atoms in the asymmetric unit of this crystal.
const Mat3N &	frac () const
	Returns the fractional coordinates of the atoms in the asymmetric unit of this crystal.
auto	to_fractional (const Mat3N &p) const
	Converts the given cartesian coordinates to fractional coordinates.
auto	to_cartesian (const Mat3N &p) const
	Converts the given fractional coordinates to cartesian coordinates.
int	num_sites () const
	Returns the number of sites in the crystal lattice.
const std::vector< SymmetryOperation > &	symmetry_operations () const
	Returns the symmetry operations of the crystal lattice.
const SpaceGroup &	space_group () const
	Returns the space group of the crystal lattice.
const AsymmetricUnit &	asymmetric_unit () const
	Returns a constant reference to the asymmetric unit of the crystal lattice.
AsymmetricUnit &	asymmetric_unit ()
	Returns a reference to the asymmetric unit of the crystal lattice.
const UnitCell &	unit_cell () const
	Returns the unit cell of the crystal lattice.
CrystalAtomRegion	slab (const HKL &lower, const HKL &upper) const
	Returns the atoms in the specified slab of the crystal lattice.
const CrystalAtomRegion &	unit_cell_atoms () const
	Returns the atoms in the unit cell of the crystal lattice.
CrystalAtomRegion	atom_surroundings (int asym_idx=0, double radius=6.0) const
	Returns the atoms within a certain radius of the specified atom in the crystal lattice.
std::vector< CrystalAtomRegion >	asymmetric_unit_atom_surroundings (double radius) const
	Returns the atoms within a certain radius of each atom in the asymmetric unit of the crystal lattice.
const PeriodicBondGraph &	unit_cell_connectivity () const
	Returns the connectivity graph of the atoms in the unit cell of the crystal lattice.
const std::vector< Molecule > &	unit_cell_molecules () const
	Returns the molecules in the unit cell of the crystal lattice.
const std::vector< Molecule > &	symmetry_unique_molecules () const
	Returns the symmetry-unique molecules in the unit cell of the crystal lattice.
double	volume () const
	Returns the volume of the unit cell of the crystal lattice.
CrystalDimers	symmetry_unique_dimers (double distance_tolerance) const
	Returns the neighbouring dimers for the symmetry-unique molecules in this crystal, within a certain neighbour radius.
CrystalDimers	unit_cell_dimers (double distance_tolerance) const
	Returns the neighbouring dimers for the unit cell molecules in this crystal, within a certain neighbour radius.
std::string	dimer_symmetry_string (const occ::core::Dimer &dimer) const
	Returns a string representing the symmetry of a dimer in the crystal lattice.
void	set_connectivity_criteria (bool guess=true)
	Specify the behaviour for guessing/finding bonds.
SiteMappingTable	atom_site_mapping_table () const
	Creates a mapping table for atomic sites in the crystal.
SiteMappingTable	molecule_site_mapping_table () const
	Creates a mapping table for molecular sites in the crystal.
bool	gamma_point_unit_cell_molecules () const
	Checks if molecules are enforced to have centroids in the gamma point.
void	set_gamma_point_unit_cell_molecules (bool set)
	Controls enforcement of molecule centroids in the gamma point.

Static Public Member Functions
static Crystal	create_primitive_supercell (const Crystal &c, HKL hkl)
	Creates a primitive supercell from a crystal lattice.
static IVec3	compute_cell_shift (const Vec3 &to, const Vec3 &from, const SymmetryOperation &symop_from)

Detailed Description

A class representing a crystal structure.

A crystal is a periodic arrangement of atoms in 3D space, characterized by its unit cell, space group, and the atoms in its asymmetric unit. This class provides methods to access and manipulate the properties of the crystal lattice, such as its atoms, bonds, molecules, and symmetry operations.

Constructor & Destructor Documentation

Crystal()

occ::crystal::Crystal::Crystal	(	const AsymmetricUnit &	asymmetric_unit,
		const SpaceGroup &	space_group,
		const UnitCell &	unit_cell
	)

Constructs a crystal lattice from the given asymmetric unit, space group, and unit cell.

Parameters

asymmetric_unit	The asymmetric unit of the crystal lattice, containing the atoms and their properties.
space_group	The space group of the crystal lattice, defining its symmetry operations.
unit_cell	The unit cell of the crystal lattice, defining its lengths and angles (cell vectors).

Member Function Documentation

asymmetric_unit() [1/2]

AsymmetricUnit & occ::crystal::Crystal::asymmetric_unit ( )

inline

Returns a reference to the asymmetric unit of the crystal lattice.

The asymmetric unit of the lattice contains the atoms and their properties, such as their positions, labels, and atomic numbers. This method allows modifying the properties of the atoms in the lattice.

Returns

A reference to the AsymmetricUnit object that defines the asymmetric unit of the lattice.

asymmetric_unit() [2/2]

const AsymmetricUnit & occ::crystal::Crystal::asymmetric_unit ( ) const

inline

Returns a constant reference to the asymmetric unit of the crystal lattice.

The asymmetric unit of the lattice contains the atoms and their properties, such as their positions, labels, and atomic numbers.

Returns

A constant reference to the AsymmetricUnit object that defines the asymmetric unit of the lattice.

asymmetric_unit_atom_surroundings()

std::vector< CrystalAtomRegion > occ::crystal::Crystal::asymmetric_unit_atom_surroundings

(

double

radius

)

const

Returns the atoms within a certain radius of each atom in the asymmetric unit of the crystal lattice.

This method can be used to find the neighbors of each atom in the asymmetric unit, or to identify the atoms that are within a certain range of distances from each atom.

Parameters

radius

The maximum distance from each atom that an atom can be in order to be included in the result. This parameter is used for all atoms in the asymmetric unit, and its value must be positive.

Returns

A vector of CrystalAtomRegion objects, where each element of the vector contains the atoms within the specified radius of a different atom in the asymmetric unit. The CrystalAtomRegion class provides methods to access the positions, atomic numbers, and symmetry operations of the atoms in the region.

atom_site_mapping_table()

SiteMappingTable occ::crystal::Crystal::atom_site_mapping_table

(

)

const

Creates a mapping table for atomic sites in the crystal.

Generates a table that maps atomic sites in the crystal to their equivalent positions under symmetry operations. This is useful for analyzing site equivalences and symmetry relationships.

Returns

A SiteMappingTable object containing the atomic site mappings.

atom_surroundings()

CrystalAtomRegion occ::crystal::Crystal::atom_surroundings	(	int	asym_idx = 0,
		double	radius = 6.0
	)		const

Returns the atoms within a certain radius of the specified atom in the crystal lattice.

This method can be used to find the neighbors of an atom, or to identify the atoms that are within a certain range of distances from the specified atom.

Parameters

asym_idx	The index of the atom in the asymmetric unit of the lattice. By default, this parameter is set to 0, indicating the first atom in the asymmetric unit.
radius	The maximum distance (Angstroms) from the specified atom that an atom can be in order to be included in the result. (default = 6.0)

Returns

A CrystalAtomRegion object containing the atoms within the specified radius of the specified atom. The CrystalAtomRegion class provides methods to access the positions, atomic numbers, and symmetry operations of the atoms in the region.

compute_cell_shift()

static IVec3 occ::crystal::Crystal::compute_cell_shift ( const Vec3 &  to, const Vec3 &  from, const SymmetryOperation &  symop_from  )

static

create_primitive_supercell()

static Crystal occ::crystal::Crystal::create_primitive_supercell ( const Crystal &  c, HKL  hkl  )

static

Creates a primitive supercell from a crystal lattice.

Given a crystal lattice, this method constructs a new lattice that is a primitive supercell of the original lattice. The dimensions of the supercell are given in the HKL parameter, and all symmetry beyond translational symmetry is removed in the resulting crystal.

Parameters

c	The crystal lattice from which to create the primitive supercell.
hkl	The lattice vector triplet (h, k, l) that defines the primitive supercell.

Returns

A new Crystal object representing the primitive supercell of the original lattice.

dimer_symmetry_string()

std::string occ::crystal::Crystal::dimer_symmetry_string

(

const occ::core::Dimer &

dimer

)

const

Returns a string representing the symmetry of a dimer in the crystal lattice.

Given a dimer in the lattice, returns a string representation of a the symmetry operation relating them (including translations)

Parameters

dimer

The dimer for which to calculate the symmetry string. The dimer must be a valid dimer in the crystal lattice, for example from the CrystalDimers class.

Returns

A string representing the symmetry of the dimer, composed of rotation and translation components

frac()

const Mat3N & occ::crystal::Crystal::frac ( ) const

inline

Returns the fractional coordinates of the atoms in the asymmetric unit of this crystal.

The fractional coordinates of an atom are its position in the lattice, expressed as a fraction of the unit cell dimensions.

Returns

A matrix of size (3, n), where n is the number of atoms in the lattice. Each column of the matrix represents the (a, b, c) fractional coordinates of an atom in the lattice.

gamma_point_unit_cell_molecules()

bool occ::crystal::Crystal::gamma_point_unit_cell_molecules ( ) const

inline

Checks if molecules are enforced to have centroids in the gamma point.

Returns whether unit cell molecules are currently being enforced to have their geometric centroids in the range [0,1) for each fractional coordinate.

Returns

True if gamma point enforcement is enabled, false otherwise.

labels()

const std::vector< std::string > & occ::crystal::Crystal::labels ( ) const

inline

Returns the labels of the atoms in the asymmetric unit of this crystal.

The labels are assigned to each atom in the asymmetric unit, and they are used to identify the atoms in the lattice.

Returns

A vector of strings containing the labels of the atoms in the lattice, in the same order as their positions.

molecule_site_mapping_table()

SiteMappingTable occ::crystal::Crystal::molecule_site_mapping_table

(

)

const

Creates a mapping table for molecular sites in the crystal.

Generates a table that maps molecular sites in the crystal to their equivalent positions under symmetry operations. This helps identify molecular symmetry relationships and equivalent molecular positions.

Returns

A SiteMappingTable object containing the molecular site mappings.

num_sites()

int occ::crystal::Crystal::num_sites ( ) const

inline

Returns the number of sites in the crystal lattice.

The number of sites in the lattice is equal to the number of atoms in the asymmetric unit

Returns

The number of sites in the lattice.

set_connectivity_criteria()

void occ::crystal::Crystal::set_connectivity_criteria

(

bool

guess = true

)

Specify the behaviour for guessing/finding bonds.

Controls whether bonds should be automatically determined based on atomic positions and covalent radii. When enabled, bonds are guessed using distance criteria. When disabled, no bonds are created.

Parameters

guess

If true, enables automatic bond detection. If false, disables bond detection. Defaults to true.

set_gamma_point_unit_cell_molecules()

void occ::crystal::Crystal::set_gamma_point_unit_cell_molecules ( bool  set )

inline

Controls enforcement of molecule centroids in the gamma point.

Sets whether unit cell molecules should have their geometric centroids enforced to lie within the range [0,1) for each fractional coordinate. When enabled, molecules will be shifted to satisfy this constraint while maintaining their internal structure and connectivity.

Parameters

set	If true, enforces gamma point centering. If false, allows molecules to have centroids outside the [0,1) range.

slab()

CrystalAtomRegion occ::crystal::Crystal::slab	(	const HKL &	lower,
		const HKL &	upper
	)		const

Returns the atoms in the specified slab of the crystal lattice.

A slab is a subset of the lattice that is defined by a pair of Miller indices (hkl), which specify the corners and of the slab (rectangular prism in lattice space).

The atoms in the slab are those whose fractional coordinates lie within inside the range of these corners, generated from the unit cell atoms, translated to all possible unit cells.

Parameters

lower	The Miller indices (hkl) of the first corner of the slab.
upper	The Miller indices (hkl) of the second corner of the slab.

Returns

A CrystalAtomRegion object containing the atoms in the specified slab of the lattice.

space_group()

const SpaceGroup & occ::crystal::Crystal::space_group ( ) const

inline

Returns the space group of the crystal lattice.

The space group of the lattice defines its symmetry operations, which are used to generate the equivalent positions of each atom in the lattice.

Returns

A constant reference to the SpaceGroup object that defines the space group of the lattice.

symmetry_operations()

const std::vector< SymmetryOperation > & occ::crystal::Crystal::symmetry_operations ( ) const

inline

Returns the symmetry operations of the crystal lattice.

The symmetry operations of the lattice are defined by its space group, and they are used to generate the equivalent positions of each atom in the lattice.

Returns

A vector of SymmetryOperation objects, containing the symmetry operations of the lattice, in the same order as they are defined in the space group.

symmetry_unique_dimers()

CrystalDimers occ::crystal::Crystal::symmetry_unique_dimers

(

double

distance_tolerance

)

const

Returns the neighbouring dimers for the symmetry-unique molecules in this crystal, within a certain neighbour radius.

A dimer is a pair of molecules in the crystal.

Parameters

distance_tolerance

The maximum distance between two atoms in order for them to be considered.

Returns

A CrystalDimers object containing the symmetry-unique dimers in the crystal.

symmetry_unique_molecules()

const std::vector< Molecule > & occ::crystal::Crystal::symmetry_unique_molecules

(

)

const

Returns the symmetry-unique molecules in the unit cell of the crystal lattice.

A symmetry-unique molecule is a the subset of unit_cell_molecules that are not related to each other by symmetry (i.e. removing symmetry related duplicates)

Returns

A vector of Molecule objects, where each element of the vector represents a different symmetry-unique molecule in the unit cell of the lattice.

to_cartesian()

auto occ::crystal::Crystal::to_cartesian ( const Mat3N &  p ) const

inline

Converts the given fractional coordinates to cartesian coordinates.

Parameters

p	A matrix of size (3, n), where n is the number of coordinates to convert. Each column of the matrix represents the (x, y, z) fractional coordinates of a point in the lattice.

Returns

A matrix of size (3, n), where n is the number of coordinates to convert. Each column of the matrix represents the (x, y, z) cartesian coordinates of the same points, after converting them from fractional to cartesian coordinates.

to_fractional()

auto occ::crystal::Crystal::to_fractional ( const Mat3N &  p ) const

inline

Converts the given cartesian coordinates to fractional coordinates.

Parameters

p	A matrix of size (3, n), where n is the number of coordinates to convert. Each column of the matrix represents the (x, y, z) cartesian coordinates of a point in the lattice.

Returns

A matrix of size (3, n), where n is the number of coordinates to convert. Each column of the matrix represents the (a, b, c) fractional coordinates of the same points, after converting them from cartesian to fractional coordinates.

unit_cell()

const UnitCell & occ::crystal::Crystal::unit_cell ( ) const

inline

Returns the unit cell of the crystal lattice.

The unit cell of the lattice defines its dimensions and geometry, which are used to generate the equivalent positions of each atom in the lattice.

Returns

A reference to the UnitCell object that defines the unit cell of the lattice.

unit_cell_atoms()

const CrystalAtomRegion & occ::crystal::Crystal::unit_cell_atoms

(

)

const

Returns the atoms in the unit cell of the crystal lattice.

The atoms in the unit cell are those that are equivalent to the atoms in the asymmetric unit, after applying the symmetry operations of the lattice.

Returns

A constant reference to a CrystalAtomRegion object containing the atoms in the unit cell of the lattice. The CrystalAtomRegion class provides methods to access the positions, atomic numbers, and symmetry operations of the atoms in the unit cell.

unit_cell_connectivity()

const PeriodicBondGraph & occ::crystal::Crystal::unit_cell_connectivity

(

)

const

Returns the connectivity graph of the atoms in the unit cell of the crystal lattice.

The connectivity graph of the atoms in the unit cell is a graph data structure that represents the bonds between the atoms in the unit cell. The graph is built by considering the bonds between the atoms in the unit cell and neighbouring cells.

Returns

A reference to a PeriodicBondGraph object representing the connectivity graph of the atoms in the unit cell. The PeriodicBondGraph class provides methods to access and manipulate the graph data, such as adding or removing bonds, or traversing the graph to find connected components or shortest paths.

unit_cell_dimers()

CrystalDimers occ::crystal::Crystal::unit_cell_dimers

(

double

distance_tolerance

)

const

Returns the neighbouring dimers for the unit cell molecules in this crystal, within a certain neighbour radius.

A dimer is a pair of molecules in the crystal.

Parameters

distance_tolerance

The maximum distance between two atoms in order for them to be considered.

Returns

A CrystalDimers object containing the unit cell dimers in the crystal.

unit_cell_molecules()

const std::vector< Molecule > & occ::crystal::Crystal::unit_cell_molecules

(

)

const

Returns the molecules in the unit cell of the crystal lattice.

A molecule is a connected subgraph of the connectivity graph of the atoms in the unit cell. This method returns the molecules that are identified by traversing the graph and partitioning it into connected components.

Returns

A vector of Molecule objects, where each element of the vector represents a different molecule in the unit cell of the lattice.

volume()

double occ::crystal::Crystal::volume

(

)

const

Returns the volume of the unit cell of the crystal lattice.

The volume of the unit cell is calculated from the lattice vectors of the unit cell, using the formula V = |a x b x c|, where a, b and c are the lattice vectors of the unit cell.

Returns

The volume of the unit cell of the lattice, as a double.

---

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

• /home/runner/work/occ/occ/include/occ/crystal/crystal.h