Examples
********


Introduction
============

The ADF package contains a series of sample runs for the BAND program.
Provided are UNIX scripts to run the calculations and the resulting
output files.

The examples serve:

* To check that the program has been installed correctly: run the
  sample inputs and compare the results with the provided outputs.
  *Read the remarks below about such comparisons.*

* To demonstrate how to do calculations: an illustration to the User
  manuals. The number of options available in BAND is substantial and
  the sample runs do not cover all of them. They should be sufficient,
  however, to get a feeling for how to explore the possibilities.

* To work out special applications that do not fit well in the User's
  Guide.

Where references are made to the operating system (OS) and to the file
system on your computer the terminology of UNIX type OSs is used.

All sample files are stored in subdirectories under
$AMSHOME/examples/, where $AMSHOME is the main directory of the ADF
package. The main subdirectory for the BAND examples is
$AMSHOME/examples/band. Each sample run has its own directory. For
instance, $AMSHOME/examples/band/NaCl/ contains a BAND calculation on
the NaCl bulk crystal. Each sample subdirectory contains:

* A file TestName.run: the UNIX script to execute the calculation or
  sequence of calculations of the example

* A file TestName_orig.out: the resulting output(s) against which you
  can compare the outcome of your own calculation.

Notes:

* Running the examples on Windows: You can run an example calculation
  by double-clicking on the appropriate .run file.  After the
  calculation has finished, you can compare the TestName.out file with
  the  reference TestName_orig.out file. See remarks about comparing
  output files below.

* The UNIX scripts make use of the *rm* (remove) command. Some UNIX
  users may have aliased the *rm* command. They should accordingly
  adapt these commands in the sample scripts so as to make sure that
  the scripts will remove the files. New users may get stuck initially
  because of files that are lingering around after an earlier attempt
  to run one of the examples. In a subsequent run, when the program
  tries to open a similar (temporary or result) file again, an error
  may occur if such a file already exists. Always make sure that no
  files are left in the run-directory except those that are required
  specifically.

* It is a good idea to run each example in a separate directory that
  contains no other important files.

* The run-scripts use the environment variables AMSBIN and
  AMSRESOURCES. They stand respectively for the directory that
  contains the program executables and the main directory of the
  database.  To use the scripts as they are you must have defined the
  variables AMSBIN and AMSRESOURCES in your environment. If a parallel
  version has been installed, it is preferable to have also the
  environment variable NSCM. This defines the default number of
  parallel processes that the program will try to use. Consult the
  Installation Manual for details.

* As you will note the sample run scripts refer to the programs by
  names like 'adf', 'band', and so on. When you inspect your $AMSBIN
  directory, however, you may find that the program executables have
  names 'adf.exe', 'band.exe'. There are also files in $AMSBIN with
  names 'adf', 'band', but these are in fact scripts to execute the
  binaries. We strongly recommend that you use these scripts in your
  calculations, in particular when running parallel jobs: the scripts
  take care of some aspects that you have to do otherwise yourself in
  each calculation.

* You need a license file to run any calculations successfully. If you
  have troubles with your license file, consult the Installation
  manual. If that doesn't help contact us at support@scm.com

Many of the provided samples have been devised to be short and simple,
at the expense of physical or chemical relevance and precision or
general quality of results. They serve primarily to illustrate the use
of input, necessary files, and type of results. The descriptions have
been kept brief. Extensive information about using keywords in input
and their implications is given in the User's Guide and the Utilities
and Property Programs documents (NMR, DIRAC, and other utility
programs).

When you compare your own results with the sample outputs, you should
check in particular (as far as applicable):

* Occupation numbers and energies of the one-electron orbitals;

* The optimized geometry;

* Vibrational frequencies;

* The bonding energy and the various terms in which it has been
  decomposed;

* The dipole moment;

* The logfile. At the end of a calculation the logfile is
  automatically appended (by the program itself) to the standard
  output.

General remarks about comparisons:

* For technical reasons, discussion of which is beyond the scope of
  this document, differences between results obtained on different
  machines, or with different numbers of parallel processes, may be
  much larger than you would expect.  They may significantly exceed
  the machine precision. What you should check is that they fall well
  (by at least an order of magnitude) within the *numerical
  integration* precision used in the calculation.

* For similar reasons the orientation of the molecule used by the
  program may be different on different machines, even when the same
  input is supplied. In such cases the different orientations should
  be related and only differ in some trivial way, such as by a simple
  rotation of all coordinates by 90 degrees around the z-axis. When in
  doubt, contact an ADF representative.

* A BAND run may generate, apart from result files that you may want
  to save, a few scratch files. The UNIX scripts that run the samples
  take care of removing these files after the calculations have
  finished, to avoid that the program aborts in the next run by
  attempting to open a 'new' file that is found to exist already.

* A sample calculation may use one or more data files, in particular
  *fragment* files. The samples are self-contained: they first run the
  necessary pre-calculations to produce the fragment files. In
  'normal' research work you may have libraries of fragments
  available, first for the 'basic atoms', and later, as projects are
  developing, also for larger fragments so that you can start
  immediately on the actual system by attaching the appropriate
  fragment files.

Default settings of print options result in a considerable amount of
output. This is also the case in some of the sample runs, although in
many of them quite a bit of 'standard' output is suppressed by
inserting applicable print control keys in the input file. Consult the
User's Guide about how to regulate input with keys in the input file.


Model Hamiltonians
==================

* Example: Spin polarization: antiferromagnetic iron

* Example: Applying a Magnetic Field (S . B)

* Example: Applying a Magnetic Field (L . B)

* Example: Graphene sheet with dispersion correction

* Example: H on perovskite with the COSMO solvation model

* Example: Applying a homogeneous electric field

* Example: Finite nucleus

* Example: Fixing the Band gap of NiO with GGA+U

* Example: Hubbard combined with spin flip

* Example: Fixing the band gap of ZnS with the TB-mBJ model potential

* Example: DFT-1/2 method for Silicon


Precision and performance
=========================

* Example: Convenient way to specify a basis set

* Example: Tuning precision and performance

* Example: Multiresolution

* Example: BSSE correction

* Example: Speed up SCF during geometry optimization


GTO
===

* Example: eigenvalue-only self-consistent GW@PBE calculation: Ne with
  GTO type basis set


Restarts
========

* Example: Restart the SCF

* Example: Restart SCF for properties calculation

* Example: Properties on a grid

* Example: DOS and BandStructure from a previous calculation


NEGF
====

* Example: Main NEGF flavors

* Example: NEGF with bias

* Example: NEGF using the non-self consistent method


Structure and Reactivity
========================

* Example: NaCl: Bulk Crystal

* Example: Transition-State search using initial Hessian

* Example: Atomic energies

* Example: Calculating the atomic forces

* Example: Optimizing the geometry


Time dependent DFT
==================

* Example: TD-CDFT for MoS2 Monolayer (NewResponse)

* Example: TD-CDFT for Copper (NewResponse)

* Example: TDCDFT: Plot induced density (NewResponse)

* Example: TD-CDFT for bulk diamond (OldResponse)


Spectroscopy
============

* Example: Hyperfine A-tensor

* Example: Zeeman g-tensor

* Example: NMR

* Example: EFG

* Example: Phonons


GW
==

* Example: eigenvalue-only self-consistent GW@PBE calculation: H2O

* Example: eigenvalue-only self-consistent GW@PBE calculation: Ne with
  GTO type basis set


Analysis
========

* Example: CO absorption on a Cu slab: fragment option and densityplot

* Example: Grid key for plotting results

* Example: H2 on [PtCl4]2-: charged molecules and PEDA

* Example: CO absorption on a MgO slab: fragment option and PEDA

* Example: CO absorption on a MgO slab: fragment option, PEDA and
  PEDANOCV

* Example: Bader analysis

* Example: Properties at nuclei

* Example: Band structure plot

* Example: Effective Mass (electron mobility)

* Example: Generating an Excited State with and Electron Hole

* Example: LDOS (STM) for a BN slab


List of Examples
================

* BasisDefaults

* BeO_tape41

* BetaIron

* BField

* BFieldLdotB

* BNForce

* BSSE

* COChainFreqTS

* EffectiveMass

* EField

* FiniteNucleus

* Frags_COCu

* Graphene_Dispersion

* GraphenePhonons

* GridKey

* H2BulkGeo

* H_ref

* HonPerovskite_Solvation

* Li2O_Bader

* Li_BZPlot

* Multiresolution_H2O

* NaCl

* NEGF

* NEGF with bias

* NEGF_Conductance

* NewResp_3DCopper

* NewResp_PlotInducedDensity

* NewResponse for 2D Slab

* NiO_Hubbard

* HubbardInputOptions

* OldResp_Diamond

* PE-NMR

* PEDA

* PEDANOCV

* Peptide_NumericalQuality

* PropertiesAtNuclei

* Restart a SCF

* Restart for Properties

* Si_ElectronHole

* SnO_EFG

* TiF3a

* TiF3g

* ZnS_ModelPotential

* GW QP calculation for H2O

* GW QP calculation for Ne with GTO type basis set
