Writing Input Parameter Documentation

The input parameters of exciting are defined and documented in the files in the schema directory. These {.xsd} files describe the schema of the exciting input file. The master file is input.xsd. It includes definitions of its child elements via <xs:include/>. The include element is part of the XML Schema language such each of the schema files constitute a valid schema. For some processing, the files have to be combined to one long file. The template schemaexpand.xsl cares for that and the results are stored in excitinginput.xsd. The scripts that generate the documentation expect the sub-schema files to have only one element in their root and that the file is named with the element name. For a more detailed picture se the Step by step howto update input docu

The documentation is generated by the make file. make doc generates the latex input reference and the wiki markup for wikidot.

Each element, attribute and type declarations may contain an xs:annotation element with an xs:documentation element. The xs:documentation element contains a documentation string. This string is used to create the online-help (input-reference-helium) and is used in a few other places where input parameter descriptions are usefull. There are templates to convert the schema into a wiki page and into a Latex document.

This templates use a few formatting markup elements. They are as follows.

displaymath

Latex equation display.

inlinemath

Inline Latex.

pre

Pre-formatted text.

it

Italic.

bf

Bold.

pre-bf

Bold and preformatted.

filename

Formats file name as bold italic pre.

green

Green text.

blue

Blue text.

attref

Make link link from attribute name. If the attribute name has multiple occurrences the parent element can be specified by setting the parent attribute of the attref element. This is useful if the link would be ambiguous otherwise.

elementref

Make link link from element name.

list

Encloses list items.

li

List item.

p

Used as empty tag, it inserts a paragraph break.

a

Hyperlink (use href attribute as in http).

exciting

Empty tag inserts the exciting program name in the right format.

Example

    <xs:annotation>
    <xs:documentation> In order to perform an <exciting/> calculation an XML input file called
        <filename>input.xml</filename> must be provided. <p> This web page lists all
          <blue>elements</blue> and <green>attributes</green> that can be used in the input file of
        an <exciting>exciting</exciting> calculation: </p>
      <list>
        <li>
          <blue>elements</blue> are defined according to the <a
            href="http://en.wikipedia.org/wiki/XML#Key_terminology">general XML conventions </a>.
            <it>Example:</it> The element <elementref>groundstate</elementref> is used to set up a
          self-consistent calculation of the ground-state energy. </li>
        <li>
          <green>attributes</green> are defined according to the <a
            href="http://en.wikipedia.org/wiki/XML#Key_terminology">general XML conventions </a>. An
          attribute is always connected to an element. In <exciting>exciting</exciting> an attribute
          generally specifies a parameter or a set of parameters which are connected to the
          corresponding element. <it>Example:</it> The attribute <attref>xctype</attref> of the
          element <elementref>groundstate</elementref> defines which exchange-correlation potential
          is used in the self-consistent calculation. </li>
      </list>
      <p> The input file of an <exciting>exciting</exciting> calculation is named
          <filename>input.xml</filename>. A simple example for an input file can be found <a
          href="http://exciting-code.org/input-file-format-overview">here</a>. The input file
          <filename>input.xml</filename> must be a valid XML file and it must contain the root
        element <elementref>input</elementref>. </p>
      <p> Unless explicitly stated otherwise, <exciting>exciting</exciting> uses atomic units (
          <inlinemath>\hbar = m_{e} = e = 1</inlinemath> ): </p>
      <list>
        <li> Energies are given in Hartree: <p>
            <inlinemath> 1\ {\rm Ha} = 2\ {\rm Ry} = 27.21138386(68)\ {\rm eV} = 4.35926\cdot
              10^{-18}\ {\rm J}</inlinemath>
          </p>
        </li>
        <li> Lengths are given in Bohr: <p>
            <inlinemath> 1\ a_{\rm Bohr}\ = 0.52917720859(36)\ {\buildrel _{\circ} \over
              {\mathrm{A}}} \ = 0.52917720859(36) \cdot 10^{-10} \ {\rm m}</inlinemath>
          </p>
        </li>
        <li> Magnetic fields are given in units of <p>
            <inlinemath> 1\ {\rm a.u.} = \displaystyle\frac{e}{a_{\rm Bohr}^2}\ = 1717.2445320376\
              {\rm Tesla}. </inlinemath>
          </p>
        </li>
      </list>
      <p> Note: The electron charge is positive, so that the atomic numbers
          <inlinemath>Z</inlinemath> are negative. </p>
    </xs:documentation>
    <xs:appinfo>
      <title>
        <exciting>exciting</exciting> input reference </title>
      <root>input</root>
    </xs:appinfo>
  </xs:annotation>

The result is the first section in input reference