dftbutils sub-package

Run BS (skpar.dftbutils.runBS)

skpar.dftbutils.runBS.main_bands(args)

Chain the relevant tasks for obtaining band-structure and execute.

skpar.dftbutils.runBS.set_bands_parser(parser=None)

Define parser options specific for band-structure calculations.

Parameters:parser – python parser Typically, that will be a sub-parser passed from top executable.

Query DFTB (skpar.dftbutils.queryDFTB)

class skpar.dftbutils.queryDFTB.BandsOut(*args, **kwargs)

A dictionary initialised with the bands from dp_bands or similar tool.

Useage:

destination_dict = BandsOut.fromfile(file)

classmethod fromfile(fp, enumeration=True)

class skpar.dftbutils.queryDFTB.Bandstructure(*args, **kwargs)

A dictionary initialised with the bands and some analysis of the bands.

It requires two files: detailed.out from dftb+, and bands_tot.dat from dp_bands. It reads the bands via BandsOut; obtains the number of electrons via DetailedOut. It returns a dictionary with all that is in DetailedOut plus: ‘bands’: energy bands (excluding k-point enumeration) ‘Ecb’ : LUMO ‘Evb’ : HOMO ‘Egap’ : Ecb - Evb

Useage:

destination_dict = Bandstructure.fromfiles(detailed.out_file, bands_file)

classmethod fromfiles(fp1, fp2, enumeration=True)

Read the output of dftb+ and dp_bands and return a dictionary with band-structure data.

class skpar.dftbutils.queryDFTB.DetailedOut(*args, **kwargs)

A dictionary initialised from file with the detailed output of dftb+.

Useage:

destination_dict = DetailedOut.fromfile(filename)

conv_tags = [('iSCC', ('nscc', 'scc_err')), ('SCC converged', True), ('SCC is NOT converged', True)]

energy_tags = [('Fermi energy:', 'Ef'), ('Band energy:', 'Eband'), ('TS:', 'Ets'), ('Band free energy (E-TS):', 'Ebf'), ('Extrapolated E(0K):', 'E0K'), ('Energy H0:', 'Eh0'), ('Energy SCC:', 'Escc'), ('Energy L.S:', 'Els'), ('Total Electronic energy:', 'Eel'), ('Repulsive energy:', 'Erep'), ('Total energy:', 'Etot'), ('Total Mermin free energy:', 'Emermin')]

classmethod fromfile(fp)

nelec_tags = [('Input/Output electrons (q):', ('nei', 'neo'))]

skpar.dftbutils.queryDFTB.calc_masseff(bands, extrtype, kLineEnds, lattice, meff_tag=None, Erange=0.008, forceErange=False, ib0=0, nb=1, usebandindex=False)

A complex wrapper around meff(), with higher level interface.

Calculate parabolic effective mass at the specified extrtype of given bands, calculated along two points in k-space defined by a list of two 3-tuples - kLineEnds. lattice is a lattice object, defining the metric of the kspace.

Parameters:

• bands – an array (nb, nk) energy values in [eV], or a 1D array like
• extrtype – type of extremum to search for: ‘min’ or ‘max’, handled by np.min()/max()
• kLineEnds – two 3-tuples, defining the coordinates of the endpoints of the k-line along which band is obtained, in terms of k-scace unit vectors, e.g. if band is obtained along a number of points from Gamma to X, of the BZ of a cubic lattice, then kLineEnds should read ((0, 0, 0), (1, 0, 0))
• lattice – lattice object, holding mapping to kspace.
• meff_name – the name to be featured in the logger
• Erange – Energy range [eV] over which to fit the parabola [dflt=8meV], i.e. ‘depth’ of the assumed parabolic well.

Return meff:

the value of the parabolic effective mass [m_0] at the extrtype of the given E-kline, if the extremum is not at the boundary of the given k-line.

skpar.dftbutils.queryDFTB.expand_meffdata(meff_data)

skpar.dftbutils.queryDFTB.get_Ek(bsdata, sympts)

skpar.dftbutils.queryDFTB.get_bandstructure(workroot, source, destination, detailfile='detailed.out', bandsfile='bands_tot.dat', hsdfile='dftb_pin.hsd', latticeinfo=None, *args, **kwargs)

Load whatever data can be obtained from detailed.out of dftb+ and bands_tot.dat of dp_bands.

skpar.dftbutils.queryDFTB.get_dftbp_data(source, destination, workdir='.', *args, **kwargs)

Load whatever data can be obtained from detailed.out of dftb+.

skpar.dftbutils.queryDFTB.get_effmasses(workroot, source, destination, directions=None, carriers='both', nb=1, Erange=0.04, usebandindex=False, forceErange=False, *args, **kwargs)

Return a dictionary with effective masses for the given carriers for the first nb bands in the VB and CB, along the given paths, as well as the values of the extrema and their position along the directions in the paths.

skpar.dftbutils.queryDFTB.get_labels(ss)

Return two labels from a string containing “-” or two words starting with a capital.

For example, the input string may be ‘G-X’, ‘GX’, ‘Gamma-X’, ‘GammaX’. The output is always: (‘G’, ‘X’) or (‘Gamma’, ‘X’).

skpar.dftbutils.queryDFTB.get_special_Ek(workroot, source, destination, sympts=None, extract={'cb': [0], 'vb': [0]}, align='Ef', *args, **kwargs)

Query bandstructure data and yield the eigenvalues at k-points of high-symmetry.

skpar.dftbutils.queryDFTB.greek(label)

Change Greek letter names to single Latin capitals, and vice versa.

Useful for some names of high-symmetry points inside the BZ, to shorten the names of Gamma, Sigma and Delta. Note that Lambda cannot be made into L, as it will make automatic L to Lambda as well, which is wrong since L is a standard point on the BZ surface.

skpar.dftbutils.queryDFTB.is_monotonic(x)

Return True if x is monotonic (either never increases or never decreases); False otherwise.

skpar.dftbutils.queryDFTB.meff(band, kline)

Return the effective mass, in units of m_0, given a band a k-line.

The mass is calculated as as the inverse of the curvature of bands, assuming parabolic dispersion within kline, working in atomic units: bands and kline are in Hartree and 1/Bohr, h_bar = 1, m_0 = 1

meff = (h_bar**2) / (d**2E/dk**2), [m0]

skpar.dftbutils.queryDFTB.plot_fitmeff(ax, xx, x0, extremum, mass, dklen=None, ix0=None, *args, **kwargs)

Plot the second order polynomial fitted to E(k) dispersion on top of ax axes of a matplotlib figure object. mass is the fitted effective mass extremum is extremal energy, E0 x0 is the relative position of the extremum along the given kline xx.

Assumed is that around the extremum at k0:

E”(k) = 1/mass => E(k) = E(x) = c2*x^2 + c1*x + c0.

Since E”(x) = 2*c2 => c2 = 1/(2*mass). Since E’(x) = 2*c2*x + c1, and E’(x=x0) = 0 and E(x=x0) = E0 => knowing E0 and x0, we can obtain c1 and c2:

c1 = -2*c2*x0 c0 = E0 - c2*x0^2 - c1*x0

Query k-Lines (skpar.dftbutils.querykLines)

Module for k-Lines extraction and k-Label manipulation

Recall that bands contains NO information of the k-points. So we must provide that ourselves, and reading the dftb_pin.hsd (the parsed input) seems the best way to do so. We also need to figure out what to do with equivalent points, or points where a new path starts. Finally, points internal to the Brilloin Zone are labeled with Greek letters, which should be rendered properly.

skpar.dftbutils.querykLines.get_klines(lattice, hsdfile='dftb_pin.hsd', workdir=None, *args, **kwargs)

This routine analyses the KPointsAndWeights stanza in the input file of DFTB+ (given as an input argument hsdfile), and returns the k-path, based on the lattice object (given as an input argument lattice). If the file name is not provided, the routine looks in the default dftb_pin.hsd, i.e. in the parsed file!

The routine returns a list of tuples (kLines) and a dictionary (kLinesDict) with the symmetry points and indexes of the corresponding k-point in the output band-structure.

kLines is ordered, as per the appearence of symmetry points in the hsd input, e.g.:

• [(‘L’, 0), (‘Γ’, 50), (‘X’, 110), (‘U’, 130), (‘K’, 131), (‘Γ’, 181)]

therefore it may contain repetitions (e.g. for ‘Γ’, in this case).

kLinesDict returns a dictionary of lists, so that there’s a single entry for non-repetitive k-points, and more than one entries in the list of repetitive symmetry k-points, e.g. (see for ‘Γ’ above):

• {‘X’: [110], ‘K’: [131], ‘U’: [130], ‘L’: [0], ‘Γ’: [50, 181]}

skpar.dftbutils.querykLines.get_kvec_abscissa(lat, kLines)

Return abscissa values for the reciprocal lengths corresponding to the k-vectors derived from kLines.

skpar.dftbutils.querykLines.greekLabels(kLines)

Check if Γ is within the kLines and set the label to its latex formulation. Note that the routine will accept either list of tupples (‘label’,int_index) or a list of strings, i.e. either kLines or only the kLinesLabels. Could do check for other k-points with greek lables, byond Γ (i.e. points that are inside the BZ, not at the faces) but in the future.

Lattice (skpar.dftbutils.lattice)

This module lists the component vectors of the direct and reciprocal lattices for different crystals. It is based on the following publication: Wahyu Setyawan and Stefano Curtarolo, “High-throughput electronic band structure calculations: Challenges and tools”, Comp. Mat. Sci. 49 (2010), pp. 291–312.

class skpar.dftbutils.lattice.BCC(param, setting='curtarolo')

This is Body Centered Cubic lattice (cF)

class skpar.dftbutils.lattice.CUB(param, setting=None)

This is CUBic, cP lattice

class skpar.dftbutils.lattice.FCC(param, setting='curtarolo')

This is Face Centered Cubic lattice (cF)

class skpar.dftbutils.lattice.HEX(param, setting='curtarolo')

This is HEXAGONAL, hP lattice

class skpar.dftbutils.lattice.Lattice(info)

Generic lattice class.

get_kcomp(string)

Return the k-components given a string label or string set of fraction.

Example of string:

s = ‘X’ s = ‘1/2 0 1/2’ s = ‘1/2, 0, 1/2’ s = ‘0.5 0 0.5’

get_kvec(kpt)

Return the real space vector corresponding to a k-point.

class skpar.dftbutils.lattice.MCL(param, setting='curtarolo')

This is simple Monoclinic MCL_* (mP) lattice, set via a, b <= c, and alpha < 90 degrees, beta = gamma = 90 degrees as in W. Setyawan, S. Curtarolo / Computational Materials Science 49 (2010) 299-312. Setting=ITC should work for the standard setting (angle>90) of ITC-A, but is not currently implemented. Note that conventional and primitive cells are the same.

class skpar.dftbutils.lattice.MCLC(param, setting='ITC')

This is base-centered Monoclinic MCLC_* mS, lattice Primitive lattice defined via: a <> b <> c, and alpha <> 90 degrees, beta = gamma = 90 degrees

class skpar.dftbutils.lattice.ORC(param, setting='curtarolo')

This is ORTHOROMBIC, oP lattice

class skpar.dftbutils.lattice.RHL(param, setting=None)

This is Rhombohedral RHL, hR lattice Primitive lattice defined via: a = b = c, and alpha = beta = gamma <> 90 degrees Two variations exists: RHL1 (alpha < 90) and RHL2 (alpha > 90)

class skpar.dftbutils.lattice.TET(param, setting='curtarolo')

This is TETRAGONAL, tP lattice

skpar.dftbutils.lattice.getSymPtLabel(kvec, lattice)

Return the symbol corresponding to a given k-vector, if named.

This routine returns the symbol of a symmetry point that is given in terms of reciprocal cell-vectors (kvec – a 3-tuple) of the lattice object.

skpar.dftbutils.lattice.get_dftbp_klines(lattice, delta=None, path=None)

Print out the number of points along each segment of the BZ path (default for the lattice chosen if None) of a given lattice object

skpar.dftbutils.lattice.get_kvec(comp_rc, recipr_cell)

comp_rc are the components of a vector expressed in terms of reciprocal cell vectors recipr_cell. Return the components of this vector in terms of reciprocal unit vectors.

skpar.dftbutils.lattice.get_recipr_cell(A, scale)

Given a set of set of three vectors A, assumed to be that defining the primitive cell, return the corresponding set of vectors that define the reciprocal cell, B, scaled by the input parameter scale, which defaults to 2pi. The B-vectors are computed as follows: B0 = scale * (A1 x A2)/(A0 . A1 x A2) B1 = scale * (A2 x A0)/(A0 . A1 x A2) B2 = scale * (A0 x A1)/(A0 . A1 x A2) and are returnd as a list of 1D arrays. Recall that the triple-scalar product is invariant under circular shift, and equals the (signed) volume of the primitive cell.

skpar.dftbutils.lattice.getkLineLength(kpt0, kpt1, Bvec, scale)

Given two k-points in terms of unit vectors of the reciprocal lattice, Bvec, return the distance between the two points, in terms of reciprocal length.

skpar.dftbutils.lattice.len_pathsegments(lattice, scale=None, path=None)

Report the lenth in terms of _scale_ (2pi/a if None) of the BZ _path_ (default for the lattice chosen if None) of a given _lattice_ object

skpar.dftbutils.lattice.repr_lattice(lat)

Report cell vectors, reciprocal vectors and standard path

Plot (skpar.dftbutils.plot)

class skpar.dftbutils.plot.Plotter(data=None, filename=None, Erange=[-13, 13], krange=None, figsize=(6, 7), log=<logging.Logger object>, refEkpts=None, refBands=None, col='darkred', withmarkers=False, colref='blue', cycle_colors=False)

This class plots the bandstructure contained in ‘data’ to a file named ‘filename’. Energy range, and figure size may be controlled by ‘Erange’ and ‘figsize’ respectively. ‘data’ is a dictionary {‘bands’:values, ‘kLines’:values}; filename is a string. ‘refEkpts’ and ‘refBands’ can be plotted, if supplied, but note that refBands must have the same number of k-points as data[‘bands’] ‘refEkpts’ is a list of tupples…. ‘col’ and ‘colref’ are used for data and ref* respectively. ‘data’ bands may be plotted with cycling colours too (cycle_colors=True).

plot(*args, **kwargs)

This method attempt to plot and save a figure of the bandstructure contained in self.data. self.data may be initialised at self.__init__() and the ‘bands’ and ‘kLines’ fields of data may be independently updated. This allows one to call plot() without any arguments. Alternatively, one may pass data explicitely using data = {‘bands’:values, ‘kLines’:values} where ‘bands’ values are the E-k dispersion, and ‘kLines’ are the labels for points of high symmetry. plot() can be called also with two positional arguments: bands,kLines or one positional arguments: data, or two key-value pairs: bands=…, kLines=…

skpar.dftbutils.plot.plotBS(plotname, xx, yy, colors=None, markers='', ylabels=None, xlim=None, ylim=[-13, 13], figsize=(6, 7), title=None, withmarkers=False, **kwargs)

Specialised magic routine for plotting band-structure.

Unils (skpar.dftbutils.utils)

skpar.dftbutils.utils.configure_logger(name, filename=None, verbosity=20)

Get parent logger: logging INFO on the console and DEBUG to file.

skpar.dftbutils.utils.get_logger(name, filename=None, verbosity=20)

Return a named logger with file and console handlers.

Get a name-logger. Check if it is(has) a parent logger. If parent logger is not configured, configure it, and if a child logger is needed, return the child. The check for parent logger is based on name: a child if it contains ‘.’, i.e. looking for ‘parent.child’ form of name. A parent logger is configured by defining a console handler at verbosity level, and a file handler at DEBUG level, writing to filename.