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. Inline notebook plots start PyVista’s trame server during the plot call, including when show=False or a plotter is supplied.

  • 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. Inline notebook plots start PyVista’s trame server during the plot call, including when show=False or a plotter is supplied.

  • 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.