PseudoPotentialData

Enables programmatic access to standard pseudopotential libraries for solid-state calculations. In using this library the combination of a string identifier and the element symbol provides a unique and reproducible mapping to a pseudopotential file. Moreover in case the pseudopotential file happens to be missing on the computer Julia's artifact system takes care to automatically download it as needed.

Basic usage

For example, the following code automatically downloads the pseudopotential file of the standard pseudodojo pseudopotential for LDA pseudopotentials (referred to by the identifier dojo.nc.sr.lda.v0_4_1.standard.upf) and places the full path to the downloaded pseudopotential file into the filename variable:

using PseudoPotentialData
family = PseudoFamily("dojo.nc.sr.lda.v0_4_1.standard.upf")
filename = pseudofile(family, :Si)

"/home/runner/.julia/artifacts/326db5c901e2681584ec5c06fc17f6c96e516ff9/Si.upf"

As you see this will be a string such as /home/user/.julia/artifacts/56094b8162385233890d523c827ba06e07566079/Si.upf, which luckily you don't usually have to know or remember. Note, further that this path may differ between computers, julia versions etc. It is therefore highly recommended to use the above mechanism based on identfier and element symbol instead of hard-coding the expanded path in user scripts.

For multiple elements you can similarly use

pseudofile.(family, [:C, :Si])

2-element Vector{String}:
 "/home/runner/.julia/artifacts/326db5c901e2681584ec5c06fc17f6c96e516ff9/C.upf"
 "/home/runner/.julia/artifacts/326db5c901e2681584ec5c06fc17f6c96e516ff9/Si.upf"

A PseudoFamily struct is furthermore an AbstractDict{Symbol,String} for the mapping of element symbol to file path, e.g. one can perform index lookup

family[:Si]

"/home/runner/.julia/artifacts/326db5c901e2681584ec5c06fc17f6c96e516ff9/Si.upf"

iterate over pairs

for (k, v) in family
   println(k, " => ", v)
   break
end

H => /home/runner/.julia/artifacts/326db5c901e2681584ec5c06fc17f6c96e516ff9/H.upf

or get the list of available elements as the list of keys:

collect(keys(family))

70-element Vector{Symbol}:
 :H
 :He
 :Li
 :Be
 :B
 :C
 :N
 :O
 :F
 :Ne
 ⋮
 :Ir
 :Pt
 :Au
 :Hg
 :Tl
 :Pb
 :Bi
 :Po
 :Rn

Metadata on the pseudopotential family and individual elements in the family can be accessed via the pseudometa function:

pseudometa(family)

Dict{String, Any} with 11 entries:
  "functional"        => "lda"
  "elements"          => [:H, :He, :Li, :Be, :B, :C, :N, :O, :F, :Ne  …  :Os, :…
  "relativistic"      => "sr"
  "program"           => "oncvpsp3"
  "version"           => v"0.4.1"
  "extra"             => ["standard"]
  "extracted_on"      => "2024-12-27T19:51:43.744"
  "extension"         => "upf"
  "pseudodojo_handle" => "nc-sr-04_pw_standard_upf"
  "type"              => "nc"
  "collection"        => "dojo"

or for an element:

pseudometa(family, :Si)

Dict{String, Any} with 6 entries:
  "rcut"           => 10.0
  "Ecut"           => 16
  "supersampling"  => 2.0
  "cutoffs_normal" => Dict{String, Any}("Ecut"=>16, "supersampling"=>2.0)
  "cutoffs_high"   => Dict{String, Any}("Ecut"=>22, "supersampling"=>2.0)
  "cutoffs_low"    => Dict{String, Any}("Ecut"=>12, "supersampling"=>2.0)

Notably this often contains recommended values of the kinetic energy cutoffs of plane-wave bases. These can be also accessed more conveniently via

recommended_cutoff(family, :Si)

(Ecut = 16.0, supersampling = 2.0, Ecut_density = 64.0)

Note, that the Ecut and Ecut_density values are in atomic Hartree units.

Available pseudopotential families and naming convention

A list of available pseudopotential families is available as

PseudoPotentialData.family_identifiers()

24-element Vector{String}:
 "cp2k.nc.sr.lda.v0_1.largecore.gth"
 "cp2k.nc.sr.lda.v0_1.semicore.gth"
 "cp2k.nc.sr.lda.v0_1.smallcore.gth"
 "cp2k.nc.sr.pbe.v0_1.largecore.gth"
 "cp2k.nc.sr.pbe.v0_1.semicore.gth"
 "cp2k.nc.sr.pbe.v0_1.smallcore.gth"
 "dojo.nc.fr.pbe.v0_4.standard.upf"
 "dojo.nc.fr.pbe.v0_4.stringent.upf"
 "dojo.nc.fr.pbesol.v0_4.standard.upf"
 "dojo.nc.fr.pbesol.v0_4.stringent.upf"
 ⋮
 "dojo.nc.sr.pbe.v0_5.stringent.upf"
 "dojo.nc.sr.pbesol.v0_4_1.standard.upf"
 "dojo.nc.sr.pbesol.v0_4_1.stringent.upf"
 "dojo.paw.sr.lda.v1_1.standard.xml"
 "dojo.paw.sr.lda.v1_1.stringent.xml"
 "dojo.paw.sr.pbe.v1_1.standard.xml"
 "dojo.paw.sr.pbe.v1_1.stringent.xml"
 "dojo.paw.sr.pbesol.v1_1.standard.xml"
 "dojo.paw.sr.pbesol.v1_1.stringent.xml"

The naming convention is as that each pseudo family name consists of a list of fields, which are concatenated using a . (dot). These are:

1. collection: An identifier for the pseudo collection (like dojo for the PseudoDojo family of potentials.
2. type: The type of pseudopotential (nc: norm-conserving, us: ultrasoft, paw: projected augmented wave)
3. relativistic: Details on the level of relativistic effects employed when generating the pseudo (fr: Full relativistic, sr: Scalar relativistic, nr: No relativistic)
4. functional: The functional for which the pseudopotential was prepared
5. version: The version of the pseudopotential construction (with version points replaced by underscores)
6. extra: Some additional comments specifying the pseudopotential. E.g. for PseudoDojo potentials there is usually a stringent version (requiring slightly larger cutoffs) and a standard version being a bit softer.
7. extension: The file format of the pseudopotential files in this library.

For a given PseudoFamily object the above fields (as well as typically additional metadata information) can also be accessed via the pseudometa function as indicated above.

More details on the available pseudopotential families is given in the PseudoLibrary repository, which manages the data underlying this package.

Interface

PseudoFamily(identifier::AbstractString) -> PseudoFamily

artifact_directory(family::PseudoFamily) -> String

family_identifiers() -> Vector{String}

pseudofile(family::PseudoFamily, element::Symbol) -> String

pseudometa(
    family::PseudoFamily,
    element::Symbol
) -> Dict{String, Any}

pseudometa(family::PseudoFamily) -> Dict{String, Any}

recommended_cutoff(
    family::PseudoFamily,
    element::Symbol
) -> NamedTuple{(:Ecut, :supersampling, :Ecut_density), <:Tuple{Union{Missing, Float64}, Union{Missing, Float64}, Union{Missing, Float64}}}