General notes on the Examples

The ADF package contains a series of sample runs. 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 ADF and 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 a UNIX type OS is used and a hierarchical structure of directories is assumed.

All sample files are stored in subdirectories under $ADFHOME/examples/, where $ADFHOME is the main directory of the ADF package. There are two main subdirectories in examples/: adf/ for calculations with the molecular code ADF (and related utility programs) and band/ for calculations with the periodic structures code BAND. Each sample run has its own directory (under adf/ or band/ respectively). For instance, $ADFHOME/examples/band/NaCl/ contains an 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 ADFBIN and ADFRESOURCES.
  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
  ADFBIN and ADFRESOURCES in your environment.
  If a parallel (PVM or MPI) 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 $ADFBIN directory, however, you may find
  that the program executables have names 'adf.exe', 'band.exe'.
  There are also files in $ADFBIN 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 Guides (ADF and BAND) 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.