Introduction to the GGD structure¶

The purpose of this guide is to provide a better insight on the Generalized Grid Description (GGD) structure found in Data Dictionary [DD_git] and how to utilize it for storing description of grids such as structured and unstructured grids.

Basic principles of tree hierarchy¶

Data Dictionary is a complex hierarchical structure consisting of tree nodes and it is fundamental to know the basics. Each leaf of a tree is set to hold specified data in specified format. There are next building blocks that compose the Data Dictionary:

• a node, the main building block of the data tree, referring to any element of the tree. There are two types of nodes:

  • simple structure node, being a regular single node, and

  • array of structures node (AOS), describing a 1D array of structures under a single node label,

• a leaf, referring to an end-point of a tree,

• a parent, referring to an element one level above a particular node,

• a sibling, referring to an element at the same level as a given node,

• a child, referring to an element one level below a particular node, with navigation through the tree nodes running from start-point nodes through lower-level nodes to the end-point leafs.

Grid basics¶

The grid (or mesh) is an assemblage of multiple connected elements, provided through their geometry information, which as a whole represents a discrete approximation of geometry of a real-life physical object. Grids are required for solving physical or mathematical problems like fluid flow and heat transfer, producing virtual presentations of simulations intended for analysis of simulation results and other computing-related work in connection with the real-life object.

Each grid is constructed by many low-level components of various geometrical types, hereafter referred to as objects, as the same term is used for geometrical types in Data Dictionary.

The main objects forming the grid are:

1. points or nodes,

2. edges or lines,

3. faces or surfaces, also known as two-dimensional cells, and

4. three-dimensional cells or volumes.

A point with given coordinates in a specific coordinate system represents the base-level grid object. Two specific points form an object specified as an edge, and two or more edges form an object specified as a face or a two-dimensional cell. The most commonly used two-dimensional cell shapes are triangles, formed by three edges, and quadrilaterals, formed by four edges as shown in figures below. In three-dimensional space, multiple 2D cells form a 3D cell, of which the most commonly used are tetrahedron (formed using four triangle 2D cells) and hexahedron (formed using six quadrilateral 2D cells).

Grid subsets¶

The grid subset, or subgrid, represents a portion of the contents of a larger full grid, usually intended for a more accurate analysis of an exactly specified piece of the grid. Each grid subset is defined by objects of only one type, that being either points/nodes, lines/edges, or surfaces/two-dimensional cells, etc.

Review of the GGD (sub)structure¶

The GGD structure is present within many Interface Data Structures (IDSs) found in the Data Dictionary (DD) [DD_git].

GGD term is being used to refer to both grid_ggd(:) and ggd(:) Arrays of Structures (AOS). At first, there was only a ggd(ti) AOS which contained both grid description and physical quantities for given timeslice ti. As in many cases, the grid is static e.g. it doesn’t change through time rewriting it for each time slice is unnecessary and space consuming. For those reasons, with the IMAS 3.15.1 release (see [IMAS_releases]), the grid was moved out to a separate AOS, the same tree-hierarchy-level as the ggd AOS, named grid_ggd.

The grid_ggd AOS¶

The grid_ggd AOS holds the grid description for different time slices. In case the grid does not change with time it is enough to fill grid description only for the first “time slice”. Note that the readers (methods, routines, etc.) must be aware of this!

It consists of identifier node, space AOS, grid_subset AOS and time node.

identifier node¶

The identifier node holds information on the grid, see ggd_identifier for the possible values.

• name leaf (STR_0D), holding the name of the grid,

• index leaf (INT_0D), holding the grid index correlating with the time slices (starting with index 1), and

• description leaf (STR_0D), holding the custom description of the grid.

space AOS¶

The space AOS holds information on the various spaces of the grid:

• identifier node, holding basic information for given space,

• geometry_type node, defining type of space geometry,

• coordinates_types leaf (INT_0D), holding coordinates IDs that are being used to define given space. The coordinate IDs can be found in coordinate_identifier or $IMAS_PREFIX/include/cpp/coordinate_identifier.h. For example, ID 1 describes first Cartesian coordinate in the horizontal plane - x[m] , ID 2 describes second cartesian coordinate in the horizontal plane - y[m], etc.

• objects_per_dimension AOS, holding definition of the space objects for every dimension. For example, objects_per_dimension(1) (note: Fortran notation, index starting with 1) holds the description on the 0D objects - points/nodes/vertices; objects_per_dimension(2) holds the description on 1D objects - lines/edges, objects_per_dimension(3) holds the description on 2D objects - surfaces, objects_per_dimension(4) holds information on 3D objects - volumes, etc.

identifier node¶

The identifier node holds information on the space, see ggd_space_identifier for the possible values.

• name leaf (STR_0D), holding the name of the space,

• index leaf (INT_0D), holding the space integer/index identifier (starting with index 1), and

• description leaf (STR_0D), holding the custom description of the space.

geometry_type node¶

The identifier node holds information on the geometry type used in given space description:

• name leaf (STR_0D), holding the name of the geometry type,

• index leaf (INT_0D), holding the geometry type integer/index identifier, 0 for standard geometry, 1 for Fourier geometry, and

• description leaf (STR_0D), holding the custom description of the geometry type.

objects_per_dimension AOS¶

The objects_per_dimension AOS holds definition of all space objects in the domain for each dimension. For example, objects_per_dimension(1) (note: Fortran notation, index starting with 1) holds the description on the 0D objects - points/nodes/vertices; objects_per_dimension(2) holds the description on 1D objects - lines/edges, objects_per_dimension(3) holds the description on 2D objects - surfaces, objects_per_dimension(4) holds information on 3D objects - volumes, etc.

Its child is object AOS. For n objects (for example, points) there are n object structures. Each object structure holds:

• boundary AOS, describing a set of n-1 dimensional objects defining the boundary of given n-dimensional object. For example, for 2D object - surface, the boundary would be defined by 1D objects - edges/lines.

• geometry leaf (FLT_1D), describing geometry of the object through coordinates. This usually refers only to 0D objects, higher dimensional objects have this leaf empty. This is an array, and its size depends on the space coordinates_type leaf. For example, in a case of one point with X and Y coordinates the coordinates_type leaf would hold coordinate IDs 1 and 2 while objects_per_dimension(1).object(1).geometry would hold an 1D array containing two float numbers defining the “value” of the X and Y coordinates.

• nodes leaf (INT_0D), describing which 0D objects form this element. For example, in a case of a 2D object - surface that is constructed by nodes 1, 2, 3, and 4, the nodes leaf would hold integers (object IDs) 1, 2, 3, and 4, referring to objects_per_dimension(1).object(1), object(2), object(3) and object(4), where object IDs are indices to navigate to object(i) node.

• measure leaf (FLT_0D), describing the measure of the given object. For example, for 1D object - line/edge -> length value, for 2D object - surface -> surface area and 3D object - volume -> volume.

The child AOS of the object AOS is boundary AOS, describing a set of \({n-1}\) dimensional objects defining the boundary of given n-dimensional object which can additionally characterize the grid. Boundary represents a list of \({n-1}\) dimensional components defining the n dimensional object or bounds of the \({n}\) dimensional object inside the grid. For example, the boundary of an edge object would be two points/nodes, while the boundary of a 2D quadrilateral cell object would be four edges. The boundary AOS children are:

• index leaf (INT_0D), defining index of given n-1 dimensional object,

• neighbours leaf (INT_1D), defining neighbours of given n-1 dimensional boundary object.

grid_subset AOS¶

The grid_subset AOS holds information on the various grid subsets of the grid. The grid subset, or subgrid, represents a portion of the contents of a larger full grid, usually intended for more accurate analysis of an exactly specified piece of the grid, for example, inner divertor region, outer divertor region etc.

Each grid subset is defined by objects of only one type, that being either points or nodes, edges, surfaces, etc.

List of confirmed grid subset labels and their belonging IDs can be found in ggd_subset_identifier or $IMAS_PREFIX/include/cpp/ggd_subset_identifier.h.

The grid_subset AOS children are:

• identifier node, holding basic information on the grid subset,

• dimension leaf (INT_0D), defining dimension of the grid subset elements,

• element AOS, defining a set of elements defined by combination of objects from potentially all spaces,

• base AOS, defining set of bases for the grid subset, and

• metric node, defining metric of the canonical frame onto Cartesian coordinates.

identifier node¶

The identifier node holds information on the grid subset, see ggd_subset_identifier for the possible values.

• name leaf (STR_0D), holding the name/label of the grid subset,

• index leaf (INT_0D), holding the integer/index identifier (starting with index 1), and

• description leaf (STR_0D), holding the custom description of the grid subset.

element AOS¶

The element AOS is designed to contain data on each element of the same dimension, forming the grid subset. Each element can be formed by one or more objects and the data on the objects forming the element is stored in its child named object AOS. The relation between grid, grid subset, element, and object is shown in figure below.

The children of the object AOS are:

• space leaf (INT_0D), representing index of the space from which that object is taken,

• dimension leaf (INT_0D), referring to the dimension of the object, and

• index leaf (INT_0D), defining the object index.

The space, dimension and index integers represent a navigation indicies to navigate through grid_ggd(:).space AOS -> grid_ggd(:).space(space_index).objects_per_dimension(dimension_index) .object(object_index). This way we can get our object defining the element that composes grid subset.

For example, in a case we have a grid subset composed by one 2D surface, this 2D surface would represent our element. 2D surface is then composed by either 4 points or 4 edges - objects.

For direct examples and better insight on the relation between grid subsets, elements, and objects check the Examples.

base AOS and metric node¶

The base AOS contains a set of bases for the grid subset. For each base, the structure describes the projection of the base vectors on the canonical frame of the grid.

The metric node contains the metric of the canonical frame onto Cartsian coordinates.

Both have children with the same labels and characteristics:

• jacobian node (FLT_1D)

• tensor_covariant node (FLT_3D)

• tensor_contravariant node (FLT_3D)

The ggd AOS¶

The ggd AOS holds the plasma quantities represented using the Generalized Grid Description for various time slices. The quantities correspond directly to one of the grid subsets (e.g. 100 values corresponding to grid subset composed by 100 points). ggd AOS contents differ between IDSs and usually it contains many child nodes/AOSs however the same rules apply to all.

The most common ggd child nodes/AOS are the electrons node and ions AOS. There can be many different ion species and each ion specie refers to one structure of the ions AOS (...ion(ion_specie_index)).

In continuation of this guide only the electrons node will be presented as for other siblings the same rules apply.

electrons node¶

The electrons node holds plasma quantities related to electrons, as implied in the label of the node. It contains many child AOSs, as seen in the figure below. For all of those AOSs the same rules apply (for so called generic grid scalar node type). In this guide the electron temperature - temperature AOS will be looked into.

temperature AOS¶

The temperature node holds plasma quantities related to (electron) temperature. Its children are:

• grid_index leaf (INT_0D), holding index of the grid used to represent this quantity,

• grid_subset_index leaf (INT_0D), holding index of the grid subset the data is provided on (Each structure of temperature AOS corresponds to one of the grid subsets),

• values leaf (FLT_1D) holding values corresponding to the grid subset (one value per element in the grid subset), and

• coefficients leaf (FLT_2D) holding interpolation coefficients, to be used for a high precision evaluation of the physical quantity with finite elements, provided per element in the grid subset (first dimension).

grid_index and grid_subset_index indices are used to navigate through ...grid_ggd(grid index).grid_subset(grid_subset_index) and locate the corresponding grid subset definition. The values holds \({n}\) values which correspond to ...grid_ggd(grid index).grid_subset(grid_subset_index).element(1...n) elements.