SOLPS-ITER codebase

In this tutorial, you will learn:

• How to obtain the SOLPS source code
• Where you should install SOLPS
• How to initiate the SOLPS work environment
• How to update SOLPS
• The very basics of Git

Official sources

This tutorial overlaps heavily with section 1.1 Obtaining and updating the code of the SOLPS manual and the SOLPS repository README open_in_new.d

Get access to SOLPS-ITER

SOLPS-ITER is developed by the ITER Organisation (IO). Currently, its source code is housed in a private ITER Git repository open_in_new, but soon (as of January 2026) it will be made open-source. You can ask for access to SOLPS-ITER if you are employed at an institution affiliated with the ITER Organisation or someone from such an institution vouches for you (e.g. your supervisor). To get access to SOLPS-ITER:

1. Write to Xavier Bonnin (mail xavier.bonnin@iter.org) that you would like to use SOLPS-ITER and ask him to give you access to the SOLPS repository. Use the email address of your ITER-affiliated institution. Follow Xavier's instructions to:

   • Get an IDM open_in_new (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 the SOLPS mailing list (mail solps-iter@iter.org) and the SOLPS-ITER Slack group open_in_new, where you'll be able to discuss SOLPS-related issues and ask for help.

2. Generate a pair of SSH keysopen_in_new (or use a pair already present in ~/.ssh/).

   cd ~/.ssh
   ssh-keygen -t rsa -C "your_email@institute.eu"
   

   Upload the public key to your ITER public key list. (That is, copy-paste the inside of the id_rsa.pub file there.)

3. Download the source code of SOLPS-ITER using Git.

   cd /path/to/solps
   git clone ssh://git@git.iter.org/bnd/solps-iter.git
   

Congrats, you have the source code - mostly text files written in Fortran. To actually run SOLPS-ITER, you must first compile the source code, including all of SOLPS dependencies.

Tip

Check out our Useful links and browse the SOLPS-ITER Confluence page open_in_new, the ITER SharePoint open_in_new, and other interesting locations, just so you know they exist.

Where and how to install SOLPS-ITER

The SOLPS-ITER code has a convoluted list of dependencies, which makes it much too complicated for a common mortal to install just anywhere. We recommend one of two options:

1. Install SOLPS-ITER at a properly configured site (EUROfusion Gatewayopen_in_new, ITER computing clusters, see the list in section 1.3 Initial set-up of the SOLPS-ITER manual).
2. Use a container installation, which you can run anywhere.

Properly configured site

A properly configured site is an HPC (High-Performance Computing) server where:

1. All required dependencies are installed
2. The site-specific configuration files have been committed to the main SOLPS-ITER repository

Example of a properly configured site: EUROfusion Gateway

• EUROfusion Gateway open_in_new = HPC-CINECA cluster in Italy
• Available to all EUROfusion beneficiaries, no need to register any specific project (in contrast to e.g. IT4I)
• Known under a variety of legacy names: Marconi, Marconi Gateway, Gateway, ITM etc. (ITM or MARCONI in the manual)

How to install SOLPS-ITER at a properly configure site:

1. Log into the site's command line.

   ssh -X username@my.server.eu
   

2. Download ("clone") the SOLPS repository to your directory of choice.

   cd /path/to/solps
   git clone ssh://git@git.iter.org/bnd/solps-iter.git
   

   SSH authetication

   If you get the error

   Permission denied (publickey).
   fatal: Could not read from remote repository.
   
   Please make sure you have the correct access rights and the repository exists.
   

   ...you have not correctly set up SSH key authentication. Follow the instructions above.

   EUROfusion Gateway

   Do not install SOLPS-ITER into your home folder but into /pfs/work/$USER/.

3. Enter the solps-iter repository and select your code version branch.

   cd solps-iter
   git checkout master  # master, develop, release/3.1.1 etc.
   

4. Initialize and update everything.

   git pull
   git submodule update --init
   

   Do not check out individual submodules

   At this point, the SOLPS manual instructs to checkout individual submodules:

   git checkout master
   cd modules/B2.5
   git checkout master
   cd ../Eirene
   git checkout master
   cd ../DivGeo
   git checkout master
   cd ../Carre
   git checkout master
   cd ../adas
   git checkout master
   

   This is not necessary, since git submodule update has already done this. It has checked out each submodule at a specific commit as determined by a .gitmodules file, combining their versions "as the developer intended". Checking out the submodules individually only makes sense as a troubleshooting option, when you want to blindly incorporate bleeding edge changes (bug fixes) in submodules but the developers temporarily forgot to update .gitmodules in the main repository.

5. Initiate the SOLPS work environment.

   tcsh
   source setup.csh
   

   Optional: first setup

   At this point, the SOLPS manual instructs to run the command:

   first_setup
   

   We believe that this is intended only when setting up configuration of SOLPS-ITER on a completely new site. It generates default setup/config files if any are missing. But there is no harm in running it anyway.

6. Clean for good luck and compile SOLPS (recommended targets: solps, solps_mpi).

   gmake clean_solps
   gmake clean_solps_mpi
   gmake solps
   gmake solps_mpi
   

Installation guides

The SOLPS wiki offers three installation guides in addition to installing on a properly configured site:

• Installing SOLPS in a container - recommended

  • Quick and clean installation of SOLPS-ITER, portable to any site
  • Pre-built containers with zero setup are available
  • Requires Apptainer open_in_new or Docker open_in_new 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.

• (Legacy) Installing SOLPS at Soroban

  • Soroban open_in_new = IPP Prague cluster in Czechia, properly configured site since v3.0.9, supports containers
  • Available to IPP Prague employees and students
  • Known as IPPCR in the manual

• (Legacy) Installing SOLPS at IT4I

  • IT4Innovations open_in_new (IT4I) = supercomputing centre in Czechia, 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

Compiling SOLPS elsewhere: Discouraged for beginners. If you absolutely must do it, get in touch with someone experienced (mail Jan Hečko, mail Xavier Bonnin, your local SOLPS guru). Look for the SETUP/easybuild-local.sh script in the SOLPS-ITER repository, which is currently the recommended tool for the job. It should install all the dependencies for you in the form of environmental modules. As for its documentation, there are comments in the script and there are a few words written about it in the SOLPS-ITER GUI documentation.

How to initiate the SOLPS-ITER work environment

Once you have downloaded 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.

1. Log in to the server where your SOLPS-ITER is installed.

   ssh -X username@my.server.eu
   

   Refer to Remote access for the particular address of your server.

   IPP Prague

   When accessing the Soroban cluster at IPP Prague, additionally ask the resource management system qsub to assign you some computational power in an interactive job.

   qsub -IX
   

2. Enter your SOLPS-ITER installation folder (also known as $SOLPSTOP - that is SOLPS top, not SOLP stop).

   cd /path/to/solps/solps-iter
   

3. Initiate the tcsh shell.

   tcsh
   

4. Load the environment variables and commands.

   source setup.csh
   

5. If you're going to use DivGeo, Carre of Triang (building a new simulation), specify the device name.

   setenv DEVICE besttokamak
   

IPP Prague

In case of error module: command cannot be found, open or create a .tcshrc file in your home directory and paste inside this line:

source /usr/share/modules/init/tcsh

Open a new command line and try initiating the SOLPS-ITER work environment again.

How to update SOLPS-ITER

SOLPS-ITER is a living code which constantly receives tweaks and bug fixes, as evident from the SOLPS user forumsopen_in_new 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 when a new master is released. This is usually commemmorated by naming the new master with a version number, e.g. SOLPS-ITER 3.0.9.

There are two ways to update the code, a simple one and a manual one. They both begin by initiating the SOLPS work environment.

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 about twice a year (as of January 2026). The develop branch is updated more frequently, but it's 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.

1. Check whether you have modified any source code files in the SOLPS-ITER folder and not committed them.

   git status
   

   If there are any, use your Git knowledge to commit them, stash them, or discard the changes. New (untracked) files are usually not a problem.

2. (Optional) At this moment, you may switch to a different branch if you want to do that. Otherwise skip this step.

   git checkout feature/wg_workflow
   

3. 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
   

4. 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 hereopen_in_new. Thus, gmake should be preferred, just to be on the safe side.

   Clean when switching branches

   When switching code branches or versions, it is highly recommended to clean everything up by building the corresponding clean_* targets (or simply gmake clean_all). 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

If you have no idea what Git is or you were intimidated the last time you tried to find out, these are the necessary basics.

Simply put, Gitopen_in_new 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.

Where to learn Git

In addition to the guide below, refer to many well-written Git tutorialsopen_in_new on the internet to get a more complete picture. And bookmark the official Git docsopen_in_new. 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 repositoryopen_in_new 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 months, and they can contain important bug fixes and plasma physics updates.

Why update SOLPS-ITER when a new master comes out?

If something isn't working in SOLPS and you try to submit a bug report or ask about it on the SOLPS Slackopen_in_new, the first reply will be: "Are you using the current master version?"

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

Git cheatsheet

Look for detailed command usage in the official Git documentationopen_in_new.

Download ("clone") a repository:

git clone ssh://git@git.iter.org/bnd/solps-iter.git

Update a repository (download the latest changes and apply them):

# Don't forget to do the analogous action for the submodules, too
git pull
git submodule update --init

On the usage of --init

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