tidy3d.TriangularSurfaceDataset

tidy3d.TriangularSurfaceDataset#

class TriangularSurfaceDataset[source]#

Bases: UnstructuredDataset

Dataset for storing triangulated surface data. Data values are associated with the nodes of the mesh.

Parameters:

Note

To use full functionality of unstructured datasets one must install vtk package (pip install tidy3d[vtk] or pip install vtk). For visualization, pyvista is recommended (pip install pyvista). Otherwise the functionality of unstructured datasets is limited to creation, writing to/loading from a file, and arithmetic manipulations.

Example

>>> import numpy as np
>>> from tidy3d.components.data.data_array import PointDataArray, CellDataArray, IndexedDataArray
>>>
>>> # Create a simple triangulated surface
>>> tri_grid_points = PointDataArray(
...     [[0.0, 0.0, 0.0], [1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [1.0, 1.0, 0.0]],
...     coords=dict(index=np.arange(4), axis=np.arange(3)),
... )
>>>
>>> tri_grid_cells = CellDataArray(
...     [[0, 1, 2], [1, 2, 3]],
...     coords=dict(cell_index=np.arange(2), vertex_index=np.arange(3)),
... )
>>>
>>> tri_grid_values = IndexedDataArray(
...     [1.0, 2.0, 3.0, 4.0], coords=dict(index=np.arange(4)),
... )
>>>
>>> tri_grid = TriangularSurfaceDataset(
...     points=tri_grid_points,
...     cells=tri_grid_cells,
...     values=tri_grid_values,
... )
>>>
>>> # Visualize the surface (change show=False to show=True to display the plot)
>>> _ = tri_grid.plot(show=False)
>>>
>>> # Customize the visualization (change show=False to show=True to display the plot)
>>> _ = tri_grid.plot(cmap='plasma', grid=True, grid_color='white', show=False)
>>>
>>> # For vector fields
>>> vector_values = IndexedDataArray(
...     [[1, 0, 0], [0, 1, 0], [0, 0, 1], [1, 1, 0]],
...     coords=dict(index=np.arange(4), axis=np.arange(3)),
... )
>>> vector_grid = tri_grid.updated_copy(values=vector_values)
>>>
>>> # Plot as arrow field (change show=False to show=True to display the plot)
>>> _ = vector_grid.quiver(scale=0.2, show=False)

Attributes

points

values

cells

Fundamental parameters to set up based on grid dimensionality

Methods

get_cell_volumes()

Get areas associated to each cell of the grid.

plane_slice(axis, pos)

Slice data with a plane and return the resulting line as a DataArray.

plot([plotter, field, grid, cbar, cmap, ...])

Plot the surface mesh and/or associated data using PyVista.

quiver([plotter, dim, scale, downsampling, ...])

Plot the associated data as vector field using arrows.

sel([x, y, z, method])

Extract/interpolate data along one or more spatial or non-spatial directions.
points#
values#
cells#

Fundamental parameters to set up based on grid dimensionality

plane_slice(axis, pos)[source]#

Slice data with a plane and return the resulting line as a DataArray.

Parameters:

  • axis (Axis) – The normal direction of the slicing plane.

  • pos (float) – Position of the slicing plane along its normal direction.

Returns:

The resulting slice.

Return type:

xarray.DataArray

sel(x=None, y=None, z=None, method=None, **sel_kwargs)[source]#

Extract/interpolate data along one or more spatial or non-spatial directions. Currently works only for non-spatial dimensions through additional arguments. Selection along non-spatial dimensions is forwarded to .sel() xarray function. Parameter ‘method’ applies only to non-spatial dimensions.

Parameters:

  • x (Union[float, ArrayLike] = None) – x-coordinate of the slice.

  • y (Union[float, ArrayLike] = None) – y-coordinate of the slice.

  • z (Union[float, ArrayLike] = None) – z-coordinate of the slice.

  • method (Literal[None, "nearest", "pad", "ffill", "backfill", "bfill"] = None) – Method to use in xarray sel() function.

  • **sel_kwargs (dict) – Keyword arguments to pass to the xarray sel() function.

Returns:

Extracted data.

Return type:

Union[TriangularSurfaceDataset, xarray.DataArray]

get_cell_volumes()[source]#

Get areas associated to each cell of the grid.

plot(plotter=None, field=True, grid=False, cbar=True, cmap='viridis', vmin=None, vmax=None, grid_color='black', grid_width=1.0, opacity=1.0, show=True, windowed=None, window_size=(800, 600), **mesh_kwargs)[source]#

Plot the surface mesh and/or associated data using PyVista.

Parameters:

  • plotter (pyvista.Plotter = None) – PyVista plotter to add the mesh to. If not specified, one is created.

  • field (bool = True) – Whether to plot the data field.

  • grid (bool = False) – Whether to show the mesh edges/grid lines.

  • cbar (bool = True) – Display scalar bar (only if field == True).

  • cmap (str = "viridis") – Color map to use for plotting.

  • vmin (float = None) – The lower bound of data range that the colormap covers. If None, inferred from the data.

  • vmax (float = None) – The upper bound of data range that the colormap covers. If None, inferred from the data.

  • grid_color (str = "black") – Color of grid lines when grid == True.

  • grid_width (float = 1.0) – Width of grid lines when grid == True.

  • opacity (float = 1.0) – Opacity of the mesh (0=transparent, 1=opaque).

  • show (bool = True) – Whether to display the plot immediately. If False, returns plotter for further customization.

  • windowed (bool = None) – Whether to display in an external window. If None (default), automatically detects environment (inline in notebooks, windowed otherwise). Set to True to force external window even when running in a notebook, which provides better interactivity and performance.

  • window_size (tuple = (800, 600)) – Size of the window (width, height) when creating new plotter.

  • **mesh_kwargs – Additional keyword arguments passed to plotter.add_mesh().

Returns:

The plotter object with the mesh added. Returns None if show=True and plotter was auto-created.

Return type:

pyvista.Plotter

Raises:

DataError – If nothing to plot or if multiple fields present without selection.

quiver(plotter=None, dim='axis', scale=0.1, downsampling=1, color='magnitude', cbar=True, cmap='Spectral', show=True, windowed=None, window_size=(800, 600), **arrow_kwargs)[source]#

Plot the associated data as vector field using arrows.

Field values must have length 3 along the dimension representing x, y, and z components.

Parameters:

  • plotter (pyvista.Plotter = None) – PyVista plotter to add the arrows to. If not specified, one is created.

  • dim (str = "axis") – Dimension along which x, y, z components are stored.

  • scale (float = 0.1) – Size of arrows relative to the diagonal length of the surface bounding box.

  • downsampling (int = 1) – Step for selecting points for plotting (1 for plotting all points).

  • color (str = "magnitude") – How to color arrows. If “magnitude”, colors by vector magnitude using cmap. Otherwise, should be a valid color string (e.g., ‘red’, ‘blue’, ‘#FF0000’).

  • cbar (bool = True) – Display scalar bar (only if color == "magnitude").

  • cmap (str = "Spectral") – Color map to use when coloring by magnitude.

  • show (bool = True) – Whether to display the plot immediately.

  • windowed (bool = None) – Whether to display in an external window. If None (default), automatically detects environment (inline in notebooks, windowed otherwise). Set to True to force external window.

  • window_size (tuple = (800, 600)) – Size of the window (width, height) when creating new plotter.

  • **arrow_kwargs – Additional keyword arguments passed to plotter.add_mesh() for the arrow glyphs.

Returns:

The plotter object with arrows added. Returns None if show=True and plotter was auto-created.

Return type:

pyvista.Plotter

Raises:

DataError – If dataset doesn’t contain exactly 3 fields for vector components.