Wavefunction database and computation (WfBase)

WfBase is a software package providing an easy way to compute from first-principles various properties depending on the electronic structure of periodic solids. This package can parse user-provided mathematical expressions, in a human-readable format, using the Einstein notation for indices. It is well suited, for example, to calculate terms that arise in the perturbation theory context, where one needs to sum over electronic states over arbitrarily dense sampling of the Brillouin zone.

This package also comes with a built-in database of some simple materials. The accuracy of the electronic structure in the database is on the level of common generalized gradient approximation (GGA) approximations to the density functional theory. All calculations in the database include fully-relativistic effects, such as the spin-orbit interaction.

To install WfBase run the following command in your terminal (more details on installation):

pip install wfbase --upgrade

To learn about using WfBase take a look at the list of examples as well as the detailed technical description of all WfBase functionalities.

Start guide

Here is a quick start guide to using the WfBase package.

Accessing database

After downloading the database you should use the load function to open one of the database entries,

db = wf.load("data/au_fcc.wf")

Next, we can use the created object db to compute from first-principles various basic electronic-structure quantities on an arbitrarily dense sampling of the Brillouin zone.

comp = db.do_mesh([16, 16, 16])

A newly created object, comp, now stores information about the electronic band structure (E) and the needed matrix elements (A), along with other quantities as well.

Computing user-defined quantities

You can now use basic quantities stored in comp, such as E and A, to compute user-defined quantities. All you need to do here is to call function evaluate with a string representation of the mathematical expression you wish to calculate. For example, you can provide the following strings to compute the interband optical conductivity,

comp.evaluate(
"sigma_oij <= (j/(numk*volume)) * A_knmi*A_kmnj * (E_kn - E_km)/(E_km - E_kn - hbaromega_o - j*eta)",
"E_km > ef, E_kn < ef"
)

Given this information, WfBase can now

  • parse the provided strings,

  • perform the sum over the repeated indices while enforcing the provided constraints on the empty and occupied states,

  • check that the physical units are consistent in the provided expression, and find the physical unit of the resulting quantity sigma,

  • provide LaTeX’ed equation of the provided expression, as shown here,

  • example quick

  • give the final result (optical conductivity), converted to SI units if needed,

  • example quick

Computational provenance

User can access from within their script detailed information about the computed quantity sigma,

comp.info("sigma")

The example output of function info can be found here.

Using an additional flag to function info one can also get the automatically generated python code that WfBase used under the hood to evaluate the provided expression,

comp.info("sigma", show_code = True)

For reproducibility purposes, one can run this code directly if needed.

Furthermore, one can also access information about any other quantity stored in object comp, such as the electron band energy (E) or Berry connection (A),

comp.info("E")
comp.info("A")

The output of these functions will give you information about the order and meaning of indices of these quantities, as well as the definition of each quantity, sign convention, physical units, and so on.

Finally, for a more complete computational provenance, one can also obtain information about the density functional theory (DFT) calculation used to generate the database entry itself,

db.info()

The example output of this function can be found here.

Example source code

Here is the complete source code of the calculation described above. Many more examples can be found here.

import wfbase as wf

wf.download_data_if_needed()

# loads the database
db = wf.load("data/au_fcc.wf")

# calculates needed quantities on a grid of k-points
comp = db.do_mesh([16, 16, 16])

# changes the default values of some of the parameters
comp["eta"] = 0.2
comp.compute_photon_energy("hbaromega", 1.0, 3.0, 51)

# evaluates interband optical conductivity
comp.evaluate(
    "sigma_oij <= (j/(numk*volume)) * A_knmi*A_kmnj * (E_kn - E_km)/(E_km - E_kn - hbaromega_o - j*eta)",
    "E_km > ef, E_kn < ef"
)

# renders the string above in LaTeX
wf.render_latex(comp.get_latex("sigma"), "fig_quick_latex.png")

# converts to SI units and multiplies with e^2/hbar
result, result_latex = comp.compute_in_SI("sigma", "e^2 / hbar")

import matplotlib.pyplot as plt
fig, ax = plt.subplots(figsize = (4.0, 3.0))
ax.plot(comp["hbaromega"], result[:, 0, 0].real * 1.0E-5, "k-")
ax.set_xlabel(r"$\hbar \omega$ (eV)")
ax.set_ylabel(r"$\sigma_{\rm xx}$ $\left(\displaystyle\frac{10^5}{\Omega {\rm m}}\right)$")
ax.set_ylim(0.0)
fig.tight_layout()
fig.savefig("fig_quick.pdf")