Running SOLPS-ITER

This tutorial will guide you through a successful run of SOLPS-ITER. It is assumed that you have created a new SOLPS-ITER simulation or you're building upon an already run simulation.

It is assumed that you have initiated the SOLPS-ITER environment.

See also Questions and Answers, section Running, restarting and transferring SOLPS-ITER runs.

Running SOLPS-ITER using `b2run`

The simplest way to run SOLPS-ITER is using the b2run command in the run folder:

b2run b2mn >& run.log &

The b2run b2mn part is essential; this is what runs SOLPS-ITER.
The >& run.log part redirects both STDOUT and STDERR to a log file named run.log; the extra & suppresses EIRENE pre-processing printout.
The final & lets the simulation run in the background so that you can use the command line for other things in the meantime.

In this form, this command will persist in running your simulation even after you have closed the command line, lost your internet connection or shut down your computer. This applies, however, only when you're running SOLPS-ITER on an external server!

You can submit several simulations at once using b2run in this bare form. Beware, however, that submitting two runs at once is not twice as efficient. Each b2run will hog all the computational power it can to itself. Consequently, simultaneous runs will compete for resources and your local system administrator might get angry at you. Use b2run when making short runs in quick succession (e.g. while catching the exact moment the solution goes supra-luminal and the run crashes). When making production runs, use submission scripts to reserve computational power only for yourself.

You will find all information about your run (whether it ended successfully, how many iterations were performed, type of errors etc.) in the run.log file. After longer runs (hundreds of iterations), the file gets too long to be read comfortably in text editors. To extract only the last 1000 lines into a new text file:

tail -1000 run.log > short-run.log

Running SOLPS-ITER using submission scripts

Submission scripts are wrappers around b2run which use the local computational job queueing system (SLURM, QSUB etc.) to reserve certain computational power and time for your simulation. You may encounter official SOLPS submission scripts (itmsubmit for EUROfusion Gateway, itersubmit for ITER clusters...) and in-house submission scripts. Generally, you will launch a submission script in the run folder. Many simulations can be run simultaneously from different folders.

You can find official SOLPS-ITER submission scripts in $SOLPSTOP/runs. The _coupled scripts are used for coupled B2.5+EIRENE simulations and they are launched automatically if EIRENE is turned on. The _loop scripts launch one shorter simulation after another in a chain, as a safeguard against losing all progress should a long simulation crash. It also helps use the server's computational power more efficiently (bite-sized runs that can fit beside larger jobs) and delivers partial results faster (the resource management system doesn't have to wait until it has 24 cores free for three weeks).

Where are the live simulation files?

When you run b2run in the run folder, you can see the files being updated as the simulation happens (mostly in the b2mn.exe.dir folder). You can monitor the simulation progress by reading these files. However, using submission scripts may leave the run folder inert until the simulation is finished, after which everything is updated at once. This is typically because the submission script has copied over the simulation folder to its own disk for faster access. If you find that live folder, you can to monitor the simulation progress there.

Official submission scripts

Official SOLPS-ITER submission scripts only

The instructions in this section pertain only to official SOLPS-ITER submission scripts, shipped in the $SOLPSTOP/runs folder. Other submission scripts (e.g. launching SOLPS with a container) may be used differently.

To submit a simulation, initiate the SOLPS-ITER work environment, go to the run folder of the simulation you'd like to run and use an equivalent of the following command:

itmsubmit -m "-np 8" -j "my_job_with_no_blank_spaces" -T "1"

To break this down:

itmsubmit is the name of the submission script on the EUROfusion Gateway. Each properly configured site should have its own submission script (ippsubmit for IPP Garching, itersubmit on ITER etc.).
-m specifies the MPI (Message Passing Interface) execution options (= EIRENE parallelisation). "-np 8" will instruct the script to use 8 processors in parallel. If -m is not set, the code will run on 1 thread.
-j is followed by the job name. This parameter is mandatory. If it isn't set, a default name will be used and the queue will be a mess. The name should contain alphanumeric characters only, meaning the underscore character is fine but a blank space will result in the error set: Variable name must begin with a letter..
-T specifies the approximate number of hours the simulation will take, so that the resource management system knows what priority to assign it. Always leave extra time compared to the planned simulation run time, so that the computation doesn't stop before b2fstate is written.

All the official submission scripts use similar flags. To learn more, look at their source code in $SOLPSTOP/runs or try:

itmsubmit -h

IPP Prague - TODO construction

As of February 2026, the Soroban server of IPP Prague is a properly configured site but its submission script sorobansubmit is not part of the official SOLPS distribution yet. You can copy it into $SOLPSTOP/scripts as part of the SOLPS configuration files as detailed in the legacy guide Installing SOLPS-ITER at COMPASS (Soroban).

Additional information on sorobansubmit:

-H specifies the Soroban node which should carry out the job. If nothing is selected, the resource management system will choose on its own. For example, sorobansubmit -j "my_job" -H "soroban-node-06".
By default, sorobansubmit submits the jobs into the queue long, which has the lowest priority. To change this behaviour, open the submission script source code, find the line #PBS -q long and change the queue (e.g. to medium, where jobs can take 2 days at most).

Managing queues

Once a job is submitted to a resource management system, it will enter a queue with all the other jobs. Depending on the server, there may be more than one queue (long, short, priority...). Once the system decides it has enough free computational time to launch your simulation, it will do so. Managing the queue is necessary so that you know which of your simulations are running, how long they've been at it and which ones have finished.

Email notifications that a simulation has ended

In the submission script source code, you may find a line which specifies an email. Define the EMAIL variable (or whatever it is called) in your command line prior to launching the submission script, or write your email address directly into the script. Then, when the job is finished, you will receive an email. This is useful as a notification that you should check the simulation, or as a reminder on the following morning what you were doing the day before.

SLURMopen_in_new: The resource management system of the EUROfusion Gateway and other clusters. Example commands:

# Check the queue
squeue

# List only your jobs in the queue
squeue -u $USER

QSUBopen_in_new: The resource management system of the Soroban server at IPP Prague and other clusters. Example commands:

# Check the queue
qstat

# List only your jobs in the queue
qstat -u $USER

# Delete a job from the queue
qdel NNNNN
# where `NNNNN` are the first 5 numbers printed by qstat in the column Job id

IPP Prague

Utilisation of the Soroban server can also be checked in a web browser, addresses soroban:44444open_in_new (doesn't work through VPN) or Soroban cluster utilisationopen_in_new, or with the command pbsnodes -a. Don't expect immediate updates, it takes a minute or two to see your submitted/deleted job.

Restarting a SOLPS-ITER run

SOLPS-ITER simulations are not typically made all in one go. Usually you'll run them for some time, check the results, tweak something and continue the simulation. Restarting the simulations is useful when:

You're still searching for the ideal input parameters (e.g. diffusion coefficients).
The simulation is unstable.
You want the simulation to produce additional output.
You're starting from another converged solution.

...and on many other occasions.

Use the cp command

When manipulating simulation files, always use the cp command! Using the file browser to copy the files, renaming the files etc. may cause the initial plasma state file b2fstati to be ignored and let the simulation begin again from the flat profiles state. More in Common pitfalls: The danger of timestamps.

To restart a simulation:

Go into the run folder.
Check if your run has concluded successfully.
Delete b2mn.prt. Failing to do so will prevent your simulation from running.
```
rm b2mn.prt
```
Remove b2mn.prt, not b2mn.dat

Everyone raise your hand if you once didn't pay attention and by mistake removed the B2.5 master control file b2mn.dat instead of b2mn.prt... OTL
Rewrite b2fstati (i for "initial" plasma state) with b2fstate (e for "end" plasma state).
```
cp b2fstate b2fstati
```
Run b2run b2mn >& run.log & or a submission script again.

b2fstati and b2fstate magic

The simulation will start from whichever plasma state is present in b2fstati. If no b2fstati is present (or the simulation ignores it), SOLPS-ITER will run b2ai to create a b2fstati containing the "flat profiles" solution and start from there.

Create a checkpoint of the simulation state so you can come back to it later: cp b2fstate b2fstate_before_gas_puff (You can archive EIRENE results as well (files fort.13, 14, 15, 44 and 46), but only b2fstate is essential.)
Return to a checkpoint: cp b2fstate_before_gas_puff b2fstati
Adopt a completely different solution (with the same geometry/number of cells): cp ../another_run/b2fstate b2fstati

Branching out a SOLPS-ITER run

Sometimes, you'll want to see what happens when you tweak a simulation a little (e.g. trying this weird switch you've just found in B2.5 documentation), but you don't want to lose the original simulation in case something goes wrong. Other times, you'll want to conduct a parameter scan. That is when you need is branching an existing run out.

Simple and dirty:

# Go to the simulation folder
cd $SOLPSTOP/runs/my_simulation

# Make a copy of an existing run
cp -r run_existing run_new

Clean start:

# Go to the simulation folder
cd $SOLPSTOP/runs/my_simulation

# Make an empty folder for the new run
mkdir run_new

# Copy over master control files
cp run_existing/b2mn.dat run_new/b2mn.dat
cp run_existing/input.dat run_new/input.dat

# Copy over boundary conditions
cp run_existing/b2.boundary.parameters run_new/b2.boundary.parameters
cp run_existing/b2.neutrals.parameters run_new/b2.neutrals.parameters
cp run_existing/b2.transport.parameters run_new/b2.transport.parameters

# Copy over the plasma state
cp run_existing/b2fstate run_new/b2fstati

# Create EIRENE symlinks to the baserun folder
setup_baserun_eirene_links

Both ways will produce a fully independent copy of the original run. The second way just gets rid of all unnecessary baggage (leftover figures etc.).

Choose descriptive names for run folders

When naming your new runs, imagine you're going on maternity leave tomorrow and coming back in three years. Will you have any idea what run_17_new means? You won't. Name it PSOL_170kW_nesep_1.5e19.

Interrupting a SOLPS-ITER run

If you want the simulation to end, or you want to check its intermediate results with something that needs the end state b2fstate (like b2plot), you can soft-land the simulation. In the run folder:

touch b2mn.exe.dir/.quit

This will end the simulation after the current iteration is finished, write the output files and quit SOLPS-ITER. When using submission scripts, take care to run this in the live folder (where files are continually updated), not the inert source folder.

Defining how long SOLPS-ITER should run

SOLPS-ITER keeps running until one of its stops is pulled. All of them are defined in b2mn.dat. Browse them in B2.5 switches.

Set the number of iterations (iteration = 1 EIRENE call + several B2.5 calls):

'b2mndr_ntim' '100'

Set the target value of residuals (mostly useful only for standalone B2.5 runs):

'b2mndr_min_areshe' ' 1.00E-03'

Set the target CPU time (in seconds):

'b2mndr_cpu' '3600'

Set the target real elapsed time (in seconds):

'b2mndr_elapsed' '3600'

I usually alternate between elapsed time for long runs and number of iterations for very short runs. At least one complete iteration will always be performed.

Monitoring a SOLPS-ITER run

While a SOLPS-ITER simulation is underway, you can check how it's doing with several built-in tools. Mind that not all built-in tools will work. For example, b2plot uses the b2fstate file, which is only produced at the end of the run and is missing in the meantime. So you can only use b2plot to view a simulation that has successfully concluded.

`2dt` time traces

The 2dt command plots the time trace (= evolution during subsequent SOLPS iterations) of several chosen plasma parameters. For example, to plot the evolution of $n_e$ on the outer midplane separatrix:

2dt nesepm

Other plottable quantities are listed in the SOLPS manual, Appendix E Quantities stored in b2time.nc. They include fluxes, temperatures, densities, potentials etc. at various locations in the simulated domain.

The 2dt command reads data from the file b2time.nc (check its source code $SOLPSTOP/scripts/2dt). This file is created by default by SOLPS and it is automatically updated with new data every few iterations while SOLPS is running. The relevant switches in b2mn.dat are:

# Save current values to b2time.nc every 20 iterations
'b2mndr_b2time'     '20'

# Append this run's values to last run's values
# If positive, last run's values are overwritten and lost
'b2mndr_stim'       '-1.0'

Adjust the period of b2time.nc writes so that you can see what's going on with the simulation (nearing a crash - printout at every iteration) while keeping the file size reasonable (fast standalone iterations - printout every 50 iterations).

You can also load b2time.nc contents with your own in-house scripts, which can then be run while the simulation is still underway.

2dt produces a messy line

Refer to Questions and answers: 2dt tesepm produces a messy line.

Computation history `cpu`

To display the number of iterations already performed and how long they took, use:

cpu

Use it twice in a row to see if a simulation is running.

Residuals

Residuals show how close the current plasma solution is to ideal. They are calculated for each cell, each B2.5 equation (continuity, momentum, electron/total ion energy) and each ion species by evaluating the equation left-hand side (temporal evolution and transport) and right-hand side (sources) and subtracting them. Calculated in this manner, residuals can be positive or negative and their value doesn't have direct meaning, although the smaller, the better. SOLPS sums up residuals over the entire B2.5 grid, norms them to a positive value and periodically saves them to the b2ftrace file as it runs.

To plot the time evolution of global residuals:

# Plot the continuity equation residuals
resco

Other residuals commands are listed in the SOLPS manual, section 2.5 scripts, of which probably the most useful is resall_D.

How to read residuals plots

See Questions and answers: What is the meaning of residuals plots?

Checking if a run has converged

`b2run` troubleshooting

It is good to know that b2run is actually an alias for gmake, thus many error messages are the same.

Target does not exist

You may have omitted a step in the B2.5 hierarchy. For example, you may be trying to run b2plot but the b2fstate file is absent, or you're trying to run b2yt but b2yt.dat is absent. The error message says what the target is; it needs to be run beforehand. However, do not run the target by yourself. Find out why it was not created. Easy solution: you forgot. Hard solution: something failed.

Faulty internal parameter jxa

In b2mn.dat, switches b2mwti_jxa and b2tqna_ixa can be used to set the indices of the outer midplane and other important locations. If they aren't set here, default values will be used. This error message may mean that the switches in your b2mn.dat are inconsistent with your grid. This may happen when you create a different grid (different number of grid points or surfaces) but keep b2mn.dat from the original simulation. Look the keywords up in the SOLPS manual for more information.

Transferring a SOLPS-ITER run using `b2yt`

b2yt is useful in the following situations:

You have a converged run and want to increase the grid resolution.
You want to build a new case whose geometry is similar but not the same as a previously converged run, and you don't want to wait until the "flat profiles" solution converges.
You want to check if the converged result is the same between two SOLPS version (4.3, 5, another release of SOLPS-ITER...).

The following materials concern b2yt:

SOLPS manual, section 3.14 b2yt, changing from one grid size and species set to another. Pretty informative in the large picture, but doesn't provide step-by-step instructions.
ITER Organisation: Converting or resizing a case: b2ytopen_in_new. Describes a few steps in greater detail, but doesn't give the whole process either.
Conversion tutorialopen_in_new

Transferring SOLPS runs as a whole

Moving a SOLPS run to a different simulation or a simulation to a different server is described in Remote access: Transferring SOLPS-ITER runs.