Skip to content

Latest commit

 

History

History
248 lines (195 loc) · 6.87 KB

how-to-write.org

File metadata and controls

248 lines (195 loc) · 6.87 KB

How To Write

Engine

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.

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

Math

Just use latex as if you were in latex $$∫ ∑$$ and you can also use equations

\begin{equation} \label{eqseq} \hat{H} ψ = E ψ \end{equation} and references work too \ref{eqseq}.

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.

Bibliography

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 cite:&al2017properties;&gruneis2017perspective.

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

Literature

bibliography:group.bib

More information

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

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

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.

Conventions

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.

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.
KeywordValue
coulombIntegralsCoulomb 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.