General

Overview

AMS is the new driver program introduced in the 2018 release of the Amsterdam Modeling Suite. The job of AMS is to handle all changes in the simulated system’s geometry, e.g. during a geometry optimization or molecular dynamics calculation, using the so-called “engines” like BAND or DFTB for the calculation of energies and forces. In summary, one might say that the AMS driver steers the engines across the potential energy surface.

Prior to the 2018 release of the Amsterdam Modeling Suite, what we now call engines used to be separate programs, each with their own input and output files and formats. Starting with the 2018 release, the engines are only accessible through the AMS driver program, that provides a unified interface to all of them.

What’s new in the AMS2019 driver?

Motivation and progress

The Amsterdam Modeling Suite has grown substantially over the last decade, and in the 2017 release included programs implementing methods all the way from accurate density functional theory, through semi-empirical methods, to fast reactive force fields. Many of these programs have originally been developed by academic groups and are now maintained and expanded by SCM in collaboration with the original authors.

This rapid growth of the Amsterdam Modeling Suite had, however, led to a certain degree of unnecessary inhomogenity within the suite: The input for the same task, e.g. a geometry optimization, differed quite a lot between the different programs in the suite. While this problem was mostly hidden for users of the graphical interface, it constituted a barrier for users of the new scripting frameworks such as PLAMS. Furthermore, the different programs produced rather different output files for the same task, making the automated extraction of results unnecessarily difficult. Finally, and most importantly, the rapid growth of the AMS suite had also led to a certain level of feature fragmentation, where some features were available in one program but not the other: ADF, for example, was able to do a linear transit calculation, while BAND was not. Constrained geometry optimization was supported in DFTB, but not in UFF. ReaxFF could be used for Grand Canonical Monte Carlo simulations, but DFTB could not.

In order to overcome these issues and make the Amsterdam Modeling Suite more powerful and user friendly, we are introduced the AMS driver program with the 2018 release of the suite. The idea of this reorganization is to have only a single program called the AMS driver that under the hood uses the so-called “engines” like BAND or DFTB for the calculation of energies and gradients, where the engines are technically no longer separate programs but just libraries used by the AMS driver. In this way much of the input and output of AMS is the same, no matter which particular engine is used for a calculation. It also avoids the feature fragmentation, since any new feature in the AMS driver can immediately be used with all engines in the suite. Furthermore, the AMS driver also allows running external programs as an engine providing energies and gradients, allowing end-users to perform all calculations supported by AMS with virtually any atomistic modeling program they have access to and to visualize the results in the graphical user interface of the Amsterdam Modeling Suite.

Converting all the programs of the Amsterdam Modeling Suite into engine libraries that are used by the AMS driver is a big reorganization of the entire suite, which is not complete yet. The long-term goal is to integrate all programs in the suite fully into the AMS driver, but as of the 2018 release, only BAND, DFTB, MOPAC and UFF have been fully integrated and removed as separate programs. ReaxFF is fully usable from within AMS, but not all features of the standalone ReaxFF program (e.g. the bond boost method) have been ported to AMS yet. Therefore, ReaxFF is in the 2018 release both available as an AMS engine and as the familiar standalone program. ADF can be used both through AMS and as the standalone program known from previous releases. QuantumEspresso has not yet been integrated into AMS. External programs can be hooked into the AMS driver through a thin scripting layer. While the transition to AMS is not complete yet, we believe that AMS in its current state already offers significant benefits over the 2017 release.

As with any large reorganization, it is unavoidable that some things change. For GUI users this should not create any issues, but users familiar with the existing command line and scripting interfaces will notice these changes and their existing workflows might need to be adjusted to the new setup. We know that these kind of changes can be disrupting for existing users, and where possible we try to keep backwards compatibility with previous versions, but unfortunately this is not always possible. However, overall AMS provides a much more consistent and convenient interface to command line and scripting users, and we believe that the new simplicity and expanded feature set of AMS make transitioning to the new framework well worth the effort.

Input, execution and output

With the introduction of AMS in the 2018 release of the Amsterdam Modeling Suite, there were some changes in the input and output files and formats used by our software. Users of the graphical interface should not notice these changes, but people using the software from the command line or through the scripting frameworks need to be aware of them.

Generally the input for AMS has the block and keyword structure that most programs in the Amsterdam Modeling Suite have already been using. See the Input syntax section for more details. The only new construct in the AMS input is a special Engine block, that selects which engine is used for the simulation and also contains all the details of its configuration. This is probably best illustrated by an example. Let us look at the following AMS input, which optimizes the geometry of the methane molecule and calculates its normal modes of vibration at the optimized geometry:

$ADFBIN/ams << EOF

Task GeometryOptimization

GeometryOptimization
    Convergence
        Gradients 1.0e-4
    End
End

Properties
   NormalModes true
End

System
    Atoms
        C       0.00000000       0.00000000       0.00000000
        H       0.63294000      -0.63294000      -0.63294000
        H      -0.63294000       0.63294000      -0.63294000
        H       0.63294000       0.63294000       0.63294000
        H      -0.63294000      -0.63294000       0.63294000
    End
End

Engine DFTB
    Model DFTB3
    ResourcesDir DFTB.org/3ob-3-1
EndEngine

EOF

Note how DFTB is selected as the engine in the Engine DFTB line that opens the Engine block. All DFTB specific configuration is contained within this engine block, which is terminated by EndEngine. The fact that we want to run a geometry optimization with normal modes for methane and things like convergence criteria for the optimization are of course completely independent from which engine is actually used to perform this calculation. Therefore they are all found outside of the Engine block. In this sense, the AMS input is split up into the driver level input (everything outside of the engine block) and the engine input, which is just a single Engine block. This separation makes it easy to perform the same calculation at a different level of theory, by simply switching out the Engine block in the input. We could, for example, repeat the same calculation at the DFT-GGA level using the Band engine:

Engine BAND
    XC
       GGA PBE
    End
EndEngine

Engines like BAND that have many options and can calculate many properties, consequently also have a large number of possible keywords in their input. In order to have a better structured documentation we have split off the description of the engine inputs into separate engine specific manuals, while this AMS manual only documents the driver level keywords outside of the Engine block. All the engine specific options are found in the respective engine’s manual, which documents the keywords in its Engine block. In general all engines can be used with all tasks in AMS. There are only a few rather obvious restrictions, for example that only engines which can handle periodic systems can be used for the calculation of phonons.

The introduction of the Engine block is the only real change AMS brings to the input side of things. On the output side there are a few more changes.

The first change to the output is that AMS does not put any of its output files into the present working directory, as virtually all of the standalone programs in the suite did. Instead AMS creates a *.results directory, which collects all result file associated with a job. Here * is replaced by the jobname, which is set with the AMS_JOBNAME environment variable:

AMS_JOBNAME=methane $ADFBIN/ams << EOF

... see above ...

EOF

This would put all results related to our geometry optimization of methane into the newly created folder methane.results. (The default name of the results folder is ams.results if AMS_JOBNAME is not set, see the environment variables section of this manual for documentation of all environment variables used by AMS.) In this way users can easily run multiple jobs in the same directory without danger of clashing output files, which was a common problem before the introduction of AMS. This new setup is also more consistent with the graphical user interface, which already collected all files associated with a specific job into a dedicated results directory. Note that AMS will by default not overwrite results directories if a job is rerun or another job is run with the same jobname.

Inside of the results directory users will always find the logfile ams.log, which is written during a running calculation and can be used to monitor its progress. Furthermore the results directory contains binary result files in the KF format, which can be opened and inspected with the KFBrowser GUI component. Conceptually there are two different kinds of these binary files in the result folder:

  • The main ams.rkf written by the AMS driver. It contains high level information about the trajectory that the AMS driver took over the potential energy surface. For a geometry optimization it would for example contains the history of how the systems geometry changed during the optimization as well as the final optimized geometry. For a molecular dynamics simulation it would contain the full trajectory. The format in which this information is written is independent from which engine was used for a calculation.
  • Additionally there might be a binary output file for every point on the potential energy surface that was visited during the calculation. They contain all information tied to a specific point on the potential energy surface. We call these files the engine output files, because they are not written by the AMS driver, but by the specific engine used for the calculation. As such they contain engine specific information (e.g. orbitals for quantum mechanical engines), which might be written in an engine specific format. The engine files are basically the same as the main output file the standalone programs produced for single point calculations prior to the 2018 release of the suite: The BAND engine writes engine output files that are basically the same as the RUNKF file that the BAND program wrote. The engine output files of the DFTB engine correspond to the dftb.rkf file that the DFTB program used to write. The engine output files all have the extension .rkf, but their filename is usually somehow descriptive of the point on the PES that they correspond to. Note that one does not always get an engine output file for every PES point that was visited during the calculation. For most applications this would just be too much data, so by default the engine results are only kept for special points, e.g. the final geometry in a geometry optimization.

Having multiple different binary output files could be confusing for people that are used to the single result file that was written by the standalone programs in ADF<=2017. After all, it brings up the question in which file the desired property is stored. The general rule is: If the property is tied to a particular point on the potential energy surface, it is stored in the engine output file belonging to that particular point. This includes all properties documented in the PES point properties section of this manual. If the information depends on the entire trajectory over the PES, it is found in the main ams.rkf written by the AMS driver.