Fireball ASE interface#

class fireballpy.Fireball(fdata, *, lazy=True, verbose=False, kpts=(1, 1, 1), **kwargs)[source]#

Python implementation of Fireball DFT code compatible with ASE API.

The idea of this DFT code is to make use of precomputed integrals of the basis functions (called FData) and to implement self consistency over the point charges to gain a massive speed improvement.

This class has been designed with the idea of being used as part of ASE’s API. As such, it needs to be attached to a valid ase.Atoms object.

For a detailed tutorial on how to use this class please look at the FireballPy User Guide.

Parameters:

fdatastr

Name of the FData to be used. See available_fdatas() for a table of available FData. If set to 'custom' then an fdata_path pointing to a local FData folder must be provided. Please note that the first time an FData is used it needs to download all the necessary files.

lazybool, optional

If set to True (default) it will only load necessary files for the species which are involved in the computation. If set to False it will load the FData for all the species available in it. This will add a significant overhead at the exchange of not having to load new species if they are added later.

verbosebool, optional

If True information of the convergence of the SCF loop will be printed on screen. Default is False.

kptsArrayLike[int] | ArrayLike[float] | float, optional

Specify the k-points for a periodic computation. It can be either a set of three Monkhorst-Pack indices, a nkpts x 3 array with the coordinates of the k-points in reciprocal cell units, or a density of k-points in inverse angstroms. By default, it will generate a (1, 1, 1) Monkhorst-Pack corresponding to the Gamma point alone.

**kwargs

Advanced options. May requiere previous experience with DFT computations:

Property	Type	Description
`gamma`	`bool` or `None`	If the k-points are to be generated from a Monkhorst-Pack or from a k-point density, should the Gamma (`[0, 0, 0]`) point be forcefully included (`True`), forcefully excluded (`False`) or don’t care whether it is included or not (`None`, default)
`charges_method`	`str` or `None`	How the autoconsistency in the charges will be performed. By default depends on the FData (`None`). If a custom FData is selected, then this parameter must be specified. For more options see here.
`dipole_method`	`str`	Whether to use the improved dipole description (`'improved'`, default) or not (`'legacy'`). In periodic systems this is ignored as only the legacy description is implemented.
`fdata_path`	`str`	Path to a custom FData. Ignored unless `fdata = 'custom'`.
`total_charge`	`int`	Total charge of the system in elementary charge units (1 extra electron will be `total_charge = -1`). Default is 0.
`correction`	`dict` or `None`	By default (`None`) will apply DFT-D3 correction for the selected FData if optimized parameters are available (see `available_fdatas()`). Also, it may be a dictionary with the parameters for DFT-D3 correction The dictionary must contain the keys `'kind'` (right now it can only be `'dftd3'`), `'damping'` and either `'method'` or `'params_tweaks'`. It may be forcefully shut down by providing `False`. For more information, see Simple DFT-D3 documentation.
`mixer_kws`	`dict`	Dictionary with the charges mixer options. For reference see here.

Methods

get_eigenvalues(kpt=0, spin=0)	Obtain Hamiltonian eigenvalues in eV.
get_eigenvectors(kpt=0, spin=0)	Obtain the wavefunction coefficients.
get_fermi_level()	Obtain the Fermi energy in eV.
get_ibz_k_points()	Obtain the coordinates of k-points used in the computation.
get_k_point_weights()	Obtain the associated weights of the k-points.
get_number_of_bands()	Obtain the number of orbitals considered.
get_number_of_shells()	Obtain the number of shells considered.
get_shell_charges()	Obtain the charges of each shell.
fix_charges()	Fix shell charges
unfix_charges()	Unfix shell charges

Notes

If you use this code in a publication please cite us [Lewis2011].

[Lewis2011]

James. P. Lewis, et al., “Advances and applications in the FIREBALL ab initio tight-binding molecular-dynamics formalism”, Phys. Status Solidi B, 248(9):1989-2007, 2011. DOI:10.1002/pssb.201147259

fix_charges()[source]#: Fix shell charges for following computations

get_eigenvalues(kpt=0, spin=0)[source]#

Get the eigenvalues of the hamiltonian in electronvolts.

Parameters:

kptint: Index of the k-point to obtain the eigenvalues. Check Fireball.get_ibz_k_points(). By default takes the first (kpt = 0).
spinint: Spin index for the eigenvalues. Currently dummy as no spin polarisation is implemented.

Returns:

NDArray[float]: Array with the eigenvalues for the requested k-point.

Raises:

PropertyNotPresent: If any computation has been done and eigenvalues were not yet computed.
IndexError: If the an out-of-bounds k-point index is requested.

get_eigenvectors(kpt=0, spin=0)[source]#

Get the coefficients for each wave function.

Parameters:

kptint: Index of the k-point to obtain the eigenvectors. Check Fireball.get_ibz_k_points(). By default takes the first (kpt = 0).
spinint: Spin index for the eigenvalues. Currently dummy as no spin polarisation is implemented.

Returns:

NDArray[float] | NDArray[complex]: Matrix with the eigenvectors. Each column are the coefficients of that wavefunction.

Raises:

PropertyNotPresent: If any computation has been done and eigenvectors were not yet computed.
IndexError: If the an out-of-bounds k-point index is requested.

get_fermi_level()[source]#

Get the Fermi level in electronvolts.

Returns:

float: Fermi energy in units of eV.

Raises:

PropertyNotPresent: If any computation has been done and the Fermi level was not yet computed.

get_ibz_k_points()[source]#

Get the k-points used for computation. Note that there may be less than imputed as redundant k-points are deleted.

Returns:

NDArray[float]: Array with the coordinates of each k-point in inverse angstroms

Raises:

PropertyNotPresent: If any computation has been done and k-points were not yet computed.

get_k_point_weights()[source]#

Get the weights of the k-points used for computation. Note that there may be less than imputed as redundant k-points are deleted.

Returns:

NDArray[float]: Array with the weights of each k-point.

Raises:

PropertyNotPresent: If the any computation has been done and k-point weights were not yet computed.

get_number_of_bands()[source]#

Get the number of bands.

Returns:

int: Number of bands

Raises:

PropertyNotPresent: If the any computation has been done and the number of bands is not yet computed.

get_number_of_shells()[source]#

Get the number of shells.

Returns:

int: Number of shells

Raises:

PropertyNotPresent: If the any computation has been done and the number of shells is not yet computed.

get_shell_charges()[source]#

Get the charges of each shell if computed.

Returns:

NDArray[float]: Array with the charges of each shell. A null charge represents that shell is not applicable to the corresponding atom.

Raises:

PropertyNotPresent: If the any computation has been done and the shell charges are not yet computed.

unfix_charges()[source]#: Unfix shell charges for following computations