add antenna gain and efficiency figures of merit

CHANGELOG.md

@@ -15,6 +15,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `PlaneWaveBeamProfile`, `GaussianBeamProfile` and `AstigmaticGaussianBeamProfile` components to compute field data associated to such beams based on their corresponding analytical expressions, and compute field overlaps with other data.
 - `num_freqs` argument to the `PlaneWave` source.
 - Support for running multiple adjoint simulations from a single forward simulation in adjoint pipeline depending on monitor configuration.
+- Ability to directly create `DirectivityData` from an `xarrray.Dataset` containing electromagnetic fields, where the flux is calculated by integrating the fields over the surface of a sphere.
+- Ability to the `TerminalComponentModeler` that enables the computation of antenna parameters and figures of merit, such as gain, radiation efficiency, and reflection efficiency. When there are multiple ports in the `TerminalComponentModeler`, these antenna parameters may be calculated with user-specified port excitation magnitudes and phases.
 
 ### Changed
 - The coordinate of snapping points in `GridSpec` can take value `None`, so that mesh can be selectively snapped only along certain dimensions.
@@ -26,6 +28,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added warning when a lumped element is not completely within the simulation bounds, since now lumped elements will only have an effect on the `Simulation` when they are completely within the simulation bounds.
 - Allow `ModeData` to be passed to path integral computations in the `microwave` plugin.
 - Default number of grid cells refining lumped elements is changed to 1, and some of the generated `MeshOverrideStructure` are replaced by grid snapping points.
+- Definition of left- and right-handed circular polarization in `DirectivityData` to follow engineering convention.
+- Extended the number of quantities provided by the `DirectivityData`, which now includes more parameters of interest like radiation intensity and gain. In addition, antenna parameters can be decomposed into contributions from individual polarization components according to a specified polarization basis, either `linear` or `circular`.
 
 ### Fixed
 - Make gauge selection for non-converged modes more robust.

docs/api/index.rst

@@ -27,6 +27,7 @@ API |:computer:|
     heat/index
     charge/index
     eme/index
+    microwave/index
     plugins/index
     spice
     constants
@@ -53,6 +54,7 @@ API |:computer:|
 .. include:: /api/heat/index.rst
 .. include:: /api/charge/index.rst
 .. include:: /api/eme/index.rst
+.. include:: /api/microwave/index.rst
 .. include:: /api/plugins/index.rst
 .. include:: /api/constants.rst
 .. include:: /api/abstract_base.rst

docs/api/microwave/index.rst

@@ -0,0 +1,10 @@
+Microwave |:satellite:|
+=======================
+
+.. toctree::
+    :hidden:
+
+    output_data
+
+
+.. include:: /api/microwave/output_data.rst

docs/api/microwave/output_data.rst

@@ -0,0 +1,10 @@
+.. currentmodule:: tidy3d
+
+Output Data
+-----------
+
+.. autosummary::
+   :toctree: ../_autosummary/
+   :template: module.rst
+
+   tidy3d.AntennaMetricsData

docs/api/plugins/smatrix.rst

@@ -11,6 +11,7 @@ Scattering Matrix Calculator
    tidy3d.plugins.smatrix.Port
    tidy3d.plugins.smatrix.ModalPortDataArray
    tidy3d.plugins.smatrix.TerminalComponentModeler
+   tidy3d.plugins.smatrix.PortDataArray
    tidy3d.plugins.smatrix.TerminalPortDataArray
    tidy3d.plugins.smatrix.LumpedPort
    tidy3d.plugins.smatrix.CoaxialLumpedPort

tests/test_components/test_microwave.py

@@ -3,6 +3,10 @@
 from math import isclose
 
 import numpy as np
+import pytest
+import xarray as xr
+from tidy3d.components.data.monitor_data import FreqDataArray
+from tidy3d.components.microwave.data.monitor_data import AntennaMetricsData
 from tidy3d.components.microwave.formulas.circuit_parameters import (
     capacitance_colinear_cylindrical_wire_segments,
     capacitance_rectangular_sheets,
@@ -12,6 +16,8 @@
 )
 from tidy3d.constants import EPSILON_0
 
+from ..test_data.test_monitor_data import make_directivity_data
+
 
 def test_inductance_formulas():
     """Run the formulas for inductance and compare to precomputed results."""
@@ -49,3 +55,45 @@ def test_capacitance_formulas():
     D2 = 0.144
     C_ref = np.pi * EPSILON_0 * length / (np.log(length / radius) - 2.303 * D2)
     assert isclose(C3, C_ref, rel_tol=1e-2)
+
+
+def test_antenna_parameters():
+    """Test basic antenna parameters computation and validation."""
+
+    # Create from random directivity data
+    directivity_data = make_directivity_data()
+    f = directivity_data.coords["f"]
+    power_inc = FreqDataArray(0.8 * np.ones(len(f)), coords={"f": f})
+    power_refl = 0.25 * power_inc
+    antenna_params = AntennaMetricsData.from_directivity_data(
+        directivity_data, power_inc, power_refl
+    )
+
+    # Test that all essential parameters exist and are correct type
+    assert isinstance(antenna_params.radiation_efficiency, FreqDataArray)
+    assert isinstance(antenna_params.reflection_efficiency, FreqDataArray)
+    assert np.allclose(antenna_params.reflection_efficiency, 0.75)
+    assert isinstance(antenna_params.gain, xr.DataArray)
+    assert isinstance(antenna_params.realized_gain, xr.DataArray)
+
+    # Test partial gain computations in linear basis
+    partial_gain_linear = antenna_params.partial_gain(pol_basis="linear")
+    assert isinstance(partial_gain_linear, xr.Dataset)
+    assert "Gtheta" in partial_gain_linear
+    assert "Gphi" in partial_gain_linear
+
+    # Test partial gain computations in circular basis
+    partial_gain_circular = antenna_params.partial_gain(pol_basis="circular")
+    assert isinstance(partial_gain_circular, xr.Dataset)
+    assert "Gright" in partial_gain_circular
+    assert "Gleft" in partial_gain_circular
+
+    # Test partial realized gain computations in both bases
+    assert isinstance(antenna_params.partial_realized_gain("linear"), xr.Dataset)
+    assert isinstance(antenna_params.partial_realized_gain("circular"), xr.Dataset)
+
+    # Test validation of pol_basis parameter
+    with pytest.raises(ValueError):
+        antenna_params.partial_gain("invalid")
+    with pytest.raises(ValueError):
+        antenna_params.partial_realized_gain("invalid")

tests/test_data/test_data_arrays.py

@@ -43,8 +43,8 @@
 TS = np.linspace(0, 1e-12, 4)
 MODE_INDICES = np.arange(0, 4)
 DIRECTIONS = ["+", "-"]
-PHIS = np.linspace(0, np.pi, 100)
-THETAS = np.linspace(0, 2 * np.pi, 100)
+PHIS = np.linspace(0, 2 * np.pi, 100)
+THETAS = np.linspace(0, np.pi, 100)
 PD = np.atleast_1d(4000)
 
 FIELD_MONITOR = td.FieldMonitor(size=SIZE_3D, fields=FIELDS, name="field", freqs=FREQS)

tests/test_data/test_monitor_data.py

@@ -5,7 +5,11 @@
 import pydantic.v1 as pydantic
 import pytest
 import tidy3d as td
-from tidy3d.components.data.data_array import FreqModeDataArray
+import xarray as xr
+from tidy3d.components.data.data_array import (
+    FreqDataArray,
+    FreqModeDataArray,
+)
 from tidy3d.components.data.monitor_data import (
     DiffractionData,
     DirectivityData,
@@ -185,18 +189,54 @@ def make_flux_data():
     return FluxData(monitor=FLUX_MONITOR, flux=FLUX.copy())
 
 
-def make_directivity_data():
+def make_directivity_data(planar_monitor: bool = False):
     data = make_far_field_data_array()
+    monitor = DIRECTIVITY_MONITOR
+    if planar_monitor:
+        size = list(DIRECTIVITY_MONITOR.size)
+        size[1] = 0
+        monitor = DIRECTIVITY_MONITOR.updated_copy(size=size)
     return DirectivityData(
-        monitor=DIRECTIVITY_MONITOR,
+        monitor=monitor,
         flux=FLUX.copy(),
         Er=data,
         Etheta=data,
         Ephi=data,
         Hr=data,
         Htheta=data,
         Hphi=data,
+        projection_surfaces=monitor.projection_surfaces,
+    )
+
+
+def make_field_dataset_using_power_density(
+    values: np.ndarray, theta: np.ndarray, phi: np.ndarray, freqs: np.ndarray, r_proj: np.ndarray
+):
+    """Helper function to create ``DirectivityMonitor`` and field dataset with a desired power density."""
+    monitor = td.DirectivityMonitor(
+        size=(2, 2, 2),
+        center=(0, 0, 0),
+        freqs=freqs,
+        name="proj_monitor",
+        far_field_approx=True,
+        proj_distance=r_proj,
+        theta=theta,
+        phi=phi,
+    )
+
+    coords = dict(r=r_proj, theta=theta, phi=phi, f=freqs)
+    field = td.FieldProjectionAngleDataArray(values, coords=coords)
+
+    field_components = dict(
+        Er=field,
+        Etheta=field,
+        Ephi=field,
+        Hr=field,
+        Htheta=-1.0 * field,
+        Hphi=field,
     )
+    field_dataset = xr.Dataset(field_components)
+    return monitor, field_dataset
 
 
 def make_flux_time_data():
@@ -337,12 +377,102 @@ def test_flux_time_data():
     _ = data.flux
 
 
-def test_directivity_data():
-    data = make_directivity_data()
-    _ = data.directivity
-    _ = data.axial_ratio
-    _ = data.left_polarization
-    _ = data.right_polarization
+@pytest.mark.parametrize("planar_monitor", [False, True])
+def test_directivity_data(planar_monitor):
+    data = make_directivity_data(planar_monitor)
+    _ = data.flux
+    f = data.flux.f.values
+    # make some dummy data to represent power supplied to antenna
+    power_in = FreqDataArray(np.abs(np.random.random(size=np.shape(f))), coords=dict(f=f))
+    assert isinstance(data.partial_radiation_intensity(), xr.Dataset)
+    assert isinstance(data.radiation_intensity, xr.DataArray)
+    assert isinstance(data.partial_directivity(), xr.Dataset)
+    assert isinstance(data.directivity, xr.DataArray)
+
+    assert isinstance(data.calc_partial_gain(power_in), xr.Dataset)
+    assert isinstance(data.calc_gain(power_in), xr.DataArray)
+    assert isinstance(data.axial_ratio, xr.DataArray)
+    assert isinstance(data.left_polarization, xr.DataArray)
+    assert isinstance(data.right_polarization, xr.DataArray)
+
+    # Test computations using the circular polarization basis
+    pol_basis = "circular"
+    assert isinstance(data.fields_circular_polarization, xr.Dataset)
+    assert isinstance(data.partial_radiation_intensity(pol_basis), xr.Dataset)
+    assert isinstance(data.partial_directivity(pol_basis), xr.Dataset)
+    assert isinstance(data.calc_partial_gain(power_in=power_in, pol_basis=pol_basis), xr.Dataset)
+
+    # Test raise exception when pol_basis is wrong
+    with pytest.raises(ValueError):
+        data.partial_radiation_intensity("invalid")
+    with pytest.raises(ValueError):
+        data.partial_directivity("invalid")
+    with pytest.raises(ValueError):
+        data.calc_partial_gain(power_in, "invalid")
+    # Test helpers to slice data along a constant phi
+    DirectivityData.get_phi_slice(data.Etheta, phi=0)
+    DirectivityData.get_phi_slice(data.Etheta, phi=np.pi, symmetric=True)
+
+
+def test_directivity_data_from_projected_fields():
+    """Test DirectivityData is constructed properly and integration of uniform fields over
+    spherical surface matches analytic value. Also test validation of angle sampling."""
+
+    freqs = np.array([1e9, 10e9])
+    r_proj = np.array([1.0])
+    # Test invalid theta range
+    theta = np.linspace(0, np.pi / 2, 20)  # Missing half sphere
+    phi = np.linspace(0, 2 * np.pi, 40)
+    values = np.ones((len(r_proj), len(theta), len(phi), len(freqs)), dtype=complex)
+    monitor, proj_angle_data = make_field_dataset_using_power_density(
+        values, theta, phi, freqs, r_proj
+    )
+    with pytest.raises(ValueError, match="Chosen limits for `theta` are not appropriate"):
+        dir_data = td.DirectivityData.from_spherical_field_dataset(monitor, proj_angle_data)
+
+    # Test invalid phi range
+    theta = np.linspace(0, np.pi, 20)
+    phi = np.linspace(0, np.pi, 40)  # Missing half sphere
+    values = np.ones((len(r_proj), len(theta), len(phi), len(freqs)), dtype=complex)
+    monitor, proj_angle_data = make_field_dataset_using_power_density(
+        values, theta, phi, freqs, r_proj
+    )
+    with pytest.raises(ValueError, match="Chosen limits for `phi` are not appropriate"):
+        dir_data = td.DirectivityData.from_spherical_field_dataset(monitor, proj_angle_data)
+
+    # Test too coarse sampling
+    theta = np.linspace(0, np.pi, 5)  # Too few points
+    phi = np.linspace(0, 2 * np.pi, 40)
+    values = np.ones((len(r_proj), len(theta), len(phi), len(freqs)), dtype=complex)
+    monitor, proj_angle_data = make_field_dataset_using_power_density(
+        values, theta, phi, freqs, r_proj
+    )
+    with pytest.raises(ValueError, match="There are not enough sampling points"):
+        dir_data = td.DirectivityData.from_spherical_field_dataset(monitor, proj_angle_data)
+
+    # Test unsorted
+    theta = np.linspace(0, np.pi, 20)[::-1]
+    phi = np.linspace(0, 2 * np.pi, 40)
+    values = np.ones((len(r_proj), len(theta), len(phi), len(freqs)), dtype=complex)
+    monitor, proj_angle_data = make_field_dataset_using_power_density(
+        values, theta, phi, freqs, r_proj
+    )
+    with pytest.raises(ValueError, match="theta was not provided as a sorted array."):
+        dir_data = td.DirectivityData.from_spherical_field_dataset(monitor, proj_angle_data)
+
+    # Test success case with proper sampling
+    theta = np.linspace(0, np.pi, 20)
+    phi = np.linspace(0, 2 * np.pi, 40)
+    values = np.ones((len(r_proj), len(theta), len(phi), len(freqs)), dtype=complex)
+    monitor, proj_angle_data = make_field_dataset_using_power_density(
+        values, theta, phi, freqs, r_proj
+    )
+    dir_data = td.DirectivityData.from_spherical_field_dataset(monitor, proj_angle_data)
+
+    # Flux should correspond with the surface area of a sphere
+    flux_values = dir_data.flux.values
+    # Check against analytical value with 1% tolerance
+    assert np.allclose(flux_values, 4 * np.pi, rtol=1e-2)
 
 
 def test_diffraction_data():