Skip to content

Feature blog aims to introduce additional important features of SOLPS-ITER which did not fit in the main step-by-step tutorials. Familiarity with the basic workflow is assumed.

Wide grids for the fluid solver

Motivation

Historically, the B2.5 fluid code was only able to work with the so-called structured computational grids. Cells within a structured grid form a regular pattern with fixed number of cells (per region) in poloidal and radial directions. This allows for more human-friendly cell indexing and looping in the code, relying on rows & columns. Unfortunately, it also requires the radial boundary of the SOL plasma fluid to be defined by exactly one magnetic surface. The surface typically does not follow the shape of the wall, leaving gaps between the grid boundary and the wall.

The KU Leuven group is currently finalizing an upgrade to the B2.5 code, which allows the use of unstructured grids, where the cells can be arbitrarily added/removed to/from any row or column. It is then possible to extend the grid from a narrow grid to a wide grid simply by adding cells in the radial direction up to the vessel wall as needed, while still keeping the proper alignment with magnetic surfaces. Note that in practice the process is reversed and the grid is instead cut out from a large structured grid spanning the whole vessel outline.

Typical applications for wide grids extended to vessel wall, i.e. vessel mode, include:

  • closed divertors and baffles (plasma around the baffles is typically not negligible)
  • complex divertor designs such as the Super-X divertor on MAST-U
  • strong radial plasma fluxes, large SOL widths

Alternatively, if extension of the grid to the vessel wall is not possible (e.g. bad equilibrium data) or not desired (e.g. adds too many cells, slows down computation), it is possible to create a smaller unstructured grid to only refine problematic divertor target geometry. The goal is to avoid strong cell deformation and improve orthogonality near the targets. This is referred to as the target mode grid extension.

More info

The Wide Grids version includes several other interesting additions from the KU Leuven group that are not discussed here, namely:

  • K-model (K = turbulent energy) for self-consistent estimation of anomalous transport coefficients within the simulation, where the dominating turbulent transport is assumed to be the interchange instability
  • algorithmic differentiation (AD) optimization method for input parameters
  • hybrid neutrals model, i.e. applying kinetic neutrals only where needed
  • advanced fluid neutrals model, i.e. more accurate standalone runs

You can read more about these features on the SharePoint, mainly this pdf and presentations in SOLPS-ITER Extended Grids Workshops, and there are also corresponding published papers (see the references in those documents). In some cases, there may be a description in the manual (compiled on the WG code branch).

The WG version of SOLPS-ITER

At the moment (June 2024), the wide grid version of the code 3.2.0 is still in development and it is not merged into the standard master / develop branches. Instead, checkout one of the branches below and recompile the code as described in the How to update SOLPS-ITER instructions:

  • feature/wg_workflow - the "official one"
  • feature/us_grid_input - the bleeding edge from Leuven, currently (June 2024) recommended
    • has important additions such as the improved cut-cell algorithm carreMode=3
    • may be merged soon, use feature/wg_workflow if you cannot find this one anymore

Branch names may change

As the development progresses, it's possible that the names of the active branches have become different from what is stated above. Feel free to check the repository for more up-to-date branches. Eventually, the situation should stabilize and the WG version should be released as the 3.2.0 version sometime in 2025.

Important note before you start: When working with the wide grid version, keep in mind that the wide grids code diverged quite a long time ago (approx. version 3.0.6), so some of the more recent features are not yet present. Furthermore, the unstructured grid format makes most of the output files completely incompatible with any external postprocessing tools & libraries that work with the standard SOLPS-ITER versions. For matlab users, there are updated matlab tools readily available in the solps-iter/scripts/MatlabPostProcessing directory.

Reference materials

The wide grid workflow is not yet documented in the official SOLPS-ITER documentation. In addition to this brief tutorial, it is recommended/necessary to read through the following materials from the SharePoint:

DivGeo+Carre2+Triang workflow

Prerequisites:

  • installed and compiled an up-to-date wide grid version of SOLPS-ITER
    • ideally feature/us_grid_input branch, which supports carreMode=3 (improved cut-cell algorithm)
  • equilibrium data that extends well beyond the vessel wall
    • depends on the situation, the more the better, it can always be cropped back
    • e.g. 25%-50% of vessel dimension
  • other data required for a standard narrow grid (vessel outline, target geometry, ...)

The workflow is very similar to the original one, most (all) of the work being done in DivGeo. After preparing the .dg project based on the instructions below and after exporting with File -> Output, simply run the traditional commands. Notice that carre is now renamed to carre2, to reflect its major update.

lns <your-project-name>
carre2 -    # Go through the steps by pressing enter
triang      # Go through the steps by pressing enter

Back to DivGeo. The main workflow difference is in the following new or updated DivGeo Variables that need to be specified. See also their help text in DivGeo.

  • Carre2 setup - new
    • general configuration for Carre2 that ends up in carre.dat, see help text in DivGeo and below
    • assigning fcLbl (face label) index to all structure elements
    • carreMode=0, gridExtensionMode=0, equExtensionMode=0 results in the standard narrow grid algorithm
  • Midplane definition - new
    • inner & outer midplane cells are now defined by two user-specified virtual elements, which intersect the cells along the full radial width of the grid, core to vessel wall
    • it used to be defined by specifying a cell index in b2mn.dat (b2mwti_jxi and b2mwti_jxa)
  • Structure - updated
    • Structure.Vessel specifies the complete vessel outline, which is used to cut out the mesh, required for gridExtensionMode=2 (vessel mode)
  • Target specification, Vessel specification - updated
    • each specification for a target or a vessel section is now assigned a fcLbl (face label)
    • note that the CARRE guard length is still being specified here

The first new concept is the fcLbl (face label) index. Contrary to a structured grid (old), the user needs to manually categorize vessel and target boundaries so that the b2.boundary.parameters and b2.neutrals.parameters stencil files can be properly generated. Each element of the vessel wall outline that limits the desired grid (including the real targets) needs to be linked to one of the Target specification or Vessel specification variables using the fcLbl index (arbitrary non-negative number). The Carre2 setup variable menu is used to assign fcLbl to elements and each Target specification and Vessel specification variable has a fcLbl property. In case of Target specification, it is recommended to select values corresponding to their numbering (1, 2 SN or 1, 2, 3, 4 DN) to avoid confusion. Elements with the same fcLbl should belong to one continuous section, which usually makes it necessary to create several Vessel specification for the different wall sections divided by targets.

The second new concept is the definition of the midplane. In the new version, all projects now must include a virtual element (2 connected points) for inner and outer midplane. These 2 elements should fully intersect the grid from core to vessel at the user-determined location of each midplane. Add them to the Midplane definition as well as Elements not for Eirene (to make sure they are virtual, ignored).

Read further and refer to the materials on the SharePoint (Workflow_divgeo_carre2_uinp.pdf, 20230815_carre2_presentation.pdf) to get more details about the new variables mentioned above and about using the vessel mode and target mode grid extension algorithms from Carre2.

Narrow grid

To build a narrow grid just like in the old version, configure Carre2 as follows (the defaults)

  • carreMode=0
  • gridExtensionMode=0
  • equExtensionMode=0

Make sure to still properly specify Midplane definition and assign fcLbl indexes to all structure elements. Other than that, follow the standard steps from the old DivGeo tutorial.

Target mode extension

Target mode is not described here at this moment, please refer to Workflow_divgeo_carre2_uinp.pdf. In general, the approach is similar to Vessel mode, but simpler.

  • carreMode=3 (better results) or carreMode=2 (worse results)
  • gridExtensionMode=1 (target mode)
  • equExtensionMode=0

Vessel mode extension

To build a wide grid extending all the way to the vessel wall, configure Carre2 to use a cut-cell algorithm in vessel mode

  • carreMode=3 (better results) or carreMode=2 (worse results)
  • gridExtensionMode=2 (vessel mode)
  • equExtensionMode=0

Note about equExtensionMode

The equExtensionMode parameter is used to adjust and extrapolate equilibrium data to enable the grid extension in problematic cases. It can help when the equilibrium data are not available at a large-enough distance past the vessel wall or when the poloidal coils are too close to the vessel wall and strongly deform the magnetic field. As the DivGeo help text suggests, this feature is for "expert use only" and it is not discussed here further.

The approach is best described in pictures such as here Workflow_divgeo_carre2_uinp.pdf. The main idea is to build a narrow mesh that touches user-defined virtual targets positioned outside the vessel wall, far enough to ensure the grid covers the whole vessel outline. Note that often the SN cases need to be prepared as DDN cases. This is because the second X-point is often located just outside of the vessel and becomes part of the expanded grid.

Tip

Changing SN case to DDN case requires importing an appropriate DDN topology File -> Import -> Topology, adding a variable Extra targets for DN (similar to Structure), adding two Target specification variables and making sure the target specifications 1-4 are assigned to the targets in the "conventional DivGeo order". See the standard DivGeo tutorial presentation for more details.

The individual steps can be summarized as follows:

  1. Prepare an equilibrium that spans well beyond the vessel wall (e.g. 25%-50% of vessel dimension).
  2. Switch to DDN topology for SN case if needed.
  3. Manually add virtual targets (individual closed polygons) at rough positions outside the vessel wall, to be adjusted later.
    • Make sure the surfaces have 2+ elements (required by Structure). In fact it is useful to split it into e.g. 10 elements to be able to later shape the target.
  4. Manually add virtual "limiting triangles" to have better control over the surfaces generated later.
  5. Assign target surfaces to Structure and Extra targets for DN. Assign only the helper triangles to Structure.Structure. Assign the vessel outline, including the real targets, to Structure.Vessel.
  6. Do a few steps unrelated to the mesh building process:
    1. Define the inner and outer midplane elements in Midplane definition.
    2. Choose a unique fcLbl index to each Target specification and Vessel specification.
    3. Assign each vessel (or real target) structure elements to the corresponding fcLbl index, specifying sections with shared boundary conditions.
  7. Assign virtual things to Elements not for Eirene.
    • the midplane elements
    • the virtual targets
    • the virtual limiting triangles
  8. Create surfaces and grid points in all regions as usual.
  9. Adjust the shape and position of the virtual targets so that the grid extends past the vessel wall and try to make the target surface roughly orthogonal to the magnetic surfaces (it helps). Use Commands -> Rebuild Carre objects to see the results.
    • try cropping the equilibrium data in different ways if the edge surfaces do not behave nicely
  10. Adjust CARRE guard length in each Target specification as appears sensible.
    • start with 0 for all targets with good orthogonality to the intersecting magnetic surfaces
    • increase the guard length if carre2 command g reports "orthogonality not reached" issues
  11. Run File -> Output, lns ..., carre2 - and view the generated grid.
    • This is where all the magic happens, the cells are cut based on the vessel outline and iteratively adjusted.
    • If needed, repeat from step 8, adjusting the targets, surfaces, grid points, guard lengths.
  12. When you are happy with the fluid grid, proceed with triang. It should be a breeze at that point, since it is fully based on the fluid grid.

See last slide of 20230815_carre2_presentation.pdf for a few common issues and their solution.