PDielec.UnitCell

Hold unit cell information and its associated calculated properties.

Classes

UnitCell

Hold unit cell information and its associated calculated properties.

Functions

convert_length_units(value, units_in, units_out)

"Convert between different length units.

Module Contents

class PDielec.UnitCell.UnitCell(a=None, b=None, c=None, alpha=None, beta=None, gamma=None, units='Angstrom')

Hold unit cell information and its associated calculated properties.

Initialize the class instance with optional lattice parameters and calculate the reciprocal lattice.

Parameters

a, b, cfloat or array, optional

Lattice vectors or cell lengths. If not specified, they default to [1.0, 0.0, 0.0], [0.0, 1.0, 0.0], and [0.0, 0.0, 1.0], respectively.

alpha, beta, gammafloat, optional

Lattice angles (in degrees). These are only used if all three angles are specified, otherwise, the default lattice (orthorhombic) is used.

unitsstr

An optional unit such as ‘a.u., au bohr angs angstrom Angs Angstrom or nm’ The default is Angstrom. The internal unit is always the angstrom

Notes

This constructor initializes an instance with empty lists for fractional coordinates, xyz coordinates, element names, atom labels, bonds, and molecules. It also initializes an empty list for atomic masses and zero for total mass. If the angles alpha, beta, and gamma are provided, it attempts to convert the provided lattice parameters (a, b, c, alpha, beta, gamma) into a 3x3 lattice matrix. If not, it directly assigns a, b, and c as lattice vectors. Finally, it calculates and sets the reciprocal lattice for the instance.

Examples

a = [2.853604, -1.647529, 0.0]
b = [0.0,       3.295058, 0.0]
c = [0.0,       0.0,      5.284824]
cell = UnitCell( a, b, c )
cell.set_element_names(['Zn', 'Zn', 'O', 'O'])
coords = [ [ 0.333333,    0.666667,    0.000900 ]
           [ 0.666667,    0.333333,    0.500900 ]
           [ 0.333333,    0.666667,    0.381600 ]
           [ 0.666667,    0.333333,    0.881600 ] ]
cell.set_fractional_coordinates(coords)
cell.print()

_calculate_reciprocal_lattice()

Calculate the reciprocal lattice.

Parameters

None

Returns

None

Modifies

Sets the reciprocal lattice vectors from the lattice vectors

calculateCentreOfMass(atom_list=None, output='xyz')

Calculate the centre of mass for a given set of atoms.

Parameters

atom_listlist, optional

A list of atom indices for which the centre of mass should be calculated. If None, the centre of mass will be calculated for all atoms in the system. Default is None.

output{‘xyz’, ‘mass’, ‘abc’}, optional

The output requested: - ‘xyz’ returns the centre of mass coordinates in Cartesian (x, y, z) units. - ‘mass’ returns the total mass of the atoms in atom_list. - ‘abc’ returns the centre of mass in fractional (a, b, c) coordinates. If not specified, ‘xyz’ is used as default.

Returns

numpy.ndarray or float or tuple

The centre of mass as requested by output: - If ‘xyz’, returns a numpy array with the x, y, z coordinates of the centre of mass. - If ‘mass’, returns a float representing the total mass of the specified atoms. - If ‘abc’, returns a numpy array with the a, b, c fractional coordinates of the centre of mass. - If the ouput are not recognized, a tuple containing the total mass, Cartesian coordinates, and fractional coordinates of the centre of mass is returned.

See Also

convert_xyz_to_abc : A method to convert Cartesian coordinates to fractional coordinates.

Examples

>>> calculateCentreOfMass(atom_list=[1, 2, 3], output='xyz')
array([0.1, 0.2, 0.3])
>>> calculateCentreOfMass(output='mass')
50.2
>>> calculateCentreOfMass(output='abc')
array([0.4, 0.5, 0.6])

calculate_molecular_contents(scale=1.1, tolerance=0.1, radii=None)

Find whole molecules in the unit cell.

Does this by creating a supercell and exploring adjacent cells to see if there is any bonding to atoms in the adjacent cell A new unit cell is created containing whole molecules, the order of the atoms in the new cell is different. The routine returns the the number of moleculess.

Parameters

scalefloat, optional

The scale factor applied to the covalent radii. Default is 1.1

tolerancefloat, optional. Default is 0.1

The tolerance added to the scaled sum of radii to determine the maximum allowable distance between atoms i and j for them to be considered bonded.

radiia dictionary, optional

A dictionary of covalent radii for the atoms, key is the element name. If not given then the package radii are used from PDielec.Constants

Returns

int : the number of molecules

Modifies

fractional_coordinates bonds

Notes

The formula used to calculate the largest distance apart atoms i and j can be for a bond is: scale * (radi + radj) + tolerance The routine modifies its current instance The ordering of the atoms is maintained

convert_abc_to_unitcell(a, b, c, alpha, beta, gamma)

Convert a, b, c, alpha, beta, gamma to a unit cell.

Parameters

atype

Unit cell a.

btype

Unit cell b.

ctype

Unit cell c.

alphatype

Unit cell alpha in degrees.

betatype

Unit cell beta` in degrees.

gammatype

Unit cell gamma` in degrees.

Returns

latticelist of floats (3,3) list

The lattice parameters

convert_abc_to_xyz(abc)

Convert abc coordinates to xyz coordinates.

Parameters

abclist 3 floats

List of fractional coordinates

Returns

xyz : list of coordinates

convert_hkl_to_xyz(hkl)

Convert hkl miller indices to xyz coordinates.

Parameters

hkllist 3 ints

List of hkls

Returns

xyz : list of xyz coordinates

convert_unitcell_to_abc()

Convert a unit cell to the equivalent a, b, c, alpha, beta, gamma designation.

Parameters

None

Returns

a, b, cfloat

The lengths of the cell edges.

alpha, beta, gammafloat

The angles between the edges in degrees.

convert_xyz_to_abc(xyz)

Convert xyz coordinates to abc lattice coordinates.

Parameters

xyz: list of coordinates

List of coordinates in xyz space

Returns

abclist of 3 floats

List of fractional coordinates

convert_xyz_to_integer_abc(xyz)

Convert xyz coordinates to integer abc indices.

Parameters

xyzlist 3 floats

List of xyz

Returns

abc : list of abc coordinates

find_lcd(numbers)

Find the approximated lowest common denominator.

Return the list as integers divided by the lowest common denominator

Parameters

numbersarray of floats

List of numbers

Returns

results : list of integers

find_symmetry(symprec=1e-05, angle_tolerance=-1.0)

Find the space group symmetry of the unit cell.

Parameters

symprecfloat

Determine the accuracy of the coordinates for symmetry determination

angle_tolerancefloat

Determine the accuracy of the angles for symmetry determination

Returns

a tuple

(international table symbol, number])

fold_cell(symprec=1e-05)

Fold a cell so that any atoms outside a single cell are moved inside.

Any molecule or bonding information is removed. Duplication of atoms is avoided

Parameters

symprecfloat

The symmetry precision

Returns

map_old_to_new : a list of integers map_new_to_old : a list of integers

Modifies

fractional_coordinates atom_labels atom_masses element_names

getBoundingBox(originXYZ=None, originABC=None, units='Angstrom')

Generate the corners and edges of a bounding box.

This method calculates the corners and edges of a bounding box based on predefined coordinates. These coordinates are transformed using a conversion method before being paired into edges.

Parameters

originABCa list of 3 floats

Defines the centre about which the box is centred The basis for the coordinates are abc

originXYZa list of 3 floats

Defines the centre about which the box is centred The basis for the coordinates are xyz

unitsstr

An optional unit of length required for output, default is Angstrom

Returns

tuple of list

A tuple containing two elements: - The first element is a list of corners’ coordinates after conversion (list of np.ndarray). - The second element is a list of tuples, each consisting of a pair of corners representing an edge (list of tuple).

Example

To fetch the bounding box coordinates and edges, simply call:

corners_xyz, edges = object.getBoundingBox()

getDensity(units='cm')

Calculate the density of the crystal.

Returns the density in g/cc. If the mass is not known, then returns 1.0

Parameters

unitsstr

Optional parameter giving the output unit of length, default is cm, so volume will be cm3

Returns

float

The density in gms/cc

getVolume(units='cm')

Calculate the volume.

Parameters

unitsstr

An optional string indicating the required unit of length for the output value, default is cm

Returns

volume : float

get_atom_labels()

Get the atom labels for a molecule.

If the labels have not been set, then a list of labels is created from the element names

Parameters

None

A list containing the labels of atoms.

Returns

A list of atom labels

get_atomic_masses()

Get the atomic masses for the elements.

Parameters

None

Returns

masseslist

The atomic masses

get_atomic_numbers()

Get the atomic numbers for the elements.

Parameters

None

Returns

list of ints

The atomic numbers

get_bond_angles()

Return a list of atoms that form bonded angles for the unit cell.

It also returns a list of the angles in degrees

Parameters

None

Returns

(list of 3 integer tuples, list of bond angles)

list of angles is a list of 3 integers denoting involved in the angle list of angles is a list of floats

get_bonds()

Return a list of bonds for the unit cell.

It also returns a list of the bond lengths in angstrom

Parameters

None

Returns

(list of bonds, list of bondlengths)

list of bonds is a list of pairs of integers denoting a bond list of bond lengths is a list of floats

get_element_names()

Get the names of elements in the cell.

Parameters

None

Returns

element_nameslist

A list of strings representing element names to be cleaned and stored.

get_number_of_atoms()

Get the number of atoms.

Parameters

None

Returns

int

The number of atoms

get_number_of_molecules()

Get the number of molecules.

Parameters

None

Returns

int

The number of molecules

get_species()

Return a list of the unique species in the cell.

The unique list needs to maintain the order seen in the original list

Parameters

None

Returns

A list of strings

get_torsions()

Return a list of atoms that form torsion angles for the unit cell.

It also returns a list of the angles in degrees

Parameters

None

Returns

(list of 4 integer tuples, list of torsion angles)

list of torsions is a list of 4 integers denoting involved in the angle list of angles is a list of floats

guess_primitive_transform(symprec=1e-05)

Guess the primitive cell on the basis of the centering.

This routine is based on a similar routine in phonopy get_primitive_matrix_by_centring

Parameters

symprecfloat (optional)

The symmetry precision used in determining the spacegroup

Returns

A guess at the new unit cell

print()

Print the details of the given unit cell.

This method prints formatted details of the unit cell object, including lattice parameters (a, b, c, alpha, beta, gamma), lattice vectors, element names, fractional coordinates, Cartesian coordinates, and molecular information if any molecules are defined within the unit cell.

Parameters

None

Returns

None

set_atom_labels(atom_labels)

Set the atom labels for a molecule.

Parameters

atom_labelslist of strings

A list containing the labels of atoms.

Returns

None

Notes

This method updates the atom_labels attribute of the molecule with the provided list of atom labels. Each element in the input atom_labels list is appended to the self.atom_labels attribute.

set_atomic_masses(masses)

Set the atomic masses for the elements.

Parameters

masseslist

The atomic masses to be assigned. This can be a list or a dictionary of atomic masses.

Returns

None

set_atomic_numbers(atomic_numbers)

Set the element names according to the atomic numbers for a molecule.

Parameters

atomic_numbers

A list containing the atomic numbers of the atoms

Returns

None

Modifies

element_names

Notes

This method updates the atomic numbers attribute of the molecule

set_bonds(bonds)

Define a list of bonds for the unit cell.

Some checking is performed. If the bonds has duplicates but in a different order, then they are removed.

Parameters

bondsa list of integer tuple

The bonding list for the cell

Returns

None

set_element_names(element_names)

Set the names of elements in the object after cleaning them up.

Parameters

element_nameslist

A list of strings representing element names to be cleaned and stored.

Returns

None

Notes

This function takes a list of element names, cleans each name using the cleanup_symbol function (not defined here), and then updates the object’s element_names attribute with the cleaned names.

set_fractional_coordinates(coords)

Set the fractional coordinates and calculate the xyz coordinates.

Parameters

coordsa list 3 floats

Fractional coordinates

Returns

None

Modifies

fractional_coordinates xyz_coordinates nions

set_lattice(lattice, units='Angstrom')

Set the lattice parameters with a 3x3 matrix.

The lattice is stored as a numpy array The reciprical vectors are calculated.

Parameters

lattice3x3 list

The lattice vectors stored a ( a b c ) where a, b, c are 3 vectors in xyz space.

unitsstr

A string indicating the units used in lattice. Internally the units are Angstrom

Returns

None

set_molecules(molecules)

Define a list of molecules, each molecule is a list of atom coordinates.

Parameters

moleculeslist of 3 floats

A list of molecules

Returns

None

set_xyz_coordinates(coords, units='Angstrom')

Set the xyz coordinates and calculate the fractional coordinates.

Parameters

coordslist of 3 floats

A list of xyz coordinates, the unit of length must agree with the lattice

unitsstr

A unit of length for the input values. The default is Angstrom.

Returns

None

Modifies

xyz_coordinates fractional_coordinates nions

trim_cell()

Trim this cell so that any atoms outside a single cell are removed.

As well as removing the redundant atoms, a list of the mappings from the original cell and to the old cell are generated

This routine is used when generating a primitive (the new) cell, from a standard cell

Parameters

None

Returns

map_old_to_new : a list of integers map_new_to_old : a list of integers

Modifies

fractional_coordinates atom_labels atom_masses element_names

write_cif(filename=None, filedescriptor=sys.stdout, description=None)

Write the crystallographic information file (CIF) representation of a structure.

Parameters

filenamestr, optional

The name of the file to be written. If not provided, the CIF data is printed to stdout.

filedescriptorfiledescriptor, optional

The file descriptor of the file to be written. If not provided, the CIF data is printed to stdout.

descriptionstr, optional

A description of the cif file

Returns

None

Notes

This method prints the CIF representation of a structure, including the space group, cell dimensions, angles, volume, and the fractional coordinates of the atoms. Any lengths are converted to Angstrom, the volumes is give as Angstrom^3 If a filename is provided, the CIF data will be written to that file. Otherwise, it will be printed to standard output. Only one of filename or filedescriptor can be specified

Examples

To print the CIF representation to standard output, simply call the method without arguments:

>>> cell.write_cif()

To write the CIF representation to a file named “example.cif”:

>>> cell.write_cif('example.cif')

atom_labels = []

atomic_masses = []

bonds = []

centres_of_mass = []

element_names = []

fractional_coordinates = []

lattice = [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]]

molecules = []

nions = 0

total_mass = 0.0

units = 'Angstrom'

xyz_coordinates = []

PDielec.UnitCell.convert_length_units(value, units_in, units_out)

“Convert between different length units.

The ‘internal’ unit is taken to be the Angstrom so units are relative to the Angstrom The unit strings are made lowercase, so case should be irrelevant

Parameters

valuefloat or list of floats or a numpy array

The value(s) for which the conversion is to be made.

units_instr

The units of the input value(s). Can be one of ‘

units_outstr

The units of the output value(s). Must be one of ‘a.u. au bohr ang angs angstrom nm um mm cm m’

Returns

scalar or numpy array

The converted value(s) in the output units specified.

Notes

The input can be either a scalar value, a list or a numpy array of values. The function will return the converted value(s) in the output units specified.