How To Write

This manual is written using the org-mode markup language.

You can find some cheatsheets for org's markup you can checkout

• https://orgmode.org/quickstart.html
• http://xahlee.info/emacs/emacs/emacs_org_markup.html

Additionally, org-mode's manual is found here and a compact guide is found here.

Please notice that for this manual to build you will need a recent version of emacs, at least newer than Emacs 27. You probably can install it from the snapstore if you are using a supported distribution.

Just use latex as if you were in latex \[\int \sum\] and you can also use equations

and references work too \ref{eqseq}.

org-mode has several types of links.

The equivalent to tex's

\section{My section}
\label{sec-my-section}

My section~\ref{sec-my-section}

is

* My section
:PROPERTIES:
:CUSTOM_ID: sec-my-section
:END:

My section [[#sec-my-section]]
# or using org-ref's syntax
My section [[ref:sec-my-section]]

Checkout some other example in the Hyperlinks (Org Mode Compact Guide) page.

Some important examples for us are

[[file:algorithms/CoupledCluster/CoupledCluster.org::#maxiterations][maxIterations keyword]]

which links the heading maxiterations in the file CoupledCluster/CoupledCluster.org and gets rendered as maxIterations keyword.

In order to use a bibtex file in a page, you have to add it with the

bibliography:group.bib
# or
bibliography:./path-to-your-bib-file.bib,other-file.bib

and add citations like cite:&yourcite, for instance (Al-Hamdani et al. 2017; Grüneis et al. 2017).

Here an example of the rendered bibliography of the citations made up here.

If you want to write some code blocks, the equivalent of markdown's

```python
def fun():
  pass
```

in org is

#+begin_src python
def fun():
    pass
#+end_src

and it renders like:

def fun():
    pass

In order to document an object, the following sections have to appear:

Brief description

A brief description of what the object is and what it is commonly used for. Some further discussion of the object can be added here, for instance an example of an algorithm call to create the object or links to relevant algorithms.

Specification [Optional]

In the case of objects with a clear yaml specification, this should be explicitly provided here, see for instance the yaml specification of GridVectors.

Literature [Optional]

If in the previous sections a literature citation has been used, then add this section to list the references.

The following sections have to be provided:

Brief description

A very brief description of what the algorithm is doing when called. Limit this description to a couple of lines.

Algorithm call

An example of an algorithm call in yaml format. Optional parameters should have the following format in the sample

  # keyName: valueName    # optional

For instance for PerturbativeTriples

  - name: PerturbativeTriples
    in:
      coulombIntegrals: CoulombIntegrals
      amplitudes: Amplitudes
      slicedEigenEnergies: EigenEnergies
      # mp2PairEnergies: Mp2PairEnergies            # optional
    out:
      {}

Algorithm input

Explanation of the inputs of the Algorithm. It should contain a table with two columns, Keyword and Value, e.g.

Keyword	Value
coulombIntegrals	Coulomb Integrals
mp2PairEnergies optional	MP2 pair energies matrix

Optional inputs should be followed by an optional marker. The value field should be always a link to a detailed description of the input. If the value should be a commonly used object, it should be an id: like link to the corresponding object. Otherwise it can link to a section in the same document.

Algorithm output

This section should include:

• A table with the same format as for the input parameters for the output parameters.
• A section with a sample stdout output of a succesful run of the algorithm
• A section with the relevant yaml output of the algorithm. I.e., timings and flop count and so on needn't be included.

Computational complexity [Optional]

A discussion of the computational of the algorithm and some methods developed for it.

Theory [Optional]

A quick description of the theoretical background. If the method is well-known, refer to relevant articles.

Literature [Optional]

If in the previous sections a literature citation has been used, then add this section to list the references.