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 first part of each output is an echo of the input (for most of the programs in the package).
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 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/adf/e_HCN/ contains an ADF calculation on the HCN molecule. Each sample subdirectory contains:
A file run: the UNIX script to execute the calculation or sequence of calculations of the example
A file outpt: the resulting output(s) against which you can compare the outcome of your own calculation.
Notes:
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 (scratch) 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.When you run the samples, be aware that they contain rather general rm commands. Starting from the examples in adf2004.01 the rather general rm commands have been replaced with specific rm commands, which makes it less likely that something is removed that you would rather keep. But still take care that nothing is removed that you would rather keep! It is a good idea to use for such tests a safe 'temp' directory that contains no other important stuff. All will be OK if you run them in the directory in which the pertaining sample resides. Be sure to check and understand what will happen if you move and execute them somewhere else.
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. In addition, you may want to create a file $ADFBIN/nodeinfo to specify the maximum number of parallel processes to use for each of the hosts in the virtual parallel machine (hosts not mentioned in this file will have at most one process spawned on them). 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 copied automatically (by the program itself) to the tail of standard output.
General remarks about comparisons:
For technical reasons, the 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 indeed exceed significantly 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.
An ADF 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.
Survey of the Examples
The Survey of Applications follows a survey of the main application topics with references to related sample runs is given. A sample run usually involves several calculations, for instance a few CREATE runs (with ADF), then a molecular calculation (also ADF), and finally a NMR calculation (with the NMR program) to compute chemical shifts. The samples are identified in this documentation by the name of the directory they reside in. All such names start with 'e_'. The samples are indicated by these directory names, however with the 'e_' prefix omitted. For instance, GO_H2O refers to the directory e_GO_H2O/ (in $ADFHOME/adf/), where in this case GO stands for Geometry Optimization.
