asedftk is a wrapper around the density-functional toolkit (DFTK), a Julia code for plane-wave based density-functional theory (PWDFT). asedftk provides an ASE-compatible calculator class, which allows to directly employ DFTK inside ASE workflows.
- Install Julia e.g. by downloading the binary. The use of at least Julia 1.5 is required.
- Install asedftk from PyPi, for example
using pip:
Note: You can also use
pip install asedftk
pip
if you are managing your python packages with anaconda (conda install pip
followed by above command), but it is not recommended to do this in the root anaconda environment. - (optionally, but recommended) Precompille DFTK into a custom Julia sysimage
for asedftk:
While this step is not needed for asedftk to function, it is highly recommended as it greatly reduces DFTK's latency by compiling important parts of DFTK and storing them in binary form on disk as a "sysimage". This saves a lot on the just-in-time compilation time of DFTK and therefore has noticable impact especially for smaller calculations.
python -c "import asedftk; asedftk.build_sysimage()"
Note: This feature is still experimental and might not work for all setups. If you encounter problems either when building the sysimage or when attempting to use it (can be everything from an error to a segfault), you can always revert by removing the sysimage (asedftk.remove_sysimage()
).
As part of the installation DFTK will be installed automatically
inside a separate Julia environment, which is private to asedftk.
Typically this DFTK version will be updated as needed.
In case you need to do the update manually at some point, simply run
asedftk.update()
.
The best way to explain asedftk is by some examples:
from asedftk import DFTK
import ase.build
silicon = ase.build.bulk("Si")
silicon.calc = DFTK()
print("Silicon energy: ", silicon.get_potential_energy())
print("Silicon forces: ", silicon.get_forces())
from asedftk import DFTK
import ase.build
magnesium = ase.build.bulk("Mg")
magnesium.calc = DFTK(xc="PBE", smearing=("Gaussian", 0.027), kpts=(5, 5, 5))
print("Magnesium energy: ", magnesium.get_potential_energy())
print("Magnesium forces: ", magnesium.get_forces())
Using the ASE optimiser from python:
# Python
from asedftk import DFTK
import ase.build
from ase.optimize import BFGS
h2 = ase.build.molecule("H2", pbc=True, vacuum=10)
h2.set_positions([[10, 10, 11.0], [10, 10, 10]])
h2.calc = DFTK(scftol=1e-6, xc="PBE", kpts=[1, 1, 1], ecut=50)
dyn = BFGS(h2, trajectory="H2.traj")
dyn.run(fmax=0.05)
print("H-H distance: ", h2.get_distance(0, 1))
Alternatively using a Julia script (and PyCall
) to drive the optimisation:
# Julia
using PyCall
DFTKcalc = pyimport("asedftk").DFTK
ase_build = pyimport("ase.build")
BFGS = pyimport("ase.optimize").BFGS
h2 = ase_build.molecule("H2", pbc=true, vacuum=10)
h2.set_positions([[10 10 11.0]; [10 10 10]])
h2.calc = DFTKcalc(scftol=1e-6, xc="PBE", kpts=[1, 1, 1], ecut=50)
dyn = BFGS(h2, trajectory="H2.traj")
dyn.run(fmax=0.05)
println("H-H distance: ", h2.get_distance(0, 1))
The asedftk.DFTK
class supports a couple of parameters
to customise the calculation,
mostly following the
ASE calculator interface proposal.
See also the __init__
function
in calculator.jl.
- ecut: Kinetic energy cutoff. 400eV by default.
- functionals: Explicit functional list.
This overwrites the choice of xc, but xc still needs to be given to select
appropriate pseudopotentials. Valid options are
all functionals from libxc,
for example
"lda_x"
,"GGA_X_B86"
,"GGA_C_LYP"
. - kpts: k-point grid to use. Valid options are:
(n1,n2,n3)
: (Unshifted) Monkhorst-Pack grid(n1,n2,n3,"gamma")
: Shifted MP grid to contain the gamma point.[(k11,k12,k13),(k21,k22,k23),...]
: Explicit k-Point list in units of the reciprocal lattice vectors3.5
(or any float): k-point density as in3.5
kpoints per Ǎngström.
- mixing: Mixing scheme used during SCF iterations. Examples for valid options:
"SimpleMixing(α=0.7)"
: Simple mixing with damping0.7
"KerkerMixing(α=0.7, kTF=1.0)"
: Kerker mixing with dampingα = 0.7
and screening parameterkTF = 1.0
. Applies the operator kernelα * G^2 / (kTF^2 + G^2)
for a wave vectorG
in frequency space."HybridMixing(α=0.7, kTF=1.0, εr=10)"
: LDOS mixing as described in arXiv 2009.01665. Ifεr=1
a plain LDOS mixing is used, for other values a model dielectric term is added as well.kTF
is meaningless unless the model dielectric term is used.
- nbands: Number of bands to compute
- pps: Pseudopotential family. Currently the only choices are
"hgh"
(Goedecker-type pseudos) and"hgh.k"
(semi-core version of"hgh"
). - scftol: Convergence tolerance of the SCF. Default
1e-5
. - smearing: Smearing function and temperature, options:
('Fermi-Dirac', width)
('Gaussian', width)
('Methfessel-Paxton', width, n)
where in each casewidth
is the width in eV andn
is the Methfessel-Paxton order.
- xc: Exchange-correlation functional, default is
LDA
, options areLDA
orPBE
. - n_mpi: Number of MPI threads to employ when running DFTK.
Set this to a value between
1
and the number of irreducible k-Points. See the DFTK parallelization documentation for details. - n_threads: Number of Julia threads to employ when running DFTK.
Typically the best performance is obtained by using only one thread (the default)
and increasing
n_mpi
instead. See the DFTK parallelization documentation for details.
Some advanced customisation of asedftk is possible via environment variables:
JULIA
: Name of thejulia
binary, or full path to itASEDFTK_DFTK_ENVIRONMENT
: Custom environment location to use for running julia, see section below.
If you want to employ a custom Julia environment in combination with asedftk,
for example to supply a modified DFTK,
just point the environment variable ASEDFTK_DFTK_ENVIRONMENT
to the folder with your
custom environment.
When doing this, ensure that the packages specified in asedftk's
Project.toml
are available in your custom environment.