Appendices¶

Environment variables¶

The behaviour of AMS can be modified through a number of environment variables.

AMS_JOBNAME: Sets the name of a job. This name is used to determine the name of the results folder AMS creates, which is $AMS_JOBNAME.results or ams.results if this environment variable is not set.

AMS_RESULTSDIR: If this environment variable is set, instead of creating a new results folder, AMS will use the set directory as the results folder. Not that the directory set here will not be created by AMS and therefore has to exist before starting AMS. Note that this environment variable can be used to prevent AMS from creating result folders, by setting AMS_RESULTSDIR=.. This reproduces the pre-AMS behaviour of putting all result files into the directory from which a job is started.

AMS_SWITCH_LOGFILE_AND_STDOUT: If this environment variable is set, AMS will redirect what is normally printed on standard output to a file (ams.out) in the results directory. Instead the contents of the log file (ams.log) will be printed to standard output while a job is running, allowing users to easily monitor the jobs progress. Note that the log file will still be created normally as if this environment variable was not set. This environment variable is just a convenience feature for users that would always redirect their output into a file and then use tail -f on the log file to monitor the running calculation.

Extended XYZ file format¶

The .xyz file format is a simple text based format for molecular geometries. .xyz files have the number of atoms in the first line, followed by a comment line, followed by one line per atom, specifying the element as well as the x, y, and z coordinates of this atom.

However, the standard .xyz file format does not include lattice vectors. AMS therefore uses an extended .xyz file format which is also suitable for periodic systems. In this extended format the lattice vectors are specified at the end of the .xyz file via the keys VEC1, VEC2 and VEC3. For 1D periodic systems (chains) only VEC1 is needed. For 2D periodic systems (slabs) only VEC1 and VEC2 are needed. An example extended .xyz for graphene looks like this:

2

C     0.0   0.0      0.0
C     1.23  0.71014  0.0
VEC1  2.46  0.0      0.0
VEC2  1.23  2.13042  0.0

Note that the extended .xyz format is also understood by the AMS GUI for importing and exporting geometries from/to .xyz files.

Developer options¶

Print
   Timers [None | Normal | Detail | TooMuchDetail]
End

Print

Type:	Block
Description:	This block controls the printing of additional information to stdout.

Timers

Type:	Multiple Choice
Default value:	None
Options:	[None, Normal, Detail, TooMuchDetail]
Description:	Printing timing details to see how much time is spend in which part of the code.

EngineDebugging
   CheckInAndOutput [True | False]
   ForceContinousPES [True | False]
   IgnoreGradientsRequest [True | False]
   IgnoreStressTensorRequest [True | False]
   RandomFailureChance float
   RandomNoiseInEnergy float
   RandomNoiseInGradients float
End

EngineDebugging

Type:	Block
Description:	This block contains some options useful for debugging the computational engines.

CheckInAndOutput

Type:	Bool
Default value:	False
Description:	Enables some additional checks on the input and output of and engine, e.g. for NaN values.

ForceContinousPES

Type:	Bool
Default value:	False
Description:	If this option is set, the engine will always run in continuous PES mode. For many engines this disables the use of symmetry, as this one always leads to a discontinuous PES around the symmetric points: Basically there is jump in the PES at the point where the symmetry detection starts classifying the system as symmetric. Normally the continuous PES mode of the engine (often disabling the symmetry) is only used when doing numerical derivatives, but this flag forces the engine to continuously run in this mode.

IgnoreGradientsRequest

Type:	Bool
Default value:	False
Description:	If this option is set, the engine will not do analytical gradients if asked for it, so that gradients will have to be evaluated numerically by AMS.

IgnoreStressTensorRequest

Type:	Bool
Default value:	False
Description:	If this option is set, the engine will not calculate an analytical stress tensor if asked for it, so that the stress tensor will have to be evaluated numerically by AMS.

RandomFailureChance

Type:	Float
Default value:	0.0
Description:	Makes the engine randomly report failures, even though the results are actually fine. Useful for testing error handling on the application level.

RandomNoiseInEnergy

Type:	Float
Default value:	0.0
Unit:	Hartree
Description:	Adds a random noise to the energy returned by the engine. The random contribution is drawn from [-r,r] where r is the value of this keyword.

RandomNoiseInGradients

Type:	Float
Default value:	0.0
Unit:	Hartree/Angstrom
Description:	Adds a random noise to the gradients returned by the engine. A random number in the range [-r,r] (where r is the value of this keyword) is drawn and added separately to each component of the gradient.