Input and output formats

This section provides an overview of the input and output formats supported by DFTK, usually via integration with a third-party library.

Reading / writing files supported by AtomsIO

AtomsIO is a Julia package which supports reading / writing atomistic structures from / to a large range of file formats. Supported formats include Crystallographic Information Framework (CIF), XYZ and extxyz files, ASE / Gromacs / LAMMPS / Amber trajectory files or input files of various other codes (e.g. Quantum Espresso, VASP, ABINIT, CASTEP, …). The full list of formats is is available in the AtomsIO documentation.

The AtomsIO functionality is split into two packages. The main package, AtomsIO itself, only depends on packages, which are registered in the Julia General package registry. In contrast AtomsIOPython extends AtomsIO by parsers depending on python packages, which are automatically managed via PythonCall. While it thus provides the full set of supported IO formats, this also adds additional practical complications, so some users may choose not to use AtomsIOPython.

As an example we start the calculation of a simple antiferromagnetic iron crystal using a Quantum-Espresso input file, Fe_afm.pwi. For more details about calculations on magnetic systems using collinear spin, see Collinear spin and magnetic systems.

First we parse the Quantum Espresso input file using AtomsIO, which reads the lattice, atomic positions and initial magnetisation from the input file and returns it as an AtomsBase AbstractSystem, the JuliaMolSim community standard for representing atomic systems.

using AtomsIO        # Use Julia-only IO parsers
using AtomsIOPython  # Use python-based IO parsers (e.g. ASE)
system = load_system("Fe_afm.pwi")
FlexibleSystem(Fe₂, periodic = TTT):
    bounding_box      : [ 2.86814        0        0;
                                0  2.86814        0;
                                0        0  2.86814]u"Å"

    Atom(Fe, [       0,        0,        0]u"Å")
    Atom(Fe, [ 1.43407,  1.43407,        0]u"Å")

      .------.  
     /|      |  
    * |      |  
    | |      |  
    | .------.  
    |/  Fe  /   
    Fe-----*    

Next we attach pseudopotential information, since currently the parser is not yet capable to read this information from the file.

using DFTK
system = attach_psp(system, Fe="hgh/pbe/fe-q16.hgh")
FlexibleSystem(Fe₂, periodic = TTT):
    bounding_box      : [ 2.86814        0        0;
                                0  2.86814        0;
                                0        0  2.86814]u"Å"

    Atom(Fe, [       0,        0,        0]u"Å")
    Atom(Fe, [ 1.43407,  1.43407,        0]u"Å")

      .------.  
     /|      |  
    * |      |  
    | |      |  
    | .------.  
    |/  Fe  /   
    Fe-----*    

Finally we make use of DFTK's AtomsBase integration to run the calculation.

model = model_LDA(system; temperature=0.01)
basis = PlaneWaveBasis(model; Ecut=10, kgrid=(2, 2, 2))
ρ0 = guess_density(basis, system)
scfres = self_consistent_field(basis, ρ=ρ0);
n     Energy            log10(ΔE)   log10(Δρ)   Magnet   Diag   Δtime
---   ---------------   ---------   ---------   ------   ----   ------
  1   -223.7491160076                    0.22   -6.319    5.4
  2   -224.1606043595       -0.39       -0.21   -3.325    1.7    163ms
  3   -224.2176013789       -1.24       -1.06   -1.614    3.5    260ms
  4   -224.2198748700       -2.64       -1.46   -1.193    1.1    150ms
  5   -224.2207946165       -3.04       -1.72   -0.823    1.0    147ms
  6   -224.2212127296       -3.38       -2.00   -0.485    1.0    166ms
  7   -224.2213736181       -3.79       -2.35   -0.229    1.4    152ms
  8   -224.2214154288       -4.38       -2.88   -0.077    2.2    163ms
  9   -224.2214205653       -5.29       -3.56   -0.007    3.0    185ms
 10   -224.2214206910       -6.90       -3.81    0.001    3.2    244ms
 11   -224.2214207111       -7.70       -4.06   -0.001    2.2    177ms
 12   -224.2214207179       -8.16       -4.44    0.000    1.6    151ms
 13   -224.2214207187       -9.14       -5.04    0.000    2.5    171ms
 14   -224.2214207187      -10.28       -5.39    0.000    1.8    162ms
 15   -224.2214207187      -10.97       -5.83   -0.000    2.8    226ms
 16   -224.2214207187      -13.07       -6.22    0.000    2.5    207ms

Writing VTK files for visualization

For visualizing the density or the Kohn-Sham orbitals DFTK supports storing the result of an SCF calculations in the form of VTK files. These can afterwards be visualized using tools such as paraview. Using this feature requires the WriteVTK.jl Julia package.

using WriteVTK
save_scfres("iron_afm.vts", scfres; save_ψ=true);

This will save the iron calculation above into the file iron_afm.vts, using save_ψ=true to also include the KS orbitals.

Parsable data-export using json

Many structures in DFTK support the (unexported) todict function, which returns a simplified dictionary representation of the data.

DFTK.todict(scfres.energies)
Dict{String, Float64} with 9 entries:
  "AtomicNonlocal" => -4.34593
  "PspCorrection"  => 7.03001
  "Ewald"          => -161.527
  "total"          => -224.221
  "Entropy"        => -0.0306478
  "Kinetic"        => 75.663
  "AtomicLocal"    => -161.128
  "Hartree"        => 41.397
  "Xc"             => -21.2803

This in turn can be easily written to disk using a JSON library. Currently we integrate most closely with JSON3, which is thus recommended.

using JSON3
open("iron_afm_energies.json", "w") do io
    JSON3.pretty(io, DFTK.todict(scfres.energies))
end
println(read("iron_afm_energies.json", String))
{
    "AtomicNonlocal": -4.345930956928255,
    "PspCorrection": 7.03000636467455,
    "Ewald": -161.52650757200072,
    "total": -224.22142071873438,
    "Entropy": -0.03064782032849634,
    "Kinetic": 75.6630497647276,
    "AtomicLocal": -161.12810866589587,
    "Hartree": 41.39700665438633,
    "Xc": -21.28028848736955
}

Once JSON3 is loaded, additionally a convenience function for saving a parsable summary of scfres objects using save_scfres is available:

using JSON3
save_scfres("iron_afm.json", scfres)

Writing and reading JLD2 files

The full state of a DFTK self-consistent field calculation can be stored on disk in form of an JLD2.jl file. This file can be read from other Julia scripts as well as other external codes supporting the HDF5 file format (since the JLD2 format is based on HDF5).

using JLD2
save_scfres("iron_afm.jld2", scfres);

Since such JLD2 can also be read by DFTK to start or continue a calculation, these can also be used for checkpointing or for transferring results to a different computer. See Saving SCF results on disk and SCF checkpoints for details.

(Cleanup files generated by this notebook.)

rm("iron_afm.vts")
rm("iron_afm.jld2")
rm("iron_afm_energies.json")