feat: warning for upcoming backward compatibility breaking unstructured=True (FXC-5123)

Author: dbochkov-flexcompute

CHANGELOG.md

@@ -18,6 +18,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 - `ModeSortSpec.sort_key` is now required with a default of `"n_eff"` (previously optional with `None` default). `ModeSortSpec.sort_order` is now optional with a default of `None`, which automatically selects the natural order based on `sort_key` and `sort_reference`: ascending when a reference is provided (closest first), otherwise descending for `n_eff` and polarization fractions (higher values first), ascending for `k_eff` and `mode_area` (lower values first).
+- Added deprecation warning for `TemperatureMonitor` and `SteadyPotentialMonitor` when `unstructured` parameter is not explicitly set. The default value of `unstructured` will change from `False` to `True` in the next release.
 
 ### Fixed
 - Fixed intermittent "API key not found" errors in parallel job launches by making configuration directory detection race-safe.

tests/test_components/test_heat_charge.py

@@ -232,7 +232,7 @@ def boundary_conditions():
 @pytest.fixture(scope="module")
 def monitors():
     """Creates monitors of different types and sizes."""
-    temp_mnt1 = td.TemperatureMonitor(size=(1.6, 2, 3), name="test")
+    temp_mnt1 = td.TemperatureMonitor(size=(1.6, 2, 3), name="test", unstructured=False)
     temp_mnt2 = td.TemperatureMonitor(size=(1.6, 2, 3), name="tet", unstructured=True)
     temp_mnt3 = td.TemperatureMonitor(
         center=(0, 0.9, 0), size=(1.6, 0, 3), name="tri", unstructured=True, conformal=True
@@ -241,7 +241,7 @@ def monitors():
         center=(0, 0.9, 0), size=(1.6, 0, 3), name="empty", unstructured=True, conformal=False
     )
 
-    volt_mnt1 = td.SteadyPotentialMonitor(size=(1.6, 2, 3), name="v_test")
+    volt_mnt1 = td.SteadyPotentialMonitor(size=(1.6, 2, 3), name="v_test", unstructured=False)
     volt_mnt2 = td.SteadyPotentialMonitor(size=(1.6, 2, 3), name="v_tet", unstructured=True)
     volt_mnt3 = td.SteadyPotentialMonitor(
         center=(0, 0.9, 0), size=(1.6, 0, 3), name="v_tri", unstructured=True, conformal=True
@@ -952,7 +952,7 @@ def test_freqs_validation():
     structures = [cathode, silicon, anode]
 
     volt_monitor = td.SteadyPotentialMonitor(
-        center=(0, 0, 0), size=(td.inf, td.inf, td.inf), name="voltage"
+        center=(0, 0, 0), size=(td.inf, td.inf, td.inf), name="voltage", unstructured=False
     )
 
     charge_tolerance = td.ChargeToleranceSpec(rel_tol=1e5, abs_tol=1e3, max_iters=400)
@@ -1137,6 +1137,42 @@ def test_vertical_natural_convection():
         )
 
 
+def test_unstructured_default_warning():
+    """Test that warning is issued when unstructured uses default (not explicitly set)."""
+    # Should warn: unstructured not set (defaults to False)
+    with AssertLogLevel("WARNING", contains_str="default value of 'unstructured'"):
+        td.TemperatureMonitor(size=(1, 1, 1), name="test1")
+
+    # Should NOT warn: unstructured explicitly set to False
+    with AssertLogLevel(None):
+        td.TemperatureMonitor(size=(1, 1, 1), name="test2", unstructured=False)
+
+    # Should NOT warn: unstructured explicitly set to True
+    with AssertLogLevel(None):
+        td.TemperatureMonitor(size=(1, 1, 1), name="test3", unstructured=True)
+
+    # Should warn: SteadyPotentialMonitor with default unstructured (not explicitly set)
+    with AssertLogLevel("WARNING", contains_str="default value of 'unstructured'"):
+        td.SteadyPotentialMonitor(size=(1, 1, 1), name="test4")
+
+    # Should NOT warn: SteadyPotentialMonitor with unstructured explicitly set to False
+    with AssertLogLevel(None):
+        td.SteadyPotentialMonitor(size=(1, 1, 1), name="test5", unstructured=False)
+
+    # Should NOT warn: SteadyPotentialMonitor with unstructured explicitly set to True
+    with AssertLogLevel(None):
+        td.SteadyPotentialMonitor(size=(1, 1, 1), name="test6", unstructured=True)
+
+    # Should NOT warn: monitors with unstructured: Literal[True] (always unstructured=True)
+    with AssertLogLevel(None):
+        td.SteadyFreeCarrierMonitor(size=(1, 1, 1), name="test7")
+        td.SteadyEnergyBandMonitor(size=(1, 1, 1), name="test8")
+        td.SteadyCapacitanceMonitor(size=(1, 1, 1), name="test9")
+        td.SteadyElectricFieldMonitor(size=(1, 1, 1), name="test10")
+        td.SteadyCurrentDensityMonitor(size=(1, 1, 1), name="test11")
+        td.VolumeMeshMonitor(size=(1, 1, 1), name="test12")
+
+
 def test_heat_charge_monitors_validation(monitors):
     """Checks for no name and negative size in monitors."""
     temp_mnt = monitors[0]
@@ -1164,7 +1200,7 @@ def test_monitor_crosses_medium(mediums, structures, heat_simulation, conduction
 
     # Voltage monitor
     volt_monitor = td.SteadyPotentialMonitor(
-        center=(0, 0, 0), size=(td.inf, td.inf, td.inf), name="voltage"
+        center=(0, 0, 0), size=(td.inf, td.inf, td.inf), name="voltage", unstructured=False
     )
     # A voltage monitor in a heat simulation should throw error if no ChargeConductorMedium is present
     with pytest.raises(pd.ValidationError):
@@ -1174,7 +1210,7 @@ def test_monitor_crosses_medium(mediums, structures, heat_simulation, conduction
 
     # Temperature monitor
     temp_monitor = td.TemperatureMonitor(
-        center=(0, 0, 0), size=(td.inf, td.inf, td.inf), name="temperature"
+        center=(0, 0, 0), size=(td.inf, td.inf, td.inf), name="temperature", unstructured=False
     )
     # A temperature monitor should throw error in a conduction simulation if no SolidSpec is present
     with pytest.raises(pd.ValidationError):
@@ -1184,7 +1220,9 @@ def test_monitor_crosses_medium(mediums, structures, heat_simulation, conduction
 
     # check error is raised in voltage monitor doesn't cross a conducting medium
     with pytest.raises(pd.ValidationError):
-        volt_mnt = td.SteadyPotentialMonitor(center=(0, 0, 0), size=(0, td.inf, td.inf))
+        volt_mnt = td.SteadyPotentialMonitor(
+            center=(0, 0, 0), size=(0, td.inf, td.inf), unstructured=False
+        )
         _ = conduction_simulation.updated_copy(monitors=[volt_mnt])
 
 
@@ -1365,7 +1403,7 @@ def test_sim_data_plotting(simulation_data):
         heat_sim_data.updated_copy(data=[heat_sim_data.data[0]] * 2)
 
     # Test updating simulation data with invalid simulation
-    temp_mnt = td.TemperatureMonitor(size=(1, 2, 3), name="test")
+    temp_mnt = td.TemperatureMonitor(size=(1, 2, 3), name="test", unstructured=False)
     temp_mnt = temp_mnt.updated_copy(name="test2")
 
     sim = heat_sim_data.simulation.updated_copy(monitors=[temp_mnt])
@@ -1797,6 +1835,7 @@ def place_box(center_offset):
                     center=[0, 0, 0],
                     size=(td.inf, td.inf, td.inf),
                     name="test_monitor",
+                    unstructured=False,
                 )
             ],
         )
@@ -1846,7 +1885,10 @@ def test_sim_structure_extent(box_size, log_level):
             grid_spec=td.UniformUnstructuredGrid(dl=0.1),
             monitors=[
                 td.SteadyPotentialMonitor(
-                    center=(0, 0, 0), size=(td.inf, td.inf, td.inf), name="test_monitor"
+                    center=(0, 0, 0),
+                    size=(td.inf, td.inf, td.inf),
+                    name="test_monitor",
+                    unstructured=False,
                 )
             ],
         )
@@ -1993,8 +2035,8 @@ def test_simulation_with_multiple_sources_and_monitors(
     ]
 
     monitors = [
-        td.TemperatureMonitor(size=(1.6, 2, 3), name="temp_mnt1"),
-        td.SteadyPotentialMonitor(size=(1.6, 2, 3), name="volt_mnt1"),
+        td.TemperatureMonitor(size=(1.6, 2, 3), name="temp_mnt1", unstructured=False),
+        td.SteadyPotentialMonitor(size=(1.6, 2, 3), name="volt_mnt1", unstructured=False),
     ]
 
     boundary_spec = [
@@ -2036,7 +2078,7 @@ def test_dynamic_simulation_updates(heat_simulation):
     assert updated_sim.center == new_center
 
     # Add a new monitor
-    new_monitor = td.TemperatureMonitor(size=(1, 1, 1), name="new_temp_mnt")
+    new_monitor = td.TemperatureMonitor(size=(1, 1, 1), name="new_temp_mnt", unstructured=False)
     updated_sim = heat_simulation.updated_copy(
         monitors=(*list(heat_simulation.monitors), new_monitor)
     )
@@ -2242,7 +2284,7 @@ def test_bandgap_monitor():
 def test_additional_edge_cases():
     """Test additional edge cases and error handling."""
     # Attempt to create a monitor with zero size
-    td.TemperatureMonitor(size=(0, 0, 0), name="zero_size_mnt")
+    td.TemperatureMonitor(size=(0, 0, 0), name="zero_size_mnt", unstructured=False)
 
     # Create a simulation with overlapping structures
     td.HeatChargeSimulation(
@@ -2652,6 +2694,7 @@ def test_heat_charge_simulation_plot():
         center=(0, 0, 0),
         size=(1, 1, 0),
         name="temp_mnt",
+        unstructured=False,
     )
 
     # Create a HEAT simulation

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

@@ -37,7 +37,7 @@ class TemperatureData(HeatChargeMonitorData):
     >>> temp_data = SpatialDataArray(
     ...     np.ones((2, 3, 4)), coords={"x": [0, 1], "y": [0, 1, 2], "z": [0, 1, 2, 3]}
     ... )
-    >>> temp_mnt = TemperatureMonitor(size=(1, 2, 3), name="temperature")
+    >>> temp_mnt = TemperatureMonitor(size=(1, 2, 3), name="temperature", unstructured=True)
     >>> temp_mnt_data = TemperatureData(
     ...     monitor=temp_mnt, temperature=temp_data, symmetry=(0, 1, 0), symmetry_center=(0, 0, 0)
     ... )

tidy3d/components/tcad/data/sim_data.py

@@ -221,7 +221,7 @@ class HeatChargeSimulationData(AbstractHeatChargeSimulationData):
     -------
     >>> import tidy3d as td
     >>> import numpy as np
-    >>> temp_mnt = td.TemperatureMonitor(size=(1, 2, 3), name="sample")
+    >>> temp_mnt = td.TemperatureMonitor(size=(1, 2, 3), name="sample", unstructured=True)
     >>> heat_sim = HeatChargeSimulation(
     ...     size=(3.0, 3.0, 3.0),
     ...     structures=[
@@ -506,7 +506,7 @@ class VolumeMesherData(AbstractHeatChargeSimulationData):
     >>> import tidy3d as td
     >>> import numpy as np
     >>> mesh_mnt = td.VolumeMeshMonitor(size=(1, 2, 3), name="mesh")
-    >>> temp_mnt = td.TemperatureMonitor(size=(1, 2, 3), name="sample")
+    >>> temp_mnt = td.TemperatureMonitor(size=(1, 2, 3), name="sample", unstructured=True)
     >>> heat_sim = td.HeatChargeSimulation(
     ...     size=(3.0, 3.0, 3.0),
     ...     structures=[

tidy3d/components/tcad/monitors/charge.py

@@ -7,6 +7,7 @@
 import pydantic.v1 as pd
 
 from tidy3d.components.tcad.monitors.abstract import HeatChargeMonitor
+from tidy3d.log import log
 
 
 class SteadyPotentialMonitor(HeatChargeMonitor):
@@ -21,6 +22,19 @@ class SteadyPotentialMonitor(HeatChargeMonitor):
     ... )
     """
 
+    @pd.root_validator(pre=True)
+    def _warn_unstructured_default_change(cls, values):
+        """Warn users that the default value of 'unstructured' will change to True in the next release."""
+        # Only warn if 'unstructured' is not explicitly set (using default False)
+        if "unstructured" not in values:
+            log.warning(
+                "The default value of 'unstructured' for 'SteadyPotentialMonitor' will change "
+                "from 'False' to 'True' in the next release. To avoid this warning and ensure "
+                "consistent behavior, please explicitly set 'unstructured=True' or 'unstructured=False' "
+                "when creating the monitor."
+            )
+        return values
+
 
 class SteadyFreeCarrierMonitor(HeatChargeMonitor):
     """

tidy3d/components/tcad/monitors/heat.py

@@ -2,9 +2,11 @@
 
 from __future__ import annotations
 
+import pydantic.v1 as pd
 from pydantic.v1 import Field, PositiveInt
 
 from tidy3d.components.tcad.monitors.abstract import HeatChargeMonitor
+from tidy3d.log import log
 
 
 class TemperatureMonitor(HeatChargeMonitor):
@@ -19,3 +21,16 @@ class TemperatureMonitor(HeatChargeMonitor):
         "This can be useful for reducing data storage as needed by the application."
         "NOTE: this is only relevant for unsteady (transient) Heat simulations. ",
     )
+
+    @pd.root_validator(pre=True)
+    def _warn_unstructured_default_change(cls, values):
+        """Warn users that the default value of 'unstructured' will change to True in the next release."""
+        # Only warn if 'unstructured' is not explicitly set (using default False)
+        if "unstructured" not in values:
+            log.warning(
+                "The default value of 'unstructured' for 'TemperatureMonitor' will change "
+                "from 'False' to 'True' in the next release. To avoid this warning and ensure "
+                "consistent behavior, please explicitly set 'unstructured=True' or 'unstructured=False' "
+                "when creating the monitor."
+            )
+        return values

tidy3d/components/tcad/simulation/heat.py

@@ -43,7 +43,7 @@ class HeatSimulation(HeatChargeSimulation):
     ...             condition=td.TemperatureBC(temperature=500),
     ...         )
     ...     ],
-    ...     monitors=[td.TemperatureMonitor(size=(1, 2, 3), name="sample")],
+    ...     monitors=[td.TemperatureMonitor(size=(1, 2, 3), name="sample", unstructured=True)],
     ... )
     """
 

tidy3d/components/tcad/simulation/heat_charge.py

@@ -228,7 +228,7 @@ class HeatChargeSimulation(AbstractSimulation):
     ...             condition=td.TemperatureBC(temperature=500),
     ...         )
     ...     ],
-    ...     monitors=[td.TemperatureMonitor(size=(1, 2, 3), name="sample")],
+    ...     monitors=[td.TemperatureMonitor(size=(1, 2, 3), name="sample", unstructured=True)],
     ... )
 
     To run a drift-diffusion (``Charge`` |:zap:|) system:
@@ -1999,7 +1999,7 @@ def from_scene(cls, scene: Scene, **kwargs: Any) -> HeatChargeSimulation:
         ...             condition=TemperatureBC(temperature=500),
         ...         )
         ...     ],
-        ...     monitors=[TemperatureMonitor(name="temp_monitor", center=(0, 0, 0), size=(1, 1, 1))],
+        ...     monitors=[TemperatureMonitor(name="temp_monitor", center=(0, 0, 0), size=(1, 1, 1), unstructured=True)],
         ... )
         """