# Copyright (C) 2023 - 2026 ANSYS, Inc. and/or its affiliates.
# SPDX-License-Identifier: MIT
#
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in all
# copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.
"""Module for plotting decks."""
import typing
import numpy as np
import pandas as pd
from ansys.dyna.core import Deck
[docs]
def get_nid_to_index_mapping(nodes) -> np.ndarray:
"""Create array-based node ID to index mapping.
Returns an array where mapping[nid] = index.
This is much faster than dict-based lookup (5000x+ speedup).
"""
nids = nodes["nid"].values
max_nid = nids.max()
# Create lookup array: mapping[nid] = index
# Use -1 for invalid entries
mapping = np.full(max_nid + 1, -1, dtype=np.int32)
mapping[nids] = np.arange(len(nids), dtype=np.int32)
return mapping
[docs]
def merge_keywords(
deck: Deck,
) -> typing.Tuple[pd.DataFrame, typing.Dict]:
"""
Merge mesh keywords.
Given a deck, merges specific keywords (NODE, ELEMENT_SHELL, ELEMENT_BEAM, ELEMENT_SOLID)
and returns tham as data frames.
"""
nodes_temp = [kwd.nodes for kwd in deck.get_kwds_by_type("NODE")]
nodes = pd.concat(nodes_temp) if len(nodes_temp) else pd.DataFrame()
df_list = {}
for item in ["SHELL", "BEAM", "SOLID"]:
matching_elements = [kwd.elements for kwd in deck.get_kwds_by_type("ELEMENT") if kwd.subkeyword == item]
df_list[item] = pd.concat(matching_elements) if len(matching_elements) else pd.DataFrame()
return (
nodes,
df_list,
) # solids
[docs]
def process_nodes(nodes_df):
"""Process nodes DataFrame to extract XYZ coordinates as a numpy array."""
nodes_xyz = nodes_df[["x", "y", "z"]]
return nodes_xyz.to_numpy()
[docs]
def shell_facet_array(facets: pd.DataFrame) -> np.array:
"""
Get the shell facet array from the DataFrame.
Facets are a pandas frame that is a sequence of integers
or NAs with max length of 8.
valid rows contain 3,4,6, or 8 items consecutive from the
left. we don't plot quadratic edges so 6/8 collapse to 3/4
invalid rows are ignored, meaning they return an empty array
return an array of length 4 or 5 using the pyvista spec
for facets which includes a length prefix
[1,2,3]=>[3,1,2,3]
[1,2,3,0]=>[3,1,2,3]
[1,2,3,NA]=>[3,1,2,3]
"""
facet_array = np.empty(5, dtype=np.int32)
for idx, item in enumerate(facets):
# find the first empty column
if pd.isna(item) or item == 0:
if idx == 3 or idx == 6:
facet_array[0] = 3
return facet_array[:-1]
elif idx == 4:
facet_array[0] = 4
return facet_array
else:
# invalid
return np.empty(0)
# fill the output to the right of the prefix
if idx < 4:
facet_array[idx + 1] = item
facet_array[0] = 4
return facet_array
[docs]
def solid_array(solids: pd.DataFrame):
"""
Get the solid array from the DataFrame.
Solids are a pandas frame that is a sequence of integers
or NAs with max length of 28.
valid rows contain 3, 4, 6, or 8 items consecutive from the
left. We don't plot quadratic edges so 6/8 collapse to 3/4
invalid rows are ignored, meaning they return an empty array
return an array of length 4 or 5 using the pyvista spec
for facets which includes a length prefix
[1,2,3]=>[3,1,2,3]
[1,2,3,0]=>[3,1,2,3]
[1,2,3,NA]=>[3,1,2,3]
"""
# FACES CREATED BY THE SOLIDS BASED ON MANUAL
# A DUMMY ZERO IS PUT AS A PLACEHOLDER FOR THE LEN PREFIX
four_node_faces = [[0, 1, 2, 3], [0, 1, 2, 4], [0, 1, 3, 4], [0, 2, 3, 4]]
six_node_faces = [
[0, 1, 2, 5],
[0, 3, 4, 6],
[0, 2, 3, 5, 6],
[0, 1, 5, 6, 4],
[0, 1, 2, 3, 4],
]
eight_node_faces = [
[0, 1, 2, 3, 4],
[0, 1, 2, 5, 6],
[0, 5, 6, 7, 8],
[0, 3, 4, 7, 8],
[0, 2, 3, 6, 7],
[0, 1, 4, 5, 8],
]
facet_array = []
for idx, item in enumerate(solids):
# find the first empty column
if pd.isna(item) or item == 0:
if idx == 4:
facet_array = [len(facet) - 1 if i == 0 else solids[i - 1] for facet in four_node_faces for i in facet]
return facet_array
elif idx == 6:
facet_array = [len(facet) - 1 if i == 0 else solids[i - 1] for facet in six_node_faces for i in facet]
return facet_array
elif idx == 8:
facet_array = [len(facet) - 1 if i == 0 else solids[i - 1] for facet in eight_node_faces for i in facet]
return facet_array
else:
# invalid
return []
# fill the output to the right of the prefix
return np.array(facet_array)
[docs]
def line_array(lines: pd.DataFrame) -> np.array:
"""
Convert DataFrame to lines array.
`lines` is a pandas frame that is a sequence of integers
or NAs with max length of 2.
valid rows contain 2 items consecutive from the
left.
invalid rows are ignored, meaning they return an empty array
return an array of length 3 using the pyvista spec
for facets which includes a length prefix
[1,2,]=>[2,1,2]
[1,2,3,0]=>[]
[1,2,3,NA]=>[]
"""
line_array = np.empty(3, dtype=np.int32)
for idx, item in enumerate(lines):
# find the first empty column
if pd.isna(item) or item == 0:
if idx == 0 or idx == 1:
return np.empty(0)
# fill the output to the right of the prefix
if idx < 2:
line_array[idx + 1] = item
line_array[0] = 2
return line_array
[docs]
def map_facet_nid_to_index(flat_facets: np.array, mapping: np.ndarray) -> np.array:
"""Convert node IDs to indices using array-based mapping.
Given a flat list of facets or lines, use the mapping array to convert
node IDs to Python indices for PyVista visualization.
The mapping is a numpy array where mapping[nid] = index.
"""
result = flat_facets.copy()
# Build a mask for positions that are node IDs (not length prefixes)
mask = np.ones(len(flat_facets), dtype=bool)
i = 0
while i < len(flat_facets):
count = flat_facets[i]
mask[i] = False # Don't transform the count
i += count + 1
# Apply mapping only to node ID positions (vectorized)
result[mask] = mapping[flat_facets[mask]]
return result
[docs]
def get_pyvista():
"""Method to import pyvista, raising an exception if not installed."""
try:
import pyvista as pv
except ImportError:
raise Exception("plot is only supported if pyvista is installed")
return pv
[docs]
def is_jupyter_environment():
"""Check if code is running in a Jupyter notebook environment.
Returns
-------
bool
True if running in Jupyter notebook/lab, False otherwise.
"""
try:
from IPython import get_ipython
ipython = get_ipython()
if ipython is None:
return False
# Check for notebook or lab kernels
if "IPKernelApp" in ipython.config:
return True
except (ImportError, AttributeError):
pass
return False
[docs]
def get_polydata(deck: Deck, cwd=None, extract_surface=True):
"""Create the PolyData Object for plotting from a given deck with nodes and elements.
Parameters
----------
deck : Deck
The deck to plot
cwd : str, optional
Current working directory for expanding includes
extract_surface : bool, default=True
If True, extract only the exterior surface for solid elements.
This dramatically improves performance for large solid meshes with no visual difference,
since only the surface is visible anyway. Set to False to include all cells.
Returns
-------
pyvista.UnstructuredGrid
UnstructuredGrid containing the mesh for visualization
"""
# import this lazily (otherwise this adds over a second to the import time of pyDyna)
pv = get_pyvista()
# check kwargs for cwd. future more arguments to plot
# flatten deck
if cwd is not None:
flat_deck = deck.expand(cwd=cwd, recurse=True)
else:
flat_deck = deck.expand(recurse=True)
# get dataframes for each element types
nodes_df, element_dict = merge_keywords(flat_deck)
shells_df = element_dict["SHELL"]
beams_df = element_dict["BEAM"]
solids_df = element_dict["SOLID"]
nodes_list = process_nodes(nodes_df)
if len(nodes_df) == 0 or len(shells_df) + len(beams_df) + len(solids_df) == 0:
raise Exception("missing node or element keyword to plot")
mapping = get_nid_to_index_mapping(nodes_df)
# Extract shell facets - returns triangles and quads separately
triangles, tri_eids, tri_pids, quads, quad_eids, quad_pids = extract_shell_facets(shells_df, mapping)
lines, line_eids, line_pids = extract_lines(beams_df, mapping)
solids_info = extract_solids(solids_df, mapping)
# celltype_dict for beam and shell
celltype_dict = {
pv.CellType.LINE: lines.reshape([-1, 3])[:, 1:] if len(lines) > 0 else np.empty((0, 2), dtype=int),
}
# Add triangles if present
if len(triangles) > 0:
celltype_dict[pv.CellType.TRIANGLE] = triangles.reshape([-1, 4])[:, 1:]
# Add quads if present
if len(quads) > 0:
celltype_dict[pv.CellType.QUAD] = quads.reshape([-1, 5])[:, 1:]
# dict of cell types for node counts
solid_celltype = {
4: pv.CellType.TETRA,
5: pv.CellType.PYRAMID,
6: pv.CellType.WEDGE,
8: pv.CellType.HEXAHEDRON,
}
# Update celltype_dict with solid elements
solids_pids = np.empty((0), dtype=int)
solids_eids = np.empty((0), dtype=int)
for n_points, elements in solids_info.items():
if len(elements[0]) == 0:
continue
temp_solids, temp_solids_eids, temp_solids_pids = elements
celltype_dict[solid_celltype[n_points]] = temp_solids.reshape([-1, n_points + 1])[:, 1:]
# Update part_ids and element_ids info for solid elements
if len(solids_pids) != 0:
solids_pids = np.concatenate((solids_pids, temp_solids_pids), axis=0)
else:
solids_pids = temp_solids_pids
if len(solids_pids) != 0:
solids_eids = np.concatenate((solids_eids, temp_solids_eids), axis=0)
else:
solids_eids = temp_solids_eids
# Create UnstructuredGrid
plot_data = pv.UnstructuredGrid(celltype_dict, nodes_list)
# Combine shell metadata (triangles and quads)
shell_pids_combined = np.concatenate((tri_pids, quad_pids), axis=0)
shell_eids_combined = np.concatenate((tri_eids, quad_eids), axis=0)
# Extract only the exterior surface for performance if solids are present
# This dramatically speeds up plotting with no visual difference since only surface is visible
has_solids = len(solids_info) > 0 and any(len(v[0]) > 0 for v in solids_info.values())
if extract_surface and has_solids:
# Add cell data before extraction (extract_surface preserves cell_data for extracted cells)
plot_data.cell_data["part_ids"] = np.concatenate((line_pids, shell_pids_combined, solids_pids), axis=0)
plot_data.cell_data["element_ids"] = np.concatenate((line_eids, shell_eids_combined, solids_eids), axis=0)
# Extract surface - removes interior solid cells
plot_data = plot_data.extract_surface()
else:
# Add cell data without surface extraction
plot_data.cell_data["part_ids"] = np.concatenate((line_pids, shell_pids_combined, solids_pids), axis=0)
plot_data.cell_data["element_ids"] = np.concatenate((line_eids, shell_eids_combined, solids_eids), axis=0)
return plot_data
[docs]
def plot_deck(deck, **args):
"""Plot the deck with automatic Jupyter notebook support.
Parameters
----------
deck : Deck
The deck to plot
cwd : str, optional
Current working directory for expanding includes
jupyter_backend : str, optional
Jupyter backend to use. Options are 'static', 'server', 'trame', or None.
If not specified, automatically detects Jupyter environment and uses 'static'.
Set to None to disable Jupyter mode explicitly.
color : str, optional
Color of the mesh
scalars : str, optional
Scalars to color by (e.g., 'part_ids', 'element_ids')
**args :
Additional keyword arguments passed to pyvista.plot()
Returns
-------
pyvista plot or camera position
Depends on the plotting backend used
"""
# import this lazily (otherwise this adds over a second to the import time of pyDyna)
pv = get_pyvista()
plot_data = get_polydata(deck, args.pop("cwd", ""))
# set default color if both color and scalars are not specified
color = args.pop("color", None)
scalars = args.pop("scalars", None)
# Handle Jupyter backend - auto-detect if not specified
jupyter_backend = args.pop("jupyter_backend", "auto")
if jupyter_backend == "auto":
if is_jupyter_environment():
jupyter_backend = "static" # Default to static for simplicity
else:
jupyter_backend = None
# Add jupyter_backend to args if specified
if jupyter_backend is not None:
args["jupyter_backend"] = jupyter_backend
if scalars is not None:
return plot_data.plot(scalars=scalars, **args) # User specified scalars
elif color is not None:
return plot_data.plot(color=color, **args) # User specified color
else:
return plot_data.plot(color=pv.global_theme.color, **args) # Default color
