INGRID: an interactive grid generator for 2D edge plasma modeling
B. M. Garcia, M. V. Umansky, J. Watkins, J. Guterl, O. Izacard
IINGRID: an interactive grid generator for 2D edge plasma modeling
B. M. Garcia, a) M. V. Umansky, b) J. Watkins, c) J. Guterl, d) and O. Izacard e)1) University of California - Santa Cruz, Santa Cruz, California,USA Lawrence Livermore National Laboratory, Livermore, California,USA Brigham Young University, Idaho, USA General Atomics, San Diego, California, USA (Dated: March 3, 2021)
A new grid generator for tokamak boundary plasma INGRID (Interactive Grid Generator)is a Python-based code for calculating grids for boundary plasma modeling, for variety ofconfigurations with one or two X-points in the domain. Based on a given geometry of themagnetic field, INGRID first calculates a skeleton grid which consists of a small numberof quadrilateral patches, then it puts a subgrid on each of the patches, and joins them ina global grid. This “divide and conquer” strategy allows treating in a uniform way a va-riety of configurations with one or two X-points in the domain. This includes single-null,double-null, and variety of configurations topologically equivalent to snowflake-plus orsnowflake-minus configurations. INGRID design allows generating grids either interac-tively via a parameter-file driven GUI, or using a non-interactive script-controlled work-flow. Results of testing demonstrate that INGRID is a flexible, robust, and user-friendlygrid generation tool for tokamak boundary plasma modeling. a) Electronic mail: [email protected] b) Electronic mail: [email protected] c) Electronic mail: [email protected] d) Electronic mail: [email protected] e) Electronic mail: [email protected] a r X i v : . [ phy s i c s . p l a s m - ph ] M a r . INTRODUCTIONA. Tokamak edge plasma modeling Research in tokamak edge plasma physics is critical for realizing practical fusion energy anddesigning future fusion reactors. One of the greatest challenges that tokamak edge plasma re-searchers face today is determining effective methods for controlling particle and heat fluxes ontokamak plasma-facing components (PFC) while maintaining good core-plasma performance. Apossible solution is the use of advanced divertor configurations .The traditional X-point divertor configuration uses a first-order null point for the poloidal field,which is usually placed at the bottom of the core plasma, or at the top. The traditional double-nullconfiguration uses one first-order X-point at the bottom and one at the top.In contrast, several advanced divertor configurations have been proposed where a secondaryX-point is included in the divertor region. These include snowflake-like configurations and theX-point Target configuration. Snowflake-like configurations approximate a configuration with anexact second-order null of the poloidal field dubbed “snowflake” . In practice, instead of an exactsecond-order null, a configuration is used where two regular X-points are brought close together,which leads to snowflake-plus and snowflake-minus configurations . On the other hand, for anX-Point Target configuration , a secondary X-point is introduced in the divertor far away from theprimary X-point, in the divertor leg near the target plate.Each of these divertor configuration is characterized by locations of the primary and secondaryX-points in the domain. The primary X-point is the most significant as it separates the plasma intothe hot core region and colder scrape-off layer (SOL) region. However, a secondary X-point helpsredirect and distribute the flux of plasma particles and energy over multiple locations (strike points)on the material surface. Furthermore, a secondary X-point may help increase plasma radiation inthe divertor, and potentially it may cause other interesting and important effects in divertor plasma. B. Grid generation for tokamak edge plasma simulations
Tokamak boundary and divertor plasma modeling relies heavily on edge transport modelingcodes such as UEDGE , SOLPS , EDGE2D , just to mention a few major ones. These codes aresimilar in many ways; they all solve the time-evolution fluid equations for toroidally-symmetric,collisional plasma based on the Braginskii equations, using ad-hoc radial transport coefficients.2he simulations are usually carried out in the actual geometry of a modeled tokamak, to accountfor details of magnetic field geometry and plasma-facing components.Computational grids for tokamak boundary plasma modeling are usually chosen to follow themagnetic flux surfaces, to avoid numerical pollution caused by the extreme anisotropy of plasmatransport along and across the magnetic field . Thus the computational grid has to follow theunderlying magnetic field, and with one or several X-points present in the simulation domain thegrid topology can become highly nontrivial.There are several grid generators for tokamak edge plasma region currently in use. The UEDGEcode uses a grid generator that is a part of the UEDGE package, SOLPS normally uses grid gen-erator CARRE , and EDGE2D usually relies on grid generator GRID2D . These are sufficientin most cases for modeling single-null and double-null configurations. However modeling of ad-vanced divertors may require incorporating secondary X-points in the divertor region, and gridgenerators currently in use for the major edge transport codes are not inherently designed to pro-duce computational grids for general configurations containing more than one X-point at arbitrarylocations in the domain.To increment the capabilities for grid generation for tokamak boundary plasma modeling, inparticular for advanced divertors, a new grid generator INGRID has been developed, as describedin the present report. INGRID (Interactive Grid Generator) is a Python based, interactive, gridgenerator for edge plasma modeling that is capable of handling configurations with one or twoX-points anywhere in the computational domain. INGRID provides a robust set of tools such asan easy to use GUI intended for users of all levels. By internally handling the challenges that typ-ically arise with generating grids for tokamak edge plasma region, INGRID can indeed improveefficiency in a user’s workflow for edge-plasma modeling. The INGRID algorithm’s inspirationwas drawn from an older IDL-based project GINGRED where the “divide and conquer” strat-egy for grid generation was first tried. An important motivating factor for implementing INGRIDin Python was using an open-source language with highly advanced numerical and graphical li-braries. II. CLASSIFICATION OF EQUILIBRIA
To understand the range of geometric possibilities in presence of one and two X-points, con-sider the diagrams in Fig.(1). 3f there is a single X-point in the region it defines a separatrix, Fig. (1 (a)). The X-pointis a self-intersection point of the separatrix that divides the plane into three topologically distinctregions. One is the “core plasma region”, containing the magnetic axis, or the O-point. Next, thereis a region lying opposite to the core plasma region, across the X-point, and it is called the “privateflux region”, or PFR. And the remaining part is the “common flux region”, or scrape-off-layer(SOL) region.A second X-point can be added outside of the core plasma region. Ignoring the degeneratecase when the secondary X-point is on the primary-separatrix, there are two topologically distinctpossibilities: with respect to the primary separatrix the second X-point can be either in the privateflux region, Fig. (1 (c)); or in the common flux region Fig. (1 (b)). The former case is called“snowflake-plus” and the latter case is called “snowflake-minus” .However, from the grid generation perspective, we consider further variations of “snowflake-like” configurations, as shown in Fig. (1). Consider a line orthogonal to flux surfaces and passingthrough the secondary X-point X , and consider the intersection of this line with the primaryseparatrix, X (cid:48) . For “snowflake-minus” configuration there five possibilities for the projection point X (cid:48) . It can belong to: (i) the arc [ M W , M E ] connecting the two midplane-level points, or (ii) the arc [ M W , X ] , or (iii) the arc [ M E , X ] , or the arc (iv) [ X , S W ] connecting the primary X-point and oneof the “strike-points”, or (v) the arc [ X , S E ] . For “snowflake-plus” configuration, there are twopossibilities for the projection point X (cid:48) . It can belong to: (i) [ X , S E ] , or to (ii) [ X , S W ] .Based on the location of the secondary X-point X and its orthogonal projection on the primaryseparatrix X (cid:48) , we use the following notation for the configurations with two X-points:• UDN: SF − , X (cid:48) ∈ [ M E , M W ] • SF15: SF − , X (cid:48) ∈ [ M E , X ] • SF165: SF − , X (cid:48) ∈ [ M W , X ] • SF45: SF − , X (cid:48) ∈ [ S E , X ] • SF135: SF − , X (cid:48) ∈ [ S W , X ] • SF75: SF + , X (cid:48) ∈ [ S E , X ] • SF105: SF + , X (cid:48) ∈ [ S W , X ] . Our geometric classification here is topology-based, it applies tomore general situations when the two X-points can be far apart; but the notation introduced inliterature is still useful. All in all, with the single-null (SNL) configuration included, for eitherone and two X-points in the domain, there are eight possible configurations. We don’t considerdegenerate cases where the secondary X-point is exactly on the primary separatrix, or the projectedpoint X (cid:48) is exactly on the primary X-point X , or it is exactly on a midplane point M E or M W ; theassumption is that a practical, experiment-relevant configuration would always have some finitedegree of asymmetry to fall into one of the eight considered categories. III. COMPUTATIONAL ALGORITHM METHODOLOGYA. “Divide and conquer” strategy
The INGRID workflow includes two main steps: (i) constructing a “skeleton grid” (also calledfurther a “Patch-Map”) which corresponds to the geometry of the magnetic field in hand andconsists of a small number of quadrilateral patches; and (ii) putting a subgrid on each of thepatches. This is illustrated in Fig. (2) where a Patch-Map is shown with one of the patchescovered with a subgrid.The skeleton grid is constructed as a smallest possible grid to be aligned with the given mag-netic field and respecting the magnetic field topology. The geometry of magnetic flux surfaces, inparticular the X-points and the magnetic axis, and the geometry of plasma facing material surfacesall together define a patch map. For calculating a subgrid, the code divides each quarilateral patchinto a number of radial and poloidal zones according to user-provided input. Finally, all subgridsare joined together to produce the global grid.
B. Magnetic field interpolation
Input data for grid generation come in the form of the poloidal magnetic flux Ψ sampled on rec-tilinear grid in R , Z , from an MHD reconstruction code such as EFIT or TEQ. For obtaining thevalues of the poloidal magnetic flux Ψ and its derivatives between data points of a provided mag-netic equilibrium, INGRID utilizes bicubic interpolation . Bicubic interpolation needs function5alues and derivatives to be provided on the original grid, and for our use of bicubic interpolation,the derivatives ∂ Z Ψ , ∂ R Ψ , ∂ R , Z Ψ are first evaluated at the original grid points by finite difference.Flux surfaces are reconstructed in INGRID by integrating the ODEs,˙ R = − R ψ z (1)˙ Z = R ψ r (2)The bicubic interpolation guarantees smoothness of Ψ at the edges of cells of the original R , Z grid, so the resulting flux surfaces are smooth. C. Calculation of reference points
The topology of magnetic flux surfaces in tokamak edge plasma is defined by relative positionsof X-points and the magnetic axis. These key reference points are calculated in INGRID by findingnulls of the poloidal field, solving the equation ( Ψ R ) + ( Ψ Z ) = D. Topology analysis
Based on the user input, INGRID seeks a configuration with either one or two X-points inthe domain. If one X-point is required, this is a single-null (SNL) configuration. Although inthe tokamak edge plasma community it is common to distinguish the “upper single null” and the“lower single null configurations”, for INGRID there is no distinction between those. Instead ofusing “lower” and “upper” for the divertor, and “inner” and “outer” for target plates, INGRIDuses the notion of the “compass” directions North-South-East-West associated with the primaryX-point, and the North direction is defined to point into the core plasma along the ∇Ψ direction.Then for a single-null configuration, one of the plates is in the South-West direction (denoted as a6West” plate, and the other one is in the South-East direction, and is denoted as the “East” plate,as illustrated in Fig. (7).If two X-points are required to be in the domain, INGRID performs further analysis to see inwhich category the given magnetic configuration falls. First, it determines whether the secondaryX-point is in the private-flux region or in the common-flux region (SOL) with respect to the pri-mary separatrix. Next, an orthogonal projection is constructed from the secondary X-point to theprimary separatrix. If the secondary X-point is in the private-flux region with respect to the pri-mary separatrix, this can be either SF105 or SF75 configuration. Then an orthogonal projectionis constructed from the secondary X-point to the primary separatrix, and based on the location ofthis projection the specific configuration is identified.In case the secondary X-point is in the common-flux region with respect to the primary sepa-ratrix, and the secondary X-point and the primary X-point are on opposite sides of the midplane(the horizontal plane through the magnetic axis) this is the unbalanced double null (UDN) config-uration, see Fig. (8).In case the secondary X-point is in the common-flux region with respect to the primary sepa-ratrix, and the secondary X-point and the primary X-point are on the same side of the midplanethis can be on of four possible cases: SF15, SF45, SF135, or SF165 configurations, see Figs. (1,9-14). An orthogonal projection is then constructed from the secondary X-point to the primaryseparatrix, and based on the location of this projection the specific configuration is identified. E. Patch-Map construction
After the analysis of magnetic geometry for a given magnetic field and establishing what con-figuration corresponds to it, INGRID creates a corresponding Patch-Map which is an orderedcollection of quadrilateral patches defining the skeleton grid. A Patch-Map is constructed usingnumerical line tracing of poloidal and radial surfaces through the X-points, and radial and poloidalsurfaces defining the domain boundaries. Radial domain boundaries are flux surfaces correspond-ing to maximum and minimum values of the poloidal flux function Ψ , these values are defined bythe user in the input file. The poloidal domain boundaries are target plates surfaces, also definedin the input file.For each of the divertor configurations that INGRID can use - which includes a single-null,unbalanced double-null, and six snowflake-like configurations - there is a specific type of Patch-7ap that defines the topology of this configuration. For example, for a SNL configuration shownin Fig. (7), a Patch-Map includes two radial zones, two poloidal zones defining divertor legs, andfour poloidal zones defining the edge plasma domain around the last closed flux surface. Such aPatch-Map that contains twelve patches is necessary and sufficient to represent a general single-null geometry, albeit in a most basic and crude way. Furthermore, a finer grid representing asingle-null geometry can be always represented as this Patch-Map with local refinement appliedto one or several of these twelve patches. For a more complicated unbalanced double null (UDN)geometry shown in Fig. (8), the Patch-Map must include three radial zones because there are twoseparatrices there. There are four poloidal zones to represent four divertor legs there, and togetherwith four poloidal zones covering the core domain there are total eight poloidal zones. All in all,there are twenty four patches in this case. Similarly, for each of the snowflake-like configurationsthere are twenty four patches, as illustrated in Figs. (9-14). F. Grid construction
For a given magnetic configuration, a Patch-Map represents a very crude grid where each Patchis a “quadrilateral” with four vertices. The radial sides of this quadrilateral are defined by two fluxsurfaces, Ψ ( R , Z ) = Ψ and Ψ ( R , Z ) = Ψ . The poloidal sides of a Patch are usually constructedto be aligned with ∇Ψ , which makes the skeleton grid locally orthogonal.However, more generally the poloidal sides of a Patch can deviate from the ∇Ψ direction. Forexample, for those patches that contain the poloidal boundaries of the domain, given by the targetplates, one of the sides is defined by the target plate shape. The curve describing the target platecan be arbitrary, as long as it does not form “shadow regions”, i.e., Ψ is a continuous function ofthe length along the plate.Going beyond the skeleton grid, a Patch can be divided in a number of radial and poloidalzones, forming a subgrid local to this patch. The radial zones are constructed to be aligned withflux surfaces, so the global grid remains aligned with the poloidal magnetic field. For the poloidalzones, the main algorithm is based on dividing the patch poloidally into equal size segments.However, as described further, there are options in the code for controlling the radial and poloidaldistribution of subgrid.The radial and poloidal dimensions and distribution of subgrid on a given Patch are not entirelyindependent of subgrids on other patches as the global grid still has to be Cartesian in the index8pace. Thus the poloidal grid has to be consistent for those patches that are stacked on top of eachother radially, and the radial grids have to be consistent for those patches stacked on top of eachother poloidally. G. Grid customization
INGRID provides users a number of tools for customization of generated grids, which can becontrolled via the parameter file. Users can modify both the Patch-Map and the subgrids in orderto optimize the global grid.Default settings for constructing a Patch-Map use the horizontal plane through the magneticaxis, commonly referred to as the midplane. However, INGRID allows shifting the magnetic axisvertically and horizontally. Moreover, instead of using the horizontal direction for the midplane,the user can set two angles defining a “generalized midplane”.Also, for those patches that include an X-point as one of their vertices, the default poloidalboundaries use in the East and West directions from the X-point along the ∇Ψ direction. However,the user can redefine those curved, replacing them by straight lines in a desired direction.For fine-tuning the grid, subgrids can be adjusted as well. By default, during Patch refinement,grid seed-points are distributed uniformly in length along the radial boundaries and distributeduniformly along the poloidal boundaries in locally-normalized Ψ . This default behavior can bechanged so that grid seed-point placement obeys a user specified distribution function.Another important customization feature in INGRID is a “ distortion_correction " tool formitigating grid shearing. This tool allows the user to set limits on deviation between the poloidaldirection and the ∇Ψ direction. This effectively allows enforcing nearly orthogonal subgrids inselected patches. If the “ distortion_correction ” constraint cannot be satisfied (vertex leavesthe Patch), INGRID will backtrack until the vertex is within the Patch bounds. An example of the distortion_correction feature applied to a grid can be seen in Fig.( 3). IV. PERFORMANCEA. Scaling of calculation time
The results of INGRID timing test on a MacBook computer are shown in Table (IV A) and inFig. (4). The scaling appears sublinear for small grids; for larger grids it asymptotes to linear.9ote that the cost of grid generation is not significant in a typical edge plasma modeling work-flow; running the simulation takes orders of magnitude more computing time. This scaling makesINGRID practical for constructing large grids.SNLCells Per Patch Total Cells Time (s)9 108 48.32192316 192 63.92034725 300 82.62227936 432 100.04136849 588 118.41324464 768 138.11350481 972 153.613585100 1200 171.291218121 1452 189.555594144 1728 198.343664169 2028 215.742957196 2352 236.941801225 2700 250.419288 10F75Cells Per Patch Total Cells Time (s)9 243 73.64441016 432 99.18981225 675 127.37005836 972 155.95890549 1323 181.51856564 1728 206.47466981 2187 230.737183100 2700 253.775640121 3267 281.557351144 3888 305.958863169 4563 332.568824196 5292 359.910149225 6075 387.905040
B. Benchmark testing
To verify grids calculated by INGRID, several benchmark tests have been performed with theUEDGE code.In these testes, UEDGE solutions were compared, using grids from INGRID and grids pro-duced with the UEDGE internal grid generator; for the same physics problem statement, the sameboundary conditions, using the same (or very close) domain geometry.In one of these test problems, a snowflake-like SF75 configuration was used, based on magneticreconstruction data from the TCV tokamak. The UEDGE grid generator cannot deal with theSF75 configuration directly; but it can be set up to treat each X-point as a part of a separate SNconfiguration, and then joining two such SN grids together one can produce a grid for the fullSF75 domain.The UEDGE code was set up to solve to the steady state the time-evolution equations for plasmadensity, plasma parallel momentum, ion thermal energy, and electron thermal energy.11 ∂ t n i + ∇ · (cid:104) n i (cid:126) V i (cid:105) = S i (4) ∂∂ t (cid:2) Mn i V i , || (cid:3) + ∇ · (cid:104) Mn i (cid:126) V i V i , || − ˆ η i ∇ V i , || (cid:105) = S m , || (5) ∂∂ t (cid:20) nT i (cid:21) + ∇ · (cid:20) n i T i (cid:126) V i + (cid:126) q i (cid:21) = S E , i (6) ∂∂ t (cid:20) nT e (cid:21) + ∇ · (cid:20) n e T e (cid:126) V e + (cid:126) q e (cid:21) = S E , e (7)Here we use the standard notation: n i is the plasma density, (cid:126) V i is the plasma fluid velocity, T e , i is the electron and ion temperature, (cid:126) q e , i is the electron and ion heat flux, S i , S m , || , S E , e , i are sourcesof plasma density, parallel momentum, and electron and ion thermal energy.The grids used for the calculation are shown in Fig. (5). The grid generated with the UEDGEgrid generator is constructed to be strictly locally orthogonal; the grid from INGRID is not orthog-onal. Also, there is slight difference in the domain shape. Still, the steady state solutions exhibitessentially the same distributions of plasma density, temperature, and parallel flow velocity, as canbe seen in Fig. (6). V. SOFTWARE DESIGN AND USER INTERACTIONA. Choice of development in Python
INGRID has been exclusively developed in the Python programming language. Python hasan advantage as a free, community supported language with extensive graphical and numericallibraries. In addition to the developer tools readily available, the large scientific computing userbase puts INGRID in a good position for extensive use within the edge-plasma modeling commu-nity and continued development. Python is a choice of object-oriented programming language thatis being increasingly utilized in major tokamak plasma modeling projects such as OMFIT andPyUEDGE . This makes Python a natural and consistent choice to carry out software develop-ment needs. INGRID makes heavy use of Python’s standard computational and graphical librariessuch as numpy, SciPy, matplotlib, SymPy, PyYAML. and tkinter . Software project setup,12aintenance, and installation is easily achieved in Python through native package structuring con-ventions and external package management tools such as setuptools. Within the INGRID packageare a variety of modules containing classes related to geometric representations, line tracing, inter-polation, and other INGRID management tasks. Two INGRID subpackages are dedicated to GUIdevelopment and magnetic topology modules. B. INGRID package organization
The top-level INGRID package includes a collection of modules responsible for the essen-tial grid-generation processes, as well as two subpackages dedicated to the GUI and supportedmagnetic-topology models. Modules ingrid and utils contain classes responsible for man-agement and execution of INGRID functionality, whereas modules geometry , interpol , and line_tracing contain classes responsible for computational tasks such as topology modeling,interpolation of data, and line tracing.The Ingrid class is contained within the ingrid module and is designed to provide a high-level interface for users. This
Ingrid class is used to activate INGRID’s GUI mode and also con-tains high-level methods for importing data, visualizing data, analyzing data, grid-generation, andexporting of data; all of which can be utilized in Python scripts. Class
IngridUtils is containedwithin the utils module and serves as the base class for
Ingrid . IngridUtils class methods en-capsulate much of the lower-level software details used to implement the methods in the
Ingrid class. Because of this,
IngridUtils is encouraged for use by advanced users and developersof INGRID. In addition to
IngridUtils , class
TopologyUtils can be found within the utils module. In a manner similar to
IngridUtils , the
TopologyUtils class serves as a base classfor each magnetic-topology class within the topologies subpackage.
TopologyUtils containskey methods for generating Patch-Maps, visualizing data, generating grids, and exporting grids ingridue format. Eight magnetic-topology classes are contained within their own modules withinthe topologies subpackage:
SNL , UDN , SF15 , SF45 , SF75 , SF105 , SF135 , and
SF165 . Eachmagnetic-topology class contains configuration specific line-tracing instructions for constructionof Patch-Maps, Patch-Map layout information, and gridue formatting information.
Ingrid and
IngridUtils conduct analysis of MHD equilibrium data in order to decide which magnetic-topology class to instantiate from the topologies subpackage. The
IngridUtils class alwaysmaintains a reference to the instantiated object in order to effectively manage grid-generation.13ll GUI operation is managed by class ingrid_gui within the gui s subpackage. INGRID’sGUI front-end was developed with the tkinter package; a Python interface to the Tk GUI toolkitthat is available within the Python Standard Library. Class ingrid_gui is simply responsible formanaging event handling, and managing an
Ingrid object that is used to drive the GUI with directcalls to the available high-level methods.Beyond modules ingrid and utils , modules geometry , interpol , and line_tracing formthe computation and modeling foundation of INGRID. Classes Bicubic and
EfitData can befound within the interpol module. The
Bicubic class handles biciubic interpolation of data andis composed with classes that directly utilize bicubic interpolation. Class
EfitData is used toprovide an interpolated representation of provided MHD equilibrium data.
EfitData computespartial derivative information of MHD equilibrium data, provides interpolated ψ function valuesby interfacing with class Bicubic , and contains methods for visualisation of interpolated MHDequilibrium data. Module geometry contains classes
Point , Line , Patch , and
Cell . Theseclasses are the building-blocks for creation of Patch-Maps and generation of grids.
C. INGRID geometry object hierarchy
If we are to adopt an object-oriented approach to grid generation, then we must develop a set oftools that can be utilized throughout our project. Here we discuss how INGRID defines a collec-tion of geometric classes in order to make the grid generating process as simple as possible for allmagnetic topologies of interest. To do so, INGRID defines the following collection of geometricabstractions: the Point class, the Line class, the Cell class, and the Patch class. All together, theseclasses arm INGRID with the ability to represent any magnetic topology of interest. We providea very brief description of the classes here. Figure 2 illustrates the geometry collection describedbelow.A Point object simply represents an arbitrary ( r , z ) spatial coordinate. A Line object object isdefined by two or more Point objects. This Line object definition allows for the representation ofany arbitrary curve we may encounter (e.g. psi-surface, target plate, limiter geometry). A Patchobject represents a quadrilateral region of the domain. Patches are defined by four Line objects.This Patch abstraction allows for partitioning of the domain of interest into various regions that wewould like to obtain a grid representation of. A Cell object resides within a Patch and representsa quadrilateral grid cell. Cells are defined by five Point objects: four corners and a center. These14ell objects contain spatial and experimental data that are to be used in simulation code.From these definitions, we have the building blocks for modeling any of the magnetic topolo-gies of interest we mentioned in the previous section. In particular, we aim to construct a collectionof Patch objects representing the divertor configuration of interest. We call this collection of Patchobjects a Patch-Map. This Patch-Map allows us to create a grid of Cell objects within each Patch,thus providing the final grid. The management of the Patch-Map creation and grid generation ismanaged by a magnetic topology class of modeling interest.As of the current INGRID release, we have defined magnetic topology classes SNL, UDN,SF15, SF45, SF75, SF105, SF135, and SF165. These are contained within a dedicated topolo-gies subpackage within the INGRID code. We also introduce a general “Ingrid" class exclusivelymeant for user interfacing and management. The Ingrid class and all magnetic topologies are sup-ported by the backend utility classes IngridUtils and TopologyUtils respectively. We will discussthese classes at a later part of the report. D. INGRID parameter file
INGRID has been designed to be controlled from a single configuration/parameter file whenoperating in GUI mode. We have decided to use YAML formatted files for the parameter file .This YAML file is similar to the familiar Fortran namelist files due to the key-value structure it isbased off of. YAML is in an easy to read format that has extensive support within Python. Withthe PyYAML library, Python reads a YAML formatted file and internally represents it as a Pythondictionary. This allows users to model cases in the INGRID GUI and reuse a parameter file inscripting for later usage (e.g. batch grid generation). Some key controls within the parameter fileinclude: EFIT file specification, specification of number of X-points, approximate coordinates ofX-point(s) of interest, approximate magnetic-axis coordinates, psi level values, and target platesettings (files, transformations). Other controls in the parameter file include: path specificationfor data files, grid cell np/nr values, poloidal and radial grid transformation settings, limiter spe-cific settings, saving/loading of Patch maps, gridue settings, and debug settings. This is not anexhaustive list. Further details can be found in INGRID’s Read The Docs online documentation.15 . INGRID target plate file INGRID users must specify the geometry of the limiter and/or target plates, to represent theshape of material walls in a modeled device. The limiter and target plates are represented inINGRID by a piecewise-linear model defined by a set of nodes; the (r,z) coordinates of thosenodes are expected to be provided in separate data files. There is one data file for the limiter andone for each target plate, either in the text format or as a NumPy binary. The names of those datafiles are set in the INGRID parameter file. In the case that the limiter and target plate data areprovided in text format, the user must specify (r,z) coordinates for each point defining the surfacesequentially on a separate line in the corresponding data file; and Python-formatted single- linecomments can be included, as shown in the Appendix.For use of NumPy binary files, users must also adhere to a particular internal file structure.Given two NumPy arrays of shape ( n , ) that represent r and z coordinate values respectively, onecan define a NumPy array of shape ( , n ) representing the n -many points required to model thepiecewise-linear model of interest. This NumPy array of shape ( , n ) can be saved into a NumPybinary file in order to be loaded into INGRID. In addition to the requirements above, INGRIDasserts that strike-point geometry files used for Patch-Maps are monotonic in psi along the lengthof the target plates (i.e. no shadow regions). This assertion allows for INGRID generated Patch-Maps to conform entirely to a user’s specified strike-point geometry. While operating INGRIDin GUI mode, users will be warned if the loaded geometry file is not monotonic in psi along thetarget plate length. F. INGRID workflow
INGRID can be operated via GUI or utilizing the INGRID library directly in Python scripts.The GUI workflow highlights the interactive nature of INGRID by allowing users to visually in-spect MHD equilibrium data, configure geometry, and refine parameter file values on the fly. Forboth GUI operation and scripting with INGRID, the high-level INGRID workflow is: (i) Parameterfile visualization and editing, (ii) Analysis of MHD equilibrium data and creation of Patch-Map,(iii) Patch-Map refinement and gridue export. INGRID internally handles step (ii) and leaves theuser to with steps (i) and (iii). These steps are where the user is able to customize the Patch-Mapand grid to meet their modeling needs. 16tep (i) in the INGRID workflow allows users to visually inspect MHD equilibrium data, target-plates & limiter geometry, and psi-level contours that are specified within a loaded parameter file.Since creation of grids is tied directly to MHD equilibrium analysis and Patch-Map creation, step(i) is crucial for successful grid generation. To simplify this step, the INGRID GUI provides aneasy to use workspace for preparation of a parameter file for the subsequent analysis of MHDequilibrium data and Patch-Map creation. Examples of common operations at this step includemodifications to strike-point geometry and psi-level boundaries for subsequent Patch-Maps. Oncea user is satisfied with parameter file settings, step (ii) can be immediately executed with no furtheruser intervention. Should any errors in Patch-Map creation occur (e.g. misplaced target-plates, psi-boundaries that do not conform to configuration specific requirements), INGRID will prompt theuser and allow for appropriate edits to be made. Upon completion of step (ii), the created Patch-Map will be provided to users as a new matplotlib figure. From here the user can decide to proceedwith Patch-Map refinement or start over at step (i) to make edits to the Patch-Map.In order to streamline grid generation and skip directly to step (iii), INGRID supports Patch-Map reconstruction. This feature allows users to bypass line-tracing routines by reloading a savedPatch-Map from a previous INGRID session. To do so, INGRID encodes essential geometry andtopology analysis data in a specially formatted dictionary that is then saved as a NumPy binaryfile. Class
IngridUtils handles the encoding and reconstruction of Patch-Maps. These recon-struction features can be configured by the user within the INGRID parameter file.After a Patch-Map has been generated or reconstructed, users can configure grid generationspecific settings that will be utilized during Patch-Map refinement. Similar to Patch-Map gener-ation, once all local subgrids have been created within Patch objects, a new matplotlib figure ispresented with the generated grid. From here, users can make grid generation setting edits in theINGRID parameter file or proceed to exporting a gridue file.
VI. SUMMARY
INGRID is a new grid generator for tokamak boundary region, it is capable of producing gridsfor single-null (SNL), unbalanced double-null (UDN), and snowflake-like (SF) configurations.Currently, exported grids are in the format of the UEDGE code, as detailed in Ref. ( ); futuredevelopment may include addition of grid formats used by other codes if INGRID is adopted inthe broader edge-plasma community, beyond UEDGE. INGRID can be utilized via the INGRID17ython package, or through a parameter file driven GUI mode. The internal equilibrium geometryanalysis algorithm provides the ability to automatically identify the divertor configuration em-bedded within experimental data with minimal user interaction. A divide-and-conquer, geometryclass hierarchy approach to grid generation is at the heart of INGRID and leads to the Patch-Mapabstraction: a partition of the modeling domain that allows for localized grid generation. Theselocalized grids are combined into a global grid that are then ready for export. Current compu-tational scaling of grid generation algorithm follows a sublinear trend independent of magnetic-topology modeled. Benchmarking of INGRID against the internal grid generator in UEDGE isdemonstrated for an SF75 snowflake-like configuration. These tests illustrate INGRID’s ability toproduce practical grids for tokamak edge modeling, for complex magnetic flux function with oneor two X-points in the domain, and for nontrivial target plate geometry. VII. ACKNOWLEDGMENTS
The authors would like to thank M.E.Rensink for his help with grid generation in UEDGE.This work was performed for U.S. Department of Energy by Lawrence Livermore National Lab-oratory under Contract DE-AC52-07NA27344, and General Atomics under Contract DE-FG02-95ER54309.
VIII. APPENDIX: PARAMETER FILE
A snippet of an INGRID parameter file is shown below. In the file, the user is supposed toprovide settings relevant to grid and Patch generation: 1) For the magnetic field geometry, thename (with path) of data file, in the commonly used neqdsk format 2) For radial boundaries, thevalues of normalizes poloidal flux Psi for each of the radial boundary 3) For poloidal boundaries,the code has options to use one of these: a) limiter data embedded in the eqdsk file b) limiter dataprovided in a separate file (the file name and path must be included) c) target plates geometry inseparate files, one per each plate (the file names and paths must be included) 4) How many X-points to include in the domain, 1 or 2 5) Approximate R,Z coordinates for each of the includedX-points and for the magnetic axis, to provide initial guess for the solver 6) Dimensions of sub-grids 7) Options related to grid customization 8) Options related to integrator settings. U s e r d a t a d i r e c t o r i e s −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−− x p t : 1 . 3 0 0 0 9 4 0 3 2 6 8 7z x p t : − 1 . 1 3 3 1 5 9 3 7 5 3 0 2 s e _ e f i t _ b o u n d s : f a l s e Listing 1: Snippet of YAML formatted configuration file. YAML files utilize Python formattedcomments, keyword-value mappings, and nesting of structures via indentation.
REFERENCES M. Kotschenreuther, Physics of Plasmas , 072502 (2007). D. D. Ryutov, Physics of Plasmas , 064502 (2007). D. D. Ryutov, Physics of Plasmas , 092501 (2008). B. LaBombard, Nuclear Fusion , 053020 (2015). T. D. Rognlien, D. D. Ryutov, N. Mattor, and G. D. Porter, Physics of Plasmas , 1851 (1999). S. Wiesen, Journal of Nuclear Materials , 480 (2015). R. Simonini, Journal of Nuclear Materials , 368 (1994). M. V. Umansky, M. S. Day, and T. D. Rognlien, Numerical Heat Transfer, Part B , 533 (2005). R. Marchand and M. Dumberry, “CARRE: a quasi-orthogonal mesh generator for 2d edgeplasma modelling,” Computer Physics Communications , 232 – 246 (1996). A. Taroni, “The multi-fluid codes Edgeid and Edge2D: Models and results,” Contribution toPlasma Physics , 448 (1992). O. Izacard and M. Umansky, “Gingred, a general grid generator for 2d edge plasma modeling,”(2017), arXiv:1705.05717 [physics.plasm-ph].22 D. D. Ryutov, M. A. Makowski, and M. V. Umansky, “Local properties of the magnetic field ina snowflake divertor,” Plasma Physics and Controlled Fusion , 105001 (2010). L. Lao, H. S. John, R. Stambaugh, A. Kellman, and W. Pfeiffer, “Reconstruction of currentprofile parameters and plasma shapes in tokamaks,” Nuclear Fusion , 1611–1622 (1985). W. H. Press, S. A. Teukolsky, W. T. Vetterling, and B. P. Flannery,
Numerical Recipes in C , 2nded. (Cambridge University Press, Cambridge, USA, 1992). O. Meneghini, S. Smith, L. Lao, O. Izacard, Q. Ren, J. Park, J. Candy, Z. Wang, C. Luna,V. Izzo, B. Grierson, P. Snyder, C. Holland, J. Penna, G. Lu, P. Raum, A. McCubbin, D. Orlov,E. Belli, N. Ferraro, R. Prater, T. Osborne, A. Turnbull, and G. Staebler, “Integrated modelingapplications for tokamak experiments with OMFIT,” Nuclear Fusion , 083008 (2015). O. Meneghini and L. Lao, “Integrated modeling of tokamak experiments with omfit,” Plasmaand Fusion Research , 2403009–2403009 (2013). “UEDGE code GitHub repository,” GitHub/LLNL/UEDGE, accessed: 2021-01-18. S. van der Walt, S. C. Colbert, and G. Varoquaux, “The numpy array: A structure for efficientnumerical computation,” Computing in Science Engineering , 22–30 (2011). P. Virtanen, R. Gommers, T. E. Oliphant, M. Haberland, T. Reddy, D. Cournapeau, E. Burovski,P. Peterson, W. Weckesser, J. Bright, S. J. van der Walt, M. Brett, J. Wilson, K. J. Millman,N. Mayorov, A. R. J. Nelson, E. Jones, R. Kern, E. Larson, C. Carey, ˙Ilhan Polat, Y. Feng,E. W. Moore, J. VanderPlas, D. Laxalde, J. Perktold, R. Cimrman, I. Henriksen, E. A. Quin-tero, C. R. Harris, A. M. Archibald, A. H. Ribeiro, F. Pedregosa, P. van Mulbregt, and S. . .Contributors, “Scipy 1.0–fundamental algorithms for scientific computing in python,” (2019),arXiv:1907.10121 [cs.MS]. J. D. Hunter, “Matplotlib: A 2d graphics environment,” Computing in Science Engineering ,90–95 (2007). K. Simonov, “Pyyaml homepage,” https://pyyaml.org/wiki/PyYAML (2006). M. E. Rensink and T. D. Rognlien, “Mapping of orthogonal 2d flux coordinates for two nearbymagnetic x-points to logically rectangular domains,” Tech. Rep. LLNL-TR-731515 (LawrenceLivermore National Laboratory, Livermore, California, 2017).23 (a) (b) (c)
X’2 X’2O O O
Figure 1: Topological possibilities with one and two X-points. As explained in the main text,case (a) is a single-null configuration; case (b) with the secondary X-point in the common-fluxregion has five variations, depending on the location of the projection point X (cid:48) ; case (c) with thesecondary X-point in the private-flux region has two variations depending on the location of theprojection point X (cid:48) . The East-West notation for the two midplane points and the two strike pointsis based on designating the direction from the primary X-point toward the O-point as “North”.This is invariant notation, independent on whether the primary X-point is at the top, at the bottom,or anywhere else. 24 atchCell Figure 2: INGRID Patch-Map; a subgrid is shown on one of the patches distortion_correctionDisabled Enabled
Figure 3: Comparison of SF135 grids generated with and without activation of the distor-tion_correction tool. Highlighted regions illustrate regions of notably improved grid orthogonality.25igure 4: Scaling of grid generation follows a sublinear trend independent of configuration. Gridswere generated with n × n many cells per Patch with n = { , , , . . . , } . With n × n subgriddimensions, SNL configurations contain 12 n many cells, whereas SF75 configurations contain27 n many cells. 26 NGRID UEDGE
Figure 5: INGRID and UEDGE generated grids used for the benchmark calculations.27
EDGE V ⎢⎢ [m/s]Ni[m-3]Te[eV] INGRID
Figure 6: Results of the benchmark calculations run on INGRID and UEDGE generated grids.28 NL Primary Separatrix plate_W1 plate_E1A2 B2 B1 E1E2F2A1 F1C2 C1 D2D1psi_pf_1 psi_corepsi_1 xpt1
NW N NEESESSWW
Figure 7: SNL Patch-Map29 rimary SeparatrixSecondary Separatrix xpt1xpt2 plate_E1plate_W1plate_E2 plate_W2A2A1A3B3 B2 B1 G1G2 G3H3H2H1D2 C2 C1 F1F2 F3D3 D1 E1 E2 E3C3 psi_core psi_pf_1psi_pf_2psi_1 psi_2
UDN
ESESW NENWW S NESE SWNE NWWS N
Figure 8: UDN Patch-Map30
F15
A3 A2A1B3 B2 B1 H1H2H3I1 I2 I3 E1 E2 E3G3 G2 F3F2 F1G1C1 D1C2C3 D2 D3plate_W1 plate_E2plate_E1 plate_W2psi_1 psi_2psi_2psi_pf_1 psi_pf_2psi_core xpt2xpt1
N NE ESESSWWNW NW ESSW SE NENW
Primary SeparatrixSecondary Separatrix
Figure 9: SF15 Patch-Map31
F45
A3 A2A1 F1 F2 F3B3 B2B1 E1 E2 E3 G3I2I1C1C2C3 D1 D2D3 I3 H3 G2G1H1H2psi_1 psi_pf_2psi_2psi_pf_1psi_coreplate_W1 plate_E1 plate_E2plate_W2
NW ESSW SENW NEN SSWE WNE NW
Primary SeparatrixSecondary Separatrix xpt1xpt2
Figure 10: SF45 Patch-Map32
SF75
Primary SeparatrixSecondary Separatrix xpt1xpt2
NSSW SEW ENW NENNW NEW ESW SES psi_core
Figure 11: SF75 Patch-Map33 rimary SeparatrixSecondary Separatrix
A3 A2A1 I1 I3I2 H3 H2H1B3 B2 B1C3 C2C1 F1F2 F3G2 G3 G1D1 E1D2D3 E2 E3plate_W1 plate_W2plate_E2plate_W2 psi_pf_2psi_2 psi_pf_1psi_1 psi_core
NNWW SSW SEENEN ENENWWSW S SE xpt1xpt2
SF105
Figure 12: SF105 Patch-Map34 rimary SeparatrixSecondary Separatrix
SF135
A3 B3 C3B2B1 G1 G3G2F2 F3F1C1C2H3 H2 H1 D2D3 D1 E2E1 E3A1A2I1I2 I3 psi_core plate_W2plate_E2plate_W1 plate_E1psi_pf_1psi_2 psi_1psi_pf_2
N ESESSW NW NEW NESSWSE NWWNE xpt1xpt2
Figure 13: SF135 Patch-Map35 pt2xpt1
Primary SeparatrixSecondary Separatrix
SF165 plate_W2plate_E2 plate_W1 plate_E1psi_pf_2 psi_pf_1 psi_core
A3A1A2I1 I2 I3 B2 B1
H3 H2 H1
G2G3 G1 F1 F2 F3E1 E2 E3C1C2C3 D1 D2 D3B3psi_2
ESESW NENWW S NNESESW NWE WS N psi_1psi_1