docstrings

Author: dbochkov-flexcompute

tidy3d/__init__.py

@@ -125,6 +125,10 @@
     HeatDataArray,
     IndexedDataArray,
     IndexedVoltageDataArray,
+    IndexedFieldDataArray, 
+    IndexedFieldTimeDataArray,
+    IndexedFreqDataArray,
+    IndexedTimeDataArray,
     ModeAmpsDataArray,
     ModeIndexDataArray,
     PointDataArray,
@@ -622,6 +626,10 @@ def set_logging_level(level: str) -> None:
     "CellDataArray",
     "IndexedDataArray",
     "IndexedVoltageDataArray",
+    "IndexedFieldDataArray", 
+    "IndexedFieldTimeDataArray",
+    "IndexedFreqDataArray",
+    "IndexedTimeDataArray",
     "SteadyVoltageDataArray",
     "TriangularGridDataset",
     "TetrahedralGridDataset",

tidy3d/components/data/data_array.py

@@ -1253,23 +1253,8 @@ class SpatialVoltageDataArray(AbstractSpatialDataArray):
     _dims = ("x", "y", "z", "voltage")
 
 
-class IndexedVectorDataArray(DataArray):
-    """Stores a mutlidimensional array enumerated by coordinates ``index`` and ``axis``. It is typically used
-    in conjuction with a ``PointDataArray`` to store point-associated vector data.
-
-    Example
-    -------
-    >>> indexed_array = IndexedFieldDataArray(
-    ...     (1+1j) * np.random.random((4,3)), coords=dict(index=np.arange(4), axis=np.arange(3))
-    ... )
-    """
-
-    __slots__ = ()
-    _dims = ("index", "axis")
-
-
 class IndexedFieldDataArray(DataArray):
-    """Stores a mutlidimensional array enumerated by coordinates ``index`` and ``axis``. It is typically used
+    """Stores indexed values of vector fields in frequency domain. It is typically used
     in conjuction with a ``PointDataArray`` to store point-associated vector data.
 
     Example
@@ -1284,7 +1269,7 @@ class IndexedFieldDataArray(DataArray):
 
 
 class IndexedFieldTimeDataArray(DataArray):
-    """Stores a mutlidimensional array enumerated by coordinates ``index`` and ``axis``. It is typically used
+    """Stores indexed values of vector fields in time domain. It is typically used
     in conjuction with a ``PointDataArray`` to store point-associated vector data.
 
     Example
@@ -1299,13 +1284,13 @@ class IndexedFieldTimeDataArray(DataArray):
 
 
 class IndexedFreqDataArray(DataArray):
-    """Stores a mutlidimensional array enumerated by coordinates ``index`` and ``axis``. It is typically used
+    """Stores indexed values of scalar fields in frequency domain. It is typically used
     in conjuction with a ``PointDataArray`` to store point-associated vector data.
 
     Example
     -------
     >>> indexed_array = IndexedFieldDataArray(
-    ...     (1+1j) * np.random.random((4,3,1)), coords=dict(index=np.arange(4), axis=np.arange(3), f=[1e9])
+    ...     (1+1j) * np.random.random((4,1)), coords=dict(index=np.arange(4), f=[1e9])
     ... )
     """
 
@@ -1314,13 +1299,13 @@ class IndexedFreqDataArray(DataArray):
 
 
 class IndexedTimeDataArray(DataArray):
-    """Stores a mutlidimensional array enumerated by coordinates ``index`` and ``axis``. It is typically used
+    """Stores indexed values of scalar fields in time domain. It is typically used
     in conjuction with a ``PointDataArray`` to store point-associated vector data.
 
     Example
     -------
     >>> indexed_array = IndexedFieldDataArray(
-    ...     (1+1j) * np.random.random((4,3,1)), coords=dict(index=np.arange(4), axis=np.arange(3), t=[0])
+    ...     (1+1j) * np.random.random((4,1)), coords=dict(index=np.arange(4), t=[0])
     ... )
     """
 
@@ -1361,7 +1346,6 @@ class IndexedTimeDataArray(DataArray):
     CellDataArray,
     IndexedDataArray,
     IndexedVoltageDataArray,
-    IndexedVectorDataArray,
     IndexedFieldDataArray,
     IndexedFieldTimeDataArray,
     IndexedFreqDataArray,
@@ -1372,9 +1356,9 @@ class IndexedTimeDataArray(DataArray):
 IndexedDataArrayTypes = Union[
     IndexedDataArray, 
     IndexedVoltageDataArray, 
-    IndexedVectorDataArray, 
     IndexedFieldDataArray, 
     IndexedFieldTimeDataArray,
     IndexedFreqDataArray,
     IndexedTimeDataArray,
+    PointDataArray,
 ]

tidy3d/components/data/dataset.py

@@ -314,7 +314,7 @@ def apply_phase(self, phase: float) -> AbstractFieldDataset:
 
 
 class ElectromagneticSurfaceFieldDataset(AbstractFieldDataset, ABC):
-    """Stores a collection of E, H and J fields with x, y, z components. The E is normal to the surface while H and J fields are tangential."""
+    """Stores a collection of E and H fields with x, y, z components."""
 
     E: Tuple[Optional[TriangularSurfaceDataset], Optional[TriangularSurfaceDataset]]  = pd.Field(
         (None, None),
@@ -360,7 +360,7 @@ def current_density(self) -> ElectromagneticSurfaceFieldDataset:
         if template is None:
             raise ValueError("Could not calculate current density: the dataset does not contain H field information.")
 
-        return template.updated_copy(np.cross(h_diff, self.normal.values, dim="axis"))
+        return template.updated_copy(xr.cross(h_diff, self.normal.values, dim="axis"))
 
     @property
     def grid_locations(self) -> Dict[str, str]:

tidy3d/components/data/monitor_data.py

@@ -94,8 +94,6 @@
     ModeSolverDataset,
     PermittivityDataset,
     ElectromagneticSurfaceFieldDataset,
-    # SurfaceFieldDataset,
-    # SurfaceFieldTimeDataset,
 )
 from .utils import TriangularSurfaceDataset
 
@@ -1335,7 +1333,7 @@ def time_reversed_copy(self) -> FieldTimeData:
 
 
 class AbstractSurfaceFieldData(MonitorData, AbstractFieldDataset, ABC):
-    """Collection of scalar fields with some symmetry properties."""
+    """Collection of vector fields on a surfacewith some symmetry properties."""
 
     monitor: Union[SurfaceFieldMonitor, SurfaceFieldTimeMonitor]
 
@@ -1356,14 +1354,14 @@ class AbstractSurfaceFieldData(MonitorData, AbstractFieldDataset, ABC):
 
     @property
     def symmetry_expanded(self):
-        """Return the :class:`.AbstractFieldData` with fields expanded based on symmetry. If
+        """Return the :class:`.AbstractSurfaceFieldData` with fields expanded based on symmetry. If
         any symmetry is nonzero (i.e. expanded), the interpolation implicitly creates a copy of the
         data array. However, if symmetry is not expanded, the returned array contains a view of
         the data, not a copy.
 
         Returns
         -------
-        :class:`AbstractFieldData`
+        :class:`AbstractSurfaceFieldData`
             A data object with the symmetry expanded fields.
         """
 
@@ -1374,11 +1372,11 @@ def symmetry_expanded(self):
 
     @property
     def symmetry_expanded_copy(self) -> AbstractFieldData:
-        """Create a copy of the :class:`.AbstractFieldData` with fields expanded based on symmetry.
+        """Create a copy of the :class:`.AbstractSurfaceFieldData` with fields expanded based on symmetry.
 
         Returns
         -------
-        :class:`AbstractFieldData`
+        :class:`AbstractSurfaceFieldData`
             A data object with the symmetry expanded fields.
         """
 
@@ -1395,7 +1393,7 @@ def _symmetry_update_dict(self) -> Dict:
 
 
 class ElectromagneticSurfaceFieldData(AbstractSurfaceFieldData, ElectromagneticSurfaceFieldDataset, ABC):
-    """Collection of electromagnetic fields."""
+    """Collection of electromagnetic fields on a surface."""
 
     @property
     def intensity(self) -> Tuple[TriangularSurfaceDataset, TriangularSurfaceDataset]:
@@ -1404,12 +1402,12 @@ def intensity(self) -> Tuple[TriangularSurfaceDataset, TriangularSurfaceDataset]
         for ind in range(2):
             if self.E[ind] is not None:
                 e_field = self.E[ind]
-                intensity[ind] = e_field.updated_copy(values=sum(e_field.values.sel(axis=axis) ** 2 for axis in range(3)))
+                intensity[ind] = e_field.norm(dim="axis") ** 2
         return intensity
 
     @property
     def poynting(self) -> Tuple[TriangularSurfaceDataset, TriangularSurfaceDataset]:
-        """Time-averaged Poynting vector for frequency-domain data associated to a surface monitor."""
+        """Time-averaged Poynting vector for frequency-domain data."""
 
         poynting = [None, None]
         for ind in range(2):
@@ -1436,22 +1434,21 @@ def _check_fields_stored(self, components: list[str]):
 
 class SurfaceFieldData(ElectromagneticSurfaceFieldData):
     """
-    Data associated with a :class:`.SurfaceFieldMonitor`: scalar components of E and H fields.
+    Data associated with a :class:`.SurfaceFieldMonitor`: E and H fields on a surface.
 
     Example
     -------
-    >>> from tidy3d import ScalarFieldDataArray
-    >>> x = [-1,1,3]
-    >>> y = [-2,0,2,4]
-    >>> z = [-3,-1,1,3,5]
-    >>> f = [2e14, 3e14]
-    >>> coords = dict(x=x[:-1], y=y[:-1], z=z[:-1], f=f)
-    >>> grid = Grid(boundaries=Coords(x=x, y=y, z=z))
-    >>> scalar_field = ScalarFieldDataArray((1+1j) * np.random.random((2,3,4,2)), coords=coords)
-    >>> monitor = FieldMonitor(
-    ...     size=(2,4,6), freqs=[2e14, 3e14], name='field', fields=['Ex', 'Hz'], colocate=True
+    >>> from tidy3d import PointDataArray, IndexedFieldDataArray, TriangularSurfaceDataset, CellDataArray
+    >>> points = PointDataArray([[0, 0, 0], [0, 1, 0], [1, 1, 1]], dims=["index", "axis"])
+    >>> cells = CellDataArray([[0, 1, 2]], dims=["cell_index", "vertex_index"])
+    >>> values = PointDataArray([[1, 0, 0], [0, 1, 0], [0, 0, 1]], dims=["index", "axis"])
+    >>> field_values = IndexedFieldDataArray(np.ones((3, 3, 1)) + 0j, coords={"index": [0, 1, 2], "axis": [0, 1, 2], "f": [1e10]})
+    >>> field = TriangularSurfaceDataset(points=points, cells=cells, values=field_values)
+    >>> normal = TriangularSurfaceDataset(points=points, cells=cells, values=values)
+    >>> monitor = SurfaceFieldMonitor(
+    ...     size=(2,4,6), freqs=[1e10], name='field', fields=['E', 'H']
     ... )
-    >>> data = FieldData(monitor=monitor, Ex=scalar_field, Hz=scalar_field, grid_expanded=grid)
+    >>> data = SurfaceFieldData(monitor=monitor, E=[None, field], H=[None, field], normal=normal)
 
     """
 
@@ -1463,11 +1460,14 @@ class SurfaceFieldData(ElectromagneticSurfaceFieldData):
 
     def normalize(self, source_spectrum_fn: Callable[[float], complex]) -> FieldDataset:
         """Return copy of self after normalization is applied using source spectrum function."""
-        return self
         fields_norm = {}
         for field_name, field_data in self.field_components.items():
-            src_amps = source_spectrum_fn(field_data.f)
-            fields_norm[field_name] = (field_data / src_amps).astype(field_data.dtype)
+            fields_norm[field_name] = [None, None]
+            for ind in range(2):
+                src_amps = source_spectrum_fn(field_data[ind].values.f)
+                fields_norm[field_name][ind] = field_data[ind].updated_copy(
+                    values=(field_data[ind].values / src_amps).astype(field_data[ind].values.dtype)
+                )
 
         return self.copy(update=fields_norm)
 
@@ -1477,18 +1477,17 @@ class SurfaceFieldTimeData(ElectromagneticSurfaceFieldData):
 
     Example
     -------
-    >>> from tidy3d import ScalarFieldTimeDataArray
-    >>> x = [-1,1,3]
-    >>> y = [-2,0,2,4]
-    >>> z = [-3,-1,1,3,5]
-    >>> t = [0, 1e-12, 2e-12]
-    >>> coords = dict(x=x[:-1], y=y[:-1], z=z[:-1], t=t)
-    >>> grid = Grid(boundaries=Coords(x=x, y=y, z=z))
-    >>> scalar_field = ScalarFieldTimeDataArray(np.random.random((2,3,4,3)), coords=coords)
-    >>> monitor = FieldTimeMonitor(
-    ...     size=(2,4,6), interval=100, name='field', fields=['Ex', 'Hz'], colocate=True
+    >>> from tidy3d import PointDataArray, IndexedFieldDataArray, TriangularSurfaceDataset, CellDataArray
+    >>> points = PointDataArray([[0, 0, 0], [0, 1, 0], [1, 1, 1]], dims=["index", "axis"])
+    >>> cells = CellDataArray([[0, 1, 2]], dims=["cell_index", "vertex_index"])
+    >>> values = PointDataArray([[1, 0, 0], [0, 1, 0], [0, 0, 1]], dims=["index", "axis"])
+    >>> field_values = IndexedFieldDataArray(np.ones((3, 3, 1)) + 0j, coords={"index": [0, 1, 2], "axis": [0, 1, 2], "f": [1e10]})
+    >>> field = TriangularSurfaceDataset(points=points, cells=cells, values=field_values)
+    >>> normal = TriangularSurfaceDataset(points=points, cells=cells, values=values)
+    >>> monitor = SurfaceFieldTimeMonitor(
+    ...     size=(2,4,6), interval=100, name='field', fields=['E', 'H']
     ... )
-    >>> data = FieldTimeData(monitor=monitor, Ex=scalar_field, Hz=scalar_field, grid_expanded=grid)
+    >>> data = SurfaceFieldTimeData(monitor=monitor, E=[None, field], H=[None, field], normal=normal)
     """
 
     monitor: SurfaceFieldTimeMonitor = pd.Field(
@@ -1499,16 +1498,20 @@ class SurfaceFieldTimeData(ElectromagneticSurfaceFieldData):
 
     @property
     def poynting(self) -> ScalarFieldTimeDataArray:
-        """Instantaneous Poynting vector for time-domain data associated to a 2D monitor, projected
-        to the direction normal to the monitor plane."""
+        """Instantaneous Poynting vector for time-domain data."""
 
-        # TODO: fix this 
-        # # Tangential fields are ordered as E1, E2, H1, H2
-        # tan_fields = self._colocated_tangential_fields
-        # dim1, dim2 = self._tangential_dims
-        # e_x_h = np.real(tan_fields["E" + dim1]) * np.real(tan_fields["H" + dim2])
-        # e_x_h -= np.real(tan_fields["E" + dim2]) * np.real(tan_fields["H" + dim1])
-        # return e_x_h
+        poynting = [None, None]
+        for ind in range(2):
+            if self.E[ind] is not None and self.H[ind] is not None:
+
+                e_field = self.E[ind]
+                h_field = self.H[ind]
+
+                poynting[ind] = e_field.updated_copy(
+                    values=np.real(xr.cross(e_field.values.real, h_field.values.real, dim="axis"))
+                )
+
+        return poynting
 
 
 class PermittivityData(PermittivityDataset, AbstractFieldData):