| 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) |