libMesh
Loading...
Searching...
No Matches
elem_quality.C
Go to the documentation of this file.
1// The libMesh Finite Element Library.
2// Copyright (C) 2002-2026 Benjamin S. Kirk, John W. Peterson, Roy H. Stogner
3
4// This library is free software; you can redistribute it and/or
5// modify it under the terms of the GNU Lesser General Public
6// License as published by the Free Software Foundation; either
7// version 2.1 of the License, or (at your option) any later version.
8
9// This library is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12// Lesser General Public License for more details.
13
14// You should have received a copy of the GNU Lesser General Public
15// License along with this library; if not, write to the Free Software
16// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17
18// C++ includes
19#include <iostream>
20#include <sstream>
21
22// Local includes
23#include "libmesh/libmesh_common.h"
24#include "libmesh/elem_quality.h"
25#include "libmesh/enum_elem_type.h"
26#include "libmesh/enum_elem_quality.h"
27
28
29namespace libMesh
30{
31
32// ------------------------------------------------------------
33// Quality function definitions
34
42std::string Quality::name (const ElemQuality q)
43{
44 std::string its_name;
45
46 switch (q)
47 {
48
50 its_name = "Edge Length Ratio";
51 break;
52
53 case ASPECT_RATIO:
54 its_name = "Aspect Ratio";
55 break;
56
57 case SKEW:
58 its_name = "Skew";
59 break;
60
61 case SKEW_ANGLE:
62 its_name = "Skew Angle";
63 break;
64
65 case SHEAR:
66 its_name = "Shear";
67 break;
68
69 case SHAPE:
70 its_name = "Shape";
71 break;
72
73 case MAX_ANGLE:
74 its_name = "Maximum Angle";
75 break;
76
77 case MIN_ANGLE:
78 its_name = "Minimum Angle";
79 break;
80
82 its_name = "Maximum Dihedral Angle";
83 break;
84
86 its_name = "Minimum Dihedral Angle";
87 break;
88
89 case CONDITION:
90 its_name = "Condition Number";
91 break;
92
93 case DISTORTION:
94 its_name = "Distortion";
95 break;
96
97 case TAPER:
98 its_name = "Taper";
99 break;
100
101 case WARP:
102 its_name = "Warp";
103 break;
104
105 case STRETCH:
106 its_name = "Stretch";
107 break;
108
109 case DIAGONAL:
110 its_name = "Diagonal";
111 break;
112
114 its_name = "AR Beta";
115 break;
116
118 its_name = "AR Gamma";
119 break;
120
121 case SIZE:
122 its_name = "Size";
123 break;
124
125 case JACOBIAN:
126 its_name = "Jacobian";
127 break;
128
129 case SCALED_JACOBIAN:
130 its_name = "Scaled Jacobian";
131 break;
132
133 default:
134 its_name = "Unknown";
135 break;
136 }
137
138 return its_name;
139}
140
141
142
143
144
150std::string Quality::describe (const ElemQuality q)
151{
152
153 std::ostringstream desc;
154
155 switch (q)
156 {
157
159 case ASPECT_RATIO:
160 desc << "Max edge length ratio\n"
161 << "at element center.\n"
162 << '\n'
163 << "Suggested ranges:\n"
164 << "Hexes: (1 -> 4)\n"
165 << "Quads: (1 -> 4)";
166 break;
167
168 case SKEW:
169 desc << "Knupp's algebraic skew metric,\n"
170 << "based on the nodal Jacobian\n"
171 << "skew matrices. 1 is ideal,\n"
172 << "smaller values are worse.\n"
173 << '\n'
174 << "Suggested ranges:\n"
175 << "Hexes: (0.3 -> 1)\n"
176 << "Quads: (0.3 -> 1)";
177 break;
178
179 case SKEW_ANGLE:
180 desc << "Maximum |cos A|, where A\n"
181 << "is the angle between edges\n"
182 << "at element center.\n"
183 << "NOTE: some degenerate elements\n"
184 << "score 0 if zero-length along principal axis.\n"
185 << "Suggested ranges:\n"
186 << "Hexes: (0 -> 0.5)\n"
187 << "Quads: (0 -> 0.5)";
188 break;
189
190 case SHEAR:
191 desc << "LIBMESH_DIM / K(Js)\n"
192 << '\n'
193 << "LIBMESH_DIM = element dimension.\n"
194 << "K(Js) = Condition number of \n"
195 << " Jacobian skew matrix.\n"
196 << '\n'
197 << "Suggested ranges:\n"
198 << "Hexes(LIBMESH_DIM=3): (0.3 -> 1)\n"
199 << "Quads(LIBMESH_DIM=2): (0.3 -> 1)";
200 break;
201
202 case SHAPE:
203 desc << "LIBMESH_DIM / K(Jw)\n"
204 << '\n'
205 << "LIBMESH_DIM = element dimension.\n"
206 << "K(Jw) = Condition number of \n"
207 << " weighted Jacobian\n"
208 << " matrix.\n"
209 << '\n'
210 << "Suggested ranges:\n"
211 << "Hexes(LIBMESH_DIM=3): (0.3 -> 1)\n"
212 << "Tets(LIBMESH_DIM=3): (0.2 -> 1)\n"
213 << "Quads(LIBMESH_DIM=2): (0.3 -> 1).";
214 break;
215
216 case MAX_ANGLE:
217 desc << "Largest angle between all adjacent pairs of edges (in 2D, sides).\n"
218 << '\n'
219 << "Suggested ranges:\n"
220 << "Quads: (90 -> 135)\n"
221 << "Triangles: (60 -> 90)";
222 break;
223
224 case MIN_ANGLE:
225 desc << "Smallest angle between all adjacent pairs of edges (in 2D, sides).\n"
226 << '\n'
227 << "Suggested ranges:\n"
228 << "Quads: (45 -> 90)\n"
229 << "Triangles: (30 -> 60)";
230 break;
231
233 desc << "Largest angle between all adjacent pairs of sides (in 2D, equivalent to MAX_ANGLE).\n"
234 << "In 3D, this is the largest unoriented angle between adjacent side planes, in the range [0, 90].\n"
235 << '\n'
236 << "Suggested ranges:\n"
237 << "Quads: (90 -> 135)\n"
238 << "Triangles: (60 -> 90)\n"
239 << "C0Polyhedra: (60 -> 90)";
240 break;
241
243 desc << "Smallest angle between all adjacent pairs of sides (in 2D, equivalent to MIN_ANGLE).\n"
244 << "In 3D, this is the smallest unoriented angle between adjacent side planes, in the range [0, 90].\n"
245 << '\n'
246 << "Suggested ranges:\n"
247 << "Quads: (45 -> 90)\n"
248 << "Triangles: (30 -> 60)\n"
249 << "C0Polyhedra: (30 -> 90)";
250 break;
251
252 case CONDITION:
253 desc << "Maximum condition number of\n"
254 << "the Jacobian matrix at each\n"
255 << "corner, relative to an ideal\n"
256 << "(regular) element. 1 is ideal,\n"
257 << "larger values are worse.\n"
258 << '\n'
259 << "Suggested ranges:\n"
260 << "Quads: (1 -> 4)\n"
261 << "Hexes: (1 -> 8)\n"
262 << "Tris: (1 -> 1.3)\n"
263 << "Tets: (1 -> 3)";
264 break;
265
266 case DISTORTION:
267 desc << "min |J| * A / <A>\n"
268 << '\n'
269 << "|J| = norm of Jacobian matrix\n"
270 << " A = actual area\n"
271 << "<A> = reference area\n"
272 << '\n'
273 << "Suggested ranges:\n"
274 << "Quads: (0.6 -> 1), <A>=4\n"
275 << "Hexes: (0.6 -> 1), <A>=8\n"
276 << "Tris: (0.6 -> 1), <A>=1/2\n"
277 << "Tets: (0.6 -> 1), <A>=1/6";
278 break;
279
280 case TAPER:
281 desc << "Maximum ratio of lengths\n"
282 << "derived from opposite edges.\n"
283 << '\n'
284 << "Suggested ranges:\n"
285 << "Quads: (0.7 -> 1)\n"
286 << "Hexes: (0.4 -> 1)";
287 break;
288
289 case WARP:
290 desc << "cos D\n"
291 << '\n'
292 << "D = minimum dihedral angle\n"
293 << " formed by diagonals.\n"
294 << '\n'
295 << "Suggested ranges:\n"
296 << "Quads: (0.9 -> 1)";
297 break;
298
299 case STRETCH:
300 desc << "Sqrt(3) * L_min / L_max\n"
301 << '\n'
302 << "L_min = minimum edge length.\n"
303 << "L_max = maximum edge length.\n"
304 << '\n'
305 << "Suggested ranges:\n"
306 << "Quads: (0.25 -> 1)\n"
307 << "Hexes: (0.25 -> 1)";
308 break;
309
310 case DIAGONAL:
311 desc << "D_min / D_max\n"
312 << '\n'
313 << "D_min = minimum diagonal.\n"
314 << "D_max = maximum diagonal.\n"
315 << '\n'
316 << "Suggested ranges:\n"
317 << "Hexes: (0.65 -> 1)";
318 break;
319
321 desc << "CR / (3 * IR)\n"
322 << '\n'
323 << "CR = circumsphere radius\n"
324 << "IR = inscribed sphere radius\n"
325 << '\n'
326 << "Suggested ranges:\n"
327 << "Tets: (1 -> 3)";
328 break;
329
331 desc << "S^(3/2) / 8.479670 * V\n"
332 << '\n'
333 << "S = sum(si*si/6)\n"
334 << "si = edge length\n"
335 << "V = volume\n"
336 << '\n'
337 << "Suggested ranges:\n"
338 << "Tets: (1 -> 3)";
339 break;
340
341 case SIZE:
342 desc << "Relative size: min(J, 1/J),\n"
343 << "where J is the determinant of\n"
344 << "the nodal Jacobian relative to\n"
345 << "an ideal element of the same\n"
346 << "volume. 1 for a uniform\n"
347 << "(affine) element.\n"
348 << '\n'
349 << "Suggested ranges:\n"
350 << "Quads: (0.3 -> 1)\n"
351 << "Hexes: (0.5 -> 1)\n"
352 << "Tris: (0.25 -> 1)\n"
353 << "Tets: (0.2 -> 1)";
354 break;
355
356 case JACOBIAN:
357 case SCALED_JACOBIAN:
358 desc << "Minimum nodal Jacobian.\n"
359 << "The nodal Jacobians are computed by taking the cross product (2D) or scalar product (3D) of the adjacent edges that meet at that node.\n"
360 << "In the SCALED_JACOBIAN case, we also then divide by the lengths of each of the associated edges.\n"
361 << "For Pyramid elements where four edges meet at the apex node, special handling is required.\n"
362 << '\n'
363 << "Suggested acceptable ranges (from Cubit documentation) for SCALED_JACOBIAN metric:\n"
364 << "Quads/Hexes: (0.5 -> 1)\n"
365 << "Tris/Tets: (0.2 -> 1.0)";
366 break;
367
368 default:
369 desc << "Unknown";
370 break;
371 }
372
373 return desc.str();
374}
375
376
377std::vector<ElemQuality> Quality::valid(const ElemType t)
378{
379 std::vector<ElemQuality> v;
380
381 switch (t)
382 {
383 case NODEELEM:
384 case EDGE2:
385 case EDGE3:
386 case EDGE4:
387 {
388 // None yet
389 break;
390 }
391
392 case TRI3:
393 case TRISHELL3:
394 case TRI6:
395 case TRI7:
396 {
397 v = {
398 CONDITION,
401 JACOBIAN,
403 MAX_ANGLE,
404 MIN_ANGLE,
407 SHAPE,
408 SIZE
409 };
410
411 break;
412 }
413
414 case QUAD4:
415 case QUADSHELL4:
416 case QUAD8:
417 case QUADSHELL8:
418 case QUAD9:
419 case QUADSHELL9:
420 {
421 v = {
423 CONDITION,
426 JACOBIAN,
428 MAX_ANGLE,
429 MIN_ANGLE,
432 SHAPE,
433 SHEAR,
434 SIZE,
435 SKEW,
437 STRETCH,
438 TAPER,
439 WARP
440 };
441
442 break;
443 }
444
445 case TET4:
446 case TET10:
447 case TET14:
448 {
449 v = {
452 CONDITION,
454 JACOBIAN,
456 MAX_ANGLE,
457 MIN_ANGLE,
460 SHAPE,
461 SIZE
462 };
463
464 break;
465 }
466
467 case HEX8:
468 case HEX20:
469 case HEX27:
470 {
471 v = {
473 CONDITION,
474 DIAGONAL,
476 JACOBIAN,
478 MAX_ANGLE,
479 MIN_ANGLE,
482 SHAPE,
483 SHEAR,
484 SIZE,
485 SKEW,
487 STRETCH,
488 TAPER
489 };
490
491 break;
492 }
493
494 case PRISM6:
495 case PRISM15:
496 case PRISM18:
497 case PRISM20:
498 case PRISM21:
499 {
500 v = {
502 MAX_ANGLE,
503 MIN_ANGLE,
506 };
507
508 break;
509 }
510
511 case PYRAMID5:
512 case PYRAMID13:
513 case PYRAMID14:
514 case PYRAMID18:
515 {
516 v = {
518 MAX_ANGLE,
519 MIN_ANGLE,
522 };
523
524 break;
525 }
526
527 case C0POLYGON:
528 {
529 v = {
531 JACOBIAN,
533 MAX_ANGLE,
535 };
536
537 break;
538 }
539
540 case C0POLYHEDRON:
541 {
542 // The generic Jacobian metrics only inspect vertices with
543 // exactly three adjacent edges, but arbitrary polyhedra may
544 // have vertices of higher valence.
545 v = {
547 MAX_ANGLE,
548 MIN_ANGLE,
551 };
552
553 break;
554 }
555
556#ifdef LIBMESH_ENABLE_INFINITE_ELEMENTS
557
558 case INFEDGE2:
559 {
560 // None yet
561 break;
562 }
563
564 case INFQUAD4:
565 case INFQUAD6:
566 case INFHEX8:
567 case INFHEX16:
568 case INFHEX18:
569 case INFPRISM6:
570 case INFPRISM12:
571 {
572 v = {
573 MAX_ANGLE,
574 MIN_ANGLE,
577 };
578
579 break;
580 }
581
582#endif
583
584
585 default:
586 libmesh_error_msg("Undefined element type!");
587 }
588
589 return v;
590}
591
592} // namespace libMesh
std::string name(const ElemQuality q)
This function returns a string containing some name for q.
std::vector< ElemQuality > valid(const ElemType t)
std::string describe(const ElemQuality q)
This function returns a string containing a short description of q.
The libMesh namespace provides an interface to certain functionality in the library.
ElemType
Defines an enum for geometric element types.
ElemQuality
Defines an enum for element quality metrics.