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
1.4.2. More information
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 theyaml
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
optionalMP2 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.