How To Write

Table of Contents

1. Engine

1.1. Introduction

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

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

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.

1.1.1. Installing a minimal emacs version locally

In case you are having some problems installing emacs and you just want to get a minimal emacs version to build the pages, consider adapting this script

set -eu

url="https://github.com/emacs-mirror/emacs/archive/refs/tags/emacs-28.0.90.tar.gz"

mkdir -p ./emacs
wget $url -O - | gunzip |  tar xvf - -C ./emacs --strip-components=1

sudo apt-get install \
     libxml2-dev \
     gnutls-dev

cd ./emacs

./autogen.sh
./configure \
    --with-x-toolkit=no \
    --with-xml2 \
    --with-xpm=ifavailable \
    --with-gif=ifavailable \
    --with-tiff=ifavailable \
    --with-gnutls=ifavailable

make -j

This script installs on a debian-based system the library xml2 and gnutls and downloads and builds emacs 28 in the current directory.

You can use this emacs binary by writing a config.mk file with the following contents

EMACS_BIN = ./emacs/src/emacs

1.2. Math

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

\begin{equation} \label{eqseq} \hat{H} \psi = E \psi \end{equation}

and references work too \ref{eqseq}.

1.3. Links

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.

1.4. Bibliography

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

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.

1.4.1. Literature

Al-Hamdani, Yasmine S, Mariana Rossi, Dario Alfe, Theodoros Tsatsoulis, Benjamin Ramberger, J Gerit Brandenburg, Andrea Zen, et al. 2017. “Properties of the Water to Boron Nitride Interaction: From Zero to Two Dimensions with Benchmark Accuracy.” The Journal of Chemical Physics 147 (4): 044710. http://doi.org/10.1063/1.4985878.
Grüneis, Andreas, So Hirata, Yu-ya Ohnishi, and Seiichiro Ten-no. 2017. “Perspective: Explicitly Correlated Electronic Structure Theory for Complex Systems.” The Journal of Chemical Physics 146 (8): 080901. http://doi.org/10.1063/1.4976974.

1.4.2. More information

You can find more information in videos like this by the org-ref author.

1.5. Src blocks

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

2. Test locally

To build locally just make

make publish

You can also serve the pages to simulate how they will be deployed using

make serve

and open the url in your browser http://127.0.0.1:8888.

You can also combine both by doing

make publish serve

periodically and refreshing your browser.

3. Conventions

3.1. How to document an Object

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.

3.2. How to document an Algorithm

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.

Created: 2022-09-19 Mon 15:00