Unsteady heat support

Heat capacity is now not a required parameter unless we run unsteady heat

Author: marc-flex

tests/test_components/test_heat.py

@@ -56,6 +56,13 @@ def test_heat_medium():
     with pytest.raises(pd.ValidationError):
         _ = solid_medium.heat_spec.updated_copy(conductivity=-1)
 
+    # check we can create solid medium from  SI units
+    _ = td.SolidSpec.from_si_units(
+        conductivity=1,
+        capacity=1,
+        density=1,
+    )
+
 
 def make_heat_structures():
     fluid_medium, solid_medium = make_heat_mediums()

tests/test_components/test_heat_charge.py

@@ -1603,3 +1603,71 @@ def test_symmetry_capacitance(symmetry):
         assert (
             mnt_data.symmetry_expanded_copy.electron_capacitance.data[n] == data[n] * scaling_factor
         )
+
+
+def test_unsteady_parameters():
+    """Test that unsteady parameters are set correctly."""
+
+    _ = td.UnsteadyHeatAnalysis(
+        initial_temperature=300,
+        unsteady_spec=td.UnsteadySpec(time_step=0.1, total_time_steps=1),
+    )
+
+    # test non-positive initial temperature raises error
+    with pytest.raises(pd.ValidationError):
+        _ = td.UnsteadyHeatAnalysis(
+            initial_temperature=0,
+            unsteady_spec=td.UnsteadySpec(time_step=0.1, total_time_steps=1),
+        )
+
+    # test negative time step raises error
+    with pytest.raises(pd.ValidationError):
+        _ = td.UnsteadyHeatAnalysis(
+            initial_temperature=10,
+            unsteady_spec=td.UnsteadySpec(time_step=-0.1, total_time_steps=1),
+        )
+
+    # test negative total time steps raises error
+    with pytest.raises(pd.ValidationError):
+        _ = td.UnsteadyHeatAnalysis(
+            initial_temperature=10,
+            unsteady_spec=td.UnsteadySpec(time_step=0.1, total_time_steps=-1),
+        )
+
+
+def test_unsteady_heat_analysis(heat_simulation):
+    """Test that the validators for unsteady heat analysis are working."""
+
+    unsteady_analysis_spec = td.UnsteadyHeatAnalysis(
+        initial_temperature=300,
+        unsteady_spec=td.UnsteadySpec(time_step=0.1, total_time_steps=1),
+    )
+
+    temp_mnt = td.TemperatureMonitor(
+        center=(0, 0, 0),
+        size=(td.inf, td.inf, td.inf),
+        name="temperature",
+        unstructured=True,
+        interval=2,
+    )
+
+    # this should work since the monitor is unstructured
+    unsteady_sim = heat_simulation.updated_copy(
+        analysis_spec=unsteady_analysis_spec, monitors=[temp_mnt]
+    )
+
+    with pytest.raises(pd.ValidationError):
+        temp_mnt = temp_mnt.updated_copy(unstructured=False)
+        _ = unsteady_sim.updated_copy(monitors=[temp_mnt])
+
+    with pytest.raises(pd.ValidationError):
+        temp_mnt = temp_mnt.updated_copy(unstructured=True, interval=0)
+        _ = unsteady_sim.updated_copy(monitors=[temp_mnt])
+
+    # try simulation with excessive time steps
+    with pytest.raises(pd.ValidationError):
+        mew_spex = td.UnsteadyHeatAnalysis(
+            initial_temperature=300,
+            unsteady_spec=td.UnsteadySpec(time_step=0.1, total_time_steps=100000),
+        )
+        _ = unsteady_sim.updated_copy(analysis_spec=mew_spex)

tests/test_data/test_datasets.py

@@ -10,7 +10,7 @@
 np.random.seed(4)
 
 
-@pytest.mark.parametrize("dataset_type_ind", [0, 1])
+@pytest.mark.parametrize("dataset_type_ind", [0, 1, 2])
 @pytest.mark.parametrize("ds_name", ["test123", None])
 def test_triangular_dataset(tmp_path, ds_name, dataset_type_ind, no_vtk=False):
     import tidy3d as td
@@ -26,6 +26,11 @@ def test_triangular_dataset(tmp_path, ds_name, dataset_type_ind, no_vtk=False):
         values_type = td.IndexedVoltageDataArray
         extra_dims = {"voltage": [0, 1, 2]}
 
+    if dataset_type_ind == 2:
+        dataset_type = td.TriangularGridDataset
+        values_type = td.IndexedTimeDataArray
+        extra_dims = {"t": [0, 1, 2]}
+
     # basic create
     tri_grid_points = td.PointDataArray(
         [[0.0, 0.0], [1.0, 0.0], [0.0, 1.0], [1.0, 1.0]],
@@ -322,7 +327,7 @@ def operation(arr):
     assert result.name == ds_name
 
 
-@pytest.mark.parametrize("dataset_type_ind", [0, 1])
+@pytest.mark.parametrize("dataset_type_ind", [0, 1, 2])
 @pytest.mark.parametrize("ds_name", ["test123", None])
 def test_tetrahedral_dataset(tmp_path, ds_name, dataset_type_ind, no_vtk=False):
     import tidy3d as td
@@ -338,6 +343,11 @@ def test_tetrahedral_dataset(tmp_path, ds_name, dataset_type_ind, no_vtk=False):
         values_type = td.IndexedVoltageDataArray
         extra_dims = {"voltage": [0, 1, 2]}
 
+    if dataset_type_ind == 2:
+        dataset_type = td.TetrahedralGridDataset
+        values_type = td.IndexedTimeDataArray
+        extra_dims = {"t": [0, 1, 2]}
+
     # basic create
     tet_grid_points = td.PointDataArray(
         [

tidy3d/__init__.py

@@ -21,6 +21,7 @@
 )
 from tidy3d.components.spice.sources.dc import DCCurrentSource, DCVoltageSource
 from tidy3d.components.spice.sources.types import VoltageSourceType
+from tidy3d.components.tcad.analysis.heat_simulation_type import UnsteadyHeatAnalysis, UnsteadySpec
 from tidy3d.components.tcad.boundary.specification import (
     HeatBoundarySpec,
     HeatChargeBoundarySpec,
@@ -131,6 +132,7 @@
     FluxTimeDataArray,
     HeatDataArray,
     IndexedDataArray,
+    IndexedTimeDataArray,
     IndexedVoltageDataArray,
     ModeAmpsDataArray,
     ModeIndexDataArray,
@@ -603,6 +605,8 @@ def set_logging_level(level: str) -> None:
     "UniformHeatSource",
     "HeatSource",
     "HeatFromElectricSource",
+    "UnsteadyHeatAnalysis",
+    "UnsteadySpec",
     "UniformUnstructuredGrid",
     "DistanceUnstructuredGrid",
     "GridRefinementRegion",
@@ -635,6 +639,7 @@ def set_logging_level(level: str) -> None:
     "PointDataArray",
     "CellDataArray",
     "IndexedDataArray",
+    "IndexedTimeDataArray",
     "IndexedVoltageDataArray",
     "SteadyVoltageDataArray",
     "TriangularGridDataset",

tidy3d/components/data/data_array.py

@@ -1248,6 +1248,22 @@ class IndexedVoltageDataArray(DataArray):
     _dims = ("index", "voltage")
 
 
+class IndexedTimeDataArray(DataArray):
+    """Stores a two-dimensional array with coordinates ``index`` and ``t``, where
+    ``index`` is usually associated with ``PointDataArray`` and ``t`` indicates at what
+    simulated time the data was obtained.
+
+    Example
+    -------
+    >>> indexed_array = IndexedTimeDataArray(
+    ...     (1+1j) * np.random.random((3,2)), coords=dict(index=np.arange(3), t=[0, 1])
+    ... )
+    """
+
+    __slots__ = ()
+    _dims = ("index", "t")
+
+
 class SpatialVoltageDataArray(AbstractSpatialDataArray):
     """Spatial distribution with voltage mapping.
 
@@ -1305,7 +1321,8 @@ class PerturbationCoefficientDataArray(DataArray):
     IndexedVoltageDataArray,
     SpatialVoltageDataArray,
     PerturbationCoefficientDataArray,
+    IndexedTimeDataArray,
 ]
 DATA_ARRAY_MAP = {data_array.__name__: data_array for data_array in DATA_ARRAY_TYPES}
 
-IndexedDataArrayTypes = Union[IndexedDataArray, IndexedVoltageDataArray]
+IndexedDataArrayTypes = Union[IndexedDataArray, IndexedVoltageDataArray, IndexedTimeDataArray]

tidy3d/components/material/tcad/heat.py

@@ -9,6 +9,7 @@
 
 from tidy3d.components.base import Tidy3dBaseModel
 from tidy3d.constants import (
+    DENSITY,
     SPECIFIC_HEAT_CAPACITY,
     THERMAL_CONDUCTIVITY,
 )
@@ -69,8 +70,9 @@ class SolidMedium(AbstractHeatMedium):
     """
 
     capacity: pd.PositiveFloat = pd.Field(
+        None,
         title="Heat capacity",
-        description=f"Volumetric heat capacity in unit of {SPECIFIC_HEAT_CAPACITY}.",
+        description=f"Specific heat capacity in unit of {SPECIFIC_HEAT_CAPACITY}.",
         units=SPECIFIC_HEAT_CAPACITY,
     )
 
@@ -80,6 +82,32 @@ class SolidMedium(AbstractHeatMedium):
         units=THERMAL_CONDUCTIVITY,
     )
 
+    density: pd.PositiveFloat = pd.Field(
+        None,
+        title="Density",
+        description=f"Mass density of material in units of {DENSITY}.",
+        units=DENSITY,
+    )
+
+    def from_si_units(
+        conductivity: pd.PositiveFloat,
+        capacity: pd.PositiveFloat = None,
+        density: pd.PositiveFloat = None,
+    ):
+        """Create a SolidMedium using SI units"""
+        new_conductivity = conductivity * 1e-6  # Convert from W/(m*K) to W/(um*K)
+        new_capacity = capacity
+        new_density = density
+
+        if density is not None:
+            new_density = density * 1e-18
+
+        return SolidMedium(
+            capacity=new_capacity,
+            conductivity=new_conductivity,
+            density=new_density,
+        )
+
 
 class SolidSpec(SolidMedium):
     """Solid medium class for backwards compatibility"""

tidy3d/components/tcad/analysis/__init__.py

@@ -0,0 +1,62 @@
+"""Dealing with time specifications for DeviceSimulation"""
+
+import pydantic.v1 as pd
+
+from ....constants import KELVIN, SECOND
+from ...base import Tidy3dBaseModel
+
+
+class UnsteadySpec(Tidy3dBaseModel):
+    """Defines an unsteady specification
+
+    Example
+    --------
+    >>> import tidy3d as td
+    >>> time_spec = td.UnsteadySpec(
+    ...     time_step=0.01,
+    ...     total_time_steps=200,
+    ... )
+    """
+
+    time_step: pd.PositiveFloat = pd.Field(
+        ...,
+        title="Time-step",
+        description="Time step taken for each iteration of the time integration loop.",
+        units=SECOND,
+    )
+
+    total_time_steps: pd.PositiveInt = pd.Field(
+        ...,
+        title="Total time steps",
+        description="Specifies the total number of time steps run during the simulation.",
+    )
+
+
+class UnsteadyHeatAnalysis(Tidy3dBaseModel):
+    """
+    Configures relevant unsteady-state heat simulation parameters.
+
+    Example
+    -------
+    >>> import tidy3d as td
+    >>> time_spec = td.UnsteadyHeatAnalysis(
+    ...     initial_temperature=300,
+    ...     unsteady_spec=td.UnsteadySpec(
+    ...         time_step=0.01,
+    ...         total_time_steps=200,
+    ...     ),
+    ... )
+    """
+
+    initial_temperature: pd.PositiveFloat = pd.Field(
+        ...,
+        title="Initial temperature.",
+        description="Initial value for the temperature field.",
+        units=KELVIN,
+    )
+
+    unsteady_spec: UnsteadySpec = pd.Field(
+        ...,
+        title="Unsteady specification",
+        description="Time step and total time steps for the unsteady simulation.",
+    )

tidy3d/components/tcad/analysis/heat_simulation_type.py

@@ -9,7 +9,7 @@
 from tidy3d.components.base import skip_if_fields_missing
 from tidy3d.components.data.data_array import (
     DataArray,
-    IndexedDataArray,
+    ScalarFieldTimeDataArray,
     SpatialDataArray,
 )
 from tidy3d.components.data.utils import TetrahedralGridDataset, TriangularGridDataset
@@ -22,7 +22,9 @@
 from tidy3d.log import log
 
 FieldDataset = Union[
-    SpatialDataArray, annotate_type(Union[TriangularGridDataset, TetrahedralGridDataset])
+    SpatialDataArray,
+    ScalarFieldTimeDataArray,
+    annotate_type(Union[TriangularGridDataset, TetrahedralGridDataset]),
 ]
 UnstructuredFieldType = Union[TriangularGridDataset, TetrahedralGridDataset]
 
@@ -75,22 +77,6 @@ def warn_no_data(cls, val, values):
 
         return val
 
-    @pd.validator("temperature", always=True)
-    @skip_if_fields_missing(["monitor"])
-    def check_correct_data_type(cls, val, values):
-        """Issue error if incorrect data type is used"""
-
-        mnt = values.get("monitor")
-
-        if isinstance(val, TetrahedralGridDataset) or isinstance(val, TriangularGridDataset):
-            if not isinstance(val.values, IndexedDataArray):
-                raise ValueError(
-                    f"Monitor {mnt} of type 'TemperatureMonitor' cannot be associated with data arrays "
-                    "of type 'IndexVoltageDataArray'."
-                )
-
-        return val
-
     def field_name(self, val: str = "") -> str:
         """Gets the name of the fields to be plot."""
         if val == "abs^2":

tidy3d/components/tcad/data/monitor_data/heat.py

@@ -1,7 +1,19 @@
 """Objects that define how data is recorded from simulation."""
 
+import pydantic.v1 as pd
+
 from tidy3d.components.tcad.monitors.abstract import HeatChargeMonitor
 
 
 class TemperatureMonitor(HeatChargeMonitor):
     """Temperature monitor."""
+
+    interval: pd.PositiveInt = pd.Field(
+        1,
+        title="Interval",
+        description="Sampling rate of the monitor: number of time steps between each measurement. "
+        "Set ``interval`` to 1 for the highest possible resolution in time. "
+        "Higher integer values down-sample the data by measuring every ``interval`` time steps. "
+        "This can be useful for reducing data storage as needed by the application."
+        "NOTE: this is only relevant for unsteady (transient) Heat simulations. ",
+    )