The SOLPS-ITER codebase

Get the SOLPS-ITER access

See also the manual, section 1.1.

As the name suggests, SOLPS-ITER is a recent incarnation of the SOLPS code maintained (mainly) by the good folks at the ITER site. The code is hidden away in an internal git repository, but access is usually granted to anyone interested if they ask nicely. The main prerequisite is to be employed at the institute (IPP Prague) or at least have someone from the institute vouch for you (e.g. the supervisor in case of students). Follow these steps to gain access:

Write to Xavier Bonnin (xavier.bonnin@iter.org) that you would like to use SOLPS-ITER and ask him to give you access to the codebase. Affiliation with a EuroFusion beneficiary is required, use the @ipp.cas.cz email address if possible. Follow his instructions to:
- Get an IDM (ITER Document Management) account set up, if you don't have one already.
- Post a ticket asking for access to several git repositories, namely the SOLPS-ITER repo and several related ones.
- Additionally, Xavier will add you to his mailing list and SOLPS-ITER Slack.
Go to https://git.iter.org/plugins/servlet/ssh/account/keys.
Upload your public SSH key here (how to generate a SSH key).
You should now be able to download the source code of SOLPS-ITER using git:
```
git clone ssh://git@git.iter.org/bnd/solps-iter.git
```

Follow by reading the sections below to learn how to actually install SOLPS-ITER with all of its necessary dependencies.

Tip

Make sure to check out the list of Useful links, including the Confluence page, SharePoint, and more.

Where and how to install SOLPS-ITER

The SOLPS-ITER code has a complicated list of dependencies, which makes it complicated^2 for a common mortal to install it anywhere they would like. It is highly recommended to use a properly configured site (see below) or a container installation (see below) to handle the dependencies.

Properly configured site

A properly configured site is defined as an HPC server where

all required dependencies are installed
and the site-specific configuration files are committed to the main SOLPS-ITER repository

A complete list of recognized sites is available in the SOLPS-ITER manual, section 1.3.

On a properly configured site, the installation is fairly straightforward. Use git to download the source code and use gmake / make to compile it:

# 1. Clone the repository and enter the directory
git clone ssh://git@git.iter.org/bnd/solps-iter.git
cd solps-iter

# 2. Select your code version branch
git checkout master  # master, develop, release/3.1.1, feature/wg_workflow, etc.

# 3. Initialize and update everything
git pull
git submodule update --init

# 4. Compile (recommended targets: solps, solps_mpi), clean before for good luck
tcsh
source setup.csh
gmake clean_solps
gmake clean_solps_mpi
gmake solps
gmake solps_mpi

Tip

To switch to a different solps branch later on, repeat steps 2 + 3 + 4 with a different branch name.
To update the code anytime and apply the most recent bugfixes, repeat steps 3 + 4.

See How to update SOLPS-ITER below for more info about these two actions. Make sure to initialize the SOLPS-ITER environment before compilation (tcsh and source setup.csh) as described below. Refer to Git for dummies below in case of issues with git.

Recommended sites and options

At this moment, solps-doc offers the following list of verified options where to run the SOLPS-ITER simulations, including properly configured sites, not-at-all configured sites and container installations. The list:

Marconi/Gateway (Eurofusion) - officially supported, properly configured site
- available to all Eurofusion beneficiaries, no need to register any specific project (e.g. compared to IT4I)
- recognized as ITM, MARCONI in the manual
COMPASS Soroban (in-house) - properly configured site since v3.0.9, supports containers
- available to IPP Prague employees and students
- recognized as IPPCR in the manual
- container installation is well tested there, see below
IT4I.cz (Czech Republic) - supports containers
- requires application for a 9-month project
- servers are often upgraded, which may break things, but a container installation is resistant to this, see below
- there is also a legacy installation guide that explains an ancient installation process, without any guarantee of success, probably do not even read it
Container installation (portable) - a quick and clean installation of SOLPS-ITER, pre-built containers with zero setup are available. Requires Apptainer or Docker software installed on the target machine. Apptainer is a fairly standard HPC software, ask the respective IT support to install it if it is missing. Docker is a more common software, but it is not always available on HPC servers mainly due to security considerations.

While installing SOLPS-ITER, keep in mind that the solps-doc tutorials somewhat deviate from what is described in the SOLPS-ITER manual and in the README in the repository. But they are proof-tested and based on experience. Feel free to follow the SOLPS-ITER manual (most recent version here) to avoid problems and find solutions, and hopefully not the other way around.

You may have noticed, that any information about installation of the aforementioned "complicated dependencies" was tactfully avoided, mainly because it is complicated. It is best to get in touch with someone with previous experience in this case (us, Xavier Bonin, etc.). If you are adventurous, look for the SETUP/easybuild-local.sh script in the SOLPS-ITER repository, which is currently the recommended tool for the job and it should install all the dependencies for you in the form of Environmental modules. As for the documentation, there are comments in the script and there are a few words written about it in the SOLPS-ITER GUI docs.

How to initiate the SOLPS-ITER work environment

Once you have downloaded, configured, and compiled SOLPS-ITER by following one of the installation guides above, you may proceed to run the code. In every session, you must first initiate the SOLPS-ITER work environment. This is done by running the setup.csh script, which sets up the necessary environment variables and commands.

Log in to the server where your SOLPS-ITER is installed.
```
ssh -X username@soroban.tok.ipp.cas.cz
```
In this example, it is the Soroban server at IPP Prague, but it can be ITM Gateway, one of the IT4Innovations servers or something else. Refer to Remote access. In Soroban, additionally ask the resource management system for some computational power.
```
qsub -IX
```

Enter your SOLPS-ITER installation folder.

cd /net/soroban-node-06/scratch/jirakova/solps/solps-iter

Initiate the tcsh shell.
```
tcsh
```
Load the environment variables and commands.
```
source setup.csh
```
Set the device to COMPASS (or whatever you're modelling).
```
setenv DEVICE compass
```
You can skip this step if you aren't going to use DivGeo, Carre or Triang.

If you've just installed SOLPS-ITER at Soroban (IPP Prague server) and the work environment isn't working due to module: command cannot be found, fix it by following these steps:

Log into Soroban.
```
ssh -X username@soroban.tok.ipp.cas.cz
```
Create or edit the file .tcshrc in your home directory.
```
nano ~/.tcshrc
```
Add the following line in the file:
.tcshrc
```
source /usr/share/modules/init/tcsh
```
Press Ctrl+S and Ctrl+X to save and close the file. Then, reload the .tcshrc file to make the module command available for this session.
```
source ~/.tcshrc
```
Next time you launch tcsh, the module command should be available automatically.

How to update SOLPS-ITER

SOLPS-ITER is a living code which constantly receives tweaks and bug fixes, as evident from the User Forums which take place approximately once a month. Users that don't need to use a specific version of the code should therefore stay in touch with the latest developments by updating their code regularly.

Refer also to the bottom of the ITER Git repository of SOLPS-ITER or to chapter 1.1 of the manual.

There are two ways to update the code, a simple one and a manual one. They both begin the same:

Go to where your SOLPS-ITER is installed ($SOLPSTOP in the jargon) and initiate the SOLPS-ITER work environment.

ssh -X username@soroban-node-06
cd /scratch/jirakova/solps/solps-iter
tcsh
source setup.csh
setenv DEVICE COMPASS          # optional, only for using DivGeo

a) Simple, no-brainer version

This is only available for master or develop branches.

Depending on whether you want to use the master or develop branch, write the command

solps-iter_update

or

solps-iter_update_develop

and wait approx. 30 minutes. This will take care of everything, including the compilation of the newest version of the SOLPS-ITER manual (in $SOLPSTOP/docs/solps/solps.pdf). If you don't know the difference between the master and the develop branch, use the master branch. It is more stable, meaning it should not ever be in a broken/buggy state, and it is updated a few times per year (as of May 2024). The develop branch is updated more frequently, but it usually still quite reliable.

b) Advanced, high-control version

These steps are derived from the installation steps of the properly configured site described above. If you want to understand what's going on here, check out Git for dummies.

Check whether you have modified any source code files in the solps-iter folder and not committed them.
```
git status
```
If there are any, you should use your git knowledge to commit them, stash them, or discard the changes. New (untracked) files are usually not a problem.
(Optional) At this moment, you may switch to a different branch if want to do that. Otherwise skip this step.
```
git checkout feature/wg_workflow
```

Download any changes made to SOLPS-ITER since your last update.

git pull  # Note that `git fetch` is called automatically by `git pull`
git submodule update --init

Compile the code using gmake or make, depending on how many letters you feel like spelling today. Fun fact: on most standard Linux distributions make = gmake, but in some exotic cases make points to something else, as discussed here. Thus, gmake should be preferred, just to be on the safe side. The more you know.

Clean when switching branches

It is highly recommended to clean everything up by building the corresponding clean_* targets (or simply gmake clean_all) when switching code branches or versions. It is usually not necessary when updating the same branch.

Start with the necessary depend target and follow with any targets you need, usually named solps_*. For example:
```
gmake depend
gmake solps
gmake solps_mpi
```
The complete list of available compilation targets is available by running gmake help.

Git for dummies

Simply put, Git is a version-tracking system which allows multiple users to collaborate on a single project without getting in each other's way. It is immensely complex, best used from the command line, dauntingly inscrutable at first and delightfully rewarding once you master it. The SOLPS-ITER code is developed using Git.

Tip

In addition to the guide below, feel free to refer to one of many well-written Git tutorials on the internet to get a more complete picture, for example here. And bookmark the official docs. Learning Git properly is a good investment of your time, as it is used everywhere these days.

The story goes like this. In the password-protected servers of the ITER Organisation, there is a repository containing the source code of SOLPS-ITER. The source code is mostly composed of text files written in various programming languages; there are also some pictures and other files. The source code is what Git keeps track of. It remembers what changes to the code who proposed, when and why, if they were accepted, how they were discussed, and so on.

Having the appropriate clearance, anyone can download the source code of SOLPS-ITER to their computer. The easiest way is to install Git (it comes preinstalled in many operating systems) and run the git clone repository_location command. This connects the computer to the central code repository (called "remote" repository, sometimes origin) and downloads a copy of the current version of the source code. Now, the source code is not enough to run SOLPS-ITER, just like the blueprint of a bed cannot be slept in. First, you must compile the code on your computer, from the local copy of the source code, using the make command. Downloading the source code is quick; compiling it takes hours. At the end of it, you have a living programme which can be used to run simulations.

As time goes on, your local copy of SOLPS-ITER will grow outdated. Updates to the "master branch" (the most trustworthy version of the code) come once in a few weeks or months, and they can contain important bug fixes and plasma physics updates. To check whether an update is available, go to your SOLPS-ITER installation directory ($SOLPSTOP) and run:

git fetch

This will download the newest information (but will not apply any changes) from the origin repository at ITER Organisation. Then run:

git status

This will inform you whether any updates are available. You might, for instance, see the output:

On branch master
Your branch is up-to-date with 'origin/master'.

This means there are no updates available and your code is still fresh. If, however, you see something like "you are 1 commit behind 'origin/master'", it's a good time to update the code, starting with

git pull

Additionally, you might see something like:

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)
  (commit or discard the untracked or modified content in submodules)

    modified:   modules/B2.5 (untracked content)
    modified:   modules/Carre (untracked content)
    modified:   modules/DivGeo (untracked content)
    modified:   modules/Eirene (untracked content)
    modified:   whereami

Untracked files:
  (use "git add <file>..." to include in what will be committed)

    SETUP/config.IT4ICZ.ifort64
    SETUP/config.SOROBAN.ifort64
    SETUP/setup.csh.IT4ICZ.ifort64
    SETUP/setup.csh.SOROBAN.ifort64
    dg.dgo
    dg.str
    dg.trg
    modules/Triang/config/config.IT4ICZ.ifort64
    modules/Triang/config/config.SOROBAN.ifort64
    modules/Uinp/config/config.IT4ICZ.ifort64
    modules/Uinp/config/config.SOROBAN.ifort64
    modules/amds/config/config.IT4ICZ.ifort64
    modules/amds/config/config.SOROBAN.ifort64
    modules/solps4-5/config/config.IT4ICZ.ifort64
    modules/solps4-5/config/config.SOROBAN.ifort64
    param.dg
    scripts/sorobansubmit

no changes added to commit (use "git add" and/or "git commit -a")

It seems daunting, but it is usually quite harmless. The thing is, SOLPS-ITER compilation is different on every machine. Since every environment is unique, it requires a different configuration for installing SOLPS-ITER. The list above mostly concerns configuration files for the Soroban and IT4Innovations server, which were written by Aleš Podolník. They are an addition to the SOLPS-ITER source code, being used mainly during its compilation and setting up the SOLPS-ITER work environment. They don't interfere with SOLPS-ITER updates because Git is only concerned with the files it tracks (stored in the origin repository) and it leaves any extra files alone.

Bonus: Cheatsheet

Look for detailed command usage in the docs: https://git-scm.com/docs.

Downloading

# Download the repository
git clone ssh://git@git.iter.org/bnd/solps-iter.git

Updating

# Update the repository
#   - download the latest changes & apply them
#   - don't forget to do the analogous action for submodules, too
git pull
git submodule update --init

# TIP: The `--init` is important both just after cloning and when
# the new version adds a brand new module (e.g. Carre2)

Not-so-good practice - Checkout branches in submodules

It is often suggested (SOLPS-ITER manual) to manually checkout a specific branch for all submodules. This forcibly overrides the behviour of the git submodule update command, which checks out each module at a specific commit as determined by a .gitmodules file, i.e. combining the module versions "as the developer intended".
This only makes sense as a troubleshooting option, when you want to blindly incorporate bleeding edge changes (bug fixes) in submodules, for some reason, and the developers temporarily forgot to update the .gitmodules in the main repository, for some other reason.

# Checkout master branch in all submodules
git submodule foreach git checkout master

# Checkout development branch in all submodules
git submodule foreach git checkout development