/
index.html
66 lines (61 loc) · 16.5 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
<!DOCTYPE html>
<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Saving SCF results on disk and SCF checkpoints · DFTK.jl</title><link rel="canonical" href="https://juliamolsim.github.io/DFTK.jl/stable/examples/scf_checkpoints/"/><link href="https://fonts.googleapis.com/css?family=Lato|Roboto+Mono" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.0/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.0/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.0/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.11.1/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="../.."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="../../assets/documenter.js"></script><script src="../../siteinfo.js"></script><script src="../../../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../../assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../../assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="../../assets/themeswap.js"></script><link href="../../assets/favicon.ico" rel="icon" type="image/x-icon"/></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="../../"><img src="../../assets/logo.png" alt="DFTK.jl logo"/></a><div class="docs-package-name"><span class="docs-autofit">DFTK.jl</span></div><form class="docs-search" action="../../search/"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="../../">Home</a></li><li><span class="tocitem">Getting started</span><ul><li><a class="tocitem" href="../../guide/installation/">Installation</a></li><li><a class="tocitem" href="../../guide/tutorial/">Tutorial</a></li><li><a class="tocitem" href="../../guide/input_output/">Input and output formats</a></li><li><a class="tocitem" href="../../guide/parallelization/">Timings and parallelization</a></li><li><a class="tocitem" href="../../guide/density_functional_theory/">Density-functional theory</a></li></ul></li><li><span class="tocitem">Examples</span><ul><li><a class="tocitem" href="../metallic_systems/">Temperature and metallic systems</a></li><li><a class="tocitem" href="../pymatgen/">Creating supercells with pymatgen</a></li><li><a class="tocitem" href="../ase/">Creating slabs with ASE</a></li><li><a class="tocitem" href="../collinear_magnetism/">Collinear spin and magnetic systems</a></li><li><a class="tocitem" href="../geometry_optimization/">Geometry optimization</a></li><li><a class="tocitem" href="../scf_callbacks/">Monitoring self-consistent field calculations</a></li><li class="is-active"><a class="tocitem" href>Saving SCF results on disk and SCF checkpoints</a><ul class="internal"><li><a class="tocitem" href="#Checkpointing-of-SCF-calculations"><span>Checkpointing of SCF calculations</span></a></li></ul></li><li><a class="tocitem" href="../polarizability/">Polarizability by linear response</a></li><li><a class="tocitem" href="../gross_pitaevskii/">Gross-Pitaevskii equation in one dimension</a></li><li><a class="tocitem" href="../gross_pitaevskii_2D/">Gross-Pitaevskii equation with magnetism</a></li><li><a class="tocitem" href="../cohen_bergstresser/">Cohen-Bergstresser model</a></li><li><a class="tocitem" href="../arbitrary_floattype/">Arbitrary floating-point types</a></li><li><a class="tocitem" href="../custom_solvers/">Custom solvers</a></li><li><a class="tocitem" href="../custom_potential/">Custom potential</a></li></ul></li><li><span class="tocitem">Advanced topics</span><ul><li><a class="tocitem" href="../../advanced/conventions/">Notation and conventions</a></li><li><a class="tocitem" href="../../advanced/data_structures/">Data structures</a></li><li><a class="tocitem" href="../../advanced/useful_formulas/">Useful formulas</a></li><li><a class="tocitem" href="../../advanced/symmetries/">Crystal symmetries</a></li></ul></li><li><a class="tocitem" href="../../api/">API reference</a></li><li><a class="tocitem" href="../../publications/">Publications</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li><a class="is-disabled">Examples</a></li><li class="is-active"><a href>Saving SCF results on disk and SCF checkpoints</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href>Saving SCF results on disk and SCF checkpoints</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://github.com/JuliaMolSim/DFTK.jl/blob/master/examples/scf_checkpoints.jl" title="Edit on GitHub"><span class="docs-icon fab"></span><span class="docs-label is-hidden-touch">Edit on GitHub</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="Saving-SCF-results-on-disk-and-SCF-checkpoints"><a class="docs-heading-anchor" href="#Saving-SCF-results-on-disk-and-SCF-checkpoints">Saving SCF results on disk and SCF checkpoints</a><a id="Saving-SCF-results-on-disk-and-SCF-checkpoints-1"></a><a class="docs-heading-anchor-permalink" href="#Saving-SCF-results-on-disk-and-SCF-checkpoints" title="Permalink"></a></h1><p><a href="https://mybinder.org/v2/gh/JuliaMolSim/DFTK.jl/gh-pages?filepath=v0.3.0/examples/scf_checkpoints.ipynb"><img src="https://mybinder.org/badge_logo.svg" alt/></a> <a href="https://nbviewer.jupyter.org/github/JuliaMolSim/DFTK.jl/blob/gh-pages/v0.3.0/examples/scf_checkpoints.ipynb"><img src="https://img.shields.io/badge/show-nbviewer-579ACA.svg" alt/></a></p><p>For longer DFT calculations it is pretty standard to run them on a cluster in advance and to perform postprocessing (band structure calculation, plotting of density, etc.) at a later point and potentially on a different machine.</p><p>To support such workflows DFTK offers the two functions <a href="../../api/#DFTK.save_scfres-Tuple{AbstractString, NamedTuple}"><code>save_scfres</code></a> and <a href="../../api/#DFTK.load_scfres"><code>load_scfres</code></a>, which allow to save the data structure returned by <a href="../../api/#DFTK.self_consistent_field-Tuple{PlaneWaveBasis}"><code>self_consistent_field</code></a> on disk or retrieve it back into memory, respectively. For this purpose DFTK uses the <a href="https://github.com/JuliaIO/JLD2.jl">JLD2.jl</a> file format and Julia package. For the moment this process is considered an experimental feature and has a number of caveats, see the warnings below.</p><div class="admonition is-warning"><header class="admonition-header">Saving `scfres` is experimental</header><div class="admonition-body"><p>The <a href="../../api/#DFTK.load_scfres"><code>load_scfres</code></a> and <a href="../../api/#DFTK.save_scfres-Tuple{AbstractString, NamedTuple}"><code>save_scfres</code></a> pair of functions are experimental features. This means:</p><ul><li>The interface of these functions as well as the format in which the data is stored on disk can change incompatibly in the future. At this point we make no promises ...</li><li>JLD2 is not yet completely matured and it is recommended to only use it for short-term storage and <strong>not</strong> to archive scientific results.</li><li>If you are using the functions to transfer data between different machines ensure that you use the <strong>same version of Julia, JLD2 and DFTK</strong> for saving and loading data.</li></ul></div></div><p>To illustrate the use of the functions in practice we will compute the total energy of the O₂ molecule at PBE level. To get the triplet ground state we use a collinear spin polarisation (see <a href="../collinear_magnetism/#Collinear-spin-and-magnetic-systems">Collinear spin and magnetic systems</a> for details) and a bit of temperature to ease convergence:</p><pre><code class="language-julia">using DFTK
using LinearAlgebra
using JLD2
d = 2.079 # oxygen-oxygen bondlength
a = 9.0 # size of the simulation box
lattice = diagm(a * ones(3))
O = ElementPsp(:O, psp=load_psp("hgh/pbe/O-q6.hgh"))
atoms = [O => d / 2a * [[0, 0, 1], [0, 0, -1]]]
magnetic_moments = [O => [1., 1.]]
Ecut = 10 # Far too small to be converged
model = model_PBE(lattice, atoms, temperature=0.02, smearing=smearing=Smearing.Gaussian(),
magnetic_moments=magnetic_moments)
basis = PlaneWaveBasis(model, Ecut; kgrid=[1, 1, 1])
scfres = self_consistent_field(basis, tol=1e-2, ρ=guess_density(basis, magnetic_moments))
save_scfres("scfres.jld2", scfres);</code></pre><pre class="documenter-example-output">n Free energy Eₙ-Eₙ₋₁ ρout-ρin Magnet Diag
--- --------------- --------- -------- ------ ----
1 -27.63770786053 NaN 7.35e-01 0.001 6.5
2 -28.50153606115 -8.64e-01 4.82e-01 0.912 5.0
3 -28.90880216515 -4.07e-01 1.30e-01 1.284 5.0
4 -28.93727831009 -2.85e-02 6.83e-02 1.741 3.0
5 -28.93838048481 -1.10e-03 4.51e-02 1.934 3.0</pre><pre><code class="language-julia">scfres.energies</code></pre><pre class="documenter-example-output">Energy breakdown:
Kinetic 16.9252257
AtomicLocal -58.8307019
AtomicNonlocal 4.7445086
Ewald -4.8994689
PspCorrection 0.0044178
Hartree 19.5426744
Xc -6.4226948
Entropy -0.0023414
total -28.938380484809
</pre><p>The <code>scfres.jld2</code> file could now be transfered to a different computer, Where one could fire up a REPL to inspect the results of the above calculation:</p><pre><code class="language-julia">using DFTK
using JLD2
loaded = load_scfres("scfres.jld2")
propertynames(loaded)</code></pre><pre class="documenter-example-output">(:ham, :basis, :energies, :converged, :ρ, :eigenvalues, :occupation, :εF, :n_iter, :n_ep_extra, :ψ, :diagonalization, :stage)</pre><pre><code class="language-julia">loaded.energies</code></pre><pre class="documenter-example-output">Energy breakdown:
Kinetic 16.9252257
AtomicLocal -58.8307019
AtomicNonlocal 4.7445086
Ewald -4.8994689
PspCorrection 0.0044178
Hartree 19.5426744
Xc -6.4226948
Entropy -0.0023414
total -28.938380484809
</pre><p>Since the loaded data contains exactly the same data as the <code>scfres</code> returned by the SCF calculation one could use it to plot a band structure, e.g. <code>plot_bandstructure(load_scfres("scfres.jld2"))</code> directly from the stored data.</p><h2 id="Checkpointing-of-SCF-calculations"><a class="docs-heading-anchor" href="#Checkpointing-of-SCF-calculations">Checkpointing of SCF calculations</a><a id="Checkpointing-of-SCF-calculations-1"></a><a class="docs-heading-anchor-permalink" href="#Checkpointing-of-SCF-calculations" title="Permalink"></a></h2><p>A related feature, which is very useful especially for longer calculations with DFTK is automatic checkpointing, where the state of the SCF is periodically written to disk. The advantage is that in case the calculation errors or gets aborted due to overrunning the walltime limit one does not need to start from scratch, but can continue the calculation from the last checkpoint.</p><p>To enable automatic checkpointing in DFTK one needs to pass the <code>ScfSaveCheckpoints</code> callback to <a href="../../api/#DFTK.self_consistent_field-Tuple{PlaneWaveBasis}"><code>self_consistent_field</code></a>, for example:</p><pre><code class="language-julia">callback = DFTK.ScfSaveCheckpoints()
scfres = self_consistent_field(basis; ρ=guess_density(basis, magnetic_moments),
tol=1e-2, callback=callback);</code></pre><p>Notice that using this callback makes the SCF go silent since the passed callback parameter overwrites the default value (namely <code>DefaultScfCallback()</code>) which exactly gives the familiar printing of the SCF convergence. If you want to have both (printing and checkpointing) you need to chain both callbacks:</p><pre><code class="language-julia">callback = DFTK.ScfDefaultCallback() ∘ DFTK.ScfSaveCheckpoints(keep=true)
scfres = self_consistent_field(basis; ρ=guess_density(basis, magnetic_moments),
tol=1e-2, callback=callback);</code></pre><pre class="documenter-example-output">n Free energy Eₙ-Eₙ₋₁ ρout-ρin Magnet Diag
--- --------------- --------- -------- ------ ----
1 -27.63900019184 NaN 7.35e-01 0.001 4.5
2 -28.50159036045 -8.63e-01 4.82e-01 0.905 5.0
3 -28.90884963201 -4.07e-01 1.30e-01 1.277 5.0
4 -28.93722258809 -2.84e-02 6.86e-02 1.736 3.0
5 -28.93835470072 -1.13e-03 4.57e-02 1.932 3.0</pre><p>For more details on using callbacks with DFTK's <code>self_consistent_field</code> function see <a href="../scf_callbacks/#Monitoring-self-consistent-field-calculations">Monitoring self-consistent field calculations</a>.</p><p>By default checkpoint is saved in the file <code>dftk_scf_checkpoint.jld2</code>, which is deleted automatically once the SCF completes successfully. If one wants to keep the file one needs to specify <code>keep=true</code> as has been done in the ultimate SCF for demonstration purposes: now we can continue the previous calculation from the last checkpoint as if the SCF had been aborted. For this one just loads the checkpoint with <a href="../../api/#DFTK.load_scfres"><code>load_scfres</code></a>:</p><pre><code class="language-julia">oldstate = load_scfres("dftk_scf_checkpoint.jld2")
scfres = self_consistent_field(oldstate.basis, ρ=oldstate.ρ,
ψ=oldstate.ψ, tol=1e-3);</code></pre><pre class="documenter-example-output">n Free energy Eₙ-Eₙ₋₁ ρout-ρin Magnet Diag
--- --------------- --------- -------- ------ ----
1 -28.93867505826 NaN 2.13e-02 1.986 1.0
2 -28.93935333763 -6.78e-04 1.17e-02 1.982 1.0</pre><div class="admonition is-info"><header class="admonition-header">Availability of `load_scfres`, `save_scfres` and `ScfSaveCheckpoints`</header><div class="admonition-body"><p>As JLD2 is an optional dependency of DFTK these three functions are only available once one has <em>both</em> imported DFTK and JLD2 (<code>using DFTK</code> and <code>using JLD2</code>).</p></div></div><p>(Cleanup files generated by this notebook)</p><pre><code class="language-julia">rm("dftk_scf_checkpoint.jld2")
rm("scfres.jld2")</code></pre></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../scf_callbacks/">« Monitoring self-consistent field calculations</a><a class="docs-footer-nextpage" href="../polarizability/">Polarizability by linear response »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> on <span class="colophon-date" title="Thursday 3 June 2021 17:00">Thursday 3 June 2021</span>. Using Julia version 1.6.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>