\(\newcommand{\AA}{\text{Å}}\)

CRYSTALpytools.geometry module

Class and methods to deal with geometries, including Pymatgen Structrue and Molecule geometries and CRYSTAL gui geometries

class Crystal_gui(dimensionality=None, lattice=None, symmops=None, atom_number=None, atom_positions=None, space_group=None)

Bases: object

This class can read a CRYSTAL gui file into an object or substrate information of the object to generate a gui file.

Parameters:

  • dimensionality (int) – Number of dimensions

  • lattice (array) – 3*3 lattice matrix in Angstrom

  • symmops (array) – n_symmops*4*3 matrices of symmetry operators

  • atom_number (array) – natom*1 int array of atomic numbers

  • atom_positions (array) – natom*3 array of Cartesian coordinates

  • space_group (int) – CRYSTAL space group number

read_pmg(struc, pbc=None, vacuum=500.0, symmetry=True, zconv=None, **kwargs)

Read a pymatgen Structure object into a CRYSTAL_gui object. Vacuum layer is set to 500 Angstrom as the default of CRYSTAL for low symmstry systems.

Parameters:

  • struc (Structure|Molecule) – Pymatgen Structure / Molecule object.

  • pbc (list) – 1*3 boolian list. Implements periodicity along x, y and z directions. If none, the code will read it from input structure.

  • vacuum (float) – Vacuum distance. Unit: Angstrom. Low dimensional systems only.

  • symmetry (bool) – Do symmetry analysis.

  • zconv (list[list[int, int]]) – 1st element: The index of atom; 2nd element: The new conventional atomic number.

  • **kwargs – Passed to Pymatgen SpacegroupAnalyzer object. Valid only if symmetry=True.

read_gui(gui_file)

Read CRYSTAL gui file and genreate a Crystal_gui object.

Parameters:

gui_file (str) – The CRYSTAL structure (gui) file

write_gui(gui_file, symm=True, pseudo_atoms=[])

Write a CRYSTAL gui file (to file)

Parameters:

  • gui_file (str) – The name of the gui that is going to be written ( including .gui).

  • symm (bool) – Whether to include symmetry operations.

  • pseudo_atoms (list[int]) – A list of atoms whose core is described by a pseudopotential (conventional atomic number = atomic number + 200)

class CStructure(lattice, species, coords, symmetry_group=1, pbc=None, standarize=False, **kwargs)

Bases: Structure

Inherited from Pymatgen Structure object with added methods.

Arguments not listed are the same as Pymatgen Structure

Parameters:

  • species (list[int]) – Same as pymatgen or a 1*nAtom list of conventional atomic numbers.

  • symmetry_group (int) – Symmetry group number or symbol in CRYSTAL convention.

  • pbc (list|tuple) – Periodicity.

  • standarize (bool) – Whether to use the CRYSTAL convention of periodic boundaries for low dimensional materials. It calls the standarize_pbc() method.

  • **kwargs – Other arguments passed to pymatgen Structure.

Returns:

self (CStructure) – CStructure object.

classmethod from_pmg(struc)

Get a CStructure object from Pymatgen structure. symmetry_group currently not available.

property ndimen

Dimensionality (1~3) of the system.

property species_symbol

Atom symbols.

property species_Z

Conventional atomic numbers

property crys_coords

Composite fractional / Cartesian atomic coordinates. Consistent with CRYSTAL conventions.

  • 3D: Fractional

  • 2D: Frac, Frac, Cart

  • 1D: Frac, Cart, Cart

  • 0D: Cart, Cart, Cart

standarize_pbc()

Use the CRYSTAL standard periodic boundary for low dimensional materials.

refine_geometry(**kwargs)

Get refined geometry. Useful when reducing the cell to the irrducible one. 3D only.

Parameters:

**kwargs – Passed to Pymatgen SpacegroupAnalyzer object.

Returns:

  • self (CStructure) – New attributes listed below

  • sg (int) – Space group number

  • pstruc (Structure) – Irrducible structure that is consistent with International Crystallographic Table

  • platt (list) – minimal set of crystallographic cell parameters

  • natom_irr (int) – number of irrducible atoms

  • atom (list) – natom*4 array. 1st element: atomic number; 2-4: fractional coordinates

get_sg_symmops(**kwargs)

Get space group number and corresponding symmetry operations. To keep consistency with International Crystallographic Table, refined geometry is suggested.

Parameters:

**kwargs – Passed to Pymatgen SpacegroupAnalyzer object.

Returns:

  • self (CStructure) – New attributes are listed below

  • sg (int) – Space group number

  • n_symmops (int) – number of symmetry operations

  • symmops (array) – n_symmops*4*3 array of symmetry operations

get_pcel(smx)

Restore the supercell to primitive cell, with the origin shifted to the middle of lattice to utilize symmetry (as the default of CRYSTAL).

Parameters:

smx (array) – 3*3 array of supercell expansion matrix. Inverse will be taken automatically.

Returns:

pcel (CStructure) – Pymatgen structure of primitive cell with CRYSTALpytools methods.

get_scel(smx)

Get the supercell from primitive cell, with the origin shifted to the middle of lattice to utilize symmetry (as the default of CRYSTAL).

Parameters:

smx (array) – 3*3 array of supercell expansion matrix

Returns:

scel (CStructure) – Pymatgen structure of supercell

rot_cel(vec1, vec2)

Rotate the geometry according to 2 vectors. A rotation vector is defined.

Parameters:

  • vec1 (array) – A Cartesian vector before rotation

  • vec2 (array) – A Cartesian vector after rotation

Returns:

rcel (CStructure) – Pymatgen structure of rotated cell

miller_norm(miller)

Find the norm vector of a specified Miller plane

Parameters:

miller (array | list) – Miller indices. 3*1 1D array or nmiller*3 3D array

Returns:

vec (array) – Norm vector, normalized to 1. 3*1 1D array or nmiller*3 3D array

write_gui(gui_file=None, pbc=None, vacuum=500.0, symmetry=True, zconv=None, **kwargs)

Read a pymatgen Structure object into a CRYSTAL_gui object. Vacuum layer is set to 500 Angstrom as the default of CRYSTAL for low symmstry systems.

Developing

Parameters:

  • struc (Structure|Molecule) – Pymatgen Structure / Molecule object.

  • pbc (list) – 1*3 boolian list. Implements periodicity along x, y and z directions. If none, the code will read it from input structure.

  • vacuum (float) – Vacuum distance. Unit: Angstrom. Low dimensional systems only.

  • symmetry (bool) – Do symmetry analysis.

  • zconv (list[list[int, int]]) – 1st element: The index of atom; 2nd element: The new conventional atomic number.

  • **kwargs – Passed to Pymatgen SpacegroupAnalyzer object. Valid only if symmetry=True.

get_bonds(scale=1.2, special_bonds={})

Get bond connectivity based on distances between atoms.

Parameters:

  • scale (float) – Scale the sum of atomic radius A and radius B.

  • special_bonds (dict) – Dictionary of bond lengths that are not compliant to scale. Should be defined as {'A:B' : len}, with A B being element symbols and len being bond length in \(\AA\). The sequence of A B is arbitrary.

Returns:

  • self (CStructure) – New attributes listed below.

  • self.bonds (list) – nBond*3 list. The first and second elements are atom indices (starting from 1) of the bond. The third element is a 1*3 integer array lattice vector of the second element. The first atom always has the lattice vector of [0,0,0].

  • self.bond_matrix (bsr_array) – nAtom*nAtom sparse matrix of bond connectivity. In scipy.sparse.bsr_array format.

get_molecules(**kwargs)

Substract molecule from molecular crystals or clusters based on bond connectivity. For ionic or covalent structures where bonds form an integrated network, 1 molecule of all atoms are returned.

Parameters:

**kwargs – See the get_bonds() method.

Returns:

  • self (CStructure) – New attributes listed below.

  • self.molecules (list) – nMolecule*nAtom_per_molecule int list of atom indices (from 1).

visualize(atom_color='cpk', atom_data=[], atom_null=(0.0, 0.0, 0.0), atom_cbar_label='Atom Data', bond_color=(0.5, 0.5, 0.5), bond_data=[], bond_null=(0.0, 0.0, 0.0), bond_cbar_label='Bond Data', atom_bond_ratio='medium', cell_display=True, cell_color=(0.0, 0.0, 0.0), cell_linewidth=0.1, display_matrix=[[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]], display_origin=[0.0, 0.0, 0.0], display_range=[[0.0, 1.0], [0.0, 1.0], [0.0, 1.0]], show_the_scene=True, **kwargs)

Visualize 3D atomic structure with MayaVi (not installed by default).

2 display modes are available:

  1. Normal display. Distinguishing atoms by elements.

  2. Data display. Coloring atoms/bonds/both by the data assigned.

The displayed stucture is manipulated by the following equation:

\[\mathbf{L} = \mathbf{M}\mathbf{L_{0}} + \mathbf{p}\mathbf{M}\mathbf{L_{0}}\]

where \(\mathbf{M}\) is defined by display_matrix, \(\mathbf{p}\) is defined by display_origin. \(\mathbf{L_{0}}\) is the input structure. The object itself will not be changed.

A known issue

Due to settings of MayaVi, bonds plotted in bond data display mode are plotted as lines rather than tubes. That might make bonds look very thick in the default rendering window, which can be addressed by zooming in or expand the rendering window.

Parameters:

  • atom_color (str) – Color map of atoms. ‘jmol’ or ‘cpk’ for normal display (by elements). Or MayaVi colormaps for data display.

  • atom_data (array) – nAtom*2 array. The first column is atom indices (from 1) and the second is data. Atoms without assigned data are plotted in the color specified by atom_null.

  • atom_null (turple) – Useful only for data-display mode. Color of atoms without data assigned.

  • atom_cbar_label (str) – Title of atom data colorbar.

  • bond_color (turple|str) – Color of bonds for normal display or MayaVi colormaps for data display.

  • bond_data (array) – nBond*3 array. The first 2 columns are atom indices (from 1) connecting atom A and B. The 3rd column is data.

  • bond_null (turple) – Useful only for data-display mode. Color of bonds without data assigned.

  • bond_cbar_label (str) – Title of bond data colorbar.

  • atom_bond_ratio (str) – ‘balls’, ‘large’, ‘medium’, ‘small’ or ‘sticks’. The relative sizes of balls and sticks.

  • cell_display (bool) – Display lattice boundaries (at [0., 0., 0.] only).

  • cell_color (turple) – Color of lattice boundaries.

  • cell_linewidth (float) – Linewidth of plotted lattice boundaries.

  • display_matrix (array) – nDimen*nDimen integer matrix to manipulate the structure. Matrices with determinant \(\geq\) 1 are meaningful, otherwise error will be displayed.

  • display_origin (array) – 1*3 array of structure origin in fractional coordinates of the expanded supercell.

  • display_range (array) – 3*2 array defining the displayed region. Fractional coordinates a, b, c are used but only the periodic directions are applied. Defined according to the expanded and translated supercell.

  • show_the_scene (bool) – Display the scene by mlab.show() and return None. Otherwise return the scene object.

  • **kwargs – Other keywords passed to MayaVi or self.get_bonds(). See below.

  • scale (float) – Scale the sum of atomic radius A and radius B.

  • special_bonds (dict) – Dictionary of bond lengths that are not compliant to scale. Should be defined as {'A:B' : len}, with A B being element symbols and len being bond length in \(\AA\). The sequence of A B is arbitrary.

  • azimuth – See mlab.view().

  • elevation –

    See mlab.view().

  • distance –

    See mlab.view(). By default set to ‘auto’.

  • focalpoint –

    See mlab.view().

  • roll –

    See mlab.view().

Returns:

None

_abc_impl = <_abc._abc_data object>
class CMolecule(coords, symmetry_group=1, **kwargs)

Bases: Molecule

Deprecated, use CStructure

_abc_impl = <_abc._abc_data object>