Skip to content

Creating a new SOLPS-ITER run

At a glance, creating a new SOLPS-ITER simulation consists of the following steps:

  1. Decide what to model - refer to Comparing experiment to model: Scouting a discharge
  2. Initiate the SOLPS-ITER work environment
  3. Create a folder for the new run with the usual structure
  4. Get the input files: an .ogr file containing the wall shape and an .equ file containing the equilibrium
  5. Create a "simulation geometry” .dg file using the DivGeo programme
  6. Create the rectangular grid for B2.5 using carre and import it into DivGeo for check
  7. Create the triangular grid for EIRENE using triang and import it into DivGeo for check
  8. Procure and tweak the boundary conditions files
  9. Run SOLPS-ITER - refer to Running SOLPS-ITER

This tutorial heavily borrows from the DivGeo tutorial, one of the few helpful, upfront tutorials which SOLPS-ITER has. It applies to creating pure-deuterium runs, which are the easiest to set up and converge from "flat profiles" (the initial solution SOLPS-ITER starts running the simulation from) to a physical solution.

1. Initiate the SOLPS-ITER work environment

Log into the machine where SOLPS-ITER is installed. On Soroban and with active COMPASS VPN, this will mean 

ssh -X username@soroban
Then go to your $SOLPSTOP folder (SOLPS-ITER installation folder). Here we use the central installation. 
cd /scratch/solps/solps-iter
Start the tcsh shell and load the environment. 
tcsh
source setup.csh
Finally, specify your device name (needed by DivGeo, not necessary for only running simulations): 
setenv DEVICE compass
See The SOLPS-ITER codebase, How to initiate the SOLPS-ITER work environment for more details. If you wish, use SSHFS to mount the the $SOLPSTOP directory as well. 
sshfs username@soroban-front-01:/scratch/solps/solps-iter /mount/point/
Mount directly the $SOLPSTOP folder (say, /net/soroban-node-06/jirakova/solps/solps-iter/), not a link to it (/scratch/jirakova/solps). This will avoid symlink problems.

2. Create a folder for the new run

  1. Go to the $SOLPSTOP directory

    stop

  2. In the folder solps-iter/runs/, create a folder naming your simulation, say, compass/

  3. In compass/, create the folders baserun/ and run/
    1. baserun/ is the "basic state”, on top of which you can create a multitude of similar SOLPS-ITER runs, all sharing the same geometry and other parameters specified in DivGeo (e.g. a density scan stored in folders run_1.0/, run_1.5/ etc.)
    2. geometry files and meshes should be stored in baserun/
    3. boundary conditions can be stored in baserun/ or in run/; if they are specified in run/, they will override whatever is in baserun/

Important note: The baserun/ folder must be called baserun/ and nothing else! There may be only one baserun/ folder per simulation, but there may be multiple run/ folders per simulation, which can be called whatever you like (run1, n_3.0_PSOL_200, the_best_run etc.). Since baserun/ is what holds the simulation geometry (including grids, meshes, pumping and puffing positions etc.), all the runs in one simulation share the same grid. If you wish to create a run with a different grid, you must create a whole new simulation folder with a new baserun/.

3. Get the .ogr and .equ files

The wall shape file (extension .ogr) is a simple text file with two columns - one are the \(R\) coordinates of the first wall, and the other are the corresponding \(Z\) coordinates. Both the coordinates are in millimeters.

To create an .ogr file, you can use PLEQUE. First, log into Abacus: 

ssh username@abacus
qsub -I
Then load the necessary modules and initialise pyCDB: 
module purge
module load compass/dev
module load pleque/unstable
pycdb
Import PLEQUE and load any equilibrium in the given discharge (in this example, we load the equilibrium from \(t = 1100\) ms): 
from pleque.io.compass import cdb
eq = cdb(shot_number, 1100, revision=-1)
Extract the first wall coordinates [m]: 
R = eq.first_wall.R
Z = eq.first_wall.Z
Now save them as a text file with the extension .ogr: 
np.savetxt('/path/to/first_wall.ogr', np.transpose((R*1000, Z*1000)))
Note the conversion to millimetres in the last step.

If you're modelling a discharge with a modified chamber shape (e.g. lithium divertor tiles or limiter poking out for runaway studies), you may need to modify this file. This can be done manually later in DivGeo. Since both B2.5 and EIRENE presume the chamber to be toroidally symmetric, modelling asymmetries may be challenging. If you're expecting 3D effects to play a large role in your simulation, EMC3-EIRENE might be a better bet to capture the physics than SOLPS-ITER.

There is a separate tutorial on Creating an equilibrium file. Follow it to produce an .equ file informing SOLPS-ITER about the equilibrium shape.

Place both the .ogr and the .equ file into the baserun/ folder.

4. Create the geometry file .dg with DivGeo

DivGeo is a graphical programme which serves to set up the simulation geometry. It's a pain that it's got to be done by hand, but at least a superb tutorial exists for this stage: the DivGeo tutorial. Most of your instructions will come from there. Below you'll find my some observations and notes in bullet points. It's useful to read the bullet points before you move on to the tutorial itself.

  • For starters, skip the first page, we've already done what it says. Start by running DivGeo in the baserun/ folder. (The & will cause DivGeo to run in the background while you can still use the command line. If you close the command line, DivGeo will be terminated as well.) 
    dg &
  • DivGeo tips and tricks:
    • X. Bonnin, S. Lisgo: DG input: important points
    • Ctrl+P to zoom in as much as feasible
    • Ctrl+O to zoom out
    • Ctrl+U to unmark all (This is very useful when specifying element lists, like which elements comprise the targets. By pressing Ctrl+U before marking the target elements, you can avoid unintentionally leaving previously marked elements in the selection. This can give you trouble later, so abuse that Ctrl+U.)
    • All three mouse buttons (left, middle, right) can and should be utilised while working with DivGeo. You can set them in the upper left corner: L for left, M for middle and R for right. I recommend setting the left mouse button to Mark, the right mouse button to Zoom/Pan and the middle mouse button to whichever special action you want to carry out (Reverse normals etc.).
    • Zoom/Pan control: button click = "move to this place”, button drag = "zoom in to this area”
    • From time to time, save the file. When saving for the first time, you have to specify the file name in the Selection box of the Save dialogue. (Not the Filter box, which is higher up and begs to be used instead.) When saving next, you still have to click on the desired file name in the Selection box. Why couldn't they just use Ctrl+S? I don't know…
    • Removed lines/points will appear in blue, and stay in blue. Don't mind them, they are ghosts.
    • There is a button assignment to create sources and points. Don't make them using coordinates like the DivGeo tutorial says.
    • The little purple lines, perpendicular to white lines, are normals. Their directions are precisely set so that SOLPS-ITER knows what's inside and what's outside. See the DivGeo tutorial for information on where exactly they should point.
    • Holding down Shift while clicking will probably do the thing for a lot of instances
    • Hold Shift and button drag Add elements to make a new element from start to end (don't join to an existing element). This is useful when creating ghost triangles.
    • Since you'll need to turn on and off displaying various parts of the simulation domain (equilibrium, mesh, element numbers etc.), float the Display menu. Click View > Display and click on the dashed line on top of the menu. This will make it float.
  • The .ogr file will probably have a much higher element resolution than necessary. Reduce the number of wall elements byCommands > Simplify > Merge/Split elements. Set the maximum deviation to 0.5 mm and press OK. Keep in mind that some of the edges may have an important impact on the physics (neutral reflection etc.). Then, renumber the elements using Commands > Renumber elements, otherwise EIRENE will complain about having too many wall elements (the maximum default value is 300).
  • Before marking out the targets, switch your middle button to Add surface and check where your B2.5 mesh is going to end. What limits it? A wall? Another X-point? Do you need to expand the targets (see further)? Knowing this in advance will save you a lot of target redoing.
  • COMPASS divertors are really small and in the simulations I ran, they only "support” a narrow part of the SOL. If the SOL created in DivGeo seems too narrow to you (like it only spans 1 cm at the outer midplane), go to Edit > Create > Surfaces and press Bounding element. This will show you what's stopping your SOL from being thicker. In the case of COMPASS and my current equilibrium, the limiting factor is the extent of the inner target. Thus, I pretend that the target is a lot bigger and spans some of the chamber as well. Like so:

  • Sometimes the plasma-wall clearance on the upper right of the poloidal cross-section can be really small in COMPASS. The wall then interferes with the B2.5 mesh. David Coster's advice in this case is to manually move the limiter outward and hope real hard you aren't losing any physics with that. If you really really can't move that offending baffle out of the way, but you also really really need a wider SOL region, you need to use the wide grids code version, in which case this tutorial is useless to you.
  • Problem I encountered: only separatrix legs showed after importing the COMPASS equilibrium and importing the SN (single null) topology. See the Confluence page for the solution.
  • Caution! When you make changes to your wall (like add a segment here and there), this messes up all your variable assignments (Structure for instance). When making changes like these, always check and re-define all the variables!
  • Don't haphazardly go and specify your own amount of flux surfaces etc. Using the same grid resolution over and over again has a big advantage - you can adopt already converged solutions from other geometries and use the same post-processing routines for every geometry.
  • After you define the flux surfaces, check that they intersect the targets on the appropriate elements. Small misalignments can lead to huge problems in the future, like in the following example where I only found a problem while triangulating.

(It's the inner target edge - some of the purple-coloured cells intersect the chamber outside the "SOL” edge of the inner target.)

  • Since this always gives me an enormous headache while triangulating, here's a recap of what TRIA-EIRENE value each segment should have.

    • -1: the main wall (above targets) including the "SOL edge” element of the targets
    • -2: the private flux region (between targets) including the "PFR edge” element of the targets
    • 0: the targets themselves, between the -1 and -2 elements; helper triangles; target "back tiles"

  • Keep in mind when setting and debugging TRIA-EIRENE values:

    • Have your elements renumbered (Commands > Renumber elements) and their numbers displayed (View > Display > Numbers).
    • Have the TRIA-EIRENE parameter values displayed (Variables > TRIA-EIRENE parameters > right click on the Index box, hold and drag to the Display values option). They don't get updated automatically, so always right-click Display values again.
    • Make sure your mesh, TRIA-EIRENE parameters, and the target specifications agree! Check where the last flux surface intersects the wall, check that it's properly tagged (-1 or -2) and check that this is indeed the "SOL edge” or "PFR edge”. Sometimes flux surfaces aren't where you first thought they would be.
    • Study the Uinp error output closely. The numbers will help you pinpoint where the problem is.

  • When running the lns command, don't include the .dg extension!

  • When specifying the power radiated from the core, you can use theCOMPASS Prad_insep signal from bolometry. A quick glimpse using WebCDB may be found here.
  • You can leave the general triangle size at 1 for COMPASS. 10 is too big. You can experiment with this and see how thick the EIRENE mesh is, building new triangular meshes with triang in step 6.
  • Problem I encountered: Variable check says that IU and OU targets (inner and outer upper) are wrong, even though I'm using single null topology. See the Confluence page for a solution.

5. Create grid for B2.5 using carre

Keep following the DivGeo tutorial. My notes on this stage are few:

6. Create grid for EIRENE using triang

My notes on this stage:

  • Problem I encountered: triang complains about having too many wall elements. See the solution on the Confluence page.

  • Problem I encountered: Uinp keeps complaining that "The targets must be numbered according to the B2 convention".

    • Renumber the elements in DivGeo (under Commands) so that they follow some sane structure. Save and Output, then run Uinp again.
    • Now check the output. Uinp lists all the elements by their number. For instance attribute -1 0 -2 means that the elements have TRIA-EIRENE parameters > Index set to either -1, 0 or 2.
    • In my case, the problem was that I missed a tiny wall element while marking the -1 structure points.

  • Problem I encountered: after importing the triangulation template, it contains only triangles outside the B2.5 mesh.

    • There are actually two similar-looking files in the triangulation output: say, template.a008.tria.ogr and template.g008.tria.ogr. You want the "g" one.
  • Problem I encountered: Running t in triang says "self-intersecting structure" and then refuses to produce output. See the solution on the Confluence page.
  • Problem I encountered: Running t in triang return an error, while the *.ps file shows a weird, long "crossing line" in the chamber outline. See the solution on the Confluence page.

7. Procure and tweak boundary conditions files

The DivGeo tutorial has finished, so we resume step-by-step instructions.

The boundary conditions (BCs) of SOLPS-ITER are mostly boundary conditions for B2.5 (the plasma part of SOLPS-ITER). EIRENE doesn't offer much freedom as to boundary conditions - it already knows what happens when a neutral hits the wall. There are two ways to specify the boundary conditions: the "standard" way (b2ah.dat etc.) and the "physics" way (b2.boundary.parameters etc.). Don't let the names confuse you. Instructions from the manual are clear - the "physics" boundary conditions are vastly preferred.

Some resources what the BCs mean or how to set them:

In all of the below, copy the files using the cp command in the SOLPS-ITER work environment! Failing to do so (especially with input.dat) may instigate later symlink and timestamp problems.

First, you need to prepare the initial plasma state that SOLPS-ITER will start from. In your baserun/ folder, find the files b2ah.dat.stencil, b2ai.dat.stencil and b2ar.dat.stencil. If they aren't present, look for them without the .stencil part and use those.

(The picture shows what a stencil is in its original meaning. You spray paint onto the stencil and produce a picture underneath. It's a method often used in street art.)

Make a copy of each of them and remove the .stencil part from its name (producing b2ah.dat, b2ai.dat and b2ar.dat): 

cp b2ah.dat.stencil b2ah.dat
...and so on for the other files. Then run (still in baserun/): 
b2run b2ah
b2run b2ai
b2run b2ar
This will set up the initial simulation state: the "standard" boundary conditions for single null (SN) cases, the initial densities and temperatures and the reaction rates, respectively. Check the baserun/ folder for the new files this step has created. We won't actually be using b2ah.dat (the "standard" BCs); instead, we'll define the "physics" BCs in the next step.

In the baserun/ folder, find the files b2.boundary.parameters.stencil, b2.neutrals.parameters.stencil and input.dat. Copy all of them into the run/ folder (created all the way back in step 2) and remove the .stencil part from the name of the first two. 

cp b2.boundary.parameters.stencil ../run/b2.boundary.parameters
The b2.xxx.parameters files contain the "physics" BCs, how the mesh edge behaves and how the B2.5 neutrals behave (or how B2.5 should communicate with EIRENE), while input.dat is automatically generated EIRENE input. The last file of the "physics" boundary conditions, b2.transport.parameters, does not have a stencil automatically generated. If you don't use it, that's just as fine, SOLPS-ITER will just use the input in b2ah.dat instead. If you really want to use b2.transport.parameters, you can use the example file from chapter 5.1.8 of the manual. Refer also to Questions and answers: I copied the b2.transport.parameters file from the manual...

Finally, you need to procure the b2mn.dat file. This is a "master" file - it stores all kinds of important information and when you run SOLPS-ITER, you're explicitly calling this file. If you specify here any information that would normally go into b2ah.dat (boundary conditions), it will override the corresponding instructions in b2ah.dat. This can be useful when you're tweaking your baserun in one of your runs and you want to have all the changes in one place. Furthermore, it is b2mn.dat where you switch between the "standard” and "physics” boundary conditions. To use b2.boundary.parameters instead of b2ah.dat, paste this line into b2mn.dat:

'b2stbc_boundary_namelist' '1'
To use b2.transport.parameters instead of b2ah.dat, use: 
'b2tqna_transport_namelist' '1'
To use b2.neutrals.parameters instead of b2ah.dat, use: 
'b2stbr_neutrals_namelist' '1'
The b2mn.dat file is not produced automatically. According to Xavier Bonnin, this is to force users to build one up from scratch rather than blindly use the default file. My experience has been that a user will steal someone else's b2mn.dat file and then use that blindly. (Sorry, Xavier.) For five years, I used the b2mn.dat provided by Stefano Carli on the September 2018 SOLPS training, without knowing what switches were inside it.

As to your own b2mn.dat file, you have several options:

  • Use our annotated basic b2mn.dat. The annotations explain what the switches mean and what their default values are. Note that this was made for SOLPS version 3.0.6. You may be running a newer version, where some of the listed switches are obsolete.

  • Go through the b2mn.dat switches in Honza Hečko's B2 input docs viewer. I've compiled the switches I found interesting on my October 2023 read-through.

  • Copy b2mn.dat from the manual, section 5.1.5 b2mn.dat.

  • Copy it from $SOLPSTOP/runs/examples, where several delightfully annotated examples are provided.

  • Copy it from one of the example runs. Downloading an example run is described in the manual, section 1.5 Examples, and in $SOLPSTOP/runs/examples/README.md.

Now all your files are ready! To make sure everything is ready, run in the simulation folder (that is, in $SOLPSTOP/runs/compass/ if you named your run compass): 

correct_baserun_timestamps
This makes sure the timestamps of your files make sense. SOLPS-ITER somehow works with the timestamps and it can cause problems when they're set up badly. Then in the run/ folder: 
setup_baserun_eirene_links
b2run -n b2mn
The first command makes sure that when you run SOLPS-ITER in the run/ folder, EIRENE knows where its files are. The second command is a dry run of SOLPS-ITER which checks if all required files are available. If it calls b2mn.exe among the first lines, all is good. If it calls, say, b2ag, you may have a problem.

And that's it! You're good to go and run this simulation. To be continued in the Running SOLPS-ITER.