Documenting input keywords: scmautodoc
**************************************

Input keywords should as much as possible be documented via the
"scmautodoc" custom-made directive
("$AMSHOME/userdoc/misc/scmautodoc.py"). The scmautodoc directive uses
the information from the json input definition files
("$AMSHOME/data/input_def/") to automagically generate keywords
documentation.


Simple usage
============

Simple usage: ".. scmautodoc:: json_filename keyword_name". For
example, this is how to document the 'PESPointCharacter' input block
in the 'ams.json' file:

**Example:**

   .. scmautodoc:: ams PESPointCharacter

**Result** (the first part is the **summary**, and the second part is
the **description**)

   PESPointCharacter
      Displacement float
      NegativeEigenvalueTolerance float
      NumberOfModes integer
      Tolerance float
   End

"PESPointCharacter"
   Type:
      Block

   Description:
      Options for the characterization of PES points.

   "Displacement"
      Type:
         Float

      Default value:
         0.04

      Description:
         Controls the size of the displacements used for numerical
         differentiation: The displaced geometries are calculated by
         taking the original coordinates and adding the mass-weighted
         mode times the reduced mass of the mode times the value of
         this keyword.

   "NegativeEigenvalueTolerance"
      Type:
         Float

      Default value:
         -0.0001

      Unit:
         Hartree/Bohr^2

      Description:
         The threshold in Hessian eigenvalue below which a mode is
         considered imaginary, i.e. indicating a transition state.
         This is a small negative number, as very small negative
         eigenvalues may be due to numerical noise on an essentially
         flat PES and do not indicate true transition states.

   "NumberOfModes"
      Type:
         Integer

      Default value:
         2

      Description:
         The number of (lowest) eigenvalues that should be checked.

   "Tolerance"
      Type:
         Float

      Default value:
         0.016

      Description:
         Convergence tolerance for residual in iterative Davidson
         diagonalization.

By default the scmautodoc directive will also create a **label for
cross-reference** called "json_filename-key-keyword_name". To
reference it, you can use the ":ref:" role with an explicit link
title. E.g.:

   See the :ref:`PESPointCharacter input block <ams-key-PESPointCharacter>` for more details.

For blocks, you can also explicitly specify the (ordered) list of
subkeys you want to document. E.g.:

   .. scmautodoc:: ams PESPointCharacter Pressure

will only document the "PESPointCharacter" block and the "Pressure"
sub-key.


scmautodoc options
==================

SCMAutodoc directive options:

":notrecursive:"
   Do not recursively document sub-keys. E.g. this:

      .. scmautodoc:: ams PESPointCharacter
        :notrecursive:

   will only document the block "PESPointCharacter", but will not
   document its sub-keys and sub-blocks.

":noref:"
   Do not create a label for cross-reference. This is necessary if the
   same key/block is documented multiple times (you cannot have
   multiple labes with the same name in sphinx).

":onlysummary:"
   Only creates the *summary* part of the documentation: E.g. this:

      .. scmautodoc:: ams PESPointCharacter
        :onlysummary:

   will result in the following:

      PESPointCharacter
         Displacement float
         NegativeEigenvalueTolerance float
         NumberOfModes integer
         Tolerance float
      End

":nosummary:"
   Do not create the *summary* part (i.e. only create the
   *description*)

":skipblockdescription:"
   Do not generate the *description* of the block (only generate the
   description of the sub-keys)

":collapselongchoicesinsummary:"
   This only affects the *summary*. If you have a *multiple_choice*
   input that has a ton of possible *choices*, you might not want to
   show all these *choices* in the summary. If you include this
   option, then the *choices* of *multiple_choice* inputs with more
   than 10 elements will be replaced with "[...]" (in the summary).


Non-trivial example
===================

**Example:**

   Optimizations are controlled via the ``GeometryOptimization`` block:

   .. scmautodoc:: ams GeometryOptimization Convergence MaxIterations OptimizeLattice
     :onlysummary:

   Convergence details are be specified in with the following options:

   .. scmautodoc:: ams GeometryOptimization Convergence MaxIterations
     :skipblockdescription:
     :nosummary:
     :noref:

**Result:**

Optimizations are controlled via the "GeometryOptimization" block:

   GeometryOptimization
      Convergence
         Energy float
         Gradients float
         Quality [VeryBasic | Basic | Normal | Good | VeryGood | Custom]
         Step float
         StressEnergyPerAtom float
      End
      MaxIterations integer
      OptimizeLattice Yes/No
   End

Convergence details are be specified in with the following options:

"GeometryOptimization"
   "Convergence"
      Type:
         Block

      Description:
         Convergence is monitored for up to 4 quantities: the energy
         change, the Cartesian gradients, the Cartesian step size, and
         for lattice optimizations the stress energy per atom.
         Convergence criteria can be specified separately for each of
         these items.

      "Energy"
         Type:
            Float

         Default value:
            1e-05

         Unit:
            Hartree

         Value Range:
            value > 0

         GUI name:
            Energy convergence

         Description:
            The criterion for changes in the energy. The energy is
            considered converged when the change in energy is smaller
            than this threshold times the number of atoms.

      "Gradients"
         Type:
            Float

         Default value:
            0.001

         Unit:
            Hartree/Angstrom

         Value Range:
            value > 0

         GUI name:
            Gradient convergence

         Description:
            Threshold for nuclear gradients.

      "Quality"
         Type:
            Multiple Choice

         Default value:
            Custom

         Options:
            [VeryBasic, Basic, Normal, Good, VeryGood, Custom]

         GUI name:
            Convergence

         Description:
            A quick way to change convergence thresholds: 'Good' will
            reduce all thresholds by an order of magnitude from their
            default value. 'VeryGood' will tighten them by two orders
            of magnitude. 'Basic' and 'VeryBasic' will increase the
            thresholds by one or two orders of magnitude respectively.

      "Step"
         Type:
            Float

         Default value:
            0.01

         Unit:
            Angstrom

         Value Range:
            value > 0

         GUI name:
            Step convergence

         Description:
            The maximum Cartesian step allowed for a converged
            geometry.

      "StressEnergyPerAtom"
         Type:
            Float

         Default value:
            0.0005

         Unit:
            Hartree

         Value Range:
            value > 0

         Description:
            Threshold used when optimizing the lattice vectors. The
            stress is considered 'converged' when the maximum value of
            stress_tensor * cell_volume / number_of_atoms is smaller
            than this threshold (for 2D and 1D systems, the
            cell_volume is replaced by the cell_area and cell_length
            respectively).

   "MaxIterations"
      Type:
         Integer

      Value Range:
         value >= 0

      GUI name:
         Maximum number of iterations

      Description:
         The maximum number of geometry iterations allowed to converge
         to the desired structure.


Free blocks / non-json keywords documentation
=============================================

Sometimes (e.g. for free blocks) you cannot create the keywords
documentation automagically. For such cases you should make the
**summary** keywords **description** by hand.

**Example:**

   .. _key-MyFreeBlock:

   .. code-block:: none

     MyFreeBlock
       label x y z
     End

   ``label x y z``:
     Here you should describe what ``label``, ``x`` ``y`` and ``z`` are.

**Result:**

   MyFreeBlock
     label x y z
   End

"label x y z":
   Here you should describe what "label", "x" "y" and "z" are.


scmautodocindex and scmautodoclist
==================================

There are two custom directives related to "scmautodoc":
"scmautodocindex" and "scmautodoclist". "scmautodocindex" generates a
list of links to the keywords which were documented using
"scmautodoc". "scmautodoclist" Automatically traverse a specific json
file and generates documentation for all the non-hidden keywords.

**Example:**

   Links to manual entries
   =======================

   .. scmautodocindex::


   Summary of all keywords
   =======================

   .. scmautodoclist:: ams

The keywords generated by "scmautodoclist" automatically get labels
for cross-referencing with the format "scmautodoclist-json_name-
keyword_name". E.g., to reference the PESPointCharacter generated by
scmautodoclist: ":ref:`PESPointCharacter input block <scmautodoclist-
ams-PESPointCharacter>`"
