Feat: Add ACVoltageSource for small-signal analysis

Author: damiano-flex

docs/api/spice.rst

@@ -10,6 +10,7 @@ Sources
    :toctree: _autosummary/
    :template: module.rst
 
+   tidy3d.ACVoltageSource
    tidy3d.DCVoltageSource
    tidy3d.DCCurrentSource
 

tests/test_components/test_heat_charge.py

@@ -897,6 +897,38 @@ def test_heat_charge_bcs_validation(boundary_conditions):
     with pytest.raises(pd.ValidationError):
         td.VoltageBC(source=td.DCVoltageSource(voltage=np.array([td.inf, 0, 1])))
 
+    # Invalid ACVoltageSource: infinite voltage
+    with pytest.raises(pd.ValidationError):
+        td.VoltageBC(
+            source=td.ACVoltageSource(
+                voltage=np.array([td.inf, 0, 1]), freqs=[1e2, 1e3], amplitude=1e-2
+            )
+        )
+
+    # Invalid ACVoltageSource: infinite frequency
+    with pytest.raises(pd.ValidationError):
+        td.VoltageBC(
+            source=td.ACVoltageSource(
+                voltage=np.array([-0.1, 0.2, 0.3]), freqs=[1e2, td.inf, 1e4], amplitude=1e-2
+            )
+        )
+
+    # Invalid ACVoltageSource: negative frequency
+    with pytest.raises(pd.ValidationError):
+        td.VoltageBC(
+            source=td.ACVoltageSource(
+                voltage=np.array([-0.1, 0.2, 0.3]), freqs=[-1e2, 1e1, 1e2], amplitude=1e-2
+            )
+        )
+
+    # Invalid ACVoltageSource: infinite amplitude
+    with pytest.raises(pd.ValidationError):
+        td.VoltageBC(
+            source=td.ACVoltageSource(
+                voltage=np.array([-0.1, 0.2, 0.3]), freqs=[1e2, 1e3, 1e4], amplitude=td.inf
+            )
+        )
+
 
 def test_vertical_natural_convection():
     solid_box_l = td.Box(center=(0, 0, 0), size=(2, 2, 2))
@@ -1220,6 +1252,54 @@ def test_heat_charge_simulation(simulation_data):
     assert mesher is not None, "VolumeMesher should be created successfully."
 
 
+def test_heat_charge_multiple_ac_sources(grid_specs):
+    """Tests that a ValidationError is raised when multiple AC sources are defined."""
+    solid_box_1 = td.Box(center=(0, 0, 0), size=(2, 2, 2))
+    solid_box_2 = td.Box(center=(2, 2, 2), size=(2, 2, 2))
+    solid_box_3 = td.Box(center=(4, 4, 4), size=(2, 2, 2))
+
+    solid_medium = td.MultiPhysicsMedium(
+        heat=td.SolidMedium(conductivity=1, capacity=1), name="solid"
+    )
+    air = td.MultiPhysicsMedium(heat=td.FluidMedium(), name="air")
+
+    def createSolid(geometry, name):
+        return td.Structure(geometry=geometry, medium=solid_medium, name=name)
+
+    solid_structure_1 = createSolid(solid_box_1, "solid_1")
+    solid_structure_2 = createSolid(solid_box_2, "solid_2")
+    solid_structure_3 = createSolid(solid_box_3, "solid_3")
+
+    bc_ssac1 = td.VoltageBC(
+        source=td.ACVoltageSource(
+            voltage=[0, 1], freqs=[1e3, 1e4], amplitude=1e-3, name="ac_source1"
+        )
+    )
+    bc_ssac2 = td.VoltageBC(
+        source=td.ACVoltageSource(
+            voltage=[0, 1], freqs=[1e3, 1e4], amplitude=1e-3, name="ac_source2"
+        )
+    )
+
+    placement1 = td.StructureStructureInterface(structures=["solid_1", "solid_2"])
+    placement2 = td.StructureStructureInterface(structures=["solid_2", "solid_3"])
+
+    boundary_spec = [
+        td.HeatChargeBoundarySpec(condition=bc_ssac1, placement=placement1),
+        td.HeatChargeBoundarySpec(condition=bc_ssac2, placement=placement2),
+    ]
+
+    with pytest.raises(pd.ValidationError, match="Only a single AC source can be supplied"):
+        td.HeatChargeSimulation(
+            structures=[solid_structure_1, solid_structure_2, solid_structure_3],
+            center=(2, 2, 2),
+            size=(6, 6, 6),
+            boundary_spec=boundary_spec,
+            medium=air,
+            grid_spec=grid_specs["uniform"],
+        )
+
+
 def test_sim_data_plotting(simulation_data):
     """Tests whether simulation data can be plotted and appropriate errors are raised."""
     heat_sim_data, cond_sim_data, cap_sim_data, fc_sim_data, mesh_data = simulation_data

tidy3d/__init__.py

@@ -25,6 +25,7 @@
     IsothermalSteadyChargeDCAnalysis,
     SteadyChargeDCAnalysis,
 )
+from tidy3d.components.spice.sources.ac import ACVoltageSource
 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
@@ -444,6 +445,7 @@ def set_logging_level(level: str) -> None:
     "PML",
     "TFSF",
     "ABCBoundary",
+    "ACVoltageSource",
     "Absorber",
     "AbsorberParams",
     "AbstractFieldProjectionData",

tidy3d/components/data/data_array.py

@@ -535,6 +535,24 @@ class FreqDataArray(DataArray):
     _dims = ("f",)
 
 
+class FreqVoltageDataArray(DataArray):
+    """Frequency-domain array.
+
+    Example
+    -------
+    >>> f = [2e14, 3e14]
+    >>> v = [0.1, 0.2, 0.3]
+    >>> coords = dict(f=f, v=v)
+    >>> fd = FreqVoltageDataArray((1+1j) * np.random.random((2, 3)), coords=coords)
+    """
+
+    __slots__ = ()
+    _dims = (
+        "f",
+        "v",
+    )
+
+
 class FreqModeDataArray(DataArray):
     """Array over frequency and mode index.
 
@@ -1559,6 +1577,7 @@ def _make_impedance_data_array(result: DataArray) -> ImpedanceResultTypes:
     FreqDataArray,
     TimeDataArray,
     FreqModeDataArray,
+    FreqVoltageDataArray,
     TriangleMeshDataArray,
     HeatDataArray,
     EMEScalarFieldDataArray,

tidy3d/components/spice/sources/ac.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from typing import Optional
+
+import pydantic.v1 as pd
+
+from tidy3d.components.base import Tidy3dBaseModel
+from tidy3d.components.types import ArrayFloat1D
+from tidy3d.constants import HERTZ, VOLT
+from tidy3d.constants import inf as td_inf
+
+
+class ACVoltageSource(Tidy3dBaseModel):
+    """
+    Small-signal AC voltage source.
+
+    Notes
+    -----
+    This source represents a small-signal AC excitation defined by a list of bias voltages,
+    a set of small-signal analysis frequencies, and a small-signal amplitude (linear scale).
+
+    The bias ``voltage`` refers to the DC operating point above the simulation ground. Currently, full circuit simulation though electrical ports is not supported.
+
+    Examples
+    --------
+    >>> import tidy3d as td
+    >>> voltages = [-0.5, 0, 1, 2, 3, 4]
+    >>> frequency = [1e3, 1e4, 1e5]
+    >>> amplitude = 1e-3
+    >>> voltage_source = td.ACVoltageSource(
+    ...     voltage=voltages,
+    ...     freqs=frequency,
+    ...     amplitude=amplitude,
+    ... )
+    """
+
+    name: Optional[str] = pd.Field(
+        None,
+        title="Name",
+        description="Unique name for the AC voltage source",
+        min_length=1,
+    )
+
+    voltage: ArrayFloat1D = pd.Field(
+        ...,
+        title="DC Bias Voltages",
+        description="List of DC operating point voltages (above ground) used with :class:`VoltageBC`.",
+        units=VOLT,
+    )
+
+    freqs: ArrayFloat1D = pd.Field(
+        ...,
+        title="AC Analysis Frequencies",
+        description="List of small-signal analysis frequencies.",
+        units=HERTZ,
+    )
+
+    amplitude: pd.FiniteFloat = pd.Field(
+        ...,
+        title="Small-Signal Amplitude",
+        description="Small-signal AC amplitude.",
+        units=VOLT,
+    )
+
+    @pd.validator("voltage")
+    def validate_voltage(cls, val):
+        for v in val:
+            if v == td_inf:
+                raise ValueError(f"Voltages must be finite. Current voltage= {val}.")
+        return val
+
+    @pd.validator("freqs")
+    def validate_frequency(cls, val):
+        for v in val:
+            if v == td_inf or v <= 0:
+                raise ValueError(
+                    f"Frequencies must be strictly positive and finite. Current frequency={val}."
+                )
+        return val
+
+    @pd.validator("amplitude")
+    def validate_amplitude(cls, val):
+        if val == td_inf:
+            raise ValueError(f"Small signal amplitude must be finite. Current amplitude={val}.")
+        return val

tidy3d/components/spice/sources/dc.py

@@ -48,7 +48,13 @@ class DCVoltageSource(Tidy3dBaseModel):
     >>> voltage_source = td.DCVoltageSource(voltage=voltages)
     """
 
-    name: Optional[str]
+    name: Optional[str] = pd.Field(
+        None,
+        title="Name",
+        description="Unique name for the DC voltage source",
+        min_length=1,
+    )
+
     voltage: ArrayFloat1D = pd.Field(
         ...,
         title="Voltage",
@@ -78,7 +84,13 @@ class DCCurrentSource(Tidy3dBaseModel):
     >>> current_source = td.DCCurrentSource(current=0.4)
     """
 
-    name: Optional[str]
+    name: Optional[str] = pd.Field(
+        None,
+        title="Name",
+        description="Unique name for the DC current source",
+        min_length=1,
+    )
+
     current: pd.FiniteFloat = pd.Field(
         title="Current",
         description="DC current usually used as source in :class:`CurrentBC` boundary conditions.",

tidy3d/components/spice/sources/types.py

@@ -2,7 +2,8 @@
 
 from typing import Union
 
+from .ac import ACVoltageSource
 from .dc import DCCurrentSource, DCVoltageSource
 
-VoltageSourceType = Union[DCVoltageSource]
+VoltageSourceType = Union[DCVoltageSource, ACVoltageSource]
 CurrentSourceType = Union[DCCurrentSource]

tidy3d/components/tcad/data/sim_data.py

@@ -11,6 +11,7 @@
 from tidy3d.components.base import Tidy3dBaseModel
 from tidy3d.components.base_sim.data.sim_data import AbstractSimulationData
 from tidy3d.components.data.data_array import (
+    FreqVoltageDataArray,
     SpatialDataArray,
     SteadyVoltageDataArray,
 )
@@ -84,6 +85,12 @@ class DeviceCharacteristics(Tidy3dBaseModel):
         "is given in Ohms. Note that in 2D the resistance is given in :math:`\\Omega \\mu`.",
     )
 
+    ac_current_voltage: Optional[FreqVoltageDataArray] = pd.Field(
+        None,
+        title="AC current vs voltage and frequency",
+        description="Complex small-signal current I(v, f).",
+    )
+
 
 class AbstractHeatChargeSimulationData(AbstractSimulationData, ABC):
     """Abstract class for HeatChargeSimulation results, or VolumeMesher results."""

tidy3d/components/tcad/simulation/heat_charge.py

@@ -35,6 +35,7 @@
 from tidy3d.components.material.types import MultiPhysicsMedium, StructureMediumType
 from tidy3d.components.medium import Medium
 from tidy3d.components.scene import Scene
+from tidy3d.components.spice.sources.ac import ACVoltageSource
 from tidy3d.components.spice.sources.dc import DCVoltageSource
 from tidy3d.components.spice.types import (
     ElectricalAnalysisType,
@@ -468,6 +469,19 @@ def check_voltage_array_if_capacitance(cls, values):
             )
         return values
 
+    @pd.root_validator(skip_on_failure=True)
+    def check_single_ssac(cls, values):
+        boundary_spec = values["boundary_spec"]
+        ssac_present = False
+        for bc in boundary_spec:
+            if isinstance(bc.condition, VoltageBC):
+                if isinstance(bc.condition.source, ACVoltageSource):
+                    if ssac_present:
+                        raise SetupError("Only a single AC source can be supplied")
+                    else:
+                        ssac_present = True
+        return values
+
     @pd.root_validator(skip_on_failure=True)
     def check_natural_convection_bc(cls, values):
         """Make sure that natural convection BCs are defined correctly."""
@@ -1928,3 +1942,22 @@ def _useHeatSourceFromConductionSim(self):
         """Returns True if 'HeatFromElectricSource' has been defined."""
 
         return any(isinstance(source, HeatFromElectricSource) for source in self.sources)
+
+    def _get_charge_type(self):
+        for bc in self.boundary_spec:
+            if isinstance(bc.condition, VoltageBC):
+                if isinstance(bc.condition.source, ACVoltageSource):
+                    return "ac"
+        return "dc"
+
+    def _get_ssac_frequency_and_amplitude(self):
+        for bc in self.boundary_spec:
+            if isinstance(bc.condition, VoltageBC):
+                if isinstance(bc.condition.source, ACVoltageSource):
+                    return (
+                        bc.condition.source.freqs.tolist(),
+                        bc.condition.source.amplitude,
+                    )
+        raise SetupError(
+            "'HeatChargeSimulation' does not include any 'ACVoltageSource' in 'boundary_spec')."
+        )