$\newcommand{\AA}{\text{Å}}$

CRYSTALpytools package

Subpackages

Submodules

CRYSTALpytools.adsorb module

Created on Fri Nov 19 18:29:54 2021

sub_ads_indices(structure)

Identify the indices of substrate and adsorbate atoms in the given structure.

Parameters:: structure (pymatgen.core.structure.Structure) – The input structure.
Returns:: dict – A dictionary containing the indices of adsorbate and substrate atoms. The dictionary has two keys: - ‘adsorbate’: A list of indices corresponding to the adsorbate atoms. - ‘substrate’: A list of indices corresponding to the substrate atoms.

CRYSTALpytools.calculate module

Created on Fri Nov 19 18:29:35 2021

@author: brunocamino

cry_ads_energy(e_full_system, e_substrate, e_adsorbate)

Calculate the adsorption energy of a system.

Parameters:

e_full_system (float) – Total energy of the full system.
e_substrate (float) – Energy of the substrate.
e_adsorbate (float) – Energy of the adsorbate.

Returns:

float – Adsorption energy calculated as the difference between the total energy of the full system and the sum of the energies of the substrate and adsorbate.

cry_shrink(structure, spacing=0.2)

Determine the number of unit cells needed to achieve a desired spacing.

Parameters:

structure (pymatgen.core.structure.Structure) – The input structure.
spacing (float) – The desired spacing between unit cells. Default is 0.2.

Returns:

int – The number of unit cells (rounded up) needed to achieve the desired spacing.

CRYSTALpytools.convert module

Functions that do conversion between data / file formats

cry_ase2gui(structure, gui_file=None, vacuum=None, symmetry=True)

Transform an ASE Structure object into a Pymatgen structure object and then a CRYSTAL structure (gui) object. Vacuum layer is set to 500 Angstrom as the default of CRYSTAL for low symmstry systems

Parameters:

structure (ASE Structure) – ASE Structure object.
gui_file (str) – CRYSTAL gui / fort.34 file.
vacuum (float) – Vacuum distance. Unit: Angstrom. If none, set the length of non-periodic direction to 500 Angstrom. Low dimensional systems only.
symmetry (bool) – Perform symmetry analysis.

cry_bands2pmg(band, output, labels=None)

Transform a CRYSTAL bands object/file into a Pymatgen BandStructureSymmLine object (inherited from BandStructure). No projection is available for now. Output is mandatory here.

Parameters:

band (str|ElectronBand) – CRYSTAL fort.25 or BAND.DAT file or CRYSTALpytools ElectronBand object
output (str) – CRYSTAL properties output file
labels (list[str]) – K point labels to display in the band structure.

Returns:

BandStructureSymmLine – Pymatgen band structure object.

cry_gui2ase(gui, vacuum=None, **kwargs)

Transform a CRYSTAL structure (gui) file into an ASE atoms object.

Parameters:

gui (str|geometry.Crystal_gui) – CRYSTAL gui / fort.34 file or CRYSTALpytools gui object
vacuum (float) – Vacuum distance. Unit: Angstrom. If none, set the pbc attribute of ASE atoms object. Low dimensional systems only.
**kwargs – Passed to ASE Atoms constructor

Returns:

Atoms – ASE atoms object.

cry_gui2cif(gui, cif_file_name, vacuum=None, **kwargs)

Read a CRYSTAL structure (gui) file and save a cif file. The CifWriter object of Pymatgen is called. By default, symprec = 0.01 is used.

Parameters:

gui (str|geometry.Crystal_gui) – CRYSTAL gui / fort.34 file or CRYSTALpytools gui object
cif_file_name (str) – Name (including path) of the cif file to be saved
vacuum (float) – Vacuum distance. Unit: Angstrom. If none, set the pbc attribute of Pymatgen atoms object. Low dimensional systems only.
**kwargs – Passed to Pymatgen CifWriter.

cry_gui2pmg(gui, vacuum=None, molecule=True)

Transform a CRYSTAL structure (gui) object into a Pymatgen Structure object.

Parameters:

gui (str|geometry.Crystal_gui) – CRYSTAL gui / fort.34 file or CRYSTALpytools gui object
vacuum (float) – Vacuum distance. Unit: $\AA$. If none, set the pbc attribute of Pymatgen object. Low dimensional systems only.
molecule (bool) – Generate a Molecule Pymatgen object for 0D structures.

Returns:

Structure or Molecule – Pymatgen Structure or Molecule object.

cry_gui2xyz(gui, xyz_file_name, **kwargs)

Transform a CRYSTAL structure (gui) file into an XYZ file.

Parameters:

xyz_file_name (str) – Name of the XYZ file to be saved.
gui (str) – CRYSTAL gui / fort.34 file.
**kwargs – Passed to Pymatgen XYZ object.

cry_out2ase(output, vacuum=None, initial=False, **kwargs)

Transform a CRYSTAL output object into an ASE atoms object.

Parameters:

output (str|Crystal_output) – Crystal output file or Crystal_output object
vacuum (float) – Vacuum distance. Unit: Angstrom. If none, set the pbc attribute of ASE atoms object. Low dimensional systems only.
initial (bool) – Read the last geometry of the output file.
**kwargs – Passed to ASE Atoms constructor

Returns:

Atoms – ASE atoms object.

cry_out2cif(output, cif_file_name, vacuum=None, initial=False, **kwargs)

Read geometry from a CRYSTAL output file and save it as a CIF file. The CifWriter object of Pymatgen is called. By default, symprec = 0.01 is used.

Parameters:

output (str|Crystal_output) – Crystal output file or Crystal_output object
cif_file_name (str) – Name (including path) of the CIF file to be saved.
vacuum (float) – Vacuum distance. Unit: $\AA$. If none, set the pbc attribute of Pymatgen atoms object. Low dimensional systems only.
initial (bool) – Read the last geometry of the output file.
**kwargs – Passed to Pymatgen CifWriter.

cry_out2pmg(output, vacuum=None, initial=False, molecule=True)

Read geometry from a CRYSTAL output file and save it as a pymatgen structure object.

Parameters:

output (str|Crystal_output) – Crystal output file or Crystal_output object
vacuum (float) – Vacuum distance. Unit: Angstrom. If none, set the pbc attribute of Pymatgen object. Low dimensional systems only.
initial (bool) – Read the last geometry of the output file.
molecule (bool) – Generate a Molecule Pymatgen object for 0D structures.

Returns:

Structure – Pymatgen Structure object.

cry_out2xyz(output, xyz_file_name, initial=False, **kwargs)

Read geometry from a CRYSTAL output file and save it as an XYZ file.

Parameters:

output (str|Crystal_output) – Crystal output file or Crystal_output object
xyz_file_name (str) – Name (including path) of the XYZ file to be saved.
initial (bool) – Read the last geometry of the output file.
**kwargs – Passed to Pymatgen XYZ object.

cry_pmg2gui(structure, gui_file=None, pbc=None, vacuum=None, symmetry=True, zconv=None, **kwargs)

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

Parameters:

structure (Structure | Molecule) – Pymatgen Structure / Molecule object.
gui_file (str) – CRYSTAL gui / fort.34 file.
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: $\AA$. If none, set the length of non-periodic direction to 500 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.

CRYSTALpytools.crystal_io module

Objects of input / output files of CRYSTAL. Methods to edit or substract data from corresponding files are provided.

class Crystal_input(source='')

Bases: Crystal_inputBASE

Crystal input object inherited from the Crystal_inputBASE object. For the basic set-ups of keywords, please refer to manuals there.

Parameters:: source (str) – Template file or string. An empty object is generated for ''.

classmethod read_file(source)

Instantiate class object from file.

Parameters:: source (str) – The name of the input file.
Returns:: cls (Crystal_input)

write_file(file): Write data to a file

geom_from_cif(file, zconv=None, keyword='EXTERNAL', pbc=[True, True, True], gui_name='fort.34', **kwargs)

Read geometry from cif file and put infomation to geom block, either as ‘EXTERNAL’ or ‘CRYSTAL’. CIF files with a single geometry only.

CIF with Symmetry is required.

Note

CIF files should have the ‘.cif’ extension.

Parameters:

file (str) – CIF file.
keyword (str) – ‘EXTERNAL’ or ‘CRYSTAL’.
zconv (list[list[int, int]]) – 1st element: The index of atom; 2nd element: The new conventional atomic number. Atoms of the irreducible unit is required.
pbc (list[bool]) – Valid only if keyword = EXTERNAL. Force to remove periodic boundary conditions along x, y, z axis.
gui_name (str) – Valid only if keyword = EXTERNAL. Gui file’s name.
**kwargs – Passed to Pymatgen SpacegroupAnalyzer object.

geom_from_pmg(struc, zconv=None, keyword='EXTERNAL', gui_name='fort.34', **kwargs)

Read geometry defined by PyMatGen structure object and put infomation into geom block, either as ‘EXTERNAL’ or ‘CRYSTAL’.

See geom_from_cif for definition of arguments.

Note

Coordinates of corresponding atoms may not consistent with the original CIF file if ‘CRYSTAL’ is used, in which case coordinates of another symmetry equivalent atom is used.

bs_user(bs_str, z=[], fmt='crystal', append=False, charge=None, ECP=None, BSfile=None, title='MYBASIS')

A shortcut to get user defined (free format) basis sets from Basis Set Exchange (BSE), formatted string or file.

In some rare cases the user might want to manually change the charge assigned to the atoms to get ionic initial guess.

Parameters:

bs_str (str) – Name of basis set(BSE), formatted string or file.
z (list[int]) – List of elements, specified by conventional atomic numbers. BSE only.
fmt (str) – Format string. Consistent with BSE python API. For string and files.
append (bool) – Whether to cover old entries. If the old entry contains ‘BASISSET’, it will be removed anyway. Useful when different series of basis sets are defined
charge (dict) – To define charge. Keys: z, conventional atomic number; Values: charge of shells, whose sequence must be consistent with BS definition.
ECP (dict) – Definition of effective core pseudopotentials. Keys: z, conventional atomic number; Values: ECP string.
BSfile (str) – If not None, print basis set definitions into BSfile and use title as the entry to ‘BASISSET’ keyword
title (str) – Useful when BSfile is not None.

bs_keyword(keyword)

A shortcut to define basis sets by keywords. Equivalent to self.basisset.basisset

Parameters:: keyword (str) – Name of basis set

class Crystal_output(output_name=None)

Bases: object

This class reads a CRYSTAL output and generates an object.

Parameters:: output_name (str) – Filename

classmethod read_file(output_name)

Reads a CRYSTAL output file.

Parameters:: output_name (str) – Name of the output file.
Returns:: cls (Crystal_output)

get_dielectric_tensor()

Extracts the dielectric tensor from the output.

Returns:: list – Dielectric tensor values.

get_eigenvectors(): Extracts eigenvectors from the output.

get_dimensionality()

Gets the dimensionality of the system.

Returns:: self.dimensionality (int) – Dimensionality of the system.

get_symmops(initial=True)

Return the symmetry operators

Parameters:: initial (bool) – Optimization Only Read symmetry operators of the initial or the final geometry.
Returns:: self.symmops (numpy.ndarray) – Symmetry operators

get_geometry(initial=True, write_gui=False, gui_name=None, symmetry='pymatgen', **kwargs)

Get the geometry.

Parameters:

initial (bool) – Read the initial or last gemetry. Useful in case of geometry optimization.
write_gui (bool) – If True, write .gui file
gui_name (str) – Valid only if write_gui = True. Gui file is named as ‘gui_name’. If None, use ‘basename.gui’. The basename is the same as output file.
symmetry (str) – Valid only if write_gui = True. ‘pymatgen’ to use symmetry info from a pymatgen SpacegroupAnalyzer; ‘initial’ to use symmstry information on output file. If None, no symmstry. Otherwise it is taken from the existing gui file.
**kwargs – Valid only if write_gui = True and symmetry = 'pymatgen'. Passed to Pymatgen SpacegroupAnalyzer object.

Returns:

self.geometry (CStructure | CMolecule) – A modified pymatgen Structure or molecule object.

get_lattice(initial=True)

Returns the lattice of the system. Unit: Angstrom.

Parameters:: initial (bool) – Read the initial or last lattice. Useful in case of geometry optimization.
Returns:: self.lattice (np.ndarray) – Lattice of the system.

get_reciprocal_lattice(initial=True)

Returns the reciprocal lattice of the system. Unit: Angstrom^-1. Reciprocal lattice is consistent with CRYSTAL: 2pi is added.

Parameters:: initial (bool) – Read the initial or last lattice. Useful in case of geometry optimization.
Returns:: self.reciprocal_lattice (np.ndarray) – Lattice of the system.

property sg_number: CRYSTAL 0~3D space group number. Before geometry editing.

property sg_symbol: CRYSTAL 0~3D 0~3D space group symbol. Before geometry editing.

get_trans_matrix()

Get cell transformation matrix

Returns:: self.trans_matrix (np.ndarray) – 3*3 array of supercell expansion matrix

get_primitive_geometry(initial=True, write_gui=False, gui_name=None, symmetry='pymatgen', **kwargs)

Get the primitive geometry, reduced by cell transformation matrix inversed.

Note

This is not the standard ‘primitive cell’. This method returns geometry before supercell expansion keywords such as ‘SUPERCEL’ or ‘SCELPHONO’.

Conventional atomic numbers are not available.

Parameters:

initial (bool) – Read the initial or last geometry. Useful in case of geometry optimization.
write_gui (bool) – If True, write .gui file
gui_name (str) – Valid only if write_gui = True. Gui file is named as ‘gui_name’. If None, use ‘basename.gui’. The basename is the same as output file.
symmetry (str) – Valid only if write_gui = True. ‘pymatgen’ to use symmetry info from a pymatgen SpacegroupAnalyzer; ‘initial’ to use symmstry information on output file. If None, no symmstry. Otherwise it is taken from the existing gui file.
**kwargs – Valid only if write_gui = True and symmetry = 'pymatgen'. Passed to Pymatgen SpacegroupAnalyzer object.

Returns:

self.primitive_geometry (CStructure | CMolecule) – A modified pymatgen Structure or molecule object.

get_primitive_lattice(initial=True)

Returns the primitive lattice of the system reduced by cell transformation matrix inverse. Unit: Angstrom.

Parameters:: initial (bool) – Read the initial or last lattice. Useful in case of geometry optimization.
Returns:: self.primitive_lattice (np.ndarray) – Lattice of the system.

get_primitive_reciprocal_lattice(initial=False)

Returns the primitive reciprocal lattice of the system before expansion by cell transformation matrix inverse. Unit: Angstrom^-1.

Parameters:: initial (bool) – Read the initial or last lattice. Useful in case of geometry optimization.
Returns:: self.primitive_reciprocal_lattice (np.ndarray) – Lattice of the system.

get_config_analysis(return_multiplicity=False)

Return the configuration analysis for solid solutions (CONFCON keyword in input)

Parameters:: return_multiplicity (bool, optional) – Return multiplicity information. Defaults to False.
Returns:: list or str – Configuration analysis if available, or a warning message

get_convergence(history=False)

The wrapper of get_scf_convergence and get_opt_convergence. For analysing the geometry and energy convergence.

Note

It might not work well with SCF / OPT cycles of multiple systems such as PREOPTGEOM + EOS calculations

Note

For optimizations, it only returns to optimization convergence. SCF convergence is not available. Call get_opt_convergence() if needed.

Parameters:

history (bool) – Deprecated. Always return to history.

Returns:

self (Crystal_output) – New attributes listed below
self.final_energy (float) – eV

For other attributes, see get_scf_convergence() and get_opt_convergence() methods on the same page.

get_final_energy()

Get the final energy of the system. A wrapper of self.get_convergence.

Returns:: self.final_energy (float) – The final energy of the system in eV.

get_scf_convergence(all_cycles=False, scflog=None)

Returns the scf convergence energy and energy difference.

Note

With empirical corrections (DFT-D or gCP), the scf_energy refers to DFT energy only. The final_energy attribute includes corrections at the final step. final_energy is valid only if scf_status='converged'.

Note

For optimizations, using get_opt_convergence() with scf_history=True is suggested.

Parameters:

all_cycles (bool) – Deprecated.
scflog (str) – Path to ‘SCFOUT.LOG’. For optimizations, scflog=None returns to either the initial SCF convergence or every SCF step if ‘ONELOG’ keyword is enabled. This option helps to get SCF history from ‘SCFOUT.LOG’ file.

Returns:

self (Crystal_output) – New attributes listed below
self.scf_cycles (int|list) – Number of cycles. Array if multiple SCF cycles are read.
self.scf_status (str|list) – ‘terminated’, ‘converged’, ‘too many cycles’ and ‘unknown’. List if multiple SCF cycles are read.
self.scf_energy (array|list) – SCF energy convergence. Unit: eV
self.scf_deltae (array|list) – Energy difference. Unit: eV
self.final_energy (float) – Last step energy with corrections. Unit: eV

get_fermi_energy(history=False, scflog=None)

Returns the system Fermi energy / valance band maximum (insulators). For history=True, Fermi energy at step 0 is always 0 as no Fermi energy is solved. Similary, steps with SPINLOCK or level shifting also return to 0 Fermi energy.

Parameters:

history (bool) – Whether to read the convergence history of Fermi energy.
scflog (str) – Path to ‘SCFOUT.LOG’. For optimizations, scflog=None returns to either the initial Fermi energy or energies of every SCF if ‘ONELOG’ keyword is enabled. This option helps to get SCF history from ‘SCFOUT.LOG’ file.

Returns:

self.fermi_energy (float|array) – Fermi energy of the system. For spin-polarized insulators, the highest VBM is returned.
self.spin_pol (bool) – Not returned but defined Whether the calculation is spin-polarized.

get_band_gap(history=False, scflog=None)

Returns the system band gap. For history=True, gap at step 0 is always 0 as no energy gap is solved. Similary, steps with SPINLOCK or level shifting also return to 0 gap.

Parameters:

history (bool) – Whether to read the convergence history of band gap.
scflog (str) – Path to ‘SCFOUT.LOG’. For optimizations, scflog=None returns to either the initial band gap or gaps of every SCF if ‘ONELOG’ keyword is enabled. This option helps to get SCF history from ‘SCFOUT.LOG’ file.

Returns:

self.band_gap (float|array) – Band gap of the system. For spin-polarized systems, self.band_gap would be either a 2*1 array (history=False) or a nCYC*2 array (history=True).
self.spin_pol (bool) – Not returned but defined Whether the calculation is spin-polarized.

get_mulliken_charges()

Return the atomic Mulliken charges (PPAN keyword in input).

Returns:: self.mulliken_charges (array) – natom*1 for non spin-polarised systems. natom*3 for spin-polarised systems. [total, $\alpha$, $\beta$].

get_opt_convergence(primitive=False, scf_history=False, scflog=None, write_gui=False, gui_name=None, symmetry='pymatgen', **kwargs)

Returns optimisation convergence.

Parameters:

primitive (bool) – Deprecated. Use get_primitive_geometry() for initial and last geometries. The method here always returns to the actual structure optimized.
scf_history (bool) – Read SCF history of each optimisation step. Also refer to the get_scf_convergence() method.
scflog (str) – Path to ‘SCFOUT.LOG’. For optimizations, scflog=None returns to either the initial SCF convergence or every SCF step if ‘ONELOG’ keyword is enabled. This option helps to get SCF history from ‘SCFOUT.LOG’ file.
write_gui (bool) – If True, write .gui file of each step
gui_name (str) – Valid only if write_gui = True. Gui file is named as ‘gui_name-optxxx.gui’. If None, use ‘basename-optxxx.gui’. The basename is the same as output.
symmetry (str) – Valid only if write_gui = True. ‘pymatgen’ to use symmetry info from a pymatgen SpacegroupAnalyzer; ‘initial’ to use symmstry information on output file. If None, no symmstry. Otherwise it is taken from the existing gui file.
**kwargs – Valid only if write_gui = True and symmetry = 'pymatgen'. Passed to Pymatgen SpacegroupAnalyzer object.

Returns:

self (Crystal_output) – New attributes listed below
self.opt_cycles (int) – Number of cycles.
self.opt_status (str) – ‘terminated’, ‘converged’, ‘failed’ and ‘unknown’
self.opt_energy (array) – Total energy convergence. Unit: eV
self.opt_deltae (array) – Total energy difference. Unit: eV
self.opt_geometry (list) – Modified CStructure/CMolecule at each step.
self.opt_maxgrad (array) – Maximum gradient convergence. Unit: Hartree/Bohr
self.opt_rmsgrad (array) – RMS gradient convergence. Unit: Hartree/Bohr
self.opt_maxdisp (array) – Maximum displacement convergence. Unit: Bohr
self.opt_rmsdisp (array) – RMS displacement convergence. Unit: Bohr
self.final_energy (float) – Last step energy with corrections. Unit: eV

get_forces(initial=True, grad=False, scflog=None)

Read forces.

Note

To get forces of the last optimization step, ‘SCFOUT.LOG’ file or the ‘ONELOG’ keyword are needed.

Parameters:

initial (bool) – Deprecated.
grad (bool) – Return gradient convergence history. For optimizations only.
scflog (str) – Path to ‘SCFOUT.LOG’. For optimizations, scflog=None returns forces from the initial SCF convergence or forces of every SCF step if ‘ONELOG’ keyword is enabled. This option helps to get forces of every step from ‘SCFOUT.LOG’ file.

Returns:

self (Crystal_output) – New attributes listed below
self.forces_atoms (array) – natom*3 array. Atomic forces. Unit: Hartree/Bohr
self.forces_cell (array) – 3*3 array. Cell forces, 3D only. Unit: Hartree/Bohr
self.opt_maxgrad (array) – Maximum gradient convergence. Unit: Hartree/Bohr
self.opt_rmsgrad (array) – RMS gradient convergence. Unit: Hartree/Bohr

get_phonon(read_eigvt=False, rm_imaginary=True, rm_overlap=True, imaginary_tol=-0.0001, q_overlap_tol=0.0001, eigvt_amplitude=1.0)

Read phonon-related properties from output file.

Note

In QHA calculations, self.nqpoint refer to harmonic phonons computed. In other cases it refers to actual q points in reciprocal space.

Note

This method is developed as a basic I/O function for thermodynamic analysis. For phonon band / dos or IR / Raman spectra, please refer to the get_phonon_band, get_phonon_dos and get_spectra methods.

Parameters:

read_eigvt (bool) – Whether to read phonon eigenvectors and normalize it to 1.
rm_imaginary (bool) – Set negative frequencies to 0 and remove all the related properties. Only eigenvectors are kept.
rm_overlap (bool) – For dispersion calculations Remove repeated q points and recalculate their weights.
imaginary_tol (float) – ``rm_imaginary`` = True only The threshold of negative frequencies.
q_overlap_tol (float) – ``rm_overlap`` = True only The threshold of overlapping q points, defined as the 2nd norm of the difference of fractional q vectors
eigvt_amplitude (float|str) – Normalize the eigenvector to a certian amplitude. Either a number or ‘classical’ (classical amplitude in Bohr).

Returns:

self (Crystal_output) – New attributes listed below
self.edft (array[float]) – $E_{0}$ Energy with empirical correction. Unit: kJ/mol.
self.nqpoint (int) – Number of q points
self.qpoint (list[list[array[float], float]]) – A 1*nQpoint list of 1*2 list whose first element is a 1*3 array of fractional coordinates and the second is its weight.
self.nmode (array[int]) – Number of modes at q point. 1*nQpoint array.
self.frequency (array[float]) – nQpoint*nMode array ofvibrational frequency. Unit: THz
self.mode_symm (array[str]) – nQpoint*nMode array of the irreducible representations. In Mulliken symbols.
self.intens (array[float]) – nqpoint*nmode array of harmonic IR intensiy. Unit: km/mol
self.IR (array[bool]) – nqpoint*nmode array of boolean values specifying whether the mode is IR active
self.Raman (array[bool]) – nqpoint*nmode array of boolean values specifying whether the mode is Raman active
self.eigenvector (array[complex]) – ``read_eigvt = True only`` nqpoint*nmode*natom*3 array of eigenvectors.

get_phonon_band(q_overlap_tol=0.0001)

Read phonon bands from CRYSTAL output file.

Parameters:: q_overlap_tol (float) – The threshold for overlapped k points. Only used for getting tick positions.
Returns:: self.pband (PhononBand) – phonons.PhononBand object.

get_phonon_dos(read_INS=False, atom_prj=[], element_prj=[])

Read phonon density of states from CRYSTAL output file.

Parameters:

read_INS (bool) – Read the inelastic neutron scattering spectra, instead of the PDOS.
atom_prj (list) – Read the projections of atoms with specified labels.
element_prj (list) – Read projections of elements with specified conventional atomic numbers.

Returns:

self.pdos (PhononDOS) – phonons.PhononDOS object.

get_spectra(specfile, type='infer')

Read spectra from IRSPEC.DAT / RAMSPEC.DAT files.

Note

In principle, the code cannot tell the type of the files. It is important to assign the appropriate type to the type keyword. Currently the available options are ‘IRSPEC’ and ‘RAMSPEC’.

Parameters:

specfile (str) – File name of spectra data.
type (str) – Type of the file. See above. If ‘infer’, type is inferred from input file name.

Returns:

self.* (IR|Raman) – Dependending on the type keyword, return to spectra.IR or spectra.Raman objects. Attribute names same as type are set.

get_elatensor(*thickness)

Extracts the elastic tensor from the data.

Parameters:: *thickness (float) – Effective thickness of low dimensional materials, in $\AA$.
Returns:: self.tensor (numpy.ndarray) – Symmetrized elastic tensor in Voigt notation. For 3D systems, 6*6; for 2D, 3*3; for 1D, 1*1. The matrix always has 2 dimensions. Unit: GPa for 3D and 1D, 2D if effective thickness of materials are specified. Otherwise GPa.m for 2D and GPa.m $^{2}$ for 1D (might lead to very small numbers).

get_anh_spectra()

Note

This is not for the released feature of CRYSTAL23 v1.0.1

This method reads data from a CRYSTAL output file and processes it to extract anharmonic (VSCF and VCI) IR and Raman spectra.

Returns:

self.IR_HO_0K (array[float]) – 2D numpy array containing harmonic IR frequency and intensities computed at 0 K.
self.IR_HO_T (array[float]) – 2D numpy array containing harmonic IR frequency and intensities computed at temperature T.
self.IR_VSCF_0K (array[float]) – 2D numpy array containing VSCF IR frequency and intensities computed at 0 K.
self.IR_VSCF_T (array[float]) – 2D numpy array containing VSCF IR frequency and intensities computed at temperature T.
self.IR_VCI_0K (array[float]) – 2D numpy array containing VCI IR frequency and intensities computed at 0 K.
self.IR_VCI_T (array[float]) – 2D numpy array containing VCI IR frequency and intensities computed at temperature T.
self.Ram_HO_0K_tot (array[float]) – 2D numpy array containing harmonic Raman frequency and intensities (total) computed at 0 K.
self.Ram_HO_0K_per (array[float]) – 2D numpy array containing harmonic Raman frequency and intensities (perpendicular component ) computed at temperature 0 K.
self.Ram_HO_0K_par (array[float]) – 2D numpy array containing harmonic Raman frequency and intensities (parallel component ) computed at temperature 0 K.
self.Ram_HO_T_tot (array[float]) – 2D numpy array containing harmonic Raman frequency and intensities (total) computed at temperature T.
self.Ram_HO_T_per (array[float]) – 2D numpy array containing harmonic Raman frequency and intensities (perpendicular component ) computed at temperature T.
self.Ram_HO_T_par (array[float]) – 2D numpy array containing harmonic Raman frequency and intensities (parallel component ) computed at temperature T.
self.Ram_VSCF_0K_tot (array[float]) – 2D numpy array containing VSCF Raman frequency and intensities (total) computed at 0 K.
self.Ram_VSCF_0K_per (array[float]) – 2D numpy array containing VSCF Raman frequency and intensities (perpendicular component) computed at 0 K.
self.Ram_VSCF_0K_par (array[float]) – 2D numpy array containing VSCF Raman frequency and intensities (parallel component) computed at 0 K.
self.Ram_VSCF_T_tot (array[float]) – 2D numpy array containing VSCF Raman frequency and intensities (total) computed at temperature T.
self.Ram_VSCF_T_per (array[float]) – 2D numpy array containing VSCF Raman frequency and intensities (perpendicular component) computed at temperature T.
self.Ram_VSCF_T_par (array[float]) – 2D numpy array containing VSCF Raman frequency and intensities (parallel component) computed at temperature T.
self.Ram_VCI_0K_tot (array[float]) – 2D numpy array containing VCI Raman frequency and intensities (total) computed at 0 K.
self.Ram_VCI_0K_per (array[float]) – 2D numpy array containing VCI Raman frequency and intensities (perpendicular component) computed at 0 K.
self.Ram_VCI_0K_par (array[float]) – 2D numpy array containing VCI Raman frequency and intensities (parallel component) computed at 0 K.
self.Ram_VCI_T_tot (array[float]) – 2D numpy array containing VCI Raman frequency and intensities (total) computed at temperature T.
self.Ram_VCI_T_per (array[float]) – 2D numpy array containing VCI Raman frequency and intensities (perpendicular component) computed at temperature T.
self.Ram_VCI_T_par (array[float]) – 2D numpy array containing VCI Raman frequency and intensities (parallel component) computed at temperature T.
self.Ram_HO_0K_comp_xx (array[float]) – 2D numpy array containing harmonic Raman frequency and intensities (xx component) computed at 0 K.
self.Ram_HO_T_comp_xx (array[float]) – 2D numpy array containing harmonic Raman frequency and intensities (xx component) computed at temperature T.
self.Ram_VSCF_0K_comp_xx (array[float]) – 2D numpy array containing VSCF Raman frequency and intensities (xx component) computed at 0 K.
self.Ram_VSCF_T_comp_xx (array[float]) – 2D numpy array containing VSCF Raman frequency and intensities (xx component) computed at temperature T.
self.Ram_VCI_0K_comp_xx (array[float]) – 2D numpy array containing VCI Raman frequency and intensities (xx component) computed at 0 K.
self.Ram_VCI_T_comp_xx (array[float]) – 2D numpy array containing VCI Raman frequency and intensities (xx component) computed at temperature T.

Note

Please, note that for the sake of brevity, only the xx Raman component attributes have been listed here, but the yy, zz, xy, xz, yz components are available as well.

property n_atoms: Deprecated. Get structure object by ‘get_geometry’ and call the ‘num_sites’ attribute

property atom_symbols: Deprecated. Get structure object by ‘get_geometry’ and call the ‘species_symbol’ attribute

property atom_numbers: Deprecated. Get structure object by ‘get_geometry’ and call the ‘species_Z’ attribute

property atom_positions: Deprecated. Get structure object by ‘get_geometry’ and call the ‘crys_coords’ attribute

property atom_positions_cart: Deprecated. Get structure object by ‘get_geometry’ and call the ‘cart_coords’ attribute

property atom_positions_frac: Deprecated. Get structure object by ‘get_geometry’ and call the ‘crys_coords’ attribute

get_last_geom(write_gui_file=True, symm_info='pymatgen'): Deprecated. Use get_geometry(initial=False).

class Properties_input(source='')

Bases: Properties_inputBASE

Properties input object inherited from the Properties_inputBASE object. For the basic set-ups of keywords, please refer to manuals there.

Parameters:: source (str) – Template file or string. An empty object is generated for ''.

classmethod read_file(source)

Instantiate the object from a file.

Parameters:: source (str) – The name of the input file.
Returns:: cls (Properties_input)

write_file(file)

Writes the properties input to a file.

Parameters:: file (str) – The name of the d3 file.

make_band_block(k_path, n_kpoints, first_band, last_band, print_eig=0, print_option=1, precision=5, title='BAND STRUCTURE CALCULATION')

A shortcut for self.band(). Also accepts pymatgen HighSymmKpath objects for k path.

Parameters:

k_path (list | HighSymmKpath) – The k-path for the bands calculation.
n_kpoints (int) – The number of k-points along the path.
first_band (int) – The index of the first band.
last_band (int) – The index of the last band.
print_eig (int) – Printing options for eigenvalues (default is 0).
print_option (int) – Properties printing options (default is 1).
precision (int) – Precision in the calculation of numpy.gcd
title (str) – The title of the calculation.

make_doss_block(n_points=200, band_range=None, e_range=None, plotting_option=2, poly=12, print_option=1, projections=[], proj_type='atom', output_file=None)

A shortcut for self.doss().

Parameters:

n_points (int) – The number of points in the DOS plot.
band_range (list or tuple) – The range of bands to include in the DOS calculation.
e_range (list or tuple) – The energy range for the DOS calculation. Unit: eV
plotting_option (int) – DOS plotting options.
poly (int) – Degree of the polynomial for smearing.
print_option (int) – Properties printing options.
projections (list) – nProj*nElement list of ints specifying the projections for the pdoss calculation, or nProj*1 list of strings specifying element names to project on all atoms of the same element (output_file is needed).
proj_type (str) – Type of projection (‘atom’ or ‘site’).
output_file (str) – Output file of ‘crystal’ calculation.

make_pdoss_block(projections, proj_type='atom', output_file=None, n_points=200, band_range=None, e_range=None, plotting_option=2, poly=12, print_option=1): Deprecated. Use either self.doss() or self.make_doss_block()

make_newk_block(shrink1, shrink2, Fermi=1, print_option=0): Deprecated. Use self.newk().

make_bands_block(k_path, n_kpoints, first_band, last_band, print_eig=0, print_option=1, precision=5, title='BAND STRUCTURE CALCULATION'): Deprecated. Use self.make_band_block().

from_file(input_name): Deprecated. Use read_file()

write_properties_input(input_name): Deprecated. Use write_file()

class Properties_output(properties_output=None)

Bases: POutBASE

Creates a Properties_output object. Since not all results from ‘properties’ executable creates are summarized in output, methods of this class usually requires multiple files.

Note

Most of methods directly dealing with output file itself are saved in base.output.POutBASE object. Users typically do not need to call methods there since they are called internally.

Parameters:: properties_output (str) – Properties output file

classmethod read_file(properties_output)

Parse the properties output file.

Parameters:: properties_output (str) – The properties output file.
Returns:: cls (Properties_output)

read_electron_band(band_file)

Generate bands object from CRYSTAL BAND.DAT / fort.25 file. Energy unit: eV. E Fermi is aligned to 0.

Parameters:: band_file (str) – Name of BAND.DAT / fort.25 file.
Returns:: self.bands (ElectronBand) – The electronics.ElectronBand object.

read_Fermi_surface(f35_file)

Generate the Fermi surface, i.e., band energy across the first brillouin zone $E(k)$ from CRYSTAL fort.35 file (with ‘DLV_BAND’ keyword). Energy unit: eV.

Note

When output is available, energies are aligned to $E_{F}=0$. Otherwise values reported in fort.35 file are used.

Parameters:: f35_file (str) – Name of fort.35 file.
Returns:: self.FermiSurf (FermiSurface) – The electronics.FermiSurface object

read_electron_dos(dos_file)

Get density of states from CRYSTAL DOSS.DAT or fort.25 file. Energy unit: eV. E Fermi is aligned to 0.

Parameters:: dos_file (str) – Name of DOSS.DAT or fort.25 file
Returns:: self.doss (ElectronDOS) – The electronics.ElectronDOS object.

read_topond(topondfile, type='infer')

Read the 2D scalar plot files (‘SURF*.DAT’) or trajectory files (TRAJ*.DAT) written by TOPOND.

Geometry information is printed in the standard ouput, which is not mandatory for ‘SURF*.DAT’ but is mandatory for ‘TRAJ*.DAT’

Note

For the convenience of analysis and plotting, it is important to select the correct type for your input file. By default type=’infer’ will search for (case insensitive) the following strings:

‘SURFRHOO’, ‘SURFSPDE’, ‘SURFLAPP’, ‘SURFLAPM’, ‘SURFGRHO’, ‘SURFKKIN’, ‘SURFGKIN’, ‘SURFVIRI’, ‘SURFELFB’, ‘TRAJGRAD’, ‘TRAJMOLG’.

For their meanings, please refer TOPOND manual.

Parameters:

topondfile (str) – TOPOND formatted 2D plot file
type (str) – ‘infer’ or specified. Otherwise warning will be given.

Returns:

read_ECHG(*f25_files, method='normal', index=None)

Read charge / spin density data from a file. Unit: $e.\AA^{-3}$.

Available methods are:

‘normal’: Normal 1-file reading.
‘substract’: Substracting data from the first entry based on following
entries. Multiple entries or 1 entry with ‘PATO’ keyword enabled. For multiple entries, make sure the charge map is in the first (and ideally the only) ‘MAPN’ data block, otherwise the code won’t get the correct data. For 1 entry with ‘PATO’, data will be substracted from the ‘normal’ system.
‘alpha_beta’: Save spin-polarized data in $\alpha$ /
$\beta$ states, rather than charge($\alpha+\beta$) / spin($\alpha-\beta$). Single entry only.

Note

The standard screen output is highly recommended to add, which identifies the indices of corresponding 2D data maps. Otherwise the index input can be specified. Otherwise, the code only reads the first 2D data map for spin =1 and first 2 maps for spin=2.

Parameters:

*f25_files (str) – Path to the fort.25 file(s).
method (str) – Data processing method. See above.
index (int|list) – Sequence number of headers with the ‘-%-MAPN’ pattern. Useful only if the standard screen output is not available. Starting from 0.

Returns:

self.echg (ChargeDensity) – electronics.ChargeDensity object.

read_ECH3(*cubefiles, method='normal')

Read 3D charge / spin density data from CUBE files. Unit: $e.\AA^{-3}$.

Note

Only compatible with CRYSTAL cube outputs. Lattice constants are annotated in the comment line.

Available methods are:

‘normal’: Normal reading, 1 or 2 entries for charge and spin
densities.
‘substract’: Substracting data from the first entry based on following
entries.
‘alpha_beta’: Save spin-polarized data in $\alpha$ /
$\beta$ states, rather than charge($\alpha+\beta$) / spin($\alpha-\beta$). 1 or 2 entries for charge and spin densities.

Parameters:

*cubefiles (str) – Path to the CUBE file(s).
method (str) – Data processing method. See above.

Returns:

self.ech3 (ChargeDensity) – electronics.ChargeDensity object.

read_relativistics(f25_file, type, index=None)

Read 2D scalar / vector fields from 2c-SCF calculations, generated by the ‘PROPS2COMP’ keyword.

Note

The standard screen output is highly recommended to add, which identifies the indices of corresponding 2D data maps. Otherwise the index must be specified by integer or list of integers.

Parameters:

f25_file (str) – File name of the fort.25 file.
type (str|int|list) – Property to calculate, ‘DENSITY’, ‘MAGNETIZ’, ‘ORBCURDENS’, or ‘SPICURDENS’.
index (int|list) – Sequence number of headers with the ‘-%-MAPN’ pattern. Useful only if the standard screen output is not available. Starting from 0.

Returns:

self.* (ChargeDensity|Magnetization|OrbitalCurrentDensity|SpinCurrentDensity) – Return to classes defined in the relativisitcs module, depending on type. The attribute name is upper case type names. Unit: charge densities, $\AA^{-3}$; magnetization, A/m; Orbital/spin densities, A/m $^{2}$.

read_XRDspec(option='LP')

Read XRD spectra from standard screen output of properties calculation. It is envoked by keyword ‘XRDSPEC’.

Parameters:: option (str) – ‘NC’ for no correction (The ‘INTENS’ col); ‘LP’ for Lorentz and polarization effects (‘INTENS-LP’) and ‘DW’ for LP with Debye-Waller thermal factors (‘INTENS-LP-DW’).
Returns:: self.XRDspec (XRD) – The spectra.XRD object with spectra information.

read_cry_rholine(properties_output)

Read density line data from a file.

Parameters:: properties_output (str) – Path to the properties output file.
Returns:: self – The modified object with extracted density line data.

read_cry_lapl_profile(properties_output)

Read Laplacian profile data from a file.

Parameters:: properties_output (str) – Path to the properties output file.
Returns:: self – The modified object with extracted Laplacian profile data.

read_cry_density_profile(properties_output)

Read density profile data from a file.

Parameters:: properties_output (str) – Path to the properties output file.
Returns:: self – The modified object with extracted density profile data.

read_transport(boltztra_out)

Read electron transport properties by the BOLTZTRA keyword, including ‘KAPPA’, ‘SIGMA’, ‘SIGMAS’, ‘SEEBECK’ and ‘TDF’. Though currently the geometry information is not required, it is saved if the standard output file is given.

Note

For ‘SEEBECK’, all the 9 elements of the tensor was printed. As far as the developers have been aware of, it is symmetrized. Therefore the redundant ‘yx’, ‘zx’ and ‘zy’ dimensions are removed to keep consistent with other outputs.

Parameters:: boltztra_out (str) – ‘DAT’ files by CRYSTAL BOLTZTRA keyword.
Returns:: self.* (Tensor|Distribution) – transport.Tensor (‘KAPPA’, ‘SIGMA’, ‘SIGMAS’, ‘SEEBECK’) or transport.Distribution (TDF) classes, depending on the input file. The attribute name is upper case types.

read_cry_band(band_file): Deprecated. Use read_electron_band.

read_cry_doss(dos_file): Deprecated. Use read_electron_dos.

read_cry_ECHG(f25_file): Deprecated. Use read_ECHG.

read_cry_ECHG_delta(f25_file1, f25_file2): Deprecated. Use read_ECHG.

read_cry_contour(properties_output): Deprecated. Use read_topond.

read_cry_seebeck(properties_output): Deprecated. Use read_transport.

read_cry_sigma(properties_output): Deprecated. Use read_transport.

read_vecfield(properties_output, which_prop): Deprecated. Use read_relativistics.

read_cry_xrd_spec(properties_output): Deprecated. Use read_XRDspec.

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

Bases: Crystal_gui

Inherited from geometry.Crystal_gui. See documentations there.

class Crystal_density

Bases: object

Read density data from a .f98 file.

read_cry_irr_density(fort98_unit)

Read density profile data from a CRYSTAL .f98 file. :param fort98_unit: The file containing the formatted density matrix. :type fort98_unit: str

Returns:: None

Note: This is a work in progress. If you are interested in this functionality, please open an Issue on GitHub.

cry_combine_density(density1, density2, density3, new_density='new_density.f98', spin_pol=False)

Combine density matrix files.

Parameters:

density1 (str) – The first density matrix file.
density2 (str) – The second density matrix file.
density3 (str) – The density matrix file for the whole system.
new_density (str, optional) – The name of the new density matrix. Defaults to ‘new_density.f98’.
spin_pol (bool, optional) – Specifies if the system is spin polarized. Defaults to False.

Returns:

None

Note

This is a work in progress. If you are interested in this functionality, please open an Issue on GitHub.

write_cry_density(fort98_name, new_p, new_fort98)

Write the formatted density matrix.

Parameters:

fort98_name (str) – The name of the previous density matrix file.
new_p (list) – The new density matrix.
new_fort98 (str) – The name of the new density matrix file.
Returns
None

Note

This is a work in progress. If you are interested in this functionality, please open an Issue on GitHub.

CRYSTALpytools.elastics module

The module for 3D / 2D elastic properties.

class Tensor3D(matrix, lattice=None, is_compliance=True)

Bases: object

3D elastic tensor and related properties.

Parameters:

matrix (numpy.ndarray) – 6*6 compliance or stiffness matrix. Unit: GPa $^{-1}$ or GPa.
lattice (numpy.ndarray) – lattice matrix.
is_compliance (bool) – Compliance or stiffness matrix used as input.

property stiffness

GPa.

Type:: 6*6 stiffness matrix in Voigt annotation. Unit

property compliance

GPa $^{-1}$.

Type:: 6*6 compliance matrix in Voigt annotation. Unit

classmethod from_file(output, conventional_lattice=True)

Read elastic tensor from CRYSTAL output file and generate Tensor3D object. Calls the crystal_io.Crystal_output.get_elatensor() method. Lattice information is obtained.

Parameters:

output (str) – CRYSTAL output file.
conventional_lattice (bool) – Get conventional lattice.

Returns:

cls (Tensor3D)

get_1D(property, u, nchi=180, use_cartesian=True)

Compute properties along the given vector. Available properties are defined by the property variable. To get shear modulus / Poisson ratio of 2 specified vectors, use get_pair.

Options:

“young”: Young’s modulus in GPa.
“comp”: Linear compressibility.
“shear”: Shear modulus on the ‘loop’ normal to vector, in GPa.
“shear avg”: Averaged shear modulus on the ‘loop’, in GPa.
“shear min”: Minimum shear modulus on the ‘loop’, in GPa.
“shear max”: Maximum shear modulus on the ‘loop’, in GPa.
“poisson”: Poisson ratio on the ‘loop’ normal to vector.
“poisson avg”: Averaged Poisson ratio on the ‘loop’.
“poisson min”: Minimum Poisson ratio on the ‘loop’.
“poisson max”: Maximum Poisson ratio on the ‘loop’.

Parameters:

property (str) – Property to compute. See options above.
u (numpy.ndarray) – 3*1 or nu*3 array of vectors.
nchi (int) – Resolution of auxiliary angle $\chi$, in radian $[0, 2\pi)$. Shear modulus and Poisson ratio only.
use_cartesian (bool) – Vector is defined as cartesian or fractional coordinates. (Only when lattice information is available.)

Returns:

e (float | numpy.ndarray) – float or nu*1, some sort of property.

get_pair(property, u, v, use_cartesian=True)

Compute properties between given pairs of vectors. Used for shear modulus and Poisson ratio. For properties along the normal vector, use get_1D.

Options:

“shear”: Shear modulus between u and v, in GPa.
“poisson”: Poisson ratio between u and v.

Parameters:

property (str) – Property to compute. See options above.
u (numpy.ndarray) – 3*1 or nu*3 array of vector 1.
v (numpy.ndarray) – 3*1 or nu*3 array of vector 2.
use_cartesian (bool) – Vector is defined as cartesian or fractional coordinates. (Only when lattice information is available.)

Returns:

e (float | numpy.ndarray) – float or nu*1, some sort of property.

plot_2D(property, plane, ntheta=90, nchi=180, plane_definition='miller', u=None, utext=None, use_cartesian=True, plot_lattice=True, loop_color=None, loop_linestyle=None, loop_linewidth=None, figsize=[6.4, 4.8], get_data=False, **kwargs)

Plot 2D crystal elastic properties across the given plane. The plane is defined by any of the following methods:

‘miller’: Miller indices.
‘cartesian’: The plane normal vector in Cartesian coordinates.
‘fractional’: The plane normal vector in fractional coordinates.

Options:

“young”: Young’s modulus in GPa.
“comp”: Linear compressibility.
“shear”: Shear modulus in the plane, in GPa.
“shear avg”: Averaged shear modulus of vectors in the plane, in GPa.
“shear min”: Minimum shear modulus of vectors in the plane, in GPa.
“shear max”: Maximum shear modulus of vectors in the plane, in GPa.
“poisson”: Poisson ratio in the plane.
“poisson avg”: Averaged Poisson ratio of vectors in the plane.
“poisson min”: Minimum Poisson ratio of vectors in the plane.
“poisson max”: Maximum Poisson ratio of vectors in the plane.

This method can be used for multi-plane, multi-property plots. The same scale is enforced for subplots of the same property. Subplot titles are added automatically. The layout of subplots is, by default, nProp*nPlane or 1*nProp, which is not editable.

Parameters:

property (str|list) – Property(ies) to compute. See options above.
plane (numpy.ndarray) – 3*1 or nplane*3 array of planes.
ntheta (int) – Resolution of azimuth angle $\theta$ on plane, in radian $[0, 2\pi)$.
nchi (int) – Resolution of auxiliary angle $\chi$, in radian $[0, 2\pi)$. Shear modulus and Poisson ratio only.
plane_definition (str) – The method used to define the plane. See options above.
u (numpy.ndarray) – 3*1 or nu*3 array of vectors to be added into the figure. A line segment with doubled radius is plotted to indicate the vector. Or ‘max’ / ‘min’ / ‘bothends’, plot vectors corresponding to the max and min of elastic properties. For ‘bothends’, min first.
utext (list[str] | str) – A string or a list of string. Used to mark The vector. If None or ‘value’, the value is annotated.
use_cartesian (bool) – Vector is defined as cartesian or fractional coordinates. (Only when lattice information is available.)
plot_lattice (bool) – Draw lattice base vectors to indicate orientation of the plane.
loop_color (str|list) – Color of 2D loops. If only one string is given, apply it to all loops. ‘None’ for default values (matplotlib Tableau Palette).
loop_linestyle (str|list) – Linestyle of 2D loops. If only one string is given, apply it to all plots. ‘None’ for default values (‘-‘).
loop_linewidth (str|list) – Linewidth of band structure. If only one number is given, apply it to all plots. For the ‘multi’ mode, 1*nSystem list of linewidth numbers. ‘None’ for default values (1.0).
figsize (list) – The figure size specified as [width, height].
get_data (bool) – Developer only Return data or figure.
**kwargs – Parameters passed to PolarAxes.plot to customize the loops. Applied to all the loops.

Returns:

fig (Figure) – Matplotlib Figure object.

plot_3D(property, nphi=90, ntheta=90, nchi=180, scale_radius=True, range_cbar=None, range_x=None, range_y=None, range_z=None, u=None, utext=None, use_cartesian=True, plot_lattice=False, colormap='jet', title='default', figsize=[6.4, 4.8], plot_lib='matplotlib', **kwargs)

Plot 3D crystal elastic properties on the basis of the elastic tensor. The 3D surface is colored by the elastic property.

Options:

“young”: Young’s modulus in GPa.
“comp”: Linear compressibility.
“shear avg”: Averaged shear modulus in the normal plane, in GPa.
“shear min”: Minimum shear modulus in the normal plane, in GPa.
“shear max”: Maximum shear modulus in the normal plane, in GPa.
“poisson avg”: Averaged Poisson ratio in the normal plane.
“poisson min”: Minimum Poisson ratio in the normal plane.
“poisson max”: Maximum Poisson ratio in the normal plane.

Parameters:

property (str) – Property to compute. See options above.
nphi (int) – Resolution of azimuth angle $\phi$ on xy plane, in radian $[0, 2\pi)$.
ntheta (int) – Resolution of polar angle $\theta$ in radian $[0, 2\pi)$. In practice only half of the points defined in $[0, \pi)$ are used.
nchi (int) – Resolution of auxiliary angle $\chi$, in radian $[0, 2\pi)$. Shear modulus and Poisson ratio only.
scale_radius (bool) – To scale the radius by values of the elastic property, or plot a sphere with radius = 1.
range_cbar (list[float,float]) – Not suggested Explicitly specifying the ranges of colorbar, x, y and z axes.
range_x (list[float,float]) – Not suggested Explicitly specifying the ranges of colorbar, x, y and z axes.
range_y (list[float,float]) – Not suggested Explicitly specifying the ranges of colorbar, x, y and z axes.
range_z (list[float,float]) – Not suggested Explicitly specifying the ranges of colorbar, x, y and z axes.
u (numpy.ndarray) – 3*1 or nu*3 array of vectors to be added into the figure. A line segment with doubled radius is plotted to indicate the vector. Or ‘max’ / ‘min’ / ‘bothends’, plot vectors corresponding to the max and min of elastic properties. For ‘bothends’, min first.
utext (list[str] | str) – A string or a list of string. Used to mark the vector. If None, the input u and the corresponding value is annotated. If ‘value’, the value is annotated.
use_cartesian (bool) – Vector is defined as cartesian or fractional coordinates. (Only when lattice information is available.)
plot_lattice (bool) – Draw the lattice box around the 3D surface.
colormap (str) – Colormap name.
title (str|None) – Plot title. ‘default’ for default values and ‘None’ for no title.
figsize (list) – Figure size in inches. For plotly, 300 ppi is assumed.
plot_lib (bool) – ‘matplotlib’ or ‘plotly’. By default use matplotlib. Alternatively use plotly to enable interactive inspections in Jupyter Notebook.
**kwargs – Parameters passed to Axes3D.view_init (matplotlib) or fig.update_layout() (plotly). Only camera position keywords are suggested.

Returns:

fig (Figure) – Matplotlib or plotly Figure object. It axes is a 2*1 list of matplotlib Axis object. The first element is the axis of colorbar. The second is the axis of 3D surface. None if plot_lib = 'plotly'.

Note

When using u='max', only one vector will be plotted if the same value is repeated along different directions. Same for min and bothends.

transform(new_lattice)

Transform (rotate) the lattice and change matrix elements. Useful when lattice information is available.

Parameters:: new_lattice (numpy.ndarray)
Returns:: self (Tensor3D)

class Tensor2D(matrix, lattice=None, is_compliance=True)

Bases: object

2D elastic tensor and related properties. Periodic boundary conditions are consistent with CRYSTAL definitions, i.e., xy-periodic and slab vertical to z. Basic units: GPa, m

Parameters:

matrix (numpy.ndarray) – 3*3 compliance or stiffness matrix.
lattice (numpy.ndarray) – 2*2 lattice matrix.
is_compliance (bool) – Compliance or stiffness matrix used as input.

property stiffness

GPa, m.

Type:: 3*3 stiffness matrix in Voigt annotation. Basic units

property compliance

GPa, m.

Type:: 3*3 compliance matrix in Voigt annotation. Basic units

classmethod from_file(output, thickness)

Read elastic tensor from CRYSTAL output file and generate Tensor2D object. Calls the crystal_io.Crystal_output.get_elatensor() method. Lattice information is obtained.

Parameters:

output (str) – CRYSTAL output file.
thickness (float) – Effective thickness of low dimensional materials, in $\AA$.

Returns:

cls (Tensor2D)

get_1D(property, u, use_cartesian=True)

Compute properties along the given vector. Available properties are defined by the property variable. To get shear modulus / Poisson ratio of 2 specified vectors, use get_pair.

Options:

“young”: Young’s modulus in GPa.
“comp”: Linear compressibility.
“shear”: Shear modulus between the vector and its normal vector in plane, in GPa.
“poisson”: Poisson ratio between the vector and its normal vector in plane.

Parameters:

property (str) – Property to compute. See options above.
u (numpy.ndarray) – 2*1 or nu*2 array of vectors.
use_cartesian (bool) – Vector is defined as cartesian or fractional coordinates. (Only when lattice information is available.)

Returns:

e (float | numpy.ndarray) – float or nu*1, some sort of property.

get_pair(property, u, v, use_cartesian=True)

Compute properties between given pairs of in-plane vectors. Used for shear modulus and Poisson ratio. For properties along 1 given vector, use get_1D.

Options:

“shear”: Shear modulus between in-plane u and v, in GPa.
“poisson”: Poisson ratio between in-plane u and v.

Parameters:

property (str) – Property to compute. See options above.
u (numpy.ndarray) – 2*1 or nu*2 array of vector 1.
v (numpy.ndarray) – 2*1 or nu*2 array of vector 2.
use_cartesian (bool) – Vector is defined as cartesian or fractional coordinates. (Only when lattice information is available.)

Returns:

e (float | numpy.ndarray) – float or nu*1, some sort of property.

plot_2D(property, ntheta=90, u=None, utext=None, use_cartesian=True, plot_lattice=True, loop_color=None, loop_linestyle=None, loop_linewidth=None, layout=None, figsize=[6.4, 4.8], get_data=False, **kwargs)

Plot 2D crystal elastic properties of the system.

Options:

“young”: Young’s modulus in GPa.
“comp”: Linear compressibility.
“shear”: In-plane shear modulus between 2 vectors in the plane, in GPa.
“poisson”: In-plane Poisson ratio between 2 vectors in the plane.

This method can be used for multi-property plots. Subplot titles are added automatically. The layout of subplots is, by default, 1*nProp.

Note

u is defined by 2D vectors.

Parameters:

property (str|list) – Property(ies) to compute. See options above.
plane (numpy.ndarray) – 3*1 or nplane*3 array of planes.
ntheta (int) – Resolution of azimuth angle $\theta$ on plane, in radian $[0, 2\pi)$.
nchi (int) – Resolution of auxiliary angle $\chi$, in radian $[0, 2\pi)$. Shear modulus and Poisson ratio only.
plane_definition (str) – The method used to define the plane. See options above.
u (numpy.ndarray) – 2*1 or nu*2 array of vectors to be added into the figure. A line segment with doubled radius is plotted to indicate the vector. Or ‘max’ / ‘min’ / ‘bothends’, plot vectors corresponding to the max and min of elastic properties. For ‘bothends’, min first.
utext (list[str] | str) – A string or a list of string. Used to mark The vector. If None or ‘value’, the value is annotated.
use_cartesian (bool) – Vector is defined as cartesian or fractional coordinates. (Only when lattice information is available.)
plot_lattice (bool) – Draw lattice base vectors to indicate orientation of the plane.
loop_color (str|list) – Color of 2D loops. If only one string is given, apply it to all loops. ‘None’ for default values (matplotlib Tableau Palette).
loop_linestyle (str|list) – Linestyle of 2D loops. If only one string is given, apply it to all plots. ‘None’ for default values (‘-‘).
loop_linewidth (str|list) – Linewidth of band structure. If only one number is given, apply it to all plots. For the ‘multi’ mode, 1*nSystem list of linewidth numbers. ‘None’ for default values (1.0).
layout (list|tuple) – 2*1 list. The layout of subplots. The first element is nrows, the second is ncolumns. By default, 1*nProp.
figsize (list) – The figure size specified as [width, height].
get_data (bool) – Developer only Return data or figure.
**kwargs – Parameters passed to PolarAxes.plot to customize the loops. Applied to all the loops.

Returns:

fig (Figure) – Matplotlib Figure object.

transform(new_lattice)

Transform (rotate) the lattice and change matrix elements. Useful when lattice information is available.

Parameters:: new_lattice (numpy.ndarray)
Returns:: self (Tensor2D)

young(S, u, ndimen)

The equation of Young’s modulus. Using Tensor* objects is recommended.

\[E = \frac{1}{u_{i}u_{j}u_{k}u_{l}S_{ijkl}}\]

Einstein’s notation is used. $i,j,k,l=1,ndimen; j>i; l>k$.

Parameters:

S (numpy.ndarray) – ndimen*ndimen*ndimen*ndimen compliance matrix in Cartesian form. Base units: GPa, m.
u (numpy.ndarray) – nu*ndimen array. Must be normalized Cartesian vectors.
ndimen (int) – Dimensionality, either 2 or 3.

Returns:

e (numpy.ndarray) – nu*1 Youngs’s modulus. Base units: GPa, m.

comp(S, u, ndimen)

The equation of linear compressibility. Using Tensor* objects is recommended.

\[\beta = u_{i}u_{j}S_{ijkk}\]

Einstein’s notation is used. $i,j,k=1,ndimen; j>i$.

Parameters:

S (numpy.ndarray) – ndimen*ndimen*ndimen*ndimen compliance matrix in Cartesian form. Base units: GPa, m.
u (numpy.ndarray) – nu*ndimen array. Must be normalized Cartesian vectors.
ndimen (int) – Dimensionality, either 2 or 3.

Returns:

beta (numpy.ndarray) – nu*1 Linear compressibility.

shear(S, u, v, ndimen)

The equation of shear modulus. Using Tensor* objects is recommended.

\[G = \frac{1}{u_{i}v_{j}u_{k}v_{l}S_{ijkl}}\]

Einstein’s notation is used. $i,j,k,l=1,ndimen$.

Parameters:

S (numpy.ndarray) – ndimen*ndimen*ndimen*ndimen compliance matrix in Cartesian form. Base units: GPa, m.
u (numpy.ndarray) – nu*ndimen array. Must be normalized Cartesian vectors.
v (numpy.ndarray) – nu*nv*ndimen array. Must be normalized Cartesian vectors.
ndimen (int) – Dimensionality, either 2 or 3.

Returns:

g (numpy.ndarray) – nu*nv Shear modulus. Base units: GPa, m.

poisson(S, u, v, ndimen)

The equation of Poisson ratio. Using Tensor* objects is recommended.

\[\nu = -\frac{u_{i}u_{j}v_{k}v_{l}S_{ijkl}}{u_{i}u_{j}u_{k}u_{l}S_{ijkl}}\]

Einstein’s notation is used. $i,j,k=1,ndimen; j>i$.

Parameters:

S (numpy.ndarray) – ndimen*ndimen*ndimen*ndimen compliance matrix in Cartesian form. Base units: GPa, m.
u (numpy.ndarray) – nu*ndimen array. Must be normalized Cartesian vectors.
v (numpy.ndarray) – nu*nv*ndimen array. Must be normalized Cartesian vectors.
ndimen (int) – Dimensionality, either 2 or 3.

Returns:

nu (numpy.ndarray) – nu*nv Poisson ratio.

tensor_from_file(output, conventional_lattice=True, *thickness)

A wrapper function to get tensor objects of corresponding dimensionality.

Parameters:

output (str) – CRYSTAL output file.
conventional_lattice (bool) – 3D only. Get conventional lattice.
thickness (float) – 2D only. Effective thickness of low dimensional materials, in $\AA$.

Returns:

t (Tensor3D | Tensor2D) – Tensor objects.

voigt2cart(V)

Convert stiffness / compliance matrix in Voigt representation into Cartesian representation. For 3D: 6*6 to 3*3*3*3. For 2D: 3*3 to 2*2*2*2.

Parameters:: V (numpy.ndarray) – Voigt represented matrix.
Returns:: C (numpy.ndarray) – Cartesian represented matrix.

cart2voigt(C)

Convert 3*3*3*3 stiffness / compliance matrix in Cartesian representation into 6*6 Voigt representation.

Parameters:: C (numpy.ndarray) – Cartesian represented matrix.
Returns:: V (numpy.ndarray) – Voigt represented matrix.

CRYSTALpytools.electronics module

A post-processing module for electronic properties

class ElectronBand(spin, tick_pos, tick_label, efermi, bands, k_path, geometry=None, reciprocal_latt=None, tick_pos3d=None, k_path3d=None, unit='eV')

Bases: object

The class for electron band projected along high symmetry lines. For ‘3D band structures’, please refer to the electronics.FermiSurface class. Energy unit: eV. Fermi energy is aligned to 0.

Parameters:

spin (int) – 1, closed shell; 2, open shell
tick_pos (array) – 1*nTick array of 1D tick coordinates. Unit: $\AA$
tick_label (list) – 1*nTick of default tick labels.
efermi (float) – Fermi energy. Unit: eV.
bands (array) – nBand*nKpoint*nSpin array of energy of band structure. Aligned to $E_{F}=0$. Unit: eV.
k_path (array) – 1D coordinates of k points for band structure. Unit: $\AA$.
geometry (Structure) – Pymatgen structure
reciprocal_latt (array) – 3*3 array of reciprocal lattice matrix.
tick_pos3d (array) – 1*nTick 3D fractional tick coordinates.
k_path3d (array) – nKpoints*3 3D fractional coordinates of k points.
unit (str) – In principle, should always be ‘eV’: eV-Angstrom.

classmethod from_file(band, output=None)

Generate ElectronBand object from CRYSTAL BAND.DAT / fort.25 file. Energy unit: eV. Fermi energy is aligned to 0.

Parameters:

band (str) – Name of BAND.DAT / fort.25 file.
output (str) – Properties output file.

Returns:

cls (ElectronBand)

plot(**kwargs)

For band structure plotting, it is a wrapper of plot.plot_electron_bands() with option ‘single’ (i.e., single system). For input arguments or plotting multiple systems, check documentations there.

Parameters:: **kwargs – Plot setting parameters (i.e., except the variable for ElectronBand object). Check documents for plot.plot_electron_bands().
Returns:: fig (Figure) – Matplotlib figure object

property bandgap: A shortcut for band gap. Unit is consistent with the self.unit attribute.

get_bandgap()

Get band gap. For spin-polarized systems, 2*1 arrays are used for $\alpha$ and $\beta$ states. Data is rounded to 6 decimal places. Unit is consistent with the self.unit attribute.

Returns:

self.gap (float) – Band gap.
self.vbm (flat) – Valence band maximum, with reference to Fermi level.
self.cbm (float) – Conduction band minimum, with reference to Fermi level.
self.gap_pos (array) – Coordinates of vbm (1st element) and cbm (2nd element) 3D coordinates are returned if self.k_path3d is available. For spin-polarized cases, self.gap_pos[0] are vbm and cbm of $\alpha$ state.

to_pmg(labels=None)

Get Pymatgen BandStructureSymmLine object (inherited from BandStructure). No projection is available for now.

Note

3D information for output file is mandatory here.

Parameters:: labels (list[str]) – K point labels to display in the band structure.
Returns:: BandStructureSymmLine – Pymatgen band structure.

class FermiSurface(geometry, bands, efermi=0.0, unit='eV')

Bases: object

The class for electron band sampled across the first brillouin zone (1BZ), aka $E(k)$. For ‘normal’ band structures, please refer to the electronics.ElectronBand class. Energy unit: eV. Fermi energy is aligned to 0. For 3D and 2D systems only.

Note

The data grid is defined and saved in reciprocal unit cell, rather than 1BZ.

Parameters:

geometry (array|CStructure) – Matrix of reciprocal lattice, or an extended pymatgen Structure object.
bands (array) – nBand*nZ*nY*nX*nSpin of band energy aligned to $E_{F}=0$. The non-periodic direction must have the dimension of 1. Unit: eV.
efermi (float) – Fermi energy. Unit: eV.
unit (str) – In principle, should always be ‘eV’: eV-Angstrom.

Returns:

self (FermiSurface) – Attributes listed below.
self.rlattice (array) – Reciprocal lattice.
self.dimension (int) – 2 or 3
self.spin (int) – 1 or 2
self.bands (array) – Bands
self.efermi (float)
self.BZ (list) – Cartesian coordinates of vertices of 1BZ. Arranged in planes (i.e., the element of 4*3 array represents a plane of 4 vertices).
self.unit (str) – ‘eV’ or ‘a.u.’

classmethod from_file(band, output=None)

Generate FermiSurface object from CRYSTAL fort.35 file. Energy unit: eV. Fermi energy is aligned to 0.

Parameters:

band (str) – Name of fort.35 files.
output (str) – Properties output file.

Returns:

cls (FermiSurface)

property bandgap: A shortcut for band gap. Unit is consistent with the self.unit attribute.

get_bandgap()

Get band gap. For spin-polarized systems, 2*1 arrays are used for $\alpha$ and $\beta$ states. Data is rounded to 6 decimal places. Unit is consistent with the self.unit attribute.

Returns:

self.gap (float) – Band gap.
self.vbm (flat) – Valence band maximum, with reference to Fermi level.
self.cbm (float) – Conduction band minimum, with reference to Fermi level.
self.gap_pos (array) – Coordinates of vbm (1st element) and cbm (2nd element). For spin-polarized cases, self.gap_pos[0] are vbm and cbm of $\alpha$ state.

plot(band_index='vb', isovalue=0.0, interp='no interp', interp_size=1, colormap='jet', opacity=1.0, transparent=False, BZ_plot=True, BZ_scale=1.0, BZ_color=(0.0, 0.0, 0.0), BZ_linewidth=1.0, tick_pos=[], tick_label=[], **kwargs)

Plot $E(k)$ in the first brillouin zone (1BZ).

Note

MayaVi is used to display $E(k)$, which is not installed by default.

For 3D systems, it is displayed as isosurfaces of $E(k)$.
For 2D systems, the distribution is displayed, so isovalue is
disabled.

For 3D systems, displaying multiple bands is discouraged. But the user can still visualize the isosurfaces of multiple bands and the same isovalue and colormap applies to all the bands.

Note

Too large interp_size might be very memory and cpu demanding!

Parameters:

band_index (list|str|int) – Indices of bands to plot. Starting from 1. For spin-polarized cases, one can specify ‘4a’ for the $\alpha$ state of band 4. Use ‘vb’ and ‘cb’ to display the highest valance or the lowest conduction band.
isovalue (float|list) – 3D system only Isovalue of surfaces.
interp (str) –
Interpolate data to smoothen the plot. ‘no interp’ or ‘linear’, ‘nearest’, ‘slinear’, ‘cubic’. please refer to scipy.interpolate.interpn

The interpolated data is not saved.
interp_size (list[int]|int) – The new size of interpolated data (list) or a scaling factor. Valid only when ``interp`` is not ‘no interp’.
colormap (str) – Mayavi colormap.
opacity (float) – See Mayavi mlab.
transparent (bool) –
See Mayavi mlab.
BZ_plot (bool) – Whether to plot the boundary of 1BZ.
BZ_scale (float) – Must be between 1 and 2. Do not truncate data grid at the boundary of 1BZ, slightly expanding it by the scaling factor. This does not change the 1BZ frame plotted.
BZ_color (array) –
Color of the 1BZ plot. See Mayavi colormap.
BZ_linewidth (float) – Linewidth of the 1BZ plot.
tick_pos (array) – Not implemented
tick_label (list) – Not implemented
**kwargs – Other keywords passed to the mlab.view() command to adjust views. By default only distance='auto' is used.

Returns:

None

to_bxsf(filename, band_index=[])

3D data only

Write data into the XCrySDen BXSF file format. Unit: $\AA^{-1}$ and eV. Band labels:

[0:-2]: Band index strating from 1;
-2: Useless, 0;
-1: Spin. Alpha / No spin, 1; Beta, 2

Parameters:

filename (str) – The output xsf filename.
band_index (list|str|int) – Indices of bands to be saved. Same as the band_index option of the plot() method. ‘[]’ for all bands.

Returns:

None

class ElectronDOS(spin, efermi, doss, energy, unit='eV')

Bases: object

Electron DOS object. Energy unit: eV. E Fermi is aligned to 0.

Parameters:

spin (int) – 1, closed shell; 2, open shell
efermi (float) – Fermi energy. Unit: eV.
doss (array) – n_proj*n_energy*spin array of DOS. Positive values for both spin up and spin down states
energy (array) – Positions of DOS peaks (x axis)
unit (str) – In principle, should always be ‘eV’: eV-Angstrom.

classmethod from_file(dos)

Generate an ElectronDOS object from fort.25 / DOSS.DAT file.

Parameters:: band (str) – ‘fort.25’ or ‘DOSS.DAT’
Returns:: cls (ElectronDOS)

plot(**kwargs)

A wrapper to plot density of states of a single system with matplotlib. For input arguments or plotting multiple systems, check plot.plot_electron_doss().

Parameters:: **kwargs – Plot setting parameters (i.e., except the variable for ElectronDOS object). Check documents for plot.plot_electron_doss().
Returns:: fig (Figure) – Matplotlib figure object

class ElectronBandDOS(band, dos)

Bases: object

Electron band + dos object. Energy unit: eV. E Fermi is aligned to 0.

Parameters:

band (ElectronBand) – ElectronBand object
dos (ElectronDOS) – ElectronDOS object

classmethod from_file(*files, output=None)

Get ElectronBandDOS object from files

Parameters:

*files (str) – 2 files, the first one is for band, ‘fort.25’ or ‘BAND.DAT’; the second one is for DOS, ‘fort.25’ or ‘DOSS.DAT’. Or a single ‘fort.25’ file with both band and DOS.
output (str) – Property output file

Returns:

cls (ElectronBandDOS)

plot(**kwargs)

A wrapper to plot electron band structure + density of states of a single system with matplotlib. For input arguments, check plot.plot_electron_banddos().

Parameters:: **kwargs – Plot setting parameters (i.e., except the variable for ElectronBandDOS object). Check documents for plot.plot_electron_banddos().
Returns:: fig (Figure) – Matplotlib figure object

class ChargeDensity(data, base, spin, dimen, struc=None, unit='Angstrom')

Bases: object

Charge (spin) density object. Unit: $e.\AA^{-3}$.

Parameters:

data (array) – Plot data. nY*nX*nSpin (2D) or nZ*nY*nX*nSpin (2D)
base (array) – 3(4)*3 Cartesian coordinates of the 3(4) points defining base vectors BA, BC (2D) or OA, OB, OC (3D). The sequence is (O), A, B, C.
spin (int) – 1 or 2.
dimen (int) – Dimensionality of the plot.
struc (CStructure) – Extended Pymatgen Structure object.
unit (str) – In principle, should always be ‘Angstrom’ (case insensitive).

classmethod from_file(*files, output=None, method='normal')

Generate a ChargeDensity object from a single file, or from multiple files by substracting values from the first entry. Can be used for multiple dimensions (2D and 3D).

Note

The standard screen output is required to identify the indices of corresponding 2D data maps. Otherwise the code only reads the first 1 (2) 2D data maps for spin = 1 (2).

Available methods are:

‘normal’: Normal. For 2D fort.25 files, 1 entry. For 3D cube files,
2 entries for charge and spin if needed.
‘substact’: Substracting data from the first entry based on following
entries. Multiple entries only.
‘alpha_beta’: Save spin-polarized data in $\alpha$ /
$\beta$ states, rather than charge($\alpha+\beta$) / spin($\alpha-\beta$). For 2D fort.25 files, 1 entry. For 3D cube files, 2 entries for charge and spin if needed.

Parameters:

*files (str) – Path to the charge density / spin density file(s). All the entries must be in the same file format.
output (str) – Screen output file.
method (str) – See above.

Returns:

cls (ChargeDensity)

substract(*args)

Substracting data of the same type from the object.

Parameters:: *args (str|ChargeDensity) – File names or ChargeDensity objects.
Returns:: self (ChargeDensity) – spin dimension, if there is, is not kept. Only charge density difference is substracted.

alpha_beta()

Get the $\alpha$ / $\beta$ state density, rather than charge($\alpha+\beta$) / spin($\alpha-\beta$). spin=2 only.

Returns:: self (ChargeDensity) – The first entry of self.data is $\alpha$ state density and the second is $\beta$ state.

plot_2D(unit='Angstrom', option='both', levels=150, lineplot=False, linewidth=1.0, isovalues=None, colorplot=True, colormap='jet', cbar_label='default', a_range=[], b_range=[], rectangle=False, edgeplot=False, x_ticks=5, y_ticks=5, title='default', figsize=[6.4, 4.8], fig=None, ax_index=None, **kwargs)

Plot 2D charge/spin density map. A wrapper of plot.plot_dens_ECHG and plot.plot_spin_ECHG.

3 styles are available:

lineplot=True and colorplot=True: The color-filled contour
map with black contour lines. Dotted lines for negative values and solid lines for positive values. The solid line twice in width for 0.
lineplot=False and colorplot=True: The color-filled contour
map.
lineplot=True and colorplot=False: The color coded contour
line map. Blue dotted line for negative values and red solid lines for positive values. The balck solid line twice in width for 0.

Available options:

‘both’If spin polarized, plot both charge and spin densities.
Otherwise plot charge densities.
‘charge’: Plot charge density.
‘spin’: Plot spin density.

Parameters:

unit (str) – Plot unit. ‘Angstrom’ for $\AA^{-3}$, ‘a.u.’ for Bohr $^{-3}$.
option (str) – Available options see above.
levels (int|array) – Set levels of contour plot. A number for linear scaled plot colors or an array for user-defined levels, must be consistent with ``unit``. 2*nLevel can be defined when option='both'.
lineplot (bool) – Plot contour lines.
linewidth (float) – Contour linewidth. Useful only if lineplot=True. Other properties are not editable. Solid black lines for positive values and 0, dotted for negative.
isovalues (str|None) – Add isovalues to contour lines and set their formats. Useful only if lineplot=True. None for not adding isovalues
colorplot (bool) – Plot color-filled contour plots.
colormap (str) – Matplotlib colormap option. Useful only if colorplot=True.
cbar_label (str) – Label of colorbar. Useful only if colorplot=True. 1*2 list of colorbar titles can be set for spin-polarized systems. ‘default’ for unit and symbol. ‘None’ for no labels.
a_range (list) – 1*2 range of $a$ axis (x, or BC) in fractional coordinate.
b_range (list) – 1*2 range of $b$ axis (x, or AB) in fractional coordinate.
rectangle (bool) – If $a, b$ are non-orthogonal, plot a rectangle region and reset $b$. If used together with b_range, that refers to the old $b$ (i.e., expansion first).
edgeplot (bool) – Whether to add cell edges represented by the original base vectors (not inflenced by a/b range or rectangle options).
x_ticks (int) – Number of ticks on x axis.
y_ticks (int) – Number of ticks on y axis.
title (str|None) – Titles for both charge and spin densities. ‘default’ for default values and ‘None’ for no title.
figsize (list) – Matplotlib figure size. Note that axes aspects are fixed to be equal.
fig (Figure) – Developer Only, matplotlib Figure class.
ax_index (list[int]) – Developer Only, indices of axes in fig.axes.
**kwargs – Other arguments passed to axes.contour() function to set contour lines.

Returns:

fig (Figure) – Matplotlib figure object
ax (Axes) – Matplotlib axes object

to_xsf(filename)

2D / 3D data only

Write data into the XCrySDen XSF file format. The code writes into either 2D or 3D data grids depending on the dimension attribute. For spin-polarized cases, 2 maps will be written with the title ‘alpha+beta’ and ‘alpha-beta’ and into 2 data blocks. Objects updated by the alpha_beta() method will get grids with the same titles, which needs extra attention.

Note

Geometry information is mandatory.

Note

For 3D data grid, if CUBE file(s) are read without output, the XSF file output has the 3D ‘CRYSTAL’ periodicity. As far as the authors have been aware of, this only causes Segmentation Fault of XCrySDen 1.6.2 when dealing with low dimensional systems. Available solution includes 1. including output file 2. using other software such as VESTA 3. Changing the keyword manually.

Parameters:: filename (str) – The output xsf filename.
Returns:: None

CRYSTALpytools.execute module

Created on Fri Nov 19 18:28:54 2021

set_runcry_path(path)

Set the path for the Runcry executable.

Parameters:: path (str) – The path to the Runcry executable.
Returns:: None

set_runprop_path(path)

Set the path for the Runprop executable.

Parameters:: path (str) – The path to the Runprop executable.
Returns:: None

runcry(file_name, guessp=None)

Run Runcry calculation.

Parameters:

file_name (str) – The name of the file to run the calculation.
guessp (str, optional) – The guessp parameter. Default is None.

Returns:

str – The result of the calculation or an error message.

runprop(prop_name, wf_file)

Run Runprop calculation.

Parameters:

prop_name (str) – The name of the property to calculate.
wf_file (str) – The name of the wavefunction file.

Returns:

str – The result of the calculation or an error message.

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.

class CMolecule(coords, symmetry_group=1, **kwargs)

Bases: Molecule

Inherited from Pymatgen Molecule object with added methods.

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.
**kwargs – Other arguments passed to pymatgen Molecule.

Returns:

self (CMolecule) – CMolecule object.

CRYSTALpytools.phonons module

A post-processing module for phonon properties

class PhononBand(tick_pos, tick_label, bands, k_path, geometry=None, reciprocal_latt=None, tick_pos3d=None, k_path3d=None, unit='THz')

Bases: object

Phonon band object. Frequency unit: THz.

Note

Even though this class is not directly inherited from the electronics.ElectronBand class, its bands attribute still has the same, nBand*nKpoint*nSpin dimentionalities for using the shared plotting functions. nSpin is always 1 here.

Parameters:

tick_pos (array) – 1*nTick array of 1D tick coordinates. Unit: Angstrom
tick_label (list) – 1*nTick of default tick labels
bands (array) – nBand*nKpoint*1 array of frequency. Unit: THz
k_path (array) – 1D coordinates of k points. Unit: Angstrom
geometry (Structure) – Pymatgen structure
reciprocal_latt (array) – 3*3 array of reciprocal lattice matrix. Not valid if geometry is specified.
tick_pos3d (array) – 1*nTick 3D fractional tick coordinates
k_path3d (array) – nKpoints*3 3D fractional coordinates of k points
unit (str) – In principle, should always be ‘THz’: THz-Angstrom.

classmethod from_file(output, q_overlap_tol=0.0001)

Generate an PhononBand object from the output file of CRYSTAL.

Note

Currently only the screen output (‘.out’) file is supported.

Parameters:

output (str) – CRYSTAL output file
q_overlap_tol (float) – The threshold for overlapped k points. Only used for getting tick positions.

Returns:

cls (PhononBand)

plot(**kwargs)

A wrapper to plot band structure of a single system using matplotlib. For input arguments or plotting multiple systems, check plot.plot_phonon_bands().

Parameters:: **kwargs – Plot setting parameters (i.e., except the variable for PhononBand object). Check documents for plot.plot_electron_bands().
Returns:: fig (Figure) – Matplotlib figure object

class PhononDOS(doss, frequency, unit='THz')

Bases: object

Phonon DOS object. Frequency unit: THz.

Note

Even though this class is not directly inherited from the electronics.ElectronDOS class, its doss attribute still has the same, nProj*nFrequency*nSpin dimentionalities for using the shared plotting functions. nSpin is always 1 here.

Parameters:

doss (array) – nProj*nFrequency*1 array of DOS.
frequency (array) – Positions of DOS peaks (x axis)
unit (str) – In principle, should always be ‘THz’: THz-Angstrom.

classmethod from_file(output, read_INS=False, atom_prj=[], element_prj=[])

Generate an PhononDOS object from the output file of CRYSTAL.

Note

Currently only the screen output (‘.out’) file is supported.

Parameters:

output (str) – CRYSTAL output file
read_INS (bool) – Read the inelastic neutron scattering spectra.
atom_prj (list) – Read the projections of atoms with specified labels.
element_prj (list) – Read projections of elements with specified conventional atomic numbers.

Returns:

cls (PhononDOS)

plot(**kwargs)

A wrapper to plot density of states of a single system with matplotlib. For input arguments or plotting multiple systems, check plot.plot_phonon_doss().

Parameters:: **kwargs – Plot setting parameters (i.e., except the variable for PhononDOS object). Check documents for plot.plot_phonon_doss().
Returns:: fig (Figure) – Matplotlib figure object

class PhononBandDOS(band, dos)

Bases: object

Phonon band + dos object. Frequency unit: THz.

Parameters:

band (PhononBand) – PhononBand object
dos (PhononDOS) – PhononDOS object

classmethod from_file(*output, q_overlap_tol=0.0001, read_INS=False, atom_prj=[], element_prj=[])

Get PhononBandDOS object from files

Parameters:

*output (str) – CRYSTAL screen output file. 2 files, the first one is for band the second one is for DOS. Or a single output file file with both band and DOS.
q_overlap_tol (float) – The threshold for overlapped k points. Only used for getting tick positions.
read_INS (bool) – Read the inelastic neutron scattering spectra.
atom_prj (list) – Read the projections of atoms with specified labels.
element_prj (list) – Read projections of elements with specified conventional atomic numbers.

Returns:

cls (PhononBandDOS)

plot(**kwargs)

A wrapper to plot phonon band structure + density of states of a single system with matplotlib. For input arguments, check plot.plot_phonon_banddos().

Parameters:: **kwargs – Plot setting parameters (i.e., except the variable for PhononBandDOS object). Check documents for plot.plot_phonon_banddos().
Returns:: fig (Figure) – Matplotlib figure object

CRYSTALpytools.plot module

Functions to visualize CRYSTAL outputs.

plot_ECHG(*echg, unit='Angstrom', output=[], option='both', levels=150, lineplot=False, linewidth=1.0, isovalues=None, colorplot=True, colormap='jet', cbar_label='default', a_range=[], b_range=[], rectangle=False, edgeplot=False, x_ticks=5, y_ticks=5, layout=None, title=None, figsize=[6.4, 4.8], sharex=True, sharey=True, fontsize=14, **kwargs)

Read and plot multiple 2D charge density files / objects. The uniform plot set-ups are used for comparison.

3 styles are available:

lineplot=True and colorplot=True: The color-filled contour map
with black contour lines. Dotted lines for negative values and solid lines for positive values. The solid line twice in width for 0.
lineplot=False and colorplot=True: The color-filled contour map.
lineplot=True and colorplot=False: The color coded contour line
map. Blue dotted line for negative values and red solid lines for positive values. The balck solid line twice in width for 0.

Available options:

‘both’If spin polarized, plot both charge and spin densities.
Otherwise plot charge densities.
‘charge’: Plot charge density.
‘spin’: Plot spin density.
‘diff’: Substracting charge data from the first entry with the following
entries. Return to a non spin-polarized object.

Parameters:

*echg (electronics.ChargeDensity|str) – Extendable. File names or electronics.ChargeDensity objects.
unit (str) – Plot unit. ‘Angstrom’ for $\AA^{-3}$, ‘a.u.’ for Bohr $^{-3}$.
output (str|list[str]) – Output files corresponding to the input data file. String for the same output of all the files and list for every input file. If not given, read the first 1(2) MAPNET data of systems without (with) spin.
option (str) – Available options see above.
levels (int|array) – Set levels of contour plot. A number for linear scaled plot colors or an array for user-defined levels, must be consistent with ``unit``. 2*nLevel can be defined when option='both'.
lineplot (bool) – Plot contour lines.
linewidth (float) – Contour linewidth. Useful only if lineplot=True. Other properties are not editable. Solid black lines for positive values and 0, dotted for negative.
isovalues (str|None) – Add isovalues to contour lines and set their formats. Useful only if lineplot=True. None for not adding isovalues.
colorplot (bool) – Plot color-filled contour plots.
colormap (str) – Matplotlib colormap option. Useful only if colorplot=True.
cbar_label (str) – Label of colorbar. Useful only if colorplot=True. 1*2 list of colorbar titles can be set for spin-polarized systems. ‘None’ for no labels and ‘default’ for default label.
a_range (list) – 1*2 range of $a$ axis (x, or BC) in fractional coordinate.
b_range (list) – 1*2 range of $b$ axis (x, or AB) in fractional coordinate.
rectangle (bool) – If $a, b$ are non-orthogonal, plot a rectangle region and reset $b$. If used together with b_range, that refers to the old $b$.
edgeplot (bool) – Whether to add cell edges represented by the original base vectors (not inflenced by a/b range or rectangle options).
x_ticks (int) – Number of ticks on x axis.
y_ticks (int) – Number of ticks on y axis.
layout (list|tuple) – The layout of subplots, [nrow, ncol]. Default is 2 cols per row.
title (str|None) – The title of the plot. ‘None’ for no title. The default subplot titles are used either way.
figsize (list) – Matplotlib figure size. Note that axes aspects are fixed to be equal.
sharex (bool) – Whether to share the x-axis among subplots.
sharey (bool) – Whether to share the y-axis among subplots.
fontsize (int) – Fontsize of the heightest level of title.
**kwargs – Other arguments passed to axes.contour() function to set contour lines. Applied to all the subplots.

Returns:

figs (list|Figure) – Matplotlib Figure object or a list of them.

plot_relativistics2D(*relat, unit='SI', type=[], output=[], direction=['x', 'y', 'z'], levels=100, quiverplot=True, quiverscale=1.0, colorplot=True, colormap='jet', cbar_label='default', a_range=[], b_range=[], rectangle=False, edgeplot=False, x_ticks=5, y_ticks=5, layout=None, title=None, figsize=[6.4, 4.8], sharex=True, sharey=True, fontsize=14, **kwargs)

Plot 2D vector field properties from relativistics (2c-SCF) calculations.

3 styles are available:

quiverplot=True and colorplot=True: The color-filled contour
illustrates the norm of vectors. The black arrows indicates both the directions and norms of in-plane prjections.
quiverplot=True and colorplot=False: The arrows are colored to
indicate the directions and norms of in-plane prjections.
quiverplot=False and colorplot=True: The color-filled contour
illustrates the norm of vectors, similar to the 2D scalar map.

Note

Not for charge density (relativistics.ChargeDensity). To visualize it, use plot_ECHG.

Parameters:

*relat (str|Magnetization|OrbitalCurrentDensity|SpinCurrentDensity|) – extendable input of vector field classes, or input files.
unit (str) – Plot unit. ‘SI’ for $\AA$ and A/m (A/m $^{2}$). ‘a.u.’ for Bohr and a.u. magnetization / current density.
type (str|list[str]) – Properties to plot. Either as a string or a list of strings consistent with input filenames. If a list of types and a single file is given, read all the types from the input file. In other cases error would be given.
output (str|list[str]) – Output files corresponding to the input data file. String for the same output of all the files and list for every input file.
direction (list[str]|str) – Only for SpinCurrentDensity classes. Direction of spin-current to plot, in ‘x’, ‘y’ or ‘z’. Applied to all the SpinCurrentDensity objects.
levels (int|array) – Set levels of colored contour/quiver plot. A number for linear scaled plot colors or an array for user-defined levels. 1D.
quiverplot (bool) – Plot 2D field of arrows.
quiverscale (float) – Tune the length of arrows. Useful only if quiverplot=True.
colorplot (bool) – Plot color-filled contour plots.
colormap (str) – Matplotlib colormap option. Useful only if colorplot=True.
cbar_label (str|None) – Label of colorbar. ‘default’ for unit. ‘None’ for no label. Useful only if colorplot=True.
a_range (list) – 1*2 range of $a$ axis (x, or BC) in fractional coordinate.
b_range (list) – 1*2 range of $b$ axis (x, or AB) in fractional coordinate.
rectangle (bool) – If $a, b$ are non-orthogonal, plot a rectangle region and reset $b$. If used together with b_range, that refers to the old $b$ (i.e., expansion first).
edgeplot (bool) – Whether to add cell edges represented by the original base vectors (not inflenced by a/b range or rectangle options).
x_ticks (int) – Number of ticks on x axis.
y_ticks (int) – Number of ticks on y axis.
layout (list|tuple) – The layout of subplots, [nrow, ncol]. Default is 2 cols per row.
title (str|None) – The title of the plot. ‘None’ for no title. The default subplot titles are used either way.
figsize (list) – Matplotlib figure size. Note that axes aspects are fixed to be equal.
sharex (bool) – Whether to share the x-axis among subplots.
sharey (bool) – Whether to share the y-axis among subplots.
fontsize (int) – Fontsize of the heightest level of title.
**kwargs – Other arguments passed to axes.quiver() function to set arrow styles. Applied to all the subplots.
Returns – fig (Figure): Matplotlib Figure class.

plot_electron_bands(*bands, unit='eV', k_label=[], mode='single', not_scaled=False, energy_range=[], k_range=[], band_label=None, band_color=None, band_linestyle=None, band_linewidth=None, fermi_level=0.0, fermi_color='tab:green', fermi_linestyle='-', fermi_linewidth=1.0, layout=None, title=None, figsize=[6.4, 4.8], legend='lower right', sharex=True, sharey=True, fontsize=14, **kwargs)

Plot electron band structures.

Parameters:

*bands (ElectronBand|str) – electronics.ElectronBand object or band structure files of the CRYSTAL properties excutable. Note that lattice information is not available if file names are specified.
unit (str) – The unit of energy. Can be ‘eV’ or ‘a.u.’.
k_label (list) – nSystem*nTick or 1*nTick list of strings of the label for high symmetry points along the path. If a 1D list is given, the same labels are used for all the systems. mathtext experssions can also be used as in matplotlib.
mode (str) – The plotting mode, ‘single’, ‘multi’ and ‘compare’.
not_scaled (bool) – Whether to scale the x-axis for different volumes. Useful with mode='compare'. The multi mode forces scaling.
energy_range (array) – A 2x1 array specifying the energy range.
k_range (array) – A 2x1 array specifying the k-range.
band_label (str|list) – Plot legend. If only one string is given, apply it to all plots. 1*nSystem or nSystem*2 (spin) plot legend otherwise. If spin>1 and 1*nSystem list is used, they are marked with the same label.
band_color (str|list) – Color of band structure. If only one string is given, apply it to all plots. For ‘single’ and ‘compare’ modes, also 1*2 color list for spin. For the ‘multi’ mode, 1*nSystem or nSystem*2 (spin) plot color. If spin>1 and spin dimension is not included, spin states are in the same color. ‘None’ for default values (‘tab:blue’ and other tab series).
band_linestyle (str|list) – Linestyle of band structure. If only one string is given, apply it to all plots. For ‘single’ and ‘compare’ also r 1*2 linestyle list for spin. For the ‘multi’ mode, 1*nSystem or nSystem*2 (spin) linestyle string. If spin>1 and spin dimension is not included, spin states are in the same style. ‘None’ for default values (‘-‘).
band_linewidth (str|list) – Linewidth of band structure. If only one number is given, apply it to all plots. For ‘single’ and ‘compare’ modes, also 1*2 linewidth list for spin. For the ‘multi’ mode, 1*nSystem or nSystem*2 (spin) linewidth numbers. If spin>1 and spin dimension is not included, spin states are in the same width. ‘None’ for default values (1.0).
fermi_level (float|list|None) – Fermi energy in the same unit as input band energy. By default the band is aligned to 0. Can be used to offset the band. None for not plotting Fermi. For ‘compare’ mode, different offsets can be used.
fermi_color (str) – Color of the Fermi level.
fermi_linestyle (str) – Line style of Fermi level.
fermi_linewidth (float) – Width of the Fermi level.
layout (list|tuple) – For ‘compare’ mode, the layout of subplots, [nrow, ncol]. The default is 2 cols per row.
title (str) – The title of the plot.
figsize (list) – The figure size specified as [width, height].
legend (str|None) – Loc parameter passed to axes.legend() None for not adding legend.
sharex (bool) – Whether to share the x-axis among subplots.
sharey (bool) – Whether to share the y-axis among subplots.
fontsize (int) – Fontsize of the highest level title and axis labels.
**kwargs – Other arguments passed to Axes.plot() of band plots.

Returns:

fig (Figure) – Matplotlib figure object

Raises:

ValueError – If the specified unit is unknown.

plot_electron_doss(*doss, unit='eV', beta='up', overlap=False, prj=[], energy_range=[], dos_range=[], dos_label=None, dos_color=None, dos_linestyle=None, dos_linewidth=None, fermi_level=0.0, fermi_color='tab:green', fermi_linestyle='-', fermi_linewidth=1.0, title=None, figsize=[6.4, 4.8], legend='lower right', sharex=True, sharey=False, fontsize=14, **kwargs)

Plot electron density of states.

Parameters:

*doss (ElectronDOS|str) – electronics.ElectronDOS object or DOSS files of the CRYSTAL properties excutable. Note that lattice information is not available if file names are specified.
unit (str) – ‘eV’ or ‘a.u.’
beta (str) – Plot settings for $eta$ states (‘up’ or ‘down’).
overlap (bool) – Plotting multiple projections into the same figure. Useful only if a single entry of doss is plotted. Otherwise projections from the same entry will be overlapped into the same subplot.
prj (list) – Index of selected projections, consistent with the first dimension of the doss, starting from 1. Effective for all the subplots.
energy_range (list) – 1*2 list of energy range
dos_range (list) – 1*2 list of DOS range
dos_label (str|list) – Plot legend. If only one string is given, apply it to all plots. 1*nPrj or nPrj*2 (spin) plot legend otherwise. If spin>1 and 1*nSystem list is used, they are marked with the same label. Effective for all the subplots.
dos_color (str|list) – Color of DOSS plots. If only one string is given, apply it to all plots. 1*nPrj or nPrj*2 (spin) plot color. If spin>1 and spin dimension is not included, spin states are in the same color. ‘None’ for default values (matplotlib Tableau Palette for both spin-up and spin-down states). Effective for all the subplots.
dos_linestyle (str|list) – Linestyle of DOSS plot. If only one string is given, apply it to all plots. 1*nPrj or nPrj*2 (spin) line styles. If spin>1 and spin dimension is not included, spin states are in the same linestyle. ‘None’ for default values (‘-’ for spin-ups and ‘–’ for spin-downs). Effective for all the subplots.
dos_linewidth (str|list) – Linewidth of DOSS plot. If only one number is given, apply it to all plots. 1*nPrj or nPrj*2 (spin) line widthes. If spin>1 and spin dimension is not included, spin states are in the same linestyle. ‘None’ for default values (1.0). Effective for all the subplots.
fermi_level (float|list|None) – Fermi energy in the same unit as input doss energy. By default the doss is aligned to 0. Can be used to offset the doss. None for not plotting Fermi.
fermi_color (str) – Color of the Fermi level.
fermi_linestyle (str) – Line style of Fermi level.
fermi_linewidth (float) – Width of the Fermi level.
title (str) – The title of the plot.
figsize (list) – The figure size specified as [width, height].
legend (str|None) –
Loc parameter passed to axes.legend() None for not adding legend.
sharex (bool) – Whether to share the x-axis among subplots.
sharey (bool) – Whether to share the y-axis among subplots.
fontsize (int) – Fontsize of the highest level title and axis labels.
**kwargs – Other arguments passed to Axes.plot() of band plots.

Returns:

fig (Figure) – Matplotlib figure object

plot_electron_banddos(*data, unit='eV', k_label=[], dos_beta='down', dos_overlap=True, dos_prj=[], energy_range=[], k_range=[], dos_range=[], band_width=2, band_label=None, band_color=None, band_linestyle=None, band_linewidth=None, dos_label=None, dos_color=None, dos_linestyle=None, dos_linewidth=None, fermi_level=0.0, fermi_color='tab:green', fermi_linestyle='-', fermi_linewidth=1.0, title=None, figsize=[6.4, 4.8], legend='lower right', fontsize=14, **kwargs)

Plot electron band structure + dos for a single system, i.e., the bands and doss variables are not extendable.

Input arguments not in the list are consistent with plot_electron_doss and plot_electron_bands.

Parameters:

*data – Either 1 or 2 entries. For one enetry, it is fort.25 containing both band and DOS, or ElectronBandDOS object. For 2 entries, the first entry is bands of plot_electron_bands and the second is doss of plot_electron_doss
dos_beta (str) – beta of plot_electron_doss.
dos_overlap (bool) – overlap of plot_electron_doss. The user can either plot projections into the same subplot or into separate subplots.
dos_prj (list) – prj of plot_electron_doss.
band_width (int|float) – Relative width of band structure, times of the width of a DOS subplot.

Returns:

fig (Figure) – Matplotlib figure object

Raises:

ValueError – If the unit parameter is unknown.

plot_topond2D(*topond, unit='Angstrom', type='infer', option='normal', levels='default', lineplot=True, linewidth=1.0, isovalues='%.4f', colorplot=False, colormap='jet', cbar_label='default', cpt_marker='o', cpt_color='k', cpt_size=10, traj_color='r', traj_linestyle=':', traj_linewidth=0.5, a_range=[], b_range=[], edgeplot=False, x_ticks=5, y_ticks=5, layout=None, title=None, figsize=[6.4, 4.8], sharex=True, sharey=True, fontsize=14)

Read and plot multiple TOPOND 2D plot files / objects. The uniform plot set-ups are used for comparison.

Note

For the convenience of analysis and plotting, it is important to select the correct type for your input file. By default type=’infer’ will search for (case insensitive) the following strings:

‘SURFRHOO’, ‘SURFSPDE’, ‘SURFLAPP’, ‘SURFLAPM’, ‘SURFGRHO’, ‘SURFKKIN’, ‘SURFGKIN’, ‘SURFVIRI’, ‘SURFELFB’, ‘TRAJGRAD’, ‘TRAJMOLG’

For their meanings, please refer the TOPOND manual.

Available options:

‘normal’ : Literally normal.
‘diff’Substract data from the first entry using following entries. All
the entries must have the same type and must be ‘SURF*’ types.
‘overlay’: Overlapping a ‘TRAJ*’ object on the 2D ‘SURF*’ object. Inputs
must be 1*2 lists of a Surf object and a Traj object. File names are not permitted as geometry information is mandatory.

Note

2D periodicity (a_range and b_range), though available for the child classes of the topond.ScalarField class, is not suggested as TOPOND plotting window does not always commensurate with periodic boundary. The topond.Trajectory class has no 2D periodicity so if option='overlay', a_range, b_range and edgeplot will be disabled.

Note

The plot_lapm option is not available for Laplacian class. Use Laplacian().plot_2D().

Parameters:

*topond (electronics.ChargeDensity|SpinDensity|Gradient|Laplacian|HamiltonianKE|LagrangianKE|VirialField|ELF|GradientTraj|ChemicalGraph|list|str) – Extendable. File names, topond objects or 1*2 list for option='overlay'. Geometry information is not available if file names are used - might lead to errors!.
unit (str) – Plot unit. ‘Angstrom’ for $\AA^{-3}$, ‘a.u.’ for Bohr $^{-3}$.
type (str) – ‘infer’ or specified. Otherwise warning will be given.
option (str) – Available options see above.
levels (array|int) – Set levels of contour plot. ‘Default’ for built-in, property adaptive levels (unit='Angstrom'). Otherwise as array or int for linear scales. Entries must be consistent with ``unit``.
lineplot (bool) – Plot contour lines.
linewidth (float) – Contour linewidth. Useful only if lineplot=True. Other properties are not editable.
isovalues (str|None) – Add isovalues to contour lines and set their formats. Useful only if lineplot=True. None for not adding isovalues.
colorplot (bool) – Plot color-filled contour plots.
colormap (str) – Matplotlib colormap option. Useful only if colorplot=True.
cbar_label (str) – Label of colorbar. Useful only if colorplot=True. ‘None’ for default.
cpt_marker (str) – Marker of critical point scatter.
cpt_color (str) – Marker color of critical point scatter.
cpt_size (float|int) – Marker size of critical point scatter.
traj_color (str) – Line color of 2D trajectory plot.
traj_linestyl (str) – Line style of 2D trajectory plot.
traj_linewidth (str) – Line width of 2D trajectory plot.
a_range (list) – 1*2 range of $a$ axis (x, or BC) in fractional coordinate. ‘Surf’ plots only.
b_range (list) – 1*2 range of $b$ axis (x, or AB) in fractional coordinate. ‘Surf’ plots only.
edgeplot (bool) – Whether to add cell boundaries represented by the original base vectors (not inflenced by a/b range).
x_ticks (int) – Number of ticks on x axis.
y_ticks (int) – Number of ticks on y axis.
title (str|None) – The title of the plot. ‘None’ for no title. The default subplot titles are used either way.
figsize (list) – Matplotlib figure size. Note that axes aspects are fixed to be equal.
sharex (bool) – Whether to share the x-axis among subplots.
sharey (bool) – Whether to share the y-axis among subplots.
fontsize (int) – Fontsize of the heightest level of title.

Returns:

fig (Figure) – Matplotlib Figure object.

plot_cry_rholine(rholine_obj)

Plot the resistivity as a function of distance.

Parameters:

rholine_obj (object) – Rholine object containing the data for the resistivity.
save_to_file (bool, optional) – If True, saves the plot to a file. Default is False.

Returns:

None

Notes: - Plots the resistivity as a function of distance. - Sets the x-axis label as \AA and the y-axis label as \rho [\frac{e}{\AA^{3}]. - Saves the plot to a file named ‘figure_rholine_YYYY-MM-DD_HHMMSS.jpg’ in the current directory. - If save_to_file is True, saves the plot to a file specified by save_to_file parameter.

plot_cry_lapl_profile(lapl_obj)

Plot the Laplacian profile of a crystal.

Parameters:

lapl_obj (object) – Laplacian object containing the data for the Laplacian profile.
save_to_file (bool, optional) – Indicates whether to save the plot to a file. Defaults to False.

Returns:

None

Notes

Plots the Laplacian profile using the data from the Laplacian object.
The x-axis represents the distance in angstroms.
The y-axis represents the Laplacian in electrons per cubic angstrom to the fifth power (e/A^5).
The area under the curve where the Laplacian is negative is filled with a light blue color.
The area under the curve where the Laplacian is positive is filled with a light coral color.
If save_to_file is set to a file path, the plot is saved to that file.

plot_cry_density_profile(lapl_obj)

Plot the density profile of a crystal.

Parameters:

lapl_obj (object) – Laplacian object containing the data for the density profile.
save_to_file (bool, optional) – Indicates whether to save the plot to a file. Defaults to False.

Returns:

None

Notes

Plots the density profile using the data from the Laplacian object.
The x-axis represents the distance in angstroms.
The y-axis represents the density in electrons per cubic angstrom (e/A^3).
If save_to_file is set to a file path, the plot is saved to that file.

plot_transport_tensor(*boltztra, option='normal', x_axis='potential', x_range=[], direction='xx', spin='sum', plot_series=[], plot_label=None, plot_color=None, plot_linestyle=None, plot_linewidth=None, zero_color='tab:gray', zero_linestyle='-', zero_linewidth=1.0, layout=None, title=None, figsize=[6.4, 4.8], legend='upper left', sharey=True, fontsize=14, **kwargs)

Plot tensor-like transport properties in multiple ways:

Normal: For 1 entry, same as transport.Tensor.plot(). Otherwise plot
different transport properties of the same system. A massive plot in nRow*nCol is plotted and each subplot consists of nDir*1 subplots. The layout option only specifies the layout of property blocks, and the sharey option fixes the y axis scale of ‘sub-subplots’.
Multi: Plot transport properties of different systems together for
comparison. In this case direction does not accept list variables, and entries of plot_series will be plotted into subplots.

With list inputs the user can get thermoelectric power factor ($S^{2}\sigma$) or dimensionless figure of merit ($ZT = \frac{S^{r}\sigma T}{\kappa}$).

Power Factor: 1*2 list of any 2 in ‘SIGMA’, ‘SIGMAS’ and ‘SEEBECK’.
ZT: 1*3 list of 1 ‘KAPPA’ and any 2 in ‘SIGMA’, ‘SIGMAS’ and ‘SEEBECK’.

Note

Make sure all the entries are from the same calculation when using ‘power factor’ or ‘zt’ options. The code only checks the dimensionalities of tensors.

X-axis options:

X_axis: Chemical potential $\mu$; Plot series: Temperature $T$.
X_axis: Carrier density $\rho(\mu; T)$; Plot series: Temperature $T$.
X_axis: Temperature $T$; Plot series: Chemical potential $\mu$.

Parameters:

*boltztra (str|Tensor) – DAT’ files by CRYSTAL BOLTZTRA keyword or the transport.Tensor objects.
option (str) – ‘power factor’, ‘zt’ and ‘multi’. See above.
x_axis (str) – X axis options, ‘potential’, ‘carrier’ or ‘temperature’. See above.
x_range (list) – Display range of x axis. Y axis is self-adaptive.
direction (str|list) – Depending on the dimensionality of the system, including ‘xx’, ‘xy’, ‘xz’, ‘yx’, ‘yy’, ‘yz’, ‘zx’, ‘zy’ and ‘zz’. A list of options will generate nDirect*1 subplots. The direction of each subplot is annotated on the upper left corner. List entry is not allowed for ``option=’multi’``.
spin (str) – Spin-polarized systems only. Electron spins to plot. ‘up’, ‘down’ or ‘sum’. Disabled for option='spin'.
plot_series (list|array|float) – Values of the plot series. Should be commensurate with the choice of x_axis. It will be annotated on the upper right corner for option='multi'.
plot_label (list|str|None) – None for default values: plot_series and its unit, or sequence number of materials for option='multi'. If str, prefixing that entry in front of the default value. If list, it should be 1*nPlotSeries, or 1*nBoltztra for option='multi', for every plot line.
plot_color (list|str|None) – Similar to electronics.ElectronDOS.plot(). If str, use the same color for all the plot lines. If 1*nPlotSeries(nBoltztra), use the same color for every plot line. If 2*nPlotSeries(nBoltztra), use different colors for p-type and n-type carrier properties.
plot_linestyle (list|str|None) – Similar to electronics.ElectronDOS.plot(). See explanations of plot_color.
plot_linewidth (list|float|None) – Similar to electronics.ElectronDOS.plot(). See explanations of plot_color.
zero_color (str) – Color of the 0 value line.
zero_linestyle (str) – Linestyle of the 0 value line.
zero_linewidth (float) – Linewidth of the 0 value line.
layout (list[int]) – Layout of subplots. By default it is nDirection*1 or nPlot_series*1 gird of figures.
title (str) – Title
figsize (list) – Figure size.
legend (str|None) – Location of legend. None for not adding legend.
sharey (bool) – Share y axis for multiple subplots. Share x is enforced.
fontsize (float|int) – Font size of the title, subplot capations (direction), x and y axis capations.
**kwargs – Other arguments passed to the matplotlib Axes.plot() method. Applied to all the plots.

Returns:

fig (Figure) – Matplotlib Figure object.

plot_elastics3D(*tensor, property, uniform_scale=True, nphi=90, ntheta=90, nchi=180, scale_radius=True, range_cbar=None, range_x=None, range_y=None, range_z=None, u=None, utext=None, use_cartesian=True, plot_lattice=False, colormap='jet', layout=None, title=None, figsize=[6.4, 4.8], fontsize=14, **kwargs)

A wrapper function of Tensor3D objects to plot 3D crystal elastic properties. The user can plot multiple properties for different systems. The function returns to a matplotlib figure object for further processing. The uniform plot set-ups are used for comparison. Only matplotlib is used for plotting. Plotly is not available.

Properties:

“young”: Young’s modulus.
“comp”: Compressibility.
“shear avg”: Average shear modulus.
“shear min”: Minimum shear modulus.
“shear max”: Maximum shear modulus.
“poisson avg”: Average Poisson ratio.
“poisson min”: Minimum Poisson ratio.
“poisson max”: Maximum Poisson ratio.

Parameters:

*tensor (str | Tensor3D | numpy.ndarray) – Elastic tensor definition. Can be CRYSTAL output files, Tensor3D objects and 6*6 elastic matrices in Voigt notation, GPa. For files, conventional_lattice=True.
property (str | list[str]) – The properties to plot. See above.
uniform_scale (bool) – Use the same color scale for all plots of the same property.
nphi (int) – Resolution of azimuth angle $\phi$ on xy plane, in radian $[0, 2\pi)$.
ntheta (int) – Resolution of polar angle $\theta$ in radian $[0, 2\pi)$. In practice only half of the points defined in $[0, \pi)$ are used.
nchi (int) – Resolution of auxiliary angle $\chi$, in radian $[0, 2\pi)$. Shear modulus and Poisson ratio only.
scale_radius (bool) – To scale the radius by values of the elastic property, or plot a sphere with radius = 1.
range_cbar (list[float,float]) – Not suggested Explicitly specifying the ranges of colorbar, x, y and z axes.
range_x (list[float,float]) – Not suggested Explicitly specifying the ranges of colorbar, x, y and z axes.
range_y (list[float,float]) – Not suggested Explicitly specifying the ranges of colorbar, x, y and z axes.
range_z (list[float,float]) – Not suggested Explicitly specifying the ranges of colorbar, x, y and z axes.
u (numpy.ndarray) – 3*1 or nu*3 array of vectors to be added into the figure. A line segment with doubled radius is plotted to indicate the vector. Or ‘max’ / ‘min’ / ‘bothends’, plot vectors corresponding to the max and min of elastic properties. For ‘bothends’, min first.
utext (list[str] | str) – A string or a list of string. Used to mark the vector. If None, the input u and the corresponding value is annotated. If ‘value’, the value is annotated.
use_cartesian (bool) – Vector is defined as cartesian or fractional coordinates. (Only when lattice information is available.)
plot_lattice (bool) – Draw the lattice box around the 3D surface.
colormap (str) – Colormap name.
layout (list|tuple) – The layout of subplots, [nrow, ncol]. Default is nTensor*nProperty or 1*nTensor.
title (str|None) – The title of the plot. ‘None’ for no title. The default subplot titles (property) are added either way.
figsize (list) – Matplotlib figure size.
fontsize (int) – Fontsize of the heightest level of title.
**kwargs – Parameters passed to Axes3D.view_init. Only camera position keywords are suggested.

Returns:

fig (Figure) – Matplotlib figure object.

plot_elastics2D(*tensor, property, plane=[], ntheta=90, nchi=180, plane_definition='miller', u=None, utext=None, use_cartesian=True, plot_lattice=True, loop_label=None, loop_color=None, loop_linestyle=None, loop_linewidth=None, layout=None, title=None, figsize=[6.4, 4.8], legend='upper left', fontsize=14, **kwargs)

A wrapper function of Tensor3D or Tensor2D objects to plot 2D crystal elastic properties. The user can plot multiple properties on multiple crystal planes (3D only) for multiple systems. The function returns to a matplotlib figure object for further processing. The uniform plot set-ups (radius) are used for comparison. Base units: GPa, m.

Properties, depending on the dimensionality of systems:

“young”: Young’s modulus.
“comp”: Compressibility.
“shear”: Shear modulus between vectors in plane and plane norm (3D) or in-plane vectors (2D).
“shear avg”: Average shear modulus (3D).
“shear min”: Minimum shear modulus (3D).
“shear max”: Maximum shear modulus (3D).
“poisson”: Poisson ratio between vectors in plane and plane norm or in-plane vectors (2D).
“poisson avg”: Average Poisson ratio (3D).
“poisson min”: Minimum Poisson ratio (3D).
“poisson max”: Maximum Poisson ratio (3D).

For 3D systems, the plotting planes have to be defined with any of the following methods:

‘miller’: Miller indices.
‘cartesian’: The plane normal vector in Cartesian coordinates.
‘fractional’: The plane normal vector in fractional coordinates.

The default layout is either 1*nProp or nProp*nPlane. For multi-system plottings, the properties on the same plane are plotted into the same axis for comparison. The radius is ‘uniform’ for the same property, i.e., same raidus for plots on various materials and planes.

Note

For multi-system plotting, the loop_* inputs do not change with the plotting planes, but with systems in order to distinguish them. Therefore they should be defined by 1*nTensor list. In this case, loop_label is used. Otherwise it is not called.

For multi-system plotting, u and utext options are disabled.

Parameters:

*tensor (str|Tensor3D|numpy.ndarray) – Elastic tensor definition. Can be CRYSTAL output files, Tensor3D / Tensor2D``objects and 6\*6 / 3\*3 **elastic** matrices in Voigt notation, GPa. But dimensionalities of systems must be consistent. For 3D files, ``conventional_lattice=True.
property (str | list[str]) – The properties to plot. See above.
plane (numpy.ndarray) – 3D only 3*1 or nplane*3 array of planes.
ntheta (int) – Resolution of azimuth angle $\theta$ on plane, in radian $[0, 2\pi)$.
nchi (int) – 3D only Resolution of auxiliary angle $\chi$, in radian $[0, 2\pi)$. Shear modulus and Poisson ratio only.
plane_definition (str) – 3D only The method used to define the plane. See options above.
u (numpy.ndarray) – nDimen*1 or nu*nDimen array of vectors to be added into the figure. A line segment with doubled radius is plotted to indicate the vector. Or ‘max’ / ‘min’ / ‘bothends’, plot vectors corresponding to the max and min of elastic properties. For ‘bothends’, min first.
utext (list[str] | str) – A string or a list of string. Used to mark The vector. If None or ‘value’, the value is annotated.
use_cartesian (bool) – Vector is defined as cartesian or fractional coordinates. (Only when lattice information is available.)
plot_lattice (bool) – Draw lattice base vectors to indicate orientation of the plane.
loop_label (str|list) – Multi-tensor only Label of loops. None for default values: sequence number of materials If str, prefixing that entry in front of the default value. If list, it should be in 1*nTensor.
loop_color (str|list) – Color of 2D loops. If only one string is given, apply it to all loops. ‘None’ for default values (matplotlib Tableau Palette).
loop_linestyle (str|list) – Linestyle of 2D loops. If only one string is given, apply it to all plots. ‘None’ for default values (‘-‘).
loop_linewidth (str|list) – Linewidth of band structure. If only one number is given, apply it to all plots. For the ‘multi’ mode, 1*nSystem list of linewidth numbers. ‘None’ for default values (1.0).
layout (list|tuple) – 2D only 2*1 list. The layout of subplots. The first element is nrows, the second is ncolumns. By default, 1*nProp.
title (str) – Title
figsize (list) – The figure size specified as [width, height].
legend (str|None) – Multi-tensor only Location of legend. None for not adding legend.
fontsize (float|int) – Font size of the title.
**kwargs – Parameters passed to PolarAxes.plot to customize the loops. Applied to all the loops.

Returns:

fig (Figure) – Matplotlib figure object.

plot_phonon_bands(*bands, unit='cm-1', q_overlap_tol=0.0001, k_label=None, mode='single', not_scaled=False, frequency_range=[], k_range=[], band_label=None, band_color=None, band_linestyle=None, band_linewidth=None, plot_freq0=True, freq0_color='tab:gray', freq0_linestyle='-', freq0_linewidth=1.0, layout=None, title=None, figsize=[6.4, 4.8], legend='lower right', sharex=True, sharey=True, fontsize=14, **kwargs)

Plot phonon band structures.

Parameters:

*bands (PhononBand|str) – phonons.PhononBand object or the standard screen output (.out) files of CRYSTAL.
unit (str) – The unit of frequency. Can be ‘cm-1’ or ‘THz’.
q_overlap_tol (float) – The threshold for overlapped k points. Only used for getting tick positions. For filename input only.
k_label (list) –
nSystem*nTick or 1*nTick list of strings of the label for high symmetry points along the path. If a 1D list is given, the same labels are used for all the systems. mathtext experssions can also be used as in matplotlib.
mode (str) – The plotting mode, ‘single’, ‘multi’ and ‘compare’.
not_scaled (bool) – Whether to scale the x-axis for different volumes. Useful with mode='compare'. The multi mode forces scaling.
frequency_range (array) – A 2x1 array specifying the frequency range.
k_range (array) – A 2x1 array specifying the k-range.
band_label (str|list) – Plot legend. If only one string is given, apply it to all plots. 1*nSystem plot legend otherwise.
band_color (str|list) – Color of band structure. If only one string is given, apply it to all plots. For the ‘multi’ mode, 1*nSystem list of plot colors. ‘None’ for default values (matplotlib Tableau Palette).
band_linestyle (str|list) – Linestyle of band structure. If only one string is given, apply it to all plots. For the ‘multi’ mode, 1*nSystem list of linestyle strings. ‘None’ for default values (‘-‘).
band_linewidth (str|list) – Linewidth of band structure. If only one number is given, apply it to all plots. For the ‘multi’ mode, 1*nSystem list of linewidth numbers. ‘None’ for default values (1.0).
plot_freq0 (bool) – Whether to plot 0 frequency line.
freq0_color (str) – Color of the 0 frequency line.
freq0_linestyle (str) – Line style of 0 frequency line.
freq0_linewidth (float) – Width of the 0 frequency line.
layout (list|tuple) – For ‘compare’ mode, the layout of subplots, [nrow, ncol]. The default is 2 cols per row.
title (str) – The title of the plot.
figsize (list) – The figure size specified as [width, height].
legend (str|None) –
Loc parameter passed to axes.legend() None for not adding legend.
sharex (bool) – Whether to share the x-axis among subplots.
sharey (bool) – Whether to share the y-axis among subplots.
fontsize (int) – Fontsize of the highest level title and axis labels.
**kwargs – Other arguments passed to Axes.plot() of band plots.

Returns:

fig (Figure) – Matplotlib figure object

Raises:

ValueError – If the specified unit is unknown.

plot_phonon_doss(*doss, unit='cm-1', read_INS=False, atom_prj=[], element_prj=[], overlap=False, prj=[], gauss=0.0, frequency_range=[], dos_range=[], dos_label=None, dos_color=None, dos_linestyle=None, dos_linewidth=None, plot_freq0=True, freq0_color='tab:gray', freq0_linestyle='-', freq0_linewidth=1.0, title=None, figsize=[6.4, 4.8], legend='lower right', sharex=True, sharey=False, fontsize=14, **kwargs)

Plot phonon density of states.

Parameters:

*doss (PhononDOS|str) – phonon.PhononDOS object or the standard screen output (.out) files of CRYSTAL.
unit (str) – The unit of frequency. Can be ‘cm-1’ or ‘THz’.
read_INS (bool) – Read the inelastic neutron scattering spectra. For filename input only.
atom_prj (list) – Read the projections of atoms with specified labels. For filename input only.
element_prj (list) – Read projections of elements with specified conventional atomic numbers. For filename input only.
overlap (bool) – Plotting multiple projections into the same figure. Useful only if a single entry of doss is plotted. Otherwise projections from the same entry will be overlapped into the same subplot.
prj (list) – Index of selected projections, consistent with the first dimension of the doss, starting from 1. Effective for all the subplots.
gauss (float) – The standard deviation of Gaussian broadening, i.e. the $\sigma$ of $a\exp{\frac{(x-b)^{2}}{2\sigma^{2}}}$. ‘0’ for no Gaussian broadening. The length of data will be tripled. Valid only for data on the plot. Data saved in object is unchanged.
frequency_range (list) – 1*2 list of frequency range
dos_range (list) – 1*2 list of DOS range
dos_label (str|list) – Plot legend. If only one string is given, apply it to all plots. 1*nPrj plot legend otherwise. Effective for all the subplots.
dos_color (str|list) – Color of DOSS plots. If only one string is given, apply it to all plots. When overlap=True, 1*nPrj list of plot color. ‘None’ for default values (matplotlib Tableau Palette). Effective for all the subplots.
dos_linestyle (str|list) – Linestyle of DOSS plot. If only one string is given, apply it to all plots. When overlap=True, 1*nPrj list of line styles. ‘None’ for default values (‘-‘). Effective for all the subplots.
dos_linewidth (str|list) – Linewidth of DOSS plot. If only one number is given, apply it to all plots. When overlap=True, 1*nPrj list of line widthes. ‘None’ for default values (1.0). Effective for all the subplots.
plot_freq0 (bool) – Whether to plot 0 frequency line.
freq0_color (str) – Color of the 0 frequency line.
freq0_linestyle (str) – Line style of the 0 frequency line.
freq0_linewidth (float) – Width of the 0 frequency line.
title (str) – The title of the plot.
figsize (list) – The figure size specified as [width, height].
legend (str|None) –
Loc parameter passed to axes.legend() None for not adding legend.
sharex (bool) – Whether to share the x-axis among subplots.
sharey (bool) – Whether to share the y-axis among subplots.
fontsize (int) – Fontsize of the highest level title and axis labels.
**kwargs – Other arguments passed to Axes.plot() of band plots.

Returns:

fig (Figure) – Matplotlib figure object

plot_phonon_banddos(*data, unit='cm-1', q_overlap_tol=0.0001, read_INS=False, atom_prj=[], element_prj=[], k_label=[], dos_overlap=True, dos_prj=[], dos_gauss=0.0, frequency_range=[], k_range=[], dos_range=[], band_width=2, band_label=None, band_color=None, band_linestyle=None, band_linewidth=None, dos_label=None, dos_color=None, dos_linestyle=None, dos_linewidth=None, plot_freq0=True, freq0_color='tab:green', freq0_linestyle='-', freq0_linewidth=1.0, title=None, figsize=[6.4, 4.8], legend='lower right', fontsize=14, **kwargs)

Plot phonon band structure + dos for a single system, i.e., the bands and doss variables are not extendable.

Input arguments not in the list are consistent with plot_phonon_doss and plot_phonon_bands.

Parameters:

*data – Either 1 or 2 entries. For one enetry, it is the standard screen output (.out) file with both band and DOS, or PhononBandDOS object. For 2 entries, the first entry is bands of plot_phonon_bands and the second is doss of plot_phonon_doss.
dos_overlap (bool) – overlap of plot_phonon_doss. The user can either plot projections into the same subplot or into separate subplots.
dos_prj (list) – prj of plot_phonon_doss.
dos_gauss (float) – gauss of plot_phonon_doss.
band_width (int|float) – Relative width of band structure, times of the width of a DOS subplot.

Returns:

fig (Figure) – Matplotlib figure object

Raises:

ValueError – If the unit parameter is unknown.

plot_XRD(*xrd, option='LP', shift=10, label=None, color=None, linestyle=None, linewidth=None, theta_range=[], title=None, figsize=[6.4, 4.8], legend='upper left', fontsize=14, **kwargs)

Plot the XRD spectra of multiple systems into the same plot axes.

Note

The highest intensity is normalized to 100.

Parameters:

xrd (str|XRD) – File name or spectra.XRD objects. Extendable.
option (str) – File name inputs only ‘NC’ for no correction (The ‘INTENS’ col); ‘LD’ for Lorentz and polarization effects (‘INTENS-LP’) and ‘DW’ for LD with Debye-Waller thermal factors (‘INTENS-LP-DW’).
shift (float) – If multiple spectra are plotted, shifting them up by the given value. Shift length is the value after normalization.
label (list|str|None) – List of plot labels. ‘None’ for the default values (’# <number>’) and string for prefix the string before number. Otherwise should be a 1*nXRD list.
color (list|str|None) – If str, use the same color for all the plot lines. If 1*nXRD, use the color defined for every plot line. ‘None’ for default values (matplotlib Tableau Palette).
linestyle (list|str|None) – See explanations of color.
linewidth (list|float|None) – See explanations of color.
theta_range (list) – 1*2 list of theta range in degree.
title (str|None) – The title of the plot. ‘None’ for no title.
figsize (list) – Matplotlib figure size.
legend (str|None) – Location of legend. None for not adding legend.
fontsize (int) – Fontsize of the axis label and title.
**kwargs – Other parameters passed to matplotlib Axes.plot() method.

Returns:

fig (Figure) – Matplotlib figure.

plot_IR(*ir, unit='cm-1', option='LG', shift=0, label=None, color=None, linestyle=None, linewidth=None, x_range=[], title=None, figsize=[6.4, 4.8], legend='upper left', sharey=True, fontsize=14, **kwargs)

Plot the IR spectra of multiple systems into the same plot axes. For reflectance spectra, nDirection*1 plots are generated. All the input files must have the same symmetry.

Note

The highest intensity is normalized to 100.

Parameters:

ir (str|IR) – IRSPEC.DAT file name or spectra.IR objects. Extendable.
option (str) – Broadening method. ‘LG’ for Lorentzian-Gaussian, ‘V’ for Voigt, ‘RS’ for Rayleigh spherical particles, ‘RE’ for Rayleigh with elipsoid particles, ‘REFL’ for reflectance spectra with ‘LG’. Periodic systems only.
shift (float) – If multiple spectra are plotted, shifting them up by the given value. Shift length is the value after normalization.
label (list|str|None) – List of plot labels. ‘None’ for the default values (’# <number>’) and string for prefix the string before number. Otherwise should be a 1*nIR list.
color (list|str|None) – If str, use the same color for all the plot lines. If 1*nIR, use the color defined for every plot line. ‘None’ for default values (matplotlib Tableau Palette).
linestyle (list|str|None) – See explanations of color.
linewidth (list|float|None) – See explanations of color.
x_range (list) – 1*2 list of x axis range.
title (str|None) – The title of the plot. ‘None’ for no title.
figsize (list) – Matplotlib figure size.
legend (str|None) – Location of legend. None for not adding legend.
sharey (bool) – Whether to share the y-axis among subplots. Share x is enforced.
fontsize (int) – Fontsize of the axis label and title.
**kwargs – Other parameters passed to matplotlib Axes.plot() method.

Returns:

fig (Figure) – Matplotlib figure.

plot_Raman(*raman, option='poly', overlap=True, direction=['xx', 'xy', 'xz', 'yy', 'yz', 'zz'], shift=0, label=None, color=None, linestyle=None, linewidth=None, x_range=[], title=None, figsize=[6.4, 4.8], legend='upper left', sharey=True, fontsize=14, **kwargs)

Plot the Raman spectra of multiple systems into the same plot axes.

Available options:

‘tot’: Plot total raman spectra only. Plots with a single panel is generated.
‘poly’: Plot total, parallel and perpendicular spectra into 3 subplots.
‘single’: Plot single crystal spectra of specified directions into subplots.

Note

The highest intensity is normalized to 100.

Parameters:

raman (str|Raman) – RAMSPEC.DAT file name or spectra.Raman objects. Extendable.
option (str) – ‘tot’, ‘poly’ or ‘single’, see above.
overlap (bool) – If more than 1 inequivalent directions exists, whether to plot spectra into the same plot or into subplots.
direction (list|str) – ``option=’single’`` only Specify the directions of single crystal spectra to plot.
shift (float) – If multiple spectra are plotted, shifting them up by the given value. Shift length is the value after normalization.
label (list|str|None) – List of plot labels. ‘None’ for the default values (’# <number>’) and string for prefix the string before number. Otherwise should be a 1*nRaman list.
color (list|str|None) – If str, use the same color for all the plot lines. If 1*nRaman, use the color defined for every plot line. ‘None’ for default values (matplotlib Tableau Palette).
linestyle (list|str|None) – See explanations of color.
linewidth (list|float|None) – See explanations of color.
x_range (list) – 1*2 list of x axis range.
title (str|None) – The title of the plot. ‘None’ for no title.
figsize (list) – Matplotlib figure size.
legend (str|None) – Location of legend. None for not adding legend.
sharey (bool) – Whether to share the y-axis among subplots. Share x is enforced.
fontsize (int) – Fontsize of the axis label and title.
**kwargs – Other parameters passed to matplotlib Axes.plot() method.

Returns:

fig (Figure) – Matplotlib figure.

plot_cry_spec(transitions, typeS, components=False, bwidth=5, stdev=3, eta=0.5, fmin=None, fmax=None, ylim=None, savefig=False, dpi=300, filetype='png', exp_spec=None, sep=';', show=True, export_csv=False, label=None, xlabel='Wavenumber [cm$^{-1}$]', ylabel='Intensity [arb. u.]', linewidth=2.0, padd=100, fontsize=12, style=None, compstyle=None, nopadding=False, figsize=(16, 6))

Note

This is not for the released feature of CRYSTAL23 v1.0.1

This function enables the simulation of vibrational spectra based on a 2D NumPy array containing a list of transition frequencies and the corresponding intensities. The code allows users to model spectral broadening according to various profiles (Gaussian, Lorentzian, pseudo-Voigt), or zero broadening (Dirac deltas-like lines). Please, note that by turning the optional argument ‘component’ to True you can additionally plot contributions arising from each transition.

Parameters:

transitions (float|numpy.ndarray) – Array containing transition frequencies
intensities ((axis=0) and corresponding)
typeS (str) – String specifying the spectral profile: ‘bars’,
'lorentz'
'gauss'
'pvoigt'.
components (bool, optional) – Whether to plot contributions arising from
transition (each)
bwidth (float, optional) – Half-width at half-maximum of the Lorentzian
profile (default is 0.5)
stdev (float, optional) – Standard deviation of the Gaussian profile
5). ((default is)
eta (float, optional) – Fraction of Lorentzian character in pseudo-Voigt
profile
fmin (float, optional) – Minimum frequency.
fmax (float, optional) – Maximum frequency.
ylim (float, optional) – Maximum intensity.
savefig (bool, optional) – Whether to save the figure (default is False).
dpi (float, optional) – Dots per inches (default is 300).
filetype (str, optional) – File extension (default is ‘png’).
show (bool, optional) – Whether to show the figure (default is True).
export_csv (bool, optional) – Whether to save plot in csv format (default is
False).
xlabel (str, optional) – x-axis label (default is ‘Wavenumber [cm$^{-1}$]’).
ylabel (str, optional) – y-axis label (default is ‘Intensity [arb. u.]’).
linewidth (float) – Linewidth (default is 2.0).
padd (float, optional) – left- and right- hand side padding expressed in the
x-axis (same unit of the quantity reported in)
fontsize (integer, optional) – Fontsize (default is 12).
style (str, optional) – String specifying Matplotlib style.
compstyle (str|list, optional) – List containing Matplotlib styles to plot
component. (each)
nopadding (bool, optional) – Whether to remove padding (default is False).
figsize (real|list, optional) – List of two numbers specifying the aspect
figure (ratio of the)

Returns:

None

plot_cry_spec_multi(files, typeS, components=False, bwidth=5, stdev=3, eta=0.5, fmin=None, fmax=None, ylim=None, savefig=False, dpi=300, filetype='png', label=None, xlabel='Wavenumber [cm$^{-1}$]', ylabel='Instensity [arb. u.]', linewidth=2.0, padd=100, fontsize=12, style=None, nopadding=False, figsize=(16, 6))

Note

This is not for the released feature of CRYSTAL23 v1.0.1

This function is a wrapper for plot_spec function, enablng the simulation of many vibrational spectra coming from a list of NumPy array.

Parameters:

transitions (float|numpy.ndarray) – Array containing transition frequencies
intensities ((axis=0) and corresponding)
typeS (str) – String specifying the spectral profile: ‘bars’,
'lorentz'
'gauss'
'pvoigt'.
components (bool, optional) – Whether to plot contributions arising from
transition (each)
bwidth (float, optional) – Half-width at half-maximum of the Lorentzian
profile (default is 0.5)
stdev (float, optional) – Standard deviation of the Gaussian profile
5). ((default is)
eta (float, optional) – Fraction of Lorentzian character in pseudo-Voigt
profile
fmin (float, optional) – Minimum frequency.
fmax (float, optional) – Maximum frequency.
ylim (float, optional) – Maximum intensity.
savefig (bool, optional) – Whether to save the figure (default is False).
dpi (float, optional) – Dots per inches (default is 300).
filetype (str, optional) – File extension (default is ‘png’).
xlabel (str, optional) – x-axis label (default is ‘Wavenumber [cm$^{-1}$]’).
ylabel (str, optional) – y-axis label (default is ‘Intensity [arb. u.]’).
linewidth (float) – Linewidth (default is 2.0).
padd (float, optional) – left- and right- hand side padding expressed in the
x-axis (same unit of the quantity reported in)
fontsize (integer, optional) – Fontsize (default is 12).
style (str, optional) – String specifying Matplotlib style.
nopadding (bool, optional) – Whether to remove padding (default is False).
figsize (real|list, optional) – List of two numbers specifying the aspect
figure (ratio of the)

Returns:

None

plot_cry_xrd(xrd_obj): Deprecated. Use plot_XRD.

plot_cry_irspec(irspec, x_unit='cm-1', y_mode='LG', figsize=None, linestyle='-', linewidth=1.5, color='tab:blue', freq_range=None, int_range=None, label=None): Deprecated. Use plot_IR.

plot_cry_ramspec(ramspec, y_mode='total', figsize=None, linestyle='-', linewidth=1.5, color='tab:blue', freq_range=None, int_range=None, label=None): Deprecated. Use plot_Raman.

plot_cry_ela(choose, ndeg, *args, dpi=200, filetype='.png', transparency=False): Deprecated. Use plot_elastics3D.

plot_vecfield2D_m(header, dens, quivscale, name='MAG', levels=150, dpi=400): Deprecated and incompatible with new functions. Give error.

plot_vecfield2D_j(header, dens, quivscale, name='SC', levels=150, dpi=400): Deprecated and incompatible with new functions. Give error.

plot_vecfield2D_J(header, dens_JX, dens_JY, dens_JZ, quivscale, name='SCD', levels=150, dpi=400): Deprecated and incompatible with new functions. Give error.

plot_electron_band(bands, unit='eV', k_labels=None, mode='single', not_scaled=False, energy_range=None, k_range=None, color='blue', labels=None, linestl='-', linewidth=1, fermi='forestgreen', fermiwidth=1.5, fermialpha=1, title=None, figsize=None, scheme=None, sharex=True, sharey=True, fontsize=12): Deprecated. Use plot_electron_bands.

plot_cry_band(bands, k_labels=[], energy_range=[], title=None, not_scaled=True, mode='single', linestl='-', linewidth=1, color='blue', fermi='forestgreen', k_range=[], labels=None, figsize=[6.4, 4.8], scheme=None, sharex=True, sharey=True, fermiwidth=1.5, fermialpha=1, fontsize=12): Deprecated. Use plot_electron_bands.

plot_electron_dos(doss, unit='eV', beta='up', overlap=False, prj=None, energy_range=None, dos_range=None, color='blue', labels=None, linestl=None, linewidth=1, fermi='forestgreen', title=None, figsize=None): Deprecated. Use plot_electron_doss.

plot_cry_doss(doss, color='blue', fermi='forestgreen', overlap=False, labels=None, figsize=[6.4, 4.8], linestl=None, linewidth=1.0, title=None, beta='down', energy_range=[], dos_range=[], prj=[]): Deprecated. Use plot_electron_doss.

plot_cry_es(bands, doss, k_labels=[], color_bd='blue', color_doss='blue', fermi='forestgreen', energy_range=[], linestl_bd=None, linestl_doss=None, linewidth=1.0, prj=[], figsize=[6.4, 4.8], labels=None, dos_range=[], title=None, dos_beta='down'): Deprecated. Use plot_electron_doss.

plot_dens_ECHG(obj_echg, unit='Angstrom', xticks=5, yticks=5, cmap_max=None, cmap_min=None): Deprecated. Use plot_ECHG.

plot_spin_ECHG(obj_echg, unit='Angstrom', levels=150, xticks=5, yticks=5, cmap_max=None, cmap_min=None): Deprecated. Use plot_ECHG.

plot_cry_contour(contour_obj): Deprecated. Use plot_topond2D.

plot_cry_contour_differences(contour_obj, contour_obj_ref): Deprecated. Use plot_topond2D.

plot_cry_seebeck_potential(seebeck_obj): Deprecated. Use plot_transport_tensor.

plot_cry_seebeck_carrier(seebeck_obj): Deprecated. Use plot_transport_tensor.

plot_cry_multiseebeck(*seebeck): Deprecated. Use plot_transport_tensor.

plot_cry_sigma_potential(sigma_obj): Deprecated. Use plot_transport_tensor.

plot_cry_sigma_carrier(sigma_obj): Deprecated. Use plot_transport_tensor.

plot_cry_multisigma(*sigma): Deprecated. Use plot_transport_tensor.

plot_cry_powerfactor_potential(seebeck_obj, sigma_obj): Deprecated. Use plot_transport_tensor.

plot_cry_powerfactor_carrier(seebeck_obj, sigma_obj): Deprecated. Use plot_transport_tensor.

plot_cry_zt(seebeck_obj, sigma_obj): Deprecated. Use plot_transport_tensor.

CRYSTALpytools.relativistics module

The module for ‘2c-SCF’, i.e., 2-component SCF, and relativistics.

class ChargeDensity(data, base, spin, dimen, struc=None, unit='Angstrom')

Bases: ChargeDensity

Same as electronics.ChargeDensity, the spin density. But its dimension is kept to be commensurate with other keywords of the ‘PROPS2COMP’ block.

Note

Its type attribute is ‘ECHG’ rather than ‘DENSITY’

classmethod from_file(file, output)

Generate a ChargeDensity object from CRYSTAL formatted output unit and standard screen output (mandatory).

Parameters:

file (str) – File name of fort.25 or CUBE (in development) files.
output (str) – Screen output of ‘properties’ calculation.

Returns:

cls (ChargeDensity)

class VectorField

Bases: object

The basic vector field object, containing a nY*nX*3 (nZ*nY*nX*3) data array for 2D (3D) fields. Call the property-specific child classes below in use. 3D methods under development.

plot_2D(levels=100, quiverplot=True, quiverscale=1.0, colorplot=True, colormap='jet', cbar_label=None, a_range=[], b_range=[], rectangle=False, edgeplot=False, x_ticks=5, y_ticks=5, figsize=[6.4, 4.8], fig=None, ax_index=None, **kwargs)

Plot 2D vector field.

3 styles are available:

quiverplot=True and colorplot=True: The color-filled contour
illustrates the norm of vectors. The black arrows indicates both the directions and norms of in-plane prjections.
quiverplot=True and colorplot=False: The arrows are colored
to indicate the directions and norms of in-plane prjections.
quiverplot=False and colorplot=True: The color-filled contour
illustrates the norm of vectors, similar to the 2D scalar map.

Parameters:

levels (int|array) – Set levels of colored contour/quiver plot. A number for linear scaled plot colors or an array for user-defined levels. 1D.
quiverplot (bool) – Plot 2D field of arrows.
quiverscale (float) – Tune the length of arrows. Useful only if quiverplot=True.
colorplot (bool) – Plot color-filled contour plots.
colormap (str) – Matplotlib colormap option. Useful only if colorplot=True.
cbar_label (str) – Label of colorbar. Useful only if colorplot=True.
a_range (list) – 1*2 range of $a$ axis (x, or BC) in fractional coordinate.
b_range (list) – 1*2 range of $b$ axis (x, or AB) in fractional coordinate.
rectangle (bool) – If $a, b$ are non-orthogonal, plot a rectangle region and reset $b$. If used together with b_range, that refers to the old $b$ (i.e., expansion first).
edgeplot (bool) – Whether to add cell edges represented by the original base vectors (not inflenced by a/b range or rectangle options).
x_ticks (int) – Number of ticks on x axis.
y_ticks (int) – Number of ticks on y axis.
figsize (list) – Matplotlib figure size. Note that axes aspects are fixed to be equal.
fig (Figure) – Developer Only, matplotlib Figure class.
ax_index (list[int]) – Developer Only, indices of axes in fig.axes.
**kwargs – Other arguments passed to axes.quiver() function to set arrow styles.

Returns:

fig (Figure) – Matplotlib Figure class.

class Magnetization(data, base, dimen, struc, unit='SI')

Bases: VectorField

The class for magnetization. Unit: ‘SI’ (length: $\AA$, magnetization: A/m).

Parameters:

data (array) – nY*nX*3 (nZ*nY*nX*3) array of magnetization vectors in 2D (3D) plane.
base (array) – 3*3 Cartesian coordinates of the 3 points defining vectors BA and BC (2D) or 3 base vectors (3D)
dimen (int) – Dimensionality of the plot.
struc (CStructure) – Extended Pymatgen Structure object.
unit (str) – In principle, should always be ‘SI’ (case insensitive).

classmethod from_file(file, output)

Generate a Magentization object from CRYSTAL formatted output unit and standard screen output (mandatory).

Parameters:

file (str) – File name of fort.25 or CUBE (in development) files.
output (str) – Screen output of ‘properties’ calculation.

Returns:

cls (Magnetization)

plot_2D(unit='SI', levels=100, quiverplot=True, quiverscale=1.0, colorplot=True, colormap='jet', cbar_label='default', a_range=[], b_range=[], rectangle=False, edgeplot=False, x_ticks=5, y_ticks=5, title='default', figsize=[6.4, 4.8], fig=None, ax_index=None, **kwargs)

Plot 2D magnetization field.

3 styles are available:

quiverplot=True and colorplot=True: The color-filled contour
illustrates the norm of vectors. The black arrows indicates both the directions and norms of in-plane prjections.
quiverplot=True and colorplot=False: The arrows are colored
to indicate the directions and norms of in-plane prjections.
quiverplot=False and colorplot=True: The color-filled contour
illustrates the norm of vectors, similar to the 2D scalar map.

Parameters:

unit (str) – Plot unit. ‘SI’ for $\AA$ and A/m. ‘a.u.’ for Bohr and a.u. magnetization.
levels (int|array) – Set levels of colored contour/quiver plot. A number for linear scaled plot colors or an array for user-defined levels. 1D.
quiverplot (bool) – Plot 2D field of arrows.
quiverscale (float) – Tune the length of arrows. Useful only if quiverplot=True.
colorplot (bool) – Plot color-filled contour plots.
colormap (str) – Matplotlib colormap option. Useful only if colorplot=True.
cbar_label (str|None) – Label of colorbar. ‘default’ for unit. ‘None’ for no label. Useful only if colorplot=True.
a_range (list) – 1*2 range of $a$ axis (x, or BC) in fractional coordinate.
b_range (list) – 1*2 range of $b$ axis (x, or AB) in fractional coordinate.
rectangle (bool) – If $a, b$ are non-orthogonal, plot a rectangle region and reset $b$. If used together with b_range, that refers to the old $b$ (i.e., expansion first).
edgeplot (bool) – Whether to add cell edges represented by the original base vectors (not inflenced by a/b range or rectangle options).
x_ticks (int) – Number of ticks on x axis.
y_ticks (int) – Number of ticks on y axis.
title (str|None) – Plot title. ‘default’ for proeprty plotted. ‘None’ for no title.
figsize (list) – Matplotlib figure size. Note that axes aspects are fixed to be equal.
fig (Figure) – Developer Only, matplotlib Figure class.
ax_index (list[int]) – Developer Only, indices of axes in fig.axes.
**kwargs – Other arguments passed to axes.quiver() function to set arrow styles.

Returns:

fig (Figure) – Matplotlib Figure class.

class OrbitalCurrentDensity(data, base, dimen, struc, unit='SI')

Bases: VectorField

The class for orbital current density. Unit: ‘SI’ (length: $\AA$, orbital current density: A/m $^{2}$).

Parameters:

data (array) – nY*nX*3 (nZ*nY*nX*3) array of orbnital current vectors in 2D (3D) plane.
base (array) – 3*3 Cartesian coordinates of the 3 points defining vectors BA and BC (2D) or 3 base vectors (3D)
dimen (int) – Dimensionality of the plot.
struc (CStructure) – Extended Pymatgen Structure object.
unit (str) – In principle, should always be ‘SI’ (case insensitive).

classmethod from_file(file, output)

Generate a OrbitalCurrentDensity object from CRYSTAL formatted output unit and standard screen output (mandatory).

Parameters:

file (str) – File name of fort.25 or CUBE (in development) files.
output (str) – Screen output of ‘properties’ calculation.

Returns:

cls (OrbitalCurrentDensity)

plot_2D(unit='SI', levels=100, quiverplot=True, quiverscale=1.0, colorplot=True, colormap='jet', cbar_label='default', a_range=[], b_range=[], rectangle=False, edgeplot=False, x_ticks=5, y_ticks=5, title='default', figsize=[6.4, 4.8], fig=None, ax_index=None, **kwargs)

Plot 2D orbital current density field.

3 styles are available:

quiverplot=True and colorplot=True: The color-filled contour
illustrates the norm of vectors. The black arrows indicates both the directions and norms of in-plane prjections.
quiverplot=True and colorplot=False: The arrows are colored
to indicate the directions and norms of in-plane prjections.
quiverplot=False and colorplot=True: The color-filled contour
illustrates the norm of vectors, similar to the 2D scalar map.

Parameters:

unit (str) – Plot unit. ‘SI’ for $\AA$ and A/m $^{2}$. ‘a.u.’ for Bohr and a.u. current density.
levels (int|array) – Set levels of colored contour/quiver plot. A number for linear scaled plot colors or an array for user-defined levels. 1D.
quiverplot (bool) – Plot 2D field of arrows.
quiverscale (float) – Tune the length of arrows. Useful only if quiverplot=True.
colorplot (bool) – Plot color-filled contour plots.
colormap (str) – Matplotlib colormap option. Useful only if colorplot=True.
cbar_label (str|None) – Label of colorbar. ‘default’ for unit. ‘None’ for no label. Useful only if colorplot=True.
a_range (list) – 1*2 range of $a$ axis (x, or BC) in fractional coordinate.
b_range (list) – 1*2 range of $b$ axis (x, or AB) in fractional coordinate.
rectangle (bool) – If $a, b$ are non-orthogonal, plot a rectangle region and reset $b$. If used together with b_range, that refers to the old $b$ (i.e., expansion first).
edgeplot (bool) – Whether to add cell edges represented by the original base vectors (not inflenced by a/b range or rectangle options).
x_ticks (int) – Number of ticks on x axis.
y_ticks (int) – Number of ticks on y axis.
title (str|None) – Plot title. ‘default’ for proeprty plotted. ‘None’ for no title.
figsize (list) – Matplotlib figure size. Note that axes aspects are fixed to be equal.
fig (Figure) – Developer Only, matplotlib Figure class.
ax_index (list[int]) – Developer Only, indices of axes in fig.axes.
**kwargs – Other arguments passed to axes.quiver() function to set arrow styles.

Returns:

fig (Figure) – Matplotlib Figure class.

class SpinCurrentDensity(data_x, data_y, data_z, base, dimen, struc, unit='SI')

Bases: VectorField

The class for spin current density. Unit: ‘SI’ (length: $\AA$, spin current density: A/m $^{2}$).

Parameters:

data_x (array) – nY*nX*3 (nZ*nY*nX*3) array of spin current vectors $J^{x}$ in 2D (3D) plane.
data_y (array) – nY*nX*3 (nZ*nY*nX*3) array of spin current vectors $J^{y}$ in 2D (3D) plane.
data_z (array) – nY*nX*3 (nZ*nY*nX*3) array of spin current vectors $J^{z}$ in 2D (3D) plane.
base (array) – 3*3 Cartesian coordinates of the 3 points defining vectors BA and BC (2D) or 3 base vectors (3D)
dimen (int) – Dimensionality of the plot.
struc (CStructure) – Extended Pymatgen Structure object.
unit (str) – In principle, should always be ‘SI’ (case insensitive).

classmethod from_file(file, output)

Generate a SpinCurrentDensity object from CRYSTAL formatted output unit and standard screen output (mandatory).

Parameters:

file (str) – File name of fort.25 or CUBE (in development) files.
output (str) – Screen output of ‘properties’ calculation.

Returns:

cls (SpinCurrentDensity)

plot_2D(unit='SI', direction=['x', 'y', 'z'], levels=100, quiverplot=True, quiverscale=1.0, colorplot=True, colormap='jet', cbar_label='default', a_range=[], b_range=[], rectangle=False, edgeplot=False, x_ticks=5, y_ticks=5, title='default', figsize=[6.4, 4.8], fig=None, ax_index=None, **kwargs)

Plot 2D orbital current density field.

3 styles are available:

quiverplot=True and colorplot=True: The color-filled contour
illustrates the norm of vectors. The black arrows indicates both the directions and norms of in-plane prjections.
quiverplot=True and colorplot=False: The arrows are colored
to indicate the directions and norms of in-plane prjections.
quiverplot=False and colorplot=True: The color-filled contour
illustrates the norm of vectors, similar to the 2D scalar map.

Parameters:

unit (str) – Plot unit. ‘SI’ for $\AA$ and A/m $^{2}$. ‘a.u.’ for Bohr and a.u. current density.
direction (str|list) – Direction of spin-current to plot, in ‘x’, ‘y’ or ‘z’.
levels (int|array) – Set levels of colored contour/quiver plot. A number for linear scaled plot colors or an array for user-defined levels. 1D.
quiverplot (bool) – Plot 2D field of arrows.
quiverscale (float) – Tune the length of arrows. Useful only if quiverplot=True.
colorplot (bool) – Plot color-filled contour plots.
colormap (str) – Matplotlib colormap option. Useful only if colorplot=True.
cbar_label (str|None) – Label of colorbar. ‘default’ for unit. ‘None’ for no label. Useful only if colorplot=True.
a_range (list) – 1*2 range of $a$ axis (x, or BC) in fractional coordinate.
b_range (list) – 1*2 range of $b$ axis (x, or AB) in fractional coordinate.
rectangle (bool) – If $a, b$ are non-orthogonal, plot a rectangle region and reset $b$. If used together with b_range, that refers to the old $b$ (i.e., expansion first).
edgeplot (bool) – Whether to add cell edges represented by the original base vectors (not inflenced by a/b range or rectangle options).
x_ticks (int) – Number of ticks on x axis.
y_ticks (int) – Number of ticks on y axis.
title (str|None) – Plot title. ‘default’ for proeprty plotted. ‘None’ for no title.
figsize (list) – Matplotlib figure size. Note that axes aspects are fixed to be equal.
fig (Figure) – Developer Only, matplotlib Figure class.
ax_index (list[int]) – Developer Only, indices of axes in fig.axes. Must be consistent with length of direction.
**kwargs – Other arguments passed to axes.quiver() function to set arrow styles.

Returns:

fig (Figure) – Matplotlib Figure class.

CRYSTALpytools.spectra module

Classes and methods for spectra.

class XRD(theta, spectra)

Bases: object

The class for X-ray diffraction spectra.

Parameters:

theta (array) – 2:math:`theta` values in degree.
spectra (array) – Spectra intensities.

classmethod from_file(output, option='LP')

Read XRD spectra from the standard screen output of properties calculation.

Parameters:

output (str) – Output filename.
option (str) – ‘NC’ for no correction (The ‘INTENS’ col); ‘LP’ for Lorentz and polarization effects (‘INTENS-LP’) and ‘DW’ for LP with Debye-Waller thermal factors (‘INTENS-LP-DW’).

Returns:

cls (XRD)

plot(theta_range=[], normalize=True, title=None, figsize=[6.4, 4.8], fontsize=14, **kwargs)

Plot XRD spectra.

Parameters:

theta_range (list) – 1*2 list of theta range in degree.
normalize (bool) – Normalize the maximum intensity to 100.
title (str|None) – The title of the plot. ‘None’ for no title.
figsize (list) – Matplotlib figure size.
fontsize (int) – Fontsize of the axis label and title.
**kwargs – Other parameters passed to matplotlib Axes.plot() method.

Returns:

fig (Figure) – Matplotlib figure.

class IR(freq, absorb, reflec, type, unit='cm-1')

Bases: object

The class for infrared spectrum. Unit: in principle, should always in ‘cm $^{-1}$’.

Parameters:

freq (array) – Frequencies. Must be commensurate with unit.
absorb (array) – Absorbance spectrum, nType*nFreq array.
reflec (array) – Reflectance spectrum along inequivalent polarization directions (periodic systems only), nDir*nFreq array.
type (str) – ‘molecule’ or ‘crystal’
unit (str) – ‘cm-1’ or ‘THz’.

classmethod from_file(specfile, output=None)

Generate an IR object from output and ‘IRSPEC.DAT’ files of CRYSTAL.

Parameters:: specfile (str) – The ‘IRSPEC.DAT’ file.
Returns:: cls (IR)

plot(unit='cm-1', option='LG', normalize=True, REFL_overlap=True, shift=0, label=None, color=None, linestyle=None, linewidth=None, x_range=[], title=None, figsize=[6.4, 4.8], legend='upper left', sharey=True, fontsize=14, fig=None, **kwargs)

Plot IR spectra into the same axis.

Parameters:

unit (str) – X axis unit. ‘cm $^{-1}$’ or ‘nm’.
option (str) – Broadening method. ‘LG’ for Lorentzian-Gaussian, ‘V’ for Voigt, ‘RS’ for Rayleigh spherical particles, ‘RE’ for Rayleigh with elipsoid particles, ‘REFL’ for reflectance spectra with ‘LG’. Periodic systems only.
normalize (bool) – Normalize the maximum intensity to 100.
REFL_overlap (bool) – For ``option=’REFL’`` only If more than 1 inequivalent directions exists, whether to plot REFL data into the same plot or into subplots.
shift (float) – For ``option=’REFL’`` and ``REFL_overlap=False`` only If multiple spectra are plotted, shift them up by the given value. Shift length is the value after normalization if normalize=True.
label (list|str|None) – For ``option=’REFL’`` only List of plot labels. ‘None’ for the default values (’# <number>’) and string for prefix the string before number. Otherwise should be a 1*nPlot list.
color (list|str|None) – For ``option=’REFL’`` only If str, use the same color for all the plot lines. If 1*nPlot, use the color defined for every plot line. ‘None’ for default values (matplotlib Tableau Palette).
linestyle (list|str|None) – For ``option=’REFL’`` only See explanations of color.
linewidth (list|float|None) – For ``option=’REFL’`` only See explanations of color.
x_range (list) – 1*2 list of x axis range.
title (str|None) – The title of the plot. ‘None’ for no title.
figsize (list) – Matplotlib figure size.
legend (str|None) – Location of legend. None for not adding legend.
sharey (bool) – Whether to share the y-axis among subplots. Share x is enforced.
fontsize (int) – Fontsize of the axis label and title.
fig (Figure) – Developer Only Matplotlib figure object.
**kwargs – Other parameters passed to matplotlib Axes.plot() method.

Returns:

fig (Figure) – Matplotlib figure.

class Raman(freq, poly, single, unit='cm-1')

Bases: object

The class for Raman spectrum. Unit: in principle, should always in ‘cm $^{-1}$’.

Parameters:

freq (array) – Frequencies. Must be commensurate with unit.
poly (array) – Polycrystalline isotropic spectrum, 3*nFreq array for total, parallel and perpendicular directions.
single (array) – Single crystal spectrum, 6*nFreq array for xx, xy, xz, yy, yz, zz directions.
unit (str) – ‘cm-1’ or ‘THz’.

classmethod from_file(specfile, output=None)

Generate an Raman object from output and ‘RAMSPEC.DAT’ files of CRYSTAL.

Parameters:: specfile (str) – The ‘RAMSPEC.DAT’ file.
Returns:: cls (IR)

plot(option='poly', normalize=True, overlap=True, direction=['xx', 'xy', 'xz', 'yy', 'yz', 'zz'], shift=0, label=None, color=None, linestyle=None, linewidth=None, x_range=[], title=None, figsize=[6.4, 4.8], legend='upper left', sharey=True, fontsize=14, fig=None, ax_index=None, **kwargs)

Plot Raman spectra into the same axis.

Parameters:

option (str) – ‘tot’, ‘poly’ or ‘single’. ‘tot’ plots the total raman spectrum of polycrystalline material. ‘poly’ plots total, parallel and perpendicular spectra. ‘single’ plots spectra along xx, xy, xz, yy, yz, zz directions.
normalize (bool) – Normalize the maximum intensity to 100.
overlap (bool) – If more than 1 inequivalent directions exists, whether to plot spectra into the same plot or into subplots.
direction (list|str) – ``option=’single’`` only Specify the directions of single crystal spectra to plot.
shift (float) – If multiple spectra are plotted, shifting them up by the given value.
label (list|str|None) – List of plot labels. ‘None’ for the default values (‘total’, ‘parallel’ series or ‘xx’ ‘yy’ series) and string for prefix the string before default values. Otherwise should be a 1*nPlot list.
color (list|str|None) – If str, use the same color for all the plot lines. If 1*nPlot, use the color defined for every plot line. ‘None’ for default values (matplotlib Tableau Palette).
linestyle (list|str|None) – See explanations of color.
linewidth (list|float|None) – See explanations of color.
x_range (list) – 1*2 list of x axis range.
title (str|None) – The title of the plot. ‘None’ for no title.
figsize (list) – Matplotlib figure size.
legend (str|None) – Location of legend. None for not adding legend.
sharey (bool) – Whether to share the y-axis among subplots. Share x is enforced.
fontsize (int) – Fontsize of the axis label and title.
fig (Figure) – Developer Only Matplotlib figure object.
ax_index (int) – Developer Only Index of the Axes object in fig.
**kwargs – Other parameters passed to matplotlib Axes.plot() method.

Returns:

fig (Figure) – Matplotlib figure.

CRYSTALpytools.thermodynamics module

A post-processing module for DFT lattice dynamics by harmonic and quasiharmonic approximations (HA/QHA).

class Mode(rank=0, frequency=[], volume=[], eigenvector=[], symmetry='')

Bases: object

Defines a vibrational mode and do analysis per mode.

Parameters:

rank (int) – The rank of the mode object, from 1.
frequency (array[float]) – Frequencies of the mode (Ncalc*1). Unit: THz. Note: NOT angular frequency, which is frequency*2pi.
volume (array[float]) – Lattice volumes of harmonic calculations (Ncalc*1). Unit: Angstrom^3
eigenvector (array[float]) – Corresponding normalized eigenvectors (Ncalc*Natom*3).
symmetry (str) – Irreducible representations in Mulliken symbols.

get_zp_energy()

Get the zero-point energy of a single mode. ncalc = 1 only.

\[E^{zp}_{i,\mathbf{q}}=\frac{1}{2}\hbar\omega_{i,\mathbf{q}}\]

Returns:: self.zp_energy (float) – Zero-point energy. Unit: KJ/mol

get_u_vib(temperature)

Get the vibration contribution to internal energy (including zero-point energy) of a single mode. ncalc = 1 only.

\[U^{vib}_{i,\mathbf{q}}\left(T\right)=E^{zp}_{i,\mathbf{q}}+ \frac{\hbar\omega_{i,\mathbf{q}}}{\exp{\left( \frac{\hbar\omega_{i,\mathbf{q}}}{k_{B}T} \right)}-1}\]

Parameters:: temperature (float) – Temperature where the quantity is computed. Unit: K
Returns:: self.u_vib (float) – Vibration contribution to internal energy. Unit: KJ/mol

get_entropy(temperature)

Get the entropy of a single mode. ncalc = 1 only.

\[S_{i,\mathbf{q}}\left(T\right)=k_{B}\left\{ \frac{\hbar\omega_{i,\mathbf{q}}}{k_{B}T\left[ \exp{\left( \frac{\hbar\omega_{i,\mathbf{q}}}{k_{B}T} \right)}-1 \right]}-\ln{\left[ 1-\exp{\left( -\frac{\hbar\omega_{i,\mathbf{q}}}{k_{B}T} \right)} \right]} \right\}\]

Parameters:: temperature (float) – Unit: K
Returns:: self.entropy (float) – Entropy. Unit: J/mol*K

get_c_v(temperature)

Get the constant volume specific heat of a single mode. ncalc = 1 only.

\[C^{V}_{i,\mathbf{q}}= \frac{\left(\hbar\omega_{i,\mathbf{q}}\right)^{2}}{k_{B}T^{2}} \frac{\exp{ \left( \frac{\hbar\omega_{i,\mathbf{q}}}{k_{B}T} \right)} }{\left[ \exp{\left( \frac{\hbar\omega_{i,\mathbf{q}}}{k_{B}T} \right)-1} \right]^{2} }\]

Parameters:: temperature (float) – Unit: K
Returns:: self.c_v (float) – Constant volume specific heat. Unit: J/mol*K

polynomial_fit(order)

Fit phonon frequency as the polynomial function of volume. ncalc > 1 only.

Note

To improve the accuracy of fittings, $\Delta\omega(\Delta V)$ is fitted as a polynomial function without the constant term.

$\Delta V=V-V_{min}$ is used so HA phonons of the most compact structure is kept. See ‘FIXINDEX’ keyword in CRYSTAL manual for further information.

Parameters:

order (array[int]) – Orders of polynomials.

Returns:

self.poly_fit (Dict[int, NumPy Polynomial]) – Key - orders of power, Value - fitted NumPy polynomials
self.poly_fit_rsquare (Dict[int, float]) – Key - orders of power, Value - goodness of fittings, characterized by R^2.

get_gruneisen(order, volume)

Return to mode Grüneisen parameter. ncalc > 1 only.

\[\gamma = -\frac{V}{\omega(V)}\frac{\partial\omega}{\partial V}\]

Note

order is used only for the dict key. In principle, order=1 for the Grüneisen model (see QHA.thermo_gruneisen()). Use other order numbers for frequencies fitted by QHA.thermo_freq().

Parameters:

order (int | list) – See polynomial_fit
volume (float | array) – Typically the equilibrium volume

Returns:

self.gruneisen (dict) – Key, order; Value, Gruneisen parameter

class Harmonic(temperature=[], pressure=[], filename=None, autocalc=True)

Bases: object

A class for harmonic phonon calclulations. It can be parameterized from a CRYSTAL output file, phonopy ouput file or by setting all the information (usually for QHA).

Parameters:

temperature (array|float) – Optional Temperatures where thermodynamic properties are computed. Unit: K
pressure (array|float) – Optional Pressures where thermodyanmic properties are calculated. Unit: GPa
filename (str | None) – Name of the printed-out file. If None, do not print out file.
autocalc (bool) – Automatically launch calculations.

Temperatures and pressures can also be defined by self.thermodynamics, whose entries always cover the entries here.

Phonon dispersions are forced to be summed if the automatic scheme (autocalc=True) is launched. To get verbose outputs, call self.thermodynamics() first and then call self.print_results().

Usage:

ha = Harmonic(temperature=[0, 100, 200, 300], pressure=[0.,])
ha.from_file('harmonic_phonon.out')

from_file(output_name, read_eigvt=False, imaginary_tol=-0.0001, q_overlap_tol=0.0001, qha_index=0)

Generate the Harominc object from a HA output file. Imaginary modes and overlapped q points are forced to be cleaned.

Parameters:

output_name (str) – Name of the output file.
read_eigvt (bool) – Whether to read eigenvectors from output.
imaginary_tol (float) – The threshold of negative frequencies.
q_overlap_tol (float) – The threshold of overlapping points, defined as the 2nd norm of the difference of fractional q vectors
qha_index (int) – If the input is a QHA file, specify the index of calculation to read (from 0).

Returns:

self (Harmonic) – Attributes listed below.
structure (CStructure) – Extended Pymatgen structure class. The supercell expanded by keyword ‘SCELPHONO’ is reduced.
natom (int) – Number of atoms in the reduced cell.
volume (float) – Volume of the reduced cell. Unit: $\AA^{3}$
edft (float) – Internal energy. Unit: kJ/mol
nqpoint (int) – Number of q points
qpoint (list) – nQpoint*2 list. The first element is 1*3 array of fractional coordinates in reciprocal space and the second is its weight.
nmode (array[int]) – Number of modes at every q point.
mode (list[Mode]) – List of mode objects at all the qpoints.

Raises:

ValueError – If a QHA output file is read.

from_phonopy(phono_yaml, struc_yaml=None, edft=None, scale=1.0, imaginary_tol=0.0001, q_overlap_tol=0.0001, q_id=None, q_coord=None)

Build a Harmonic object from Phonopy ‘band.yaml’ or ‘qpoints.yaml’ file.

Note

Mode symmetry and eigenvector are currently not available.

Note

q_id and q_coord should not be set simultaneously. If set, q_id takes priority and q_coord is ignored. If both are none, all the points will be read.

Parameters:

phono_yaml (str) – Phonopy band.yaml or qpoint.yaml file
struc_yaml (str) – Phonopy phonopy.yaml or phonopy_disp.yaml file. Needed only if a qpoint.yaml file is read.
edft (float) – DFT energy. Unit: kJ/mol
scale (float) – Scaling factor of phonon frequency.
imaginary_tol (float) – The threshold of negative frequencies.
q_overlap_tol (float) – The threshold of overlapping points, defined as the 2nd norm of the difference of fractional q vectors
q_id (list[int]) – Specify the id (from 0) of q points to be read. nqpoint*1 list.
q_coord (list[list]) – Specify the coordinates of q points to be read. nqpoint*3 list.

Returns:

self (Harmonic) – Attributes listed below.
structure (CStructure) – Extended Pymatgen structure class. The supercell expanded by keyword ‘SCELPHONO’ is reduced.
natom (int) – Number of atoms in the reduced cell.
volume (float) – Volume of the reduced cell. Unit: $\AA^{3}$.
edft (float) – Internal energy. Unit: kJ/mol
nqpoint (int) – Number of q points.
qpoint (list) – nQpoint*2 list. The first element is 1*3 array of fractional coordinates in reciprocal space and the second is its weight.
nmode (array[int]) – Number of modes at every q point.
mode (list[Mode]) – List of mode objects at all the qpoints.

Raises:

Exception – If the length unit in yaml file is neither ‘au’ nor ‘angstrom’.
Exception – If q point is not found.

from_frequency(edft, qpoint, frequency, eigenvector, symmetry, structure=None, natom=None, volume=None, imaginary_tol=0.0001, q_overlap_tol=0.0001, ignore_natom=False)

Generate a Harmonic object by specifying frequency and eigenvector. Imaginary modes and overlapped q points are forced to be cleaned.

Parameters:

edft (float) – Electron total energy in kJ/mol.
qpoint (list[list[array[float], float]]) – nQpoint*2 list of: 1*3 array of fractional coordinate and weight of qpoint.
frequency (array[float]) – Array of frequencies. Unit: THz
eigenvector (array[float]) – Normalized eigenvectors to 1.
symmetry (array[str]) – Irreducible representations in Mulliken symbols.
structure (CStructure) – Extended Pymatgen structure class. The supercell expanded by keyword ‘SCELPHONO’ is reduced.
natom (int) – Number of atoms in the reduced cell.
volume (float) – Volume of the reduced cell. Unit: $\AA^{3}$
imaginary_tol (float) – The threshold of negative frequencies.
q_overlap_tol (float) – The threshold of overlapping points, defined as the 2nd norm of the difference of fractional q vectors
ignore_natom (bool) – Developer only.

Note

The user should define either structure or natom + volume.

Returns:

self (Harmonic) – Attributes see from_file() and from_phonopy.

Raises:

AttributeError – If computational data is stored in the object.
ValueError – If neither of the 2 available options are defined.

thermodynamics(sumphonon=True, **kwargs)

Calculate the thermodynamic properties (zp_energy, u_vib, entropy, c_v and Gibbs and Helmholtz free energy) of the HA system at all qpoints and the whole temperature/pressure range.

Other parameters are the sum of corresponding attributes of all the Mode objects. The Helmholtz and Gibbs free energies are defined as:

\[ \begin{align}\begin{aligned}F(p,V) = E_{DFT} + F_{vib}(T) = E_{DFT} + U_{vib}(T) - TS(T)\\G(p, V) = F + pV\end{aligned}\end{align} \]

Parameters:

temperature (array|float) – Optional Unit: K
pressure (array|float) – Optional Unit: GPa
sumphonon (bool) – Whether to sum up the phonon contributions across the sampled q points and take weighted-average.

Returns:

self (Harmonic) – Attributes listed below.
self.helmholtz (array) – nQpoint*nTemperature. Unit: KJ/mol
self.gibbs (array) – nQpoint*nPressure*nTemperature. Unit: KJ/mol
self.zp_energy (array) – Zero-point energy. 1*nQpoint. Unit: KJ/mol
self.u_vib (array) – Vibrational contribution to internal energy. nQpoint*nTemperature. Unit: KJ/mol
self.entropy (array) – nQpoint*nTemperature. Unit: J/mol*K
self.c_v (array) – Constant volume specific heat. nQpoint*nTemperature. Unit: J/mol*K

Note

If sumphonon = True, nqpoint = 1 but its dimension in attribute is kept for consistency.

Raises:: Exception – If temperature and pressure are defined neither here nor during initialization

write_HA_result()

class Quasi_harmonic(temperature=[], pressure=[], filename=None)

Bases: object

Generate and rearrange harmonic phonons, store the fitted, volume-dependent QHA phonon information and obtain the QHA thermodynamic properties.

Parameters:

temperature (array|float) – Unit: K
pressure (array|float) – Unit: GPa
filename (str) – Name of the output file. Valid if write_out = True.

Temperatures and pressures can also be defined by self.thermodynamics, whose entries always cover the entries here.

Usage:

qha = Quasi_harmonic()
qha.from_QHA_file('qha_phonon.out')
qha.thermo_freq(eos_method='birch_murnaghan', temperature=[0, 100, 200, 300], pressure=[0., 0.5, 1.]):

from_HA_files(*input_files, imaginary_tol=0.0001, q_overlap_tol=0.0001, mode_sort_tol=0.4)

Read data from individual HA calculation outputs. Imaginary modes and overlapped q points are forced to be cleaned.

Parameters:

*input_files (str) – Harmonic phonon output filenames. Extendable.
imaginary_tol (float) – The threshold of negative frequencies.
q_overlap_tol (float) – The threshold of overlapping points, defined as the 2nd norm of the difference of fractional q vectors
mode_sort_tol (float | None) – The threshold of close mode overlaps. If none, do not sort modes and eigenvector is not read.

Returns:

self (Quasi_harmonic) – New Attributes listed below
self.ncalc (int) – Number of HA phonon calculations.
self.combined_phonon (list[Harmonic]) – List of Harmonic objects.
self.combined_volume (list[float]) – Volumes. Unit: Angstrom^3
self.combined_edft (list[float]) – DFT total energies. Unit: KJ/mol
self.combined_mode (list[Mode]) – List of mode objects.

from_QHA_file(input_file, imaginary_tol=0.0001, q_overlap_tol=0.0001, mode_sort_tol=0.4)

Read data from a single QHA calculation at Gamma point. Imaginary modes and overlapped q points are forced to be cleaned.

Parameters:

input_file (str) – Only 1 QHA file is permitted.
imaginary_tol (float) – The threshold of negative frequencies.
q_overlap_tol (float) – The threshold of overlapping points, defined as the 2nd norm of the difference of fractional q vectors
mode_sort_tol (float | None) – The threshold of close mode overlaps. If none, do not sort modes.

Returned attributes are consistent with Quasi_harmonic.from_HA_files.

Raises:: ValueError – If multiple files are defined.

from_phonopy_files(phono_yaml, struc_yaml=None, edft=None, scale=1.0, imaginary_tol=0.0001, q_overlap_tol=0.0001, q_id=None, q_coord=None)

Build a QHA object from Phonopy ‘band.yaml, ‘mesh.yaml’ or ‘qpoints.yaml’ file.

Note

Mode symmetry and eigenvector are currently not available.

Note

q_id and q_coord should be set once and are applicable to all the yaml files.

Parameters:

phono_yaml (list[str]|str) – ncalc*1 list of Phonopy files.
struc_yaml (list[str]|str) –
ncalc*1 list of Phonopy phonopy.yaml or phonopy_disp.yaml files. *Needed only if a qpoint.yaml/

mesh.yaml file is read.*
edft (list[float]) – ncalc*1 list / array of DFT energies. Unit: kJ/mol.
scale (float) – Scaling factor of phonon frequency.
imaginary_tol (float) – The threshold of negative frequencies.
q_overlap_tol (float) – The threshold of overlapping points, defined as the 2nd norm of the difference of fractional q vectors
q_id (list[int]) – See Harmonic.from_phonopy.
q_coord (list[list]) – See Harmonic.from_phonopy.

Returned attributes are consistent with Quasi_harmonic.from_HA_files.

thermo_freq(eos_method='birch_murnaghan', poly_order=[2, 3], min_method='BFGS', volume_bound=None, mutewarning=False, **kwargs)

Obtain thermodynamic properties by explicitly fitting phonon frequencies as polynomial functions of volume. DFT total energies are fitted as a function of volume by equation of states (EOS).

The equilibrium volume is fitted by minimizing Gibbs free energy at constant temperature and pressure.

\[V(T,p)=\text{min}[G(V;T,p)]=\text{min}[E_{0}(V)+F_{vib}(V;T,p)+pV)]\]

Parameters:

eos_method (str) – EOS used to fit DFT total energy and Helmholtz free energy (to get bulk modules).
poly_order (array[int]) – The order of polynomials used to fit frequency as the function of volumes.
min_method (string, optional) – Minimisation algorithms.
volume_bound (tuple-like) – volumes. Unit: Angstrom^3
mutewarning (bool) – Whether print out warning messages.
**kwargs – See below
temperature (array[float]) – Unit: K
pressure (array[float]) – Unit: GPa
order (int) – For DeltaFactor / Polynomial EOSs.
min_ndata_factor (int) – For Numerical EOS.
max_poly_order_factor (int) – For Numerical EOS.
min_poly_order_factor (int) – For Numerical EOS.

Note

Valid entries of eos_method are consistent with PyMatGen eos module.
Parameterized and tested algorithms for min_method:
- BFGS(no boundary)
- L-BFGS-B(with boundary)

Returns:

self (Quasi_harmonic) – New Attributes listed below
self.temperature (array) – Unit: K
self.pressure (array) – Unit: GPa
self.volume (array) – nPressure*nTemperature, same below. Equilibrium volumes. Unit: $\AA^{3}$
self.helmholtz (array) – Helmholtz free energy. Unit: kJ/mol
self.gibbs (array) – Gibbs free energy. Unit: kJ/mol
self.entropy (array) – Entropy. Unit: $J.mol^{-1}.K^{-1}$
self.c_v (array) – Constant volume specific heat. Unit: $J.mol^{-1}.K^{-1}$
self.e0_eos (Pymatgen EOS) – Pymatgen EOS object. EOS used to fit DFT energy.
self.e0_eos_method (str) – Name of the EOS.

Raises:

Exception – If temperature or pressure is defined neither here nor during initialization.

thermo_gruneisen(eos_method='birch_murnaghan', min_method='BFGS', volume_bound=None, mutewarning=False, **kwargs)

Grüneisen parameters and related properties. The macroscopic Grüneisen parameter is defined as:

\[\gamma=\sum_{\textbf{q}i}\frac{\gamma_{\textbf{q}i}C_{V,\textbf{q}i}}{C_{V}}\]

Thermal expansion coefficient in Grüneisen model:

\[\alpha_{V}^{gru}=\frac{\gamma C_{V}}{K_{T}V}\]

Note

The Grüneisen model is used to fit frequencies, equivalent to using self.thermo_freq(poly_order=1).

For arguments, see self.thermo_freq.

Returns:

self (Quasi_harmonic) – New attributes listed below. Other attributes are the same as self.thermo_freq.
self.gruneisen (array) – npressure*ntemperature, same below. Macroscopic Grüneisen parameter. Temperature should > 0.
self.alpha_vgru (array) – Thermal expansion coefficient by Grüneisen method.
self.c_pgru (array) – Constant pressure specific heat by Grüneisen method. Unit: $J.mol^{-1}.K^{-1}$
self.k_t (array) – Isothermal bulk modulus. Unit: GPa.
self.k_sgru (array) – Adiabatic bulk modulus by Grüneisen method. Unit: GPa.

thermo_eos(eos_method='birch_murnaghan', poly_order=[2, 3], mutewarning=False, **kwargs)

Obtain thermodynamic properties by fitting EOS, which is fitted by the Helmholtz free energies of sampled harmonic phonons. The explicit sorting and fitting of frequency-volume relationship is disabled.

Entropy is obtained by taking the derivation of Gibbs free energy at constant pressure.

\[S=-\left(\frac{\partial G}{\partial T}\right)_{p}\]

Constant pressure specific heat is obtained by taking the second derivative of $G$.

\[C_{p}=-T\left(\frac{\partial^{2}G}{\partial T^{2}}\right)_{p}\]

Note

poly_order should >= 2.

For arguments, see self.thermo_freq.

Returns:

self (Quasi_harmonic) – New attributes listed below
self.temperature (array) – Unit: K
self.pressure (array) – Unit: GPa
self.volume (array) – nPressure*nTemperature, same below. Equilibrium volumes. Unit: $\AA^{3}$
self.helmholtz (array) – Helmholtz free energy. Unit: kJ/mol
self.gibbs (array) – Gibbs free energy. Unit: kJ/mol
self.entropy (array) – Entropy. Unit: $J.mol^{-1}.K^{-1}$
self.c_p (array) – Constant pressure specific heat. Unit: $J.mol^{-1}.K^{-1}$
self.fe_eos (list[Pymatgen EOS]) – nTemperature*1 list of Pymatgen EOS objects. EOSs used to fit HA free energy at constant temperature.
self.fe_eos_method (str) – The name of EOS used.

Raises:

Exception – If the number of HA calculations is less than 4.
Exception – If temperature or pressure is defined neither here nor during initialization.

expansion_vol(poly_order=[2, 3], plot=True, fit_fig='expansion_fit.png')

Fit the thermal expansion curve and get thermal expansion coefficients at equilibrium volumes.

The volumetric thermal expansion coefficient at constant pressure:

\[\alpha_{V}(T) = \frac{1}{V(T)}\left(\frac{\partial V(T)}{\partial T}\right)_{p}\]

For thermal expansion with Grüneisen model, please refer to the thermo_gruneisen() method.

Parameters:

poly_order (list[int]) – method = ‘polynomial’, order of polynomials.
plot (bool) – Plot V-T curves to examine the goodness of fitting. An interactive window will pump out to let user to specify the optimial fitting.
fit_fig (str) – File name for fittings. A temperal figure is printed to help the user choose the optimal fitting.

Returns:

self (Quasi_harmonic) – New attributes listed below
self.vol_fit (list) – 1*nPressure. List of Numpy polynomial object, the fitted volume V(T).
self.alpha_v (array) – nPressure*nTemperature. Expansion coefficients at equilibrium volumes.

bulk_modulus(adiabatic=True, **kwargs)

Calculate isothermal and adiabatic bulk moduli at equilibrium volumes.

The following equations are used:

\[ \begin{align}\begin{aligned}K_{T}(p;T) = V(p;T)\left(\frac{\partial^{2}F(V;T)}{\partial V^{2}}\right)_{T}\\K_{S} = K_{T} + \frac{\alpha^{2}_{V}VTK^{2}_{T}}{C_{V}}\end{aligned}\end{align} \]

To get $K_{T}$, Helmholtz free energy is fit as isothermal EOSs. For self.thermo_eos(), that means doing nothing; For self.thermo_freq(), EOS fitting is required, whose form is the same as EOS used for $E_{0}$.

Parameters:

adiabatic (bool) – Whether to fit adiabatic bulk modulus. Thermal expansion coefficient needed.
**kwargs – See below.
order – (int): To restore EOS.
min_ndata_factor – (int): To restore EOS.
max_poly_order_factor – (int): To restore EOS.
min_poly_order_factor – (int): To restore EOS.

Returns:

self (Quasi_harmonic) – New attributes listed below
self.k_t (array) – nPressure*nTemperature, same below. Isothermal bulk modulus. Unit: GPa.
self.k_s (array) – Adiabatic bulk modulus. Unit: GPa.

specific_heat()

Calculate constant volume or pressure specific heat at equilibrium volumes.

The following equation is used:

\[C_{p} - C_{V} = \alpha_{V}^{2}K_{T}VT\]

Returns:

self (Quasi_harmonic) – New attributes listed below
self.c_v (array) – nPressure*nTemperature, same below. Constant volume specific heat. Unit: J/mol/K
self.c_p (array) – Constant pressure specific heat. Unit: J/mol/K.

Note

This method fits self.c_p by self.c_v when thermo_freq and thermo_gruneisen was used. self.c_v is obtained by when thermo_eos is used.

expansion_lin(poly_order=[2, 3], interp=None)

Fit linear expansions of lattice parameters by the 2-order Taylor expansion.

\[G(\mathbf{p})=G_{0}(\mathbf{p_{0}})+\Delta\mathbf{p}^{T}\mathbf{H}\Delta\mathbf{p}\]

$G$ is Gibbs free energy. $\mathbf{p}$ is the vector of lattice parameters. $\Delta\mathbf{p}$ means the difference between the fitted and equilibrium lattice parameters. $\mathbf{H}$ is the Hessian of $G$ and displacements along lattice parameters.

The RMS deviations (RMSD) of the following equation is minimized at constant temperature and pressure. But deviations from equilibrium volume might occur. RMSD of Gibbs free energy is available in output file only.

\[\mathbf{p_{0}} = \min\left\{\Delta\mathbf{p}^{T}\mathbf{H}\Delta\mathbf{p} - [G(\mathbf{p})-G_{0}(T,p)]\right\}\]

Note

Raimbault, V. Athavale and M. Rossi, Phys. Rev. Materials, 2019, 3, 053605.

This method requires a larger number of HA calculations to ensure a small RMSD. Typically the number of HA calculations should follow the equation below, otherwise the warning massage is given.

\[n_{HA} \geq n_{latt} + \sum_{i=1}^{n_{latt}}i\]

$n_{latt}$ is the lenth of the minimial set of lattice parameters. The optimized lattice parameters at DFT level are used for fitting.

To avoid warnings, use interp to linearly interpolate the lattice parameters and to get thermodynamic properties from the fitted QHA object.

Parameters:

poly_order (list[int]) – Order of polynomials used to fit the linear expansion coefficients. The optimal fit across the sampled temperature and pressure range of a certain lattice parameter is automatically chosen based on $R^{2}$.
interp (int) – Number of interpolated geometries. All the HA geometries are used besides the interpolated ones.

Returns:

self (Quasi_harmonic) – New attributes listed below
self.lattice (array) – nPressure*nTemperature*nLattice. The equilibrium values of minimal set of lattice parameters.
self.latt_fit (list) – nPressure*nLattice. Numpy polynomial object, the fitted a(v). Linear part only.
self.alpha_latt (array) – nPressure*nTemperature*nLattice. Linear expansion coefficients. Linear part only.

eos_fit(volume, energy, method, write_out=True, **kwargs)

Fit energy-volume relationship by equation of states.

Parameters:

volume (array[float]) – Unit: Angstrom^3
energy (array[float]) – Unit: kJ/mol
method (str) – Name of EoS used. Consistent with Pymatgen.
write_out (bool) – Whether to print EOS information.
order (int) – For DeltaFactor / Polynomial methods.
min_ndata_factor (int) – For the NumericalEOS method.
max_poly_order_factor (int) – For the NumericalEOS method.
min_poly_order_factor (int) – For the NumericalEOS method.

Returns:

eos (Pymatgen EOS) – The fitted equation of state.
eos_method (string) – Name of the fitted equation of state

freq_polynomial_fit(order)

Fit phonon frequencies as polynomial functions of volumes.

Parameters:: order (list[int] | array[int]) – The order of polynomials used.
Returns:: self.fit_order (int) – The optimal order of polynomial fit.

Please also refer to self.poly_fit and self.poly_fit_rsquare attributes of Mode class.

class Phonopy

Bases: object

The convertor between Phonopy and CRYSTALpytools file formats

classmethod read_structure(file)

Read geometry from Phonopy band.yaml, phonopy.yaml or phonopy_disp.yaml files.

Parameters:: file (str) – Phonopy yaml file
Returns:: struc (Pymatgen Structure)
Raises:: Exception – If the length unit in yaml file is neither ‘au’ nor ‘angstrom’.

classmethod read_frequency(file, q_id=None, q_coord=None)

Read phonon frequency from Phonopy band.yaml, mesh.yaml or qpoints.yaml files. Frequency units must be THz (default of Phonopy).

Parameters:

file (str) – Phonopy yaml file
q_id (list[int]) – Specify the id (from 0) of q points to be read. nqpoint*1 list.
q_coord (list[list]) – Specify the coordinates of q points to be read. nqpoint*3 list.

q_id and q_coord should not be set simultaneously. If set, q_id takes priority and q_coord is ignored. If both are none, all the points will be read.

Note

Setting q_id or q_coord change their weights, i.e., the sum of their weights is renormalized to 1.

Returns:

qpoint (list) – natom*2 list. 1st element: 3*1 array. Fractional coordinates of q points; 2nd element: float. Weight
frequency (array) – nqpint*nmode array. Phonon frequency in THz.

Raises:

Exception – If (some of) q point is not found.

classmethod write_force_constants(hessfile='HESSFREQ.DAT', phonopyfile='FORCE_CONSTANTS')

Write Phonopy/VASP FORCE_CONSTANTS file by CRYSTAL HESSFREQ.DAT file.

For example, to convert the calculation ‘example’ with a 4*4*4 supercelland get phonon frequencies at Gamma point, use the following code:

>>> from CRYSTALpytools.thermodynamics import Phonopy
>>> Phonopy.write_force_constants(hessfile='example.HESSFREQ')
>>> phonopy --crystal --qpoints='0 0 0' -c example.out --dim='4 4 4' --readfc

Parameters:

hessfile (str) – The HESSFREQ.DAT file
phonopyfile (str) – The output name

class Output

Bases: object

Deal with output data file

classmethod write_HA_result(ha)

Write harmonic phonon information.

Parameters:: ha (Harmonic) – CRYSTALpytools.thermodynamic.Harmonic object

classmethod write_QHA_combinedata(qha)

Write QHA combined phonon information.

Parameters:: qha (Quasi_harmonic) – CRYSTALpytools.thermodynamic.Quasi_harmonic object

classmethod write_QHA_sortphonon(qha, close_overlap)

Write QHA phonon sort information.

Parameters:

qha (Quasi_harmonic) – CRYSTALpytools.thermodynamic.Quasi_harmonic object.
close_overlap (array[int]) – nqpoint*nmode_ref*ncalc*nmode_sort. Number of close overlaps.

classmethod write_QHA_eosfit(qha, eos, method)

Write QHA phonon eos fit information.

Parameters:

qha (Quasi_harmonic) – CRYSTALpytools.thermodynamic.Quasi_harmonic object.
order (list[int]) – Orders of polynomials
method (str) – Name of EoS used.

classmethod write_QHA_polyfit(qha, order, rsquare_q)

Write QHA phonon polynomial fit information.

Parameters:

qha (Quasi_harmonic) – CRYSTALpytools.thermodynamic.Quasi_harmonic object.
order (list[int]) – List of polynomial orders.
rsquare_q (array) – Nqpoint*Norder list. Overall goodness at a q point.

classmethod write_QHA_thermofreq(qha, min_method, volume_bound)

Write QHA thermodynamics information (frequency fitting).

Parameters:: qha (Quasi_harmonic) – CRYSTALpytools.thermodynamic.Quasi_harmonic object.

classmethod write_QHA_thermogru(qha)

Write QHA thermodynamics information (Grüneisen fitting).

Parameters:: qha (Quasi_harmonic) – CRYSTALpytools.thermodynamic.Quasi_harmonic object.

classmethod write_QHA_thermoeos(qha)

Write QHA thermodynamics information (EOS fitting).

Parameters:: qha (Quasi_harmonic) – CRYSTALpytools.thermodynamic.Quasi_harmonic object.

classmethod write_expansion_vol(qha, fit_order, fit_rs)

Write volumetric thermal expansions.

Parameters:

qha (Quasi_harmonic) – CRYSTALpytools.thermodynamic.Quasi_harmonic object.
fit_order (int) – The order of polynomial used for fitting.
fit_rs (list[float]) – R^2 of fitting. nPressure*1 list.

classmethod write_bulk_modulus(qha, adiabatic)

Write bulk moduli.

Parameters:

qha (Quasi_harmonic) –

CRYSTALpytools.thermodynamic.Quasi_harmonic: object.
adiabatic (bool): Whether the adiabatic bulk modulus $K_{S}$: is fitted.

classmethod write_specific_heat(qha)

Write bulk moduli.

Parameters:: qha (Quasi_harmonic) – CRYSTALpytools.thermodynamic.Quasi_harmonic object.

classmethod write_expansion_latt(qha, e_err, fit_order, r_square)

Write linear expansion information.

Parameters:

qha (Quasi_harmonic) – CRYSTALpytools.thermodynamic.Quasi_harmonic object.
e_err (array) – RMS deviation of Gibbs free energy at T and p.
fit_order (array) – The order of polynomials used for fitting lattice parameter.
r_square (array) – R^2 of fitting. nLatt*nPress

CRYSTALpytools.topond module

The module for TOPOND topological analysis of electron density

class ScalarField

Bases: object

Basic TOPOND scalar field class, containing a nY*nX (nZ*nY*nX) data array for 2D (3D) fields. Call the property-specific child classes below to use. 3D methods under development.

plot_2D(levels=100, lineplot=False, contourline=None, isovalues='%.2f', colorplot=False, colormap='jet', cbar_label=None, a_range=[], b_range=[], edgeplot=False, x_ticks=5, y_ticks=5, figsize=[6.4, 4.8], overlay=None, fig=None, ax_index=None, **kwargs)

Plot 2D contour lines, color maps or both for the 2D data set. The user can also get the overlapped plot of ScalarField and Trajectory classes.

Note

2D periodicity (a_range and b_range), though available for the ScalarField class, is not suggested as TOPOND plotting window does not always commensurate with periodic boundary. The Trajectory class has no 2D periodicity so if overlay is not None, a_range, b_range and edgeplot will be disabled.

3 styles are available:

lineplot=True and colorplot=True: The color-filled contour
map with black contour lines. Dotted lines for negative values and solid lines for positive values. The solid line twice in width for 0.
lineplot=False and colorplot=True: The color-filled contour
map.
lineplot=True and colorplot=False: The color coded contour
line map. Blue dotted line for negative values and red solid lines for positive values. The balck solid line twice in width for 0.

Parameters:

levels (array|int) – Set levels of colored / line contour plot. A number for linear scaled plot colors or an array for user-defined levels. 1D.
lineplot (bool) – Plot contour lines.
contourline (list) – nLevel*3 contour line styles. Useful only if lineplot=True. For every line, color, line style and line width are defined in sequence.
isovalues (str|None) – Add isovalues to contour lines and set their formats. Useful only if lineplot=True. None for not adding isovalues.
colorplot (bool) – Plot color-filled contour plots.
colormap (str) – Matplotlib colormap option. Useful only if colorplot=True.
cbar_label (str) – Label of colorbar. Useful only if colorplot=True. ‘None’ for no labels.
a_range (list) – 1*2 range of $a$ axis (x, or BC) in fractional coordinate.
b_range (list) – 1*2 range of $b$ axis (y, or BA) in fractional coordinate.
edgeplot (bool) – Whether to add cell boundaries represented by the original base vectors (not inflenced by a/b range).
x_ticks (int) – Number of ticks on x axis.
y_ticks (int) – Number of ticks on y axis.
figsize (list) – Matplotlib figure size. Note that axes aspects are fixed to be equal.
overlay (None|Trajectory) – Overlapping a 2D plot from the topond.Trajectory object if not None.
fig (Figure) – Developer Only, matplotlib Figure class.
ax_index (int) – Developer Only, index of the axis in fig.axes.
**kwargs – Other arguments passed to topond.Trajectory.

Returns:

fig (Figure) – Matplotlib Figure object

substract(*args)

Substracting data of the same type from the object.

Parameters:: *args (str|ScalarField) – File names or ScalarField objects. Must be of the same type (check the attribute type).
Returns:: self (ScalarField) – Data difference

class Trajectory

Bases: object

Basic TOPOND trajectory plot class. Call the property-specific child classes below to use.

plot_2D(cpt_marker='o', cpt_color='k', cpt_size=10, traj_color='r', traj_linestyle=':', traj_linewidth=0.5, x_ticks=5, y_ticks=5, figsize=[6.4, 4.8], overlay=None, fig=None, ax_index=None, **kwargs)

Get TOPOND trajectory in a 2D plot.

Note

2D periodicity (a_range and b_range) is not available for the Trajectory class. If overlay is not None, a_range and b_range and edgeplot will be disabled for the ScalarField object.

Parameters:

cpt_marker (str) – Marker of critical point scatter.
cpt_color (str) – Marker color of critical point scatter.
cpt_size (float|int) – Marker size of critical point scatter.
traj_color (str) – Line color of 2D trajectory plot.
traj_linestyl (str) – Line style of 2D trajectory plot.
traj_linewidth (str) – Line width of 2D trajectory plot.
x_ticks (int) – Number of ticks on x axis.
y_ticks (int) – Number of ticks on y axis.
figsize (list) – Matplotlib figure size. Note that axes aspects are fixed to be equal.
overlay (None|ScalarField) – Overlapping a 2D plot from the topond.ScalarField object if not None.
fig (Figure|None) – Developers only, matplotlib Figure class..
ax_index (list[int]) – Developer Only, indices of axes in fig.axes.
**kwargs – Other arguments passed to ScalarField.plot_2D().

Returns:

fig (Figure) – Matplotlib Figure object

class ChargeDensity(data, base, dimen, struc=None, unit='Angstrom')

Bases: ScalarField

The charge density object from TOPOND. Unit: ‘Angstrom’ for $\AA^{-3}$ and ‘a.u.’ for Bohr $^{-3}$.

Parameters:

data (array) – 2D (3D) Plot data. (nZ*)nY*nX. 3D methods under developing.
base (array) – 3*3 Cartesian coordinates of the 3 points defining vectors BA and BC.
struc (CStructure) – Extended Pymatgen Structure object.
unit (str) – In principle, should always be ‘Angstrom’ (case insensitive).

classmethod from_file(file, output=None)

Generate a ChargeDensity object from a single file. Can be used for multiple dimensions (2D only now. 3D under development).

Note

Though output is not mandatory for plotting proposes, it is highly recommended to be added for geometry information and other methods.

Parameters:

file (str) – File name of the ‘SURFRHOO.DAT’ file
output (str) – Screen output of ‘properties’ calculation.

Returns:

cls (ChargeDensity)

plot_2D(unit='Angstrom', levels='default', lineplot=True, linewidth=1.0, isovalues='%.2f', colorplot=False, colormap='jet', cbar_label='default', a_range=[], b_range=[], edgeplot=False, x_ticks=5, y_ticks=5, title='default', figsize=[6.4, 4.8], overlay=None, fig=None, ax_index=None, **kwargs)

Plot 2D contour lines, color maps or both for the 2D data set. The user can also get the overlapped plot of ScalarField and Trajectory classes.

Note

For more information of plot setups, please refer its parent class, topond.ScalarField.

Parameters:

unit (str) – Plot unit. ‘Angstrom’ for $\AA^{-3}$, ‘a.u.’ for Bohr $^{-3}$.
levels (array|int) – Set levels of colored / line contour plot. A number for linear scaled plot colors or an array for user-defined levels. 1D. ‘default’ for default levels.
lineplot (bool) – Plot contour lines.
contourline (list) – Width of contour lines. Other styles are pre- set and cannot be changed.
isovalues (str|None) – Add isovalues to contour lines and set their formats. Useful only if lineplot=True. None for not adding isovalues.
colorplot (bool) – Plot color-filled contour plots.
colormap (str) – Matplotlib colormap option. Useful only if colorplot=True.
cbar_label (str) – Label of colorbar. Useful only if colorplot=True. ‘None’ for no labels.
a_range (list) – 1*2 range of $a$ axis (x, or BC) in fractional coordinate.
b_range (list) – 1*2 range of $b$ axis (y, or BA) in fractional coordinate.
edgeplot (bool) – Whether to add cell boundaries represented by the original base vectors (not inflenced by a/b range).
x_ticks (int) – Number of ticks on x axis.
y_ticks (int) – Number of ticks on y axis.
title (str|None) – Plot title. ‘default’ for default values and ‘None’ for no title.
figsize (list) – Matplotlib figure size. Note that axes aspects are fixed to be equal.
overlay (None|Trajectory) – Overlapping a 2D plot from the topond.Trajectory object if not None.
fig (Figure) – Developer Only, matplotlib Figure class.
ax_index (int) – Developer Only, index of the axis in fig.axes.
**kwargs – Other arguments passed to topond.Trajectory.

Returns:

fig (Figure) – Matplotlib Figure object

class SpinDensity(data, base, dimen, struc=None, unit='Angstrom')

Bases: ScalarField

The spin density object from TOPOND. Unit: ‘Angstrom’ for $\AA^{-3}$ and ‘a.u.’ for Bohr $^{-3}$.

Parameters:

data (array) – 2D (3D) Plot data. (nZ*)nY*nX. 3D methods under developing.
base (array) – 3*3 Cartesian coordinates of the 3 points defining vectors BA and BC.
struc (CStructure) – Extended Pymatgen Structure object.
unit (str) – In principle, should always be ‘Angstrom’ (case insensitive).

classmethod from_file(file, output=None)

Generate a SpinDensity object from a single file. Can be used for multiple dimensions (2D only now. 3D under development).

Note

Though output is not mandatory for plotting proposes, it is highly recommended to be added for geometry information and other methods.

Parameters:

file (str) – File name of the ‘SURFSPDE.DAT’ file
output (str) – Screen output of ‘properties’ calculation.

Returns:

cls (SpinDensity)

plot_2D(unit='Angstrom', levels='default', lineplot=True, linewidth=1.0, isovalues='%.4f', colorplot=False, colormap='jet', cbar_label='default', a_range=[], b_range=[], edgeplot=False, x_ticks=5, y_ticks=5, title='default', figsize=[6.4, 4.8], overlay=None, fig=None, ax_index=None, **kwargs)

Plot 2D contour lines, color maps or both for the 2D data set. The user can also get the overlapped plot of ScalarField and Trajectory classes.

Note

For more information of plot setups, please refer its parent class, topond.ScalarField.

Parameters:

unit (str) – Plot unit. ‘Angstrom’ for $\AA^{-3}$, ‘a.u.’ for Bohr $^{-3}$.
levels (array|int) – Set levels of colored / line contour plot. A number for linear scaled plot colors or an array for user-defined levels. 1D. ‘default’ for default levels.
lineplot (bool) – Plot contour lines.
contourline (list) – Width of contour lines. Other styles are pre- set and cannot be changed.
isovalues (str|None) – Add isovalues to contour lines and set their formats. Useful only if lineplot=True. None for not adding isovalues.
colorplot (bool) – Plot color-filled contour plots.
colormap (str) – Matplotlib colormap option. Useful only if colorplot=True.
cbar_label (str) – Label of colorbar. Useful only if colorplot=True. ‘None’ for no labels.
a_range (list) – 1*2 range of $a$ axis (x, or BC) in fractional coordinate.
b_range (list) – 1*2 range of $b$ axis (y, or BA) in fractional coordinate.
edgeplot (bool) – Whether to add cell boundaries represented by the original base vectors (not inflenced by a/b range).
x_ticks (int) – Number of ticks on x axis.
y_ticks (int) – Number of ticks on y axis.
title (str|None) – Plot title. ‘default’ for default values and ‘None’ for no title.
figsize (list) – Matplotlib figure size. Note that axes aspects are fixed to be equal.
overlay (None|Trajectory) – Overlapping a 2D plot from the topond.Trajectory object if not None.
fig (Figure) – Developer Only, matplotlib Figure class.
ax_index (int) – Developer Only, index of the axis in fig.axes.
**kwargs – Other arguments passed to topond.Trajectory.

Returns:

fig (Figure) – Matplotlib Figure object

class Gradient(data, base, dimen, struc=None, unit='Angstrom')

Bases: ScalarField

The charge density gradient object from TOPOND. Unit: ‘Angstrom’ for $\AA^{-4}$ and ‘a.u.’ for Bohr $^{-4}$.

Parameters:

data (array) – 2D (3D) Plot data. (nZ*)nY*nX. 3D methods under developing.
base (array) – 3*3 Cartesian coordinates of the 3 points defining vectors BA and BC.
struc (CStructure) – Extended Pymatgen Structure object.
unit (str) – In principle, should always be ‘Angstrom’ (case insensitive).

classmethod from_file(file, output=None)

Generate a Gradient object from a single file. Can be used for multiple dimensions (2D only now. 3D under development).

Note

Though output is not mandatory for plotting proposes, it is highly recommended to be added for geometry information and other methods.

Parameters:

file (str) – File name of the ‘SURFGRHO.DAT’ file
output (str) – Screen output of ‘properties’ calculation.

Returns:

cls (Gradient)

plot_2D(unit='Angstrom', levels='default', lineplot=True, linewidth=1.0, isovalues='%.2f', colorplot=False, colormap='jet', cbar_label='default', a_range=[], b_range=[], edgeplot=False, x_ticks=5, y_ticks=5, title='default', figsize=[6.4, 4.8], overlay=None, fig=None, ax_index=None, **kwargs)

Plot 2D contour lines, color maps or both for the 2D data set. The user can also get the overlapped plot of ScalarField and Trajectory classes.

Note

For more information of plot setups, please refer its parent class, topond.ScalarField.

Parameters:

unit (str) – Plot unit. ‘Angstrom’ for $\AA^{-3}$, ‘a.u.’ for Bohr $^{-3}$.
levels (array|int) – Set levels of colored / line contour plot. A number for linear scaled plot colors or an array for user-defined levels. 1D. ‘default’ for default levels.
lineplot (bool) – Plot contour lines.
contourline (list) – Width of contour lines. Other styles are pre- set and cannot be changed.
isovalues (str|None) – Add isovalues to contour lines and set their formats. Useful only if lineplot=True. None for not adding isovalues.
colorplot (bool) – Plot color-filled contour plots.
colormap (str) – Matplotlib colormap option. Useful only if colorplot=True.
cbar_label (str) – Label of colorbar. Useful only if colorplot=True. ‘None’ for no labels.
a_range (list) – 1*2 range of $a$ axis (x, or BC) in fractional coordinate.
b_range (list) – 1*2 range of $b$ axis (y, or BA) in fractional coordinate.
edgeplot (bool) – Whether to add cell boundaries represented by the original base vectors (not inflenced by a/b range).
x_ticks (int) – Number of ticks on x axis.
y_ticks (int) – Number of ticks on y axis.
title (str|None) – Plot title. ‘default’ for default values and ‘None’ for no title.
figsize (list) – Matplotlib figure size. Note that axes aspects are fixed to be equal.
overlay (None|Trajectory) – Overlapping a 2D plot from the topond.Trajectory object if not None.
fig (Figure) – Developer Only, matplotlib Figure class.
ax_index (int) – Developer Only, index of the axis in fig.axes.
**kwargs – Other arguments passed to topond.Trajectory.

Returns:

fig (Figure) – Matplotlib Figure object

class Laplacian(data, base, dimen, struc=None, unit='Angstrom')

Bases: ScalarField

The Laplacian object from TOPOND. Unit: ‘Angstrom’ for $\AA^{-5}$ and ‘a.u.’ for Bohr $^{-5}$.

Parameters:

data (array) – 2D (3D) Plot data. (nZ*)nY*nX. 3D methods under developing.
base (array) – 3*3 Cartesian coordinates of the 3 points defining vectors BA and BC.
struc (CStructure) – Extended Pymatgen Structure object.
unit (str) – In principle, should always be ‘Angstrom’ (case insensitive).

classmethod from_file(file, output=None)

Generate a Laplacian object from a single file. Can be used for multiple dimensions (2D only now. 3D under development).

Note

Though output is not mandatory for plotting proposes, it is highly recommended to be added for geometry information and other methods.

It is suggested to name the file with ‘LAPP’ or ‘LAPM’. Otherwise it will be read as ‘LAPP’. Data is always saved as $\nabla^{2}\rho$.

Parameters:

file (str) – File name of the ‘SURFLAPP.DAT’ or ‘SURFLAPM.DAT’ file
output (str) – Screen output of ‘properties’ calculation.

Returns:

cls (Laplacian)

plot_2D(unit='Angstrom', plot_lapm=False, levels='default', lineplot=True, linewidth=1.0, isovalues='%.2f', colorplot=False, colormap='jet', cbar_label='default', a_range=[], b_range=[], edgeplot=False, x_ticks=5, y_ticks=5, title='default', figsize=[6.4, 4.8], overlay=None, fig=None, ax_index=None, **kwargs)

Plot 2D contour lines, color maps or both for the 2D data set. The user can also get the overlapped plot of ScalarField and Trajectory classes.

Note

For more information of plot setups, please refer its parent class, topond.ScalarField.

Parameters:

unit (str) – Plot unit. ‘Angstrom’ for $\AA^{-3}$, ‘a.u.’ for Bohr $^{-3}$.
plot_lapm (bool) – Whether to plot $-\nabla^{2}\rho$.
levels (array|int) – Set levels of colored / line contour plot. A number for linear scaled plot colors or an array for user-defined levels. 1D. ‘default’ for default levels.
lineplot (bool) – Plot contour lines.
contourline (list) – Width of contour lines. Other styles are pre- set and cannot be changed.
isovalues (str|None) – Add isovalues to contour lines and set their formats. Useful only if lineplot=True. None for not adding isovalues.
colorplot (bool) – Plot color-filled contour plots.
colormap (str) – Matplotlib colormap option. Useful only if colorplot=True.
cbar_label (str) – Label of colorbar. Useful only if colorplot=True. ‘None’ for no labels.
a_range (list) – 1*2 range of $a$ axis (x, or BC) in fractional coordinate.
b_range (list) – 1*2 range of $b$ axis (y, or BA) in fractional coordinate.
edgeplot (bool) – Whether to add cell boundaries represented by the original base vectors (not inflenced by a/b range).
x_ticks (int) – Number of ticks on x axis.
y_ticks (int) – Number of ticks on y axis.
title (str|None) – Plot title. ‘default’ for default values and ‘None’ for no title.
figsize (list) – Matplotlib figure size. Note that axes aspects are fixed to be equal.
overlay (None|Trajectory) – Overlapping a 2D plot from the topond.Trajectory object if not None.
fig (Figure) – Developer Only, matplotlib Figure class.
ax_index (int) – Developer Only, index of the axis in fig.axes.
**kwargs – Other arguments passed to topond.Trajectory.

Returns:

fig (Figure) – Matplotlib Figure object

class HamiltonianKE(data, base, dimen, struc=None, unit='Angstrom')

Bases: ScalarField

The Hamiltonian kinetic energy density object from TOPOND. Unit: ‘Angstrom’ for eV.:math:AA^{-3} and ‘a.u.’ for Hartree.Bohr $^{-3}$.

Parameters:

data (array) – 2D (3D) Plot data. (nZ*)nY*nX. 3D methods under developing.
base (array) – 3*3 Cartesian coordinates of the 3 points defining vectors BA and BC.
struc (CStructure) – Extended Pymatgen Structure object.
unit (str) – In principle, should always be ‘Angstrom’ (case insensitive).

classmethod from_file(file, output=None)

Generate a HamiltonianKE object from a single file. Can be used for multiple dimensions (2D only now. 3D under development).

Note

Though output is not mandatory for plotting proposes, it is highly recommended to be added for geometry information and other methods.

Parameters:

file (str) – File name of the ‘SURFKKIN.DAT’ file
output (str) – Screen output of ‘properties’ calculation.

Returns:

cls (HamiltonianKE)

plot_2D(unit='Angstrom', levels='default', lineplot=True, linewidth=1.0, isovalues='%.2f', colorplot=False, colormap='jet', cbar_label='default', a_range=[], b_range=[], edgeplot=False, x_ticks=5, y_ticks=5, title='default', figsize=[6.4, 4.8], overlay=None, fig=None, ax_index=None, **kwargs)

Plot 2D contour lines, color maps or both for the 2D data set. The user can also get the overlapped plot of ScalarField and Trajectory classes.

Note

For more information of plot setups, please refer its parent class, topond.ScalarField.

Parameters:

unit (str) – Plot unit. ‘Angstrom’ for $\AA^{-3}$, ‘a.u.’ for Bohr $^{-3}$.
levels (array|int) – Set levels of colored / line contour plot. A number for linear scaled plot colors or an array for user-defined levels. 1D. ‘default’ for default levels.
lineplot (bool) – Plot contour lines.
contourline (list) – Width of contour lines. Other styles are pre- set and cannot be changed.
isovalues (str|None) – Add isovalues to contour lines and set their formats. Useful only if lineplot=True. None for not adding isovalues.
colorplot (bool) – Plot color-filled contour plots.
colormap (str) – Matplotlib colormap option. Useful only if colorplot=True.
cbar_label (str) – Label of colorbar. Useful only if colorplot=True. ‘None’ for no labels.
a_range (list) – 1*2 range of $a$ axis (x, or BC) in fractional coordinate.
b_range (list) – 1*2 range of $b$ axis (y, or BA) in fractional coordinate.
edgeplot (bool) – Whether to add cell boundaries represented by the original base vectors (not inflenced by a/b range).
x_ticks (int) – Number of ticks on x axis.
y_ticks (int) – Number of ticks on y axis.
title (str|None) – Plot title. ‘default’ for default values and ‘None’ for no title.
figsize (list) – Matplotlib figure size. Note that axes aspects are fixed to be equal.
overlay (None|Trajectory) – Overlapping a 2D plot from the topond.Trajectory object if not None.
fig (Figure) – Developer Only, matplotlib Figure class.
ax_index (int) – Developer Only, index of the axis in fig.axes.
**kwargs – Other arguments passed to topond.Trajectory.

Returns:

fig (Figure) – Matplotlib Figure object

class LagrangianKE(data, base, dimen, struc=None, unit='Angstrom')

Bases: ScalarField

The Lagrangian kinetic energy density object from TOPOND. Unit: ‘Angstrom’ for eV.:math:AA^{-3} and ‘a.u.’ for Hartree.Bohr $^{-3}$.

Parameters:

data (array) – 2D (3D) Plot data. (nZ*)nY*nX. 3D methods under developing.
base (array) – 3*3 Cartesian coordinates of the 3 points defining vectors BA and BC.
struc (CStructure) – Extended Pymatgen Structure object.
unit (str) – In principle, should always be ‘Angstrom’ (case insensitive).

classmethod from_file(file, output=None)

Generate a LagrangianKE object from a single file. Can be used for multiple dimensions (2D only now. 3D under development).

Note

Though output is not mandatory for plotting proposes, it is highly recommended to be added for geometry information and other methods.

Parameters:

file (str) – File name of the ‘SURFGKIN.DAT’ file
output (str) – Screen output of ‘properties’ calculation.

Returns:

cls (LagrangianKE)

plot_2D(unit='Angstrom', levels='default', lineplot=True, linewidth=1.0, isovalues='%.2f', colorplot=False, colormap='jet', cbar_label='default', a_range=[], b_range=[], edgeplot=False, x_ticks=5, y_ticks=5, title='default', figsize=[6.4, 4.8], overlay=None, fig=None, ax_index=None, **kwargs)

Plot 2D contour lines, color maps or both for the 2D data set. The user can also get the overlapped plot of ScalarField and Trajectory classes.

Note

For more information of plot setups, please refer its parent class, topond.ScalarField.

Parameters:

unit (str) – Plot unit. ‘Angstrom’ for $\AA^{-3}$, ‘a.u.’ for Bohr $^{-3}$.
levels (array|int) – Set levels of colored / line contour plot. A number for linear scaled plot colors or an array for user-defined levels. 1D. ‘default’ for default levels.
lineplot (bool) – Plot contour lines.
contourline (list) – Width of contour lines. Other styles are pre- set and cannot be changed.
isovalues (str|None) – Add isovalues to contour lines and set their formats. Useful only if lineplot=True. None for not adding isovalues.
colorplot (bool) – Plot color-filled contour plots.
colormap (str) – Matplotlib colormap option. Useful only if colorplot=True.
cbar_label (str) – Label of colorbar. Useful only if colorplot=True. ‘None’ for no labels.
a_range (list) – 1*2 range of $a$ axis (x, or BC) in fractional coordinate.
b_range (list) – 1*2 range of $b$ axis (y, or BA) in fractional coordinate.
edgeplot (bool) – Whether to add cell boundaries represented by the original base vectors (not inflenced by a/b range).
x_ticks (int) – Number of ticks on x axis.
y_ticks (int) – Number of ticks on y axis.
title (str|None) – Plot title. ‘default’ for default values and ‘None’ for no title.
figsize (list) – Matplotlib figure size. Note that axes aspects are fixed to be equal.
overlay (None|Trajectory) – Overlapping a 2D plot from the topond.Trajectory object if not None.
fig (Figure) – Developer Only, matplotlib Figure class.
ax_index (int) – Developer Only, index of the axis in fig.axes.
**kwargs – Other arguments passed to topond.Trajectory.

Returns:

fig (Figure) – Matplotlib Figure object

class VirialField(data, base, dimen, struc=None, unit='Angstrom')

Bases: ScalarField

The Virial field density object from TOPOND. Unit: ‘Angstrom’ for eV.:math:AA^{-3} and ‘a.u.’ for Hartree.Bohr $^{-3}$.

Parameters:

data (array) – 2D (3D) Plot data. (nZ*)nY*nX. 3D methods under developing.
base (array) – 3*3 Cartesian coordinates of the 3 points defining vectors BA and BC.
struc (CStructure) – Extended Pymatgen Structure object.
unit (str) – In principle, should always be ‘Angstrom’ (case insensitive).

classmethod from_file(file, output=None)

Generate a VirialField object from a single file. Can be used for multiple dimensions (2D only now. 3D under development).

Note

Though output is not mandatory for plotting proposes, it is highly recommended to be added for geometry information and other methods.

Parameters:

file (str) – File name of the ‘SURFVIRI.DAT’ file
output (str) – Screen output of ‘properties’ calculation.

Returns:

cls (VirialField)

plot_2D(unit='Angstrom', levels='default', lineplot=True, linewidth=1.0, isovalues='%.2f', colorplot=False, colormap='jet', cbar_label='default', a_range=[], b_range=[], edgeplot=False, x_ticks=5, y_ticks=5, title='default', figsize=[6.4, 4.8], overlay=None, fig=None, ax_index=None, **kwargs)

Plot 2D contour lines, color maps or both for the 2D data set. The user can also get the overlapped plot of ScalarField and Trajectory classes.

Note

For more information of plot setups, please refer its parent class, topond.ScalarField.

Parameters:

unit (str) – Plot unit. ‘Angstrom’ for $\AA^{-3}$, ‘a.u.’ for Bohr $^{-3}$.
levels (array|int) – Set levels of colored / line contour plot. A number for linear scaled plot colors or an array for user-defined levels. 1D. ‘default’ for default levels.
lineplot (bool) – Plot contour lines.
contourline (list) – Width of contour lines. Other styles are pre- set and cannot be changed.
isovalues (str|None) – Add isovalues to contour lines and set their formats. Useful only if lineplot=True. None for not adding isovalues.
colorplot (bool) – Plot color-filled contour plots.
colormap (str) – Matplotlib colormap option. Useful only if colorplot=True.
cbar_label (str) – Label of colorbar. Useful only if colorplot=True. ‘None’ for no labels.
a_range (list) – 1*2 range of $a$ axis (x, or BC) in fractional coordinate.
b_range (list) – 1*2 range of $b$ axis (y, or BA) in fractional coordinate.
edgeplot (bool) – Whether to add cell boundaries represented by the original base vectors (not inflenced by a/b range).
x_ticks (int) – Number of ticks on x axis.
y_ticks (int) – Number of ticks on y axis.
title (str|None) – Plot title. ‘default’ for default values and ‘None’ for no title.
figsize (list) – Matplotlib figure size. Note that axes aspects are fixed to be equal.
overlay (None|Trajectory) – Overlapping a 2D plot from the topond.Trajectory object if not None.
fig (Figure) – Developer Only, matplotlib Figure class.
ax_index (int) – Developer Only, index of the axis in fig.axes.
**kwargs – Other arguments passed to topond.Trajectory.

Returns:

fig (Figure) – Matplotlib Figure object

class ELF(data, base, dimen, struc=None, unit='Angstrom')

Bases: ScalarField

The electron localization object from TOPOND. Dimensionless. Unit: ‘Angstrom’ for $\AA$ and ‘a.u.’ for Bohr (only for plot base vectors).

Parameters:

data (array) – 2D (3D) Plot data. (nZ*)nY*nX. 3D methods under developing.
base (array) – 3*3 Cartesian coordinates of the 3 points defining vectors BA and BC.
struc (CStructure) – Extended Pymatgen Structure object.

classmethod from_file(file, output=None)

Generate a ELF object from a single file. Can be used for multiple dimensions (2D only now. 3D under development).

Note

Though output is not mandatory for plotting proposes, it is highly recommended to be added for geometry information and other methods.

Parameters:

file (str) – File name of the ‘SURFELFBDAT’ file
output (str) – Screen output of ‘properties’ calculation.

Returns:

cls (ELF)

plot_2D(unit='Angstrom', levels='default', lineplot=True, linewidth=1.0, isovalues='%.2f', colorplot=False, colormap='jet', cbar_label='default', a_range=[], b_range=[], edgeplot=False, x_ticks=5, y_ticks=5, title='default', figsize=[6.4, 4.8], overlay=None, fig=None, ax_index=None, **kwargs)

Plot 2D contour lines, color maps or both for the 2D data set. The user can also get the overlapped plot of ScalarField and Trajectory classes.

Note

For more information of plot setups, please refer its parent class, topond.ScalarField.

Parameters:

unit (str) – Plot unit. ‘Angstrom’ for $\AA^{-3}$, ‘a.u.’ for Bohr $^{-3}$.
levels (array|int) – Set levels of colored / line contour plot. A number for linear scaled plot colors or an array for user-defined levels. 1D. ‘default’ for default levels.
lineplot (bool) – Plot contour lines.
contourline (list) – Width of contour lines. Other styles are pre- set and cannot be changed.
isovalues (str|None) – Add isovalues to contour lines and set their formats. Useful only if lineplot=True. None for not adding isovalues.
colorplot (bool) – Plot color-filled contour plots.
colormap (str) – Matplotlib colormap option. Useful only if colorplot=True.
cbar_label (str) – Label of colorbar. Useful only if colorplot=True. ‘None’ for no labels.
a_range (list) – 1*2 range of $a$ axis (x, or BC) in fractional coordinate.
b_range (list) – 1*2 range of $b$ axis (y, or BA) in fractional coordinate.
edgeplot (bool) – Whether to add cell boundaries represented by the original base vectors (not inflenced by a/b range).
x_ticks (int) – Number of ticks on x axis.
y_ticks (int) – Number of ticks on y axis.
title (str|None) – Plot title. ‘default’ for default values and ‘None’ for no title.
figsize (list) – Matplotlib figure size. Note that axes aspects are fixed to be equal.
overlay (None|Trajectory) – Overlapping a 2D plot from the topond.Trajectory object if not None.
fig (Figure) – Developer Only, matplotlib Figure class.
ax_index (int) – Developer Only, index of the axis in fig.axes.
**kwargs – Other arguments passed to topond.Trajectory.

Returns:

fig (Figure) – Matplotlib Figure object

class GradientTraj(wtraj, traj, base, struc, unit='Angstrom')

Bases: Trajectory

The charge density gradient trajectory object from TOPOND. Unit: ‘Angstrom’ for $\AA$ and ‘a.u.’ for Bohr.

Parameters:

wtraj (list[int]) – 1*nPath, weight of the path, int 0 to 3.
traj (list[array]) – 1*nPath, list of paths. Every array is a nPoint*3 3D ref framework coordinates of points on the path.
base (array) – 3*3 Cartesian coordinates of the 3 points defining vectors BA and BC.
struc (CStructure) – Extended Pymatgen Structure object.
unit (str) – In principle, should always be ‘Angstrom’ (case insensitive).

Returns:

self (GradientTraj) – Import attributes: trajectory, nPath*2 list of trajectory and its weight; cpoint, nCpoint*3 array of critical point coordinates in 3D ref framework.

classmethod from_file(file, output)

Generate a GradientTraj object from ‘TRAJGRAD.DAT’ file and the standard screen output of CRYSTAL ‘properties’ calculation.

Note

Output file is mandatory.

Parameters:

file (str) – ‘TRAJGRAD.DAT’ file by TOPOND.
output (str) – Standard output of Properties calculation, used to get geometry and orientation of the plane.

Returns:

cls (ChargeDensity)

plot_2D(unit='Angstrom', cpt_marker='o', cpt_color='k', cpt_size=10, traj_color='r', traj_linestyle=':', traj_linewidth=0.5, x_ticks=5, y_ticks=5, title='default', figsize=[6.4, 4.8], overlay=None, fig=None, ax_index=None, **kwargs)

Plot charge density gradient trajectory in a 2D plot.

Note

For more information of plot setups, please refer its parent class, topond.Trajectory.

Parameters:

unit (str) – Plot unit. ‘Angstrom’ for $\AA^{-3}$, ‘a.u.’ for Bohr $^{-3}$.
cpt_marker (str) – Marker of critical point scatter.
cpt_color (str) – Marker color of critical point scatter.
cpt_size (float|int) – Marker size of critical point scatter.
traj_color (str) – Line color of 2D trajectory plot.
traj_linestyl (str) – Line style of 2D trajectory plot.
traj_linewidth (str) – Line width of 2D trajectory plot.
x_ticks (int) – Number of ticks on x axis.
y_ticks (int) – Number of ticks on y axis.
title (str|None) – Plot title. ‘default’ for proeprty plotted. ‘None’ for no title.
figsize (list) – Matplotlib figure size. Note that axes aspects are fixed to be equal.
overlay (None|ScalarField) – Overlapping a 2D plot from the topond.ScalarField object if not None.
fig (Figure|None) – Developers only, matplotlib Figure class..
ax_index (list[int]) – Developer Only, indices of axes in fig.axes.
**kwargs – Other arguments passed to ScalarField.plot_2D().

Returns:

fig (Figure) – Matplotlib Figure object

class ChemicalGraph(wtraj, traj, base, struc, unit='Angstrom')

Bases: Trajectory

The molecular / crystal graph object from TOPOND. Unit: ‘Angstrom’ for $\AA$ and ‘a.u.’ for Bohr.

Parameters:

wtraj (list[int]) – 1*nPath, weight of the path, int 0 to 3.
traj (list[array]) – 1*nPath, list of paths. Every array is a nPoint*3 3D ref framework coordinates of points on the path.
base (array) – 3*3 Cartesian coordinates of the 3 points defining vectors BA and BC.
struc (CStructure) – Extended Pymatgen Structure object.
unit (str) – In principle, should always be ‘Angstrom’ (case insensitive).

Returns:

self (ChemicalGraph) – Import attributes: trajectory, nPath*2 list of trajectory and its weight; cpoint, nCpoint*3 array of critical point coordinates in 3D ref framework.

classmethod from_file(file, output)

Generate a ChemicalGraph object from ‘TRAJMOLG.DAT’ file and the standard screen output of CRYSTAL ‘properties’ calculation.

Note

Output file is mandatory.

Parameters:

file (str) – ‘TRAJMOLG.DAT’ file by TOPOND.
output (str) – Standard output of Properties calculation, used to get geometry and orientation of the plane.

Returns:

cls (ChargeDensity)

plot_2D(unit='Angstrom', cpt_marker='o', cpt_color='k', cpt_size=10, traj_color='r', traj_linestyle=':', traj_linewidth=0.5, x_ticks=5, y_ticks=5, title='default', figsize=[6.4, 4.8], overlay=None, fig=None, ax_index=None, **kwargs)

Plot crystal / molecular graph in a 2D plot.

Note

For more information of plot setups, please refer its parent class, topond.Trajectory.

Parameters:

unit (str) – Plot unit. ‘Angstrom’ for $\AA^{-3}$, ‘a.u.’ for Bohr $^{-3}$.
cpt_marker (str) – Marker of critical point scatter.
cpt_color (str) – Marker color of critical point scatter.
cpt_size (float|int) – Marker size of critical point scatter.
traj_color (str) – Line color of 2D trajectory plot.
traj_linestyl (str) – Line style of 2D trajectory plot.
traj_linewidth (str) – Line width of 2D trajectory plot.
x_ticks (int) – Number of ticks on x axis.
y_ticks (int) – Number of ticks on y axis.
title (str|None) – Plot title. ‘default’ for proeprty plotted. ‘None’ for no title.
figsize (list) – Matplotlib figure size. Note that axes aspects are fixed to be equal.
overlay (None|ScalarField) – Overlapping a 2D plot from the topond.ScalarField object if not None.
fig (Figure|None) – Developers only, matplotlib Figure class..
ax_index (list[int]) – Developer Only, indices of axes in fig.axes.
**kwargs – Other arguments passed to ScalarField.plot_2D().

Returns:

fig (Figure) – Matplotlib Figure object

CRYSTALpytools.transport module

The module for electron transport property analysis.

class Tensor(temperature, potential, carrier_density, tensor, struc, type, unit)

Bases: object

The basic class for electron transport properties described by tensors, including ‘KAPPA’, ‘SIGMA’, ‘SIGMAS’ and ‘SEEBECK’. Units must be consistent with the output files.

Parameters:

temperature (array) – Temperature in K
potential (array) – Chemical potential in eV.
carrier_density (array) – nT*nPot*nSpin array of carrier density in cm $^{-3}$.
tensor (array) – nT*nPot*nDimen*nSpin array of flattened tensor elements. nDimen = 6 for 3D systems, 3 for 2D and 1 for 1D.
struc (CStructure) – Extended Pymatgen Structure object.
type (str) – ‘KAPPA’, ‘SIGMA’, ‘SIGMAS’ or ‘SEEBECK’.
unit (str) – Same as output file.

Returns:

self (Tensor) – Attributes: ‘T’, ‘mu’, ‘carrier’, ‘data’, ‘type’, ‘struc’, ‘unit’ and ‘spin’

classmethod from_file(*file, output=None, method='normal')

Read electron transport properties by the BOLTZTRA keyword, including ‘KAPPA’, ‘SIGMA’, ‘SIGMAS’, and ‘SEEBECK’. Though currently the geometry information is not required, it is saved if the standard output file is given.

Also allow for generating the following properties not printed by CRYSTAL:

Power Factor: $S^{2}\sigma$. Any 2 from ‘SEEBECK’, ‘SIGMA’ and
‘SIGMAS’ are required.
ZT: $\frac{S^{r}\sigma T}{\kappa}$. ‘KAPPA’ and any 2
from ‘SEEBECK’, ‘SIGMA’ and ‘SIGMAS’ are required.

Note

Make sure all the entries are from the same calculation. The code only checks the dimensionalities of tensors.

Note

For ‘SEEBECK’, all the 9 elements of the tensor was printed. As far as the developers have been aware of, it is symmetrized. Therefore the redundant ‘yx’, ‘zx’ and ‘zy’ dimensions are removed to keep consistent with other outputs.

Parameters:

file (str) – ‘DAT’ files by CRYSTAL BOLTZTRA keyword. Extendable only when method='power factor' or method='zt'.
output (str) – Properties output file.
method (str) – ‘normal’ to read 1 file, or ‘power factor’ or ‘zt’. For meanings, see above.

Returns:

cls (Tensor)

classmethod get_power_factor(obj1, obj2)

Get thermoelectric power factor object from any 2 objects of ‘SEEBECK’, ‘SIGMA’ or ‘SIGMAS’ types.

\[\text{Power Factor} = S^{2}\sigma\]

Note

Make sure all the entries are from the same calculation. The code only checks the dimensionalities of tensors. The geometry follows the first entry.

Parameters:

obj1 (Tensor) – Tensor object 1 of ‘SEEBECK’, ‘SIGMA’ or ‘SIGMAS’ types.
obj2 (Tensor) – Tensor object 2 of ‘SEEBECK’, ‘SIGMA’ or ‘SIGMAS’ types.

Returns:

cls (PowerFactor) – ‘POWERFACTOR’ type of object, in ‘W/m/K^2’.

classmethod get_zt(obj1, obj2, obj3)

Get thermoelectric dimensionless figure of merit (ZT) object from a ‘KAPPA’ object and any 2 from ‘SEEBECK’, ‘SIGMA’ and ‘SIGMAS’.

\[ZT = \frac{S^{r}\sigma T}{\kappa}\]

Note

Make sure all the entries are from the same calculation. The code only checks the dimensionalities of tensors. The geometry follows the ‘KAPPA’ entry.

Parameters:

obj1 (Tensor) – Tensor object 1 of ‘KAPPA’, ‘SEEBECK’, ‘SIGMA’ or ‘SIGMAS’ types.
obj2 (Tensor) – Tensor object 2 of ‘KAPPA’, ‘SEEBECK’, ‘SIGMA’ or ‘SIGMAS’ types.
obj3 (Tensor) – Tensor object 3 of ‘KAPPA’, ‘SEEBECK’, ‘SIGMA’ or ‘SIGMAS’ types.

Returns:

cls (ZT) – ‘ZT’ type of object, in ‘dimensionless’.

plot(x_axis='potential', x_range=[], direction='xx', spin='sum', plot_series=[], plot_label=None, plot_color=None, plot_linestyle=None, plot_linewidth=None, zero_color='tab:gray', zero_linestyle='-', zero_linewidth=1.0, layout=None, title='default', figsize=[6.4, 4.8], legend='upper left', sharey=True, fontsize=14, fig=None, ax_index=None, **kwargs)

Plot tensor-like transport properties in multiple ways:

X_axis: Chemical potential $\mu$; Plot series: Temperature $T$.
X_axis: Carrier density $\rho(\mu; T)$; Plot series: Temperature $T$.
X_axis: Temperature $T$; Plot series: Chemical potential $\mu$.

For comparison of multiple systems, please refer to the plot.plot_transport_tensor() method.

Parameters:

x_axis (str) – X axis options, ‘potential’, ‘carrier’ or ‘temperature’. For meanings, see above.
x_range (list) – Display range of x axis. Y axis is self-adaptive.
direction (str|list) – Depending on the dimensionality of the system, including ‘xx’, ‘xy’, ‘xz’, ‘yx’, ‘yy’, ‘yz’, ‘zx’, ‘zy’ and ‘zz’. A list of options will generate nDirect*1 subplots. The direction of each subplot is annotated on the upper left corner.
spin (str) – Spin-polarized systems only. Electron spins to plot. ‘up’, ‘down’ or ‘sum’.
plot_series (list|array|float) – Values of the plot series. Should be commensurate with the choice of x_axis.
plot_label (list|str|None) – None for default values: plot_series and its unit. If str, prefixing that entry in front of the default value. If list, it should be 1*nPlotSeries for every plot line.
plot_color (list|str|None) – Similar to electronics.ElectronDOS.plot(). If str, use the same color for all the plot lines. If 1*nPlotSeries, use the same color for every plot line. If 2*nPlotSeries, use different colors for p-type and n-type carrier properties.
plot_linestyle (list|str|None) – Similar to electronics.ElectronDOS.plot(). See explanations of plot_color.
plot_linewidth (list|float|None) – Similar to electronics.ElectronDOS.plot(). See explanations of plot_color.
zero_color (str) – Color of the 0 value line.
zero_linestyle (str) – Linestyle of the 0 value line.
zero_linewidth (float) – Linewidth of the 0 value line.
layout (list[int]) – Layout of subplots. By default it is nDirection*1 gird of figures.
title (str|None) – Plot title. ‘default’ for the property plotted. ‘None’ for no title.
figsize (list) – Figure size.
legend (str|None) – Location of legend. None for not adding legend.
sharey (bool) – Share y axis for multiple subplots. Share x is enforced.
fontsize (float|int) – Font size of the title, subplot capations (direction), x and y axis capations.
fig (Figure) – Developer Only, matplotlib Figure class.
ax_index (list[int]) – Developer Only, indices of axes in fig.axes.
**kwargs – Other arguments passed to the matplotlib Axes.plot() method. Applied to all the plots.

Returns:

fig (Figure) – Matplotlib Figure object.

class Distribution(energy, distr, struc, type, unit)

Bases: object

The class for electron transport properties described by distribution, currently transport distribution function (TDF) only. Units must be consistent with the output files.

Parameters:

energy (array) – Energy in eV.
distr (array) – nEnergy*nDimen*nSpin Distribution function
carrier_density (array) – nT*nPot*nSpin array of carrier density in cm $^{-3}$. nDimen = 6 for 3D systems, 3 for 2D and 1 for 1D.
struc (CStructure) – Extended Pymatgen Structure object.
type (str) – ‘TDF’.
unit (str) – Same as output file.

Returns:

self (Distribution) – Attributes: ‘energy’, ‘function’, ‘type’, ‘struc’, ‘unit’ and ‘spin’

classmethod from_file(boltztra_out, output=None)

Read electron transport distribution functions (‘TDF.DAT’) by the BOLTZTRA keyword. Though currently the geometry information is not required, it is saved if the standard output file is given.

Parameters:: boltztra_out (str) – ‘DAT’ files by CRYSTAL BOLTZTRA keyword.
Returns:: cls (Distribution)

class Kappa(temperature, potential, carrier_density, tensor, struc)

Bases: Tensor

Themal conductivity $\kappa$. Inherited from transport.Tensor. Unit: W/m/K.

Parameters:

temperature (array) – Temperature in K
potential (array) – Chemical potential in eV.
carrier_density (array) – nT*nPot*nSpin array of carrier density in cm $^{-3}$.
tensor (array) – nT*nPot*nDimen*nSpin array of flattened tensor elements. nDimen = 6 for 3D systems, 3 for 2D and 1 for 1D.
struc (CStructure) – Extended Pymatgen Structure object.

Returns:

self (Kappa) – Attributes: ‘T’, ‘mu’, ‘carrier’, ‘data’, ‘type’, ‘struc’, ‘unit’ and ‘spin’

classmethod from_file(file, output=None)

Read the ‘KAPPA.DAT’ file. Though currently the geometry information is not required, it is saved if the standard output file is given.

Parameters:

file (str) – ‘KAPPA.DAT’ file.
output (str) – Properties output file.

Returns:

cls (Kappa)

class Sigma(temperature, potential, carrier_density, tensor, struc)

Bases: Tensor

Electrical conductivity $\sigma$. Inherited transport.Tensor. Unit: 1/Ohm/m.

Parameters:

temperature (array) – Temperature in K
potential (array) – Chemical potential in eV.
carrier_density (array) – nT*nPot*nSpin array of carrier density in cm $^{-3}$.
tensor (array) – nT*nPot*nDimen*nSpin array of flattened tensor elements. nDimen = 6 for 3D systems, 3 for 2D and 1 for 1D.
struc (CStructure) – Extended Pymatgen Structure object.

Returns:

self (Sigma) – Attributes: ‘T’, ‘mu’, ‘carrier’, ‘data’, ‘type’, ‘struc’, ‘unit’ and ‘spin’

classmethod from_file(file, output=None)

Read the ‘SIGMA.DAT’ file. Though currently the geometry information is not required, it is saved if the standard output file is given.

Parameters:

file (str) – ‘SIGMA.DAT’ file.
output (str) – Properties output file.

Returns:

cls (Sigma)

class Seebeck(temperature, potential, carrier_density, tensor, struc)

Bases: Tensor

Seebeck coefficient $S$. Inherited transport.Tensor. Unit: V/K.

Note

For Seebeck, spin is always 1 but its dimension is kept to be commensurate with other classes.

Parameters:

temperature (array) – Temperature in K
potential (array) – Chemical potential in eV.
carrier_density (array) – nT*nPot*1 array of carrier density in cm $^{-3}$.
tensor (array) – nT*nPot*nDimen*1 array of flattened tensor elements. nDimen = 6 for 3D systems, 3 for 2D and 1 for 1D.
struc (CStructure) – Extended Pymatgen Structure object.

Returns:

self (Seebeck) – Attributes: ‘T’, ‘mu’, ‘carrier’, ‘data’, ‘type’, ‘struc’, ‘unit’ and ‘spin’

classmethod from_file(file, output=None)

Read the ‘SEEBECK.DAT’ file. Though currently the geometry information is not required, it is saved if the standard output file is given.

Parameters:

file (str) – ‘SEEBECK.DAT’ file.
output (str) – Properties output file.

Returns:

cls (Seebeck)

class SigmaS(temperature, potential, carrier_density, tensor, struc)

Bases: Tensor

Electrical conductivity times Seebeck coefficient $\sigma S$. Inherited transport.Tensor. Unit: A/m/K.

Parameters:

temperature (array) – Temperature in K
potential (array) – Chemical potential in eV.
carrier_density (array) – nT*nPot*nSpin array of carrier density in cm $^{-3}$.
tensor (array) – nT*nPot*nDimen*nSpin array of flattened tensor elements. nDimen = 6 for 3D systems, 3 for 2D and 1 for 1D.
struc (CStructure) – Extended Pymatgen Structure object.

Returns:

self (SigmaS) – Attributes: ‘T’, ‘mu’, ‘carrier’, ‘data’, ‘type’, ‘struc’, ‘unit’ and ‘spin’

classmethod from_file(file, output=None)

Read the ‘SIGMAS.DAT’ file. Though currently the geometry information is not required, it is saved if the standard output file is given.

Parameters:

file (str) – ‘SIGMAS.DAT’ file.
output (str) – Properties output file.

Returns:

cls (SigmaS)

class PowerFactor(temperature, potential, carrier_density, tensor, struc)

Bases: Tensor

Thermoelectrical power factor $S^{2}\sigma$. Inherited transport.Tensor. Unit: W/m/K^2.

Parameters:

temperature (array) – Temperature in K
potential (array) – Chemical potential in eV.
carrier_density (array) – nT*nPot*nSpin array of carrier density in cm $^{-3}$.
tensor (array) – nT*nPot*nDimen*nSpin array of flattened tensor elements. nDimen = 6 for 3D systems, 3 for 2D and 1 for 1D.
struc (CStructure) – Extended Pymatgen Structure object.

Returns:

self (PowerFactor) – Attributes: ‘T’, ‘mu’, ‘carrier’, ‘data’, ‘type’, ‘struc’, ‘unit’ and ‘spin’

classmethod from_file(file1, file2, output=None)

Get thermoelectric power factor object from any 2 files of ‘SEEBECK’, ‘SIGMA’ or ‘SIGMAS’ types. Though currently the geometry information is not required, it is saved if the standard output file is given.

Note

Make sure all the entries are from the same calculation. The code only checks the dimensionalities of tensors. The geometry follows the first entry.

Parameters:

file1 (str) – File 1 in ‘SEEBECK’ ‘SIGMA’ or ‘SIGMAS’ types.
file2 (str) – File 2 in ‘SEEBECK’ ‘SIGMA’ or ‘SIGMAS’ types.
output (str) – Properties output file.

Returns:

cls (PowerFactor)

class ZT(temperature, potential, carrier_density, tensor, struc)

Bases: Tensor

Thermoelectric dimensionless figure of merit (ZT) $\frac{S^{r}\sigma T}{\kappa}$. Inherited transport.Tensor. Unit: dimensionless.

Parameters:

temperature (array) – Temperature in K
potential (array) – Chemical potential in eV.
carrier_density (array) – nT*nPot*nSpin array of carrier density in cm $^{-3}$.
tensor (array) – nT*nPot*nDimen*nSpin array of flattened tensor elements. nDimen = 6 for 3D systems, 3 for 2D and 1 for 1D.
struc (CStructure) – Extended Pymatgen Structure object.

Returns:

self (ZT) – Attributes: ‘T’, ‘mu’, ‘carrier’, ‘data’, ‘type’, ‘struc’, ‘unit’ and ‘spin’

classmethod from_file(file1, file2, file3, output=None)

Get ZT object from a ‘KAPPA’ file and any 2 files of ‘SEEBECK’, ‘SIGMA’ and ‘SIGMAS’. Though currently the geometry information is not required, it is saved if the standard output file is given.

Note

Make sure all the entries are from the same calculation. The code only checks the dimensionalities of tensors. The geometry follows the first entry.

Parameters:

file1 (str) – File 1 in ‘KAPPA’, ‘SEEBECK’ ‘SIGMA’ or ‘SIGMAS’ types.
file2 (str) – File 2 in ‘KAPPA’, ‘SEEBECK’ ‘SIGMA’ or ‘SIGMAS’ types.
file3 (str) – File 3 in ‘KAPPA’, ‘SEEBECK’ ‘SIGMA’ or ‘SIGMAS’ types.
output (str) – Properties output file.

Returns:

cls (PowerFactor)

class TDF(energy, distr, struc)

Bases: Distribution

Themal distribution function. Inherited from transport.Distribution. Unit: eV and 1/hbar^2*eV*fs/angstrom.

Parameters:

energy (array) – Energy in eV.
distr (array) – nEnergy*nDimen*nSpin Distribution function
carrier_density (array) – nT*nPot*nSpin array of carrier density in cm $^{-3}$. nDimen = 6 for 3D systems, 3 for 2D and 1 for 1D.
struc (CStructure) – Extended Pymatgen Structure object.

Returns:

self (Distribution) – Attributes: ‘energy’, ‘function’, ‘type’, ‘struc’, ‘unit’ and ‘spin’

classmethod from_file(file, output=None)

Read the ‘TDF.DAT’ file. Though currently the geometry information is not required, it is saved if the standard output file is given.

Parameters:

file (str) – ‘TDF.DAT’ file.
output (str) – Properties output file.

Returns:

cls (SigmaS)

CRYSTALpytools.units module

Constants and unit conversion used in CRYSTALpytools.

H_to_eV(energy)

eV_to_H(energy)

H_to_kjmol(energy)

kjmol_to_H(energy)

au_to_angstrom(length)

angstrom_to_au(length)

cm_to_thz(freq)

thz_to_cm(freq)

hartree_to_thz(freq)

thz_to_hartree(freq)

amu_to_me(mass)

me_to_amu(mass)

GPa_to_au(pressure)

au_to_GPa(pressure)

ampere_to_au(current)

au_to_ampere(current)

CRYSTALpytools.utils module

Created on 29/03/2022

help(folder='./')

view_pmg(pmg_structure)

CRYSTALpytools package

Subpackages

Submodules

CRYSTALpytools.adsorb module

CRYSTALpytools.calculate module

CRYSTALpytools.convert module

CRYSTALpytools.crystal_io module

CRYSTALpytools.elastics module

CRYSTALpytools.electronics module

CRYSTALpytools.execute module

CRYSTALpytools.geometry module

CRYSTALpytools.phonons module

CRYSTALpytools.plot module

CRYSTALpytools.relativistics module

CRYSTALpytools.spectra module

CRYSTALpytools.thermodynamics module

CRYSTALpytools.topond module

CRYSTALpytools.transport module

CRYSTALpytools.units module

CRYSTALpytools.utils module

Module contents