Appendices
**********


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
      AlwaysClaimSuccess Yes/No
      CheckInAndOutput Yes/No
      ForceContinousPES Yes/No
      IgnoreGradientsRequest Yes/No
      IgnorePreviousResults Yes/No
      IgnoreStressTensorRequest Yes/No
      NeverQuiet Yes/No
      RandomFailureChance float
      RandomNoiseInEnergy float
      RandomNoiseInGradients float
      RandomStopChance float
   End

"EngineDebugging"
   Type:
      Block

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

   "AlwaysClaimSuccess"
      Type:
         Bool

      Default value:
         No

      Description:
         If an engine fails, pretend that it worked. This can be
         useful when you know that an SCF might fail.

   "CheckInAndOutput"
      Type:
         Bool

      Default value:
         No

      Description:
         Enables some additional checks on the input and output of an
         engine, e.g. for NaN values.

   "ForceContinousPES"
      Type:
         Bool

      Default value:
         No

      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:
         No

      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.

   "IgnorePreviousResults"
      Type:
         Bool

      Default value:
         No

      Description:
         If this option is set, the engine will not receive
         information from previous calculations. Typically this
         information is used to restart the self consistent procedure
         of the engine.

   "IgnoreStressTensorRequest"
      Type:
         Bool

      Default value:
         No

      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.

   "NeverQuiet"
      Type:
         Bool

      Default value:
         No

      Description:
         Makes the engine ignore the request to work quietly.

   "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.

   "RandomStopChance"
      Type:
         Float

      Default value:
         0.0

      Description:
         Makes the engine randomly stop. Can be used to simulate
         crashes.


Symmetry
========


Schönfliess symbols and symmetry labels
---------------------------------------

A survey of all molecular point groups that are recognized by AMS is
given below. The table contains the Schönfliess symbols together with
the names of the subspecies of the irreducible representations as they
are used by AMS to label normal modes.


Schönfliess symbols and the labels of the irreducible representations.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

 
| **Point**                                          | **Schönfliess**                                                                                                          | **Irreducible representations**                                                                                                                                                                                                                                                                                                                                                                                  |
 
| **Group**                                          | **Symbol in AMS**                                                                                                        |                                                                                                                                                                                                                                                                                                                                                                                                                  |
 
| C_1                                                | NOSYM                                                                                                                    | A                                                                                                                                                                                                                                                                                                                                                                                                                |
 
| C_∞v                                               | C(LIN)                                                                                                                   | Sigma Pi                                                                                                                                                                                                                                                                                                                                                                                                         |
 
| D_∞h                                               | D(LIN)                                                                                                                   | Sigma.g Sigma.u Pi.g Pi.u                                                                                                                                                                                                                                                                                                                                                                                        |
 
| I                                                  | I                                                                                                                        | A T1 T2 G H                                                                                                                                                                                                                                                                                                                                                                                                      |
 
| I_h                                                | I(H)                                                                                                                     | A.g A.u T1.g T1.u T2.g T2.u G.g G.u H.g H.u                                                                                                                                                                                                                                                                                                                                                                      |
 
| O                                                  | O                                                                                                                        | A1 A2 E T1 T2                                                                                                                                                                                                                                                                                                                                                                                                    |
 
| O_h                                                | O(H)                                                                                                                     | A1.g A1.u A2.g A2.u E.g E.u T1.g T1.u T2.g T2.u                                                                                                                                                                                                                                                                                                                                                                  |
 
| T                                                  | T                                                                                                                        | A E T                                                                                                                                                                                                                                                                                                                                                                                                            |
 
| T_h                                                | T(H)                                                                                                                     | A.g A.u E.g E.u T.g T.u                                                                                                                                                                                                                                                                                                                                                                                          |
 
| T_d                                                | T(D)                                                                                                                     | A1 A2 E T1 T2                                                                                                                                                                                                                                                                                                                                                                                                    |
 
| C_i                                                | C(I)                                                                                                                     | A.g A.u                                                                                                                                                                                                                                                                                                                                                                                                          |
 
| S_n                                                | S(N)                                                                                                                     | n=4: A B E                                                                                                                                                                                                                                                                                                                                                                                                       |
 
|                                                    |                                                                                                                          | n=6: A.g A.u E.g E.u                                                                                                                                                                                                                                                                                                                                                                                             |
 
|                                                    |                                                                                                                          | n=8: A B E1 E2 E3                                                                                                                                                                                                                                                                                                                                                                                                |
 
| C_n                                                | C(N)                                                                                                                     | n=2: A B                                                                                                                                                                                                                                                                                                                                                                                                         |
 
|                                                    |                                                                                                                          | n=4: A B E                                                                                                                                                                                                                                                                                                                                                                                                       |
 
|                                                    |                                                                                                                          | even n: A B E1 E2 ...                                                                                                                                                                                                                                                                                                                                                                                            |
 
|                                                    |                                                                                                                          | n=3: A E                                                                                                                                                                                                                                                                                                                                                                                                         |
 
|                                                    |                                                                                                                          | odd n: A E1 E2 ...                                                                                                                                                                                                                                                                                                                                                                                               |
 
| C_nv                                               | C(NV)                                                                                                                    | n=2: A1 A2 B1 B2                                                                                                                                                                                                                                                                                                                                                                                                 |
 
|                                                    |                                                                                                                          | n=4: A1 A2 B1 B2 E                                                                                                                                                                                                                                                                                                                                                                                               |
 
|                                                    |                                                                                                                          | even n: A1 A2 B1 B2 E1 E2 ...                                                                                                                                                                                                                                                                                                                                                                                    |
 
|                                                    |                                                                                                                          | n=3: A1 A2 E                                                                                                                                                                                                                                                                                                                                                                                                     |
 
|                                                    |                                                                                                                          | odd n: A1 A2 E1 E2 ...                                                                                                                                                                                                                                                                                                                                                                                           |
 
| C_s                                                | C(S)                                                                                                                     | A' A''                                                                                                                                                                                                                                                                                                                                                                                                           |
 
| C_nh                                               | C(NH)                                                                                                                    | n=2: A.g A.u B.g B.u                                                                                                                                                                                                                                                                                                                                                                                             |
 
|                                                    |                                                                                                                          | n=4: A.g A.u B.g B.u E.g E.u                                                                                                                                                                                                                                                                                                                                                                                     |
 
|                                                    |                                                                                                                          | even n: A.g A.u B.g B.u E1.g E1.u E2.g E2.u ...                                                                                                                                                                                                                                                                                                                                                                  |
 
|                                                    |                                                                                                                          | n=3: A' A'' E' E''                                                                                                                                                                                                                                                                                                                                                                                               |
 
|                                                    |                                                                                                                          | odd n: A' A'' E1' E1'' E2' E2'' ...                                                                                                                                                                                                                                                                                                                                                                              |
 
| D_n                                                | D(N)                                                                                                                     | n=2: A B1 B2 B3                                                                                                                                                                                                                                                                                                                                                                                                  |
 
|                                                    |                                                                                                                          | n=4: A1 A2 B1 B2 E                                                                                                                                                                                                                                                                                                                                                                                               |
 
|                                                    |                                                                                                                          | even n A1 A2 B1 B2 E1 E2 ...                                                                                                                                                                                                                                                                                                                                                                                     |
 
|                                                    |                                                                                                                          | n=3: A1 A2 E                                                                                                                                                                                                                                                                                                                                                                                                     |
 
|                                                    |                                                                                                                          | odd n: A1 A2 E1 E2 ...                                                                                                                                                                                                                                                                                                                                                                                           |
 
| D_nd                                               | D(ND)                                                                                                                    | n=2: A1 A2 B1 B2 E                                                                                                                                                                                                                                                                                                                                                                                               |
 
|                                                    |                                                                                                                          | even n: A1 A2 B1 B2 E1 E2 ...                                                                                                                                                                                                                                                                                                                                                                                    |
 
|                                                    |                                                                                                                          | n=3: A1.g A1.u A2.g A2.u E.g E.u                                                                                                                                                                                                                                                                                                                                                                                 |
 
|                                                    |                                                                                                                          | odd n: A1.g A1.u A2.g A2.u E1.g E1.u E2.g E2.u ...                                                                                                                                                                                                                                                                                                                                                               |
 
| D_nh                                               | D(NH)                                                                                                                    | n=2: A.g A.u B1.g B1.u B2.g B2.u B3.g B3.u                                                                                                                                                                                                                                                                                                                                                                       |
 
|                                                    |                                                                                                                          | n=4: A.g A.u B1.g B1.u B2.g B2.u B3.g B3.u E.g E.u                                                                                                                                                                                                                                                                                                                                                               |
 
|                                                    |                                                                                                                          | even n: A.g A.u B1.g B1.u B2.g B2.u B3.g B3.u E1.g E1.u E2.g E2.u ...                                                                                                                                                                                                                                                                                                                                            |
 
|                                                    |                                                                                                                          | n=3: A1' A1'' A2' A2'' E' E''                                                                                                                                                                                                                                                                                                                                                                                    |
 
|                                                    |                                                                                                                          | odd n: A1' A1'' A2' A2'' E1' E1'' E2' E2'' ...                                                                                                                                                                                                                                                                                                                                                                   |
 

The symmetry labeling may depend on the choice of coordinate system.
For instance, B1 and B2 representations in C_nv are interchanged when
you rotate the system by 90 degrees around the z-axis so that x-axis
becomes y-axis and vice versa (apart from sign).


Molecular orientation requirements
----------------------------------

In order that AMS recognizes the (sub)symmetry of a molecule, the
molecule has to have a specific orientation in space.

* The origin is a fixed point of the symmetry group.

* The z-axis is the main rotation axis.

* xy is the \sigma_h -plane (axial groups, C(s)).

* The x-axis is a C_2  axis (D symmetries).

* The xz-plane is a \sigma_v -plane (C_nv  symmetries).

* In T_d, O, and O_h  the z-axis is a fourfold axis (S_4  or C_4) and
  the (111)-direction is a threefold axis.

* In T and T_h  the z-axis is a C_2 axis and the (111)-direction is a
  threefold axis.

* In I and I_h  the z-axis is a C_5 axis and the x-axis is a C_2  axis

If the system is symmetrized (and no symmetry is given in the System
block key) the molecular structure is rotated and translated into this
standard orientation.


Molecular orientation conventions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The molecular requirements for AMS may not fully determine the
orientation of the molecule, like for D_2h molecules. See Mulliken [1]
for standard conventions on the molecular orientation and notation. A
few of these conventions are listed below:

* in planar C_2v molecules the x axis is perpendicular to the plane of
  the molecule.

* in planar D_2h molecules the x axis is perpendicular to the plane of
  the molecule and the z-axis passes through the greatest number of
  atoms. If the last condition is not decisive, the z-axis should pass
  through the greatest number of bonds.

* in planar D_4h and D_6h molecules the C_2-axis passes through the
  greatest number of atoms. If the last condition is not decisive, the
  C_2-axis should pass through the greatest number of bonds.

[1] R.S Mulliken, *Report on Notation for the Spectra of Polyatomic
    Molecules*, Journal of Chemical Physics 23, 1997 (1955)
