From ab8d67d5c8c1b6272062e1989473a827309013f2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?B=C3=A1lint=20Aradi?= Date: Fri, 30 Nov 2018 14:18:10 +0100 Subject: [PATCH] Update chapters in Basic usage Adapt to changed output, set current parser version in input, make run.sh scripts complete. --- .../basics/bandstruct/1_density/dftb_in.hsd | 9 +- .../basics/bandstruct/1_density/run.sh | 7 + .../basics/bandstruct/2_bands/dftb_in.hsd | 9 +- .../recipes/basics/bandstruct/2_bands/run.sh | 2 + .../recipes/basics/firstcalc/dftb_in.hsd | 3 - docs/basics/bandstruct.rst | 38 +++-- docs/basics/firstcalc.rst | 144 +++++++++--------- docs/basics/index.rst | 5 + docs/introduction.rst | 44 ++++-- 9 files changed, 143 insertions(+), 118 deletions(-) diff --git a/docs/_archives/recipes/basics/bandstruct/1_density/dftb_in.hsd b/docs/_archives/recipes/basics/bandstruct/1_density/dftb_in.hsd index 19f12c46..67f2aa7a 100644 --- a/docs/_archives/recipes/basics/bandstruct/1_density/dftb_in.hsd +++ b/docs/_archives/recipes/basics/bandstruct/1_density/dftb_in.hsd @@ -14,8 +14,8 @@ Geometry = GenFormat { } Hamiltonian = DFTB { - SCC = Yes - SCCTolerance = 1e-5 + Scc = Yes + SccTolerance = 1e-5 SlaterKosterFiles = Type2FileNames { Prefix = "../../../slakos/mio-ext/" Separator = "-" @@ -25,9 +25,6 @@ Hamiltonian = DFTB { Ti = "d" O = "p" } - Filling = Fermi { - Temperature [Kelvin] = 0.0 - } KPointsAndWeights = SupercellFolding { 4 0 0 0 4 0 @@ -52,6 +49,6 @@ Analysis { } ParserOptions { - ParserVersion = 5 + ParserVersion = 6 } diff --git a/docs/_archives/recipes/basics/bandstruct/1_density/run.sh b/docs/_archives/recipes/basics/bandstruct/1_density/run.sh index 53d807a4..e1ab9fda 100755 --- a/docs/_archives/recipes/basics/bandstruct/1_density/run.sh +++ b/docs/_archives/recipes/basics/bandstruct/1_density/run.sh @@ -1,3 +1,10 @@ #!/bin/bash set -e dftb+ > output +dp_dos band.out dos_total.dat >> output +dp_dos -w dos_ti.1.out dos_ti.s.dat >> output +dp_dos -w dos_ti.2.out dos_ti.p.dat >> output +dp_dos -w dos_ti.3.out dos_ti.d.dat >> output +dp_dos -w dos_o.1.out dos_o.s.dat >> output +dp_dos -w dos_o.2.out dos_o.p.dat >> output + diff --git a/docs/_archives/recipes/basics/bandstruct/2_bands/dftb_in.hsd b/docs/_archives/recipes/basics/bandstruct/2_bands/dftb_in.hsd index e4701170..398a6d69 100644 --- a/docs/_archives/recipes/basics/bandstruct/2_bands/dftb_in.hsd +++ b/docs/_archives/recipes/basics/bandstruct/2_bands/dftb_in.hsd @@ -14,9 +14,9 @@ Geometry = GenFormat { } Hamiltonian = DFTB { - SCC = Yes + Scc = Yes ReadInitialCharges = Yes - MaxSCCIterations = 1 + MaxSccIterations = 1 SlaterKosterFiles = Type2FileNames { Prefix = "../../../slakos/mio-ext/" Separator = "-" @@ -26,9 +26,6 @@ Hamiltonian = DFTB { Ti = "d" O = "p" } - Filling = Fermi { - Temperature [Kelvin] = 0.0 - } KPointsAndWeights = Klines { 1 0.5 0.5 -0.5 # Z 20 0.0 0.0 0.0 # G @@ -38,5 +35,5 @@ Hamiltonian = DFTB { } ParserOptions { - ParserVersion = 5 + ParserVersion = 6 } diff --git a/docs/_archives/recipes/basics/bandstruct/2_bands/run.sh b/docs/_archives/recipes/basics/bandstruct/2_bands/run.sh index 40f4af79..f3978bc0 100755 --- a/docs/_archives/recipes/basics/bandstruct/2_bands/run.sh +++ b/docs/_archives/recipes/basics/bandstruct/2_bands/run.sh @@ -2,3 +2,5 @@ set -e cp ../1_density/charges.bin . dftb+ > output +dp_bands band.out band >> output + diff --git a/docs/_archives/recipes/basics/firstcalc/dftb_in.hsd b/docs/_archives/recipes/basics/firstcalc/dftb_in.hsd index b0bab79b..89d7ede3 100644 --- a/docs/_archives/recipes/basics/firstcalc/dftb_in.hsd +++ b/docs/_archives/recipes/basics/firstcalc/dftb_in.hsd @@ -26,9 +26,6 @@ Hamiltonian = DFTB { O = "p" H = "s" } - Filling = Fermi { - Temperature [Kelvin] = 0.0 - } } Options {} diff --git a/docs/basics/bandstruct.rst b/docs/basics/bandstruct.rst index 1d700eab..88425a62 100644 --- a/docs/basics/bandstruct.rst +++ b/docs/basics/bandstruct.rst @@ -17,20 +17,20 @@ you will need the Slater-Koster sets `mio` and `tiorg`. The sample input files assume that the necessary Slater-Koster files have been copied into a subdirectory `mio-ext`. -The examples here are based on DFTB+ version 17.1, the input/output -files in other versions may slightly differ from those shown here. - Introduction ============ The calculation of the band structure for a periodic system consists of two -steps. First for self-consistent (SCC) calculations, the charges in the system -must be calculated using a converged k-point sampling. Then, keeping the -obtained self-consistent charges fixed, the one-electron levels must be -calculated for k-points chosen along the specific lines in k-space of the chosen -band structure. These are usually between high symmetry points in the Brillouin -zone of that unit cell. +steps. + +* First for self-consistent (SCC) calculations, the charges in the system must + be calculated using a converged k-point sampling. + +* Then, keeping the obtained self-consistent charges fixed, the one-electron + levels must be calculated for k-points chosen along the specific lines in + k-space of the chosen band structure. These are usually between high symmetry + points in the Brillouin zone of that unit cell. Creating the proper input charges @@ -84,9 +84,6 @@ good k-point sampling. A sample `dftb_in.hsd` input looks like:: Ti = "d" O = "p" } - Filling = Fermi { - Temperature [Kelvin] = 0.0 - } KPointsAndWeights = SupercellFolding { 4 0 0 0 4 0 @@ -111,7 +108,7 @@ good k-point sampling. A sample `dftb_in.hsd` input looks like:: } ParserOptions { - ParserVersion = 5 + ParserVersion = 6 } In the input above, the coordinates have been specified in relative (fractional) @@ -123,7 +120,7 @@ line of the geometry specification:: 6 F : -The k-points are been generated automatically using the ``SupercellFolding`` +The k-points are generated automatically using the ``SupercellFolding`` method, which enables among others the generation of Monkhorst-Pack schemes. In the current example, a k-point set equivalent to the Monkhorst-Pack scheme :math:`4 \times 4 \times 4` has been chosen (For details how to specify the @@ -141,7 +138,7 @@ an accuracy in the range of 1e-3 eV for the total energy. Also, by specifying a smaller SCC tolerance than the chosen one (1e-5) you can check that converging the charges more precisely does not significantly decrease the total energy. We note in passing that these settings provide well converged results for the total -energy in the current example, by in principal may not provide converged values +energy in the current example, but in principal may not provide converged values for other properties. One should, in principal, test the convergence of any evaluated properties with respect to the calculation parameters. @@ -259,8 +256,9 @@ to be changed slightly:: # ... -Note: only the relevant part of the input are shown, here. See the -`Introduction`_ how to obtain the archive with the full input. +Note: only the relevant parts of the input are shown, here. See the +:ref:`sec-introduction` section on how to obtain the archive with the full +input. The input is (must be) almost the same as in the previous case, with only a few adaptions: @@ -303,9 +301,9 @@ adaptions: point only, as demonstrated above for the Z-point. Running DFTB+ with the input above, the eigenlevel spectrum is calculated at - the required k-points. The results are written to the file `detailed.out` and - in more readable format to `band.out`. You can use the script `dp_bands` from - the `dptools` package to convert this file into NXY format. By issuing:: + the required k-points. The results are written to the file `band.out`. You can + use the script `dp_bands` from the `dptools` package to convert this file into + XNY format. By issuing:: dp_bands band.out band diff --git a/docs/basics/firstcalc.rst b/docs/basics/firstcalc.rst index e1336e30..e7ff7f91 100644 --- a/docs/basics/firstcalc.rst +++ b/docs/basics/firstcalc.rst @@ -7,16 +7,21 @@ First calculation with DFTB+ [Input: `recipes/basics/firstcalc/`] This chapter should serve as a tutorial guiding you through your first -calculation with DFTB+. As an example, the equilibrium geometry of a water -molecule is calculated. +calculation with DFTB+. As an example, the equilibrium geometry of the water +molecule will be calculated. As with all simulation tools, the work consists of +three steps: + +* telling DFTB+ what to do, +* running DFTB+, +* analysing the results. Providing the input =================== -First you have to create the input for the code. DFTB+ accepts the input as -Human-readable Structured Data (HSD). The input file must be called -`dftb_in.hsd`. The input file used in this howto looks as follows:: +DFTB+ accepts the input in the Human-readable Structured Data (HSD) format. The +input file must be called `dftb_in.hsd`. The input file used in this example +looks as follows:: Geometry = GenFormat { 3 C @@ -46,9 +51,6 @@ Human-readable Structured Data (HSD). The input file must be called O = "p" H = "s" } - Filling = Fermi { - Temperature [Kelvin] = 0.0 - } } Options {} @@ -120,7 +122,7 @@ geometry should be changed (if at all) during the calculation. If you only would like to make a static calculation, you must either set it to an empty value like :: - Driver = {} # Empty value for the driver + Driver {} # Empty value for the driver or omit the ``Driver`` block completely from `dftb_in.hsd`. @@ -176,8 +178,9 @@ written that will contain the present geometry during the optimisation (and then the final geometry at the end of the calculation). The geometry is written in gen and xyz formats to the files obtained by appending ".gen" and ".xyz" suffixes to the specified name (`geom.out.gen` and `geom.out.xyz` in our case.) -The `dptools` package (distributed with DFTB+) contains scripts to convert -between the gen and the xyz formats (and various other formats). +The `dptools` package distributed with DFTB+ contains scripts (`gen2xyz` and +`xyz2gen`) to convert between the gen and the xyz formats (and various other +formats). Hamiltonian @@ -201,9 +204,6 @@ DFTB Hamiltonian has the following properties:: O = "p" H = "s" } - Filling = Fermi { # No electronic temperature - Temperature [Kelvin] = 0.0 - } } In this example the charge self-consistent DFTB (SCC-DFTB) method is used for @@ -213,7 +213,7 @@ order to find the final ground state of the system it has to iteratively solve the system, until the atomic charges are self-consistently converged. Convergence is reached if the difference between the charges used to build the Hamiltonian and the charges obtained after the diagonalisation of the -Hamiltonian is below a certain tolerance (the default is 1e-4 electrons, but can +Hamiltonian is below a certain tolerance (the default is 1e-5 electrons, but can be tuned with the ``SccTolerance`` option). If this level of convergence is not reached within a certain number of iterations, the code calculates the total energy using the charges obtained so far and stops with an appropriate warning @@ -226,7 +226,7 @@ Slater-Koster files. Those files always describe the interaction between atom pairs. Therefore, you have to specify, for each pairwise combination of chemical elements in your system, the corresponding Slater-Koster file:: - SlaterKosterFiles = { # Specifying Slater-Koster files + SlaterKosterFiles { # Specifying Slater-Koster files O-O = "../../slakos/mio-ext/O-O.skf" O-H = "../../slakos/mio-ext/O-H.skf" H-O = "../../slakos/mio-ext/H-O.skf" @@ -260,10 +260,6 @@ have to use the ``Charge`` option. Similarly, the system is assumed to be spin-unpolarised. You can however use the option ``SpinPolarisation`` to change this standard behaviour. -The ``Filling`` option describes the method to use for filling up the one -electron levels with electrons. Here Fermi-Dirac statistics are used. The -filling functions usually requires further parameters (e.g the temperature). - Analysis -------- @@ -316,9 +312,11 @@ required files (Slater-Koster files, any files included in the HSD input via Slater-Koster files need to be present. In order to run the calculation, you should invoke DFTB+ without any arguments -in the directory containing the file `dftb_in.hsd`:: +in the directory containing the file `dftb_in.hsd`. As DFTB+ writes some useful +output to the standard output (to the screen), it is recommended to save this +output for later investigation:: - dftb+ + dftb+ | tee output Assuming the binary `dftb+` lies in your search path, you should obtain an output starting with:: @@ -424,9 +422,9 @@ Examining the output ==================== DFTB+ communicates through two channels with you: by printing information to -standard output (which you should probably redirect into a file to keep for -later evaluation) and by writing information into various files. In the -following, the most important of these files will be introduced and analysed +standard output (which you should redirect into a file to keep for later +evaluation) and by writing information into various files. In the following, the +most important of these files will be introduced and analysed Standard output @@ -442,7 +440,6 @@ program header:: | Copyright (C) 2017 DFTB+ developers group | |=============================================================================== - |=============================================================================== | | When publishing results obtained with DFTB+, please cite the following | reference: @@ -496,7 +493,7 @@ missing specifications, you should look at the processed input file `dftb_pin.hsd`, which contains the value for all the possible input settings (see next the subsection). -At this point that the DFTB+ code is then initialised, and the most important +At this point the DFTB+ code is then initialised, and the most important parameters of the calculation are then printed out:: Mode: Conjugate gradient relaxation @@ -616,7 +613,7 @@ set:: MaxAtomStep = 0.20000000000000001 AppendGeometries = No ConvergentForcesOnly = Yes - Constraints = {} + Constraints {} } Similarly, in the ``DFTB{}`` block the switch for the orbital resolved SCC, for @@ -658,49 +655,45 @@ a summary of the last SCC cycle and coordinates of any moved atoms:: 2 -0.00000000 -0.26834536 1.47115110 3 0.00000000 -0.26834536 -1.47115110 -Then the net atomic charges for each atom follow (in case of |H2O| showing a -strong electron transfer from the each hydrogen to the oxygen):: +Then the populaton analysis information follows:: + + Total charge: -0.00000000 + + Atomic gross charges (e) + Atom Charge + 1 -0.59261515 + 2 0.29630757 + 3 0.29630757 + + Nr. of electrons (up): 8.00000000 + Atom populations (up) + Atom Population + 1 6.59261515 + 2 0.70369243 + 3 0.70369243 + + l-shell populations (up) + Atom Sh. l Population + 1 1 0 1.73421713 + 1 2 1 4.85839802 + 2 1 0 0.70369243 + 3 1 0 0.70369243 + + Orbital populations (up) + Atom Sh. l m Population + 1 1 0 0 1.73421713 + 1 2 1 -1 1.68107958 + 1 2 1 0 1.17731844 + 1 2 1 1 2.00000000 + 2 1 0 0 0.70369243 + 3 1 0 0 0.70369243 + - Net atomic charges (e) - Atom Net charge - 1 -0.59261515 - 2 0.29630757 - 3 0.29630757 +It shows the total charge of the system and the charges for each atom, followed +by detailed population analyis for each atom, shell and orbital. .. |H2O| replace:: H\ :sub:`2`\ O -Then the energies of the individual electronic levels (orbitals) in both -Hartrees and electronvolts, followed by the occupation of the individual single -particle levels for all of the possible spin channels. For spin unpolarised -calculations (like this one) you will get only one set of values, since the -levels are spin restricted and are twofold degenerate:: - - Eigenvalues /H - -0.84898606 - -0.41433754 - -0.31375444 - -0.25917545 - 0.39926500 - 0.55838451 - - Eigenvalues /eV - -23.10208606 - -11.27469810 - -8.53769263 - -7.05252282 - 10.86455343 - 15.19441557 - - Fillings - 2.00000 - 2.00000 - 2.00000 - 2.00000 - 0.00000 - 0.00000 - -In a collinear spin polarised calculation you would obtain separate values for -the spin up and spin down levels. Then you obtain a count of the total number electrons in the system, and the number of electrons on each atom, each atomic shell of the atoms (s, p, d, etc.) @@ -752,11 +745,12 @@ Mermin free energy instead of the total energy:: Total Electronic energy: -4.1505816095 H -112.9431 eV Repulsive energy: 0.0726436756 H 1.9767 eV Total energy: -4.0779379339 H -110.9663 eV + Extrapolated to 0: -4.0779379339 H -110.9663 eV Total Mermin free energy: -4.0779379339 H -110.9663 eV -Between the two blocks of energy data, the input and output charges at the last -Hamiltonian diagonalisation are shown, so that you can check that no charges get -lost during the calculation. +Between the two blocks of energy data, the input and output electron numbers at +the last Hamiltonian diagonalisation are shown, so that you can check that no +electrons get lost during the calculation. This is then followed by a confirmation that the SCC convergence has been reached in the last geometry step:: @@ -797,10 +791,12 @@ found stored as xyz and gen format in the output files `geom.out.xyz` and band.out -------- -For large systems, and especially for periodic systems with many k-points, it -can become quite difficult to get a good overview of the one electron levels and -their occupations in `detailed.out`. Therefore, an extra file `band.out` is also -created, which contains this information in a more human readable format:: +This file contains the energies of the individual electronic levels (orbitals) +in electronvolts, followed by the occupation of the individual single particle +levels for all of the possible spin channels. For spin unpolarised calculations +(like this one) you will get only one set of values, since the levels are spin +restricted and are twofold degenerate. In a collinear spin polarised calculation +you would obtain separate values for the spin up and spin down levels:: KPT 1 SPIN 1 KWEIGHT 1.0000000000000000 -23.10209 2.00000 diff --git a/docs/basics/index.rst b/docs/basics/index.rst index f281481d..67df0899 100644 --- a/docs/basics/index.rst +++ b/docs/basics/index.rst @@ -1,7 +1,12 @@ +.. _sec-basics: + ########### Basic usage ########### +This part contains recipes for some basic tasks often done with DFTB+. This is +the best place to start, if you are new to the software package. + .. toctree:: :maxdepth: 1 diff --git a/docs/introduction.rst b/docs/introduction.rst index bd6011c0..bf8c2771 100644 --- a/docs/introduction.rst +++ b/docs/introduction.rst @@ -1,3 +1,5 @@ +.. _sec-introduction: + ************ Introduction ************ @@ -5,28 +7,52 @@ Introduction This document is a collection of examples demonstrating the usage of the quantum mechanical atomistic software package `DFTB+ `_. +Before you start +================ + The examples assume that you have the `latest stable version `_ of DFTB+ installed (although many of them may run also with older versions). Additionally they require some parameterisation files (Slater-Koster files), which can be downloaded from `dftb.org `_. -The recipes often only show the relevant part of the input. In order to obtain -the full input and in order to run the examples, you should download the archive +The recipes often only show the relevant parts of the input. In order to obtain +the full input and in order to run the examples yourself, download the archive containing all the inputs of the individual recipes. .. only :: builder_html or readthedocs See :download:`archive with all inputs <_downloads/archives/recipes.tar.bz2>`. -In the various recipes, the directory, where the full self-containing input can -be found within this archive, is indicated in square brackets right after the -section title (e.g. [Input: `recipes/basics/firstcalc/`]). +In each recipe we indicate in square brackets after the section titles the +corresponding directories in the archive, where the self-contained input can be +found (e.g. [Input: `recipes/basics/firstcalc/`]). -After unpacking the archive, you can also automatically download all -Slater-Koster-files needed by the examples by issuing :: +After unpacking the archive, you should download all Slater-Koster-files needed +by the examples by issuing :: ./scripts/get_slakos -in the root folder of the archive. Then you should be able to run each example -by calling ``dftb+`` from the corresponding input folder. +in the root folder of the archive. After this you should be able to run each +example. The `run.sh` scripts in the example folders contain the individual +commands needed to run the full example. + + +Where to start +============== + +The individual chapters are more or less independent from each other, so you may +directly go to the one closest to your interests. However, if you are new to +DFTB+, please make sure to work through the relevant chapters in +:ref:`sec-basics` first. + +The recipes serve the puprose of enabling you to start with a given +functionality of DFTB+ and are, therefore, rather short and focused. Please +always consult also the corresponding sections of the `DFTB+ manual +`_ +for further details and possibilities. + +Please note that the example outputs in the recipes may have been created with +older versions of DFTB+ and may, therefore, differ slightly in their format from +the ones you obtain. The corresponding inputs in the archive should work with +the last stable release of DFTB+ without any changes, though.