PDielec.UnitCell
#
Hold unit cell information and its associated calculated properties.
Module Contents#
Classes#
Hold unit cell information and its associated calculated properties. |
Functions#
|
"Convert between different length units. |
- class PDielec.UnitCell.UnitCell(a=None, b=None, c=None, alpha=None, beta=None, gamma=None, units='Angstrom')[source]#
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.
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(lattice)[source]#
Calculate the reciprocal lattice.
Parameters#
- lattice3x3 list of floats
Lattice as [a, b, c] where a/b/c are [x,y,z]
Returns#
None
Returns#
sets the reciprocal lattice vectors
- calculateCentreOfMass(atom_list=None, output='xyz')[source]#
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)[source]#
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 new unit cell, the number of molecules and the old ordering of the atoms.
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#
new_unit_cell, len(new_molecules), old_order
Notes#
The formula used to calculate the largest distance apart atoms i and j can be for a bond is: scale * (radi + radj) + tolerance
- convert_abc_to_unitcell(a, b, c, alpha, beta, gamma)[source]#
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)[source]#
Convert abc coordinates to xyz coordinates.
Parameters#
- abclist 3 floats
List of fractional coordinates
Returns#
xyz : list of coordinates
- convert_hkl_to_xyz(hkl)[source]#
Convert hkl miller indices to xyz coordinates.
Parameters#
- hkllist 3 ints
List if hkls
Returns#
xyz : list of xyz coordinates
- convert_unitcell_to_abc()[source]#
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)[source]#
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
- find_symmetry(symprec=1e-05, angle_tolerance=-1.0)[source]#
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])
- getBoundingBox(units='Angstrom')[source]#
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#
- 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')[source]#
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')[source]#
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()[source]#
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()[source]#
Get the atomic masses for the elements.
Parameters#
None
Returns#
- masseslist
The atomic masses
- get_atomic_numbers()[source]#
Get the atomic numbers for the elements.
Parameters#
None
Returns#
- list of ints
The atomic numbers
- get_bond_angles()[source]#
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()[source]#
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_torsions()[source]#
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
- print()[source]#
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)[source]#
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)[source]#
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_bonds(bonds)[source]#
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)[source]#
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)[source]#
Set the fractional coordinates and calculate the xyz coordinates.
Parameters#
- coordsa list 3 floats
Fractional coordinates
Returns#
None
- set_molecules(molecules)[source]#
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')[source]#
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
- write_cif(filename=None, filedescriptor=sys.stdout, description=None)[source]#
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')
- PDielec.UnitCell.convert_length_units(value, units_in, units_out)[source]#
“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.