add doctests

Author: dmarek-flex

tests/test_components/test_geometry.py

@@ -1202,10 +1202,10 @@ def test_snap_box_to_grid_strict_behaviors():
     expanded_box = snap_box_to_grid(grid, box_coincident, snap_spec_strict_expand)
 
     # StrictExpand should move bounds outwards even when already on grid
-    assert expanded_box.bounds[0][0] < 0.1  # Left bound moved left from 0.1
-    assert expanded_box.bounds[1][0] > 0.1  # Right bound moved right from 0.1
-    assert expanded_box.bounds[0][1] < 0.2  # Bottom bound moved down from 0.2
-    assert expanded_box.bounds[1][1] > 0.2  # Top bound moved up from 0.2
+    assert np.isclose(expanded_box.bounds[0][0], 0.0)  # Left bound moved left from 0.1
+    assert np.isclose(expanded_box.bounds[1][0], 0.2)  # Right bound moved right from 0.1
+    assert np.isclose(expanded_box.bounds[0][1], 0.1)  # Bottom bound moved down from 0.2
+    assert np.isclose(expanded_box.bounds[1][1], 0.3)  # Top bound moved up from 0.2
 
     # Test StrictContract: should always move endpoints inwards, even if coincident
     box_large = td.Box(center=(0.5, 0.5, 0.5), size=(0.4, 0.4, 0.4))  # Spans multiple grid cells

tidy3d/components/data/monitor_data.py

@@ -1655,7 +1655,7 @@ class ModeData(ModeSolverDataset, ElectromagneticFieldData):
         None,
         title="Microwave Mode Dataset",
         description="Additional data relevant to RF and microwave applications, like characteristic impedance. "
-        "This field is populated when a :class:`MicrowaveModeSpec` has been provided to the :class:`ModeSpec`.",
+        "This field is populated when a :class:`MicrowaveModeSpec` has been used to set up the monitor or mode solver.",
     )
 
     @pd.validator("eps_spec", always=True)

tidy3d/components/microwave/data/dataset.py

@@ -1,6 +1,4 @@
-"""Post-processing data and figures of merit for antennas, including radiation efficiency,
-reflection efficiency, gain, and realized gain.
-"""
+"""Dataset for microwave and RF transmission line mode data, including impedance, voltage, and current coefficients."""
 
 from __future__ import annotations
 
@@ -24,7 +22,7 @@ class MicrowaveModeDataset(Dataset):
         title="Characteristic Impedance",
         description="Optional quantity calculated for transmission lines. "
         "The characteristic impedance is only calculated when a :class:`MicrowaveModeSpec` "
-        "is provided to the :class:`ModeSpec` associated with this data.",
+        "is provided to the :class:`ModeMonitor` or mode solver.",
     )
 
     voltage_coeffs: Optional[VoltageFreqModeDataArray] = pd.Field(
@@ -33,7 +31,7 @@ class MicrowaveModeDataset(Dataset):
         description="Optional quantity calculated for transmission lines, which associates "
         "a voltage-like quantity with each mode profile that scales linearly with the "
         "complex-valued mode amplitude. The mode voltages are only calculated when a :class:`MicrowaveModeSpec` "
-        "is provided to the :class:`ModeSpec` associated with this data.",
+        "is provided to the :class:`ModeMonitor` or mode solver.",
     )
 
     current_coeffs: Optional[CurrentFreqModeDataArray] = pd.Field(
@@ -42,5 +40,5 @@ class MicrowaveModeDataset(Dataset):
         description="Optional quantity calculated for transmission lines, which associates "
         "a current-like quantity with each mode profile that scales linearly with the "
         "complex-valued mode amplitude. The mode currents are only calculated when a :class:`MicrowaveModeSpec`"
-        " is provided to the :class:`ModeSpec` associated with this data.",
+        " is provided to the :class:`ModeMonitor` or mode solver.",
     )

tidy3d/components/microwave/microwave_mode_spec.py

@@ -26,7 +26,10 @@ class MicrowaveModeSpec(ModeSpec):
     impedance_specs: tuple[Optional[annotate_type(ImpedanceSpecTypes)], ...] = pd.Field(
         ...,
         title="Impedance Specifications",
-        description="Field controls how the impedance is calculated for each mode calculated by the mode solver.",
+        description="Field controls how the impedance is calculated for each mode calculated by the mode solver. "
+        "The number of impedance specifications should match the number of modes field. "
+        "When an impedance specification of ``None`` is used, the impedance calculation will be "
+        "ignored for the associated mode.",
     )
 
     @cached_property

tidy3d/components/microwave/path_integrals/base_spec.py

@@ -63,7 +63,16 @@ def _warn_rf_license(cls, values):
 
 
 class AxisAlignedPathIntegralSpec(AbstractAxesRH, Box):
-    """Class for defining the simplest type of path integral, which is aligned with Cartesian axes."""
+    """Class for defining the simplest type of path integral, which is aligned with Cartesian axes.
+
+    Example
+    -------
+    >>> path_spec = AxisAlignedPathIntegralSpec(  # doctest: +SKIP
+    ...     center=(0, 0, 1),
+    ...     size=(0, 0, 2),
+    ...     extrapolate_to_endpoints=True
+    ... )
+    """
 
     _line_validator = assert_line()
 
@@ -104,6 +113,16 @@ def _vertices_2D(self, axis: Axis) -> tuple[Coordinate2D, Coordinate2D]:
 class Custom2DPathIntegralSpec(AbstractAxesRH):
     """Class for specifying a custom path integral defined as a curve on an axis-aligned plane.
 
+    Example
+    -------
+    >>> import numpy as np
+    >>> vertices = np.array([[0, 0], [1, 0], [1, 1], [0, 1]])
+    >>> path_spec = Custom2DPathIntegralSpec(  # doctest: +SKIP
+    ...     axis=2,
+    ...     position=0.5,
+    ...     vertices=vertices
+    ... )
+
     Notes
     -----
 
@@ -116,7 +135,7 @@ class Custom2DPathIntegralSpec(AbstractAxesRH):
     """
 
     axis: Axis = pd.Field(
-        2, title="Axis", description="Specifies dimension of the planar axis (0,1,2) -> (x,y,z)."
+        ..., title="Axis", description="Specifies dimension of the planar axis (0,1,2) -> (x,y,z)."
     )
 
     position: float = pd.Field(

tidy3d/components/microwave/path_integrals/current_spec.py

@@ -24,7 +24,17 @@
 
 
 class AxisAlignedCurrentIntegralSpec(AbstractAxesRH, Box):
-    """Class for specifying the computation of conduction current via Ampère's circuital law on an axis-aligned loop."""
+    """Class for specifying the computation of conduction current via Ampère's circuital law on an axis-aligned loop.
+
+    Example
+    -------
+    >>> current_spec = AxisAlignedCurrentIntegralSpec(  # doctest: +SKIP
+    ...     center=(0, 0, 0),
+    ...     size=(1, 1, 0),
+    ...     sign="+",
+    ...     snap_contour_to_grid=True
+    ... )
+    """
 
     _plane_validator = assert_plane()
 
@@ -215,7 +225,18 @@ def plot(
 class Custom2DCurrentIntegralSpec(Custom2DPathIntegralSpec):
     """Class for specifying the computation of conduction current via Ampère's circuital law on a custom path.
     To compute the current flowing in the positive ``axis`` direction, the vertices should be
-    ordered in a counterclockwise direction."""
+    ordered in a counterclockwise direction.
+
+    Example
+    -------
+    >>> import numpy as np
+    >>> vertices = np.array([[0, 0], [2, 0], [2, 1], [0, 1], [0, 0]])
+    >>> current_spec = Custom2DCurrentIntegralSpec(  # doctest: +SKIP
+    ...     axis=2,
+    ...     position=0,
+    ...     vertices=vertices
+    ... )
+    """
 
     @add_ax_if_none
     def plot(
@@ -273,6 +294,19 @@ class CompositeCurrentIntegralSpec(Tidy3dBaseModel):
 
     This class is used to set up a ``CompositeCurrentIntegral``, which combines
     multiple current integrals. It does not perform any integration itself.
+
+    Example
+    -------
+    >>> spec1 = AxisAlignedCurrentIntegralSpec(  # doctest: +SKIP
+    ...     center=(0, 0, 0), size=(1, 1, 0), sign="+"
+    ... )
+    >>> spec2 = AxisAlignedCurrentIntegralSpec(  # doctest: +SKIP
+    ...     center=(2, 0, 0), size=(1, 1, 0), sign="+"
+    ... )
+    >>> composite_spec = CompositeCurrentIntegralSpec(  # doctest: +SKIP
+    ...     path_specs=(spec1, spec2),
+    ...     sum_spec="sum"
+    ... )
     """
 
     path_specs: tuple[Union[AxisAlignedCurrentIntegralSpec, Custom2DCurrentIntegralSpec], ...] = (

tidy3d/components/microwave/path_integrals/impedance_spec.py

@@ -32,22 +32,33 @@ class CustomImpedanceSpec(Tidy3dBaseModel):
 
     Users must supply at least one of voltage or current path specifications to control where these integrals
     are evaluated. Both voltage_spec and current_spec cannot be ``None`` simultaneously.
+
+    Example
+    -------
+    >>> from tidy3d.components.microwave.path_integrals.voltage_spec import AxisAlignedVoltageIntegralSpec
+    >>> from tidy3d.components.microwave.path_integrals.current_spec import AxisAlignedCurrentIntegralSpec
+    >>> voltage_spec = AxisAlignedVoltageIntegralSpec(  # doctest: +SKIP
+    ...     center=(0, 0, 0), size=(0, 0, 1), sign="+"
+    ... )
+    >>> current_spec = AxisAlignedCurrentIntegralSpec(  # doctest: +SKIP
+    ...     center=(0, 0, 0), size=(2, 1, 0), sign="+"
+    ... )
+    >>> impedance_spec = CustomImpedanceSpec(  # doctest: +SKIP
+    ...     voltage_spec=voltage_spec,
+    ...     current_spec=current_spec
+    ... )
     """
 
     voltage_spec: Optional[VoltagePathSpecTypes] = pd.Field(
         None,
         title="Voltage Integration Path",
-        description="Path specification for computing the voltage associated with each mode. "
-        "The number of path specifications should equal the 'num_modes' field "
-        "in the 'ModeSpec'.",
+        description="Path specification for computing the voltage associated with a mode profile.",
     )
 
     current_spec: Optional[CurrentPathSpecTypes] = pd.Field(
         None,
         title="Current Integration Path",
-        description="Path specification for computing the current associated with each mode. "
-        "The number of path specifications should equal the 'num_modes' field "
-        "in the 'ModeSpec'.",
+        description="Path specification for computing the current associated with a mode profile.",
     )
 
     @pd.validator("current_spec", always=True)

tidy3d/components/microwave/path_integrals/types.py

@@ -1,3 +1,5 @@
+"""Common type definitions for path integral specifications."""
+
 from __future__ import annotations
 
 from typing import Union