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>`