fix(rf): enforce far_field_approx=True for DirectivityMonitor

Author: dmarek-flex

CHANGELOG.md

@@ -33,6 +33,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - `CustomVoltageIntegral2D` → `Custom2DVoltageIntegral`
   - `CustomCurrentIntegral2D` → `Custom2DCurrentIntegral`
   - Path integral and impedance calculator classes have been refactored and moved from `tidy3d.plugins.microwave` to `tidy3d.components.microwave`. They are now publicly exported via the top-level package `__init__.py`, so you can import them directly, e.g. `from tidy3d import ImpedanceCalculator, AxisAlignedVoltageIntegral, AxisAlignedCurrentIntegral, Custom2DVoltageIntegral, Custom2DCurrentIntegral, Custom2DPathIntegral`.
+- `DirectivityMonitor` now forces `far_field_approx` to `True`, which was previously configurable.
 
 ### Fixed
 - More robust `Sellmeier` and `Debye` material model, and prevent very large pole parameters in `PoleResidue` material model.

schemas/Simulation.json

@@ -5379,6 +5379,9 @@
         },
         "far_field_approx": {
           "default": true,
+          "enum": [
+            true
+          ],
           "type": "boolean"
         },
         "freqs": {

schemas/TerminalComponentModeler.json

@@ -5860,6 +5860,9 @@
         },
         "far_field_approx": {
           "default": true,
+          "enum": [
+            true
+          ],
           "type": "boolean"
         },
         "freqs": {

tests/test_components/test_monitor.py

@@ -445,3 +445,26 @@ def test_monitor_surfaces_from_volume():
     # z+ surface
     assert monitor_surfaces[5].center == (center[0], center[1], center[2] + size[2] / 2.0)
     assert monitor_surfaces[5].size == (size[0], size[1], 0.0)
+
+
+def test_directivity_monitor():
+    """Check validation of directivity monitor."""
+    size = (1, 2, 3)
+    center = (1, 2, 3)
+
+    pd = np.atleast_1d(40000)
+    thetas = np.linspace(0, 2 * np.pi, 100)
+    phis = np.linspace(0, np.pi, 100)
+
+    # far_field_approx cannot be set to False
+    with pytest.raises(pydantic.ValidationError):
+        _ = td.DirectivityMonitor(
+            size=size,
+            center=center,
+            theta=thetas,
+            phi=phis,
+            proj_distance=pd,
+            freqs=FREQS,
+            name="directivity",
+            far_field_approx=False,
+        )

tests/test_plugins/test_array_factor.py

@@ -308,7 +308,6 @@ def make_antenna_sim():
         name="directivity",
         phi=list(phi),
         theta=list(theta),
-        far_field_approx=False,
     )
 
     # Create the simulation object
@@ -628,7 +627,6 @@ def test_rectangular_array_calculator_monitor_data_from_array_factor():
         name="radiation",
         phi=list(np.linspace(0, 2 * np.pi, 10)),
         theta=list(np.linspace(0, np.pi, 10)),
-        far_field_approx=False,
     )
     coords_under_sampled = {
         "r": [monitor_directivity_under_sampled.proj_distance],

tidy3d/components/monitor.py

@@ -1237,8 +1237,27 @@ class DirectivityMonitor(MicrowaveBaseModel, FieldProjectionAngleMonitor, FluxMo
 
         Balanis, Constantine A., "Antenna Theory: Analysis and Design,"
         John Wiley & Sons, Chapter 2.12 (2016).
+
+    Example
+    -------
+    >>> import numpy as np
+    >>> monitor = DirectivityMonitor(  # doctest: +SKIP
+    ...     center=(0, 0, 0),
+    ...     size=(2, 2, 2),
+    ...     freqs=[1e9, 2e9, 3e9],
+    ...     name='directivity_monitor',
+    ...     theta=np.linspace(0, np.pi, 10),
+    ...     phi=np.linspace(0, 2*np.pi, 20),
+    ... )
     """
 
+    far_field_approx: Literal[True] = pydantic.Field(
+        True,
+        title="Far Field Approximation",
+        description="Directivity calculations require the far field approximation. "
+        "This field is hard-coded to be ``True`` and cannot be changed.",
+    )
+
     def storage_size(self, num_cells: int, tmesh: ArrayFloat1D) -> int:
         """Size of monitor storage given the number of points after discretization."""
         # stores 1 complex number per pair of angles, per frequency,