cp2k/docs

CP2K Documentation

These are the source of the CP2K manual. They are published daily by this script.

To build a local version of the manual perform the following steps:

1. Create and activate a virtual Python environment:

   python3 -m venv ../docs_venv
   source ../docs_venv/bin/activate
   

2. Install the required Python packages:

   pip3 install -r ./requirements.txt
   

3. (optional) Build a CP2K binary and use it to generate the cp2k_input.xml file:

   ../exe/local/cp2k.psmp --xml
   

4. (optional) Generate Markdown pages from the cp2k_input.xml file:

   ./generate_input_reference.py ./cp2k_input.xml
   

5. Run Sphinx:

   make html
   

6. Browse the HTML output in the _build/html directory.

Tip

While the first invocation of Sphinx can be quite slow, subsequent builds are significantly faster thanks to its doctree cache. Nevertheless, a build with the full input reference can take several minutes and requires a lot of memory. So for development it's advisable to build without the input reference. To check cross-references one can generate the input reference and then remove all pages except the relevant ones.

---

Syntax Cheat Sheet

The CP2K manual uses Sphinx with the MyST parser for Markdown support. The following gives a quick overview of the syntax:

Headings

# A first-level heading

## A second-level heading

### A third-level heading

Basic Text Formatting

**bold text**

_italic text_

~~strikethrough text~~

`inline code`

For a all typography options see the MyST documentation.

Links

• Acronym: {term}`ADMM`
• Publication: [](#Wilhelm2018) ⚠️ see note below
• Another page: [](../optical/tddft)
• Subsection in another page: [](../optical/tddft.md#periodic-systems) ⚠️ with file extension
• Input section: [FORCE_EVAL](#CP2K_INPUT.FORCE_EVAL)
• Input keyword: [STRESS_TENSOR](#CP2K_INPUT.FORCE_EVAL.STRESS_TENSOR)
• External URL: <https://www.gromacs.org>
• External URL with label: [click here](https://github.com/cp2k/cp2k-examples/blob/master/qm_mm/Protein.pdb)

Note

The variable names in bibliography.F only mostly coincide with the citation keys in the docs. The best place to look up citation keys is the bibliography page.

Lists

1. First enumerated item
1. Second enumerated item


- A bullet point
- Another bullet point

Tables

| foo | bar |
| --- | --- |
| baz | bim |

For a all table options see the MyST documentation.

Math

Inline math: $A_{ia,jb}$.

Math block:
$$ \begin{align}
    A_{ia,jb} &= (\varepsilon_a^{GW}-\varepsilon_i^{GW})\delta_{ij}\delta_{ab}
    B_{ia,jb} &= 2 v_{ia,bj} - W_{ib,aj} \quad .
\end{align} $$

See also the MyST and MathJax documentation.

Notes and Warnings

```{note}
A note box.
```

```{warning}
A warning box.
```

For all available admonitions see the MyST documentation.

Code Blocks

```python
for i in range(10):
  print("Hello World")
```

Diagrams

```mermaid
block-beta
a b
a --> b
```

For details see the Mermaid documentation and also check out their great live editor.

Videos

```{youtube} teHVWKwBOTU
---
url_parameters: ?start=1500
align: center
privacy_mode:
---
```

The above example links to https://www.youtube.com/watch?v=teHVWKwBOTU at the 1500 seconds time mark.