Line data Source code
1 0 : \cond NEVER
2 : Distributed under the MIT License.
3 : See LICENSE.txt for details.
4 : \endcond
5 : # Visualisation Connectivity {#visualisation_connectivity}
6 :
7 : \tableofcontents
8 :
9 : This guide is split into two parts. The first part details what is meant by
10 : 'connectivity' and how it is used to visualise SpECTRE simulations in standard
11 : visualisation software such as Paraview. The second part details the
12 : methodology associated with ExtendConnectivity - a post-processing executable
13 : that removes gaps in the default visualisations produced by SpECTRE.
14 :
15 : # What is Connectivity?
16 :
17 : SpECTRE simulations are built on a computational grid composed of individual
18 : gridpoints. The 'connectivity' is a list added in the output simulation files
19 : that instructs visualisation software, namely Paraview, on how to connect these
20 : gridpoints to create lines/surfaces/volumes (depending on the dimension of the
21 : simulation) as needed. Given these instructions, Paraview interpolates the data
22 : over the regions between gridpoints to create line/surface/volume meshes.
23 :
24 : In general, the connectivity list contains gridpoints in a particular sequence
25 : that corresponds to a line/surface/volume mesh in Paraview. These gridpoints are
26 : labelled with integers that are based on the order in which they appear in the
27 : h5 files output by the simulation. As one might expect, this list is structured
28 : differently depending on the dimension of the simulation. The key underlying
29 : difference is the size of the smallest connected region. In 1D, our domain is
30 : composed of lines so the smallest connected region is a line made up by two
31 : points. In 2D, the smallest connected region used by SpECTRE is typically a
32 : quadrilateral made up by four points. In 3D, the smallest connected region used
33 : by SpECTRE is typically a hexahedron made up by eight points. A visual
34 : representation is illusutrated below. (Note: The numbering of points has been
35 : chosen arbitrarily. In reality, this numbering is determined based on the order
36 : of gridpoints in the h5 file(s)).
37 :
38 : \image html ConnectivityStructure.png "Basic connectivity in 1D, 2D, and 3D"
39 :
40 : The figure above shows how connectivity is defined for a region in each
41 : dimension. Fig (a) shows the gridpoint structure for these regions and Fig (c)
42 : shows how the resulting mesh appears. Fig (b) shows how a connectivity list
43 : should be sequenced to create the desired mesh. Then, in 1D, our connectivity
44 : list to create the line in (c) would be [1,2]. Similarly, in 2D, our
45 : connectivity list would be [1,2,4,3] and in 3D, our list would be
46 : [1,2,4,3,5,6,8,7]. (Note that this sequencing is dictated by Paraview's
47 : conventions, not SpECTRE's.)
48 :
49 : The above example illustrates how to connect the smallest connected region in
50 : each dimension. The complete connectivity list, detailing how the entire domain
51 : mesh is to be created, is made by concatenating individual connectivity lists.
52 : Thus, in 1D, Paraview interprets the list [1,2,2,3] in blocks of 2, with the
53 : first block [1,2] representing a line between gridpoints 1 and 2, and the second
54 : block [2,3] representing a line between gridpoints 2 and 3. This works similarly
55 : in the other dimensions.
56 :
57 :
58 : # How does ExtendConnectivity work?
59 :
60 : ExtendConnectivity is a post-processing algorithm that looks to add more
61 : connectivity entries to fill up any gaps in visualisation. These gaps have
62 : multiple sources, the largest of which is the fact that SpECTRE does not add
63 : connectivity between elements (as defined in
64 : \ref domain_concepts "Domain Concepts") by default. This is important in certain
65 : simulations where the endpoints of the elements do not overlap (e.g simulations
66 : using Gauss quadrature), resulting in gaps between elements in visualisations.
67 : ExtendConnectivity looks to fix this problem specifically. **Note:** The
68 : remainder of this guide assumes we are working with simulations whose elements
69 : don't overlap.
70 :
71 : ## Neighbours
72 :
73 : The key idea in understanding how ExtendConnectivity works is understanding
74 : how neighbouring elements are categorised and dealt with. The next sections
75 : explain the categories of 'face neighbour', 'edge neighbour', and 'corner
76 : neighbour' in detail for 1D, 2D, and 3D.
77 :
78 : ### 3D
79 :
80 : We shall start in 3D because the categories are most intuitively defined in
81 : 3D. The image below shows a typical example of SpECTRE connectivity for a 3D
82 : volume element (with h-refinement 1 and p-refinement 2 in each direction),
83 : coloured by their neighbour categorisation.
84 :
85 : \image html DefaultConnectivity3D.png "3D domain with default connectivity"
86 :
87 : In the above image, the grey cube is our reference element that neighbour
88 : elements are defined around. Then, we define any element that, if elements
89 : overlapped, would share a face with our reference element to be a 'face
90 : neighbour'. By this definition, we can see that our blue cubes in the above
91 : image are our face neighbours. The definitions of the other categories are
92 : analogous. We define any element that, if elements overlapped, would
93 : share an edge to be an 'edge neighbour' and any element that would share a
94 : corner to be a 'corner neighbour'. Hence, our red cubes are our edge neighbours
95 : and our green cube is our corner neighbour. In general, for a 3D simulation,
96 : face neighbours share a 2D region, edge neighbours share a 1D region, and corner
97 : neighbours share a 0D region.
98 :
99 : These categories apply to the element as a whole. Then, after the element is
100 : categorised, the gridpoints must be filtered to the particular face, edge, or
101 : corner that will be connected with our reference element. Note that edge and
102 : corner neighbours require gridpoints from multiple neighbours (e.g. edge
103 : neighbours involve connecting four edges - one from the reference element, two
104 : from face neighbours, and one from the edge neighbour). Once the correct
105 : gridpoints are identified, they are connected as described in the previous
106 : section. The neighbour direction in particular determines the ordering of the
107 : gridpoints in this sequence. The image below shows the same domain after the
108 : missing connectivity has been added, coloured by the type of connectivity added.
109 :
110 : \image html ExtendedConnectivity3D.png "3D domain with extended connectivity"
111 :
112 : In this image, the brown cubes are the face neighbour connections, the orange
113 : cubes are the edge neighbour connections, and the yellow cube is the corner
114 : neighbour connection. The entire process is then repeated for the next element.
115 :
116 : This example required only one connectivity entry to be added per neighbour
117 : since each element was made up of just one cube. At larger p-refinements, an
118 : element consists of more cubes and consequently, more connectivity entries are
119 : required. For example, if the domain above had a p-refinement of 3 in each
120 : dimension instead, face connections would require adding four cubes
121 : and edge connections would require two cubes.
122 :
123 : ### 2D
124 :
125 : We can now generalise these definitions to other dimensions. The image below
126 : shows a typical example of SpECTRE connectivity for a 2D volume element (with
127 : h-refinement 1 and p-refinement 2 in each direction), coloured by their
128 : neighbour categorisation in the same colours as above.
129 :
130 : \image html ExtendedConnectivity2D.png "2D domain with extended connectivity"
131 :
132 : Once again, the grey square is our reference element. We now define our
133 : neighbour types to be analogous to the types in 3D but reduced by one dimension.
134 : Then, in a 2D simulation, face neighbours share a 1D regions, edge neighbours
135 : share a 0D region, and corner neighbours do not exist. In the image above, our
136 : face neighbours are once again blue and our edge neighbours are once again red.
137 :
138 : Once the elements are categorised, the relevant gridpoints are once again
139 : filtered and connected according to the 2D structure explained above. In the
140 : image, the face connections are coloured brown and the edge connections are
141 : coloured orange again. The next element is then made the reference element and
142 : the process is repeated to build up the connectivity for the entire domain.
143 :
144 : ### 1D
145 :
146 : We display the concepts in 1D for completeness. The image below shows an example
147 : of SpECTRE connectivity for a 1D volume element (with h-refinement 1 and
148 : p-refinement 2), coloured by their neighbour categorisation in the same colours
149 : as above.
150 :
151 : \image html ExtendedConnectivity1D.png "1D domain with extended connectivity"
152 :
153 : In this image, the grey line is our reference element. In a 1D simulation, we
154 : correspondingly define face neighbours to share a 0D region and both edge and
155 : corner neighbours do not exist. Then, in the image above, our face neighbour
156 : is once again the blue element and the face connection is coloured brown again.
157 :
158 : ### Summary
159 :
160 : * Face Neighbour:<br>
161 : A neighbouring element that shares an overlap region one dimension lower than
162 : the dimension of the simulation.
163 :
164 : * Edge Neighbour:<br>
165 : A neighbouring element that shares an overlap region two dimensions lower than
166 : the dimension of the simulation.
167 :
168 : * Corner Neighbour:<br>
169 : A neighbouring element that shares an overlap region three dimensions lower
170 : than the dimension of the simulation.
171 :
172 :
173 : ## Connecting elements with different p-refinements
174 :
175 : To be added.
|
