/
search_index.js
3 lines (3 loc) · 117 KB
/
search_index.js
1
2
3
var documenterSearchIndex = {"docs":
[{"location":"publications/#Publications-1","page":"Publications","title":"Publications","text":"","category":"section"},{"location":"publications/#","page":"Publications","title":"Publications","text":"This page contains a list of publications dealing with DFTK or which make use of DFTK. Feel free to drop us a line if you want your work to be added here. To cite DFTK please use (Image: DOI).","category":"page"},{"location":"publications/#","page":"Publications","title":"Publications","text":"M. F. Herbst, A. Levitt and E. Cancès. A posteriori error estimation for the non-self-consistent Kohn-Sham equations (2020). ArXiv:2004.13549.\nE. Cancès, G. Kemlin and A. Levitt. Convergence analysis of direct minimization and self-consistent iterations (2020). ArXiv:2004.09088.","category":"page"},{"location":"contributing/#Contributing-1","page":"Contributing","title":"Contributing","text":"","category":"section"},{"location":"contributing/#","page":"Contributing","title":"Contributing","text":"Contributions to the code in any form is welcome, just submit a pull request on github.","category":"page"},{"location":"contributing/#","page":"Contributing","title":"Contributing","text":"If you stumble across issues in using DFTK or have suggestions for future developments we are more than happy to hear about it. In this case please open an issue or contact us (@mfherbst and @antoine-levitt) directly.","category":"page"},{"location":"advanced/useful_formulas/#Useful-formulas-1","page":"Useful formulas","title":"Useful formulas","text":"","category":"section"},{"location":"advanced/useful_formulas/#","page":"Useful formulas","title":"Useful formulas","text":"This section holds a collection of formulae, which are helpful when working with DFTK and plane-wave DFT in general. See also Notation and conventions for a description of the conventions used in the equations.","category":"page"},{"location":"advanced/useful_formulas/#Fourier-transforms-1","page":"Useful formulas","title":"Fourier transforms","text":"","category":"section"},{"location":"advanced/useful_formulas/#","page":"Useful formulas","title":"Useful formulas","text":"The Fourier transform is\nwidehatf(q) = int_mathbb R^3 e^-i q cdot x dx\nFourier transforms of centered functions: If f(x) = R(x) Y_l^m(xx), then\nbeginaligned\n hat f( q)\n = int_mathbb R^3 R(x) Y_l^m(xx) e^-i q cdot x dx \n = sum_l = 0^infty 4 pi i^l\n sum_m = -l^l int_mathbb R^3\n R(x) j_l(q x)Y_l^m(-qq) Y_l^m(xx)\n Y_l^mast(xx)\n dx \n = 4 pi Y_l^m(-qq) i^l\n int_mathbb R^+ r^2 R(r) j_l(q r) dr\n endaligned\nThis also holds true for real spherical harmonics.","category":"page"},{"location":"advanced/useful_formulas/#Spherical-harmonics-1","page":"Useful formulas","title":"Spherical harmonics","text":"","category":"section"},{"location":"advanced/useful_formulas/#","page":"Useful formulas","title":"Useful formulas","text":"Plane wave expansion formula\ne^i q cdot r =\n 4 pi sum_l = 0^infty sum_m = -l^l\n i^l j_l(q r) Y_l^m(qq) Y_l^mast(rr)\nSpherical harmonics orthogonality\nint_mathbbS^2 Y_l^m*(r)Y_l^m(r) dr\n = delta_ll delta_mm\nThis also holds true for real spherical harmonics.","category":"page"},{"location":"examples/metallic_systems/#","page":"Temperature and metallic systems","title":"Temperature and metallic systems","text":"EditURL = \"https://github.com/JuliaMolSim/DFTK.jl/blob/master/examples/metallic_systems.jl\"","category":"page"},{"location":"examples/metallic_systems/#Temperature-and-metallic-systems-1","page":"Temperature and metallic systems","title":"Temperature and metallic systems","text":"","category":"section"},{"location":"examples/metallic_systems/#","page":"Temperature and metallic systems","title":"Temperature and metallic systems","text":"(Image: ) (Image: )","category":"page"},{"location":"examples/metallic_systems/#","page":"Temperature and metallic systems","title":"Temperature and metallic systems","text":"In this example we consider the modeling of a magnesium lattice as a simple example for a metallic system. For our treatment we will use the PBE exchange-correlation functional. First we import required packages and setup the lattice.","category":"page"},{"location":"examples/metallic_systems/#","page":"Temperature and metallic systems","title":"Temperature and metallic systems","text":"using DFTK\nusing Plots\n\na = 3.01794 # bohr\nb = 5.22722 # bohr\nc = 9.77362 # bohr\nlattice = [[-a -a 0]; [-b b 0]; [0 0 -c]]\nMg = ElementPsp(:Mg, psp=load_psp(\"hgh/pbe/Mg-q2\"))\natoms = [Mg => [[2/3, 1/3, 1/4], [1/3, 2/3, 3/4]]];\nnothing #hide","category":"page"},{"location":"examples/metallic_systems/#","page":"Temperature and metallic systems","title":"Temperature and metallic systems","text":"Next we build the PBE model and discretize it. Since magnesium is a metal we apply a small smearing temperature to ease convergence using the Fermi-Dirac smearing scheme. Note that both the Ecut is too small as well as the minimal k-point spacing kspacing far too large to give a converged result. These have been selected to obtain a fast execution time.","category":"page"},{"location":"examples/metallic_systems/#","page":"Temperature and metallic systems","title":"Temperature and metallic systems","text":"kspacing = 0.5 # Minimal spacing of k-points,","category":"page"},{"location":"examples/metallic_systems/#","page":"Temperature and metallic systems","title":"Temperature and metallic systems","text":"in units of wavevectors (inverse Bohrs)","category":"page"},{"location":"examples/metallic_systems/#","page":"Temperature and metallic systems","title":"Temperature and metallic systems","text":"Ecut = 5 # kinetic energy cutoff in Hartree\ntemperature = 0.01 # Smearing temperature in Hartree\n\nkgrid = kgrid_size_from_minimal_spacing(lattice, kspacing)\nkgrid_size_from_minimal_spacing(lattice, kspacing)\nmodel = model_DFT(lattice, atoms, [:gga_x_pbe, :gga_c_pbe];\n temperature=temperature,\n smearing=DFTK.Smearing.FermiDirac())\nbasis = PlaneWaveBasis(model, Ecut, kgrid=kgrid);\nnothing #hide","category":"page"},{"location":"examples/metallic_systems/#","page":"Temperature and metallic systems","title":"Temperature and metallic systems","text":"Finally we run the SCF. Even though two magnesium atoms in our pseudopotential model only result in four valence electrons being explicitly treated, we still solve for eight bands in order to capture the partial occupations beyond the Fermi level due to the employed smearing scheme.","category":"page"},{"location":"examples/metallic_systems/#","page":"Temperature and metallic systems","title":"Temperature and metallic systems","text":"scfres = self_consistent_field(basis, n_bands=8);\nnothing #hide","category":"page"},{"location":"examples/metallic_systems/#","page":"Temperature and metallic systems","title":"Temperature and metallic systems","text":"scfres.energies","category":"page"},{"location":"examples/metallic_systems/#","page":"Temperature and metallic systems","title":"Temperature and metallic systems","text":"The fact that magnesium is a metal is confirmed by plotting the density of states around the Fermi level.","category":"page"},{"location":"examples/metallic_systems/#","page":"Temperature and metallic systems","title":"Temperature and metallic systems","text":"εs = range(minimum(minimum(scfres.eigenvalues)) - .5,\n maximum(maximum(scfres.eigenvalues)) + .5, length=1000)\nDs = DOS.(εs, Ref(basis), Ref(scfres.eigenvalues))\nq = plot(εs, Ds, label=\"DOS\")\nvline!(q, [scfres.εF], label=\"εF\")","category":"page"},{"location":"examples/pymatgen/#","page":"Creating supercells with pymatgen","title":"Creating supercells with pymatgen","text":"EditURL = \"https://github.com/JuliaMolSim/DFTK.jl/blob/master/examples/pymatgen.jl\"","category":"page"},{"location":"examples/pymatgen/#Creating-supercells-with-pymatgen-1","page":"Creating supercells with pymatgen","title":"Creating supercells with pymatgen","text":"","category":"section"},{"location":"examples/pymatgen/#","page":"Creating supercells with pymatgen","title":"Creating supercells with pymatgen","text":"(Image: ) (Image: )","category":"page"},{"location":"examples/pymatgen/#","page":"Creating supercells with pymatgen","title":"Creating supercells with pymatgen","text":"The Pymatgen python library allows to setup solid-state calculations using a flexible set of classes as well as an API to an online data base of structures. Its Structure and Lattice objects are directly supported by the DFTK load_atoms and load_lattice functions, such that DFTK may be readily used to run calculation on systems defined in pymatgen. Using the pymatgen_structure function a conversion from DFTK to pymatgen structures is also possible. In the following we use this to create a silicon supercell and find its LDA ground state using direct minimisation.","category":"page"},{"location":"examples/pymatgen/#","page":"Creating supercells with pymatgen","title":"Creating supercells with pymatgen","text":"First we setup the silicon lattice in DFTK.","category":"page"},{"location":"examples/pymatgen/#","page":"Creating supercells with pymatgen","title":"Creating supercells with pymatgen","text":"using DFTK\n\na = 10.263141334305942 # Lattice constant in Bohr\nlattice = a / 2 .* [[0 1 1.]; [1 0 1.]; [1 1 0.]]\nSi = ElementPsp(:Si, psp=load_psp(\"hgh/lda/Si-q4\"))\natoms = [Si => [ones(3)/8, -ones(3)/8]];\nnothing #hide","category":"page"},{"location":"examples/pymatgen/#","page":"Creating supercells with pymatgen","title":"Creating supercells with pymatgen","text":"Next we make a [2, 2, 2] supercell using pymatgen","category":"page"},{"location":"examples/pymatgen/#","page":"Creating supercells with pymatgen","title":"Creating supercells with pymatgen","text":"pystruct = pymatgen_structure(lattice, atoms)\npystruct.make_supercell([2, 2, 2])\nlattice = load_lattice(pystruct)\natoms = [Si => [s.frac_coords for s in pystruct.sites]];\nnothing #hide","category":"page"},{"location":"examples/pymatgen/#","page":"Creating supercells with pymatgen","title":"Creating supercells with pymatgen","text":"Setup an LDA model and discretize using a single kpoint and a small Ecut of 5 Hartree. Notice that PlaneWaveBasis defaults to just using the Γ-point if no k-point options are provided.","category":"page"},{"location":"examples/pymatgen/#","page":"Creating supercells with pymatgen","title":"Creating supercells with pymatgen","text":"model = model_LDA(lattice, atoms)\nbasis = PlaneWaveBasis(model, 5)\n\n# Find the ground state using direct minimisation (always using SCF is boring ...)\nscfres = direct_minimization(basis, tol=1e-5);\nnothing #hide","category":"page"},{"location":"examples/pymatgen/#","page":"Creating supercells with pymatgen","title":"Creating supercells with pymatgen","text":"scfres.energies","category":"page"},{"location":"examples/arbitrary_floattype/#","page":"Arbitrary floating-point types","title":"Arbitrary floating-point types","text":"EditURL = \"https://github.com/JuliaMolSim/DFTK.jl/blob/master/examples/arbitrary_floattype.jl\"","category":"page"},{"location":"examples/arbitrary_floattype/#Arbitrary-floating-point-types-1","page":"Arbitrary floating-point types","title":"Arbitrary floating-point types","text":"","category":"section"},{"location":"examples/arbitrary_floattype/#","page":"Arbitrary floating-point types","title":"Arbitrary floating-point types","text":"(Image: ) (Image: )","category":"page"},{"location":"examples/arbitrary_floattype/#","page":"Arbitrary floating-point types","title":"Arbitrary floating-point types","text":"Since DFTK is completely generic in the floating-point type in its routines, there is no reason to perform the computation using double-precision arithmetic (i.e.Float64). Other floating-point types such as Float32 (single precision) are readily supported as well. On top of that we already reported[HLC2020] calculations in DFTK using elevated precision from DoubleFloats.jl or interval arithmetic using IntervalArithmetic.jl. In this example, however, we will concentrate on single-precision computations with Float32. The setup of such a reduced-precision calculation is basically identical to the regular case, since Julia automatically compiles all routines of DFTK at the precision, which is used for the lattice vectors. Apart from setting up the model with an explicit cast of the lattice vectors to Float32, there is thus no change in user code required:","category":"page"},{"location":"examples/arbitrary_floattype/#","page":"Arbitrary floating-point types","title":"Arbitrary floating-point types","text":"[HLC2020]: M. F. Herbst, A. Levitt, E. Cancès. A posteriori error estimation for the non-self-consistent Kohn-Sham equations ArXiv 2004.13549","category":"page"},{"location":"examples/arbitrary_floattype/#","page":"Arbitrary floating-point types","title":"Arbitrary floating-point types","text":"using DFTK\n\n# Setup silicon lattice\na = 10.263141334305942 # lattice constant in Bohr\nlattice = a / 2 .* [[0 1 1.]; [1 0 1.]; [1 1 0.]]\nSi = ElementPsp(:Si, psp=load_psp(:Si, functional=\"lda\"))\natoms = [Si => [ones(3)/8, -ones(3)/8]]\n\n# Cast to Float32, setup model and basis\nmodel = model_DFT(Array{Float32}(lattice), atoms, [:lda_x, :lda_c_vwn])\nEcut = 7\nbasis = PlaneWaveBasis(model, Ecut, kgrid=[4, 4, 4])\n\n# Run the SCF\nscfres = self_consistent_field(basis, tol=1e-4);\nnothing #hide","category":"page"},{"location":"examples/arbitrary_floattype/#","page":"Arbitrary floating-point types","title":"Arbitrary floating-point types","text":"To check the calculation has really run in Float32, we check the energies and density are expressed in this floating-point type:","category":"page"},{"location":"examples/arbitrary_floattype/#","page":"Arbitrary floating-point types","title":"Arbitrary floating-point types","text":"scfres.energies","category":"page"},{"location":"examples/arbitrary_floattype/#","page":"Arbitrary floating-point types","title":"Arbitrary floating-point types","text":"eltype(sum(values(scfres.energies)))","category":"page"},{"location":"examples/arbitrary_floattype/#","page":"Arbitrary floating-point types","title":"Arbitrary floating-point types","text":"eltype(scfres.ρ.real)","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"EditURL = \"https://github.com/JuliaMolSim/DFTK.jl/blob/master/examples/gross_pitaevskii.jl\"","category":"page"},{"location":"examples/gross_pitaevskii/#Gross-Pitaevskii-equation-in-one-dimension-1","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"","category":"section"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"(Image: ) (Image: )","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"In this example we will use DFTK to solve the Gross-Pitaevskii equation, and use this opportunity to explore a few internals.","category":"page"},{"location":"examples/gross_pitaevskii/#The-model-1","page":"Gross-Pitaevskii equation in one dimension","title":"The model","text":"","category":"section"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"The Gross-Pitaevskii equation (GPE) is a simple non-linear equation used to model bosonic systems in a mean-field approach. Denoting by ψ the effective one-particle bosonic wave function, the time-independent GPE reads in atomic units:","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":" H ψ = left(-frac12 Δ + V + 2 C ψ^2right) ψ = μ ψ qquad ψ_L^2 = 1","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"where C provides the strength of the boson-boson coupling. It's in particular a favorite model of applied mathematicians because it has a structure simpler than but similar to that of DFT, and displays interesting behavior (especially in higher dimensions with magnetic fields, see Gross-Pitaevskii equation with magnetism).","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"We wish to model this equation in 1D using DFTK. First we set up the lattice. For a 1D case we supply two zero lattice vectors,","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"a = 10\nlattice = a .* [[1 0 0.]; [0 0 0]; [0 0 0]];\nnothing #hide","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"which is special cased in DFTK to support 1D models.","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"For the potential term V we just pick a harmonic potential. The real-space grid is in 01) in fractional coordinates( see Lattices and lattice vectors), therefore:","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"pot(x) = (x - a/2)^2;\nnothing #hide","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"We setup each energy term in sequence: kinetic, potential and nonlinear term. For the non-linearity we use the PowerNonlinearity(C, α) term of DFTK. This object introduces an energy term C ρ(r)^α dr to the total energy functional, thus a potential term α C ρ^α-1. In our case we thus need the parameters","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"C = 1.0\nα = 2;\nnothing #hide","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"... and with this build the model","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"using DFTK\nusing LinearAlgebra\n\nn_electrons = 1 # Increase this for fun\nterms = [Kinetic(),\n ExternalFromReal(r -> pot(r[1])),\n PowerNonlinearity(C, α),\n]\nmodel = Model(lattice; n_electrons=n_electrons, terms=terms,\n spin_polarization=:spinless); # use \"spinless electrons\"\nnothing #hide","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"We discretize using a moderate Ecut (For 1D values up to 5000 are completely fine) and run a direct minimization algorithm:","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"Ecut = 500\nbasis = PlaneWaveBasis(model, Ecut)\nscfres = direct_minimization(basis, tol=1e-8) # This is a constrained preconditioned LBFGS\nscfres.energies","category":"page"},{"location":"examples/gross_pitaevskii/#Internals-1","page":"Gross-Pitaevskii equation in one dimension","title":"Internals","text":"","category":"section"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"We use the opportunity to explore some of DFTK internals.","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"Extract the converged density and the obtained wave function:","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"ρ = real(scfres.ρ.real)[:, 1, 1] # converged density\nψ_fourier = scfres.ψ[1][:, 1]; # first kpoint, all G components, first eigenvector\nnothing #hide","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"Transform the wave function to real space and fix the phase:","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"ψ = G_to_r(basis, basis.kpoints[1], ψ_fourier)[:, 1, 1]\nψ /= (ψ[div(end, 2)] / abs(ψ[div(end, 2)]));\nnothing #hide","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"Check whether ψ is normalised:","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"x = a * vec(first.(DFTK.r_vectors(basis)))\nN = length(x)\ndx = a / N # real-space grid spacing\n@assert sum(abs2.(ψ)) * dx ≈ 1.0","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"The density is simply built from ψ:","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"norm(scfres.ρ.real - abs2.(ψ))","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"We summarize the ground state in a nice plot:","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"using Plots\n\np = plot(x, real.(ψ), label=\"real(ψ)\")\nplot!(p, x, imag.(ψ), label=\"imag(ψ)\")\nplot!(p, x, ρ, label=\"ρ\")","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"The energy_hamiltonian function can be used to get the energy and effective Hamiltonian (derivative of the energy with respect to the density matrix) of a particular state (ψ, occupation). The density ρ associated to this state is precomputed and passed to the routine as an optimization.","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"E, ham = energy_hamiltonian(basis, scfres.ψ, scfres.occupation; ρ=scfres.ρ)\n@assert sum(values(E)) == sum(values(scfres.energies))","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"Now the Hamiltonian contains all the blocks corresponding to kpoints. Here, we just have one kpoint:","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"H = ham.blocks[1];\nnothing #hide","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"H can be used as a linear operator (efficiently using FFTs), or converted to a dense matrix:","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"ψ11 = scfres.ψ[1][:, 1] # first kpoint, first eigenvector\nHmat = Array(H) # This is now just a plain Julia matrix, which we can compute and store in this simple 1D example\n@assert norm(Hmat * ψ11 - H * ψ11) < 1e-10","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"Let's check that ψ11 is indeed an eigenstate:","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"norm(H * ψ11 - dot(ψ11, H * ψ11) * ψ11)","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"Build a finite-differences version of the GPE operator H, as a sanity check:","category":"page"},{"location":"examples/gross_pitaevskii/#","page":"Gross-Pitaevskii equation in one dimension","title":"Gross-Pitaevskii equation in one dimension","text":"A = Array(Tridiagonal(-ones(N - 1), 2ones(N), -ones(N - 1)))\nA[1, end] = A[end, 1] = -1\nK = A / dx^2 / 2\nV = Diagonal(pot.(x) + C .* α .* (ρ.^(α-1)))\nH_findiff = K + V;\nmaximum(abs.(H_findiff*ψ - (dot(ψ, H_findiff*ψ) / dot(ψ, ψ)) * ψ))","category":"page"},{"location":"examples/gross_pitaevskii_2D/#","page":"Gross-Pitaevskii equation with magnetism","title":"Gross-Pitaevskii equation with magnetism","text":"EditURL = \"https://github.com/JuliaMolSim/DFTK.jl/blob/master/examples/gross_pitaevskii_2D.jl\"","category":"page"},{"location":"examples/gross_pitaevskii_2D/#Gross-Pitaevskii-equation-with-magnetism-1","page":"Gross-Pitaevskii equation with magnetism","title":"Gross-Pitaevskii equation with magnetism","text":"","category":"section"},{"location":"examples/gross_pitaevskii_2D/#","page":"Gross-Pitaevskii equation with magnetism","title":"Gross-Pitaevskii equation with magnetism","text":"(Image: ) (Image: )","category":"page"},{"location":"examples/gross_pitaevskii_2D/#","page":"Gross-Pitaevskii equation with magnetism","title":"Gross-Pitaevskii equation with magnetism","text":"We solve the 2D Gross-Pitaevskii equation with a magnetic field. This is similar to the previous example (Gross-Pitaevskii equation in one dimension, but with an extra term for the magnetic field.","category":"page"},{"location":"examples/gross_pitaevskii_2D/#","page":"Gross-Pitaevskii equation with magnetism","title":"Gross-Pitaevskii equation with magnetism","text":"using DFTK\nusing StaticArrays\nusing Plots","category":"page"},{"location":"examples/gross_pitaevskii_2D/#","page":"Gross-Pitaevskii equation with magnetism","title":"Gross-Pitaevskii equation with magnetism","text":"Unit cell. Having one lattice vectors as zero means a 2D system","category":"page"},{"location":"examples/gross_pitaevskii_2D/#","page":"Gross-Pitaevskii equation with magnetism","title":"Gross-Pitaevskii equation with magnetism","text":"a = 10\nlattice = a .* [[1 0 0.]; [0 1 0]; [0 0 0]];\nnothing #hide","category":"page"},{"location":"examples/gross_pitaevskii_2D/#","page":"Gross-Pitaevskii equation with magnetism","title":"Gross-Pitaevskii equation with magnetism","text":"Confining scalar potential, and magnetic vector potential","category":"page"},{"location":"examples/gross_pitaevskii_2D/#","page":"Gross-Pitaevskii equation with magnetism","title":"Gross-Pitaevskii equation with magnetism","text":"pot(x, y, z) = (x - a/2)^2 + (y - a/2)^2\nApot(x, y, z) = .2 * @SVector [y - a/2, -(x - a/2), 0]\nApot(X) = Apot(X...);\nnothing #hide","category":"page"},{"location":"examples/gross_pitaevskii_2D/#","page":"Gross-Pitaevskii equation with magnetism","title":"Gross-Pitaevskii equation with magnetism","text":"Parameters","category":"page"},{"location":"examples/gross_pitaevskii_2D/#","page":"Gross-Pitaevskii equation with magnetism","title":"Gross-Pitaevskii equation with magnetism","text":"Ecut = 20 # Increase this for production\nC = 500.0\nα = 2\nn_electrons = 1; # Increase this for fun\nnothing #hide","category":"page"},{"location":"examples/gross_pitaevskii_2D/#","page":"Gross-Pitaevskii equation with magnetism","title":"Gross-Pitaevskii equation with magnetism","text":"Collect all the terms, build and run the model","category":"page"},{"location":"examples/gross_pitaevskii_2D/#","page":"Gross-Pitaevskii equation with magnetism","title":"Gross-Pitaevskii equation with magnetism","text":"terms = [Kinetic(),\n ExternalFromReal(X -> pot(X...)),\n PowerNonlinearity(C, α),\n Magnetic(Apot),\n]\nmodel = Model(lattice; n_electrons=n_electrons,\n terms=terms, spin_polarization=:spinless) # \"spinless electrons\"\nbasis = PlaneWaveBasis(model, Ecut)\nscfres = direct_minimization(basis, tol=1e-5) # Reduce tol for production\nheatmap(scfres.ρ.real[:, :, 1], c=:blues)","category":"page"},{"location":"guide/installation/#Installation-1","page":"Installation","title":"Installation","text":"","category":"section"},{"location":"guide/installation/#","page":"Installation","title":"Installation","text":"DFTK is not yet registered in the General registry of Julia. Instead you can obtain it from the MolSim registry, which contains a bunch of packages related to performing molecular simulations in Julia. At least Julia 1.3 is required.","category":"page"},{"location":"guide/installation/#","page":"Installation","title":"Installation","text":"First add MolSim to your installed registries. For this use","category":"page"},{"location":"guide/installation/#","page":"Installation","title":"Installation","text":"] registry add https://github.com/JuliaMolSim/MolSim.git","category":"page"},{"location":"guide/installation/#","page":"Installation","title":"Installation","text":"from a Julia command line. Afterwards you can install DFTK like any other package in Julia:","category":"page"},{"location":"guide/installation/#","page":"Installation","title":"Installation","text":"] add DFTK","category":"page"},{"location":"guide/installation/#","page":"Installation","title":"Installation","text":"or if you like to be up to date:","category":"page"},{"location":"guide/installation/#","page":"Installation","title":"Installation","text":"] add DFTK#master","category":"page"},{"location":"guide/installation/#Python-dependencies-1","page":"Installation","title":"Python dependencies","text":"","category":"section"},{"location":"guide/installation/#","page":"Installation","title":"Installation","text":"Some parts of the code require a working Python installation with the libraries pymatgen and spglib. Check out which version of python is used by the PyCall.jl package. You can do this for example with the Julia commands","category":"page"},{"location":"guide/installation/#","page":"Installation","title":"Installation","text":"using PyCall\nPyCall.python","category":"page"},{"location":"guide/installation/#","page":"Installation","title":"Installation","text":"Then use the corresponding package manager (usually apt, pip, pip3 or conda) to install aforementioned libraries, for example","category":"page"},{"location":"guide/installation/#","page":"Installation","title":"Installation","text":"pip install spglib pymatgen","category":"page"},{"location":"guide/installation/#","page":"Installation","title":"Installation","text":"or","category":"page"},{"location":"guide/installation/#","page":"Installation","title":"Installation","text":"conda install -c conda-forge spglib pymatgen","category":"page"},{"location":"guide/installation/#","page":"Installation","title":"Installation","text":"Afterwards you're all set and should be able to run the code in the examples directory.","category":"page"},{"location":"api/#API-reference-1","page":"API reference","title":"API reference","text":"","category":"section"},{"location":"api/#","page":"API reference","title":"API reference","text":"This page provides a plain list of all documented functions, structs, modules and macros in DFTK. Note that this list is neither structured, complete nor particularly clean, so it only provides rough orientation at the moment. The best reference is the code itself.","category":"page"},{"location":"api/#","page":"API reference","title":"API reference","text":"Modules = [DFTK, DFTK.Smearing]","category":"page"},{"location":"api/#DFTK.DFTK","page":"API reference","title":"DFTK.DFTK","text":"DFTK –- The density-functional toolkit. Provides functionality for experimenting with plane-wave density-functional theory algorithms.\n\n\n\n\n\n","category":"module"},{"location":"api/#DFTK.AtomicLocal","page":"API reference","title":"DFTK.AtomicLocal","text":"Atomic local potential defined by model.atoms.\n\n\n\n\n\n","category":"type"},{"location":"api/#DFTK.AtomicNonlocal","page":"API reference","title":"DFTK.AtomicNonlocal","text":"Nonlocal term coming from norm-conserving pseudopotentials in Kleinmann-Bylander form. textEnergy = sum_a sum_ij sum_n f_n ψ_np_ai D_ij p_ajψ_n\n\n\n\n\n\n","category":"type"},{"location":"api/#DFTK.ElementCohenBergstresser-Tuple{Any}","page":"API reference","title":"DFTK.ElementCohenBergstresser","text":"Element where the interaction with electrons is modelled as in CohenBergstresser1966. Only the homonuclear lattices of the diamond structure are implemented (i.e. Si, Ge, Sn).\n\nkey may be an element symbol (like :Si), an atomic number (e.g. 14) or an element name (e.g. \"silicon\")\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.ElementCoulomb-Tuple{Any}","page":"API reference","title":"DFTK.ElementCoulomb","text":"Element interacting with electrons via a bare Coulomb potential (for all-electron calculations) key may be an element symbol (like :Si), an atomic number (e.g. 14) or an element name (e.g. \"silicon\")\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.ElementPsp-Tuple{Any}","page":"API reference","title":"DFTK.ElementPsp","text":"Element interacting with electrons via a pseudopotential model. key may be an element symbol (like :Si), an atomic number (e.g. 14) or an element name (e.g. \"silicon\")\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.Energies","page":"API reference","title":"DFTK.Energies","text":"A simple struct to contain a vector of energies, and utilities to print them in a nice format.\n\n\n\n\n\n","category":"type"},{"location":"api/#DFTK.Entropy","page":"API reference","title":"DFTK.Entropy","text":"Entropy term -TS, where S is the electronic entropy. Turns the energy E into the free energy F=E-TS. This is in particular useful because the free energy, not the energy, is minimized at self-consistency.\n\n\n\n\n\n","category":"type"},{"location":"api/#DFTK.EtsfFolder-Tuple{AbstractString}","page":"API reference","title":"DFTK.EtsfFolder","text":"Initialize a EtsfFolder from the path to the folder which contains the data in the ETSF Nanoquanta format.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.Ewald","page":"API reference","title":"DFTK.Ewald","text":"Ewald term: electrostatic energy per unit cell of the array of point charges defined by model.atoms in a uniform background of compensating charge yielding net neutrality.\n\n\n\n\n\n","category":"type"},{"location":"api/#DFTK.ExternalFromFourier","page":"API reference","title":"DFTK.ExternalFromFourier","text":"External potential from the (unnormalized) Fourier coefficients V(G) G is passed in cartesian coordinates\n\n\n\n\n\n","category":"type"},{"location":"api/#DFTK.ExternalFromReal","page":"API reference","title":"DFTK.ExternalFromReal","text":"External potential from an analytic function V (in cartesian coordinates). No low-pass filtering is performed.\n\n\n\n\n\n","category":"type"},{"location":"api/#DFTK.Hartree","page":"API reference","title":"DFTK.Hartree","text":"Hartree term: for a decaying potential V the energy would be\n\n1/2 ∫ρ(x)ρ(y)V(x-y) dxdy\n\nwith the integral on x in the unit cell and of y in the whole space. For the Coulomb potential with periodic boundary conditions, this is rather\n\n1/2 ∫ρ(x)ρ(y) G(x-y) dx dy\n\nwhere G is the Green's function of the periodic Laplacian with zero mean (-Δ G = sum{R} 4π δR, integral of G zero on a unit cell).\n\n\n\n\n\n","category":"type"},{"location":"api/#DFTK.KerkerMixing","page":"API reference","title":"DFTK.KerkerMixing","text":"Kerker mixing: J^-1 ≈ α*G^2/(G0^2 + G^2)\n\n\n\n\n\n","category":"type"},{"location":"api/#DFTK.Kinetic","page":"API reference","title":"DFTK.Kinetic","text":"Kinetic energy: 1/2 sumn fn ∫ |∇ψn|^2.\n\n\n\n\n\n","category":"type"},{"location":"api/#DFTK.Kpoint","page":"API reference","title":"DFTK.Kpoint","text":"Discretization information for kpoint-dependent quantities such as orbitals. More generally, a kpoint is a block of the Hamiltonian; eg collinear spin is treated by doubling the number of kpoints.\n\n\n\n\n\n","category":"type"},{"location":"api/#DFTK.Magnetic","page":"API reference","title":"DFTK.Magnetic","text":"Magnetic term A(-i). It is assumed (but not checked) that A = 0.\n\n\n\n\n\n","category":"type"},{"location":"api/#DFTK.Model","page":"API reference","title":"DFTK.Model","text":"A physical specification of a model. Contains the geometry information, but no discretization parameters. The exact model used is defined by the list of terms.\n\n\n\n\n\n","category":"type"},{"location":"api/#DFTK.PlaneWaveBasis","page":"API reference","title":"DFTK.PlaneWaveBasis","text":"A plane-wave discretized Model. Normalization conventions:\n\nThings that are expressed in the G basis are normalized so that if x is the vector, then the actual function is sum_G x_G e_G with e_G(x) = e^iG xsqrt(unit_cell_volume). This is so that, eg norm(ψ) = 1 gives the correct normalization. This also holds for the density and the potentials.\nQuantities expressed on the real-space grid are in actual values.\n\nG_to_r and r_to_G convert between these representations.\n\n\n\n\n\n","category":"type"},{"location":"api/#DFTK.PlaneWaveBasis-Tuple{Model,Number}","page":"API reference","title":"DFTK.PlaneWaveBasis","text":"Creates a PlaneWaveBasis using the kinetic energy cutoff Ecut and a Monkhorst-Pack kpoint grid kgrid shifted by kshift (0 or 1/2 in each direction).\n\nIf enable_bzmesh_symmetry is true (default) the symmetries of the crystal are used to reduce the number of k-Points which are treated explicitly. In this case all guess densities and potential functions must agree with the crystal symmetries or the result is undefined.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.PlaneWaveBasis-Tuple{PlaneWaveBasis,AbstractArray{T,1} where T,AbstractArray{T,1} where T}","page":"API reference","title":"DFTK.PlaneWaveBasis","text":"Creates a new basis identical to basis, but with a different set of kpoints\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.PlaneWaveBasis-Tuple{PlaneWaveBasis}","page":"API reference","title":"DFTK.PlaneWaveBasis","text":"\" Convert a basis into one that uses or doesn't use BZ symmetrization Mainly useful for debug purposes (e.g. in cases we don't want to bother with symmetry)\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.PowerNonlinearity","page":"API reference","title":"DFTK.PowerNonlinearity","text":"Power nonlinearity, with energy C ∫ρ^α.\n\n\n\n\n\n","category":"type"},{"location":"api/#DFTK.PreconditionerNone","page":"API reference","title":"DFTK.PreconditionerNone","text":"No preconditioning\n\n\n\n\n\n","category":"type"},{"location":"api/#DFTK.PreconditionerTPA","page":"API reference","title":"DFTK.PreconditionerTPA","text":"(simplified version of) Tetter-Payne-Allan preconditioning ↑ M.P. Teter, M.C. Payne and D.C. Allan, Phys. Rev. B 40, 12255 (1989).\n\n\n\n\n\n","category":"type"},{"location":"api/#DFTK.PspCorrection","page":"API reference","title":"DFTK.PspCorrection","text":"Pseudopotential correction energy. TODO discuss the need for this.\n\n\n\n\n\n","category":"type"},{"location":"api/#DFTK.PspHgh-Union{Tuple{T}, Tuple{Any,Any,Any,Any,Array{Array{T,2},1}}} where T","page":"API reference","title":"DFTK.PspHgh","text":"PspHgh(Zion::Number, rloc::Number, cloc::Vector, rp::Vector, h::Vector;\n identifier=\"\", description=\"\")\n\nConstruct a Hartwigsen, Goedecker, Teter, Hutter separable dual-space Gaussian pseudopotential (1998). The required parameters are the ionic charge Zion (total charge - valence electrons), the range for the local Gaussian charge distribution rloc, the coefficients for the local part cloc, the projector radius rp (one per AM channel) and the non-local coupling coefficients between the projectors h (one matrix per AM channel).\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.RealFourierArray","page":"API reference","title":"DFTK.RealFourierArray","text":"A structure to facilitate manipulations of an array of type T in both real and fourier space. Create with from_real or from_fourier, and access with A.real and A.fourier.\n\n\n\n\n\n","category":"type"},{"location":"api/#DFTK.SimpleMixing","page":"API reference","title":"DFTK.SimpleMixing","text":"Simple mixing: J^-1 ≈ α\n\n\n\n\n\n","category":"type"},{"location":"api/#DFTK.Xc","page":"API reference","title":"DFTK.Xc","text":"Exchange-correlation term, defined by a list of functionals and usually evaluated through libxc.\n\n\n\n\n\n","category":"type"},{"location":"api/#DFTK.DOS-Tuple{Any,Any,Any}","page":"API reference","title":"DFTK.DOS","text":"Total density of states at energy ε\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.G_to_r!-Union{Tuple{Tf}, Tuple{Tr}, Tuple{AbstractArray{T,3} where T,PlaneWaveBasis,AbstractArray{T,3} where T}} where Tf where Tr","page":"API reference","title":"DFTK.G_to_r!","text":"In-place version of G_to_r.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.G_to_r-Tuple{PlaneWaveBasis,AbstractArray{T,3} where T}","page":"API reference","title":"DFTK.G_to_r","text":"G_to_r(basis::PlaneWaveBasis, [kpt::Kpoint, ] f_fourier)\n\nPerform an iFFT to obtain the quantity defined by f_fourier defined on the k-dependent spherical basis set (if kpt is given) or the k-independent cubic (if it is not) on the real-space grid.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.G_vectors-Tuple{Any}","page":"API reference","title":"DFTK.G_vectors","text":"Return the list of wave vectors (integer coordinates) for the cubic basis set.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.G_vectors-Tuple{Kpoint}","page":"API reference","title":"DFTK.G_vectors","text":"The list of G vectors of a given basis or kpoint.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.LDOS-NTuple{4,Any}","page":"API reference","title":"DFTK.LDOS","text":"Local density of states, in real space\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.NOS-Tuple{Any,Any,Any}","page":"API reference","title":"DFTK.NOS","text":"NOS(ε, basis, eigenvalues; smearing=basis.model.smearing,\n temperature=basis.model.temperature)\n\nThe number of Kohn-Sham states in a temperature window of width temperature around the energy ε contributing to the DOS at temperature T.\n\nThis quantity is not a physical quantity, but rather a dimensionless approximate measure for how well properties near the Fermi surface are sampled with the passed smearing and temperature T. It increases with both T and better sampling of the BZ with k-Points. A value gg 1 indicates a good sampling of properties near the Fermi surface.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.apply_χ0-NTuple{5,Any}","page":"API reference","title":"DFTK.apply_χ0","text":"Returns the change in density δρ for a given δV. Drop all non-diagonal terms with (f(εn)-f(εm))/(εn-εm) factor less than droptol. If sternheimer_contribution is false, only compute excitations inside the provided orbitals.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.bzmesh_ir_wedge-Tuple{Any,Any,Any}","page":"API reference","title":"DFTK.bzmesh_ir_wedge","text":"bzmesh_ir_wedge(kgrid_size, lattice, atoms; tol_symmetry=1e-5)\n\nConstruct the irreducible wedge of a uniform Brillouin zone mesh for sampling k-Points. The function returns a tuple (kcoords, ksymops), where kcoords are the list of irreducible k-Points and ksymops are a list of symmetry operations for regenerating the full mesh. lattice are the lattice vectors, column by column, atoms are pairs representing a mapping from Element objects to a list of positions in fractional coordinates. tol_symmetry is the tolerance used for searching for symmetry operations.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.bzmesh_uniform-Tuple{Any}","page":"API reference","title":"DFTK.bzmesh_uniform","text":"bzmesh_uniform(kgrid_size)\n\nConstruct a uniform Brillouin zone mesh for sampling the k-Points. The function returns a tuple (kcoords, ksymops), where kcoords are the list of k-Points and ksymops are a list of symmetry operations (for interface compatibility with PlaneWaveBasis and bzmesh_irreducible. No symmetry reduction is attempted, such that there will be prod(kgrid_size) k-Points returned and all symmetry operations are the identity.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.charge_ionic-Tuple{DFTK.Element}","page":"API reference","title":"DFTK.charge_ionic","text":"Return the total ionic charge of an atom type (nuclear charge - core electrons)\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.charge_nuclear-Tuple{DFTK.Element}","page":"API reference","title":"DFTK.charge_nuclear","text":"Return the total nuclear charge of an atom type\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.compute_density-Tuple{PlaneWaveBasis,AbstractArray{T,1} where T,AbstractArray{T,1} where T}","page":"API reference","title":"DFTK.compute_density","text":"compute_density(basis::PlaneWaveBasis, ψ::AbstractVector, occupation::AbstractVector)\n\nCompute the density for a wave function ψ discretized on the plane-wave grid basis, where the individual k-Points are occupied according to occupation. ψ should be one coefficient matrix per k-Point.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.compute_χ0-Tuple{Any}","page":"API reference","title":"DFTK.compute_χ0","text":"Compute the independent-particle susceptibility. Will blow up for large systems. Drop all non-diagonal terms with (f(εn)-f(εm))/(εn-εm) factor less than droptol.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.determine_grid_size-Union{Tuple{T}, Tuple{AbstractArray{T,2},Any}} where T","page":"API reference","title":"DFTK.determine_grid_size","text":"Determine the minimal grid size for the cubic basis set to be able to represent product of orbitals (with the default supersampling=2).\n\nOptionally optimize the grid afterwards for the FFT procedure by ensuring factorization into small primes.\n\nThe function will determine the smallest cube containing the wave vectors G^22 leq E_textcut textsupersampling^2. For an exact representation of the density resulting from wave functions represented in the spherical basis sets, supersampling should be at least 2.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.diagonalize_all_kblocks-Tuple{Any,Hamiltonian,Int64}","page":"API reference","title":"DFTK.diagonalize_all_kblocks","text":"Function for diagonalising each k-Point blow of ham one step at a time. Some logic for interpolating between k-Points is used if interpolate_kpoints is true and if no guesses are given. eigensolver is the iterative eigensolver that really does the work, operating on a single k-Block. eigensolver should support the API eigensolver(A, X0; prec, tol, maxiter) prec_type should be a function that returns a preconditioner when called as prec(ham, kpt)\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.direct_minimization-Tuple{PlaneWaveBasis}","page":"API reference","title":"DFTK.direct_minimization","text":"Computes the ground state by direct minimization. kwargs... are passed to Optim.Options(). Note that the resulting ψ are not necessarily eigenvectors of the Hamiltonian.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.energy_ewald-Tuple{Any,Any,Any}","page":"API reference","title":"DFTK.energy_ewald","text":"Compute the electrostatic interaction energy per unit cell between point charges in a uniform background of compensating charge to yield net neutrality. the lattice and recip_lattice should contain the lattice and reciprocal lattice vectors as columns. charges and positions are the point charges and their positions (as an array of arrays) in fractional coordinates. If forces is not nothing, minus the derivatives of the energy with respect to positions is computed.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.energy_psp_correction-Tuple{Model}","page":"API reference","title":"DFTK.energy_psp_correction","text":"energy_psp_correction(model)\n\nCompute the correction term for properly modelling the interaction of the pseudopotential core with the compensating background charge induced by the Ewald term.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.eval_psp_local_fourier-Union{Tuple{T}, Tuple{PspHgh,T}} where T<:Real","page":"API reference","title":"DFTK.eval_psp_local_fourier","text":"eval_psp_local_fourier(psp, q)\n\nEvaluate the local part of the pseudopotential in reciprocal space.\n\nThis function computes V(q) = ∫R^3 Vloc(r) e^{-iqr} dr = 4π ∫{R+} sin(qr)/q r e^{-iqr} dr\n\nGTH98 except they do it with plane waves normalized by 1/sqrt(Ω).\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.eval_psp_local_real-Union{Tuple{T}, Tuple{PspHgh,T}} where T<:Real","page":"API reference","title":"DFTK.eval_psp_local_real","text":"eval_psp_local_real(psp, r)\n\nEvaluate the local part of the pseudopotential in real space. The vector r should be given in cartesian coordinates.\n\nGTH98\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.eval_psp_projection_radial-Union{Tuple{T}, Tuple{PspHgh,Any,Any,T}} where T<:Real","page":"API reference","title":"DFTK.eval_psp_projection_radial","text":"eval_psp_projection_radial(psp::PspHgh, i, l, q::Number)\n\nEvaluate the radial part of the i-th projector for angular momentum l at the reciprocal vector with modulus q.\n\np(q) = ∫{R+} r^2 p(r) jl(q r) dr\n\nHGH98 except they do it with plane waves normalized by 1/sqrt(Ω).\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.find_fermi_level-Tuple{Any,Any}","page":"API reference","title":"DFTK.find_fermi_level","text":"Find the Fermi level.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.find_occupation-Union{Tuple{T}, Tuple{PlaneWaveBasis{T},Any}} where T","page":"API reference","title":"DFTK.find_occupation","text":"Find the occupation and Fermi level.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.find_occupation_bandgap-Tuple{Any,Any}","page":"API reference","title":"DFTK.find_occupation_bandgap","text":"Find Fermi level and occupation for the given parameters, assuming a band gap and zero temperature. This function is for DEBUG purposes only, and the finite-temperature version with 0 temperature should be preferred.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.guess_density-Tuple{PlaneWaveBasis}","page":"API reference","title":"DFTK.guess_density","text":"guess_density(basis)\n\nBuild a superposition of atomic densities (SAD) guess density.\n\nWe take for the guess density a gaussian centered around the atom, of length specified by atom_decay_length, normalized to get the right number of electrons\n\nhatρ(G) = Z expleft(-(2π textlength G)^2right)\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.kgrid_size_from_minimal_spacing","page":"API reference","title":"DFTK.kgrid_size_from_minimal_spacing","text":"Selects a kgrid_size to ensure a minimal spacing (in inverse Bohrs) between kpoints. Default is 2π * 004 AA^-1.\n\n\n\n\n\n","category":"function"},{"location":"api/#DFTK.list_psp","page":"API reference","title":"DFTK.list_psp","text":"list_psp(element; functional, family, core, datadir_psp)\n\nList the pseudopotential files known to DFTK. Allows various ways to restrict the displayed files.\n\nExamples\n\njulia> list_psp(family=\"hgh\")\n\nwill list all HGH-type pseudopotentials and\n\njulia> list_psp(family=\"hgh\", functional=\"lda\")\n\nwill only list those for LDA (also known as Pade in this context) and\n\njulia> list_psp(:O, core=:semicore)\n\nwill list all oxygen semicore pseudopotentials known to DFTK.\n\n\n\n\n\n","category":"function"},{"location":"api/#DFTK.load_atoms-Tuple{Any,EtsfFolder}","page":"API reference","title":"DFTK.load_atoms","text":"Load a DFTK-compatible atoms object from the ETSF folder. Use the scalar type T to represent the data.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.load_basis-Tuple{Any,EtsfFolder}","page":"API reference","title":"DFTK.load_basis","text":"Load a DFTK-compatible basis object from the ETSF folder. Use the scalar type T to represent the data.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.load_density-Tuple{Any,EtsfFolder}","page":"API reference","title":"DFTK.load_density","text":"Load a DFTK-compatible density object from the ETSF folder. Use the scalar type T to represent the data.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.load_lattice-Tuple{Any,EtsfFolder}","page":"API reference","title":"DFTK.load_lattice","text":"Load a DFTK-compatible lattice object from the ETSF folder\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.load_lattice-Tuple{Any,PyCall.PyObject}","page":"API reference","title":"DFTK.load_lattice","text":"Load a DFTK-compatible lattice object from a supported python object (e.g. pymatgen or ASE)\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.load_model-Tuple{Any,EtsfFolder}","page":"API reference","title":"DFTK.load_model","text":"Load a DFTK-compatible model object from the ETSF folder. Use the scalar type T to represent the data.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.load_psp-Tuple{AbstractString}","page":"API reference","title":"DFTK.load_psp","text":"load_psp(key; datadir_psp)\n\nLoad a pseudopotential file from the library of pseudopotentials. The file is searched in the directory datadir_psp and by the key. If the key is a path to a valid file, the extension is used to determine the type of the pseudopotential file format and a respective class is returned.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.model_DFT-Tuple{AbstractArray{T,2} where T,Array{T,1} where T,Any}","page":"API reference","title":"DFTK.model_DFT","text":"Build a DFT model from the specified atoms, with the specified functionals.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.model_LDA-Tuple{AbstractArray{T,2} where T,Array{T,1} where T}","page":"API reference","title":"DFTK.model_LDA","text":"Build an LDA model (Teter93 parametrization) from the specified atoms.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.model_atomic-Tuple{AbstractArray{T,2} where T,Array{T,1} where T}","page":"API reference","title":"DFTK.model_atomic","text":"Convenience constructor, which builds a standard atomic (kinetic + atomic potential) model. Use extra_terms to add additional terms.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.n_elec_core-Tuple{DFTK.Element}","page":"API reference","title":"DFTK.n_elec_core","text":"Return the number of core electrons\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.n_elec_valence-Tuple{DFTK.Element}","page":"API reference","title":"DFTK.n_elec_valence","text":"Return the number of valence electrons\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.r_to_G!-Tuple{AbstractArray{T,3} where T,PlaneWaveBasis,AbstractArray{T,3} where T}","page":"API reference","title":"DFTK.r_to_G!","text":"In-place version of r_to_G!. NOTE: If kpt is given, not only f_fourier but also f_real is overwritten.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.r_to_G-Tuple{PlaneWaveBasis,AbstractArray{T,3} where T}","page":"API reference","title":"DFTK.r_to_G","text":"r_to_G(basis::PlaneWaveBasis, [kpt::Kpoint, ] f_real)\n\nPerform an FFT to obtain the Fourier representation of f_real. If kpt is given, the coefficients are truncated to the k-dependent spherical basis set.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.r_vectors-Union{Tuple{PlaneWaveBasis{T}}, Tuple{T}} where T","page":"API reference","title":"DFTK.r_vectors","text":"Return the list of r vectors, in reduced coordinates. By convention, this is in [0,1]^3.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.scf_damping_solver","page":"API reference","title":"DFTK.scf_damping_solver","text":"Create a damped SCF solver updating the density as x = β * x_new + (1 - β) * x\n\n\n\n\n\n","category":"function"},{"location":"api/#DFTK.scf_nlsolve_solver","page":"API reference","title":"DFTK.scf_nlsolve_solver","text":"Create a NLSolve-based SCF solver, by default using an Anderson-accelerated fixed-point scheme, keeping m steps for Anderson acceleration. See the NLSolve documentation for details about the other parameters and methods.\n\n\n\n\n\n","category":"function"},{"location":"api/#DFTK.self_consistent_field-Tuple{PlaneWaveBasis}","page":"API reference","title":"DFTK.self_consistent_field","text":"Solve the Kohn-Sham equations with a SCF algorithm, starting at ρ.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.standardize_atoms","page":"API reference","title":"DFTK.standardize_atoms","text":"Apply various standardisations to a lattice and a list of atoms. It uses spglib to detect symmetries (within tol_symmetry), then cleans up the lattice according to the symmetries (unless correct_symmetry is false) and returns the resulting standard lattice and atoms. If primitive is true (default) the primitive unit cell is returned, else the conventional unit cell is returned.\n\n\n\n\n\n","category":"function"},{"location":"api/#DFTK.unit_to_au-Tuple{Symbol}","page":"API reference","title":"DFTK.unit_to_au","text":"unit_to_ao(symbol)\n\nGet the factor converting from the unit symbol to atomic units. E.g. unit_to_au(:eV) returns the conversion factor from electron volts to Hartree.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.DFTK_DATADIR","page":"API reference","title":"DFTK.DFTK_DATADIR","text":"The default search location for Pseudopotential data files\n\n\n\n\n\n","category":"constant"},{"location":"api/#DFTK.DensityDerivatives-Tuple{Any,Integer,Any}","page":"API reference","title":"DFTK.DensityDerivatives","text":"DOCME compute density in real space and its derivatives starting from Fourier-space density ρ\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.FourierMultiplication","page":"API reference","title":"DFTK.FourierMultiplication","text":"Fourier space multiplication, like a kinetic energy term: (Hψ)(G) = multiplier(G) ψ(G)\n\n\n\n\n\n","category":"type"},{"location":"api/#DFTK.MagneticFieldOperator","page":"API reference","title":"DFTK.MagneticFieldOperator","text":"Magnetic field operator A⋅(-i∇).\n\n\n\n\n\n","category":"type"},{"location":"api/#DFTK.NonlocalOperator","page":"API reference","title":"DFTK.NonlocalOperator","text":"Nonlocal operator in Fourier space in Kleinman-Bylander format, defined by its projectors P matrix and coupling terms D: Hψ = PDP' ψ\n\n\n\n\n\n","category":"type"},{"location":"api/#DFTK.NoopOperator","page":"API reference","title":"DFTK.NoopOperator","text":"Noop operation: don't do anything. Useful for energy terms that don't depend on the orbitals at all (eg nuclei-nuclei interaction).\n\n\n\n\n\n","category":"type"},{"location":"api/#DFTK.NoopTerm","page":"API reference","title":"DFTK.NoopTerm","text":"A term with a constant zero energy.\n\n\n\n\n\n","category":"type"},{"location":"api/#DFTK.RealFourierOperator","page":"API reference","title":"DFTK.RealFourierOperator","text":"Linear operators that act on tuples (real, fourier) The main entry point is apply!(out, op, in) which performs the operation out += op*in where out and in are named tuples (real, fourier) They also implement mul! and Matrix(op) for exploratory use.\n\n\n\n\n\n","category":"type"},{"location":"api/#DFTK.RealSpaceMultiplication","page":"API reference","title":"DFTK.RealSpaceMultiplication","text":"Real space multiplication by a potential: (Hψ)(r) V(r) ψ(r)\n\n\n\n\n\n","category":"type"},{"location":"api/#DFTK.CROP","page":"API reference","title":"DFTK.CROP","text":"CROP-accelerated root-finding iteration for f, starting from x0 and keeping a history of m steps. Optionally warming specifies the number of non-accelerated steps to perform for warming up the history.\n\n\n\n\n\n","category":"function"},{"location":"api/#DFTK.ScfConvergenceDensity-Tuple{Any}","page":"API reference","title":"DFTK.ScfConvergenceDensity","text":"Flag convergence by using the L2Norm of the change between input density and unpreconditioned output density (ρout)\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.ScfConvergenceEnergy-Tuple{Any}","page":"API reference","title":"DFTK.ScfConvergenceEnergy","text":"Flag convergence as soon as total energy change drops below tolerance\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.ScfDiagtol-Tuple{}","page":"API reference","title":"DFTK.ScfDiagtol","text":"Determine the tolerance used for the next diagonalization. This function takes ρnext - ρin and multiplies it with ratio_ρdiff to get the next diagtol, ensuring additionally that the returned value is between diagtol_min and diagtol_max and never increases.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.anderson","page":"API reference","title":"DFTK.anderson","text":"Anderson-accelerated root-finding iteration for finding a root of f, starting from x0 and keeping a history of m steps. Optionally warming specifies the number of non-accelerated steps to perform for warming up the history.\n\n\n\n\n\n","category":"function"},{"location":"api/#DFTK.apply_ksymop-Tuple{Any,Any,Any,Union{AbstractArray{T,1}, AbstractArray{T,2}} where T}","page":"API reference","title":"DFTK.apply_ksymop","text":"Apply a symmetry operation to eigenvectors ψk at a given kpoint to obtain an equivalent point in [-0.5, 0.5)^3 and associated eigenvectors (expressed in the basis of the new kpoint).\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.apply_ksymop-Tuple{Any,RealFourierArray}","page":"API reference","title":"DFTK.apply_ksymop","text":"Apply a k-point symmetry operation (the tuple (S, τ)) to a partial density.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.atom_decay_length-Tuple{Any,Any}","page":"API reference","title":"DFTK.atom_decay_length","text":"Get the lengthscale of the valence density for an atom with n_elec_core core and n_elec_valence valence electrons. ```\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.build_fft_plans-Tuple{Type{Float32},Any}","page":"API reference","title":"DFTK.build_fft_plans","text":"Plan a FFT of type T and size fft_size, spending some time on finding an optimal algorithm. Both an inplace and an out-of-place FFT plan are returned.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.build_form_factors-Tuple{Any,Any}","page":"API reference","title":"DFTK.build_form_factors","text":"Build form factors (Fourier transforms of projectors) for an atom centered at 0.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.build_projection_vectors_-Tuple{PlaneWaveBasis,Any,Kpoint}","page":"API reference","title":"DFTK.build_projection_vectors_","text":"Build projection vectors for a atoms array generated by term_nonlocal\n\nHat = sumij Cij |pi> <pj| Hper = sumR sumij Cij |pi(x-R)> <pj(x-R)| = sumR sum_ij Cij |pi(x-R)> <pj(x-R)|\n\n<ekG'|Hper|ekG> = ... = 1/Ω sumij Cij pihat(k+G') pjhat(k+G)^*\n\nwhere pihat(q) = ∫_R^3 pi(r) e^{-iqr} dr\n\nWe store 1/√Ω pihat(k+G) in proj_vectors.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.compute_partial_density-NTuple{4,Any}","page":"API reference","title":"DFTK.compute_partial_density","text":"Compute the partial density at the indicated k-Point and return it (in Fourier space).\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.datadir_psp-Tuple{}","page":"API reference","title":"DFTK.datadir_psp","text":"Return the data directory with pseudopotential files\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.eval_psp_energy_correction-Tuple{Any,PspHgh,Any}","page":"API reference","title":"DFTK.eval_psp_energy_correction","text":"eval_psp_energy_correction([T=Float64,] psp, n_electrons)\n\nEvaluate the energy correction to the Ewald electrostatic interaction energy of one unit cell, which is required compared the Ewald expression for point-like nuclei. n_electrons is the number of electrons per unit cell. This defines the uniform compensating background charge, which is assumed here.\n\nNotice: The returned result is the energy per unit cell and not the energy per volume. To obtain the latter, the caller needs to divide by the unit cell volume.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.eval_psp_projection_radial_real-Union{Tuple{T}, Tuple{PspHgh,Any,Any,T}} where T<:Real","page":"API reference","title":"DFTK.eval_psp_projection_radial_real","text":"eval_psp_projection_radial_real(psp::PspHgh, i, l, q::Real)\n\nEvaluate the radial part of the i-th projector for angular momentum l in real-space at the vector with modulus r. HGH98\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.filled_occupation-Tuple{Any}","page":"API reference","title":"DFTK.filled_occupation","text":"Maximal occupation of a state (2 for non-spin-polarized electrons, 1 otherwise).\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.find_irreducible_kpoints-Tuple{Any,Any,Any}","page":"API reference","title":"DFTK.find_irreducible_kpoints","text":"Implements a primitive search to find an irreducible subset of kpoints amongst the provided kpoints.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.index_G_vectors-Union{Tuple{T}, Tuple{PlaneWaveBasis,AbstractArray{T,1}}} where T<:Integer","page":"API reference","title":"DFTK.index_G_vectors","text":"Return the index tuple I such that G_vectors(basis)[I] == G or the index i such that G_vectors(kpoint)[i] == G. Returns nothing if outside the range of valid wave vectors.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.interpolate_blochwave-Tuple{Any,Any,Any}","page":"API reference","title":"DFTK.interpolate_blochwave","text":"Interpolate Bloch wave between two basis sets. Limited feature set. Currently only interpolation to a bigger grid (larger Ecut) on the same lattice supported.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.interpolate_density-Tuple{RealFourierArray,PlaneWaveBasis}","page":"API reference","title":"DFTK.interpolate_density","text":"Interpolate a function expressed in a basis b_in to a basis b_out This interpolation uses a very basic real-space algorithm, and makes a DWIM-y attempt to take into account the fact that bout can be a supercell of bin\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.interpolate_kpoint-Tuple{Union{AbstractArray{T,1}, AbstractArray{T,2}} where T,Kpoint,Kpoint}","page":"API reference","title":"DFTK.interpolate_kpoint","text":"Interpolate some data from one k-Point to another. The interpolation is fast, but not necessarily exact or even normalized. Intended only to construct guesses for iterative solvers\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.is_metal","page":"API reference","title":"DFTK.is_metal","text":"is_metal(band_data, εF, tol)\n\nDetermine whether the provided bands indicate the material is a metal, i.e. where bands are cut by the Fermi level.\n\n\n\n\n\n","category":"function"},{"location":"api/#DFTK.kgrid_monkhorst_pack-Tuple{Any}","page":"API reference","title":"DFTK.kgrid_monkhorst_pack","text":"Construct the coordinates of the kpoints in a (shifted) Monkorst-Pack grid\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.lda_c_vwn!-Tuple{Any}","page":"API reference","title":"DFTK.lda_c_vwn!","text":"LDA correlation according to Vosko Wilk,and Nusair, (DOI 10.1139/p80-159)\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.lda_x!-Tuple{Any}","page":"API reference","title":"DFTK.lda_x!","text":"LDA Slater exchange (DOI: 10.1017/S0305004100016108 and 10.1007/BF01340281)\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.load_atoms_pymatgen-Tuple{Any,PyCall.PyObject}","page":"API reference","title":"DFTK.load_atoms_pymatgen","text":"Load a DFTK-compatible atoms representation from a supported pymatgen object. All atoms are using a Coulomb model.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.local_potential_fourier-Union{Tuple{T}, Tuple{ElementCoulomb,T}} where T<:Real","page":"API reference","title":"DFTK.local_potential_fourier","text":"Radial local potential, in Fourier space: V(q) = int_{R^3} V(x) e^{-iqx} dx.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.local_potential_real-Tuple{ElementCoulomb,Real}","page":"API reference","title":"DFTK.local_potential_real","text":"Radial local potential, in real space.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.next_density-Tuple{Hamiltonian}","page":"API reference","title":"DFTK.next_density","text":"Obtain new density ρ by diagonalizing ham.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.normalize_kpoint_coordinate-Tuple{Real}","page":"API reference","title":"DFTK.normalize_kpoint_coordinate","text":"Bring kpoint coordinates into the range [-0.5, 0.5)\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.parse_hgh_file-Tuple{Any}","page":"API reference","title":"DFTK.parse_hgh_file","text":"parse_hgh_file(path; identifier=\"\")\n\nParse an HGH pseudopotential file and construct the PspHgh object. If identifier is given, this identifier will be set.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.psp_local_polynomial","page":"API reference","title":"DFTK.psp_local_polynomial","text":"The local potential of a HGH pseudopotentials in reciprocal space can be brought to the form Q(t) (t^2 exp(t^2 2)) where t = r_textloc q and Q is a polynomial of at most degree 8. This function returns Q.\n\n\n\n\n\n","category":"function"},{"location":"api/#DFTK.psp_projection_radial_polynomial","page":"API reference","title":"DFTK.psp_projection_radial_polynomial","text":"The nonlocal projectors of a HGH pseudopotentials in reciprocal space can be brought to the form Q(t) exp(-t^2 2) where t = r_l q and Q is a polynomial. This function returns Q.\n\n\n\n\n\n","category":"function"},{"location":"api/#DFTK.qcut_psp_local-Tuple{Any,PspHgh}","page":"API reference","title":"DFTK.qcut_psp_local","text":"Estimate an upper bound for the argument q after which abs(eval_psp_local_fourier(psp, q)) is a strictly decreasing function.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.qcut_psp_projection_radial-Tuple{Any,PspHgh,Any,Any}","page":"API reference","title":"DFTK.qcut_psp_projection_radial","text":"Estimate an upper bound for the argument q after which eval_psp_projection_radial(psp, q) is a strictly decreasing function.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.run_abinit_scf-Tuple{Model,Any}","page":"API reference","title":"DFTK.run_abinit_scf","text":"Run an SCF in ABINIT starting from a DFTK Model and some extra parameters. Write the result to the output directory in ETSF Nanoquanta format and return the EtsfFolder object.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.run_abinit_scf-Tuple{PyCall.PyObject,Any}","page":"API reference","title":"DFTK.run_abinit_scf","text":"Run an SCF in ABINIT starting from the input file infile represented as a abipy.abilab.AbinitInput python object. Write the result to the output directory in ETSF Nanoquanta format and return the result as an EtsfFolder object.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.select_eigenpairs_all_kblocks-Tuple{Any,Any}","page":"API reference","title":"DFTK.select_eigenpairs_all_kblocks","text":"Function to select a subset of eigenpairs on each k-Point. Works on the Tuple returned by diagonalize_all_kblocks.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.spglib_cell_atommapping_-Tuple{Any,Any}","page":"API reference","title":"DFTK.spglib_cell_atommapping_","text":"Construct a tuple containing the lattice and the positions of the species in the convention required to take the place of a cell datastructure used in spglib.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.symmetrize","page":"API reference","title":"DFTK.symmetrize","text":"Symmetrize a RealFourierArray by applying all symmetry operations of the basis (or all symmetries passed as the second argument) and forming the average.\n\n\n\n\n\n","category":"function"},{"location":"api/#DFTK.symmetry_operations-Tuple{Any,Any}","page":"API reference","title":"DFTK.symmetry_operations","text":"Return the k-point symmetry operations associated to a lattice, model or basis. Since the k-point discretisations may break some of the symmetries, the latter case will return a subset of the symmetries of the former two.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.total_local_potential-Tuple{Hamiltonian}","page":"API reference","title":"DFTK.total_local_potential","text":"Get the total local potential of the given Hamiltonian, in real space.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.ylm_real-Union{Tuple{T}, Tuple{Integer,Integer,AbstractArray{T,1}}} where T","page":"API reference","title":"DFTK.ylm_real","text":"Returns the (l,m) real spherical harmonic Ylm(r). Consistent with https://en.wikipedia.org/wiki/Tableofsphericalharmonics#Realsphericalharmonics\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.Smearing.entropy-Tuple{DFTK.Smearing.SmearingFunction,Any}","page":"API reference","title":"DFTK.Smearing.entropy","text":"Entropy. Note that this is a function of the energy x, not of occupation(x). This function satisfies s' = x f' (see https://www.vasp.at/vasp-workshop/k-points.pdf p. 12 and https://arxiv.org/pdf/1805.07144.pdf p. 18.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.Smearing.occupation-Tuple{DFTK.Smearing.SmearingFunction,Any}","page":"API reference","title":"DFTK.Smearing.occupation","text":"Occupation at x, where in practice x = (ε - εF) / T.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.Smearing.occupation_derivative-Tuple{DFTK.Smearing.SmearingFunction,Any}","page":"API reference","title":"DFTK.Smearing.occupation_derivative","text":"Derivative of the occupation function, approximation to minus the delta function.\n\n\n\n\n\n","category":"method"},{"location":"api/#DFTK.Smearing.occupation_divided_difference-Tuple{DFTK.Smearing.SmearingFunction,Any,Any,Any,Any}","page":"API reference","title":"DFTK.Smearing.occupation_divided_difference","text":"(f(x) - f(y))/(x - y), computed stably in the case where x and y are close\n\n\n\n\n\n","category":"method"},{"location":"advanced/conventions/#Notation-and-conventions-1","page":"Notation and conventions","title":"Notation and conventions","text":"","category":"section"},{"location":"advanced/conventions/#Usage-of-unicode-characters-1","page":"Notation and conventions","title":"Usage of unicode characters","text":"","category":"section"},{"location":"advanced/conventions/#","page":"Notation and conventions","title":"Notation and conventions","text":"DFTK liberally uses unicode characters to represent Greek characters (e.g. ψ, ρ, ε...). Make sure you use the proper Julia plugins to simplify typing them.","category":"page"},{"location":"advanced/conventions/#symbol-conventions-1","page":"Notation and conventions","title":"Symbol conventions","text":"","category":"section"},{"location":"advanced/conventions/#","page":"Notation and conventions","title":"Notation and conventions","text":"Reciprocal-space vectors: k for vectors in the Brillouin zone, G for vectors of the reciprocal lattice, q for general vectors\nReal-space vectors: R for lattice vectors, r and x are usually used for unit for vectors in the unit cell or general real-space vectors, respectively. This convention is, however, less consistently applied.\nOmega is the unit cell, and Omega (or sometimes just Omega) is its volume.\nA are the real-space lattice vectors (model.lattice) and B the Brillouin zone lattice vectors (model.recip_lattice).\nThe Bloch waves are\npsi_nk(x) = e^ikcdot x u_nk(x)\nwhere n is the band index and k the k-point. In the code we sometimes use psi and u interchangeably.\nvarepsilon are the eigenvalues, varepsilon_F is the Fermi level.\nrho is the density.\nIn the code we use normalized plane waves:\ne_G(r) = frac 1 sqrtOmega e^i G cdot r\nY^l_m are the complex spherical harmonics, and Y_lm the real ones.\nj_l are the Bessel functions. In particular, j_0(x) = fracsin xx.","category":"page"},{"location":"advanced/conventions/#Units-1","page":"Notation and conventions","title":"Units","text":"","category":"section"},{"location":"advanced/conventions/#","page":"Notation and conventions","title":"Notation and conventions","text":"In DFTK, atomic units are used throughout, most importantly lengths are in Bohr and energies in Hartree. See wikipedia for a list of conversion factors. Useful conversion factors can also be found in DFTK.units and using DFTK.unit_to_au:","category":"page"},{"location":"advanced/conventions/#","page":"Notation and conventions","title":"Notation and conventions","text":"import DFTK.units: eV, Å\n10eV # 10eV in Hartree\n#-\n1.2 / Å # 1.2 Bohr in Ångström","category":"page"},{"location":"advanced/conventions/#","page":"Notation and conventions","title":"Notation and conventions","text":"warning: Differing unit conventions\nDifferent electronic-structure codes use different unit conventions. For example for lattice vectors the common length units are Bohr (used by DFTK) and Ångström (used e.g. by ASE, 1Å ≈ 1.80 Bohr). When setting up a calculation for DFTK one needs to ensure to convert to Bohr and atomic units. For some Python libraries (currently ASE, pymatgen and abipy) DFTK directly ships conversion tools in form of the load_lattice and load_atoms functions, which take care of such conversions. Examples which demonstrate this are Creating slabs with ASE and Creating supercells with pymatgen.","category":"page"},{"location":"advanced/conventions/#conventions-lattice-1","page":"Notation and conventions","title":"Lattices and lattice vectors","text":"","category":"section"},{"location":"advanced/conventions/#","page":"Notation and conventions","title":"Notation and conventions","text":"Both the real-space lattice (i.e. model.lattice) and reciprocal-space lattice (model.recip_lattice) contain the lattice vectors in columns. If 1D or 2D problems are to be treated these arrays are still 3 times 3 matrices, but contain two or one zero-columns, respectively. The real-space lattice vectors are sometimes referred to by A and the reciprocal-space lattice vectors by B = 2pi A^-T.","category":"page"},{"location":"advanced/conventions/#","page":"Notation and conventions","title":"Notation and conventions","text":"warning: Row-major versus column-major storage order\nJulia stores matrices as column-major, but other languages (notably Python and C) use row-major ordering. Care therefore needs to be taken to properly transpose the unit cell matrices A before using it with DFTK. For the supported third-party packages load_lattice and load_atoms again handle such conversion automatically.","category":"page"},{"location":"advanced/conventions/#","page":"Notation and conventions","title":"Notation and conventions","text":"We use the convention that the unit cell in real space is 0 1)^3 in reduced coordinates and the unit cell in reciprocal space (the reducible Brillouin zone) is -12 12)^3.","category":"page"},{"location":"advanced/conventions/#Reduced-and-cartesian-coordinates-1","page":"Notation and conventions","title":"Reduced and cartesian coordinates","text":"","category":"section"},{"location":"advanced/conventions/#","page":"Notation and conventions","title":"Notation and conventions","text":"Unless denoted otherwise the code uses reduced coordinates for reciprocal-space vectors such as k, G, q or real-space vectors like r and R (see Symbol conventions). One switches to Cartesian coordinates by","category":"page"},{"location":"advanced/conventions/#","page":"Notation and conventions","title":"Notation and conventions","text":"x_textcart = M x_textred","category":"page"},{"location":"advanced/conventions/#","page":"Notation and conventions","title":"Notation and conventions","text":"where M is either A / model.lattice (for real-space vectors) or B / model.recip_lattice (for reciprocal-space vectors). A useful relationship is","category":"page"},{"location":"advanced/conventions/#","page":"Notation and conventions","title":"Notation and conventions","text":"b_textcart cdot a_textcart=2pi b_textred cdot a_textred","category":"page"},{"location":"advanced/conventions/#","page":"Notation and conventions","title":"Notation and conventions","text":"if a and b are real-space and reciprocal-space vectors respectively. Other names for reduced coordinates are integer coordinates (usually for G-vectors) or fractional coordinates (usually for k-points).","category":"page"},{"location":"advanced/conventions/#Normalization-conventions-1","page":"Notation and conventions","title":"Normalization conventions","text":"","category":"section"},{"location":"advanced/conventions/#","page":"Notation and conventions","title":"Notation and conventions","text":"The normalization conventions used in the code is that quantities stored in reciprocal space are coefficients in the e_G basis, and quantities stored in real space use real physical values. This means for instance that wavefunctions in the real space grid are normalized as fracOmegaN sum_r psi(r)^2 = 1 where N is the number of grid points and in reciprocal space its coefficients are ell^2-normalized, see the discussion in section PlaneWaveBasis and plane-wave discretisations where this is demonstrated.","category":"page"},{"location":"advanced/symmetries/#Crystal-symmetries-1","page":"Crystal symmetries","title":"Crystal symmetries","text":"","category":"section"},{"location":"advanced/symmetries/#Theory-1","page":"Crystal symmetries","title":"Theory","text":"","category":"section"},{"location":"advanced/symmetries/#","page":"Crystal symmetries","title":"Crystal symmetries","text":"In this discussion we will only describe the situation for a monoatomic crystal mathcal C subset mathbb R^3, the extension being easy. A symmetry of the crystal is a real-space unitary matrix widetildeS and a real-space vector widetildetau such that","category":"page"},{"location":"advanced/symmetries/#","page":"Crystal symmetries","title":"Crystal symmetries","text":"widetildeS mathcalC + widetildetau = mathcalC","category":"page"},{"location":"advanced/symmetries/#","page":"Crystal symmetries","title":"Crystal symmetries","text":"The symmetries where widetildeS = 1 and widetildetau is a lattice vector are always assumed and ignored in the following.","category":"page"},{"location":"advanced/symmetries/#","page":"Crystal symmetries","title":"Crystal symmetries","text":"We can define a corresponding unitary operator U on L^2(mathbb R^3) with action","category":"page"},{"location":"advanced/symmetries/#","page":"Crystal symmetries","title":"Crystal symmetries","text":" (Uu)(x) = uleft( widetildeS x + widetildetau right)","category":"page"},{"location":"advanced/symmetries/#","page":"Crystal symmetries","title":"Crystal symmetries","text":"We assume that the atomic potentials are radial and that any self-consistent potential also respects this symmetry, so that U commutes with the Hamiltonian.","category":"page"},{"location":"advanced/symmetries/#","page":"Crystal symmetries","title":"Crystal symmetries","text":"This operator acts on a plane-wave as","category":"page"},{"location":"advanced/symmetries/#","page":"Crystal symmetries","title":"Crystal symmetries","text":"beginaligned\n(U e^iqcdot x) (x) = e^iq cdot widetildetau e^i (widetildeS^T q) x\n= e^- i(S q) cdot tau e^i (S q) cdot x\nendaligned","category":"page"},{"location":"advanced/symmetries/#","page":"Crystal symmetries","title":"Crystal symmetries","text":"where we set","category":"page"},{"location":"advanced/symmetries/#","page":"Crystal symmetries","title":"Crystal symmetries","text":"beginaligned\nS = widetildeS^T\ntau = -widetildeS^-1widetildetau\nendaligned","category":"page"},{"location":"advanced/symmetries/#","page":"Crystal symmetries","title":"Crystal symmetries","text":"(these equations being also valid in reduced coordinates).","category":"page"},{"location":"advanced/symmetries/#","page":"Crystal symmetries","title":"Crystal symmetries","text":"It follows that the Fourier transform satisfies","category":"page"},{"location":"advanced/symmetries/#","page":"Crystal symmetries","title":"Crystal symmetries","text":"widehatUu(q) = e^- iq cdot tau widehat u(S^-1 q)","category":"page"},{"location":"advanced/symmetries/#","page":"Crystal symmetries","title":"Crystal symmetries","text":"In particular, if e^ikcdot x u_k(x) is an eigenfunction, then by decomposing u_k over plane-waves e^i G cdot x one can see that e^i(S^T k) cdot x (U u_k)(x) is also an eigenfunction: we can choose","category":"page"},{"location":"advanced/symmetries/#","page":"Crystal symmetries","title":"Crystal symmetries","text":"u_Sk = U u_k","category":"page"},{"location":"advanced/symmetries/#","page":"Crystal symmetries","title":"Crystal symmetries","text":"This is used to reduce the computations needed. For a uniform sampling of the Brillouin zone (the reducible k-points), one can find a reduced set of k-points (the irreducible k-points) such that the eigenvectors at the reducible k-points can be deduced from those at the irreducible k-points.","category":"page"},{"location":"advanced/symmetries/#Example-1","page":"Crystal symmetries","title":"Example","text":"","category":"section"},{"location":"advanced/symmetries/#","page":"Crystal symmetries","title":"Crystal symmetries","text":"using DFTK\na = 10.26\nlattice = a / 2 * [[0 1 1.];\n [1 0 1.];\n [1 1 0.]]\nSi = ElementPsp(:Si, psp=load_psp(\"hgh/lda/Si-q4\"))\natoms = [Si => [ones(3)/8, -ones(3)/8]]\nEcut = 5\nkgrid = [4, 4, 4]","category":"page"},{"location":"advanced/symmetries/#","page":"Crystal symmetries","title":"Crystal symmetries","text":"Let us demonstrate this in practice. We consider silicon, setup appropriately in the lattice and atoms objects as in Tutorial and to reach a fast execution, we take a small Ecut of 5 and a [4, 4, 4] Monkhorst-Pack grid. First we perform the DFT calculation disabling symmetry handling","category":"page"},{"location":"advanced/symmetries/#","page":"Crystal symmetries","title":"Crystal symmetries","text":"model = model_LDA(lattice, atoms)\nbasis_nosym = PlaneWaveBasis(model, Ecut; kgrid=kgrid, enable_bzmesh_symmetry=false)\nscfres_nosym = @time self_consistent_field(basis_nosym, tol=1e-8)\nnothing # hide","category":"page"},{"location":"advanced/symmetries/#","page":"Crystal symmetries","title":"Crystal symmetries","text":"and then redo it using symmetry (the default):","category":"page"},{"location":"advanced/symmetries/#","page":"Crystal symmetries","title":"Crystal symmetries","text":"basis_sym = PlaneWaveBasis(model, Ecut; kgrid=kgrid)\nscfres_sym = @time self_consistent_field(basis_sym, tol=1e-8)\nnothing # hide","category":"page"},{"location":"advanced/symmetries/#","page":"Crystal symmetries","title":"Crystal symmetries","text":"Clearly both yield the same energy but the version employing symmetry is faster, since less k-points are explicitly treated:","category":"page"},{"location":"advanced/symmetries/#","page":"Crystal symmetries","title":"Crystal symmetries","text":"(length(basis_sym.kpoints), length(basis_nosym.kpoints))","category":"page"},{"location":"advanced/symmetries/#","page":"Crystal symmetries","title":"Crystal symmetries","text":"Both SCFs would even agree in the convergence history if exact diagonalization was used for the eigensolver in each step of both SCFs. But since DFTK adjusts this diagtol value adaptively during the SCF to increase performance, a slightly different history is obtained. Try adding the keyword argument determine_diagtol=(args...; kwargs...) -> 1e-8 in each SCF call to fix the diagonalization tolerance to be 1e-8 for all SCF steps, which will result in an almost identical convergence history.","category":"page"},{"location":"advanced/symmetries/#","page":"Crystal symmetries","title":"Crystal symmetries","text":"We can also explicitly verify both methods to yield the same density:","category":"page"},{"location":"advanced/symmetries/#","page":"Crystal symmetries","title":"Crystal symmetries","text":"using LinearAlgebra # hide\n(norm(scfres_sym.ρ.real - scfres_nosym.ρ.real),\n norm(values(scfres_sym.energies) .- values(scfres_nosym.energies)))","category":"page"},{"location":"advanced/symmetries/#","page":"Crystal symmetries","title":"Crystal symmetries","text":"To demonstrate the mapping between k-points due to symmetry, we pick an arbitrary k-point in the irreducible Brillouin zone:","category":"page"},{"location":"advanced/symmetries/#","page":"Crystal symmetries","title":"Crystal symmetries","text":"ikpt_irred = 2\nkpt_irred_coord = basis_sym.kpoints[ikpt_irred].coordinate\nbasis_sym.ksymops[ikpt_irred]","category":"page"},{"location":"advanced/symmetries/#","page":"Crystal symmetries","title":"Crystal symmetries","text":"This is a list of all symmetries operations (S tau) that can be used to map this irreducible k-point to reducible k-points. Let's pick the third symmetry operation of this k-point and check.","category":"page"},{"location":"advanced/symmetries/#","page":"Crystal symmetries","title":"Crystal symmetries","text":"S, τ = basis_sym.ksymops[ikpt_irred][3]\nkpt_red_coord = S * basis_sym.kpoints[ikpt_irred].coordinate\nikpt_red = findfirst(kcoord -> kcoord ≈ kpt_red_coord,\n [k.coordinate for k in basis_nosym.kpoints])\n[scfres_sym.eigenvalues[ikpt_irred] scfres_nosym.eigenvalues[ikpt_red]]","category":"page"},{"location":"examples/ase/#","page":"Creating slabs with ASE","title":"Creating slabs with ASE","text":"EditURL = \"https://github.com/JuliaMolSim/DFTK.jl/blob/master/examples/ase.jl\"","category":"page"},{"location":"examples/ase/#Creating-slabs-with-ASE-1","page":"Creating slabs with ASE","title":"Creating slabs with ASE","text":"","category":"section"},{"location":"examples/ase/#","page":"Creating slabs with ASE","title":"Creating slabs with ASE","text":"(Image: ) (Image: )","category":"page"},{"location":"examples/ase/#","page":"Creating slabs with ASE","title":"Creating slabs with ASE","text":"ASE is short for the atomistic simulation environment, a Python package to simplify the process of setting up, running and analysing results from atomistic simulations across different programs. Extremely powerful in this respect are the routines this code provides for setting up complicated systems (including surface-adsorption scenarios, defects, nanotubes, etc). See also the ASE installation instructions.","category":"page"},{"location":"examples/ase/#","page":"Creating slabs with ASE","title":"Creating slabs with ASE","text":"This example shows how to use ASE to setup a particular gallium arsenide surface and run the resulting calculation in DFTK. If you are less interested in having access to the full playground of options in DFTK, but more interested in performing analysis in ASE itself, have a look at asedftk. This package provides an ASE-compatible calculator class based on DFTK, such that one may write the usual Python scripts against ASE, but the calculations are still run in DFTK.","category":"page"},{"location":"examples/ase/#","page":"Creating slabs with ASE","title":"Creating slabs with ASE","text":"The particular example we consider the (1, 1, 0) GaAs surface separated by vacuum with the setup slightly adapted from [RCW2001].","category":"page"},{"location":"examples/ase/#","page":"Creating slabs with ASE","title":"Creating slabs with ASE","text":"[RCW2001]: D. Raczkowski, A. Canning, and L. W. Wang Thomas-Fermi charge mixing for obtaining self-consistency in density functional calculations Phys. Rev. B 64, 121101(R).","category":"page"},{"location":"examples/ase/#","page":"Creating slabs with ASE","title":"Creating slabs with ASE","text":"Parameters of the calculation. Since this surface is far from easy to converge, we made the problem simpler by choosing a smaller Ecut and smaller values for n_GaAs and n_vacuum. More interesting settings are Ecut = 15 and n_GaAs = n_vacuum = 20.","category":"page"},{"location":"examples/ase/#","page":"Creating slabs with ASE","title":"Creating slabs with ASE","text":"miller = (1, 1, 0) # Surface Miller indices\nn_GaAs = 2 # Number of GaAs layers\nn_vacuum = 4 # Number of vacuum layers\nEcut = 5 # Hartree\nkgrid = (4, 4, 1); # Monkhorst-Pack mesh\nnothing #hide","category":"page"},{"location":"examples/ase/#","page":"Creating slabs with ASE","title":"Creating slabs with ASE","text":"Use ASE to build the structure:","category":"page"},{"location":"examples/ase/#","page":"Creating slabs with ASE","title":"Creating slabs with ASE","text":"using PyCall\n\nase_build = pyimport(\"ase.build\")\na = 5.6537 # GaAs lattice parameter in Ǎngström (because ASE uses Ǎ as length unit)\ngaas = ase_build.bulk(\"GaAs\", \"zincblende\", a=a)\nsurface = ase_build.surface(gaas, miller, n_GaAs, 0, periodic=true);\n\n# Get the amount of vacuum in Ångström we need to add\nd_vacuum = maximum(maximum, surface.cell) / n_GaAs * n_vacuum\nsurface = ase_build.surface(gaas, miller, n_GaAs, d_vacuum, periodic=true);\nnothing #hide","category":"page"},{"location":"examples/ase/#","page":"Creating slabs with ASE","title":"Creating slabs with ASE","text":"Use the load_atoms and load_lattice functions to convert to DFTK datastructures. These two functions not only support importing ASE atoms into DFTK, but a few more third-party datastructures as well. Typically the imported atoms use a bare Coulomb potential, such that appropriate pseudopotentials need to be attached in a post-step:","category":"page"},{"location":"examples/ase/#","page":"Creating slabs with ASE","title":"Creating slabs with ASE","text":"using DFTK\n\natoms = load_atoms(surface)\natoms = [ElementPsp(el.symbol, psp=load_psp(el.symbol, functional=\"pbe\")) => position\n for (el, position) in atoms]\nlattice = load_lattice(surface);\nnothing #hide","category":"page"},{"location":"examples/ase/#","page":"Creating slabs with ASE","title":"Creating slabs with ASE","text":"We model this surface with (quite large a) temperature of 0.01 Hartree to ease convergence. Try lowering the SCF convergence tolerance (tol or the temperature to see the full challenge of this system.","category":"page"},{"location":"examples/ase/#","page":"Creating slabs with ASE","title":"Creating slabs with ASE","text":"model = model_DFT(lattice, atoms, [:gga_x_pbe, :gga_c_pbe],\n temperature=0.001, smearing=DFTK.Smearing.Gaussian())\nbasis = PlaneWaveBasis(model, Ecut; kgrid=kgrid)\n\nscfres = self_consistent_field(basis, tol=1e-4, mixing=KerkerMixing());\nnothing #hide","category":"page"},{"location":"examples/ase/#","page":"Creating slabs with ASE","title":"Creating slabs with ASE","text":"scfres.energies","category":"page"},{"location":"guide/tutorial/#","page":"Tutorial","title":"Tutorial","text":"EditURL = \"https://github.com/JuliaMolSim/DFTK.jl/blob/master/docs/src/guide/tutorial.jl\"","category":"page"},{"location":"guide/tutorial/#Tutorial-1","page":"Tutorial","title":"Tutorial","text":"","category":"section"},{"location":"guide/tutorial/#","page":"Tutorial","title":"Tutorial","text":"(Image: ) (Image: )","category":"page"},{"location":"guide/tutorial/#","page":"Tutorial","title":"Tutorial","text":"This document provides an overview of the structure of the code and how to access basic information about calculations. Basic familiarity with the concepts of plane-wave density functional theory is assumed throughout.","category":"page"},{"location":"guide/tutorial/#","page":"Tutorial","title":"Tutorial","text":"note: Convergence parameters in the documentation\nWe use rough parameters in order to be able to automatically generate this documentation very quickly. Therefore results are far from converged. Tighter thresholds and larger grids should be used for more realistic results.","category":"page"},{"location":"guide/tutorial/#","page":"Tutorial","title":"Tutorial","text":"For our discussion we will use the classic example of computing the LDA ground state of the silicon crystal. Performing such a calculation roughly proceeds in three steps.","category":"page"},{"location":"guide/tutorial/#","page":"Tutorial","title":"Tutorial","text":"using DFTK\nusing Plots\n\n# 1. Define lattice and atomic positions\na = 10.26 # Silicon lattice constant in Bohr\nlattice = a / 2 * [[0 1 1.];\n [1 0 1.];\n [1 1 0.]]\n\n# Load HGH pseudopotential for Silicon\nSi = ElementPsp(:Si, psp=load_psp(\"hgh/lda/Si-q4\"))\n\n# Specify type and positions of atoms\natoms = [Si => [ones(3)/8, -ones(3)/8]]\n\n# 2. Select model and basis\nmodel = model_LDA(lattice, atoms)\nkgrid = [4, 4, 4] # k-point grid (Regular Monkhorst-Pack grid)\nEcut = 7 # kinetic energy cutoff in Hartree\nbasis = PlaneWaveBasis(model, Ecut; kgrid=kgrid)\n\n# 3. Run the SCF procedure to obtain the ground state\nscfres = self_consistent_field(basis, tol=1e-8);\nnothing #hide","category":"page"},{"location":"guide/tutorial/#","page":"Tutorial","title":"Tutorial","text":"Note that DFTK by default applies the convergence tolerance tol to the energy difference, so that the norm in the density difference is not yet converged to 8 digits.","category":"page"},{"location":"guide/tutorial/#","page":"Tutorial","title":"Tutorial","text":"That's it! Now you can get various quantities from the result of the SCF. For instance, the energies:","category":"page"},{"location":"guide/tutorial/#","page":"Tutorial","title":"Tutorial","text":"scfres.energies","category":"page"},{"location":"guide/tutorial/#","page":"Tutorial","title":"Tutorial","text":"Eigenvalues: here scfres.eigenvalues returns a 7x8 Array where 7 is the number of eigenvalues that are computed and 8 the number of kpoints.","category":"page"},{"location":"guide/tutorial/#","page":"Tutorial","title":"Tutorial","text":"hcat(scfres.eigenvalues...)","category":"page"},{"location":"guide/tutorial/#","page":"Tutorial","title":"Tutorial","text":"Use scfres.occupation to see the number of electrons on each energy level.","category":"page"},{"location":"guide/tutorial/#","page":"Tutorial","title":"Tutorial","text":"hcat(scfres.occupation...)","category":"page"},{"location":"guide/tutorial/#","page":"Tutorial","title":"Tutorial","text":"And density:","category":"page"},{"location":"guide/tutorial/#","page":"Tutorial","title":"Tutorial","text":"rvecs = collect(r_vectors(basis))[:, 1, 1] # slice along the x axis\nx = [r[1] for r in rvecs] # only keep the x coordinate\nplot(x, scfres.ρ.real[:, 1, 1], label=\"\", xlabel=\"x\", ylabel=\"ρ\", marker=2)","category":"page"},{"location":"guide/tutorial/#","page":"Tutorial","title":"Tutorial","text":"We can also perform various postprocessing steps: for instance compute a band structure","category":"page"},{"location":"guide/tutorial/#","page":"Tutorial","title":"Tutorial","text":"n_bands = 8\nplot_bandstructure(scfres, n_bands, kline_density=5, unit=:eV)","category":"page"},{"location":"guide/tutorial/#","page":"Tutorial","title":"Tutorial","text":"or forces","category":"page"},{"location":"guide/tutorial/#","page":"Tutorial","title":"Tutorial","text":"forces(scfres)[1] # Select silicon forces","category":"page"},{"location":"guide/tutorial/#","page":"Tutorial","title":"Tutorial","text":"The [1] extracts the forces for the first kind of atoms, i.e. Si (silicon) in the setup of the atoms list of step 1 above. As expected, they are almost zero in this highly symmetric configuration.","category":"page"},{"location":"guide/tutorial/#Where-to-go-from-here-1","page":"Tutorial","title":"Where to go from here","text":"","category":"section"},{"location":"guide/tutorial/#","page":"Tutorial","title":"Tutorial","text":"Take a look at the example index to continue exploring DFTK.","category":"page"},{"location":"advanced/data_structures/#Data-structures-1","page":"Data structures","title":"Data structures","text":"","category":"section"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"using DFTK\na = 10.26 # Silicon lattice constant in Bohr\nlattice = a / 2 * [[0 1 1.];\n [1 0 1.];\n [1 1 0.]]\nSi = ElementPsp(:Si, psp=load_psp(\"hgh/lda/Si-q4\"))\natoms = [Si => [ones(3)/8, -ones(3)/8]]\n\nmodel = model_LDA(lattice, atoms)\nkgrid = [4, 4, 4]\nEcut = 15\nbasis = PlaneWaveBasis(model, Ecut; kgrid=kgrid)\nscfres = self_consistent_field(basis, tol=1e-8);","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"In this section we assume a calculation of silicon LDA model in the setup described in Tutorial.","category":"page"},{"location":"advanced/data_structures/#Model-datastructure-1","page":"Data structures","title":"Model datastructure","text":"","category":"section"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"The physical model to be solved is defined by the Model datastructure. It contains the unit cell, number of electrons, atoms, type of spin polarization and temperature. Each atom has an atomic type (Element) specifying the number of valence electrons and the potential (or pseudopotential) it creates with respect to the electrons. The Model structure also contains the list of energy terms defining the energy functional to be minimised during the SCF. For the silicon example above, we used an LDA model, which consists of the following terms[2]:","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"[2]: If you are not familiar with Julia syntax, typeof.(model.term_types) is equivalent to [typeof(t) for t in model.term_types].","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"typeof.(model.term_types)","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"DFTK computes energies for all terms of the model individually, which are available in scfres.energies:","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"scfres.energies","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"For now the following energy terms are available in DFTK:","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"Kinetic energy\nLocal potential energy, either given by analytic potentials or specified by the type of atoms.\nNonlocal potential energy, for norm-conserving pseudopotentials\nNuclei energies (Ewald or pseudopotential correction)\nHartree energy\nExchange-correlation energy\nPower nonlinearities (useful for Gross-Pitaevskii type models)\nMagnetic field energy\nEntropy term","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"Custom types can be added if needed. For examples see the definition of the above terms in the src/terms directory.","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"By mixing and matching these terms, the user can create custom models not limited to DFT. Convenience constructors are provided for common cases:","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"model_LDA: LDA model using the Teter parametrisation\nmodel_DFT: Assemble a DFT model using any of the LDA or GGA functionals of the libxc library, for example: model_DFT(lattice, atoms, [:gga_x_pbe, :gga_c_pbe]) model_DFT(lattice, atoms, :lda_xc_teter93) where the latter is equivalent to model_LDA. Specifying no functional is the reduced Hartree-Fock model: model_DFT(lattice, atoms, [])\nmodel_atomic: A linear model, which contains no electron-electron interaction (neither Hartree nor XC term).","category":"page"},{"location":"advanced/data_structures/#PlaneWaveBasis-and-plane-wave-discretisations-1","page":"Data structures","title":"PlaneWaveBasis and plane-wave discretisations","text":"","category":"section"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"The PlaneWaveBasis datastructure handles the discretization of a given Model in a plane-wave basis. In plane-wave methods the discretization is twofold: Once the k-point grid, which determines the sampling inside the Brillouin zone and on top of that a finite plane-wave grid to discretise the lattice-periodic functions. The former aspect is controlled by the kgrid argument of PlaneWaveBasis, the latter is controlled by the cutoff energy parameter Ecut:","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"PlaneWaveBasis(model, Ecut; kgrid=kgrid)","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"The PlaneWaveBasis by default uses symmetry to reduce the number of k-points explicitly treated. For details see Crystal symmetries.","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"As mentioned, the periodic parts of Bloch waves are expanded in a set of normalized plane waves e_G:","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"beginaligned\n psi_k(x) = e^i k cdot x u_k(x)\n = sum_G in mathcal R^* c_G e^i k cdot x e_G(x)\nendaligned","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"where mathcal R^* is the set of reciprocal lattice vectors. The c_G are ell^2-normalized. The summation is truncated to a \"spherical\", k-dependent basis set","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":" S_k = leftG in mathcal R^* middle\n frac 1 2 k+ G^2 le E_textcutright","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"where E_textcut is the cutoff energy.","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"Densities involve terms like psi_k^2 = u_k^2 and therefore products e_-G e_G for G G in S_k. To represent these we use a \"cubic\", k-independent basis set large enough to contain the set G-G G G in S_k. We can obtain the coefficients of densities on the e_G basis by a convolution, which can be performed efficiently with FFTs (see G_to_r and r_to_G functions). Potentials are discretized on this same set.","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"The normalization conventions used in the code is that quantities stored in reciprocal space are coefficients in the e_G basis, and quantities stored in real space use real physical values. This means for instance that wavefunctions in the real space grid are normalized as fracOmegaN sum_r psi(r)^2 = 1 where N is the number of grid points.","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"For example let us check the normalization of the first eigenfunction at the first k-point in reciprocal space:","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"ψtest = scfres.ψ[1][:, 1]\nsum(abs2.(ψtest))","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"We now perform an IFFT to get ψ in real space. The k-point has to be passed because ψ is expressed on the k-dependent basis. Again the function is normalised:","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"ψreal = G_to_r(basis, basis.kpoints[1], ψtest)\nsum(abs2.(ψreal)) * model.unit_cell_volume / prod(basis.fft_size)","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"The list of k points of the basis can be obtained with basis.kpoints.","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"basis.kpoints","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"The G vectors of the \"spherical\", k-dependent grid can be obtained with G_vectors:","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"[length(G_vectors(kpoint)) for kpoint in basis.kpoints]","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"ik = 1\nG_vectors(basis.kpoints[ik])[1:4]","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"The list of G vectors (Fourier modes) of the \"cubic\", k-independent basis set can be obtained similarly with G_vectors(basis).","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"length(G_vectors(basis)), prod(basis.fft_size)","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"collect(G_vectors(basis))[1:4]","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"Analogously the list of r vectors (real-space grid) can be obtained with r_vectors(basis):","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"length(r_vectors(basis))","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"collect(r_vectors(basis))[1:4]","category":"page"},{"location":"advanced/data_structures/#Accessing-Bloch-waves-and-densities-1","page":"Data structures","title":"Accessing Bloch waves and densities","text":"","category":"section"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"Wavefunctions are stored in an array scfres.ψ as ψ[ik][iG, iband] where ik is the index of the kpoint (in basis.kpoints), iG is the index of the plane wave (in G_vectors(basis.kpoints[ik])) and iband is the index of the band. Densities are usually stored in a special type, RealFourierArray, from which the representation in real and reciprocal space can be accessed using ρ.real and ρ.fourier respectively.","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"using Plots # hide\nrvecs = collect(r_vectors(basis))[:, 1, 1] # slice along the x axis\nx = [r[1] for r in rvecs] # only keep the x coordinate\nplot(x, scfres.ρ.real[:, 1, 1], label=\"\", xlabel=\"x\", ylabel=\"ρ\", marker=2)","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"G_energies = [sum(abs2.(model.recip_lattice * G)) ./ 2 for G in G_vectors(basis)][:]\nscatter(G_energies, abs.(scfres.ρ.fourier[:]);\n yscale=:log10, ylims=(1e-12, 1), label=\"\", xlabel=\"Energy\", ylabel=\"|ρ|^2\")","category":"page"},{"location":"advanced/data_structures/#","page":"Data structures","title":"Data structures","text":"Note that the density has no components on wavevectors above a certain energy, because the wavefunctions are limited to frac 1 2k+G^2 E_rm cut.","category":"page"},{"location":"examples/cohen_bergstresser/#","page":"Cohen-Bergstresser model","title":"Cohen-Bergstresser model","text":"EditURL = \"https://github.com/JuliaMolSim/DFTK.jl/blob/master/examples/cohen_bergstresser.jl\"","category":"page"},{"location":"examples/cohen_bergstresser/#Cohen-Bergstresser-model-1","page":"Cohen-Bergstresser model","title":"Cohen-Bergstresser model","text":"","category":"section"},{"location":"examples/cohen_bergstresser/#","page":"Cohen-Bergstresser model","title":"Cohen-Bergstresser model","text":"(Image: ) (Image: )","category":"page"},{"location":"examples/cohen_bergstresser/#","page":"Cohen-Bergstresser model","title":"Cohen-Bergstresser model","text":"This example considers the Cohen-Bergstresser model[CB1966], reproducing the results of the original paper. This model is particularly simple since its linear nature allows one to get away without any self-consistent field calculation.","category":"page"},{"location":"examples/cohen_bergstresser/#","page":"Cohen-Bergstresser model","title":"Cohen-Bergstresser model","text":"[CB1966]: M. L. Cohen and T. K. Bergstresser Phys. Rev. 141, 789 (1966) DOI 10.1103/PhysRev.141.789","category":"page"},{"location":"examples/cohen_bergstresser/#","page":"Cohen-Bergstresser model","title":"Cohen-Bergstresser model","text":"We build the lattice using the tabulated lattice constant from the original paper, stored in DFTK:","category":"page"},{"location":"examples/cohen_bergstresser/#","page":"Cohen-Bergstresser model","title":"Cohen-Bergstresser model","text":"using DFTK\n\nSi = ElementCohenBergstresser(:Si)\nlattice = Si.lattice_constant / 2 .* [[0 1 1.]; [1 0 1.]; [1 1 0.]]\natoms = [Si => [ones(3)/8, -ones(3)/8]];\nnothing #hide","category":"page"},{"location":"examples/cohen_bergstresser/#","page":"Cohen-Bergstresser model","title":"Cohen-Bergstresser model","text":"Next we build the rather simple model and discretise it with moderate Ecut:","category":"page"},{"location":"examples/cohen_bergstresser/#","page":"Cohen-Bergstresser model","title":"Cohen-Bergstresser model","text":"Ecut = 10.0\nmodel = Model(lattice; atoms=atoms, terms=[Kinetic(), AtomicLocal()])\nbasis = PlaneWaveBasis(model, Ecut);\nnothing #hide","category":"page"},{"location":"examples/cohen_bergstresser/#","page":"Cohen-Bergstresser model","title":"Cohen-Bergstresser model","text":"We diagonalise at the Gamma point to find a Fermi level ...","category":"page"},{"location":"examples/cohen_bergstresser/#","page":"Cohen-Bergstresser model","title":"Cohen-Bergstresser model","text":"ham = Hamiltonian(basis)\neigres = diagonalize_all_kblocks(DFTK.lobpcg_hyper, ham, 6)\nεF = find_fermi_level(basis, eigres.λ)","category":"page"},{"location":"examples/cohen_bergstresser/#","page":"Cohen-Bergstresser model","title":"Cohen-Bergstresser model","text":"... and compute and plot 8 bands:","category":"page"},{"location":"examples/cohen_bergstresser/#","page":"Cohen-Bergstresser model","title":"Cohen-Bergstresser model","text":"using Plots\n\nn_bands = 8\nρ0 = guess_density(basis) # Just dummy, has no meaning in this model\np = plot_bandstructure(basis, ρ0, n_bands, εF=εF, kline_density=10)\nylims!(p, (-5, 6))","category":"page"},{"location":"#DFTK.jl:-The-density-functional-toolkit.-1","page":"Home","title":"DFTK.jl: The density-functional toolkit.","text":"","category":"section"},{"location":"#","page":"Home","title":"Home","text":"The density-functional toolkit, DFTK for short, is a library of Julia routines for playing with plane-wave density-functional theory (DFT) algorithms. In its basic formulation it solves periodic Kohn-Sham equations. The unique feature of the code is its emphasis on simplicity and flexibility with the goal of facilitating methodological development and interdisciplinary collaboration. In about 5k lines of pure Julia code we already support a sizeable set of features, after just a good year of development. Our performance is of the same order of magnitude as much larger production codes such as Abinit, Quantum Espresso and VASP.","category":"page"},{"location":"#package-features-1","page":"Home","title":"Package features","text":"","category":"section"},{"location":"#","page":"Home","title":"Home","text":"Methods and models:\nKohn-Sham-like models, with an emphasis on flexibility: compose your own model, from Cohen-Bergstresser linear eigenvalue equations to Gross-Pitaevskii equations and sophisticated LDA/GGA functionals (any functional from the libxc library)\nAnalytic potentials or Godecker norm-conserving pseudopotentials (GTH, HGH)\nBrillouin zone symmetry for k-Point sampling using spglib\nSmearing functions for metals\nSelf-consistent field approaches: Damping, Kerker mixing, Anderson/Pulay/DIIS mixing\nDirect minimization\nMulti-level threading (kpoints, eigenvectors, FFTs, linear algebra)\n1D / 2D / 3D systems\nMagnetic fields\nGround-state properties and post-processing:\nTotal energy\nForces\nDensity of states (DOS), local density of states (LDOS)\nBand structures\nEasy access to all intermediate quantities (e.g. density, Bloch waves)\nSupport for arbitrary floating point types, including Float32 (single precision) or Double64 (from DoubleFloats.jl). For DFT this is currently restricted to LDA (with Slater exchange and VWN correlation).\nThird-party integrations:\nUse structures prepared in pymatgen, ASE or abipy.\nasedftk: DFTK-based calculator implementation for ASE.\nRead data in ETSF Nanoquanta format.","category":"page"},{"location":"#example-index-1","page":"Home","title":"Example index","text":"","category":"section"},{"location":"#","page":"Home","title":"Home","text":"First, new users should take a look at the Installation and Tutorial sections. More details about DFTK are explained in the examples as we go along:","category":"page"},{"location":"#","page":"Home","title":"Home","text":"Pages = [\n \"examples/metallic_systems.md\",\n \"examples/pymatgen.md\",\n \"examples/ase.md\",\n \"examples/gross_pitaevskii.md\",\n \"examples/gross_pitaevskii_2D.md\",\n \"examples/cohen_bergstresser.md\",\n \"examples/arbitrary_floattype.md\",\n]\nDepth = 1","category":"page"},{"location":"#","page":"Home","title":"Home","text":"These and more examples can be found in the examples directory of the main code.","category":"page"},{"location":"#","page":"Home","title":"Home","text":"If you have a great example you think would fit here, please open a pull request!","category":"page"}]
}