ADF-GUI Reference Manual

Table of Contents

Introduction

This document will provide a basic reference manual of the ADF-GUI. ADF-GUI is the Graphical User Interface for the ADF package.

If you are new to the ADF-GUI we advise you to read (and try) the ADF-GUI tutorials before reading this reference manual.

Primary author of the ADF-GUI: O. Visser

Artwork: M. Luppi, www.wrinklypea.com

Other contributors: E. van Lenthe, A.L. Yakovlev, W.J. van Zeist

The ADF-GUI modules

The ADF-GUI consists of several modules:

ADFjobs

This utility ($ADFBIN/adfjobs) manages your ADF jobs: run a job on your local machine or on remote machines. It also serves as a interface to all files belonging to your job, and it servers as a convenient launcher of the other ADF-GUI modules.

ADFinput

A utility program ($ADFBIN/adfinput), which enables ADF users to easily create ADF jobs. You can use ADFinput to define your molecule (geometry), pre-optimize it, and to set details of your ADF job using an easy-to-use graphical user interface. ADFinput will generate the complete job script for you. This script takes care of running ADF and property programs as required.

ADFview

A simple program ($ADFBIN/adfview) that displays volume data, such as electron densities, orbitals, electrostatic potentials and more.

ADFmovie

This program ($ADFBIN/adfmovie) follows geometry steps as performed by ADF during geometry optimizations, IRC calculations, etc. Actually, it will display just any series of changing geometries, and is also used to display normal modes calculated with a frequency calculation.

ADFlevels

This program ($ADFBIN/adflevels) generates a diagram showing the energy levels of a finished calculation. You can interact with it: show an interaction diagram (how the molecular orbitals are constructed from fragment orbitals), show labels, occupations, orbitals, etc.

ADFspectra

This program ($ADFBIN/adfspectra) the spectra calculated by ADF. It can show IR, Raman, excitation and CD spectra, as well as a DOS plot. For some spectra it can also provide additional information, like a visualization of the normal modes or orbitals.

ADFtail

A minor ADF-GUI utility ($ADFBIN/adftail) that will just show the contents of a text file, updating when the text file grows (like the UNIX tail -f command). It is used to monitor the 'logfile'. The progress of an ADF calculation is always written to this file.

BOB

A Basic Output Browser ($ADFBIN/bob) for the output generated by ADF.

The SCM (logo) menu

All ADF-GUI modules have the SCM menu on the left-hand side, on most systems represented by a small SCM logo. You can easily switch between the different modules of the ADF-GUI using this menu:

• Input: activate ADFinput
• Levels: activate ADFlevels
• View: activate ADFview
• Spectra: activate ADFspectra
• Movie: activate ADFmovie
• Logfile: activate ADFtail
• Output: activate BOB
• Close: close all ADF-GUI modules for the current or (in ADFjobs) selected, calculation
• Close All: close all ADF-GUI modules at once
• Jobs: activate ADFjobs

When you use the SCM menu while some file is connected to the current ADF-GUI module, the selected ADF-GUI module will be activated showing data belonging to the same calculation. The title bar of any ADF-GUI module shows which file is connected, if any. Thus, you can easily switch between viewing the logfile, output, input, orbitals, etc, all belonging together.

When you use the SCM menu when no file is connected (the title bar just shows the name of the module), the selected ADF-GUI module will be started without file.

On most platforms you can tear off the SCM menu by selecting the dashed line at the top of the menu.

Automatic bug reports

Please enable the automatic mailing of bug reports. These reports contain detailed information about the internal state of the ADF-GUI module having some problem, but do not contain personal information. Information about the structure of your molecule is included.

You can enable this by setting the global environment variable SCM_ERROR_MAIL, for example in your login script:

SCM_ERROR_MAIL=errors@scm.com
export SCM_ERROR_MAIL

This will ensure that the bug report will be sent to the e-mail address you specify. If you specify your own e-mail address you can see exactly what kind of information is contained in the error report.

Your comments and bug reports are very welcome. Please send them to support@scm.com, or use the 'Feedback' menu command from the 'Help' menu of the ADF-GUI modules.

Environment Variables

The ADF-GUI is normally installed as part of the ADF package. In the following table the environment variables that are specific for the ADF-GUI are listed:

Mouse Interaction

Rotate, Translate and Zoom

In the modules that provide a 3D view of your molecule (currently ADFinput, ADFview, ADFmovie) you can rotate, translate and zoom using the mouse.

Drag with the mouse: press a mouse button, and move it while holding it down. A one-button mouse button is the same as a Left mouse button. Which mouse button, and which modifier key you press at the same time, determines what will happen:

Rotate	Left
Rotate in-plane	Ctrl-Left
Translate	Middle, or Alt-Left
Zoom	Right, or Command-Left (drag up or down)

The rotate, translate and zoom operations change how you look at the molecule. They do not change the coordinates. When you Right or command-Left without dragging the mouse, a pop-up menu will appear.

In ADFinput operating with the mouse on the selection will move the selection only. In that case the geometry of your molecule (and thus the coordinates) will change. Zooming the selection will move it perpendicular to the screen. You operate on the selection by starting the drag operation with the mouse above a selected object.

In the View menu you can select either 'Mouse as trackball' or 'Mouse as joystick'. If 'Mouse as trackball' is selected, you need to drag with the mouse (move the mouse with a button pressed down). If 'Mouse as joystick' is selected you just need to press and keep the button pressed down. The direction of movement etc will depend on the position of the mouse with respect to the center of the 3D view area. Note that 'Mouse as joystick' disables some pop-up menus.

Selecting

In the modules that provide a 3D view of your molecule (currently ADFinput, ADFview, ADFmovie) you can make selections using the mouse.

Click on an object: make a new selection with it

Click in space: clear selection

Shift-Click on object: add or remove it from the selection

Shift-Drag in space: add all objects within the rectangle to the selection

Pop-up menus: Select all similar elements or all bonds by using the pop-up menus

In some modules there are additional ways to select objects using menu commands. Furthermore, one can select atoms from the list in the coordinates window.

Shared Menus

Pop-up menus

In many cases pop-up menus are attached to objects (atoms, bonds, empty space, peaks, levels, ...) that allow you to do something with that particular object. To get the pop-up menu (a one-button mouse button is the same as a Left mouse button):

Press and hold the Right mouse button on the object: the pop-up appears almost directly.

Press and hold the Left mouse button on the object: the pop-up appears after a small delay.

ADFinput, ADFmovie and ADFview share the following pop-up menu commands, note that some programs extent the pop-up menu with some additional commands:

Pop-up menu on atom X

Atom Info: name, charges etc.

Select what info per atom to show. The atom name, and possibly some other things. To hide the info, use the "Hide Info" command.

When a .t21 result file is open in ADFview or ADFmovie, some scalar properties might be available. For example, you can show the Mulliken Charge in that atom info label, some other atomic charge, or the electrostatic potential at the nucleus. The list of available properties will automatically be constructed, depending on the kind of information in the result file.

Geometric Info

Depending on the number of atoms selected, subcommands are available to show distances and angles, or to hide them.

Info Style

Select the size and colors of the Atom Info labels.

Atom Radius

Make the radius of the selected atom(s) bigger or smaller, for display purposes only.

Define X color

Select what color to use for all atoms of type 'X'.

Store default X color

Set the currently active color for atom type 'X' as default color. The next time you start ADFinput, ADFview or ADFmovie this color will be used.

Hide all X atoms

Hide all atoms of type 'X'.

Select all X atoms

Select all atoms of type 'X'.

Pop-up menu in empty space

Atom Info

Select what info per atom to show. The atom name, and possibly some other things like charges. To hide the info, use the "Hide Info" command.

Geometric Info

Depending on the number of atoms selected, subcommands are available to show distances and angles, or to hide them.

Info Style

Select the size and colors of the Atom Info labels.

Show bonds to hidden atoms

If you hide some atoms, for example the hydrogen atoms, the bonds to these atoms may still be hidden. Use this command to show those bonds.

Hide bonds to hidden atoms

If you hide some atoms, for example the hydrogen atoms, the bonds to these atoms may still be visible. Use this command to show those bonds.

Default atom properties

Reload the default atom properties (colors, hidden etc) as stored in the preferences for the ADF-GUI.

View Menu

The 'View' menu is also shared by ADFinput, ADFmovie and ADFview. It will contain at least the following commands (note that some programs might extend the 'View' menu with other commands):

Reset View

When you use the 'Reset View' menu command, the translation, zoom and rotation settings will be adjusted such that the entire molecule is visible. The center of your molecule will be the new rotation center.

Use it for example when you translate the molecule 'out of view'.

Fly to selection

Zoom to the center of the current selection (or of the whole molecule if nothing is selected). The zooming occurs 'real life', as if you are flying to that point. The zoom point will be the new center of rotation.

Align screen

First select three atoms defining a plane (thus, not three atoms on a line ...).

Next, use the 'Align Screen' command to rotate your molecule such that the plane defined is parallel to the screen.

Mouse as

Determine how your mouse works:

Trackball: you rotate etc by dragging around the screen. This is the default, and most intuitive, mode.

Joystick: you rotate etc by pressing down a mouse button off-center, and keep it pressed down. Your molecule will rotate, translate etc in the direction of your mouse button (with respect to the center of the drawing area). Since the press-and-keep-down conflicts with pop-up menus, they will be disabled.

Anti-alias

Use the anti-alias technique to improve the quality of the pictures. Especially sharp edges will look smoother.

It works very well, but is rather time-consuming to calculate. As a result everything will be very very slow. For that reason we advise you to first increase the resolution of the picture to be saved. Next, only when you want to prepare an extremely high-quality picture for a presentation (and have plenty of time ...), you might in addition turn on anti-aliasing.

As anti-aliasing works my mixing in the background color to get smooth edges, you cannot change the background color in a saved picture. If you would wish to do so (for example, make the background transparent), you should not use anti-aliasing.

Molecule Resolution

Set the resolution of the molecule display (the number of triangles used to represent the atomic spheres and the bonds). If you have a big molecule and a low-end graphics card you can speed up display by choosing 'Low'. For high-end graphic cards you might not see a significant difference.

Molecule Ball & Sticks

Change the size (radii) of the balls and sticks used to display the molecule. Note the convenient shortcuts (control - and control +, or command - and command +).

Show Bondtype

If checked, the different bond types will be visually shown (single, double, triple and aromatic bonds). If unchecked, all bonds will be shown as simple 'single' bonds.

Background

Select the color of the background.

ADF-GUI modules

ADFjobs

Introduction

ADFjobs is a utility program ($ADFBIN/adfjobs), which enables ADF users to easily manage their ADF (and other) jobs. You can use ADFjobs to keep an overview of your jobs, to quickly access old jobs, to run jobs locally and remote, and keep track of running jobs. Finally, it provides a convenient launcher of the other ADF-GUI modules.

Thus it is a mixture between a file manager, a job manager and a launcher.

Important: to use ADFjobs with remote machines, you need to set up ssh first. You should take care to configure things such that you do not need to type a password when you access your remote machine. To do this you need to create keys, you need to run an ssh agent, and you need to add your public key to the authorized_keys file on the remote machine. For more information, consult your ssh documentation or one of the many guides on the internet.

Starting ADFjobs

If you have installed the ADF package correctly, the adfjobs command is located in $ADFBIN.

If $ADFBIN is included in your PATH environment variable, you can start the ADFjobs program with the following command:

adfjobs [dirname]

The dirname is optional, ADFjobs will use the current directory when nothing is specified.

An alternative method to start ADFjobs: select the Jobs command from the SCM menu, or use the Run command in ADFinput. ADFjobs will always start automatically when needed.

If you are using a MacOS X, you can start ADFjobs from the Launcher.

Under windows you can start ADFjobs by double-clicking the icon on the desktop.

File and Job listing

ADFjobs has one main window that displays a list of jobs. A job is actually any file, and ADFjobs groups files together to what ADFjobs considers 'jobs'. One job is a set of files with identical names except for their extension. In the job list you see this common name.

Job elements

For each job the following is presented, from left to right:

Job icon

Job details toggle

Job name

Queue name

Run options

Status icon

The job icon tells you what kind of job it is: ADF, BAND, some other script that you can run, or something unknown. The icons also come in two main versions. Depending on the style, blue and gray, or blue dot and black cross. The 'blue' icons signal 'runnable' jobs, that is, jobs that contain a file with a .run extension. ADFjobs assumes that this is some kind of shell script, and that it can run this script (either on the local or on some remote machine). Gray jobs are not runnable, no .run file is present.

The job details toggle is a button that you can click to show or hide more details about the job: Job details, Local files and Remote files. Each of the three sections may be open or closed, you can again click on the corresponding triangle to toggle this state.

The job name is just the name of the group of files without the extension.

The queue name is the name of the queue that you have set for this particular job, if any. If you select a queue from the Queue menu, that will specify the queue name here. You can also edit this name, but only when you are changing the job details for this job.

The run options is a text field that you can use to specify some details to run a job. For example, a time limit or the number of CPUs to use. The meaning depends on the Run command specified with the Job Details.

The status icon tells you if the job is a new, queued, running, ready or terminated.

Selecting

You can select one or more jobs with:

left click - select that job

shift left click - select a range of jobs

right click (or control left click) - toggle that job to be selected or not selected

click on the search icon - clear the selection

Note that the SCM menu depends on the selected job: if an ADF job is selected, the ADF-GUI modules will be shown. If a BAND jobs is selected, the BAND-GUI modules will be shown. If nothing is selected, all modules will be shown.

Changing directories, open a job, change a job name

If ADFjobs finds directories in the current directory it will show them, with a folder icon. To change into a directory, just click once on the folder icon. The icon with directory name ".." means the parent directory (one up in the tree structure).

If you open a job, by a double click (most conveniently, double click on the Job icon) it will be loaded in another ADF-GUI module. If a job is running, the logfile will be shown, otherwise ADFinput or BANDinput will be used to display the job.

To change the name of a job, just click on the job name while the job is selected. It will become editable. When you change it, all local AND remote files will be renamed to match the new name of the job.

Filtering

You can select what exactly will be shown in this window with the Filter menu. Also, you can change the order using the Sort menu. Finally, by typing text in one (or both) of the fields at the bottom, next to the magnifier glass, you will filter out only those jobs that match the text (job name or queue name) that you type. This is very convenient if you have a directory in which you have collected many jobs.

Job details

When you run a job, a number of details need to be known. Such as the machine were you wish to run, and more. The job details section collects all this information and shows it to the user. If you select a particular queue from the Queue menu, the job details will be reset to the proper values as defined for that queue. However, you can override them by changing them afterwards for a particular job. You can also change the name of queue shown with the job information, click on the name to do this. The information is stored in the .pid file from the job.

Remote host

Name of the machine on which you wish to run your job. You should be able to connect to that machine using ssh, and the name as specified. If you wish to run on your local machine, leave this field empty or specify localhost.

Remote user

The username that you need to specify in the ssh command, if any. Typically, this is your username on the remote machine.

Remote job directory

On the remote machine, ADFjobs needs to set up your input files and run script, and needs to collect the results. For that purpose ADFjobs will make its own directories within the directory you specify. A typical value would be something like $HOME/jobs.

Run command

The command on the remote machine to be executed. In this command, $job will be replaced by the full path to your job script on the remote machine. Also, $options will be replaced by the contents of the Run options field. Typically this will be used to specify the number of CPUs, a time limit, or a batch queue name.

To run interactively, just enter "$job". To submit your job to a queue, specify the submit command (for example, qsub). Several examples may be found in the preconfigured queues.

Kill command

The command to use to kill a queued or running job. In this command $pid will be replaced by the process id or the job id, as determined when starting the job. For interactive jobs, killall $pid should work fine.

Job status command

This command will be used to determine if a job is still queued or running. If a job is no longer queuer or running, it should return an empty string. Anything else will server as indication that the job is alive. For interactive jobs ps -p $pid | grep $pid works fine.

System status command

The command to use to determine the system status. This might be uptime, or some qstat command for batch systems.

Prolog command

The command to execute at the beginning of the job script. Typically, this will be used to set up the environment properly. For example, you would source a script file to set all environment variables for ADF like ADFHOME, ADFBIN etc. This is especially important if you are working with different versions of ADF at the same time.

Epilog command

This is the command to run at the end of the job script. You can use it to copy save result files, or to perform some cleanup action.

Logfile extension

The extention for the logfile, should normally be logfile. If you use ADFjobs for other programs than ADF, you could specify a different value to monitor the progress of your other program.

Local files

The local files section lists all files that ADFjobs found. They all have the same name (the name of the job), and different extensions. Here you can see what files belong to a job, including modification date and time, and the size of the files. Double clicking on some of the extensions might open that particular file, depending on your operating system.

Remote files

This is a similar list of files as the local files list, but these files reside on a the remote machine as specified in the job details. If you are preparing a new calculation it will be empty. When a calculation is complete, it will show all the result files on the remote machine.

At the top of the list the name of the directory in which the files live on the remote machine is shown.

Change job name

To change the name of a job, just click on the job name while the job is selected. It will become editable. When you change it, all local AND remote files will be renamed to match the new name of the job.

Queues

A queue within ADFjobs is just a short-cut to set all job details for some selected job. In the Queue menu you see a list of defined queues. Selecting one of them means changing the job details from all selected jobs as defined in this particular queue.

You can define a queue in several ways: new (based on one of the included example queues), new (based on the job details settings from the selected job), or by editing an existing queue. One of the queues is the default queue: if you are going to run a job without setting the job details (either by specifying a queue, or by filling out the details by hand), ADFjobs will suggest to run the job in the default queue.

The simples queue is a local interactive queue. This is just called 'interactive' in the supplied examples. Normally, you will not need to make any changes to this. When you run ADFjobs for the first time, and it does not find any queues, it will automatically create one such queue for you.

Next is a remote interactive queue. Use the same settings as for the Interactive queue, except that you specify some remote machine (and optionally a remote user).

Finally, a queue might be configured such that your job ends up in some batch queue. For this to work, you need to use some submit command. Details for these commands differ very much depending on your batch system and its configuration. ADFjobs comes with some examples for LSF, PBE and SGE batch systems. You will need to change the commands to match the submit command you are supposed with your batch system.

When running a job, ADFjobs uses the information specified with Job Details to figure out the run command. Part of this might be the '$options' variable. This will be replaced by whatever the user puts in the input field to the right of the queue name (just before the job status). Thus, you can define one queue and use this field to specify a time limit, or the number of CPUs to use, or whatever else you wish.

Menu commands

File menu

New Directory

Make a new directory. It will always have the name 'Untitled'. You can change the name by clicking twice on the name (or once if it is already selected), and typeing the new name.

Delete Directory

Delete the selected directory. It must be empty before you can do this.

Preferences

Bring up a preferences dialog box. In it you can specify the following defaults:

Local ssh command

The command you need to enter on your local machine to use the ssh command. Normally 'ssh' will be correct, but you might need to specify a full path, or the name of some other ssh program.

Local hostname

The name of your local host. It will default to a reasonable value, and you should probably not change it. It is specified here to handle mobile computers that change their name when connected to a different network. That will confuse ADFjobs, one single name should be choosen.

Timeout for remote commands

ADFjobs uses a lot of remote commands to get information about running jobs and so on. If network problems occur, or when a remote machine has some trouble, these commands will time out to so that ADFjobs can continue to work (with other hosts of course ...). If you have a slow network, or slow remote machines, you might want to specify a longer time out than the default 5 seconds.

When job starts running, show logfile

If you check this item, ADFjobs will show the logfile for any job that starts running. This is convenient to follow a job, but you might consider this to be interfering with other activities too much. Uncheck it to prevent this feature. You can always show the logfile of a job using the Logfile command from the SCM menu. When a job is still running, double clicking on the job icon will also show the logfile.

Run command checks that queue exists

When running a job, ADFjobs checks that the queue still exists in the Queue menu. Since all information is stored with the job, you can in principle still run even if the queue is no longer defined.

Run command checks that Job details match the queue

When running a job, ADFjobs checks that the job details are identical to those defined for the matching queue. Thus you will be warned if you made changes to the job details in the job, or if you redefined the queue.

Status window auto-refresh

When checked, the status window refreshes automatically after 5 minutes. If not checked, it refreshes by using the Status command from the Job menu, or by pressing Return when the status window is on top.

Quit

Quit ADFjobs. Note that ADFjobs takes care of updating logfiles from running jobs, so if you close ADFjobs these files will not be updated automatically any more.

Edit menu

This menu contains the usual menu command for text editing. The commands work only for text editing, not for anyting else.

Job menu

Run

Run the selected job. If no queue has been specified, ADFjobs will propose to use the Default queue.

Kill

Stop a running job, or remove it from the queue if queued with a batch system.

Transfer To Remote

Transfer all files belonging to this job to the remote machine. Normally you do not need to do this manually, ADFjobs transfers the files that are needed automatically.

Transfer From Remote

Transfer all files belonging to this job from the remote machine to the local machine. Normally you do not need to do this manually, ADFjobs transfers the files that are needed automatically.

Delete

Delete all files belonging to the selected job, locally and possibly remotely (ADFjobs will ask for this).

Delete Remote

Delete all files belonging to the selected job, on the remote machine only. You typically will use this to clean up on the remote machine.

Generate Test Job

Generate a job script that you can execute to verify your ADF set up. It checks environment variables, license and more. You can study the output to get an idea of what the problem is (if any). Alternatively, SCM support might ask for this output in case of problems.

Reset

Remove all job information as added by ADFjobs. Normally never needed, it is an indication of a bug in ADFjobs ...

Queue menu

New...

Create a new predefined queue. You can select from one of the included templates, and modify it as needed.

New From Job

Create a new queue based on the information as specified with a job. The queue name will be the queue name as specified with the job details in the job.

Edit...

Select an existing queue using the submenu, and change it as required.

Delete

Delete the queue you select using the submenu.

Set Default

Use the submenu to set the default queue to use when the user uses the Run command and no queue (or job details) has been set yet.

Status

Show the status window, collecting the information from the System Status commands as defined for all queues. Status pertaining to the same host is grouped together for easier reading.

Queue name

A list of queues that you have defined. If you select one of them, its settings will be applied to the selected job.

Sort menu

Define the sort order to be used while displaying jobs. Directories will always be shown first. Time is the last modification time of any of the files that make up a job. The other sort fields should be evident ...

Filter menu

Limit the kind of jobs (and directories) shown in the job list. Checked items will be visisble.

Style menu

Select the graphical style for ADFjobs (icons, colors and fonts). You can also change font details such as the font size.

ADFinput

Introduction

ADFinput is a utility program ($ADFBIN/adfinput), which enables ADF users to easily create ADF jobs. You can use ADFinput to define your molecule (geometry), pre-optimize it, and to set details of your ADF job using an easy-to-use graphical user interface. ADFinput will generate the complete job script for you. This script takes care of running ADF and property programs as required. You can also use ADFinput to run these script files, though the actual running is handled by ADFjobs.

Starting ADFinput

If you have installed the ADF package correctly, the adfinput command is located in $ADFBIN.

If $ADFBIN is included in your PATH environment variable, you can start the ADFinput program with the following command:

adfinput [filename]

The filename is optional. ADFinput only handles files that were created by ADFinput before (which have a .adf extension) and PDB files (with .pdb extension).

An alternative method to start ADFinput: select the Input command from the SCM menu, or use ADFjobs to start ADFinput.

If you are using a MacOS X, you can start ADFinput from the GUILauncher.

Under windows you can start ADFinput by double-clicking the icon on the desktop.

Menu Commands

File menu

New

Same as quitting ADFinput and starting again without specifying a file name.

Open...

Open an existing ADFinput file or PDB file (with .adf or .pdb extension).

When you open a .adf file, and a matching and newer .t21 is found that contains changed coordinates, ADFinput will ask you if you wish to update the coordinates in the .adf file to match the .t21 file. You can use this, for example, to update your geometry after running a geometry optimization. Note that the .t21 might just contain the same molecule but reoriented to obey the symmetry requirements of ADF.

Import Coordinates...

Use this menu command to import the geometry of your molecule from file.

You can import coordinates from a .t21 file generated by ADF, from a .adf file as saved by ADFinput, or from a text file (for example, a .mol, a .xyz or a .pdb file).

If you import coordinates from a .t21 file note that the extension must be .t21. A name like 'TAPE21' will not work. Bond information will only be present when the .t21 file has been created using the ADF-GUI, version 2006 or later. If no bond information is not present, just the coordinates are imported and bonds will be guessed (and no distinction will be made between different kinds of bonds).

Importing from a .adf file is straight-forward: both coordinates and bond information is present so you will get exactly what you saved.

Importing from a .mol file will also give you both the coordinates and bond information contained in the file.

Importing from a text file is rather flexible: ADFinput needs three real numbers next to each other. These will be interpreted as x, y and z coordinate. One additional integer or the abbreviation of an element is also needed to identify the kind of atom.

To be recognized as real, the real number must contain a '.' (dot), and at least one digit before or after the dot. Real numbers with exponents (E or D) are not recognized.

If an integer is used to specify the element (the nuclear charge), it may not contain a '.' (dot).

Bond information is not imported, even if present in your file (unless importing from a .adf file or a .t21 file). After you have imported some coordinates, ADFinput tries to guess the bonds between the imported atoms. This might not be very accurate.

Z-matrix import (internal coordinates) is currently not available.

Directly after the 'Import Coordinates...' command the newly imported atoms are selected. This makes it easy to reposition them with respect to other atoms that may already be present, remove the automatically guessed bonds, or use other operations on the newly imported atoms and bonds.

Export Coordinates...

Export the current geometry as a simple space separated list of element name and xyz coordinates. The number of lines will match the number of atoms, with two additional header lines. The first header line contains the number of atoms, the second line will be empty. This might change in the future. No bond information is written to the text file.

You will be prompted to specify a file name.

Save

Save the current state of what is present in ADFinput. If you have not saved before, ADFinput will ask you to specify a file name.

Not only the .adf file will be saved, but also a matching .run file which is a run script corresponding to your input. If you are performing a fragment analysis also .adf files and run scripts for the fragments will be saved.

Save As...

Save the current state of what is present in ADFinput in a file with a name of your choice.

Not only the .adf file will be saved, but also a matching .run file which is a run script corresponding to your input. If you are performing a fragment analysis also .adf files and run scripts for the fragments will be saved.

Revert...

After opening a .adf file with ADFinput and making some changes, you can use the 'Revert...' command to undo all your changes. It is the same as quitting without saving, and opening the same file again.

Save Picture...

Save a picture of your molecule (only the drawing area with your molecule, no input options) in a file.

The format used to save your picture is determined by the extension of the file name you specify. If you do not specify a known extension, it will use the standard picture format as specified using the 'Default Picture Format' menu.

Default Picture Format

Use the submenu to select the format to use when saving a picture.

Note that this is just the default to use, the user specifies the format with the extension. When the extension is not recognized (or when no extension is specified) the default format will be used.

Picture Resolution

Use the submenu to select the resolution to use when saving a picture.

Run

Start ADF and / or property programs as selected in all the input options.

This is done by telling ADFjobs to run this job. If you have made changes in ADFinput, you will first be asked to save the changes. Just as the Save menu command, this will also save the run script (with the .run extension). Next your job is run by ADFjobs. Details will depend on your ADFjobs setup.

When a run is finished, if you still have the matching ADFinput window open, you will be asked if you wish to update the coordinates of your molecule with the most recent set of coordinates from the finished calculation. You can use this, for example, to import an optimized geometry.

Note: the run script has been made considerably simpler with respect to the 2006 release and older.

Preferences...

The Preferences... menu command gives access to the 'Preferences' input panel. You may also select this panel from the pull-down menu on top of the input panels.

This panel is used to set a number of preferences for the ADF-GUI, not only for ADFinput.

To save the preferences, click on the Save button in the Preferences panel.

Quit

Stop ADFinput, ask you to save changes if you made any.

Edit menu

Undo

Undo the last operation. It uses a stack of many operations, so you can use the Undo command repeatedly.

Redo

If you have undone some operation, you can use Redo to do it again.

Cut

Make a copy of the current selection, and next delete the original.

Cut, Copy and Paste work within text fields, and with atoms and bonds in the drawing area.

Copy

Make a copy of the current selection.

Cut, Copy and Paste work within text fields, and with atoms and bonds in the drawing area.

Paste

Paste the current copy.

Cut, Copy and Paste work within text fields, and with atoms and bonds in the drawing area.

Clear

Delete the current selection.

Group

The currently selected atoms and bonds will be grouped together. Once grouped, if you select any of the group members the whole group will be selected.

You may nest groups if you wish, the original group structure will be remembered.

Ungroup

Remove the grouping of the currently selected items.

If you ungroup a nested group, only the top grouping will be removed and you will recover your original groups.

Set origin

Translate all atoms such that the selected atom will be the new origin. If nothing is selected, the center of all atoms will be the new origin. If more than one atom is selected, the center of the selected atoms will be the new origin.

When symmetry is used, the origin will also be the origin of symmetry.

Bond Lengths constrained

When creating new atoms bonded to existing atoms, ADFinput will constrain the bond length to the textbook value.

If you do not wish this to happen, select this menu command to toggle this behavior.

Add Bond

Create a bond (if possible depending on the number of free connectors) between two selected atoms.

Add Hydrogen

The 'Add Hydrogen' menu command will add hydrogen atoms to your molecule until every connector is connected. The number of connectors and the number of lone pairs determine the geometry. For example, the Oxygen atom has four connectors and two lone pairs in a tetrahedral arrangement.

The hydrogens will only be added to selected atoms, or to your whole molecule if no atoms are selected.

Remove Hydrogen

The hydrogen atoms will be removed from your molecule.

If you have selected part of your molecule, only hydrogen atoms in your selection will be removed.

Fuse Atoms

Fuse atoms that are very close together (in 3D space) to a single atom. If atom types differ, one of the types will randomly be chosen.

Select All

Select all atoms and bonds in your molecule.

Select Molecule

Select all atoms and bonds that are somehow connected to the current selection.

Select Connected

Select all atoms that are directly connected (by one bond) to the current selection.

Guess Bonds

Roughly guess what atoms are bonded together, depending on the distance between the atoms compared with text book values. The bond type is currently always set to single, so you probably need to make some changes.

Only ADFinput uses the bond information. The ADF program itself does not use any of the bond information.

Bonds will only be guessed for the selected atoms, leaving the remaining part of your molecule unchanged. If nothing is selected, bonds will be guessed for your whole molecule.

Remove Bonds

Remove all bonds in the current selection, or in your whole molecule if nothing is selected.

View menu

Standard View commands

Model menu

The 'Model' menu gives access to the first group of input panels on your right-hand side. They roughly specify your system.

You can also use the pull-down menu at the top right side (above the panels) to get to these panels.

Properties menu

The 'Properties' menu gives access to the second group of input panels on your right-hand side. You can use these to specify what properties you want to calculate.

You can also use the pull-down menu at the top right side (above the panels) to get to these panels.

Details menu

The 'Details' menu gives access to the third group of input panels on your right-hand side. You can use these to specify many details that are typically not needed. Expert users will get access to most ADF options with these panels.

You can also use the pull-down menu at the top right side (above the panels) to get to these panels.

Help menu

The help menu provides an easy way to get to information about the ADF-GUI. It will start a browser on your local machine, and connect to the SCM web site to get information.

Pop-up menu

Standard pop-up commands

Delete atom(s)

Delete the selected atoms.

Connectors

Set the number of connectors for the selected atoms. This is used by ADFinput to determine how many hydrogens may be added to the atoms.

Change atom(s) type

Change the selected atoms in some other type (select the type from the periodic system that appears).

Add structure(s)

Add the current structure to all selected atoms.

New Fragment...

Define a new fragment type. A dialog box will appear asking for the name of the new fragment. All currently selected atoms will be added to this fragment.

Another ... Fragment

Make a new ... fragment, and add the currently selected atoms to it. This way you can make multiple copies of one fragment. You should make sure that all copies have similar atoms, and that the geometries match.

Add to ... Fragment

Add the selected atoms to the ... fragment. Thus, the ... fragment will be extended. As atoms can belong to only one fragment at a time, they will be removed from the fragment to which they belonged.

Buttons and Tools

The button bar contains a number of tools and buttons:

From left to right these have the following meaning:

The currently selected atom tool, symmetry and bond type (if you are making bonds) will be shown if applicable in the status field in the bottom part of the drawing area. The currently selected tool will also be highlighted in the button bar.

Getting and changing geometry details

If you select 2, 3 or 4 atoms some geometry information will be presented at the bottom of the screen:

• 2 atoms: distance
• 3 atoms: angle
• 4 atoms: dihedral angle
• 5 atoms: angle between two planes

Often you can also change the information displayed. The geometry of your molecule will be updated accordingly. This is not always possible: ring structures make it impossible since ADFinput does not know how to change other bonds and angles. In such a case you might temporarily remove a bond, fine-tune your geometry, and finally recreate the bond you removed. The planes of the plane angle are defined through (in order of selection) atoms 1, 2 & 3 and atoms 3, 4 & 5. The order of selection is important in all cases.

Alternatively, you can use the "Geometric Info" popup menu command (from the popup that you get by right cliking, or left-click-and-hold, on an atom, bond or in epty drawing space) to show distances and/or angles in the drawing area of the molecule. These are informative only, you can not use them to change the measurements.

Keyboard shortcuts

Many tools and menu commands have keyboard shortcuts associated.

For menu command shortcuts, the shortcut is listed in the menu. On most UNIX systems (including Linux) you need to use the control key together with some letter. On a Macintosh (running locally) you need to use the command key together with a letter.

The following table lists the other keyboard shortcuts. Just press the indicated key without any modifier keys:

Presets and Defaults

All input options have default values. However, the default values depend on the main task you have chosen, and on further properties you may select to calculate. ADFinput uses presets that are simply a collection of input values to be used together as defaults.

A preset may set all or just a few input options. After you have selected a preset (using the Preset menu on the main panel), fields that are set by the selected preset will be show with a green color.

ADFinput has a couple of templates for typical calculations (currently Single Point, Geometry Optimization, IRC, Linear Transit, Frequencies, Transition State Search, Fragment Analysis and Properties Only). You may also define your own templates.

To switch from Task, we suggest you use the Preset menu. That way you will not only switch from task, but also set some other input options that are suggested for those tasks.

Use a Preset

Select the preset you want to use from the Preset menu, located in the main input options area.

All or some input values will change to the values specified in the preset you select.

Revert to preset values

If you want to undo your changes and get back to the default values as specified in the current template, simply select the template again from the Template menu.

Color Code

The input fields use a color coding to warn you they have been modified:

• No special color: the field has its original default value.
• Yellow: the field has been changed by the user (only).
• Green: the field has been changed by the preset (only).
• Red: the field has been changed by the preset, and next by the user.

The pull-down menu that you use to switch between panels uses a similar color-coding to point you to fields that have been changed:

• No special color: all fields in the panel have their original default value.
• Yellow: some fields have been changed by the user.
• Green: some fields has been changed by the preset.
• Red: some fields has been changed by the preset, and some (possibly also) by the user.

Make your own presets

It is very easy to make your own presets, collecting all or a few default values for the typical jobs you like to perform.

When the SCM_TPLDIR environment variable has been set, ADFinput will look for user-defined presets (when starting up) in the directory $SCM_TPLDIR.

Thus, to use your own presets first set up your preset directory if you have not already done so:

• make a directory in which to store your presets
• set the SCM_TPLDIR environment variable to point to this directory

Next, in ADFinput (restart it if it was already running):

• select the preset to start with (or None if you wish to start with an empty preset)
• edit all the fields as you would like them to be stored in a preset.
• select 'Save as (Full) Preset' from the Preset menu
• specify a file name, ending with '.tpl'
• click on Save.

If you now check your Preset menu you will find a new entry.

The name of the preset is the file name you have chosen, but without the .tpl extension.

The difference between a Full Preset and a 'normal' Preset is that a Full Preset will save all input options, and a 'normal' preset will save only the yellow or green fields (options that have been changed by the user or by the active template). A Full Preset is the same as a template from older ADFinput versions.

If you wish to store only fields that you have changed yourself in the preset, make sure you start with the None preset.

Defaults

The default values that are shown when you start ADFinput are generated as follows:

• Use the Defaults preset supplied by SCM
• Use the Defaults preset that the user has defined, if any
• Use the 'Single Point' preset

Thus, you can change the defaults by saving a preset called Defaults.tpl in your SCM_TPLDIR.

Calculation Tasks

There are eight basic tasks (types of calculation) that you can choose from.

The currently active Task is shown on the main panel. It is a reminder only, you cannot change it there.

The easiest and recommended way to change the task is to use the matching Preset menu command. Not only will you change the task that way, but also some other parameters that normally need to be set to get reliable results. For example, to calculate reliable frequencies you will need to use a higher integration accuracy.

Alternatively, you may select the task from the task details panel. This panel will have a different title depending on the current task (Task: SinglePoint, Task: GeometryOptimization, etc).

Fragment Analysis

Perform a fragment analysis calculation.

To set up your fragments, use the pop-up menu on the atoms to define to which fragment they belong. In the Task: FragmentAnalysis panel you can:

• set a charge per fragment
• use the check charges checkbox
• open a fragment in ADFinput, so that you can set any detail of the calculation of this fragment

The 'check charges' checkbox determines if ADFinput will make sure that the charges of the fragments added together do match the total charge of your molecule.

The default set up of the fragments is identical to all options you have chosen for your molecule, except for those features that will not work or do not make sense for fragment calculations. For example, ADF can use only 'restricted' fragments. Thus, even if you have an unrestricted calculation, the calculation on the individual fragments will always be done with restricted spin. If you click on the 'Open' buttons in the Task: FragmentAnalysis panel you can check exactly what options will be used for the fragments (and make changes to this if you desire)

Once you have set up your fragments, and choose the 'Save' command from the 'File' menu, ADFinput will generate a run script that will perform the fragment analysis. This script will first perform a calculation on each fragment, and next perform the fragment analysis.

You can read more about the fragment analysis method available in ADF in the ADF Users Guide.

Frequencies

Perform a frequencies calculation. The result of such a calculation is a hessian matrix, and a set of frequencies, intensities and normal modes (the IR spectrum). The hessian matrix may be used in subsequent calculations (for example, to help the search for a transition state).

ADF will calculate the frequencies analytically by default. You can also use a numerical scheme. To select this option use the 'Task: Frequencies' panel.

You can read more about frequencies calculations in the ADF Users Guide.

Geometry Optimization

Perform a geometry optimization. This optimization is done using either Cartesian, Internal or Delocalized coordinates. You can select which coordinate type to use in the Coordinates panel. Often the Delocalized coordinates seem to work best.

You can read more about geometry optimizations in the ADF Users Guide.

IRC (Intrinsic Reaction Coordinate)

Follow the intrinsic reaction coordinate from a transition state.

You can read more about an IRC calculation in the ADF Users Guide

Linear Transit

Perform a linear transit calculation. You need to select one or a few coordinates (typically using Internal coordinates). For these coordinates you specify their range, and you specify a number of linear transit steps. You can do this using the Linear Transit panel.

The result of the linear transit calculation is a series of optimized geometries. You can use ADFmovie to show these. You may set up a new calculation with ADFinput starting from one of those geometries, for example to have a better starting point for a transition state search. To do this, select that geometry using ADFmovie. Next, use the 'Transfer Coordinates to ADFinput' to use that geometry in ADFinput.

You can read more about linear transit runs in the ADF Users Guide.

Properties Only

This task will set up a post-ADF property program calculation. Can only be used when the appropriate .t21 or, in some cases, .t10 file is present.

You can read more about the property programs in the Properties documentation.

Single Point

Perform a single point calculation (just one geometry).

Transition State Search

Perform a transition state search.

You can read more about transition state searches in the ADF Users Guide.

Structures

With the Structure tool (the button with the benzene like graph) you can quickly add molecular fragments to your molecule. When you have selected a structure from the menu, there are different ways in which they can be used.

Replacing an existing atom

After selecting a structure from the structure menu, the structure will replace any double-clicked atom. So, to change a methane into an ethane, select the methyl structure and double-click on one of the methane hydrogens.

You can add structures in the same way using the atom pop-up menu. By right clicking on an atom (or selection), you can choose a structure from the pop-up menu. The atom (or every atom in the selection) will be replaced by the structure. This feature will not work with the metal-complexes and whole amino acids.

If you press spacebar, the last structure tool is selected again. You can then directly use it again by double-clicking on another atom.

Left-click in empty space

This will paste the structure at the desired spot. In most cases, one of the atoms in the structure will be selected. The selected atom, defined as the origin of the structure, is the same atom that will replace the atom that is double-clicked. When a molecule is already present, a potential bond will appear so that you can connect the structure to the molecule. If no atom in selected, it means that the 'replacing atom' is not defined, as is the case with the metal complexes.

If you press spacebar, the last structure tool is selected again. You can then directly use it again.

Metal Complexes

In the 'Metal Complexes' submenu of the structures menu, you will find many typical transition metal complex geometries that can serve as a good starting geometry. The dummy atoms, which define the geometry, can be conveniently replaced by structures from, for example, the 'Ligands' submenu.

The metal atoms cannot be used to replace an existing atom, since no atom is defined as the 'replacing atom'.

Dummy atoms and Multidentate ligands

Dummy ("Xx") atoms are treated a little different when used in structures. A dummy atom will not replace an existing atom when it is defined as the 'replacing atom'. Instead, the double-clicked atom will remain and will accept the bonds that the dummy atom had in the structure.

Thus, the dummy atom in the structure will be replaced instead of the atom that is double-clicked.

This behavior is utilized in the multidentate ligands, which can be added to a bare metal center. The dummy atom disappears and the ligand is bonded to the metal via the bonds that were previously located on the dummy atom.

Your own structures

You can make your own structure library very easily. First (before starting ADFinput) define an environment variable 'SCM_STRUCTURES'. It should point to some directory in which to search for possible structures. When you start ADFinput, the $SCM_STRUCTURES directory INCLUDING all subdirectories will be searched for structures. A structure is stored in an .adf file, you can just use any .adf file that you have created yourself.

The structures pull-down menu will have the same structure as the subdirectories within $SCM_STRUCTURES. One way to use this feature: set SCM_STRUCTURES to $HOME. Automatically any .adf file that you saved somewhere in your home directory will be found. However, if you have many files the start-up of ADFinput will be significantly slower since it needs to search all your files. In that case it is more convenient to make a special directory in which you put the .adf files that you wish to show up in the Structures menu.

To be able to actually use the structures as described earlier, it is necessary to define one of the atoms as having xyz-coordinates (0,0,0). This will be the atom that will actually appear at the spot of the atom that is replaced by the structure. To do this, simply select the atom and use the 'Set origin' command from the Edit menu. Next, save the structure in $SCM_STRUCTURES. As mentioned above, dummy atoms behave a little different when defined in this way.

Symmetry

The current implementation of symmetry in ADFinput is still in a very early stage: using it is somewhat complicated, and sometimes it does not work as expected.

First you need to define the point group that you want to use for your molecule. You do this by selecting the group name from the symmetry pull-down menu (initially the menu reads 'Nosym').

Next you need to define one or two operators for the selected group. In the symmetry menu you can see what operators you need to define.

Make sure that the (symmetry) origin of your molecule is set correctly (use the SetOrigin menu command).

1 atom selected: this defines the axis through center of molecule and the selected atom. This is the axis that will be used when you define a rotation axis. When you use it to define a mirror plane, the plane perpendicular to this axis through the origin of your molecule will be used.

2 atoms selected: defines an axis that will be used either as rotation axis, or as normal axis to a mirror plane through the origin.

3 atoms selected: defines a plane that will be used as mirror plane (shifted to the origin if required), or defines an axis for rotation (through the origin, in the direction of the normal vector of the plane).

Next you can use the symmetry commands:

Symmetrize: try to update the coordinates of the current atoms so that the molecule indeed has the required symmetry. Warning: if atoms are missing this will be resolved by moving equivalent atoms to the origin ...

Add symmetry equivalent atoms: generate all missing symmetry equivalent atoms to produce a molecule with the required symmetry. The existing atoms may be slightly moved to enforce perfect symmetry.

Molecule Editor Tricks

Selecting

You can make or change a selection using the mouse or using menu commands.

Making a selection with the mouse: see Selecting

Making a selection with a menu command: see Edit Menu

Pop-up menus: Select all similar elements or all bonds by using the pop-up menus.

Delete an atom

Select the atom (click on it), and press the Backspace key.

Delete a bond

Select the bond (click on it), and press the Backspace key.

Delete the selection

Make your selection, and press the Backspace key.

Make a bond

Take one of the atom tools.

Next click once on the first atom you want to connect. You will enter the bonding mode (the line to the mouse position from the atom you just clicked on will be your visual cue for the bonding mode).

Next click on the atom you want to make the bond to.

The bond will be created, and you will revert to the normal select mode.

Make a bond, alternative method

Select the two atoms that you wish to be bonded together.

Select the 'Add Bond' command from the 'Edit' menu or press ctrl-l.

Change the bond type

Select the bond or bonds to change. Next do one of the following to change the type of the selected bonds:

• press 1, 2, 3 or 4 for a single, double, triple or aromatic bond, respectively
• choose the required bond type from the Bond type pull-down menu
• use the pop-up menu and choose the required bond type from the Bond type pull-down menu

Move an atom (possibly perpendicular to the screen)

First select the atom that you want to move.

Next, translate (middle mouse button, or alt left mouse button), but start with the mouse on the atom that you want to move.

If you wish to move the atom perpendicular to the screen: use the right mouse button (or command left mouse button) and move the mouse up or down). This is equivalent to zooming.

Rotate or translate the selection

First make your selection.

Next rotate, translate or zoom as usual, but start with the mouse in the selection. So if you click and drag the selection, ONLY the selection will be rotated or translated. If you click and drag anywhere else the whole molecule will be rotated or translated (actually, only your viewpoint).

If you 'zoom' the selection you are really moving the selected objects perpendicular to the screen (in or out the screen).

Run Script

Save your input using the Save or Save As ... menu commands.

Your input will be saved in a file with the name you specify, and at the same time a run script will be saved. It has the same name, but with '.run' appended.

This script contains most commands to run your calculation. However, typically some more administrative things need to be done: make emty working directories, make some links to follow a running calculation, etc. This used to be done by the run script, but not any more. If you wish to use the run script yourself you are responsible of taking care of such details.

To run your calculation, use the Run command from the File menu. This will tell ADFjobs to run your job. Alternatively, you can switch to ADFjobs, select your job (that you should have saved from ADFinput), and select Run from ADFJobs Job menu.

In ADFinput, the panel 'Files (Restart)' you can specify what files to save at the end of the run script.

By default, TAPE21 (result data), TAPE41 (grid data for visualization) and TAPE13 (checkpoint information) are saved.

If the environment variable SCM_RESULTDIR has been set, the run script will change into that directory. Next it will run from there, and all result files will be stored in that directory.

If the environment variable SCM_RESULTDIR has not been set, the run script will execute in the directory where it is started, and the result files will also be located in that place.

Input options remarks

Empty fields

Some input fields do not have a value from the default Preset. In those cases ADFinput does not specify the value, but leaves the value to be determined by the ADF program.

Coordinates

The coordinates panel shows the coordinates corresponding to the molecule visible in the molecule display. You may edit the coordinate values here as well. Besides the values you can also change the order of the atoms, using the 'Move Atoms' buttons.

You may select to use Cartesian, Internal or Delocalized coordinates.

For internal coordinates you can currently only edit the values for bond lengths and angles, not the connection information. You can, however, change the order of the atoms. The Internal coordinates matrix will be recalculated each time the order is changed. The connection matrix will make as much use as possible of the actual bond information. If possible, vicinal dihedrals will be shown and groups such as methyls will be fully rotatable using one dihedral. If there are separate molecules present, the first atom on the second fragment will be connected to the first on the first fragment. This can be a useful trick to quickly define a certain distance.

The ordering of atoms in Cartesian, Internal and Delocalized coordinates is identical. Obviously the order is only important if you are going to use Internal coordinates.

If you will optimize the geometry (with ADF), the program will perform this optimization in the coordinate type you have selected here. Thus, the Cartesian, Internal or Delocalized pull-down menu is not only for display purposes, but determines the optimization method used.

By checking the checkboxes next to the coordinates you can freeze those coordinates during a geometry optimization.

You can select atoms using the coordinates panel as well as in the molecule pane. The coordinate lines for atoms that are selected will be highlighted in yellow.

User Input

You can use the User Input field to specify any kind of text. The text will be appended without any change to the end of the ADF input. This way, you may access some keys that are not (yet) available in ADFinput. For example, you can use it to specify the OCCUPATIONS key once you know the symmetries of the orbitals.

Note that at this point in time you can only add text to the ADF input file, not to the input of any of the property programs.

Protein QMMM calculations with PDB files

In the Protein panel you can select a PDB file to be used. That PDB file will be loaded and analyzed using the pdb2adf program. This means you have to make sure that 'pdb fragment files' are available for each non-standard residue, as required by pdb2adf. With the controls in the Protein panel you can select which Amber type to use for the different residues, and what residues and / or atoms to put in the QM and MM regions. You can also add a solvent to your calculation. Next, you can use the QMMM panel to set up other technical details of the QMMM calculation.

Currently, the protein is NOT further integrated with the molecule editor. Thus, you can not use the edit tools to change atoms in the QM or MM region. You will need to edit the PDB file.

ADFview

Introduction

ADFview is a small utility program, which provides some basic visualization tools in 3D space. It will enable ADF and BAND users to visualize their results: SCF densities, orbitals, electrostatic potentials, and any other property that is available as a scalar value over a grid.

The property fields may be available on a 'TAPE41' file, with .t41 extension, or on a file formated as a Gaussian cube file (with .cub or .cube extension). Alternatively, they can be computed from a 'TAPE21' file, with .t21 extension, as required by ADFview. For BAND calculations the property fields can be computed from a 'RUNKF' file, with .runkf extension.

Many preferences (background color, molecule resolution, etc) are shared with ADFinput and BANDinput. You can use ADFinput or BANDinput to change these preferences, and once saved ADFview will also use these.

Starting ADFview

If you have installed the ADF package correctly, the adfview command is located in $ADFBIN.

If $ADFBIN is included in your PATH environment variable, you can start the ADFview program with the following command:

adfview [filename]

The filename is optional. ADFview only handles files of with extension .t21, .t41, .runkf, .cub(e)

If a file name is given, ADFview will read the file and produce an image of your molecule just as ADFinput (or BANDinput) does. However, since neither old .t21 (before ADF2006), .t41, .runkf nor .cub(e) contains bond information, ADFview will in those cases just make a guess at the bonds to show. If you use a .t21 file that has been created using the ADF-GUI 2006 and matching ADF, the bond information will be read from a .t21 file. These bonds are the bonds as defined by the user using ADFinput.

A .t21 file is a result file produced by ADF that contains most results of the ADF calculation. The data is not yet in field format. ADFview knows what kind of fields can be generated from the data present in a .t21, and will offer those fields. When you select such a field, ADFview will calculate the field data (the function values on a 3D grid) on the fly (using the DENSF program).

A .t41 file is a file produced by DENSF that contains field information: values of some function on a 3D grid. A single .t41 file may contain many fields, and ADFview will make all fields available that are present in the .t41 file.

A .runkf file is a result file produced by BAND that contains most results of the BAND calculation. The data is not yet in field format. ADFview knows what kind of fields can be generated from the data present in a .runkf, and will offer those fields. When you select such a field, ADFview will calculate the field data (the function values on a 3D grid) on the fly (using the BAND program again).

A .cub or .cube file is a file produced by several programs, using the Gaussian cube format. ADFview can read such files to make it easier for you to compare results from ADF or BAND with results from other packages.

An alternative method to start ADFview: select the View command from the SCM menu. It will start using the .t21 file belonging to the calculation you were handling. In case of a BAND calculation it will start using the .runkf file belonging to the calculation you were handling.

Menu commands

File

New

Start over again, similar to quitting and starting ADFview without specifying a file name.

Open...

Open a .t21, a .t41, .runkf, or .cub(e) file to use for visualization.

You can have only multiple files open at the same time. If you open another file, it's fields are made available, so you can easily compare fields from different files.

Save Picture...

Save a picture of visualization area in a file.

The format used to save your picture is determined by the extension of the file name you specify. If you do not specify a known extension, it will use the standard picture format as specified using the 'Default Picture Format' menu.

Default Picture Format

Use the submenu to select the format to use when saving a picture.

Note that this is just the default to use, the user specifies the format with the extension. When the extension is not recognized (or when no extension is specified) the default format will be used.

Picture Resolution

Use the submenu to select the resolution that you want to use when saving a picture.

Export As VRML...

Export the current scene (molecule, surfaces, etc) as a VRML file. This file can be used by other utilities to visualize 3D scenes. Note that the objects are written to the file, not the rendered image. Thus, using a VRML viewer one can still rotate, zoom and so on.

Note that this is an experimental feature that might be improved or removed in future versions. Feedback is welcome!

Quit

Quit ADFview. Nothing will be saved.

Add

When you add a visualization item, below the picture a new horizontal bar will appear with controls. These controls determine the details of the item you have added: what field to use for visualization, isovalues, colors, surface properties, etc.

Isosurface

Add an isosurface: a surface through a field connecting all points with same value (the isovalue).

For example, an isosurface showing the SCF density of your molecule.

The control bar has the following controls from left to right:

Show/Hide checkbox (default checked: the isosurface is visible).

Wireframe checkbox: if checked, show wireframe instead of solid surface.

Isosurface pull-down menu: Copy To All Geometries command will create a similar surface for all open files (different geoemtries), Delete command to delete the surface, Show details will add an additional control-bar with more controls, and Hide details will remove the additional bar.

Field pull-down menu: use it to select what field to make an isosurface from. If multiple files or geometries are present, the first entry might be used to select one. In the field menu you may notice that all listed fields have checkboxes in front of them. These will be checked if the field is available. If not checked, the field will be calculated in the background when you select it. Once a field is calculated, it will remain available as long as you do not open another file or quit ADFview.

The isovalue defining the isosurface.

The details bar contains the following controls:

Opacity: determine the opacity of the surface. If less then 100% you can look through the surface. Note that often you will get visual artifacts if the value is not 100.

Ambient: amount of ambient (non-directional) light (0-100).

Diffuse: amount of diffuse (directional) light (0-100).

Specular: strength of highlights (0-100).

Power: extent of highlights (specular power).

Isosurface: Colored

Add an isosurface: a surface through a field connecting all points with same value (the isovalue). The isosurface will be colored by a second field.

For example, an isosurface showing the SCF density of your molecule, colored by the electrostatic potential.

The control bar has the following controls from left to right:

Show/Hide checkbox (default checked: the isosurface is visible).

Wireframe checkbox: if checked, show wireframe instead of solid surface.

'Isosurface: Colored' pull-down menu: Copy To All Geometries command will create a similar surface for all open files (different geoemtries), Delete command to delete the surface, Show details will add two additional control bars with more controls, and Hide details will remove the additional bars.

Field pull-down menu: use it to select what field to make an isosurface from.

The isovalue defining the isosurface.

Field pull-down menu: use it to select what field to color the surface with.

Two numbers: the range of the color field used for mapping colors.

Log checkbox: use a logarithmic color scale.

Bar checkbox: show a color bar as legend for the color field.

The first details bar contains the same controls as for a normal Isosurface.

The second details bar contains the controls defining the mapping of the color field to a color. The color is specified using the HSV color space.

The hue is what is normally thought of as color. Saturation is the amount of gray, white, or black that is mixed into the color. Zero saturation indicates no hue, just gray scale. The value component of the HSV space is a measure of its brightness. The HSV color space is normalized.

Color Scale pull-down menu: four different presets of coloring settings (color scale, gray scale, white or black). The last entry 'Store As Default' will store your current color settings as defaut.

Hue (two numbers): the lower end of the color field maps to the first hue value, the upper end maps to the second hue value, and the other values are generated linearly (or logarithmically) in between.

Saturation (two numbers): the lower end of the color field maps to the first saturation value, the upper end maps to the second saturation value, and the other values are generated linearly (or logarithmically) in between.

Value (two numbers): the lower end of the color field maps to the first intensity value, the upper end maps to the second intensity value, and the other values are generated linearly (or logarithmically) in between.

Isosurface: Double (+/-)

Add a double isosurface: just two isosurfaces at the same time, of different colors, through the same field. One isosurface corresponds with the chosen isovalue, the other one with the negative of that value.

The main control bar is identical to the control bar of a normal isosurface. If you show the details, you will find that in addition to the controls available for a normal isosurface, you can also specify coloring information. In this case, the two numbers for the HSV colors define the colors of the negative and positive isosurface.

Cut Plane: Colored

Add a plane, and color the plane with some field.

The control bar has the following controls from left to right:

Show/Hide checkbox (default checked: the cut plane is visible).

Wireframe checkbox: if checked, show wireframe instead of solid surface. Not very useful.

'Cut Plane: Colored' pull-down menu: Copy To All Geometries command will create a similar surface for all open files (different geoemtries), Delete command to delete the surface, Show details will add two additional control bars with more controls, and Hide details will remove the additional bars.

Field pull-down menu: use it to select what field to color the plane with.

Position plane checkbox: if checked, in the picture handles will appear. Using these handles you can orient and move the cut plane. Uncheck to remove the handles.

With atoms: press this button to orient the plane with 1, 2 or 3 atoms selected. With 1 atom selected move the plane to go through that atom. With 2 atoms selected, the axis between these atoms defines the plane normal, and it will be positioned exactly between the two atoms. With 3 atoms selected, move the plane such that all three atoms are in the plane.

Two numbers: the range of the color field used for mapping colors.

Log checkbox: use a logarithmic color scale.

Bar checkbox: show a color bar as legend for the color field.

The details control bar contains the coloring controls, as for a colored isosurface.

Cut Plane: Contours

Add a plane, and on that plane show contour lines for the requested contour values of some field. The contours will be colored by the value of the field.

The control bar is the same as for a colored cut plane, with the addition of the number of contours.

The details bar contain coloring information, as before. And an additional details bar is present to change the appearance of the contours: you can make the contour lines thicker (with line width), or choose to use dots of a specified size instead of lines. Note that activating the dots option makes rendering much slower.

Cut Plane: Contours (+/-)

Add a plane, and on that plane show contour lines for the requested contour values of some field. In this case, the positive and negative contours are shown in a different way, determined by the controls.

All controls are identical to the controls of a contour cut plane. The behavior is different: you specify the number and range of positive contours, possibly using a logarithmic scale. ADFview will automatically generate negative contours as well with similar values. All positive contours are drawn using one color, and all negative contours are drawn with a different color.

The coloring controls determine the colors of the negative and positive contours.

Using the Dashed checkbox, dashed lines will be used for the negative contours. This means that you can use one color (black for example) for all contours and still distinguish between the negative and positive contours.

COSMO surface: Colored

Spinor: spin magnetization density

Show the COSMO surface as used in a Cosmo calculation. Only accessible for .t21 files that contain COSMO results.

Only accessible in case of a spin-orbit coupled calculation with a TAPE21 (.t21) file to visualize a spinor.

Visualization of spinors is more difficult than visualization of orbitals. A spinor Ψ is a two-component complex wave function, which can be described with four real functions φ: real part α φ_α^R, imaginary part α φ_α^I, real part β φ_β^R, imaginary part β φ_β^I:

The density ρ is:

ρ = Ψ^† Ψ

The spin magnetization density m is:

m = Ψ^† σ Ψ

where σ is the vector of the Pauli spin matrices σ_x, σ_y, and σ_z. A spinor is fully determined by the spin magnetization density and a phase factor e^iθ, which both are functions of spatial coordinates.

The (square root of the) density and spin magnetization density are visualized as a double isosurface and a vector field respectively. The phase factor e^iθ, reduced to a plus or minus sign, is visualized with the double isosurface and with the color of the vector field.

The main control bar is identical to the control bar of a normal isosurface. If you show the details, you will find that in addition to the controls available for a normal isosurface, you can also specify coloring information. In this case, the two numbers for the HSV colors define the colors of the minus and plus sign.

Add Bond

First select two atoms. Next use this command to add a bond. This is for visual purposes only.

Delete Bond

Delete the selected bond. Mainly to correct ADFview if it mistakenly is showing some bond that really should not be present.

Fields

Calculated

Create a new control bar where you can define a new field as some mathematical function of one or two existing fields. Once the field is defined in this way, you may use it in any place where a field is used.

The mathematical operations are split in three groups: operations between two fields (+, -, /, *, min, max), operations on one field (abs, square, sqrt, sin, cos, invert, log, exp) and operations between a constant and a field (+, *). Once you have calculated a field, you may also use it in another calculated field.

Interpolated

Create a new control bar where you can define a new field as an interpolated field of an existing field. Using the interpolation you can either increase or reduce the number of grid points (for respectively a smoother picture, or for faster rendering).

The controls are simple: select the field to interpolate, select either linear or cubic interpolation, and select a interpolation factor. A factor of 2.0 means that in every direction you will get twice as many points, thus your grid will be 8 times as big. Similarly, specifying a factor of 0.5 will reduce the size of your grid by a factor of 8.

Grid

Define the grid resolution that should be used when calculating fields in the background.

A fine grid produces the most accurate results, but might be slow for big molecules. A coarse grid does not look as good, but will be much faster for big molecules.

When you change the Grid choice, the fields that have already been calculated may be recalculated. If you have more than one field already present, ADFview will ask you to confirm that you indeed wish to recalculate the fields already present. Whatever you choose, the Grid setting will always apply for newly calculated fields.

Sort by

In the field menus in the control bars you will have a list of all MOs. They are sorted in the way you select here (either by energy or by symmetry).

View

Standard View commands

Show Molecule details

Adds a control bar below the picture with some controls that determine how your molecule is shown. You can use it to hide all atoms, hide all bonds, or scale the atoms and bonds.

Show Scene Light

Adds a control bar below the picture with some scene light controls. You may activate a scene light: this light will be in a fixed position with respect to your molecule. Using the controls, you may reposition the light, and you can set the relative intensity of the scene light and normal light source.

Show All Geometries

Show all visualisation items, belonging to all geometries, if checked. Otherwise, only show those items that are related to the current geometry.

Periodic

If you are visualizing BAND results (from a .runkf file):

• Show Periodic: visualize more than one unit cell
• Show Lattice Vectors: show the the axes of the lattice vectors

Auto Update

When the auto update mode is enabled (the default situation), the display is continuously updated when you make changes. Sometimes this update may be slow, for example when updating means that new isosurfaces need to be comput