improving docstrings for Point-, Cell-, and IndexedDataArrays

CHANGELOG.md

@@ -24,6 +24,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Helpful error message if `val` supplied to `SimulationData.plot_field` not supported.
 - Fixed validator that warns if angled plane wave does not match simulation boundaries, which was not warning for periodic boundaries.
 - Validates that no nans are present in `DataArray` values in custom components.
+- Removed nans from Cartesian temperature monitors in thermal simulations by using nearest neighbor interpolation for values outside of heat simulation domain.
 
 ## [2.6.0rc1] - 2024-01-11
 

pyproject.toml

@@ -102,14 +102,16 @@ sax = {version="*", optional = true}
 vtk = {version="<=9.2.6", optional = true}
 pyswarms = {version="*", optional = true}
 sphinxemoji = {version="*", optional = true}
+devsim = {version="*", optional = true}
+cma = {version="*", optional = true}
 
 [tool.poetry.extras]
 dev = ['black', "coverage", 'dill', 'divparams', 'gdspy', 'gdstk', 'gdstk', 'grcwa', 'ipython', 'ipython', 'jax', 'jaxlib', 'jinja2',
   'jupyter', 'jupyterblack', 'myst-parser', 'memory_profiler', 'nbconvert', 'nbdime', 'nbsphinx', 'networkx', 'optax', 'pre-commit',
   'pydata-sphinx-theme', 'pylint', 'pyswarms', 'pytest', 'pytest-timeout', 'rtree', 'ruff', 'sax', 'signac', 'sphinx',
   'sphinx-book-theme', 'sphinx-copybutton', 'sphinx-sitemap', 'sphinx-tabs', 'sphinxemoji', 'tmm', 'tox', 'trimesh',
-    'vtk']
-docs = ["jupyter", "jinja2", "nbconvert", "sphinx", "nbsphinx", "ipython", "divparams", "sphinx-copybutton", "sphinx-book-theme", "pydata-sphinx-theme", "tmm", "gdstk", "grcwa", "sphinx-sitemap", "nbdime", "optax", "signac", "sax", "pylint", "jupyterblack", "sphinx-tabs", "sphinxemoji", "myst-parser"]
+    'vtk', 'devsim', 'cma']
+docs = ["jupyter", "jinja2", "nbconvert", "sphinx", "nbsphinx", "ipython", "divparams", "sphinx-copybutton", "sphinx-book-theme", "pydata-sphinx-theme", "tmm", "gdstk", "grcwa", "sphinx-sitemap", "nbdime", "optax", "signac", "sax", "pylint", "jupyterblack", "sphinx-tabs", "sphinxemoji", "myst-parser", "devsim", "cma"]
 gdspy = ["gdspy"]
 gdstk = ["gdstk"]
 jax = ["jaxlib", "jax"]

tidy3d/components/boundary.py

@@ -77,7 +77,7 @@ class BlochBoundary(BoundaryEdge):
 
     @cached_property
     def bloch_phase(self) -> Complex:
-        """Returns the forward phase factor associated with `bloch_vec`."""
+        """Returns the forward phase factor associated with ``bloch_vec``."""
         return np.exp(1j * 2.0 * np.pi * self.bloch_vec)
 
     @classmethod
@@ -118,13 +118,13 @@ def from_source(
 
         if not isinstance(source, BlochSourceType.__args__):
             raise SetupError(
-                "The `source` parameter must be `GaussianBeam`, `ModeSource`, `PlaneWave`, "
-                "or `TFSF` in order to define a Bloch boundary condition."
+                "The 'source' parameter must be 'GaussianBeam', 'ModeSource', 'PlaneWave', "
+                "or 'TFSF' in order to define a Bloch boundary condition."
             )
 
         if axis == source.injection_axis:
             raise SetupError(
-                "Bloch boundary axis must be orthogonal to the injection axis of `source`."
+                "Bloch boundary axis must be orthogonal to the injection axis of 'source'."
             )
 
         if medium is None:
@@ -768,23 +768,23 @@ class BoundarySpec(Tidy3dBaseModel):
         Boundary(),
         title="Boundary condition along x.",
         description="Boundary condition on the plus and minus sides along the x axis. "
-        "If `None`, periodic boundaries are applied. Default will change to PML in 2.0 "
+        "If ``None``, periodic boundaries are applied. Default will change to PML in 2.0 "
         "so explicitly setting the boundaries is recommended.",
     )
 
     y: Boundary = pd.Field(
         Boundary(),
         title="Boundary condition along y.",
         description="Boundary condition on the plus and minus sides along the y axis. "
-        "If `None`, periodic boundaries are applied. Default will change to PML in 2.0 "
+        "If ``None``, periodic boundaries are applied. Default will change to PML in 2.0 "
         "so explicitly setting the boundaries is recommended.",
     )
 
     z: Boundary = pd.Field(
         Boundary(),
         title="Boundary condition along z.",
         description="Boundary condition on the plus and minus sides along the z axis. "
-        "If `None`, periodic boundaries are applied. Default will change to PML in 2.0 "
+        "If ``None``, periodic boundaries are applied. Default will change to PML in 2.0 "
         "so explicitly setting the boundaries is recommended.",
     )
 

tidy3d/components/data/data_array.py

@@ -665,36 +665,52 @@ class ChargeDataArray(DataArray):
 
 
 class PointDataArray(DataArray):
-    """Indexed data array.
+    """A two-dimensional array that stores coordinates of a collection of points.
+    Dimension ``index`` denotes the index of a point in the collection, and dimension ``axis``
+    denotes the point's coordinate along that axis.
 
     Example
     -------
     >>> point_array = PointDataArray(
     ...     (1+1j) * np.random.random((5, 3)), coords=dict(index=np.arange(5), axis=np.arange(3)),
     ... )
+    >>> # get coordinates of a point number 3
+    >>> point3 = point_array.sel(index=3)
+    >>> # get x coordinates of all points
+    >>> x_coords = point_array.sel(axis=0)
     """
 
     __slots__ = ()
     _dims = ("index", "axis")
 
 
 class CellDataArray(DataArray):
-    """Cell connection data array.
+    """A two-dimensional array that stores indices of points composing each cell in a collection of
+    cells of the same type (for example: triangles, tetrahedra, etc). Dimension ``cell_index``
+    denotes the index of a cell in the collection, and dimension ``vertex_index`` denotes placement
+    (index) of a point in a cell (for example: 0, 1, or 2 for triangles; 0, 1, 2, or 3 for
+    tetrahedra).
 
     Example
     -------
     >>> cell_array = CellDataArray(
     ...     (1+1j) * np.random.random((4, 3)),
     ...     coords=dict(cell_index=np.arange(4), vertex_index=np.arange(3)),
     ... )
+    >>> # get indices of points composing cell number 3
+    >>> cell3 = cell_array.sel(cell_index=3)
+    >>> # get indices of points that represent the first vertex in each cell
+    >>> first_vertices = cell_array.sel(vertex_index=0)
     """
 
     __slots__ = ()
     _dims = ("cell_index", "vertex_index")
 
 
 class IndexedDataArray(DataArray):
-    """Indexed data array.
+    """Stores a one-dimensional array enumerated by coordinate ``index``. It is typically used
+    in conjuction with a ``PointDataArray`` to store point-associated data or a ``CellDataArray``
+    to store cell-associated data.
 
     Example
     -------

tidy3d/components/data/dataset.py

@@ -1268,14 +1268,14 @@ def plot(
         grid : bool = True
             Whether to plot the unstructured grid.
         cbar : bool = True
-            Display colorbar (only if `field == True`).
+            Display colorbar (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`, they are
+            The lower bound of data range that the colormap covers. If ``None``, they are
             inferred from the data and other keyword arguments.
         vmax : float = None
-            The upper bound of data range that the colormap covers. If `None`, they are
+            The upper bound of data range that the colormap covers. If ``None``, they are
             inferred from the data and other keyword arguments.
         shading : Literal["gourand", "flat"] = "gourand"
             Type of shading to use when plotting the data field.

tidy3d/components/data/sim_data.py

@@ -418,14 +418,14 @@ def mnt_data_from_file(cls, fname: str, mnt_name: str, **parse_obj_kwargs) -> Mo
         fname : str
             Full path to an hdf5 file containing :class:`.SimulationData` data.
         mnt_name : str, optional
-            `.name` of the monitor to load the data from.
+            ``.name`` of the monitor to load the data from.
         **parse_obj_kwargs
             Keyword arguments passed to either pydantic's ``parse_obj`` function when loading model.
 
         Returns
         -------
         :class:`MonitorData`
-            Monitor data corresponding to the `mnt_name` type.
+            Monitor data corresponding to the ``mnt_name`` type.
 
         Example
         -------
@@ -501,9 +501,9 @@ def plot_field(
             Name of :class:`.FieldMonitor`, :class:`.FieldTimeData`, or :class:`.ModeSolverData`
             to plot.
         field_name : str
-            Name of `field` component to plot (eg. `'Ex'`).
-            Also accepts `'E'` and `'H'` to plot the vector magnitudes of the electric and
-            magnetic fields, and `'S'` for the Poynting vector.
+            Name of ``field`` component to plot (eg. `'Ex'`).
+            Also accepts ``'E'`` and ``'H'`` to plot the vector magnitudes of the electric and
+            magnetic fields, and ``'S'`` for the Poynting vector.
         val : Literal['real', 'imag', 'abs', 'abs^2', 'phase'] = 'real'
             Which part of the field to plot.
         scale : Literal['lin', 'dB']
@@ -519,19 +519,19 @@ def plot_field(
             to compute the color limits. This helps in visualizing the field patterns especially
             in the presence of a source.
         vmin : float = None
-            The lower bound of data range that the colormap covers. If `None`, they are
+            The lower bound of data range that the colormap covers. If ``None``, they are
             inferred from the data and other keyword arguments.
         vmax : float = None
-            The upper bound of data range that the colormap covers. If `None`, they are
+            The upper bound of data range that the colormap covers. If ``None``, they are
             inferred from the data and other keyword arguments.
         ax : matplotlib.axes._subplots.Axes = None
             matplotlib axes to plot on, if not specified, one is created.
-        sel_kwargs : keyword arguments used to perform `.sel()` selection in the monitor data.
-            These kwargs can select over the spatial dimensions (`x`, `y`, `z`),
-            frequency or time dimensions (`f`, `t`) or `mode_index`, if applicable.
+        sel_kwargs : keyword arguments used to perform ``.sel()`` selection in the monitor data.
+            These kwargs can select over the spatial dimensions (``x``, ``y``, ``z``),
+            frequency or time dimensions (``f``, ``t``) or ``mode_index``, if applicable.
             For the plotting to work appropriately, the resulting data after selection must contain
             only two coordinates with len > 1.
-            Furthermore, these should be spatial coordinates (`x`, `y`, or `z`).
+            Furthermore, these should be spatial coordinates (``x``, ``y``, or ``z``).
 
         Returns
         -------

tidy3d/components/data/validators.py

@@ -51,8 +51,8 @@ def has_nans(values) -> bool:
                     raise ValidationError(
                         f"Found NaN values in '{field_name_display}'. "
                         "If they were not intended, please double check your construction. "
-                        "If intended, to replace these data points with a value `x`,"
-                        " call `values = np.nan_to_num(values, nan=x)`."
+                        "If intended, to replace these data points with a value 'x',"
+                        " call 'values = np.nan_to_num(values, nan=x)'."
                     )
 
         error_if_has_nans(val)

tidy3d/components/geometry/base.py

@@ -1786,9 +1786,9 @@ def surfaces_with_exclusion(cls, size: Size, center: Coordinate, **kwargs):
         denote which axis is perpendicular to that surface, while "-" and "+" denote the direction
         of the normal vector of that surface. If a name is provided, each output surface's name
         will be that of the provided name appended with the above symbols. E.g., if the provided
-        name is "box", the x+ surfaces's name will be "box_x+". If `kwargs` contains an
-        `exclude_surfaces` parameter, the returned list of surfaces will not include the excluded
-        surfaces. Otherwise, the behavior is identical to that of `surfaces()`.
+        name is "box", the x+ surfaces's name will be "box_x+". If ``kwargs`` contains an
+        ``exclude_surfaces`` parameter, the returned list of surfaces will not include the excluded
+        surfaces. Otherwise, the behavior is identical to that of ``surfaces()``.
 
         Parameters
         ----------
@@ -2036,7 +2036,7 @@ def _plot_arrow(
         bend_radius : float = None
             Radius of curvature for this arrow.
         bend_axis : Axis = None
-            Axis of curvature of `bend_radius`.
+            Axis of curvature of ``bend_radius``.
         both_dirs : bool = False
             If True, plots an arrow pointing in direction and one in -direction.
         arrow_base : :class:`.Coordinate` = None

tidy3d/components/geometry/utils.py

@@ -175,7 +175,7 @@ def vertices_from_shapely(shape: Shapely) -> ArrayFloat2D:
     Returns
     -------
     List[Tuple[ArrayFloat2D]]
-        List of tuples `(exterior, *interiors)`.
+        List of tuples ``(exterior, *interiors)``.
     """
     if shape.geom_type == "LinearRing":
         return [(shape.coords[:-1],)]

tidy3d/components/heat/data/sim_data.py

@@ -107,19 +107,19 @@ def plot_field(
             to compute the color limits. This helps in visualizing the field patterns especially
             in the presence of a source.
         vmin : float = None
-            The lower bound of data range that the colormap covers. If `None`, they are
+            The lower bound of data range that the colormap covers. If ``None``, they are
             inferred from the data and other keyword arguments.
         vmax : float = None
-            The upper bound of data range that the colormap covers. If `None`, they are
+            The upper bound of data range that the colormap covers. If ``None``, they are
             inferred from the data and other keyword arguments.
         ax : matplotlib.axes._subplots.Axes = None
             matplotlib axes to plot on, if not specified, one is created.
-        sel_kwargs : keyword arguments used to perform `.sel()` selection in the monitor data.
-            These kwargs can select over the spatial dimensions (`x`, `y`, `z`),
-            or time dimension (`t`) if applicable.
+        sel_kwargs : keyword arguments used to perform ``.sel()`` selection in the monitor data.
+            These kwargs can select over the spatial dimensions (``x``, ``y``, ``z``),
+            or time dimension (``t``) if applicable.
             For the plotting to work appropriately, the resulting data after selection must contain
             only two coordinates with len > 1.
-            Furthermore, these should be spatial coordinates (`x`, `y`, or `z`).
+            Furthermore, these should be spatial coordinates (``x``, ``y``, or ``z``).
 
         Returns
         -------
@@ -214,7 +214,7 @@ def plot_field(
                     f"Data after selection has {len(non_scalar_coords)} coordinates "
                     f"({list(non_scalar_coords.keys())}), "
                     "must be 2 spatial coordinates for plotting on plane. "
-                    "Please add keyword arguments to `plot_monitor_data()` to select out the other coords."
+                    "Please add keyword arguments to 'plot_monitor_data()' to select out the other coords."
                 )
 
             spatial_coords_in_data = {