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

CRYSTALpytools.base package

Submodules

CRYSTALpytools.base.basisset module

Basis set definitions.

class AtomBS(z, nshell, ECP=None)

Bases: object

Basis set class for CRYSTALpytools

Parameters:

  • z (int) – Conventional atomic number

  • nshell (int) – Number of shells

  • ECP (str) – Effective core potential, printed before basis sets

define_a_shell(ITYB, LAT, NG, CHE, SCAL, orbitals=[])

Define shells of atomic basis sets. Arguments are consistent with CRYSTAL manual.

Parameters:

  • ITYB (int) – Type of Gaussain orbitals

  • LAT (int) – Angular momentum

  • NG (int) – Number of Gaussian orbitals

  • CHE (float) – Charge

  • SCAL (float) – Scaling factor

  • orbitals (list) – nGTO*2 or nGTO*3 (sp type) list of exponent and contraction factors

Returns:

obj (AtomBS)

classmethod read_bse(bs, z)

Read basis sets saved in Basis Set Exchange(BSE) dictionary format and assign charge.

Note

All electron basis sets only. Atoms are charge neutral.

Parameters:

  • bs (str) – Name of basis set

  • z (int) – Conventional atomic number

Returns:

obj (AtomBS)

classmethod read_crystal(text)

Analyze text in CRYSTAL format.

print_crystal()

Print basis set into CRYSTAL format

class BasisSetBASE(atoms=[])

Bases: object

The basisset object base object, as the class of basis sets defined for the whole system. Basis sets from string, file or Basis Set Exchange(BSE), can be read and saved as a list of AtomBS objects.

classmethod from_bse(bs, z)

Get or append basis sets from Basis Set Exchange(BSE).

Parameters:

  • bs (str) – Name of basis set. Only one name is accepted.

  • z (int | list[int]) – Conventional atomic number.

Returns:

cls

classmethod from_string(bs, fmt='crystal')

Parse basis set strings.

Parameters:

  • bs (str) – Basis set string.

  • fmt (str) – Format string. Consistent with BSE python API. For non- CRYSTAL formats, only all-electron basis sets are supported. Charge of each shell will be automatically assigned to get charge neutral atoms if fmt is not ‘crystal’.

Returns:

cls

classmethod from_file(bs, fmt='crystal')

Parse basis set files.

Parameters:

  • bs (str) – Basis set file.

  • fmt (str) – Format string. Consistent with BSE python API. For non- CRYSTAL formats, only all-electron basis sets are supported. Charge of each shell will be automatically assigned to get charge neutral atoms.

Returns:

cls

print_crystal()

Print the information into CRYSTAL basis set format

CRYSTALpytools.base.crysd12 module

Classes and methods of keywords used in ‘crystal’ input file (d12).

class Crystal_inputBASE(geba=False)

Bases: BlockBASE

The base class of Crystal_input class

Parameters:

geba (bool) – Whether it is a normal d12 object or a GEBA subblock

property geom

Geometry subblock

property basisset

Basis set subblock

property scf

SCF subblock

property data

Settings in all the attributes are summarized here.

analyze_text(data)

Analyze formatted d12 file. A ‘complete’ d12 file with geometry, basis set and SCF blocks is suggested.

Parameters:

data (str) – Formatted string.

class Geom

Bases: BlockBASE

Geometry block object

property data

Settings in all the attributes are summarized here. Covers the data property in BlockBASE, to address the ambiguity of ‘MOLECULE’ keywords.

analyze_text(text)

Overrides the same method from parent class for title line.

title(title='Generated by CRYSTALpytools')
crystal(IGR='', latt=[], atom=[], IFLAG=0, IFHR=0, IFSO=0, origin=[])

Define ‘CRYSTAL’ structure

Parameters:

  • sg (int) – Space group number. Parameter IGR in the manual

  • latt (list) – Minimal set of crystallographic cell parameters

  • atom (list) – Natom * 4 list of conventional atomic number and 3D fractional coordinates.

  • IFLAG (int) – See the manual

  • IFHR (int) – See the manual

  • IFSO (int) – See the manual

  • origin (list) – IFSO > 1 See the manual

slab(IGR='', latt=[], atom=[])

Define ‘SLAB’ structure

polymer(IGR='', latt=[], atom=[])

Define ‘POLYMER’ structure

helix(N1='', N2=0, latt=[], atom=[])

Define ‘HELIX’ structure

Parameters:

  • N1 (int) – See the manual

  • N2 (int) – See the manual

molecule(IGR='', atom=[])

Define ‘MOLECULE’ structure

external(external='')

Define ‘EXTERNAL’ structure

dlvinput(dlvinput='')

Define ‘DLVINPUT’ structure

supercel(mx='')

Supercell by ‘SUPERCEL’ keyword

Parameters:

mx (array | list | str) – ndimen * ndimen matrix, None or ''

supercon(mx='')

Supercell by ‘SUPERCON’ keyword

scelconf(mx='')

Supercell by ‘SCELCONF’ keyword

scelphono(mx='')

Supercell by ‘SCELPHONO’ keyword

elastic(IDEF='', mx='')
atombsse(IAT='', NSTAR=None, RMAX=None)
atomdisp(NDISP='', atom=[])

ATOMDISP keyword

Parameters:

  • NDISP (int) – See manual

  • atom (list) – NDISP*4 list. Including LB, DX, DY, DZ

atominse(NINS='', atom=[])

ATOMINSE keyword

Parameters:

  • NINS (int) – See manual

  • atom (list) – NINS*4 list. Including NA, X, Y, Z

atomorde(atomorde='')
atomremo(NL='', atom=[])

ATOMREMO keyword

Parameters:

  • NL (int) – See manual

  • atom (list) – NL*1 list. Including LB

atomsubs(NSOST='', atom=[])

ATOMSUBS keyword

Parameters:

  • NSOST (int) – See manual

  • atom (list) – NSOST*2 list. Conventional atomic number of atoms to be substituted and to substituted

molecule2(NMOL='', atom=[])

Note

Corresponds to the option MOLECULE to isolate molecules from lattice. Only the method’s name is changed to avoid ambiguity with the one to set 0D geometry.

Parameters:

  • NMOL (int)

  • atom (list[list[int]]) – NMOL*4 list. See CRYSTAL manual.

extprt(extprt='')
cifprt(cifprt='')
cifprtsym(cifprtsym='')
coorprt(coorprt='')
testgeom(testgeom='')
property optgeom

Subblock object OPTGEOM

property freqcalc

Subblock object FREQCALC

class Optgeom

Bases: BlockBASE

OPTGEOM block object

fulloptg(fulloptg='')
cellonly(cellonly='')
intredun(intredun='')
itatocel(itatocel='')
cvolopt(cvolopt='')
hessiden(hessiden='')
hessmod1(hessmod1='')
hessmod2(hessmod2='')
hessnum(hessnum='')
toldeg(TG=0.0003)
toldex(TX=0.0012)
toldee(IG=7)
maxcycle(MAX=50)
fragment(NL='', LB=[])
Parameters:

  • NL (int | str) – Number of atoms. See manual

  • LB (list[int]) – Label of atoms. See manual

restart(restart='')
finalrun(ICODE=4)
extpress(pres='')
allowtrustr(allowtrustr='')
notrustr(notrustr='')
maxtradius(TRMAX=4.0)
trustradius(TRADIUS=0.5)
onelog(onelog='')
noxyz(noxyz='')
nosymmops(nosymmops='')
printforces(printforces='')
printhess(printhess='')
printopt(printopt='')
print(prt='')
tsopt(tsopt='')
modefollow(MODEFOL='')
pathfollow(NPATHFOL='')
fittopath(NPATHFOL2='', NPATHWEIGHT='')
chngtsfol(chngtsfol='')
scanatom(NATSCAN='', TARGET='', MSCAN='')
scanredu(IREDSCA='', ENDSCA='', MAXSCA='')
class Freqcalc

Bases: BlockBASE

FREQCALC block object

nooptgeom(nooptgeom='')
property preoptgeom

Subblock object PREOPTGEOM

dispersion(dispersion='')
bands(ISS='', NSUB=None, NLINE=None, points=[])
modes(modes='')
nomodes(nomodes='')
numderiv(N=1)
pressure(NP='', P1=None, P2=None)
restart(restart='')
stepsize(STEP=0.003)
temperat(NT='', T1=None, T2=None)
class BasisSet

Bases: BlockBASE

Basis Set block object

property data

Settings in all the attributes are summarized here. Covers the data property in BlockBASE, to deal with user’s definition of basis sets.

analyze_text(text)

Analyze the input and return to corresponding attributes. Add support to basis set strings

basisset(NAME='')
ghosts(NA='', LA=[])
from_bse(name, z, append=False)

Download basis set definitions from Basis Set Exchange (BSE).

Parameters:

  • name (str) – Basis set’s name.

  • z (list[int]) – List of elements, specified by conventional atomic numbers.

  • 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

from_string(string, fmt='crystal', append=False)

Basis set from a string

Parameters:

  • string (str) – Basis set definition.

  • fmt (str) – Format string. Consistent with BSE python API. For non-CRYSTAL formats, only all-electron basis sets are supported. Charge of each shell will be automatically assigned to get charge neutral atoms.

  • 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

from_file(file, fmt='crystal', append=False)

Basis set from a file

Parameters:

  • file (file) – Basis set definition.

  • fmt (str) –

    Format string. Consistent with BSE python API. For non-CRYSTAL formats, only all-electron basis sets are supported. Charge of each shell will be automatically assigned to get charge neutral atoms.

  • 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

from_obj(bs_obj, append=False)

Define basis set from a base.basisset.BasisSetBASE object.

Parameters:

  • bs_obj (BasisSetBASE)

  • 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

class SCF

Bases: BlockBASE

SCF block object

property data

Print formatted input. Redefined to address the END keywords of FIXINDEX blocks

rhf(rhf='')
uhf(uhf='')
rohf(NSPIN='')
property dft

Subblock object DFT

property hf3c

Subblock object HF3C

property hfsol3c

Subblock object HFSOL3C

property dftd3

Subblock object DFTD3

property gcp

Subblock object GCP

gcpauto(gcpauto='')
atomspin(NA='', LA=[])
toldee(ITOL=6)
guessp(guessp='')
maxcycle(MAX=50)
ldremo(value='')
smear(WIDTH='')
levshift(ISHIFT='', ILOCK='')
shrink(IS='', ISP='', IS1='', IS2='', IS3='')

Shrink parameters.

tolinteg(ITOL1=7, ITOL2=7, ITOL3=7, ITOL4=7, ITOL5=14)
biposize(ISIZE=4000000)
exchsize(ISIZE=4000000)
bipolar(ITCOUL=18, ITEXCH=14)
nobipola(nobipola='')
nobipcou(nobipcou='')
nobipexc(nobipexc='')
fmixing(IPMIX=30)
diis(diis='')
nodiis(nodiis='')
diisallk(diisallk='')
sloshing(sloshing='')
histdiis(NCYC='')
thrediis(DEDIIS='')
thrkdiis(DIISTHR='')
sloshfac(FKERK=1.2)
prtdiis(prtdiis='')
anderson(anderson='')
broyden(W0=0.0001, IMIX=50, ISTART=2)
ppan(ppan='')
gradcal(gradcal='')
exchange(exchange='')
postscf(postscf='')
cmplxfac(WEIGHT=2.0)
repldata(repldata='')
stdiag(stdiag='')
fixindex(fixindex='')

Fixindex keywords.

Note

‘GEOM’ is a Geom object. To modify keywords (‘CRYSTAL’ as example), use input.scf.geom.crystal().

‘BASE’ is a BasisSet object. To define basis set from bse, use input.scf.base.from_bse().

‘GEBA’ is a Crystal_inputBASE object. To modify keywords (‘CRYSTAL’ as example), use input.scf.geba.geom.crystal().

property geom

Subblock object GEOM

property base

Subblock object BASE

property geba

Subblock object GEBA

class HF3C

Bases: BlockBASE

HF3C block object

rescales8(s8='')
scalegcp(gcp='')
class HFSOL3C

Bases: HF3C

HFSOL3C block object

class DFT

Bases: BlockBASE

DFT block object

spin(spin='')
exchange(ex='')
correlat(cor='')
xcfunc(xc='')
sr_omega(sr_omega='')
mr_omega(mr_omega='')
lr_omega(lr_omega='')
sr_hyb_wb97x(sr_c='')
lsrsh_pbe(omega='', sr_c=0.0, lr_c=0.0)
lgrid(lgrid='')
oldgrid(oldgrid='')
xlgrid(xlgrid='')
xxlgrid(xxlgrid='')
xxxlgrid(xxxlgrid='')
hugegrid(hugegrid='')
radial(NR='', RL=[], IL=[])
angular(NI='', AL=[], LEV=[])
class DFTD3

Bases: BlockBASE

DFTD3 block object

version(NAT=4)
func(CHAR='')
abc(abc='')
s6(s6='')
s8(s8='')
a1(a1='')
a2(a2='')
rs6(rs6='')
rs8(rs8='')
radius(radius='')
cnradius(cnradius='')
abcradius(abcradius='')
printc6(printc6='')
class GCP

Bases: BlockBASE

GCP block object

method(method='')
sigma(sigma='')
alpha(alpha='')
beta(beta='')
eta(eta='')
radius(radius='')
printemiss(printemiss='')

CRYSTALpytools.base.extfmt module

Classes and methods to parse multiple external output formats by ‘crystal’ and ‘properties’ executables, such as ‘BAND.DAT’ and ‘fort.25’ formats.

class CrgraParser

Bases: object

A collection of functions to parse Crgra fort.25 files. Instantiation of this object is not recommaneded.

classmethod band(filename)

Parse fort.25 file for electron / phonon band structure(‘-%-BAND’). Unit: eV / THz. E Fermi is aligned to 0.

Parameters:

filename (str) – File name

Returns:

  • spin (int) – 1, closed shell; 2, open shell

  • tick_pos (array) – n_tick*1 array of 1D tick coordinates. Unit: Angstrom

  • tick_label (list) – n_tick*1 of default tick labels

  • efermi (float) – Fermi energy. Unit: eV. 0 for phonon bands.

  • bands (array) – n_bands*n_kpoints*spin array of energy / frequency. Unit: eV / THz

  • k_path (array) – 1D coordinates of k points. Unit: Angstrom

  • unit (str) – ‘eV’ or ‘THz’

classmethod dos(filename)

Parse fort.25 file for electron / phonon density of states (‘-%-DOSS’ and ‘-%-PDOS’). Unit: eV^-1 / THz^-1. E Fermi is aligned to 0. All projections must have the same energy / frequency range

Parameters:

filename (str) – File name

Returns:

  • spin (array) – 1, closed shell; 2, open shell

  • efermi (float) – Fermi energy. Unit: eV. 0 for phonon bands.

  • doss (array) – n_proj*n_energy*spin array of DOS. Positive values for both spin up and spin down states

  • energy (int) – Number of sampling points (energy or frequency).

  • unit (str) – ‘eV’ or ‘THz’

classmethod mapn(filename, index)

Parse fort.25 file for 2D isovalue maps generated by the ‘MAPNAT’ formatted keyword block (‘-%-MAPN’). Unit: a.u.

Parameters:

  • filename (str) – File name

  • index (int|list|None) – The sequence of ‘-%-MAPN’ headers starting from 0. List inputs are accepted. ‘None’ to read the first 1(2) MAPN entries for spin=1(2).

Returns:

  • spin (array) – 1, closed shell; 2, open shell

  • all_a (array|list) – 3D Cartesian coordinates of MAPNET point A. 1*3 array of index is an integer or 1*1 list. 1*nIndex list otherwise. Same below.

  • all_b (array|list) – 3D Cartesian coordinates of MAPNET point B

  • all_c (array|list) – 3D Cartesian coordinates of MAPNET point C

  • all_cosxy (float|list) – Cosine of vector AB and BC

  • all_struc (CStructure|list) – Extended Pymatgen Structure object.

  • all_map (array|list) – 2D scalar field map commensurate with MAPNET defined above, nY*nX*nSpin.

  • unit (str) – ‘a.u.’

class DLVParser

Bases: object

A collection of functions to parse DLV / Xmgrace files. Instantiation of this object is not recommaneded.

classmethod band(filename)

Parse BAND.DAT / PHONBANDS.DAT file for electron / phonon band structure. Unit: eV / THz. E Fermi is aligned to 0.

Parameters:

filename (str) – BAND.DAT or PHONBANDS.DAT.

Returns:

  • spin (int) – 1, closed shell; 2, open shell

  • tick_pos (array) – n_tick*1 array of 1D tick coordinates. Unit: Angstrom

  • tick_label (list) – n_tick*1 of default tick labels

  • efermi (float) – Fermi energy. Unit: eV. 0 for phonon bands.

  • bands (array) – n_bands*n_kpoints*spin array of energy / frequency. Unit: eV / THz

  • k_path (array) – 1D coordinates of k points. Unit: Angstrom

  • unit (str) – ‘eV’ or ‘THz’

classmethod dos(filename)

Parse DOSS.DAT / PHONDOS.DAT file for electron / phonon density of states. Unit: eV^-1 / THz^-1. E Fermi is aligned to 0. All projections must have the same energy / frequency range

Parameters:

filename (str) – File name

Returns:

  • spin (array) – 1, closed shell; 2, open shell

  • efermi (float) – Fermi energy. Unit: eV. 0 for phonon bands.

  • doss (array) – n_proj*n_energy*spin array of DOS. Positive values

  • energy (int) – Number of sampling points (energy or frequency).

  • unit (str) – ‘eV’ or ‘THz’

classmethod fort35(filename)

Keyword ‘DLV_BAND’. For 3D band structures in reciprocal space. 3D and 2D systems only.

Returns:

  • rlatt (array) – 3*3 reciprocal lattice matrix in Bohr.

  • bandnew (array) – nBand*nZ*nY*nX*nSpin array of 3D band in Hartree.

  • unit (str) – ‘a.u.’

class TOPONDParser

Bases: object

A collection of functions to parse TOPOND output files. Instantiation of this object is not recommaneded.

classmethod contour2D(filename)

Parse TOPOND 2D scalar contour plot files (SURF*.DAT). Unit: a.u.

Parameters:

filename (str)

Returns:

  • spin (array) – Always 1

  • a (array) – 3D Cartesian coordinates of MAPNET point A (xmin, ymax)

  • b (array) – 3D Cartesian coordinates of MAPNET point B (xmin, ymin)

  • c (array) – 3D Cartesian coordinates of MAPNET point C (xmax, ymin)

  • cosxy (float) – Always 0

  • struc (None) – Always None

  • map (array) – 2D scalar field map commensurate with MAPNET defined above. nY*nX*1 (spin dimension kept but no use).

  • unit (str) – ‘a.u.’

classmethod traj(filename)

Parse TOPOND trajectory plot files (TRAJ*.DAT). Unit: a.u.

Parameters:

filename (str)

Returns:

  • wtraj (list[int]) – 1*nPath, weight of the path

  • traj (list[array]) – 1*nPath, list of critical paths. Every array is the nPoint*3 3D ref framework coordinates of points on the path.

  • unit (str) – ‘a.u.’

class BOLTZTRAParaser

Bases: object

A collection of functions to parse BOLTZTRA output files. Instantiation of this object is not recommaneded.

classmethod tensor(filename)

Read properties in tensor forms, include KAPPA, SEEBECK, SIGMA, SIGMAS.

Returns:

  • spin (int) – 1 for closed shell and 2 for open shell.

  • type (str) – Type of tensor output.

  • v (float) – Volume in cm:math:^{3}.

  • t (array) – Temperature in K.

  • mu (array) – Chemical potential in eV.

  • dc (array) – nT*nMu*nspin array of carrier density. Unit: cm:math:^{-3}.

  • tensor (array) – nT*nMu*ndimen*nspin array of tensor elements.

  • unit (str) – Unit of tensor.

classmethod distribution(filename)

Read transport distribution function.

Returns:

  • spin (int) – 1 for closed shell and 2 for open shell.

  • type (str) – Type. Currently only ‘TDF’

  • energy (array) – nEnergy*nspin array, Energy in eV.

  • distr (array) – nEnergy*nDimen*nspin array of distribution. Unit: \(\hbar^{-2}.eV.fs.\AA^{-2}\).

class CUBEParser

Bases: object

A collection of functions to parse CRYSTAL CUBE files. Instantiation of this object is not recommaneded.

Note

Developed especially for CUBE formatted output of CRYSTAL. Lattice parameters must be included in the comment line in Bohr and degree.

classmethod read_cube(filename)

Read CUBE formatted files. For base vectors, they are defined by 4 points, origin, a, b and c.

Parameters:

filename (str)

Returns:

  • origin (array) – 1*3 Cartesian coordinates of origin. Unit: \(\AA\).

  • a (array) – 1*3 Cartesian coordinates of grid x base vector end. Unit: \(\AA\).

  • b (array) – 1*3 Cartesian coordinates of grid y base vector end. Unit: \(\AA\).

  • c (array) – 1*3 Cartesian coordinates of grid z base vector end. Unit: \(\AA\).

  • struc (CStructure) – Extended Pymatgen Structure object.

  • grid (array) – nZ*nY*nX array of 3D data grid.

  • unit (str) – Data grid unit, ‘a.u.’

CRYSTALpytools.base.inputbase module

Base object of all the input (d12/d3) blocks.

class BlockBASE(bg, ed, dic)

Bases: object

The base class of ‘block’ objects

Parameters:

  • bg (str) – Beginning line. Keyword or title

  • ed (str) – Ending line.

  • dic (dict) – Keyword and value (in text) pairs. Format is listed below.

Returns:

  • self (BlockBASE) – New attributes listed below

  • self._block_bg (str) – Keyword of the block

  • self._block_ed (str) – End of block indicator, ‘END’

  • self._block_data (str) – Formatted text string for d12.

  • self._block_dict (dict) – Keyword and value (in text) pairs. Key: CRYSTAL keyword in string. Value: A 3*1 or 4*1 list, see below. * 1st element: For keywords: String, formatted output; None, not including the keyword; '', keyword only * 1st element: For subblocks: Name of the ‘real’ attribute (protected by property decorator) * 2nd: bool, whether it is a sub-block or not; * 3rd: A list of conflicting keywords. * 4th: Subblock only. String that initializes the subblock object.

  • self._block_key (list) – Allowed keyword list

  • self._block_valid (bool) – Whether this block is valid and for print.

property data

Settings in all the attributes are summarized here.

assign_keyword(key, shape, value='')

Transform value into string formats.

Parameters:

  • shape (list[int]) – 1D list. Shape of input text. Length: Number of lines; Element: Number of values

  • value (list | str) – List, a 1D list of arguments; '' or a list begins with '', return to ''; None or a list begins with None, return None.

Returns:

text (str) – CRYSTAL input

static set_matrix(mx)

Set matrix-like data to get assign_keyword inputs. Used for supercell expansion matrix and strain tensor.

Parameters:

mx (list | str) – ndimen*ndimen list, None, or ''

Returns:

  • shape (list) – ndimen*1 1D list. All elements are ndimen.

  • value (list) – ndimen*2*1 1D list. Flattened matrix.

static set_list(*args)

Set list-like data to get assign_keyword inputs. Used for lists with known dimensions. Such as atom coordinate list.

Parameters:

*args – '', Clean data; None, Return keyword only; int, list, int for length of the list, list for list data

Returns:

  • shape (list) – 1 + length 1D list or []

  • args (list) – Flattened list, [] or ‘’

clean_conflict(key)

Addressing the conflictions between keywords.

Parameters:

key (str) – The keyword specified.

update_block()

Update the _block_data attribute: Summarizing all the settings to _block_data attribute for inspection and print

analyze_text(text)

Analyze the input text and return to corresponding attributes

CRYSTALpytools.base.output module

Classes and methods to parse the output files (screen output, or .out and .outp files) of ‘crystal’ and ‘properties’ executables.

class GeomBASE

Bases: object

A container of basic methods for SCF geometry.

classmethod read_geom(data)

Read lattice from ‘A B C ALPHA BETA GAMMA’ block, periodic boundary condition and atom positions from ‘ATOMS IN THE ASYMMETRIC UNIT’ block. It terminates at the first empty line after that block.

Parameters:

data (DataFrame) – Pandas DataFrame of the output

Returns:

struc (CStructure) – Extended Pymatgen Structure

class SCFBASE

Bases: object

A container of basic methods for SCF loop.

classmethod get_SCF_blocks(data)

Get SCF convergence block from output file.

Parameters:

data (DataFrame) – Pandas DataFrame of the output.

Returns:

  • nSCF (int) – Number of SCF blocks

  • SCFrange (array[int, int]) – The beginning and ending points of every SCF block.

classmethod read_convergence(data)

Read a SCF convergence block.

Parameters:

data (DataFrame) – Pandas DataFrame of the SCF convergence block.

Returns:

  • ncyc (int) – Number of cycles

  • endflag (str) – ‘terminated’, ‘converged’, ‘too many cycles’ and ‘unknown’

  • e (array) – nCYC*1 array of SCF energy. Unit: eV

  • de (array) – nCYC*1 array of SCF energy difference. Unit: eV

  • spin (bool) – Whether the system is spin-polarised.

  • efermi (array) – Fermi energy. Unit: eV

  • gap (array) – Band gap. Unit: eV

class OptBASE

Bases: object

A container of basic methods for Opt loop.

classmethod get_opt_block(data)

Get optimization convergence block (every OPT step) from output file.

Parameters:

data (DataFrame) – Pandas DataFrame of the output.

Returns:

  • nOPT (int) – Number of OPT steps

  • OPTrange (array[int, int]) – The beginning and ending points of every OPT step.

  • endflag (str) – ‘terminated’, ‘converged’, ‘failed’ and ‘unknown’

classmethod read_opt_block(data)

Read information of every OPT step from output file.

Parameters:

data (DataFrame) – Pandas DataFrame of the output.

Returns:

  • e (float) – Final SCF energy with corrections. Unit: eV

  • de (float) – Final SCF energy difference with last OPT step. Unit: eV

  • struc (CStructure) – Modified pymatgen structure.

  • maxg (float) – Max energy gradient convergence. Unit: Hartree / Bohr.

  • rmsg (float) – RMS energy gradient convergence. Unit: Hartree / Bohr,

  • maxd (float) – Max displacement convergence. Unit: Bohr.

  • rmsd (float) – RMS displacement convergence. Unit: Bohr.

class PhononBASE

Bases: object

A container of basic methods for phonon information.

classmethod readmode_basic(data, IRREP)

Read basic frequency information.

Parameters:

  • data (Series) – Pandas series. The block containing frequency info.

  • IRREP (list[str]) – Irreducible representations in Mulliken symbols. Used for phonon dispersion only.

Returns:

  • frequency (array[float]) – nmode * 1

  • mode_symm (array) – nmode * 1

  • intens (array[float]) – nmode * 1

  • IR (array[bool]) – nmode * 1

  • Raman (array[bool]) – nmode * 1

classmethod readmode_eigenvector(data, nmode)

Get mode eigenvectors.

Returns:

eigvt (array[float]) – nmode*natom*3 array.

classmethod classical_amplitude(struc, freq)

Get classical amplitude of phonon modes Under Testing

\[x = \sqrt{\frac{\hbar}{\mu\omega}}\]
Parameters:

  • struc (Structure) – Pymatgen structure

  • freq (float|array) – Frequency. Unit: THz

Returns:

classic_a (array) – nfreq*3natom*3natom array, or 3natom*3natom if freq is float. The diagonal matrix of classical amplitude.

classmethod normalize_eigenvector(eigvt, amplitude=1.0)

Normalize the mode of eigenvectors.

Parameters:

  • eigvt (array[complex]) – nmode*natom*3 array.

  • amplitude (float) – Amplitude of normalization

Returns:

eigvt (array[complex]) – Normalized eigenvector.

classmethod clean_q_overlap(crysout, threshold)

Remove the repeated q points at both ends of line segment when dispersion is read. The weight of q points will be updated here.

Parameters:

  • crysout (Crystal_output) – CRYSTALpytools.crystal_io.Crystal_output object

  • threshold (float) – The q point overlap threshold.

classmethod clean_imaginary(crysout, threshold)

Set negative frequenceies and related properteis to 0 and print warning message. Eigenvectors are kept.

Parameters:

  • crysout (Crystal_output) – CRYSTALpytools.crystal_io.Crystal_output object

  • threshold (float) – The threshold to identify a phonon mode as negative.

class POutBASE(filename)

Bases: object

Base object for Properties output file. Auxiliary information is substracted. Other data is read from formatted files respectively.

Parameters:

filename (str) – Properties output file name.

get_geometry()

Get geometry from properties output calculation.

Returns:

struc (CStructure) – Modified Pymatgen structure

get_lattice()

Get lattice matrix from properties output calculation. A 3D lattice is generated since no dimensionality information is provided.

Returns:

matrix (array) – 3*3 lattice matrix

get_topond_geometry()

Get the cluster geometry and plot plane base (2D only) from TOPOND calculation output.

Returns:

  • atomsplt (array) – Atomic numbers and coordinates in plotting frame.

  • base (array) – Valid for 2D plots only 3*3 range of orthogonal plotting base x and y. A: (xmin, ymax), B: (xmin, ymin), C: (xmax, ymin). Unit: Bohr.

get_reciprocal_lattice()

Get reciprocal lattice matrix from properties output calculation. A 3D lattice is generated since no dimensionality information is provided.

Returns:

matrix (array) – 3*3 reciprocal lattice matrix

get_3dkcoord()

BANDS calculation only. Get 3D fractional coordinates of high-symmetry and sampled k points from output file.

Returns:

  • tick_pos3d (array) – ntick*3 array of fractional coordinates of high symmetry k points

  • k_pos3d (array) – nkpoint*3 fractional coordinates of k points

get_XRDSPEC()

The keyword ‘XRDSPEC’ only. Get calculated XRD spectra.

get_Fermi()

Get Fermi energy in eV from the common block.

CRYSTALpytools.base.plotbase module

Base functions for plotting 2D and 3D figures

plot_overlap_bands(ax, bands, k_xax, k_path, k_label, energy_range, k_range, band_label, band_color, band_linestyle, band_linewidth, fermi, fermi_color, fermi_linestyle, fermi_linewidth, legend, **kwargs)

The plotting function for overlapped band structures of electron or phonon. Also can be used to get a single band.

Note

You must specify colors in string. List of RGB values are not allowed and might lead to unexpected errors.

Parameters:

  • ax (Axes) – Matplotlib Axes object. To be passed from wrapper functions.

  • bands (list) – Band structure, 1*nSystem list of nBand*nKpoint*nSpin numpy arrays.

  • k_xax (list) – Coordinates of x axis. 1*nSystem list.

  • k_path (list) – Coordinates of high-symmetric k points, 1*nSystem list of 1*nTick numpy arrays. Unit: \(\AA^{-1}\).

  • k_label (list[str] | None) – 1*nTick list of strings of the label for high symmetry points along the path. mathtext experssions can also be used as in matplotlib.

  • energy_range (list) – 1*2 list of plotting energy range.

  • k_range (list) – 1*2 list of plotting k range. Can either be length (float) or k label (str). Must be used with not_scaled=False and the same set of k_label.

  • band_label (list) – 1*nSystem or nSystem*2 (spin) plot legend. If spin>1 and 1*nSystem list is used, they are marked with the same label.

  • band_color (list) – 1*nSystem or nSystem*2 (spin) plot color. If spin >1 and 1*nSystem list is used, they are in the same color.

  • band_linestyle (list) – 1*nSystem or nSystem*2 (spin) linestyle string. If spin>1 and 1*nSystem list is used, they are in the same style.

  • band_linewidth (list) – 1*nSystem or nSystem*2 (spin) width of the plot lines. If spin>1 and 1*nSystem list is used, they are in the same width.

  • fermi (float | None) – Fermi energy. By default the band is aligned to 0. Can be used to offset the band. None for not plotting Fermi level.

  • fermi_color (str) – Color of the Fermi level.

  • fermi_linestyle (str) – Line style of Fermi level.

  • fermi_linewidth (float) – Width of the Fermi level.

  • legend (str|None) – Loc parameter passed to axes.legend() None for not adding legend.

  • **kwargs – Other commands passed to matplotlib axes.plot() method when plotting bands. Applied to all bands.

Returns:

ax (Axes) – Matplotlib Axes object.

plot_compare_bands(ax, bands, k_xax, k_path, k_label, not_scaled, energy_range, k_range, band_label, band_color, band_linestyle, band_linewidth, fermi, fermi_color, fermi_linestyle, fermi_linewidth, legend, **kwargs)

The plotting function for band structures of electron or phonon in different panels.

Note

You must specify colors in string. List of RGB values are not allowed and might lead to unexpected errors.

Parameters:

  • ax (Axes) – Matplotlib Axes object or a flatted list of them. To be passed from wrapper functions.

  • bands (list) – Band structure, 1*nSystem list of nBand*nKpoint*nSpin numpy arrays.

  • k_xax (list) – Coordinates of x axis. 1*nSystem list.

  • k_path (list) – Coordinates of high-symmetric k points, 1*nSystem list of 1*nTick numpy arrays. Unit: \(\AA^{-1}\).

  • 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.

  • not_scaled (bool) – Whether to scale the x-axis for different volumes.

  • energy_range (list) – 1*2 list of plotting energy range.

  • k_range (list) – 1*2 list of plotting k range. Can either be length (float) or k label (str). Must be used with not_scaled=False and the same set of k_label.

  • band_label (list) – 1*nSystem or nSystem*2 (spin) plot legend. If spin>1 and 1*nSystem list is used, they are marked with the same label.

  • band_color (list|str) – A color string or 1*2 color list for spin. If nSpin>1 but a string is given, same color for both spins.

  • band_linestyle (list|str) – A linestyle string or 1*2 linestyle list for spin. If nSpin>1 but a string is given, same linestyle for both spins.

  • band_linewidth (list|float) – A linewidth number or 1*2 linewidth list for spin. If nSpin>1 but a string is given, same linewidth for both spins.

  • fermi (float | None) – Fermi energy. By default the band is aligned to 0. Can be used to offset the band. None for not plotting Fermi level.

  • fermi_color (str) – Color of the Fermi level.

  • fermi_linestyle (str) – Line style of Fermi level.

  • fermi_linewidth (float) – Width of the Fermi level.

  • legend (str|None) –

    Loc parameter passed to axes.legend() None for not adding legend.

  • **kwargs – Other commands passed to matplotlib axes.plot() method when plotting bands. Applied to all bands.

Returns:

ax (Axes) – Matplotlib Axes object or a flatted list of them.

plot_doss(ax, doss, energy, beta, prj, energy_range, dos_range, dos_label, dos_color, dos_linestyle, dos_linewidth, fermi, fermi_color, fermi_linestyle, fermi_linewidth, legend, plot_vertical, **kwargs)

The base function to plot electron / phonon density of states on one axes.

Parameters:

  • ax (Axes) – Matplotlib Axes object.

  • doss (numpy.ndarray) – nProj*nEnergy*nSpin array of DOS. Positive values for both spin up and spin down states.

  • energy (numpy.ndarray) – 1*nEnergy array of energy.

  • beta (str) – Plot settings for \(eta\) states (‘up’ or ‘down’).

  • prj (list) – Index of selected projections, consistent with the first dimension of the doss, starting from 1.

  • energy_range (list) – 1*2 list of energy range.

  • dos_range (list) – 1*2 list of DOS range.

  • dos_label (list) – 1*nProj or nProj*2 (spin) plot legend. If spin>1 and 1*nProj list is used, they are marked with the same label.

  • dos_color (list) – 1*nProj or nProj*2 (spin) plot color. If spin>1 and 1*nProj list is used, they are in the same color.

  • dos_linestyle (list) – 1*nProj or nProj*2 (spin) linestyle string. If spin>1 and 1*nProj list is used, they are in the same style.

  • dos_linewidth (list) – 1*nProj or nProj*2 (spin) width of the plot lines. If spin>1 and 1*nSystem list is used, they are in the same width.

  • fermi (float|None) – Fermi energy in eV. By default the band is aligned to 0. Can be used to offset the band. None for not plotting Fermi level.

  • fermi_color (str|None) – Color of the Fermi level.

  • fermi_linestyle (str|None) – Line style of Fermi level.

  • fermi_linewidth (float|None) – Width of the Fermi level.

  • legend (str|None) –

    Loc parameter passed to axes.legend() None for not adding legend.

  • plot_vertical (bool) – Developer Only Get vertical (DOS-Energy) DOS plots.

  • **kwargs – Other commands passed to matplotlib axes.plot() method when plotting bands. Applied to all bands.

Returns:

ax (Axes) – Matplotlib axes object

plot_banddos(bands, doss, k_label, beta, overlap, prj, energy_range, k_range, dos_range, band_width, band_label, band_color, band_linestyle, band_linewidth, dos_label, dos_color, dos_linestyle, dos_linewidth, fermi, fermi_color, fermi_linestyle, fermi_linewidth, figsize, legend, **kwargs)

The base function to plot electron / phonon band structure + DOS. A single system only.

Input arguments not in the list are consistent with plot_doss and plot_compare_bands.

Parameters:

  • bands (ElectronBand) – A electronics.ElectronBand object.

  • doss (ElectronDOS) – A electronics.ElectronDOS object

  • band_width (int|float) – Relative width of band structure, times of the width of a DOS subplot.

  • overlap (bool) – Plot DOS projections into the same axes or multiple axes.

Returns:

fig (Figure) – Matplotlib figure object

plot_2Dscalar(fig, ax, data, base, levels, contourline, isovalue, colormap, cbar_label, a_range, b_range, rectangle, edgeplot, xticks, yticks, **kwargs)

Plot 2D scalar field map.

Parameters:

  • fig (Figure) – Matplotlib Figure object

  • ax (Axes) – Matplotlib Axes object

  • data (array) – 2D map data.

  • base (array) – 3*3 Cartesian coordinates of points A, B, C to define a 2D map. Vectors BA and BC are used.

  • levels (array|None) – Contour line / color isovalues. It also defines the range of data.

  • contourline (list|None) – If not None, set line styles and colors of every contourline. nLevel*3 list of matplotlib plot color, linestyle and linewidth.

  • isovalue (str|None) – If not None, set the format of isovalues added to contourlines. Useful only when contourline is not None.

  • colormap (str|None) – If not None, set the colormap of color-filled contour plots.

  • cbar_label (str) – Title of colorbar. Useful only when colormap is not None.

  • a_range (list) – Range of \(a\) axis (x, or BC) in fractional coordinate.

  • b_range (list) – 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 plot plane edges

  • xticks (int) – Number of ticks in the x direction.

  • yticks (int) – Number of ticks in the y direction.

  • **kwargs – Other arguments passed to axes.contour() function to set contour lines.

Returns:

fig (Figure) – Matplotlib Figure object

plot_2Dvector(fig, ax, data, base, scale, colorquiver, levels, colormap, cbar_label, a_range, b_range, rectangle, edgeplot, xticks, yticks, **kwargs)

Plot 2D vector field map.

Parameters:

  • fig (Figure) – Matplotlib Figure object

  • ax (Axes) – Matplotlib Axes object

  • data (array) – 2D vector map data, in nY*nX*3.

  • base (array) – 3*3 Cartesian coordinates of points A, B, C to define a 2D map. Vectors BA and BC are used.

  • scale (float) – Tune the length of arrows.

  • colorquiver (str) – Specify the color of arrows or ‘colored’ for color- coded quiver plots.

  • levels (array) – Contour color isovalues. It also defines the range of data. Useful only if colorquiver='colored'.

  • colormap (str|None) – Set the colormap of color-filled contour plots. Useful only if colorquiver='colored'.

  • cbar_label (str) – Title of colorbar. Useful only if colorquiver='colored'.

  • a_range (list) – Range of \(a\) axis (x, or BC) in fractional coordinate.

  • b_range (list) – 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 plot plane edges

  • xticks (int) – Number of ticks in the x direction.

  • yticks (int) – Number of ticks in the y direction.

  • **kwargs – Other arguments passed to axes.quiver() function to set contour lines.

Returns:

fig (Figure) – Matplotlib Figure object

CRYSTALpytools.base.propd3 module

Classes and methods of keywords used in ‘properties’ input file (d3).

class PInputBlock

Bases: BlockBASE

The base class of a ‘property input block’, i.e., a properties calculation, with non-repeated keywords.

rdfmwf(rdfmwf='')
band(TITLE='', NLINE='', ISS='', NSUB='', INZB='', IFNB='', IPLO='', LPR66='', path=[])

path can either be a NLINE*2 list of string (labels), or a NLINE*2*3 list of int (fractional coordinates).

anbd(NK='', NB='', TOL='', *args)
bwidth(INZB='', IFNB='')
commens(ICASO='')
pato(IBN='', NPR='')
nosymada(nosymada='')
newk(*args)

Inputs are separated by comma.

pban(NB='', nbands=[])
pgeomw(pgeomw='')
pdide(EMI='', EMX='')
property adft

Subblock object ADFT.

property acor

Alias of block ADFT.

property edft

Subblock object EDFT.

property enecor

Alias of block EDFT.

property clas

Subblock object CLAS. Call self.clas() to set parameters. Call self.clas.coordina() (for example) to set mapnet keywords.

Parameters:

  • IDER (int) – Order of the derivative

  • IFOR (int) – Number of point multipoles

  • charge (list) – Formal net charge

  • NPY (int) – Number of points (MAPNET). Default 100.

property echg

Subblock object ECHG. Call self.echg() to set parameters. Call self.echg.coordina() (for example) to set mapnet keywords.

Parameters:

  • IDER (int) – Order of the derivative

  • NPY (int) – Number of points (MAPNET). Default 100.

property ech3

Subblock object ECH3. Call self.ech3() to set parameters. Call self.ech3.range() (for example) to set 3D grid keywords.

Parameters:

NP (int) – Number of points along the first direction

property potm

Subblock object POTM. Call self.potm() to set parameters. Call self.potm.coordina() (for example) to set mapnet keywords.

Parameters:

  • IDER (int) – Order of the derivative

  • ITOL (int) – Penetration tolerance

  • NPY (int) – Number of points (MAPNET). Default 100.

property pot3

Subblock object POT3. Call self.pot3() to set parameters. Call self.pot3.range() (for example) to set 3D grid keywords.

Parameters:

  • NP (int) – Number of points along the first direction

  • ITOL (int) – Penetration tolerance

potc(ICA='', NPU='', IPA='', datagrid=[])

datagrid corresponds to X, Y, Z, ZP, ZM and ZD parameters, which can be NPU*3 (ICA=0), 2*1 (ICA=1) or 3*1 (ICA=2) lists.

hirshchg(hchg='')
ppan(pchg='')
emdldm(N='', PMAX='', STEP='', IPLO='', hkl=[], ICASO='', NSA1='', NSA2='')

hkl is a N*3 list of int.

kinetemd(PMAX='', PINT='', STEP='', STEPDIST='', ICASO='')
poli(IDIPO='', ITENS='', LPR68='')
polspin(IDIPO='', ITENS='', LPR68='')
anisotro(keyword='', N='', IA='')

Available keywords: ‘ALL’, ‘UNIQUE’, ‘SELECT’

isotropic(keyword='', N='', IA='')

Available keywords: ‘ALL’, ‘UNIQUE’, ‘SELECT’

doss(NPRO='', NPT='', INZB='', IFNB='', IPLO='', NPOL='', NPR='', *args)

Energy range (BMI, BMA, 2*1 list) and projections (N, NDM, Nproj*(NDM+1) list) are defined by extendable list variables. If both are defined, projections should be the last entry.

coop(NINT='', NPT='', INZB='', IFNB='', IPLO='', NPOL='', NPR='', *args)

Energy range (BMI, BMA, 2*1 list) and projections (N, NDM, Nproj*(NDM+1) list) are defined by extendable list variables. If both are defined, projections should be the last entry.

cohp(NINT='', NPT='', INZB='', IFNB='', IPLO='', NPOL='', NPR='', *args)

Energy range (BMI, BMA, 2*1 list) and projections (N, NDM, Nproj*(NDM+1) list) are defined by extendable list variables. If both are defined, projections should be the last entry.

pscf(pscf='')
class Properties_inputBASE

Bases: PInputBlock

The base class of Properties_input class. At maximum 5 same ‘properties’ calculations can be appended

property append1
property append2
property append3
property append4
property append5
analyze_text(data)

Analyze formatted d3 file.

Parameters:

data (str) – Formatted string.

class EDFT

Bases: BlockBASE

EDFT sub-block

becke(becke='')
savin(savin='')
radial(NR='', RL=[], IL=[])
angular(NI='', AL=[], IA=[])
print(prt='')
printout(prt='')
tolldens(ID='')
tollgrid(IG='')
class ADFT

Bases: EDFT

ADFT sub-block

property newbasis

Subblock object NEWBASIS

class Grid2D(header='')

Bases: BlockBASE

A base class for 2D data grid (ECHG, POTM, CLAS).

Parameters:

header (str) – Formatted headers

coordina(crda='', crdb='', crdc='')
atoms(IA='', IB='', IC='')

IA IB IC are 4*1 lists

rectangu(rec='')
margins(ABM='', CDM='', ADM='', BCM='')
print(prt='')
angstrom(ang='')
bohr(br='')
fraction(frac='')
class ECHG(header='')

Bases: Grid2D

Class for ECHG. Initialization can be done by formatted string only. Otherwise call this object from upper block.

Parameters:

  • IDER (int) – Order of the derivative

  • NPY (int) – Number of points (MAPNET)

class POTM(header='')

Bases: Grid2D

Class for POTM. Initialization can be done by formatted string only. Otherwise call this object from upper block.

Parameters:

  • IDER (int) – Order of the derivative

  • ITOL (int) – Penetration tolerance

  • NPY (int) – Number of points (MAPNET)

class CLAS(header='')

Bases: Grid2D

Class for CLAS. Initialization can be done by formatted string only. Otherwise call this object from upper block.

Parameters:

  • IDER (int) – Order of the derivative

  • IFOR (int) – Number of point multipoles

  • charge (list) – Formal net charge

  • NPY (int) – Number of points (MAPNET)

class Grid3DBASE(header='')

Bases: BlockBASE

A base class for 3D data grid (ECH3, POT3). Not for ‘GRID3D’ keyword

Parameters:

header (str) – Formatted headers

scale(scale1='', scale2='', scale3='')
range(rg1='', rg2='', rg3='')

Inputs are 2*1 lists. [minvalue, maxvalue]. The sequence of rg123 is consistent with CRYSTAL (2D: z; 1D: y, z; 0D: x, y, z)

class ECH3(header='')

Bases: Grid3DBASE

Class for ECH3. Initialization can be done by formatted string only. Otherwise call this object from upper block.

Parameters:

NP (int) – Number of points along the first direction

class POT3(header='')

Bases: Grid3DBASE

Class for POT3. Initialization can be done by formatted string only. Otherwise call this object from upper block.

Parameters:

  • NP (int) – Number of points along the first direction

  • ITOL (int) – Penetration tolerance

Module contents