AMS is the new driver program 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.
Motivation and progress¶
The Amsterdam Modeling Suite has grown substantially over the last decade, and in the 2017 release includes 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 has, however, led to a certain degree of unnecessary inhomogenity within the suite: The input for the same task, e.g. a geometry optimization, can differ quite a lot between the different progams 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 has also led to a certain level of feature fragmentation, where some features are 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 introducing the AMS driver program with the 2018 release of the suite. The idea of this reorganization is to have only a single program called AMS 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, AMS 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. GCMC) 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 are 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
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 descrption
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
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
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
- The main
ams.rkfwritten 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
RUNKFfile that the BAND program wrote. The engine output files of the DFTB engine correspond to the
dftb.rkffile 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
ams.rkf written by the AMS driver.