tensormesh.visualization

Draw Graph

draw_graph(sparse_matrix: SparseMatrix | coo_matrix | csr_matrix | csc_matrix | dia_matrix | dok_matrix | lil_matrix, points: Tensor | ndarray, draw_points: bool = True, point_color: str = 'orange', color: str = 'blue', linewidth: int = 3, alpha: float = 0.5, ax: Axes | Axes3D | None = None) → Axes | Axes3D[source]
Parameters:

  • sparse_matrix (Union[SparseMatrix, ScipySparseMatrix]) – the sparse matrix

  • points (Union[Tensor, np.ndarray]) – 2D tensor of shape [n_points, 2] the points of the mesh

  • color (str, optional) – the color of the edge, default is “blue”

  • linewidth (int, optional) – the width of the edge, default is 3

  • ax (Axes, optional) – the axis, default is None

Returns:

ax – the axis

Return type:

Axes

Draw Mesh

draw_mesh(mesh, draw_basis: bool = True, edgecolor='blue', linewidth=3, alpha=0.3, ax=None)[source]
Parameters:

  • mesh (Mesh) – the mesh

  • draw_basis (bool) – whether to draw basis

  • edgecolor (str, optional) – the color of the edge, default is “blue”

  • linewidth (float, optional) – the width of the edge, default is 3

  • alpha (float, optional) – the transparency of the edge, default is 0.3

  • ax (Axes, optional) – the axis, default is None

Returns:

ax – the axis

Return type:

Axes

Draw Facet

draw_facet_2d(points: Tensor | ndarray, elements: Dict[str, Tensor | ndarray], draw_basis: bool = False, point_color: str = 'orange', color: str = 'blue', alpha: float = 0.5, linewidth: int = 1, ax: Axes | None = None)[source]
Parameters:

  • points (Tensor|np.ndarray) – 2D tensor of shape [n_points, 2] the points of the mesh

  • elements (Dict[str,Tensor|np.ndarray]) – the elements of the mesh [n_element, n_basis]

  • color (str, optional) – the color of the facet, default is “blue”

  • alpha (float, optional) – the transparency of the facet, default is 0.5

  • linewidth (int, optional) – the linewidth of the facet, default is 3

  • ax (Axes, optional) – the axis, default is None

Returns:

ax – the axis

Return type:

Axes

draw_face(mesh, color='blue', linewidth=3, ax=None)[source]
Parameters:

  • mesh (Mesh) – the mesh

  • ax (Axes, optional) – the axis, default is None

Returns:

ax – the axis

Return type:

Axes

Draw Element Value

draw_element_value_2d_tri(points: Tensor | ndarray, elements: Tensor | ndarray, values: Tensor | ndarray, alpha: float | Tensor | ndarray | None = None, cmap: str = 'viridis', color: str | None = None, ax: Axes | None = None, **kwargs) → Tuple[PolyCollection, Axes][source]

Parameters:

points: torch.Tensor or np.ndarray

[n_points, 2]

elements: torch.Tensor or np.ndarray

[n_elements, 3]

values: torch.Tensor or np.ndarray

[n_elements]

alpha: float or torch.Tensor or np.ndarray

[n_elements] should be greater or equal 0

cmap: str

colormap, default is ‘viridis’

color: str

color, if alpha is torch.Tensor or np.ndarray, the color will be used default is None

ax: Axes

default is None

Returns:

Axes

draw_element_value_2d(points: Tensor | ndarray, elements: Dict[str, Tensor | ndarray], values: Dict[str, Tensor | ndarray], alpha: float | Dict[str, Tensor | ndarray] = 1.0, cmap: str = 'viridis', color: str | None = None, ax: Axes | None = None, **kwargs) → Tuple[Dict[str, PolyCollection], Axes][source]
Parameters:

  • points (Tensor or np.ndarray) – [n_points, 2]

  • elements (Dict[str, Tensor or np.ndarray]) – keys are ‘tri’ or ‘quad’ values are torch.Tensor or np.ndarray [n_elements, 3] or [n_elements, 4]

  • values (Dict[str, Tensor or np.ndarray]) – [n_elements]

  • alpha (float or Tensor or np.ndarray) – [n_elements] should be greater or equal 0 and less or equal than 1

  • cmap (str) – colormap, default is ‘viridis’

  • color (str) – color, if alpha is torch.Tensor or np.ndarray, the color will be used default is None

  • ax (plt.Axes) – default is None

Returns:

  • collections (Dict[str, matplotlib.collections.PolyCollection]) – Dictionary mapping element types to their polygon collections

  • ax (matplotlib.axes.Axes) – The matplotlib axes object

update_element_value_2d_tri(img: PolyCollection, values: Tensor | ndarray, alpha: float | Tensor | ndarray | None = None) → PolyCollection[source]

Update face colors of a triangle PolyCollection.

Parameters:

  • img (PolyCollection) – Collection returned by a draw helper.

  • values (Tensor or np.ndarray) – Per-element values, shape (n_elements,).

  • alpha (float or Tensor or np.ndarray, optional) – Per-element opacity, shape (n_elements,); must be non-negative when provided as an array.

Returns:

The same collection with updated array data.

Return type:

PolyCollection

update_element_value_2d(collections: Dict[str, PolyCollection], values: Dict[str, Tensor | ndarray], alpha: float | Dict[str, Tensor | ndarray] = 1.0) → Dict[str, PolyCollection][source]
Parameters:

  • collections (Dict[str,PolyCollection])

  • values (Dict[str, Tensor or np.ndarray]) – [n_elements]

  • alpha (float or Tensor or np.ndarray) – [n_elements] should be greater or equal 0 and less or equal than 1

draw_element_value_3d(points: Tensor | ndarray, elements: Dict[str, Tensor | ndarray], values: Dict[str, Tensor | ndarray], alpha: float | Dict[str, Tensor | ndarray] = 0.3, cmap: str = 'viridis', color: str | None = None, density: bool = 25, ax: Axes3D | None = None) → Tuple[Dict[str, Path3DCollection], Axes3D][source]
Parameters:

  • points (Tensor or np.ndarray) – [n_points, 3]

  • elements (Dict[str,Tensor|np.ndarray]) – dictionary of elements for each element type

  • values (Dict[str,Tensor|np.ndarray]) – dictionary of values for each element type [n_elements]

  • alpha (float or Dict[str,Tensor|np.ndarray]) – transparency value(s), default is 1.0

  • cmap (str) – colormap, default is ‘viridis’

  • color (Optional[str]) – if specified, use this color instead of colormap

  • ax (Optional[plt.Axes]) – matplotlib 3D axes, default is None

Returns:

  • collections (Dict[str,Path3DCollection]) – dictionary of scatter collections for each element type

  • ax (Axes3D) – the matplotlib 3D axes

update_element_value_3d(collections: Dict[str, Path3DCollection], points: Tensor | ndarray, elements: Dict[str, Tensor | ndarray], values: Dict[str, Tensor | ndarray], density: int = 25)[source]

Update the element values for a 3D visualization

Parameters:

  • collections (Dict[str, Path3DCollection]) – Dictionary mapping element types to their scatter plot collections

  • points (Union[Tensor, np.ndarray]) – Points tensor of shape [n_points, 3]

  • elements (Dict[str, Union[Tensor, np.ndarray]]) – Dictionary mapping element types to their element arrays

  • values (Dict[str, Union[Tensor, np.ndarray]]) – Dictionary mapping element types to their value arrays

  • density (int) – Grid density for interpolation, default 25

draw_element_value(mesh, values: Dict[str, Tensor | ndarray], alpha: float | Dict[str, Tensor | ndarray] | None = None, cmap: str = 'viridis', color: str | None = None, density: int = 25, ax: Axes | Axes3D | None = None) → Tuple[Dict[str, PolyCollection | Path3DCollection], Axes | Axes3D][source]

Draw element values for 2D or 3D mesh

Parameters:

  • mesh (Mesh) – The mesh object containing points and elements

  • values (Dict[str, Union[Tensor, np.ndarray]]) – Dictionary mapping element types to their value arrays

  • alpha (Optional[Union[float, Dict[str, Union[Tensor, np.ndarray]]]]) – Transparency value(s). If None, defaults to 1.0 for 2D and 0.2 for 3D. For float values, should be between 0 and 1. For tensor/array values, should be shape [n_elements] with values between 0 and 1.

  • cmap (str) – Colormap name, default ‘viridis’

  • color (Optional[str]) – If specified, use this color instead of colormap

  • density (int) – Grid density for 3D interpolation, default 25

  • ax (Optional[Union[Axes, Axes3D]]) – Matplotlib axes, default None

Returns:

  • collections (Dict[str, Union[PolyCollection, Path3DCollection]]) – Dictionary mapping element types to their collections

  • ax (Union[Axes, Axes3D]) – The matplotlib axes

update_element_value(mesh, collections: Dict[str, PolyCollection | Path3DCollection], values: Dict[str, Tensor | ndarray], alpha: float | Dict[str, Tensor | ndarray] = 1.0, density: int = 25)[source]

Update element values for 2D or 3D visualization

Parameters:

  • mesh (Mesh) – The mesh object containing points and elements

  • collections (Dict[str, Union[PolyCollection, Path3DCollection]]) – Dictionary mapping element types to their collections

  • values (Dict[str, Union[Tensor, np.ndarray]]) – Dictionary mapping element types to their value arrays

  • alpha (float or Dict[str, Union[Tensor, np.ndarray]]) – Transparency value(s), default 1.0

  • density (int) – Grid density for 3D interpolation, default 25

Draw Point Value

draw_point_value_2d_tri_gouraud(points: Tensor | ndarray, point_values: Tensor | ndarray, elements: Tensor | ndarray, cmap: str = 'jet', ax: Axes | None = None) → Tuple[TriMesh, Axes][source]
Parameters:

  • points (Union[Tensor,np.ndarray]) – 2D tensor of shape [n_points, 2] the points of the mesh

  • point_values (Union[Tensor,np.ndarray]) – 1D tensor of shape [n_points] the value of the points

  • elements (Union[Tensor,np.ndarray]) – 2D tensor of shape [n_elements, 3] the elements of the mesh

  • cmap (str, optional) – the colormap, default is ‘jet’

  • ax (Axes, optional) – the axis, default is None

Returns:

  • img (matplotlib.collections.PathCollection)

  • ax (matplotlib.axes.Axes)

update_point_value_2d_tri_gouraud(img: TriMesh, point_values: Tensor | ndarray)[source]
Parameters:

  • img (PolyCollection) – the image

  • point_values (Union[Tensor,np.ndarray]) – the point values, 1D tensor of shape [n_points]

draw_point_value_2d_interpolation(points: Tensor | ndarray, point_values: Tensor | ndarray, density: int = 100, cmap: str = 'jet', use_scatter: bool = False, ax: Axes | None = None) → Tuple[PathCollection | AxesImage, Axes][source]

Parameters:

points: Union[torch.Tensor,np.ndarray]

2D tensor of shape [n_points, 2] the points of the mesh

point_values: Union[torch.Tensor,np.ndarray]

1D tensor of shape [n_points] the value of the points

density: int

the density of the interpolation default is 100

cmap: str

the colormap default is ‘jet’

ax: Optional[matplotlib.axes.Axes]

the axis default is None

returns:

  • img (matplotlib.collections.PathCollection)

  • ax (matplotlib.axes.Axes)

update_point_value_2d_interpolation(img: PathCollection | AxesImage, points: Tensor | ndarray, point_values: Tensor | ndarray)[source]
Parameters:

  • img (Union[PathCollection,AxesImage]) – the image

  • points (Union[Tensor,np.ndarray]) – the points, 2D tensor of shape [n_points, 2]

  • point_values (Union[Tensor,np.ndarray]) – the point values, 1D tensor of shape [n_points]

draw_point_value_2d(points: Tensor | ndarray, point_values: Tensor | ndarray, elements: Dict[str, Tensor | ndarray], density: int = 100, cmap: str = 'jet', use_scatter: bool = False, ax: Axes | None = None)[source]

Draw nodal values on a 2D mesh.

For first-order triangles uses Gouraud shading; otherwise uses 2D interpolation.

Parameters:

  • points (Union[Tensor,np.ndarray]) – 2D tensor of shape [n_points, 2] the points of the mesh

  • point_values (Union[Tensor,np.ndarray]) – 1D tensor of shape [n_points] the value of the points

  • elements (Dict[str,Union[Tensor,np.ndarray]]) – 2D tensor of shape [n_elements, n_basis] the elements of the mesh

  • density (int) – the density of the interpolation default is 100

  • cmap (str) – the colormap default is ‘jet’

  • use_scatter (bool)

  • ax (Optional[Axes]) – the axis default is None

Returns:

  • img (matplotlib.collections.PathCollection)

  • ax (matplotlib.axes.Axes) – the axis

update_point_value_2d(img: PathCollection | PolyCollection | AxesImage, points: Tensor | ndarray, point_values: Tensor | ndarray)[source]
Parameters:

  • img (PathCollection) – the image

  • points (Union[Tensor,np.ndarray]) – the points, 2D tensor of shape [n_points, 2]

  • point_values (Union[Tensor,np.ndarray]) – the point values, 1D tensor of shape [n_points]

draw_point_value_3d_interpolation(points: Tensor | ndarray, point_values: Tensor | ndarray, density: int = 25, cmap: str = 'jet', ax: Axes3D | None = None) → tuple[Path3DCollection, Axes3D][source]
Parameters:

  • points (Union[Tensor, np.ndarray]) – 3D tensor of shape [n_points, 3] the points of the mesh

  • point_values (Union[Tensor, np.ndarray]) – 1D tensor of shape [n_points] the value of the points

  • density (int) – the density of the interpolation default is 50

  • cmap (str) – the colormap default is ‘jet’

  • ax (Optional[Axes]) – the axis, should be a 3D axis default is None

Returns:

  • img (list[matplotlib.collections.PathCollection]) – list of scatter plots for each slice

  • ax (matplotlib.axes.Axes) – the 3D axis

update_point_value_3d_interpolation(img: Path3DCollection, points: Tensor | ndarray, point_values: Tensor | ndarray)[source]
Parameters:

  • scatter_plots (list[PathCollection]) – list of scatter plots returned by draw_point_value_3d_interpolation

  • points (Union[Tensor, np.ndarray]) – the points, 3D tensor of shape [n_points, 3]

  • point_values (Union[Tensor, np.ndarray]) – the point values, 1D tensor of shape [n_points]

draw_point_value(mesh, point_values: Tensor | ndarray, density: int = 25, cmap: str = 'jet', use_scatter: bool = False, ax: Axes | Axes3D | None = None) → Tuple[TriMesh | AxesImage | PathCollection | Path3DCollection, Axes | Axes3D][source]
Parameters:

  • points (Union[Tensor, np.ndarray]) – tensor of shape [n_points, dim] the points of the mesh

  • point_values (Union[Tensor, np.ndarray]) – 1D tensor of shape [n_points] the value of the points

  • elements (Dict[str,Union[Tensor, np.ndarray]]) – the elements of the mesh

  • density (int) – the density of the interpolation default is 100

  • cmap (str) – the colormap default is ‘jet’

  • use_scatter (bool) – whether to use scatter plot (2D only)

  • ax (Optional[Axes]) – the axis default is None

Returns:

  • img (Union[matplotlib.collections.PathCollection, list[matplotlib.collections.PathCollection]])

  • ax (matplotlib.axes.Axes)

update_point_value(mesh, img: TriMesh | AxesImage | PathCollection | Path3DCollection, point_values: Tensor | ndarray)[source]
Parameters:

  • img (Union[PathCollection, PolyCollection, AxesImage, list]) – the visualization object(s) to update

  • points (Union[Tensor, np.ndarray]) – the points

  • point_values (Union[Tensor, np.ndarray]) – the point values

Stream Plotter

class StreamPlotter(nrows: int = 1, ncols: int = 1, width: int = 5, height: int = 5, filename: str = 'stream_plotter.mp4')[source]

Bases: object

__init__(nrows: int = 1, ncols: int = 1, width: int = 5, height: int = 5, filename: str = 'stream_plotter.mp4')[source]
grab_frame(**savefig_kwargs)[source]
update()[source]
draw_mesh_2d(points: Tensor | ndarray, elements: Dict[str, Tensor | ndarray], point_values: Tensor | ndarray, ax: Axes | None = None, cmap: str = 'jet', density: int = 100, use_scatter: bool = False, show_colorbar: bool = True, title: str = '', update: bool = True, show_mesh: bool = True, show_basis: bool = True, umin: float | None = None, umax: float | None = None, linewidth: int = 1, basiscolor: str = 'orange', linecolor: str = 'blue')[source]
Parameters:

  • mesh (Mesh) – the mesh

  • point_values (Tensor [n_point]) – the value of the points

  • ax (Axes, optional) – the axis, default is None

  • cmap (str)

  • density (int)

  • use_scatter (bool)

  • show_colorbar (bool, optional) – whether to show the colorbar, default is True

  • title (str, optional) – the title of the plot, default is “”

  • update (bool, optional) – whether to update the plot, default is True

  • show_mesh (bool, optional) – whether to show the mesh, default is True

draw_mesh_2d_static(points: Tensor | ndarray, elements: Dict[str, Tensor | ndarray], point_values: Dict[str, Tensor | ndarray] | ndarray | Tensor, show_colorbar: bool = True, show_mesh: bool = False, filename: str = 'mesh_2d_stream.jpq', umin: float | None = None, umax: float | None = None, **kwargs)[source]
draw_mesh_2d_stream(points: Tensor, elements: Dict[str, Tensor], point_values: Dict[str, Sequence[ndarray | Tensor] | ndarray | Tensor] | Sequence[ndarray | Tensor] | ndarray | Tensor, dt: float | None = None, show_colorbar: bool = True, fix_colorbar: bool = False, show_mesh: bool = False, filename: str = 'mesh_2d_stream.mp4', **kwargs)[source]
Parameters:

  • mesh (Mesh)

  • point_values (Dict[str,np.ndarray|Tensor]|Tensor|np.ndarray) – if more than one value is supposed to be drawn, then one could use {value_name:value} format each tensor or ndarray should be of shape [time_seq, n_points]

Animation

animate_deformation(mesh, displacement: Tensor, file_name: str, frames: int = 30, fps: int = 10, scale_factor: float = 1.0, scalars: str = 'displacement')[source]

Static Plot

plot_deformation(mesh, displacement: Tensor, file_name: str, scale_factor: float = 1.0, camera_position='isometric', fixed_nodes=None, force_vectors=None, linearize: bool = True)[source]

PyVista

plot_value(kwargs, mesh, save_path=None, dt=None, show_mesh=False)[source]

Utilities

as_sparse_matrix(x: SparseMatrix | coo_matrix | csr_matrix | csc_matrix | dia_matrix | dok_matrix | lil_matrix) → SparseMatrix[source]
as_tensor(x: Tensor | ndarray) → Tensor[source]
as_ndarray(x: Tensor | ndarray) → ndarray[source]
dim(x: Tensor | ndarray) → int[source]
grid(dim: int, min_vals: Sequence[float], max_vals: Sequence[float], density: int = 100) → ndarray[source]

Create a grid of points in 2D or 3D space.

Parameters:

  • dim (int) – Dimension of the grid (2 or 3)

  • min_vals (Sequence[float]) – Minimum values for each dimension

  • max_vals (Sequence[float]) – Maximum values for each dimension

  • density (int, optional) – Number of points along each dimension, by default 100

Returns:

Grid points with shape (density^dim, dim)

Return type:

np.ndarray

setup_headless()[source]

Start xvfb for headless rendering if needed.

mesh_to_pyvista(mesh, point_data=None, cell_data=None, linearize=False)[source]

Convert TensorMesh to PyVista mesh via intermediate VTU file.

Parameters:

  • mesh (Mesh)

  • point_data (dict, optional) – Dict of {name: tensor/array} to add as point data.

  • cell_data (dict, optional) – Dict of {name: tensor/array} to add as cell data.

  • linearize (bool, optional) – If True, convert high-order elements to linear (e.g. tet10 -> tet4).

Return type:

pyvista.DataSet