SOLPS-ITER user wisdom

This document contains "meta" information on installing, using and understanding SOLPS-ITER. It's the kind of stuff experienced users carry in the back of their minds.

Where to find information

Much SOLPS work is conducted along the frame "I have a problem, and I am seeking a solution". SOLPS documentation is, unfortunately, fragmented. This chapter provides tips where to find information.

If you receive an error message (in the terminal or in run.log), take heart and read the log carefully. Chances are, it says what the problem is and might even suggest a way to fix it. To search for a string of characters in a long file (such as run.log):
```
# Print out 5 lines above and below "chemical sputtering"
grep -C 5 'chemical sputtering' run.log

# Search for "error", ignoring upper/lower case
grep -i 'error' run.log
```
In a long simulation, run.log is typically too long to open in a text editor. To copy the last 100 lines of run.log (presumably containing information of what went wrong with the simulation) into a smaller file:
```
tail -100 run.log > short-run.log
```
You can also find output of the last 10 iterations in run.log.last10.
Consult the SOLPS-ITER manual or the EIRENE manual. The EIRENE manual is easier to read but not entirely up-to-date. Guidelines on how to read the SOLPS manual are given below.
Go through Useful links. This is basically one documentation source after another.
Try the Dictionary if it's a common term.
Use the solps-doc search toolbar. That's usually pretty reliable, but in case you're unsure of the proper keyword, try to guess what tutorial the information might be included in, browse Questions and answers and Common pitfalls. If you don't find the solution here, we will be very happy if you write about it and contribute it to solps-doc.
Go through the $SOLPSTOP/doc directory. The titles are sometimes helpful, sometimes uninformative, sometimes misleading. To find what information is inside, open the documents one by one and skim their content.
Try our Library, especially if you're looking for physics understanding.
Use Google Scholar to search for articles. Normal Google sucks at searching for SOLPS information, which is why it isn't featured in this list. (I belong to the generation which thinks it's preposterous something can't be found with Google.)
If you're looking for a SOLPS routine description (like b2stbc), consult the SOLPS-ITER source code, found in $SOLPSTOP/modules. To view and search its content, use a high-level code editor such as Visual Studio Code. This allows, for instance, searching for keywords across multiple files using Ctrl+Shift+F. In the best case, you'll find docstrings and internal documentation. In the worst case, you'll have to inspect the Fortran code line by line to figure out what the simulation actually does.
If you're looking for B2.5 switch description, use our B2 input doc viewer.
Additional B2.5 documentation can be compiled using the instructions in $SOLPSTOP/modules/B2.5/src/documentation/README.md.
Additional B2.5 documentation is found in $SOLPSTOP/modules/B2.5/src/documentation/b2cdca.F.
Description of B2.5 variables, including e.g. those in b2ah.dat, is given in $SOLPSTOP/modules/B2.5/src/documentation/b2cdcv.F.
Additional DivGeo documentation can be found in $SOLPSTOP/modules/DivGeo/equtrn/doxygen/refman.pdf.
Ask someone for help. This has a strict hierarchy, so that you save others time. Do not skip to the next step before you have tried the previous step.
1. Ask the nearest coworker, ideally but not necessarily a SOLPS-ITER user. Chances are, your problem is not strictly SOLPS-related.
2. Ask your local SOLPS team (groups emails do well).
3. Ask an external experienced modeller. Ideally this is someone you know already, such as your tutor from long ago.
4. Write to the SOLPS Slack group. (There's a good chance Xavier will answer.)
5. Ask Xavier Bonnin directly.

Other common bugfixes include:

Update to the current develop SOLPS-ITER branch, if you don't care what particular code version you're using. Xavier will ask if you have tried this.
Particularly when you're switching around different versions of SOLPS, make sure to start up the SOLPS environment from scratch. The source setup.csh command can set up different versions of the same library, causing problems with compilation.

RTFM (Read the f***ing manual)

The SOLPS-ITER manual, found in $SOLPSTOP/doc/solps/solps.pdf is a beast of 600+ pages, containing more information than you could ever want, but not the one you actually want. Each SOLPS version has its own version of the manual, and the one shipped with solps-doc is possibly quite outdated. Refer to your own manual, just to be sure. See also Questions and answers: Where do I find the latest version of the manual.

Even if the manual is hard to read and hard to find answers in, do not underestimate it. It's impolite to ask people for help before you have properly consulted the manual. And I do mean properly. "I have skimmed it" does not cut it. Xavier will scold you for failing to do so. When you reach out for help at the SOLPS-ITER Slack channel, always detail to which degree the manual answered your question. Even people proficient with SOLPS-ITER always have the manual open while working.

A note on understanding the manual: When you see something like "if model.eq.1", it means "if model is equal to 1". Similarly for model.ge.3 ("greater or equal to 3"), model.ne.0 ("not equal to 0") etc. The notation is not unified, there are "if > 1" and similar alternative notations mixed in with this one, but those are largely intuitive.

How to properly search the manual for information

Follow the instructions in this order and don't go straight to Ctrl+F. I know it's tempting but it's very unreliable.

Read the table of contents. The section titles are quite informative.
Read entire sections, not just the little bit of text where your keyword is located. This will give you context and you're very likely to find extra information as your topic is revisited.
Read the cited works. Funny story: I spent a few weeks desperately researching why there is a Pfirsch-Schlüter particle flux in the B2.5 continuity equation. Finally I was directed to an article which explained it on Slack. Then I found out it was cited in the manual in the section which gives the continuity equation. Don't be me. OTL
Ctrl+F your keywords, for example "heat flux". However, beware that your term might be called several different things (like "energy flux"). If your keyword has more than two words ("sheath heat transmission coefficient"), chances are that you won't find it using Ctrl+F.
Ctrl+F the manual source code ($SOLPSTOP/docs/solps/solps.tex). This can be useful for quantity names (q_{ax}). Beware, this can be extra unreliable as different names and typing styles might be used each time. Try to find some part of the variable name which is hard to change (axy inside D_{axy}). Alternatively, search axy in the rendered PDF.

Dictionary

The manual: The SOLPS-ITER manual. The ultimate manual, the go-to for all your questions, the 600-page beast. If a manual is referred to as "the manual", it is this manual. The manual is automatically created when you compile SOLPS-ITER; its source files are located in $SOLPSTOP/docs/solps/ and the manual itself is called solps.pdf. Each version of SOLPS-ITER has its own manual. Thus you will always find information relevant to your version in this folder.

Gateway (sometimes referred to as ITM, Marconi, Marconi Gateway or a combination of the above): Computing cluster where you can install and use SOLPS-ITER, a part of the Marconi cluster. To apply for an account, follow the instructions here. Most SOLPS-ITER users run their simulations on their local clusters, but some continue using Gateway.

Xavier Bonnin: The highest person when it comes to SOLPS-ITER (called RO, the Responsible Officer). Contact him only after you have exhausted every other option save for quitting SOLPS-ITER, as he's testy when he has to deal with beginner questions. This attitude is probably why solps-doc is a thing in the first place.

$SOLPSTOP: The SOLPS-ITER installation folder location. Use the stop command within the SOLPS-ITER work environment to go there. (Funnily, it's s-top, like SOLPS top, not stop.) DivGeo (abbreviated as DG): Programme for creating and viewing geometry of SOLPS-ITER runs. Full GUI, a little counter-intuitive but pretty friendly once you create a mesh or two. It's a pain that it's got to be done by hand, but automation efforts have been limited and futile.

SN, DN: Single null, double null. Used to refer to separatrix configurations in DivGeo.

Stratum (plural strata): A source of neutral particles in EIRENE, usually a B2.5 grid boundary ("outer target", "far SOL") or a volumetric source ("recombined D atoms"). More information is given in Questions and answers: What is a "stratum".

Flat profiles (or the flat profiles solution): Default initial state of SOLPS-ITER simulations if no b2fstati file is supplied. As the name implies, the "solution" is just constant everything across the B2.5 grid. Using the flat profiles usually happens either to someone who's very green (even for the standards of solps-doc) or by accident when b2fstati is ignored by the code. Refer to Common pitfalls: The danger of timestamps.

SOLPS-ITER user forum: A video-conference event which takes place approximately once a month. Traditionally it occurs in two instances: once late in the evening and once early in the morning on the following day (relative to the France time zone). This is so that people from different time zones have a chance to participate. Most of the time is taken up by Xavier Bonnin talking about current events in the SOLPS-ITER code and the issues its users are dealing with. At the end of the forum, participants raise questions and issues of their own. In my experience, participating in the video-conference is futile. At my level of knowledge and immersion, Xavier is very hard to understand (half because he mumbles, half because how advanced the topics are). As a result, it's much more productive to skip the video-conference and just carefully read the minutes in the e-mail Xavier sends. They are very detailed, so you probably won't miss out on anything. You will graduate from being a SOLPS beginner when you begin understanding the user forum.

SOLPS Slack: A Slack group where SOLPS users gather, exchange information and get chewed out by Xavier for not consulting every piece of documentation prior to asking for help.

SOLPS-ITER work environment: Command line where SOLPS, b2plot and other SOLPS-related stuff can be run. See How to initiate the SOLPS-ITER environment.

B2plot: A primarily plotting programme shipped directly with SOLPS-ITER. It has it own section in the manual (appendix I), can plot 2D visualisations of plasma temperature, density, radiated power and so on in a jiffy, integrate along given lines of sight, produce text files with processed code output and much more. It has its weaknesses (like awkward axis boundaries setting), but it remains a very powerful tool. See our b2plot tutorial.

David Coster: A senior researcher working at IPP Garching. One of the most experienced SOLPS-ITER users, he spends his days attending thousands of meetings.

Katka and Honza: PhD students working at IPP Prague, the main authors of solps-doc. They share the conviction that if they don't write it down, they will forget it.

Useful links

Source code of SOLPS-ITER

The source code of SOLPS-ITER, kept at ITER Github. Just downloading it is not enough to make simulations with SOLPS-ITER; first you must compile the source code (see the installation guides).
To access the link, you must first have access rights. Write to Xavier Bonnin (xavier.bonnin@iter.org) and ask him to create a user account for you.
This is the quickest way to get to the manual LaTEX source ($SOLPSTOP/docs/solps/solps.tex).

ITER SharePoint

A big old pile of documentation. Highlights:
- Minutes from the SOLPS-ITER user forums
- The Manuals and Documentation folder (has some overlap with $SOLPSTOP/doc)
- The SOLPS-ITER Papers folder (has some overlap with our Library, contains some of the newest papers on SOLPS-ITER)

SOLPS-ITER Materials

Lists new features of SOLPS-ITER over time.

SOLPS-ITER Confluence page

Useful general overview of the SOLPS-ITER versions, links to places, debriefings from SOLPS forums, etc. Updated often.
Also contains a list of problems and bugs SOLPS-ITER users have encountered and documented. I used to write my know-how there, until I started writing solps-doc.

SOLPS-ITER features wish list

List of features that someone wishes were implemented in SOLPS-ITER. Appears to have considerable overlap with Xavier's to-do list.

Eurofusion wiki - training section

Contains the list of SOLPS-ITER trainings that have taken place until today. Useful for writing down training output and finding e-mails for fellow trainees.

SOLPS Slack

A forum created in March 2020, when the coronavirus quarantine started. Has a Q&A section where you may pose your questions and get answers straight from Xavier without feeling too guilty. (But make sure to do thorough research before asking here! Especially consult the manual in great detail, according to the recipe above.)

SOLPS GUI documentation and video tutorials

Created by Leon Kos, the SOLPS-ITER GUI (Graphical User Interface) is a little-known project which aims to make SOLPS-ITER more user-friendly.
Even if you do not plan to use the tool itself, the documentation provides nicely written (but often brief) guides and overviews such as SOLPS Structure and SOLPS-ITER installation with easybuild-local.sh.

B2 input docs

Created by Jan Hečko, this webpage lists the switches of B2, their meaning and default values, in a human-readable way. The descriptions are taken from the official SOLPS/B2.5 documentation ($SOLPSTOP/B2.5/src/documentation/b2input.xml). The webpage is generated for several SOLPS-ITER versions and regularly updated. In case you want to use the webpage generator tool directly (e.g. to generate it from your version of SOLPS-ITER), clone the solps-doc repo and refer to instructions in solps-doc/extras/b2input/README.md.

ADAS manual

ADAS (Atomic Data and Analysis Structure) is the library which SOLPS-ITER uses for plasma-neutral interactions.

Library

Here are some articles and documents I've read and don't want to forget. Some are accessible in the $SOLPSTOP/docs/ folder.

Katka's PhD thesis study

Background

I place this resource first because it's hopefully one of the most comprehensive beginner guides to SOLPS-ITER. (I wrote it as a beginner guide for myself after I return from maternity leave. If it and solps-doc doesn't do the job of introducing a beginner to SOLPS-ITER, nothing will.)

It's called a "PhD thesis study" because our faculty (FNSPE CTU Prague) requires its PhD students to prove, after two years of study, that their research can eventually become a PhD thesis. This particular study recapped most of what I knew about SOLPS in fall 2021.

Beware. The study is extensive, unpolished and unfinished. It contains knowledge, but the wrapping is crumpled and I wouldn't dare cite it (just like solps-doc). I would be ashamed to submit such slapdash work, except I am simply glad to be rid of it. And the faculty did say it would make for a fine thesis, so.

If you want to know the main results of the study but don't have the energy to skim it, I have published EPS 2021 proceedings which sum them up on 4 pages.

Contents

Why modelling heat exhaust in tokamak reactors is a good idea.
General description of transport codes, derivation of the Braginskii equations and thorough discussion of transport codes limits and weaknesses. Includes a half-experimental discussion how the anomalous diffusion coefficients should be chosen. (Conclusion: black magic.)
Why we should model COMPASS (and COMPASS-U) with SOLPS-ITER.
A rant against inaccurate magnetic equilibrium reconstructions (mainly to sell my article) about COMPASS equilibrium reconstruction inaccuracies.
A heroic if unfinished attempt to relate the B2.5 equations to the Braginskii equations and explain them term by term. Basically annotations to appendix C of the manual that I wish were actually in the manual and not strewn about (see the rest of this library).
An inferior, unfinished copy of solps-doc tutorials Installing SOLPS-ITER, Creating a new SOLPS-ITER run and Processing SOLPS-ITER output.
A pure-D, drift-free, coupled SOLPS-ITER simulation of COMPASS discharge #17588: discharge description, experiment-model fitting and evaluation of the transport regime using the two-point model. Includes a neat demonstration that shifting experimental profiles by ad hoc centimeters is an unneeded uncertainty which can be avoided if you put enough thought into your equilibrium reconstruction.

In some topics, the study repeats solps-doc. In others, it delves deeper. In others yet, it contains information which isn't present in solps-doc at all. I would urge you to skim or Ctrl+F the study if you're using solps-doc as reference; it might help.

Evolution of SOLPS

S. I. Braginskii, Transport Processes in Plasma, Reviews of Plasma Physics 1 (1965)

When you hear of the Braginskii equations, this is what's referred to. Very detailed, humanely explained and surprisingly honest. A must-read for every transport code user.
length: 97 pages, difficulty: hard (because it's so damn long)

B. J. Braams, A multi-fluid code for simulation of the edge plasma in tokamaks (1987)

A rather old but all the more detailed resource on early SOLPS versions. Gives all the (then current) code equations and, delightfully, describes the variable in a nice comprehensive table. Describes discretization schemes and gives example boundary conditions. In appendix A, code subroutines and variables (such as nx, sx, resco and fhe) are described in beautiful, if outdated detail.

V. A. Rozhansky et al, Simulation of tokamak edge plasma including self-consistent electric fields, Nuclear Fusion 41 (2001)

A detailed description of B2.5 equations in SOLPS5.0. Were you wondering how drifts were implemented? Do you finally want to know what those "divergence-free terms" are? This article is your man. Brimming with information, it requires about five times more time to read than any other article.
length: 16 pages, difficulty: hard

V. A. Rozhansky et al, Potentials and currents in the edge tokamak plasma: simplified approach and comparison with two-dimensional modelling, Nuclear Fusion 43 (2003)

Compares calculation of edge plasma currents (calculating currents is about equivalent to calculating the plasma potential, and that can only be done believably by including the various drifts) on top of SOLPS5.0 using a 2D and a 1D model and finds good agreement. Breaks down the edge currents into individual components and provides formulas and commentaries on their magnitude and direction in more detail than you would ever want.
length: 9 pages, difficulty: hard

R. Schneider et al, Plasma Edge Physics with B2‐Eirene, Contributions to Plasma Physics 46 (2006)

Textbook-like in length and explanation depth. Touches almost any aspect of transport code modelling you'd like. Recommended for beginners.
length: 180 pages, difficulty: easy

V. A. Rozhansky et al, New B2SOLPS5.2 transport code for H-mode regimes in tokamaks, Nuclear Fusion 49 (2009)

A detailed description of B2.5 equations in SOLPS5.2 (and hopefully the current version of SOLPS-ITER). Answers the age-long question of "Why the hell are there Pfirsch-Schlüter fluxes in the continuity equation instead of diamagnetic fluxes?". Refer here first if you want to understand B2solps5.2_equations_2021.07.30.pdf.
length: 11 pages, difficulty: medium

S. Wiesen et al, The new SOLPS-ITER package, Journal of Nuclear Materials 463 (2015)

Compares the same runs made by SOLPS4.3 and SOLPS-ITER, gives some formulas for heat fluxes and defines convergence criteria. A longer, report-like version may be found among the ITER documents.
length: 5 pages, difficulty: easy

X. Bonnin et al, Presentation of the New SOLPS-ITER Code Package for Tokamak Plasma Edge Modelling, PFR 11 (2016)

SOLPS-ITER structure, Git version control, file description, workflow, plans for future improvements etc.
length: 6 pages, difficulty: easy

Transport codes physics

V. Kotov and D. Reiter, Two-point analysis of the numerical modelling of detached divertor plasmas, Plasma Physics and Controlled Fusion 51 (2009)

Derives a model very similar to Stangeby's 2PM based on SOLPS-ITER equations for momentum and energy transport, defines its own loss factors and calculates them for a density scan at AUG demonstrating the losses essential for achieving roll-over and detachment. Contains lovely, if not exhaustive details on where to get the data from.
length: 19 pages, difficulty: easy

P. C. Stangeby, Basic physical processes and reduced models for plasma detachment, Plasma Physics and Controlled Fusion 60, 2018

All you want to know about detachment. Starts from the fact that the ITER divertor must survive the heat fluxes and erosion of its long DT operation, derives a lovely $T_e < 10$ eV criterion for the long-term divertor survival and discusses how to get there based on transport code simulations. Also introduces two-point model formatting (2PMF) to post-process and understand the simulation output.
length: 38 pages, difficulty: medium

R. A. Pitts et al, Physics basis for the first ITER tungsten divertor, Nuclear Materials and Energy 20 (2019)

The holy grail of ITER divertor physics. Written so well that the knowledge lines up in your head by itself. Describes material limits of the tungsten divertor (steady-state, slow transients and fast transients) and how they're addressed in the ITER design. Talks a lot about SOLPS4.3 and SOLPS-ITER simulations of ITER.
length: 25 pages (in a tiny font), difficulty: easy

J-S Park et al, Assessment of ITER divertor performance during early operation phases, Nuclear Fusion 61, 2021

Density scan of pure-D, drift-less ITER plasmas of the PFPO-I stage. Finds that tungsten and beryllium-coated divertor have different molecular physics and that ITER target is well "insulated" from upstream, in that target conditions can change drastically and upstream remains the same. (cries in COMPASS)
length: 16 pages, difficulty: easy

V. A. Rozhansky et al, Potentials and currents in the edge tokamak plasma: simplified approach and comparison with two-dimensional modelling, Contributions to Plasma Physics 58 (2018)

Presents three simulations of AUG, with drifts and at three rates of nitrogen seeding, where the inner divertor is detached and the outer target gradually detaches. Shows that the parallel electric fields gradually decrease, the associated $E \times B$ drift decreases and the density maximum at the inner target moves from the SOL closer to the strike point. Also suggests the Pfirsch-Schlütter currents might create an instability in the cold divertor.
length: 7 pages, difficulty: easy (half of it is pictures)

V. Rozhansky et al, Currents structure in the scrape-off layer of a tokamak, Nuclear Materials and Energy 35 (2020)

Breaks down the SOL currents into three components: Pfirsch-Schlütter currents (AKA the currents closing the grad-B drift charge separation, but only above the X-point), thermoelectric currents (AKA the currents flowing from one divertor target to the other because of their temperature difference) and the plate closing currents (the currents closing the grad-B drift charge separation below the X-point and the currents compensating the neoclassical ion radial flow). Show these currents in Globus-M and ASDEX-U simulations and experiments.
length: 5 pages, difficulty: medium

S. Carli et al, Interchange-turbulence-based radial transport mode for SOLPS-ITER: A COMPASS case study, Contributions to Plasma Physics 60 (2020)

Extends SOLPS-ITER with a new quantity, the turbulent kinetic energy $k$, and uses it to self-consistently model $D_\perp$ based on the exchange turbulence. Compares classical ($D_\perp$ tuned manually) and self-consistent simulations and finds beautiful ballooning and satisfactory code-code-experiment agreement. To my knowledge, presents the first SOLPS-ITER (no drifts, pure D, with EIRENE) simulations of COMPASS ever. The beginning of section 3 gives an exhaustive list of "technical parameters you need to say about your interpretative modelling simulation".
length: 7 pages, difficulty: easy

Heat flux limiting

W. Fundamenski, Parallel heat flux limits in the tokamak scrape-off layer, Plasma Physics and Controlled Fusion 47 (2005)

Textbook-like review of the physics of heat flux limiters. Go-to material when seeking to learn something about these pesky input parameters. The first paragraph in section 1.3 Historical overview deserves special attention for its blatant honesty.

An applied plasma physicist attempting to model transport phenomena in a tokamak SOL is faced with a number of questions relating to parallel heat conduction in the long mean free path limit: How does $\chi_\sigma$ change with increasing $\lambda_{\sigma \sigma}$? When and by how much does it depart from $\chi_\sigma^{SH}$? How are $q_\sigma$ and $\nabla_\parallel T_\sigma$ related in this limit? Does the heat flux saturate at some value, e.g. the Maxwellian free streaming flux?

And it goes on. It stops just short of: Why did I choose to study SOLPS-ITER? What is the meaning of life?

length: 47 pages, difficulty: easy

D. Tskhakaya, On Kinetic Effects during Parallel Transport in the SOL, Contributions to Plasma Physics 48 (2008)

Discussion of heat flux limiters in transport codes, from the perspective of kinetic (PIC) codes.
length: 4 pages, difficulty: easy

J. Omotani and B. Dudson, Non-local approach to kinetic effects on parallel transport in fluid models of the scrape-off layer, Plasma Physics and Controlled Fusion 55 (2013)

Discussion of heat limiters in transport codes, from the perspective of a non-local model derived from hundreds of moments of the kinetic equation.
length: 9 pages, difficulty: easy

M. K. Prasad and D. S. Kershaw, Nonviability of some nonlocal electron heat transport modeling, Physics of Fluids B: Plasma Physics 1 (1989)

(not read yet, but promises to show that two models of nonlocal electron heat transport lead to unphysical results)

M. Day et al, The Effect of Heat Flux Limiting on Divertor Fluid Models, Contributions to Plasma Physics 36 (1996)

Absolutely smashes heat flux limiters as a concept, I love it. My favourite bits are:

The limited heat flux is written as $q_e = \left( 1/q_s + 1/q_l\right)^{-1}$, which is an arbitrary interpolation between the free-streaming and Spitzer values.

The ad-hoc limiter is not derived from first principles and it introduces a poorly understood free parameter into the model.

They basically modelled the linear device PISCES-A with a homebrew 1D code, performed a sensitivity study of the electron heat flux limiter, found a big impact on $n_e$ and $T_e$ and concluded the limiter value is bullshit, especially with predictive simulations. Lesson learned: do your sensitivity studies.

R. H. Cohen and T. D. Rognlien, Finite Mean-Free-Path Effects in Tokamak Scrape-Off Layer, Contributions to Plasma Physics 34 (1994)

Creates an analytical formula for electron parallel heat flux by patching up several known effects in the velocity space sorted by the mean free path, and compares its results for DIII-D-like plasmas to a Monte Carlo code. Gets "reasonable" agreement, meaning, eh, the order of magnitude is correct and look, they're right on top of each other here in the middle.
length: 6 pages, difficulty: medium (because of the distribution function math)

Implementation and numerics details

H. Bufferand et al, Implementation of drift velocities and currents in SOLEDGE2D–EIRENE, Nuclear Materials and Energy 12 (2017)

Describes SOLEDGE2D-EIRENE and not SOLPS-ITER, but by golly, that derivation of fluid equations including drifts is good. It even includes a derivation why the divergence of the diamagnetic flux is equal to the divergence of the grad-B drift and explains the (2dia) terms found in the manual.
length: 6 pages, difficulty: medium (there's a lot of equations)

E. Kaveeva, Output_description.pdf

When you write the line 'B2wdat' '4' into the b2mn.dat file, additional output will be produced. This document lists the variable names in this output and their prescriptions. Can be useful when you forget what hx, bb or sna are.
length: 18 pages, difficulty: hard

Unknown author, B2solps5.2_equations_2021.07.30.pdf (and later versions)

Equations used for solving the plasma state in B2.5. There are literally only equations, nearly no description of what the quantities are or mean. Recommended only for hardcore fans of equations. Forget Ctrl+F. A bit more information is given in appendix C of the manual or [Rozhansky 2009]. The file $SOLPSTOP/modules/B2.5/src/documentation/b2cdcv.F gives more information on what the variables mean.
length: 48 pages, difficulty: absolutely hardcore

Useful commands

Noted here in case I forget them.

Running a simulation cheat sheet:

# Interrupt a running simulation
touch b2mn.exe.dir/.quit

# Submit a simulation
b2run b2mn >& run.log &

# Save the last 10000 lines of run.log into short-run.log
tail -10000 run.log > short-run.log

I'm always searching for these commands in SOLPS-doc, might as well copy them all in one place.

Mount the solps-iter folder on Gateway to your local machine:

sshfs username@login.eufus.eu:/ '/mount/point/'

Useful for viewing files at Gateway and for file transfers between Gateway and your local machine.

Unmount the solps-iter folder after work is done:

fusermount -u '/mount/point/'

Don't put your computer to sleep a remote folder is mounted. It messes up my file system browser and I can't unmount, so I have to restart the computer.

Whereami:

cd $SOLPSTOP/solps-iter
./whereami

Run this in the SOLPS environment. It tells you "where you are". A list of locations is in the manual, chapter 1.3.

Text editor in Solaris 10:

dtpad file.txt

Solaris 10 is the operating system of AUG work stations.

List available modules:

module avail

Lists modules which can be loaded using module load module_name.

Set variable value in Solaris 10:

setenv PYTHONPATH /afs/ipp/home/k/katej/Documents

Cview:

cview

Available only in the AUG Solaris environment. Cview is a program capable of quickly visualising data from a given discharge in ASDEX-U or JET. For instance, to look at AUG data from a specific shot, write the shot number into the corresponding space, click Read data, and finally choose Plot time traces. Very handy for a modeller who just wants to know what the heating power is. It is written in IDL. If someone has the time, David Coster would appreciate if COMPASS was connected into it as well. Lisa Sytova calls Cview "the only thing the Solaris environment is good for".

Copy a file using scp:

scp g2kjirak@login.eufus.eu:/path/to/original_file.txt ~/Documents/copied_file.txt

To copy a folder, use the -r (recursive) option:

scp -r g2kjirak@login.eufus.eu:/path/to/original_folder ~/Documents/copied_folder

Treatise on power balance

To understand which heat fluxes should be used in 2PMF [Stangeby 2018], I write this treatise on power balance.

A few assumptions to start with.

The plasma is optically thin. Once energy is converted into radiation through atomic processes (or, in the edge plasma, bremsstrahlung), it cannot be reclaimed by the plasma and will be absorbed by the wall.

The wall is a perfect heat sink. What the wall absorbs, it never returns. Think of a thermodynamic reservoir which is cooler than the studied system. The wall returns particles (in the form of low-energy neutrals) but never returns heat.

The wall is high-recycling. In a tokamak experiment, the particle sources and sinks (gas puff, pumping) are tiny compared to the massive particle sink/source of recycling on the divertor targets. An essential aspect of the steady state is that plasma particles are neutralised on the walls, released, re-ionised (probably near the release point) and travel back inside the (confined) plasma before being expunged back on the wall. This constant re-ionisation will show up later in the power balance treatise.

Finally, the plasma is steady-state, its sole energy source is the heating power $P_{heating}$ and its sole energy sink is the wall. The power exhausted by the wall is therefore equal to the input power.

Why do we study the power balance of a plasma? Because of power exhaust problems of future reactors; more precisely, because of protection of the divertor target (and also the first wall). The target must be protected from two things specifically:

Too high (localised) heat fluxes, which wear on the material through thermal cycles or downright melt it. This not only destroys the tokamak component (so it must be replaced, which is expensive) but it also facilitates such fun events as liquid metal droplets flying into the plasma or changing the target shape and thus localising the heat fluxes even more (which destroys even more parts of the machine). The limit is about 5 MW/m² of perpendicular heat flux (the parallel heat flux can be much higher).
Excessive target sputtering by high-energy ions and neutrals. This not only causes plasma contamination but also wears on the target and changes its shape. Redeposition of the sputtered particles on other surfaces is also a thing. The limit is about 5 eV plasma (ion) temperature above the target.

Thus, even though we know that the total heating power must be exhausted by the wall, the question is where and at what target plasma temperature it will be exhausted.

The question of where is pretty simple - plasma particles carry heat flux along the field lines and the resulting pattern is highly localised on the strike points. To avoid this localisation, the energy carried by plasma particles must be converted to another channel which heats the wall more uniformly - namely radiation released during atomic processes.

The question of target plasma temperature is more complex. Of course, by removing power from the plasma particles, we also cool the target plasma. But, as it turns out, there is another player in the game: momentum (or pressure) losses, as opposed to power losses. Later in the story it turns out that these two players compete while determining the target temperature and, by extension, overall target conditions. The result isn't trivial by far. To weigh all the factors properly, we perform the power balance analysis.

We study the power balance by following the paths $P_{heating}$ takes before it finally reaches the wall. The very first junction happens inside the confined plasma: a part of the injected power is radiated (and then directly deposited on the walls without interacting with the rest of the power balance system) and a part crosses the separatrix into the scrape-off layer in the form of energetic plasma particles. From now on we will disregard the power radiated in the core and only concern ourselves with the reduced input power $P_{sep} = P_{heating} - P_{rad,core}$.

$P_{sep}$ is 100% composed of energy carried by plasma particles. This energy is transferred outward by several means:

Electron and ion conduction. Conduction is what happens when particles bump into each other during chaotic thermal movement and thus transfer their (chaotic) kinetic energy to one another. Since momentum (and thus energy) exchange is the most effective between particles of the same mass, electrons and ions conduct heat almost independently of one another. The conductive heat flux is proportional to the species heat conductivity and its temperature gradient. Electron heat conductivity is much larger than ion heat conductivity, and so the electron conductive heat flux is much higher than the ion conductive heat flux. (Assuming the same temperature gradients. Actually, since electrons are so apt at conducting energy, ion and electron temperature tends to get decoupled in the SOL since electrons lose energy faster via parallel heat conduction than they equilibrate with ions. But even so, the differences in temperature gradient can't compensate for the order-of-magnitude difference in heat conductivities.)
Electron and ion convection. Heat convection is what happens when a group of hot particles travels somewhere as a whole. (Of course, chaotic thermal movement is orders of magnitude faster than this averaged convection velocity, so adjust your mental image from people travelling in a bus to a group of hyperactive kids running around while the whole flock very slowly moves.) The convective heat flux is proportional to the species temperature, density and its averaged velocity. Plasma flows can be ambipolar (an equal amount of positive and negative charges travel together) or carrying a current (ions and electrons travel in opposite directions), and so the relative magnitude of electron and ion convective heat flux can differ. However, considering that ion conductive heat flux is rather low, convection tends to be more important with ions than conduction.

3) Ion kinetic energy. Unlike convection, this heat flux channel is independent of the plasma temperature. Even hurling completely still ions ($T_i = 0$ K) against the wall would deposit their kinetic energy $\frac{1}{2}mv^2$ onto it. Electron kinetic energy is neglected in the power balance because of their orders-of-magnitude lower mass. As a note, usually the ion impact velocity isn't negligible as the sheath accelerates ion to the sound velocity. The sound velocity can, actually, to a good approximation be used as the flow velocity of the ions impinging on the target.

Now as this power travels through the SOL both in the parallel and perpendicular direction, some of it is converted into other channels. Due to gyration around the field lines, both electrons and ions lose energy through emitting bremsstrahlung. If $Z > 1$ species are present in the plasma, they might radiate even without interaction with neutrals. (Fully ionised pure hydrogen plasma doesn't have line radiation because the bare nuclei lack the electron to pass between different states.) In the presence of neutrals, both ions and electrons lose energy via elastic collisions, ion energy can be lost via charge exchange and subsequent line radiation, ions and electrons can recombine (and then radiate the excess energy) etc. Thus the heat flux is gradually chipped away. How strong these losses are depends primarily on the divertor plasma condition. Namely, neutral pressure seems to be the most important quantity.

Now it should be noted that energy isn't the only thing lost from the plasma. Nearly every plasma particles is flying somewhere, and thus it has its associated momentum which, when averaged over a large amount of chaotically moving particles, comes across as plasma pressure. Total plasma pressure is composed of three components:

electron static pressure $en_eT_e$ ($T$ is in eV)
ion static pressure $en_iT_i$ summed over all individual ion species
ion dynamic pressure $\frac{1}{2}m_in_iv_i^2$ summed over all individual ion species (where $v$ is the averaged velocity)

The electron dynamic pressure is neglected because of the order-of-magnitude lower electron mass.

Electrons lose pressure primarily by losing energy via elastic collisions ($T_e$ dropping). Ions lose pressure by a wide variety of channels, most of which involve interaction with neutrals. For instance, when an ion undergoes charge exchange with a low-energy neutral, the difference between the state before (ion and neutral) and after (neutral and ion) is that the new ion has nearly no momentum and the neutral is happily carrying its momentum elsewhere (for example, right to the wall).

No matter how complicated a path the input heating power takes, it all ends up on the wall eventually. The power heating the wall has several components:

Power carried by charged particles. This is equal to the heat flux specified above (electron+ion conduction, electron+ion convection, ion kinetic energy).
Recombination power. Every time an electron is absorbed by the wall, it not only gives over all of its thermal energy but also, sooner or later, finds an atom (or hydrogen ion) to bind itself to. When the electron falls into a bound state, it releases energy roughly equal to 15 eV on average. (The ionisation energy of hydrogen is 13.6 eV.) Every ion-electron pair in the plasma thus implicitly carries this energy, merely by the virtue of being an ion-electron pair.
Radiation power. All of the radiation released by the plasma core and within the SOL falls onto the wall and heats it.
Power carried by incident high-energy neutrals. Such neutrals may be created by charge exchange or elastic collisions with ions.

Notice than in classical sheath theory the sheath is collisionless and isothermal, and thus no heat transfer by conduction occurs within in. Indeed, the charged particle heat flux is usually written as the sum of electron convection, ion convection and ion kinetic energy (eq. (14) in [Kotov & Reiter, 2009]). Sheath theory also postulates that ions hit the target at the sound speed and that the flow is ambipolar (same amount of positive and negative charge). In pure hydrogen plasma, this translates to equal electron and ion particle flux, and thus the total heat flux is proportional to $(T_i+T_e)nc_s$. Since the recombination power is also proportional to the same particle flux $nc_s$, it can be written within the frame of the same formula (refer to eq. (3) in [Stangeby, 2018]) and evaluated on the basis of e.g. probe measurements. However, in target temperatures above 10 eV the recombination power is so small compared to the charged particles heat flux that it can be safely neglected.

The 2PMF attempts to make a difference between the heat channels which we can measure and which are directly tied to the plasma conditions at the target (charged particle heat flux and recombination power) and the heat channels which are tied to the global plasma conditions in a complex way (radiation and neutral particle loads). The first group makes it into the 2PMF equations as the target heat flux

\[q_{\parallel t} \sim T_e n_e c_s\]

while the second group is labelled as "power losses" and is swept up into an overarching, analytically unexpressable power loss coefficient. In fact, the power loss coefficient is defined as

\[(1-f_{pow})q_{\parallel u}R_u = q_{\parallel t} R_t\]

which translates $f_{pow}$ to "how many percent of $P_{sep}$ is transferred to the wall via radiation and neutral particle loads?".

Two side notes here. Firstly, why Stangeby uses $1-f_{pow}$ instead of simply $f_{pow}$ eludes me. He probably has his reasons. Secondly, the major radius $R$ comes into the definition above because we're interested in the lost share of power, not heat flux. The units of $q_\parallel$ are Wm^-2, and depending on the flux tube area the same power passing through its upstream and target end (no losses) might show up as different heat fluxes. In the definition above, Stangeby uses the fact that flux tube area is proportional mainly to the total magnetic field $B$, which is in turn inversely proportional to the major radius, and employs $q_\parallel$ rather than the power. Conversely, SOLPS-ITER produces the power (in W) directly in its variables fhe and fhi, so it immediately offers a precise definition of $f_{pow}$. The problem is, I'm not sure if Stangeby's equations are compatible with that. My guess is that Stangeby's $1-f_{pow}$ is what it is, defined by the equation above. It only loosely means "percentage of lost power". And so even though SOLPS-ITER output might offer a quick way to calculate the lost power directly, the proper way to use 2PMF is to calculate the heat flux as (fhe+fhi)/sx and multiply it by the local major radius.

Heat flux components

According to the SOLPSpy source code, the total heat flux (fht) has the following components:

fhe (W), total electron heat flux as appearing in B2.5 equations (used in equation C.98, defined in equations C.104 and C.135)
fhi (W), total ion heat flux as appearing in B2.5 equations (used in equation C.144, defined in equations C.152 and C.173)
fhj (W), electrostatic energy flux; not sure what it is or where it appears in the equations
fhp (W), ionisation energy flux or potential energy flux (might be the heat flux released by recombination?)
fhm (W), (parallel) kinetic energy flux
- "If fhiycore_kinetic_energy.eq.1, the parallel kinetic energy flux is counted as part of the ion energy flux." (Indeed, kinetic energy appears in the definition of the ion heat flux, so I think this is the default option.)

The sound speed in B2.5 is defined on page 367 of the manual in section C.7.4 (it's the square root of the total charged particle pressure divided by their total mass density).

Section C.8 has some information on the meaning of the heat fluxes, saying: "The energy flux $q_{ENERGY} = q_{e,ENERGY} + q_{i,ENERGY}$ should be associated with the motion of guiding centers in its convective part, BUT it should NOT contain $\tilde{\Gamma}_a$, $\tilde{q}_e$ and $\tilde{q}_i$, since these are modified fluxes where divergence-free components have been analytically removed for numerical stability reasons." Since the ~ quantities appear in B2.5 equations, I am once again confused what fhe and fhi actually are.

In $SOLPSTOP/docs/SOLPS-ITER_3.0.6_Release_Notes.pdf the definition of fht is mentioned, though it's incomplete and lacks physical quantities description. There is also a very brief mention documenting the wlld output.

According to [Kotov 2009], the desired heat flux components are "electron and ion convection, electron and ion thermal conductivity, kinetic energy of the ion flow and work of the viscous force".

Treatise on detachment

This is [Stangeby 2019], reformulated for the needs of a sleep-deprived Friday me.

To protect the divertor (in particular the strike points/lines, the most endangered part of the divertor), one needs to mitigate the following two effects:

Too high (localised) heat flux or thermal cycles.
Sputtering/erosion so strong that it changes the shape/properties of the target. (This carries the added risk of polluting the main plasma with high-Z atoms.)

Now, the divertor is heated and eroded in multiple ways. It's heated by neutrons, radiation, charged particles and more. It's sputtered by both ions and neutrals. However, of these many risks, two are the greatest: the heat flux carried by charged particles and sputtering by incident ions.

Charged particles, unlike neutrons and radiation, form heating patterns which are highly localised along the strike lines. You only need to destroy one part of the divertor to render it unusable in a power plant. Plus, there are feedback effects, such as "melting strike line -> magnetic field line incidence angle steepens -> strike line melts even more", and global risks, such as "divertor develops a MARFE -> VDE -> the top of the chamber melts".
Ion sputtering is particularly powerful due to the sheath acceleration, which neutrals don't experience, and which also makes it localised along the strike lines.

So charged particle heat flux and sputtering are really what divertor protection is all about. To control them, one must constrain the target plasma parameters: the target electron temperature $T_e$ and density $n_e$. Why these two in particular?

The amount of heat the sheath exhausts from the plasma is $q_\parallel = \gamma T_e n_e \sqrt{(T_e+T_i)/m_i}$.
The higher the target temperature is, the bigger the sheath potential drop $\Delta \Phi = 2.8 T_e$, and the higher is the incident ion energy.

Taking both of these into consideration, Stangeby defines the optimum target electron temperature as below 10 eV. The optimum target electron density then depends on the magnetic field incidence angle and $T_{et}$, but generally it's of the order 10²¹ m^-3.

Now that we know that the temperature and density must have a certain value, the question becomes: "How do we do that?" And we're asking both what the engineers should do and what will actually happen in the plasma, so that we have some semblance of dynamic control over the process. At this point, Stangeby brings up experimental and simulation evidence that the target temperature depends strongly on the momentum/pressure and power losses. (He phrases it the other way around, that the losses depend on $T_{et}$, but the gist is the same - "here probably lie the physical processes which ultimately set the divertor plasma parameters".) So the question how to influence the divertor plasma parameters becomes: "How do momentum/pressure and power losses work and how do we control them?"

The physics of momentum/pressure and power losses in a plasma have everything to do with atomic physics. Viewed from the particle level, you've simply got a lot of binary (and three-body) collisions happening at once, possibly over great distances, and between many particle types: hydrogen ions, hydrogen neutrals, impurity ions and neutrals, molecules of all kinds, don't forget photons, there's also the wall and also neutrons... On this level, the total momentum and energy is always conserved. So why do we talk of momentum/pressure and power losses?

The thing is, pressure and power losses refer to these quantities being lost from a particular particle species (singly ionised hydrogen ions = protons, electrons, singly ionised carbon ions, singly ionised and excited carbon ions, $H_2+$ molecules and many more). The system as a whole (plasma, chamber and everything) can't lose or gain momentum, but a particular ion species can lose momentum at the gain of another ion species, neutrals or the wall. The system as a whole (heating systems, cooling systems, electric grid and all) can't lose or gain power, but when a bunch of excited atoms deexcite and lose photons, to them (and the edge plasma in general) this energy is lost, inevitably eaten by the greedy wall. The complex interaction of many components, ions, neutrals, molecules, the wall, photons et cetera is what defines the physics of momentum/pressure and power losses in the edge plasma.

Let's illustrate the principle of momentum and energy (not) conservation. In a binary collision, the momentum is always conserved. The kinetic energy, however, can be converted into internal energy. Not all of it. A part of it must remain - this is the kinetic energy associated with the movement of the centre of mass. When you're sitting in the centre of mass, you see your two particles flying towards each other in a straight line. This is the kinetic energy of their mutual motion, the part of the overall kinetic energy which can be converted into internal energy in a binary collision. When all of it is converted, the particles continue flying side by side. This is what all high-school textbooks call "a completely inelastic collision", in which as much kinetic energy as possible is converted. If you assume that this internal energy is lost a moment later to a photon, then you can have energy losses from your observed species without any momentum losses, since the total momentum was conserved. (Yes, that isn't entirely accurate since the photon carries a little bit of momentum as well. But the kinetic energy loss can be anything from 0 to the entire mutual motion energy, while the momentum loss due to the photon is tiny because it's light.) (...Hehe.)

The contrary momentum losses without energy losses are bit worse off On the other hand, you can also have momentum losses (from your observed particle species) without any energy loss. Consider charge exchange, the reaction where a high-energy ion takes an electron from a low-energy neutral. Here, nearly 100 % of the ion momentum was "lost", that is, the end state is that we have a momentum

Seeing now that momentum/pressure and energy losses can be decoupled in a plasma with many species…

(The treatise ends here. Either I understood the subject well enough or dropped it.)