Debian Codegraph @

pyvista/core/utilities/cell_quality.py

raw
1 """Information about cell quality measures."""
2
3 from __future__ import annotations
4
5 from dataclasses import dataclass
6 from typing import TYPE_CHECKING
7 from typing import Literal
8 from typing import NoReturn
9
10 import numpy as np
11
12 from pyvista.core.celltype import _CELL_TYPE_INFO
13 from pyvista.core.celltype import CellType
14 from pyvista.core.utilities.misc import _NoNewAttrMixin
15
16 if TYPE_CHECKING:
17 from collections.abc import Sequence
18
19 _CellQualityLiteral = Literal[
20 'area',
21 'aspect_frobenius',
22 'aspect_gamma',
23 'aspect_ratio',
24 'collapse_ratio',
25 'condition',
26 'diagonal',
27 'dimension',
28 'distortion',
29 'jacobian',
30 'max_angle',
31 'max_aspect_frobenius',
32 'max_edge_ratio',
33 'med_aspect_frobenius',
34 'min_angle',
35 'oddy',
36 'radius_ratio',
37 'relative_size_squared',
38 'scaled_jacobian',
39 'shape',
40 'shape_and_size',
41 'shear',
42 'shear_and_size',
43 'skew',
44 'stretch',
45 'taper',
46 'volume',
47 'warpage',
48 ]
49
50 _CellTypesLiteral = Literal[
51 CellType.TRIANGLE,
52 CellType.QUAD,
53 CellType.TETRA,
54 CellType.HEXAHEDRON,
55 CellType.PYRAMID,
56 CellType.WEDGE,
57 ]
58 _CellTypeNamesLiteral = Literal[
59 'TRIANGLE',
60 'triangle',
61 'QUAD',
62 'quad',
63 'TETRA',
64 'tetra',
65 'HEXAHEDRON',
66 'hexahedron',
67 'PYRAMID',
68 'pyramid',
69 'WEDGE',
70 'wedge',
71 ]
72
73
74 @dataclass
75 class CellQualityInfo(_NoNewAttrMixin):
76 """Information about a cell's quality measure."""
77
78 cell_type: _CellTypesLiteral
79 quality_measure: _CellQualityLiteral
80 acceptable_range: tuple[float, float]
81 normal_range: tuple[float, float]
82 full_range: tuple[float, float]
83 unit_cell_value: float
84
85
86 def sqrt(num: float) -> float: # noqa: D103
87 return num**0.5
88
89
90 # Define aliases to help definitions fit on one line
91 INF = float('inf')
92 ANGLE = float((180 / np.pi) * np.arccos(1 / 3))
93 R22 = sqrt(2) / 2
94 R33 = sqrt(3) / 3
95
96 TRIANGLE: Literal[CellType.TRIANGLE] = CellType.TRIANGLE
97 QUAD: Literal[CellType.QUAD] = CellType.QUAD
98 TETRA: Literal[CellType.TETRA] = CellType.TETRA
99 HEXAHEDRON: Literal[CellType.HEXAHEDRON] = CellType.HEXAHEDRON
100 PYRAMID: Literal[CellType.PYRAMID] = CellType.PYRAMID
101 WEDGE: Literal[CellType.WEDGE] = CellType.WEDGE
102
103 Info = CellQualityInfo
104
105 _CELL_QUALITY_INFO = [
106 Info(TRIANGLE, 'area', (0.0, INF), (0.0, INF), (0.0, INF), sqrt(3.0) / 4.0),
107 Info(TRIANGLE, 'aspect_ratio', (1.0, 1.3), (1.0, INF), (1.0, INF), 1.0),
108 Info(TRIANGLE, 'aspect_frobenius', (1.0, 1.3), (1.0, INF), (1.0, INF), 1.0),
109 Info(TRIANGLE, 'condition', (1.0, 1.3), (1.0, INF), (1.0, INF), 1.0),
110 Info(TRIANGLE, 'distortion', (0.5, 1.0), (0.0, 1.0), (-INF, INF), 1.0),
111 Info(TRIANGLE, 'max_angle', (60.0, 90.0), (60.0, 180.0), (0.0, 180.0), 60.0),
112 Info(TRIANGLE, 'min_angle', (30.0, 60.0), (0.0, 60.0), (0.0, 360.0), 60.0),
113 Info(TRIANGLE, 'scaled_jacobian', (0.5, 2 * R33), (-2 * R33, 2 * R33), (-INF, INF), 1.0),
114 Info(TRIANGLE, 'radius_ratio', (1.0, 3.0), (1.0, INF), (1.0, INF), 1.0),
115 Info(TRIANGLE, 'shape', (0.25, 1.0), (0.0, 1.0), (0.0, 1.0), 1.0),
116 Info(TRIANGLE, 'shape_and_size', (0.25, 1.0), (0.0, 1.0), (0.0, 1.0), 1.0),
117 Info(QUAD, 'area', (0.0, INF), (0.0, INF), (-INF, INF), 1.0),
118 Info(QUAD, 'aspect_ratio', (1.0, 1.3), (1.0, INF), (1.0, INF), 1.0),
119 Info(QUAD, 'condition', (1.0, 4), (1.0, INF), (1.0, INF), 1.0),
120 Info(QUAD, 'distortion', (0.5, 1.0), (0.0, 1.0), (-INF, INF), 1.0),
121 Info(QUAD, 'jacobian', (0.0, INF), (0.0, INF), (-INF, INF), 1.0),
122 Info(QUAD, 'max_aspect_frobenius', (1.0, 1.3), (1.0, INF), (1.0, INF), 1.0),
123 Info(QUAD, 'max_angle', (90.0, 135.0), (90.0, 360.0), (0.0, 360.0), 90.0),
124 Info(QUAD, 'max_edge_ratio', (1.0, 1.3), (1.0, INF), (1.0, INF), 1.0),
125 Info(QUAD, 'med_aspect_frobenius', (1.0, 1.3), (1.0, INF), (1.0, INF), 1.0),
126 Info(QUAD, 'min_angle', (45.0, 90.0), (0.0, 90.0), (0.0, 360.0), 90.0),
127 Info(QUAD, 'oddy', (0.0, 0.5), (0.0, INF), (0.0, INF), 0.0),
128 Info(QUAD, 'radius_ratio', (1.0, 1.3), (1.0, INF), (1.0, INF), 1.0),
129 Info(QUAD, 'relative_size_squared', (0.3, 1.0), (0.0, 1.0), (0.0, 1.0), 1.0),
130 Info(QUAD, 'scaled_jacobian', (0.3, 1.0), (-1.0, 1.0), (-1.0, 1.0), 1.0),
131 Info(QUAD, 'shape', (0.3, 1.0), (0.0, 1.0), (0.0, 1.0), 1.0),
132 Info(QUAD, 'shape_and_size', (0.2, 1.0), (0.0, 1.0), (0.0, 1.0), 1.0),
133 Info(QUAD, 'shear', (0.3, 1.0), (0.0, 1.0), (0.0, 1.0), 1.0),
134 Info(QUAD, 'shear_and_size', (0.2, 1.0), (0.0, 1.0), (0.0, 1.0), 1.0),
135 Info(QUAD, 'skew', (0.0, 0.5), (0.0, 1.0), (0.0, 1.0), 0.0),
136 Info(QUAD, 'stretch', (0.25, 1.0), (0.0, 1.0), (0.0, INF), 1.0),
137 Info(QUAD, 'taper', (0.0, 0.7), (0.0, INF), (0.0, INF), 0.0),
138 Info(QUAD, 'warpage', (0.3, 1.0), (-1.0, 1.0), (-INF, INF), 1.0),
139 Info(TETRA, 'aspect_frobenius', (1.0, 1.3), (1.0, INF), (1.0, INF), 1.0),
140 Info(TETRA, 'aspect_gamma', (1.0, 3.0), (1.0, INF), (1.0, INF), 1.0),
141 Info(TETRA, 'aspect_ratio', (1.0, 3.0), (1.0, INF), (1.0, INF), 1.0),
142 Info(TETRA, 'collapse_ratio', (0.1, INF), (0.0, INF), (0.0, INF), sqrt(6.0) / 3.0),
143 Info(TETRA, 'condition', (1.0, 3), (1.0, INF), (1.0, INF), 1.0),
144 Info(TETRA, 'distortion', (0.5, 1.0), (0.0, 1.0), (-INF, INF), 1.0),
145 Info(TETRA, 'jacobian', (0.0, INF), (0.0, INF), (-INF, INF), R22),
146 Info(TETRA, 'min_angle', (40, ANGLE), (0.0, ANGLE), (0.0, 360), ANGLE),
147 Info(TETRA, 'radius_ratio', (1.0, 3), (1.0, INF), (1.0, INF), 1.0),
148 Info(TETRA, 'relative_size_squared', (0.3, 1.0), (0.0, 1.0), (0.0, 1.0), 1.0),
149 Info(TETRA, 'scaled_jacobian', (0.5, 1.0), (-1.0, 1.0), (-INF, INF), 1.0),
150 Info(TETRA, 'shape', (0.3, 1.0), (0.0, 1.0), (0.0, 1.0), 1.0),
151 Info(TETRA, 'shape_and_size', (0.2, 1.0), (0.0, 1.0), (0.0, 1.0), 1.0),
152 Info(TETRA, 'volume', (0.0, INF), (-INF, INF), (-INF, INF), sqrt(2.0) / 12.0),
153 Info(HEXAHEDRON, 'diagonal', (0.65, 1.0), (0.0, 1.0), (0.0, INF), 1.0),
154 Info(HEXAHEDRON, 'dimension', (0.0, INF), (0.0, INF), (0.0, INF), R33),
155 Info(HEXAHEDRON, 'distortion', (0.5, 1.0), (0.0, 1.0), (-INF, INF), 1.0),
156 Info(HEXAHEDRON, 'jacobian', (0.0, INF), (0.0, INF), (-INF, INF), 1.0),
157 Info(HEXAHEDRON, 'max_edge_ratio', (1.0, 1.3), (1.0, INF), (1.0, INF), 1.0),
158 Info(HEXAHEDRON, 'max_aspect_frobenius', (1.0, 3), (1.0, INF), (1.0, INF), 1.0),
159 Info(HEXAHEDRON, 'med_aspect_frobenius', (1.0, 3), (1.0, INF), (1.0, INF), 1.0),
160 Info(HEXAHEDRON, 'oddy', (0.0, 0.5), (0.0, INF), (0.0, INF), 0.0),
161 Info(HEXAHEDRON, 'relative_size_squared', (0.5, 1.0), (0.0, 1.0), (0.0, 1.0), 1.0),
162 Info(HEXAHEDRON, 'scaled_jacobian', (0.5, 1.0), (-1.0, 1.0), (-1.0, INF), 1.0),
163 Info(HEXAHEDRON, 'shape', (0.3, 1.0), (0.0, 1.0), (0.0, 1.0), 1.0),
164 Info(HEXAHEDRON, 'shape_and_size', (0.2, 1.0), (0.0, 1.0), (0.0, 1.0), 1.0),
165 Info(HEXAHEDRON, 'shear', (0.3, 1.0), (0.0, 1.0), (0.0, 1.0), 1.0),
166 Info(HEXAHEDRON, 'shear_and_size', (0.2, 1.0), (0.0, 1.0), (0.0, 1.0), 1.0),
167 Info(HEXAHEDRON, 'skew', (0.0, 0.5), (0.0, 1.0), (0.0, INF), 0.0),
168 Info(HEXAHEDRON, 'stretch', (0.25, 1.0), (0.0, 1.0), (0.0, INF), 1.0),
169 Info(HEXAHEDRON, 'taper', (0.0, 0.5), (0.0, INF), (0.0, INF), 0.0),
170 Info(HEXAHEDRON, 'volume', (0.0, INF), (0.0, INF), (-INF, INF), 1.0),
171 Info(PYRAMID, 'volume', (0.0, INF), (-INF, INF), (-INF, INF), sqrt(2.0) / 6.0),
172 Info(WEDGE, 'volume', (0.0, INF), (-INF, INF), (-INF, INF), sqrt(3.0) / 4.0),
173 ]
174
175 # Create lookup dict
176 _CELL_QUALITY_LOOKUP: dict[CellType, dict[_CellQualityLiteral, CellQualityInfo]] = {}
177 for info in _CELL_QUALITY_INFO:
178 _CELL_QUALITY_LOOKUP.setdefault(info.cell_type, {})
179 _CELL_QUALITY_LOOKUP[info.cell_type][info.quality_measure] = info
180
181
182 _CELL_TYPE_NAMES = [typ.name for typ in _CELL_QUALITY_LOOKUP.keys()]
183
184
185 def cell_quality_info(
186 cell_type: _CellTypesLiteral | _CellTypeNamesLiteral,
187 quality_measure: _CellQualityLiteral,
188 ) -> CellQualityInfo:
189 """Return information about a cell's quality measure.
190
191 This function returns information about a quality measure computed by
192 :meth:`~pyvista.DataObjectFilters.cell_quality` for a specified
193 :class:`~pyvista.CellType`. The following is provided for each measure:
194
195 - ``acceptable_range``: Well-behaved cells have values in this range.
196 - ``normal_range``: All cells except those with degeneracies have values in this range.
197 - ``full_range``: All cells including degenerate ones have values in this range.
198 - ``unit_cell_value``: The quality measure value for a reference unit cell (e.g.
199 equilateral triangle with edge length of one for triangles).
200
201 This information can help inform if a particular cell is of high or low quality.
202
203 See the tables below for a summary of all cell quality info available from this
204 function.
205
206 .. include:: /api/core/cell_quality/cell_quality_info_table_TRIANGLE.rst
207
208 .. include:: /api/core/cell_quality/cell_quality_info_table_QUAD.rst
209
210 .. include:: /api/core/cell_quality/cell_quality_info_table_HEXAHEDRON.rst
211
212 .. include:: /api/core/cell_quality/cell_quality_info_table_TETRA.rst
213
214 .. include:: /api/core/cell_quality/cell_quality_info_table_WEDGE.rst
215
216 .. include:: /api/core/cell_quality/cell_quality_info_table_PYRAMID.rst
217
218
219 .. note::
220
221 The information returned by this function is based on the
222 `Verdict Library Reference Manual <https://github.com/sandialabs/verdict/raw/master/SAND2007-2853p.pdf>`_.
223
224 .. note::
225
226 Information is not available for all valid quality measures computed by
227 :meth:`~pyvista.DataObjectFilters.cell_quality`. Only a subset
228 is provided here. If information about a measure is missing and you have
229 knowledge about its acceptable range, normal range, etc., please consider
230 submitting a pull request on GitHub at https://github.com/pyvista/pyvista.
231
232 Parameters
233 ----------
234 cell_type : CellType | str
235 Cell type to get information about. May be a :class:`~pyvista.CellType` or the
236 name of a cell type as a string.
237
238 quality_measure : str
239 Quality measure to get information about. May be any quality measure from
240 :ref:`cell_quality_measures_table`.
241
242 Returns
243 -------
244 CellQualityInfo
245 Dataclass with information about the quality measure for a specific cell type.
246
247 Raises
248 ------
249 ValueError
250 If info is not available for the specified cell type or measure.
251
252 See Also
253 --------
254 :meth:`~pyvista.DataObjectFilters.cell_quality`
255
256 Examples
257 --------
258 Get cell quality info for :attr:`~pyvista.CellType.TRIANGLE` cells and the
259 ``'scaled_jacobian'`` quality measure.
260
261 >>> import pyvista as pv
262 >>> info_tri = pv.cell_quality_info(pv.CellType.TRIANGLE, 'scaled_jacobian')
263 >>> info_tri # doctest: +NORMALIZE_WHITESPACE
264 CellQualityInfo(cell_type=<CellType.TRIANGLE: 5>,
265 quality_measure='scaled_jacobian',
266 acceptable_range=(0.5, 1.1547005383792515),
267 normal_range=(-1.1547005383792515, 1.1547005383792515),
268 full_range=(-inf, inf),
269 unit_cell_value=1.0)
270
271 Show the acceptable range for this measure.
272
273 >>> info_tri.acceptable_range
274 (0.5, 1.1547005383792515)
275
276 Show the value of this measure for equilateral triangles with edge length of one.
277
278 >>> info_tri.unit_cell_value
279 1.0
280
281 Get info for the same measure but for :attr:`~pyvista.CellType.QUAD` cells.
282
283 >>> info_quad = pv.cell_quality_info(pv.CellType.QUAD, 'scaled_jacobian')
284 >>> info_quad # doctest: +NORMALIZE_WHITESPACE
285 CellQualityInfo(cell_type=<CellType.QUAD: 9>,
286 quality_measure='scaled_jacobian',
287 acceptable_range=(0.3, 1.0),
288 normal_range=(-1.0, 1.0),
289 full_range=(-1.0, 1.0),
290 unit_cell_value=1.0)
291
292 Show the acceptable range. Note that it differs for quads compared to triangles.
293
294 >>> info_quad.acceptable_range
295 (0.3, 1.0)
296
297 Show the value of this measure for a square cell with edge length of one.
298
299 >>> info_quad.unit_cell_value
300 1.0
301
302 See :ref:`mesh_quality_example` for more examples using this function.
303
304 """
305
306 def raise_error(item_: str, valid_options_: Sequence[str]) -> NoReturn:
307 msg = (
308 f'Cell quality info is not available for {item_}. Valid options are:\n{valid_options_}'
309 )
310 raise ValueError(msg)
311
312 if isinstance(cell_type, str):
313 upper = cell_type.upper()
314 if upper not in _CELL_TYPE_NAMES:
315 item = f'cell type {upper!r}'
316 raise_error(item, _CELL_TYPE_NAMES)
317 value = CellType(_CELL_TYPE_INFO[upper].value)
318 else:
319 value = CellType(cell_type)
320
321 # Lookup measures available for the cell type
322 try:
323 measures = _CELL_QUALITY_LOOKUP[value]
324 except KeyError:
325 item = f'cell type {value.name!r}'
326 raise_error(item, _CELL_TYPE_NAMES)
327
328 # Lookup the measure info
329 try:
330 return measures[quality_measure]
331 except KeyError:
332 item = f'{value.name!r} measure {quality_measure!r}'
333 valid_options = list(measures.keys())
334 raise_error(item, valid_options)