Tokamak Modeling and Meshing Software (TOMMS) User's Guide
- Triangular 2D mesh of a poloidal plane with field-following vertices for the user-defined region of Tokamak
- Flux surface curves with one element deep mesh (i.e. one element between two adjacent flux surfaces)
- Unstructured meshes for undefined part of scrape-off-layer regions
- Transition of meshes from one-element large aspect ratio elements to unstructured meshes with reasonable aspect ratio elements.
- The code supports a wide range of critical point configurations.
- The authorized users can find the updated installation guidelines for TOMMS in the following link. We will get an executable tomms_meshgen from the installation procedure.
- The link contains information about the installation of TOMMS on both the PPPL (RHEL 6) and SCOREC (RHEL6 and RHEL7) machines. The installation page is updated regularly.
- The sample inputs for the TOMMS can be found from Fusion_Public repo using the link below. The repository is updated regularly and now contains over 50 test cases.
- A number of different configurations for the following tokamaks are available:
- D3D
- ITER
- NSTX
- JET
- KSTAR
- Alcator C-Mod
- WEST
- Concentric Circular (No X-Point mock case)
- Double null mock case
- The detailed description of every input parameter can be found in the link below.
- The mesh can be generated by using two methods.
- Running the executable at the terminal
- Simmodeler Fusion Tab
-
Get the sample test cases from the link provided above.
-
Open a sample test case. For Example, D-g096333.03337 in this case.
- cd /Fusion_Public/samples/D-g096333.03337
-
The directory should contain a minimum of two input files.
- xgc_mesh_in: File containing the input parameters for geometry and meshing.
- geqdsk/eqd file: Equilibrium file for tokamaks.
- Additional files can be used for better control of geometry definition and will be specified in the xgc_mesh_in.
-
Load the latest gcc, mpich, and parmetis modules.
-
Provide the path of your executable and run it. In my case, the path is
- /lore/riazu/Fusion/install/bin/tomms_meshgen
-
The final model and resulting mesh are saved into the working directory. The extension of the model is
.smd, and for mesh, it is.sms. The mesh files are also saved invtkformat for visualization in Paraview. Furthermore, the mesh information is provided in different files for use in XGC. The descriptions of these files can be found on the following page: -
The results obtained were from default settings. To change any parameters, simply open the xgc_mesh_in file and edit it. For Example, the default inter_curve_spacing was 0.04. Just replace this 0.04 with the new value to modify the inter-curve spacing of the mesh.
-
Rerun the executable tomms_meshgen to get a modified mesh.
-
A sample xgc_mesh_in is provided below.
adv_log 1 !Input EFIT file containing psi grid and wall boundary. eqdskFile g096333.03337 !If set to 1, this reverses the sign of Psi, allowing for a maximum at the axis reverse_psi 0 !License file for Simmetrix software SimLic /net/common/meshSim/license/license.txt !SimLic /usr/pppl/Simmetrix/license.txt !This is the desired spacing between psi curves inter_curve_spacing 0.04 inter_curve_spacing_min 0.02 inter_curve_spacing_max 0.05 inter_curve_spacing_axis_forcing 0.05 !This is the desired spacing between points on a psi curve, in meters intra_curve_spacing 0.03 !Choose a way of uniformity in radial direction (1: psi, 2: sqrt(psi)) radial_uniform_meshing_unit 1 !not aligned but random starting positions in curve generation (default=true, bool or logical) random_start 1 !Curve with psi value larger than it will be dropped drop_open_psi 0.08 inter_curve_spacing_sol 0.025 ! used if xpt_location = 0 (no x point is used) last_closed_psi 0.53 !Defines the mesh size at the boundary wall. 0.16 meter meshSizeWall 16.0 !Define the mesh size gradient in unstructured area meshSizeGradXpt 0.3 !the order of limiter nodes. 0: clock-wise; 1 counter bdyNodeOrder 0 !factor to rescale psi eqd_psi_factor 1.3 !Number of 2D planes around the torus, used in spacing points on a curve. num_phi_planes 128 !Tolerance for the gradient of psi !Effects how exactly the critical points (mins, x-point) are found tolerance_psi_deriv 1E-10 !Tolerance for psi !All points on a psi surface are guaranteed to be within this range of the target psi value. tolerance_psi 1E-8 !Tolerance in meters !Used in checking if a point is on the boundary, or if it is a duplicate of another point. tolerance_meters 5E-10 !This value is used to prevent the same critical point from being detected twice. !If two of the same type of critical point are within this distance, one will be ignored. min_critical_spacing 0.25 !The inverse of this value gives the number of steps used to search in parametric space on the outer grid boundary. step_normalized 0.0125 !This is the change in phi of each rk4 step taken when moving a point along a psi curve. step_radians 0.00125 !This is a maximum step size added to Newton's method to deal with extremely small derivatives near critical points. max_step_meters 0.0025 !If possible, point spacing on a curve will fall within this fraction of the desired value. spacing_tolerance_optimal 0.5 !Point spacing on a curve will always be within this fraction of the desired value. !The acceptable range is calculated as 1/(1+tol) to (1+tol) so a value of 1.0 gives a range of .5 to 2.0 times the desired spacing. spacing_tolerance_absolute 0.61803398874989484820 !If the dot product between a curve's direction and the wal direction is greater than !this value, the curve may be cut off as it approaches too close to the edge. !The default value (0.996) corresponds to an approach angle of 5 degrees. parallel_cutoff 0.999975 !The output node and element files !nodeFile xgc.node !elmFile xgc.ele
-
This section will cover the steps for the generation of the mesh using the Simmodeler Fusion Tab. Follow the procedure provided below for the generation of the mesh in Simmodler Fusion Tab.
-
Open Simmodeler by loading the latest modules available. To open the Simmodeler using the terminal, follow the steps given below.
- >> module load simmetrix/simModeler/8.0-190222
- >> module load simmetrix-simmodsuite/14.0-190402dev
- >> simmodeler
-
Check the modules available before loading to make sure that you are using the latest versions.
- To open Simmodeler Fusion Tab, click on the Fusion tab on the menu bar.
- In the Fusion tab, click on the XGC to open the input/output parameters interface.
- Select the XGC mesh generation executable.
- After selecting XGC executable, the user needs to provide a
eqdskfile. - The eqdsk file can be found in the sample test case directories. For example, for the test case D-g096333.03337, the eqdsk below can be found using the link below.
- /Fusion_Public/samples/D-g096333.03337
- After both the inputs have been provided, move to the Meshing parameters by using the drop-down menu to modify any meshing parameter.
- Click on “Apply” at the bottom right corner to use the default values to generate a mesh.
- The steps to generate the mesh and default mesh can be found in the figures below.
.png)
- The final model and resulted mesh are saved into the working directory. The extension of the model is
.smdand for mesh, it is.sms. The user can access to these models and meshes anytime to make any desired changes.
- A 2D model of Tokamak along its details are presented in the figure below. In the figure, the components labeled from 0 to 6 are physics components and components labeled from 7 to 12 are physical components of the geometry.
- Geometric components of the fusion reactor. The model components include the (0) magnetic axis, (1) open magnetic flux curves, (2) closed magnetic flux curves, (3) separatrices, (4) scrape-off layer, (5) plasma core, (6) X-points, (7) vacuum vessel, (8) wall area, (9) plasma area, (10) vacuum boundary, (11) outer wall boundary, (12) Inner wall boundary [Reference 1]
- The components from 0 to 6 in the figure are the physics components that need to be defined for the meshing requirements. The component 0 shows the magnetic axis of the toroidal magnetic field of the tokamak. The components 1 and 2 are open and closed magnetic flux respectively. The magnetic flux curves in the scrape-off layer (4 in the figure) ends at diverters/limiters and are not closed at the limiter ends as can be seen in the figure. However, the magnetic flux curves inside of the separatrix (3 in the figure) are closed-ended. These magnetic flux lines between the separatrix and magnetic axis form non-intersecting loops. The component 3 in the figure is called separatrix and it divides the 2d face between two components, scrape-off layer and plasma core (5 in the figure). The scrape-off layer is the area between the separatrix and the inner wall boundary (12 in the figure). The magnetic flux curves touch the wall boundary in this scrape-off area. The component 5 is the plasma core. This is the area inside between the separatrix and the magnetic axis. The component 6 is the X-point which is a diverging point for the magnetic flux curve on the separatrix. The magnetic flux curves in the scrape-off area intersect with the wall boundary in a region close to this X-point.
-
The components from 7 to 12 in the figure are the physical components of the tokamak geometry. The component 7 in the figure is vacuum vessel. It is the main vessel that contains the wall boundary and a vacuum is maintained in it. The component 9, 11 and 12 in the figure are wall area, outer wall boundary and inner wall boundary respectively. The component 9 is the plasma area which consists of both the plasma core and the plasma in the scrape-off layer. The plasma area exists in the area inside of the wall boundary. The component 10 is the vacuum boundary and is the outermost part of the Tokamak.
-
The details can be found in the Reference 1.
XGC requires three input files to set up its triangular solver mesh:
- A file containing the cylindrical coordinates
RandZof the mesh vertices (the "node" file) - A file containing the triangle connectivity of the vertices (the "ele" file)
- A file containing the flux-surface connectivity of the vertices (the "flx" file)
The following paragraph describes the file format of those files.
The "node" file starts with a header line that contains the number of vertices of the mesh. Each of the following lines contains the R and Z coordinates of the mesh vertices, e.g.:
181162 2 0 1
1 1.218645 -1.363000 0
2 1.216197 -1.363000 0
3 1.220985 -1.363000 0
4 1.218374 -1.360182 0
5 1.220244 -1.360709 0
[...]
The three numbers following the number of vertices in the first line are there for historical reasons and can be removed in future releases (has to be coordinated with a modification in XGC).
The vertex data is arranged in four columns.
The first column is the vertex index.
The second and third column are the R and Z coordinates, and the last column indicates whether the vertex is on the wall curve (1) or not (0).
Fig. 1: Example of an XGC mesh. There are four distinct regions, i) the closed flux-surface region (core), ii) the scrape-off layer (SOL), iii) the private flux region, and iv) the unstructured mesh region (outside the blue surface). The separatrix, which includes the X-point and separates core, SOL and private region, is shown in red. There are cases with two X-points and two separatrices within the wall curve. In those cases, there is also a second private region.
The "ele" file contains the triangle connectivity of the mesh. The first line in the file lists the number of triangles (and some other numbers that are there for historical reasons but are essentially obsolete). Each of the following lines lists the triangle index and the indices of the three vertices of the triangle, e.g.:
361725 3 0
1 2 1 4
2 5 1 3
3 1 5 4
4 2 7 6
5 2 8 7
6 8 2 4
7 10 3 9
[...]
Most vertices in XGC meshes are not really unstructured, but are aligned on a set of surfaces of constant poloidal magnetic flux (flux-surfaces or flux-curves). The minority of vertices is really unstructured. In this sense, XGC meshes are divided into two regions, the field-aligned and unstructured regions. The two regions are separated by the blue flux-surface in Fig. 1. Around the X-point and where flux-surfaces intersect with the wall curve, additional vertices that are not field-aligned have to be added to generate high-quality meshes. Those vertices are called "non-aligned vertices" in the remainder of this section. Fig. 2 shoes an example of those non-aligned vertices.
Fig. 2: Nonaligned vertices are shown in red, field-aligned vertices and unstructured vertices are shown in black. The non-aligned vertices are all in the region that is otherwise filled with field-aligned mesh (inside the blue surface in Fig. 1).
Simply speaking, flux-surface averages <A> in XGC are computed by calculating the mean of A over the vertices on the same flux-surface.
In many situations, it is necessary to know the value of <A> on each vertex of the mesh.
This value is readily obtained for all field-aligned vertices.
The value of <A> on the non-aligned vertices, on the other hand, is obtained through interpolation from the field-aligned vertices.
In XGC, linear interpolation is used, which requires knowledge of the two flux-surfaces between which each non-aligned vertex lies.
Fig. 3 shows an example.
Two adjacent flux surfaces are shown in orange, and the non-aligned vertices between them are shown in red.
The "flx" file contains lists of vertices that are on the same flux-surface, the two flux-surfaces associated with each of the non-aligned vertices, and some other information about the mesh structure.
1
1920 -1
93 23 16 0
94 -1
1 11 21 29
69137
70218 70221 70222 70223 [...]
72375 72376 72377 72378 [...]
75593 75597 75598 75599 [...]
[...]
-1
3893
11131
106 107
10822
106 107
10825
106 107
10532
-1
The first line is the number of separatrices/X-points in the mesh (currently a maximum of two is supported.
The second line contains the indices of the X-point vertices.
The third line is the number of flux-surfaces in the core, the SOL, the lower private region and the upper private region (if it exists).
The fourth line contains the indices of the separatrix flux-surfaces.
The fifth line contains the number of vertices on each flux-surface.
The following lines until the first line with -1 are lists of indices of vertices. The length of each line is given by the numbers in line 5.
The line after the first -1 is the number of non-aligned vertices.
Finally, the following lines until the second -1 give the index of each non-aligned vertex and the indices of the two associated flux-surfaces.
- Simmetrix Native Model (.smd)
- Simmetrix Mesh (.sms)
- PUMI Model (.dmg)
- PUMI Mesh (.smb)
- XGC Mesh Files
- VTK Files for visualization in Paraview
- Simmetrix mesh with original mesh entity numbering (sim-mesh.vtk)
- Re-ordered (XGC ordering) mesh with a set of XGC information, including curve types and physics regions (pumi-mesh.vtk)
- [1] F. Zhang et al., “Mesh generation for confined fusion plasma simulation,” Eng. Comput., vol. 32, no. 2, pp. 285–293, Apr. 2016.
- [2] Riaz, Usman and Seol, E. Seegyoung and Hager, Robert and Shephard, Mark S., Modeling and Meshing for Tokamak Edge Plasma Simulations. Available at SSRN: https://ssrn.com/abstract=4471686 or http://dx.doi.org/10.2139/ssrn.4471686