Contribute

SOLPS Tutorials is an open, collaborative project between SOLPS-ITER users. Contributions are warmly welcome, whether they be individual fixes, tutorial expansions or entirely new tutorials.

To clone the SOLPS-Tutorials repositoryopen_in_new to your local machine:

cd /new/home/for/solps/documentation
git clone git@github.com:iterorganization/SOLPS-Tutorials.git

Basic Git knowledge is required

Learn more in Introduction to Git, Git workflow for dummiesopen_in_new, CodeRefinery Git introopen_in_new or Contributing to Djangoopen_in_new.

Technical information

Our tutorials are written in Markdownopen_in_new and rendered as web pages with MkDocsopen_in_new. The SOLPS-Tutorials repositoryopen_in_new on GitHub is owned by the ITER Organisation. Their websiteopen_in_new is hosted by ReadtheDocsopen_in_new.

Repository structure:

docs: Markdown tutorials and their figures and files
- feature_blog: tutorials introducing advanced SOLPS features
- files: non-image files, mostly PDFs
- img: pictures used to illustrate the tutorials
- installing: tutorials on installing SOLPS
- my_first_simulation: tutorials taking a beginner through their first SOLPS simulation
- supplementary: tutorials covering everything around SOLPS
- css, javascript (technical stuff)
extras: additional content generated without MkDocs, most importantly the B2.5 switch documentation
mkdocs.yml: controls of the navigation bar on the left
README.md: basic information about SOLPS-Tutorials
.gitignore, .gitlab-ci.yml, requirements.txt (technical stuff)

Contribution guidelines

Respect the existing documentation structure. Before you write a tutorial, figure out if an equivalent is already present, and amend that if necessary.
- My first SOLPS-ITER simulation: A beginner's first contact with SOLPS-ITER, step-by-step instructions toward creating one's first SOLPS-ITER simulation with the narrow grids version. Keep it simple. Document frequently encountered problems, but don't explain anything in depth. If needed, describe the issue at length elsewhere (e.g. in Common pitfalls) and link to it.
- Feature blog: Largely independent ways to make a SOLPS simulation more complicated. Explain why one would want to adopt a particular feature, what are the benefits and costs, and how to do it. You can go into detail, but don't paraphrase or copy-paste existing documentation. Link to it instead.
- Supplementary material: Everything that didn't fit in the first two categories.
Do not duplicate. If something is explained elsewhere (SOLPS manual, ITER SharePoint...) and you find yourself paraphrasing it or, God forbid, copy-pasting it, link to it instead.
Kateřina's three postulates for writing SOLPS Tutorials:
1. You will forget everything you don't write down.
2. You can't keep any notes other than SOLPS Tutorials.
3. Someone else will read SOLPS Tutorials.
Use admonitions (colour boxes) for information outside the main tutorial flow.
Use in-text icons for external links, downloadable files, email addresses and "under construction" warnings.
Keep lists short. (They turn up as long paragraphs in the search bar, clogging the output. This list is borderline.)
All the .md files have to be accessible from the navigation sidebar. Put new files into mkdocs.yml.
Use the mother tongueopen_in_new. Read the instructions aloud and see if they flow off the tongue or make you choke. Write as if you were explaining it to a confused student. Sounding too familiar is better than sounding too stiff.

How to publish your contribution

1. Get a clean local copy of SOLPS Tutorials

If you don't have a local copy of SOLPS Tutorials yet, clone one.

cd /new/home/for/solps/documentation
git clone git@github.com:iterorganization/SOLPS-Tutorials.git

If you already have a copy, clean it. It makes creating commits easier.

cd SOLPS-Tutorials
git fetch
git status

If you see you're up-to-date with master, you're good to go.
If you are on master but you're missing the last updates, download them to your local copy.
```
git pull
```
Kateřina usually finds herself on a different, long-forgotten branch, from the last time she was contributing and forgot to switch back to master. Usually there are modified files as well. In such a case, it's easiest to make a new local copy of the repository.
```
# Rename the old copy
cd ..
mv SOLPS-Tutorials SOLPS-Tutorials_definitely_not

# Clone another, fresh copy of the master branch
git clone git@github.com:iterorganization/SOLPS-Tutorials.git
```
Proceed according to the instructions below and watch out for mentions of SOLPS-Tutorials_definitely_not.

2. Create a new branch

Write permissions to the SOLPS-Tutorials repository

The SOLPS-Tutorials repositoryopen_in_new is open for everyone to read and clone, but has only a limited circle of contributors with write permissions. Circumvent this by creating your own fork, a perfect copy of the SOLPS-Tutorials repository which doesn't affect the original but allows submitting pull requests. Once you've made it to the list of major contributors, you will be granted write permissions and will be able to create branches and create pull requests straight to SOLPS-Tutorials.

To create your own fork of SOLPS-Tutorials:

Go to the GitHub repositoryopen_in_new of SOLPS Tutorials. In the upper right, click Fork.
Click Create fork. This will create the repository your_username/SOLPS-Tutorials.
In the tutorial below, do everything in your fork instead of the SOLPS-Tutorials repository. Create a new branch, commit your changes. Finally, go to the GitHub page of your fork and click Contribute instead of creating a pull request. This will initiate a pull request directly to the original SOLPS-Tutorials repository.

Like SOLPS-ITERopen_in_new itself, SOLPS Tutorials accept new contributions via pull requestsopen_in_new. This allows Kateřina to review documentation changes and request edits before the contributions go live. Thus, everybody (including her) has to tread the mill of making new branches, creating pull requests, and merging branches into master.

To create a new branch of SOLPS-Tutorials:

Visit the list of SOLPS-Tutorials branchesopen_in_new on its GitHub page. On the upper right, click New branch. (If the button is not there, you don't have write permissions. Create a fork of the repository according to the instructions above.) Select master as the source. Name the branch using the common conventionsopen_in_new, using branch prefixes such as feature/, fix/ or refactor/.

Switch to the new branch on your local machine.

# Download the information that there is a new remote branch
git fetch

# Create a local copy of that branch
git checkout -b feature/my_new_branch origin/feature/my_new_branch

The -b will create your own local branch which tracks the remote branch. It prevents the detached HEAD state.

Now it's finally time to get writing.

3. Write and commit your contribution

If you have a SOLPS-Tutorials_definitely_not, this is where you integrate it into the fresh copy.

Paste the modified contents of SOLPS-Tutorials_definitely_not into your new shiny SOLPS-Tutorials.
Resolve conflicts. The Source Control tab in our editor of choice, Visual Studio Code, works well. Compare your old files with the newest master, get familiar with what has been done while you were sleeping and modify your past contributions accordingly. Use the Revert button/option to undo your "deletions". You don't want to overwrite any work others have done in the meantime.

Don't postpone resolving conflicts

I know you're impatient to get started on the actual work, but if you postpone dealing with the conflicts, they will become a headache. You'll invest effort into rewriting documentation that's out-of-date. At the end of it, when you're making your commits and merging into master, you will have to deal with the conflicts anyway. And it will be harder, because you've just polished your contribution and you want to send it out there already. But now not only you are bogged down by Git conflicts; you also have to rewrite your contribution to accommodate the work of others.

(Note: Kateřina is getting so deep into this because she's lazy. This box is for her future self, who is likely to go: "Ahh, who cares about Git conflicts, we'll resolve them later.")

For writing your contribution, we recommend the Visual Studio Code as editor. Make generous use of Markdown extensions and icons where appropriate.

To commit your changes:

Go through the changes you've made. Stage them into logical units and commit them with informative commit messages. The Source Control tab in Visual Studio Code is more convenient than doing this in the command line.

Basic commit guidelines:
- It's preferable to make a large number of atomic commits ("Change recommended gas puff value", "Add section on lowering grid resolution") as opposed to one all-encompassing commit ("I'm done for today", "Various edits").
- Commit messages should be so informative that you don't need to check the commit line by line to know what it did.
- Individual commits should form logical wholes. If you aren't done yet (you're in the middle of rewriting an entire section), don't commit it yet.
- Refer to How to write better Git commit messagesopen_in_new.
Once you have a series of commits acknowledging all the changes you've made to the Tutorials, upload them to your branch in the central repository.
```
git push
```

To merge these changes into the master branch, you will create a pull request in the next step.

4. Create a pull request

On the SOLPS-Tutorials GitHub pageopen_in_new, create a new pull request which merges your branch back into master. Add Kateřina as a reviewer so she can check the changes and give you a deserved pat on the back. Expect a response within 3 days.
If Kateřina requests edits, return to the previous subsection. Pull her changes if there are any, write your changes, commit them, push them. They will automatically fall within the existing pull request.
Once your contribution has gone live, switch to the master branch on your local machine. (Kateřina always forgets about this step.)
```
git checkout master
git pull
```
It takes about two hours for changes in master to show up on the webpage.

Thank you for contributing to SOLPS Tutorials!

Recommended editors

SOLPS Tutorials are written in Markdownopen_in_new, which is little more than plain text with a few basic formatting marks. Any text editor suffices to edit the tutorials. However, to edit and display the rendered results (like seeing actual bullet points instead of -), we recommend Visual Studio Codeopen_in_new, which includes a Markdown preview out-of-the-box. To display the rendered results, click on the icon with the page and magnifying glass in the top right corner of the editor.

Note that some of the fancier extension features (such as "external link" icons) will not be displayed properly by VC Code. To preview how the rendered page will look on the SOLPS Tutorials web, install MkDocs locally.

Markdown extensions

To make the SOLPS Tutorials easier to read, we use extensions of the Markdown syntax, such as boxes with useful tips. Consider using them to break up the text flow and mark up notes and details. They are implemented using Python Markdown Extensionsopen_in_new, which are are pre-installed in MkDocs as a Python package. Use

pip install --upgrade pymdown-extensions

to get the most recent version. Note that the extensions won't be displayed properly in a pure-Markdown preview in VS Code. You need to build the MkDocs locally or let it be built in a CI pipeline to see the final result.

The setup of Markdown extensions is easy. Just make sure the specific extension is enabled in the mkdocs.yml config:

markdown_extensions:
  - pymdownx.arithmatex:
      generic: true   # Options can be specified like this
  - pymdownx.blocks.tab
  - ... # Add more extensions here

Currently enabled extensions:

pymdownx.arithmatexopen_in_new: LaTeX math equations in $...$ and $$...$$ blocks
pymdownx.superfencesopen_in_new: better fenced code blocks with syntax highlighting
- Can add title, add line numbers, highlight lines
pymdownx.inlinehiliteopen_in_new: same as superfences, but for inline code snippets
- Add shebang #!python at the start, followed by a space and the code line
pymdownx.blocks.* several block-based features that share a common syntax using /// fences
- pymdownx.blocks.admonitionopen_in_new: highlighted box with note, warning, etc.
  - Predefined types: note, danger, tip, warning (also attention, hint, caution, error, but they all seem to be styled like note)
- pymdownx.blocks.definitionopen_in_new: indented list of terms and their definitions
- pymdownx.blocks.detailsopen_in_new: similar to admonition, but collapsible
- pymdownx.blocks.tabopen_in_new: tabbed content blocks
  - Fence the content with lines /// tab | Tab 1 name and ///, repeat for each tab

LaTEX math

Math written in LaTeX syntax, both inline expressions with $P_{SOL}$ ( $P_{SOL}$ ) and equations:

\[ \int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi} \]

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

Admonitions

There are four admonition box styles available: hint (blue), tip (green), warning (yellow) and danger (red). The former three are self-explanatory; danger usually denotes a piece of information or an entire section focused on a particular machine or server.

Admonition box displaying a tip:

Hot tip

SOLPS Tutorials will help you learn SOLPS-ITER.

/// tip | Hot tip
SOLPS Tutorials will help you learn SOLPS-ITER.
///

Admonition box with a warning:

Warning

SOLPS-ITER is not for the feeble of mind.

/// warning | Warning
SOLPS-ITER is not for the feeble of mind.
///

Admonition box with a hint or a note:

Helpful hint

Life will get better if you sleep a lot.

/// hint | Helpful hint
Life will get better if you sleep a lot.
///

Admonition box with very specific information:

IPP Prague

COMPASS was a sheath-limited tokamak.

/// danger | IPP Prague
COMPASS was a sheath-limited tokamak.
///

Code blocks

Code block with syntax highlighting and a title (e.g. a filename):

b2.neutrals.parameters

crcstra= 'W', 'E', 'S', 'S', 'N', 'C', 'V', 'T',

```{.fortran title="b2.neutrals.parameters"}
crcstra= 'W', 'E', 'S', 'S', 'N', 'C', 'V', 'T',
```

Fancy two-tab code block with highlighted lines showing the same parameter for both alternatives of Eirene input files.

Formatted (input.dat)JSON (eirene.input.json)

SURFMOD_4_CARBON_SPT_PUMP_580K
    1     2     0     0     1
1.20600E+03-5.00000E-02 0.00000E+00 0.00000E+00 0.00000E+00-1.00000E+00
1.00000E+00 9.00000E-01 1.00000E+00 1.00000E+00 5.00000E-01 1.00000E+00
1.00000E+00 1.00000E+00 0.00000E+00 0.00000E+00 1.00000E+00

{
  // ...
  "REFLECTION_MODELS": {
    "MANUAL": "http://www.eirene.de/eirene.pdf#subsection.2.6.1",
    // ...
    "SURFMODS": [
      {
        "NAME": "SURFMOD_4_CARBON_SPT_PUMP_580K",
        // ...
        "RECYCT": 9.0E-01,
        // ...
      }
    ]
  }
}

/// tab | Formatted (`input.dat`)
```{.python hl_lines="4"}
SURFMOD_4_CARBON_SPT_PUMP_580K
    1     2     0     0     1
1.20600E+03-5.00000E-02 0.00000E+00 0.00000E+00 0.00000E+00-1.00000E+00
1.00000E+00 9.00000E-01 1.00000E+00 1.00000E+00 5.00000E-01 1.00000E+00
1.00000E+00 1.00000E+00 0.00000E+00 0.00000E+00 1.00000E+00
```
///

/// tab | JSON (`eirene.input.json`)
```{.json hl_lines="10"}
{
  // ...
  "REFLECTION_MODELS": {
    "MANUAL": "http://www.eirene.de/eirene.pdf#subsection.2.6.1",
    // ...
    "SURFMODS": [
      {
        "NAME": "SURFMOD_4_CARBON_SPT_PUMP_580K",
        // ...
        "RECYCT": 9.0E-01,
        // ...
      }
    ]
  }
}
```
///

Icons

To make SOLPS Tutorials easier to read, we use icons from the Material Symbols set provided by Google. Everything is set up in the MkDocs config. To use the icons, simply search for them on Google Fontsopen_in_new. Click on an icon to open a sidebar, scroll to the Inserting the icon section and copy the <span> tag into your Markdown text.

Note that, like the Markdown extensions, the icons will not show up in Markdown editors such as Visual Studio Code. They will only show on the final webpage or when you generate a preview of the MkDocs yourself.

External link (pointing outside SOLPS Tutorials): ITER Sharepointopen_in_new

ITER Sharepoint
<span class="material-symbols-outlined">open_in_new</span>

Link to a (downloadable) file: Katka's PhD thesisdownload

Katka's PhD thesis
<span class="material-symbols-outlined">download</span>

Under construction or to do:

TODO construction: Update the tutorials.

> **TODO** <span class="material-symbols-outlined">construction</span>:
> Update the tutorials.

Email address: mail hromasova@ipp.cas.cz

<span class="material-symbols-outlined">mail</span>
[hromasova@ipp.cas.cz](mailto:hromasova@ipp.cas.cz)

Preview your changes to SOLPS Tutorials

Quick edits of SOLPS Tutorials are best done in a Markdown editor, which will render the files in real time. However, most of the fancy extensions will not be rendered in that way. There are two options to view the final result before it goes live after merging a pull request into the master branch:

A complete webpage preview is generated once you open a pull requestopen_in_new to master. Simply wait a couple of minutes for the ReadTheDocs bot to post the link in the pull request's thread.

Build the pages locally:

# Go to the cloned repository
cd SOLPS-Tutorials

# Create a virtual environment and install the libraries
# This may take a few minutes the first time
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Serve and automatically rebuild on any file modifications
mkdocs serve

IPP Prague

When on COMPASS servers, it's easiest to build the pages locally on Soroban:

# Log in to your IPP Prague work station
# If you log into the Soroban front instead, add a tunneling request
ssh -X jirakova@soroban.tok.ipp.cas.cz -L 8000:127.0.0.1:8000
# 8000 is the port being tunneled
# Adjust the port according to where MkDocs creates the documentation

# Load Python 3.8
module load python/3.8-anaconda-2021.05

Ctrl + right click on the link on the last line of the command line output, and a live preview of SOLPS Tutorials will open in your web browser. Every time you save a file, its preview will be updated on the page.

Sub-pages located in ./extras may be handled differently. Refer to corresponding readmes in the ./extras folder for build instructions and/or check the definition of automated pipeline in .gitlab-ci.yml file.