photonforge 1.3.0__cp310-cp310-win_amd64.whl → 1.3.2__cp310-cp310-win_amd64.whl

photonforge/time_steppers/amplifier.py

@@ -0,0 +1,353 @@
+from collections.abc import Sequence
+
+import numpy
+from numpy.random import SeedSequence, default_rng
+
+from ..extension import (
+    Component,
+    TimeStepper,
+    register_time_stepper_class,
+)
+from ..typing import (
+    Frequency,
+    Gain,
+    NonNegativeInt,
+    Power_dBm,
+    TimeDelay,
+    annotate,
+)
+from ..utils import K_B, H
+
+
+class OpticalAmplifierTimeStepper(TimeStepper):
+    r"""Time-stepper for a unidirectional optical amplifier.
+
+    This model implements a simple optical amplifier with a constant gain
+    and amplified spontaneous emission (ASE) noise. The ASE noise power is
+    determined by the amplifier's gain and noise figure.
+
+    Notes:
+    ASE noise is modeled as a complex Gaussian random process. Its one-sided
+    power spectral density (PSD) is:
+
+    .. math::
+
+       S_\text{ASE} &= n_{sp} (10^\frac{g}{10} - 1) h\nu
+
+       n_\text{sp} &= \frac{10^\frac{\text{NF}}{10}}{2}
+
+    in which :math:`g` is the power gain in dB, :math:`h\nu` is the photon
+    energy, and :math:`n_\text{sp}` is the spontaneous emission factor,
+    derived from the noise figure.
+
+    The discrete-time simulation represents a spectral slice of width
+    :math:`1/\Delta t` centered at the carrier frequency. To conserve the
+    total physical noise energy in this slice, the noise variance per sample
+    is:
+
+    .. math:: \sigma^2 = \frac{S_\text{ASE}}{\Delta t}
+
+    This corresponds to integrating the optical PSD over the full simulation
+    bandwidth.
+
+    Args:
+        gain: The amplifier's power gain.
+        noise_figure: The amplifier's noise figure (NF). If ``None``, noise
+          is disabled.
+        ports: Input and output port names. If not set, the *sorted* list of
+          port names from the component is used.
+        seed: Random number generator seed to ensure reproducibility.
+
+    Reference:
+        Agrawal, G. P. (2010). *Fiber-Optic Communication Systems*. Wiley.
+    """
+
+    def __init__(
+        self,
+        *,
+        gain: Gain = 0,
+        noise_figure: Gain | None = None,
+        ports: annotate(Sequence[str], minItems=2, maxItems=2) | None = None,
+        seed: NonNegativeInt | None = None,
+    ):
+        super().__init__(gain=gain, noise_figure=noise_figure, ports=ports, seed=seed)
+
+    def setup_state(
+        self,
+        *,
+        component: Component,
+        time_step: TimeDelay,
+        carrier_frequency: Frequency,
+        **kwargs,
+    ):
+        """Initialize internal state.
+
+        Args:
+            component: Component representing amplifier.
+            time_step: The interval between time steps (in seconds).
+            carrier_frequency: The carrier frequency used to construct the time
+              stepper. The carrier should be omitted from the input signals, as
+              it is handled automatically by the time stepper.
+            kwargs: Unused.
+        """
+        p = self.parametric_kwargs
+
+        ports = p["ports"]
+        component_ports = sorted(component.select_ports("optical"))
+        if ports is None:
+            ports = component_ports
+            if len(ports) != 2:
+                raise RuntimeError(
+                    "OpticalAmplifierTimeStepper can only be used in components with 2 optical "
+                    "ports."
+                )
+        elif len(ports) != 2:
+            raise ValueError("'Argument 'ports' must be a sequence of 2 port names.")
+        elif not all(name in component_ports for name in ports):
+            raise RuntimeError(
+                f"Not all port names defined in OpticalAmplifierTimeStepper ({ports!r}) match the "
+                f"optical port names in component '{component.name}' ({component_ports!r})."
+            )
+
+        self.keys = tuple(p + "@0" for p in ports)
+
+        g = 10.0 ** (p["gain"] / 10.0)
+        nf = p["noise_figure"]
+        n_sp = 0.0 if nf is None else (0.5 * 10.0 ** (nf / 10.0))
+        s_ase = n_sp * (g - 1.0) * H * carrier_frequency
+
+        self._gain = g**0.5
+        self._stdev = (0.5 * s_ase / time_step) ** 0.5
+        self._seed = SeedSequence() if p["seed"] is None else p["seed"]
+        self.reset()
+
+    def reset(self):
+        """Reset internal state."""
+        self._rng = default_rng(self._seed)
+        self._sample_noise()
+
+    def _sample_noise(self):
+        self._ase = self._rng.normal(0, self._stdev) + 1j * self._rng.normal(0, self._stdev)
+
+    def step_single(
+        self,
+        inputs: numpy.ndarray,
+        outputs: numpy.ndarray,
+        time_index: int,
+        update_state: bool,
+        shutdown: bool,
+    ) -> None:
+        """Take a single time step on the given inputs.
+
+        Args:
+            inputs: Input values at the current time step. Must be a 1D array of
+              complex values ordered
+              according to :attr:`keys`.
+            outputs: Pre-allocated output array where results will be stored.
+              Same size and type as ``inputs``.
+            time_index: Time series index for the current input.
+            update_state: Whether to update the internal stepper state.
+            shutdown: Whether this is the last call to the single stepping
+              function for the provided :class:`TimeSeries`.
+        """
+        outputs[1] = self._ase + self._gain * inputs[0]
+        if update_state:
+            self._sample_noise()
+
+
+class ElectricalAmplifierTimeStepper(TimeStepper):
+    r"""Time-stepper for a broadband amplifier or modulator dirver.
+
+    This model implements an electrical amplifier with linear gain, noise,
+    bandwidth limiting, port reflections, and common nonlinear effects: 1 dB
+    compression, third-order intercept point (IP3), and saturation.
+
+    Args:
+        gain: The amplifier's power gain.
+        f_3dB: -3 dB frequency cutoff for bandwidth limiting.
+        saturation_power: Output saturation power.
+        compression_power: 1 dB compression power.
+        ip3: Third order intercept point.
+        noise_figure: The amplifier's noise figure (NF). If ``None``,
+          noise is disabled.
+        r0: Reflection coefficient for the input port.
+        r1: Reflection coefficient for the output port.
+        ports: Input and output port names. If not set, the *sorted* list of
+          port names from the component is used.
+        seed: Random number generator seed to ensure reproducibility.
+
+    Notes:
+        The forward path signal is processed through the following stages at
+        each time step:
+
+        1.  Low-pass filter for bandwidth limiting:
+
+            .. math::
+
+               y_0\![n] &= \alpha y_0\![n-1] + (1-\alpha) G_a a_\text{in}
+
+               \alpha &= e^{-2\pi f_\text{3dB} \Delta t}
+
+               G_a &= 10^\frac{G_\text{dB}}{20}
+
+        2.  Soft-knee compression:
+
+            .. math::
+
+               y_1 &= y_0 \left( 1 + \frac{c_s}{P_\text{1dB}} y_0^2
+                 \right)^{-\frac{1}{2}}
+
+               c_s &= 10^\frac{1}{10} - 1
+
+        3.  Cubic IP3 nonlinearity:
+
+            .. math::
+
+                y_2 = y_1 \left(1 - \frac{1}{P_\text{IP3}} y_1^2\right)
+
+        4.  Smooth saturation: A `tanh` function smoothly clamps the output
+            amplitude to approach :math:`\sqrt{P_\text{sat}}`.
+
+        5.  Additive noise: if enabled, white Gaussian noise is added to the
+            output. The noise power spectral density is derived from the
+            noise figure :math:`F` as :math:`S_P = k_B T_0 G_\text{dB} F`.
+    """
+
+    def __init__(
+        self,
+        *,
+        gain: Gain = 0,
+        f_3dB: annotate(Frequency | None, label="f 3dB") = None,
+        saturation_power: Power_dBm | None = None,
+        compression_power: Power_dBm | None = None,
+        ip3: annotate(Power_dBm | None, label="IP3") = None,
+        noise_figure: Gain | None = None,
+        r0: annotate(float, minimum=-1, maximum=1) = 0,
+        r1: annotate(float, minimum=-1, maximum=1) = 0,
+        ports: annotate(Sequence[str], minItems=2, maxItems=2) | None = None,
+        seed: NonNegativeInt | None = None,
+    ):
+        super().__init__(
+            gain=gain,
+            f_3dB=f_3dB,
+            saturation_power=saturation_power,
+            compression_power=compression_power,
+            ip3=ip3,
+            noise_figure=noise_figure,
+            r0=r0,
+            r1=r1,
+            ports=ports,
+            seed=seed,
+        )
+
+    def setup_state(
+        self,
+        *,
+        component: Component,
+        time_step: TimeDelay,
+        **kwargs,
+    ):
+        """Initialize internal state.
+
+        Args:
+            component: Component representing the amplifier.
+            time_step: The interval between time steps (in seconds).
+            kwargs: Unused.
+        """
+        p = self.parametric_kwargs
+
+        ports = p["ports"]
+        component_ports = sorted(component.select_ports("electrical"))
+        if ports is None:
+            ports = component_ports
+            if len(ports) != 2:
+                raise RuntimeError(
+                    "ElectricalAmplifierTimeStepper can only be used in components with 2 "
+                    "electrical ports."
+                )
+        elif len(ports) != 2:
+            raise ValueError("'Argument 'ports' must be a sequence of 2 port names.")
+        elif not all(name in component_ports for name in ports):
+            raise RuntimeError(
+                f"Not all port names defined in ElectricalAmplifierTimeStepper ({ports!r}) match "
+                f"the electrical port names in component '{component.name}' ({component_ports!r})."
+            )
+
+        self.keys = tuple(p + "@0" for p in ports)
+
+        self._r0 = p["r0"]
+        self._r1 = p["r1"]
+
+        f_3dB = p["f_3dB"]
+        self._alpha = 0.0 if f_3dB is None else numpy.exp(-2 * numpy.pi * f_3dB * time_step)
+
+        g = 10.0 ** (p["gain"] / 10.0)
+        self._gain = (1.0 - self._alpha) * g**0.5
+
+        p1dB = p["compression_power"]
+        self._c_1dB = 0.0 if p1dB is None else ((10.0**0.1 - 1.0) * 10.0 ** (p1dB / -10.0 + 3.0))
+
+        ip3 = p["ip3"]
+        self._c_ip3 = 0.0 if ip3 is None else (10.0 ** (ip3 / -10.0 + 3.0))
+
+        p_sat = p["saturation_power"]
+        self._sat = 0.0 if p_sat is None else (10.0 ** (p_sat / 20.0 - 1.5))
+
+        T_0 = 290  # K
+        nf = p["noise_figure"]
+        self._stdev = (
+            0.0 if nf is None else (0.5 * K_B * T_0 * g * 10 ** (nf / 10.0) / time_step) ** 0.5
+        )
+        self._seed = SeedSequence() if p["seed"] is None else p["seed"]
+
+        self.reset()
+
+    def reset(self):
+        """Reset internal state."""
+        self._y = 0.0
+        self._rng = default_rng(self._seed)
+        self._sample_noise()
+
+    def _sample_noise(self):
+        self._noise = self._rng.normal(0, self._stdev)
+
+    def step_single(
+        self,
+        inputs: numpy.ndarray,
+        outputs: numpy.ndarray,
+        time_index: int,
+        update_state: bool,
+        shutdown: bool,
+    ) -> None:
+        """Take a single time step on the given inputs.
+
+        Args:
+            inputs: Input values at the current time step. Must be a 1D array of
+              complex values ordered
+              according to :attr:`keys`.
+            outputs: Pre-allocated output array where results will be stored.
+              Same size and type as ``inputs``.
+            time_index: Time series index for the current input.
+            update_state: Whether to update the internal stepper state.
+            shutdown: Whether this is the last call to the single stepping
+              function for the provided :class:`TimeSeries`.
+        """
+        x0 = inputs[0].real
+        x1 = inputs[1].real
+
+        y0 = self._alpha * self._y + self._gain * x0
+        y = y0 / (1.0 + self._c_1dB * y0**2) ** 0.5
+        y = y * max(0.0, (1.0 - self._c_ip3 * y**2))
+        if self._sat > 0.0:
+            y = self._sat * numpy.tanh(y / self._sat)
+
+        outputs[0] = self._r0 * x0
+        outputs[1] = self._r1 * x1 + self._noise + y
+
+        if update_state:
+            self._y = y0
+            self._sample_noise()
+
+
+register_time_stepper_class(OpticalAmplifierTimeStepper)
+register_time_stepper_class(ElectricalAmplifierTimeStepper)

photonforge/{analytic_time_steppers.py → time_steppers/analytic.py}

@@ -1,7 +1,21 @@
 import numpy
 
-from .extension import TimeStepper, register_time_stepper_class
-from .typing import TimeDelay
+from ..extension import (
+    Component,
+    Interpolator,
+    TimeStepper,
+    register_time_stepper_class,
+)
+from ..typing import (
+    Coordinate,
+    Frequency,
+    Loss,
+    PropagationLoss,
+    TimeDelay,
+)
+from ..utils import C_0, route_length
+
+_zero = Interpolator([0], [0])
 
 
 class _ArrayDelayBuffer:
@@ -224,4 +238,179 @@ class DelayedTimeStepper(TimeStepper):
         numpy.copyto(outputs, self._temp_output_buffer)
 
 
+class AnalyticWaveguideTimeStepper(TimeStepper):
+    r"""Analytic waveguide tiem-stepper with power-dependent effects.
+
+    This model simulates a two-port optical waveguide where the effective
+    refractive index is dynamically perturbed by power-dependent effects,
+    specifically free-carrier dispersion and thermal changes. The total
+    effective index at any time is the sum of the baseline index and the
+    dynamic perturbations:
+
+    .. math::
+
+       &n(t) = n_\text{eff} + n_\text{fc}(t) + n_\text{th}(t)
+
+       &\tau_\text{fc} \frac{{\rm d}n_\text{fc}}{{\rm d}t}
+         + n_\text{fc}(t) = \Delta n_\text{fc}(P(t))
+
+       &\tau_\text{th} \frac{{\rm d}n_\text{th}}{{\rm d}t}
+         + n_\text{th}(t) = \Delta n_\text{th}(P(t))
+
+    in which :math:`\Delta n_\text{fc}` and :math:`\Delta n_\text{th}` are
+    the steady-state index changes corresponding to the instantaneous
+    optical power :math:`P(t)` due to free-carrier and thermal effects,
+    respectively.
+
+    Args:
+        n_eff: Effective refractive index (loss can be included here by
+          using complex values).
+        length: Length of the waveguide. If not provided, the length is
+          measured by :func:`route_length` or ports distance.
+        propagation_loss: Propagation loss.
+        n_group: Group index of the optical mode, used to calculate delay.
+        tau_fc: Time constant for the free-carrier effects. If zero,
+          free-carrier effects are disabled.
+        dn_fc: Power-dependent, steady-state index variation due to
+          free-carrier effects.
+        tau_th: Time constant for the thermal effects. If zero, thermal
+          effects are disabled.
+        dn_th: Power-dependent, steady-state index variation due to thermal
+          effects.
+
+    Notes:
+        The group delay :math:`n_g \ell / c_0` is implemented as a fixed
+        multiple of the time step.
+
+        This model uses a lumped element approximation by assuming a uniform
+        effect along the waveguide length.
+    """
+
+    def __init__(
+        self,
+        *,
+        n_eff: complex,
+        length: Coordinate | None = None,
+        propagation_loss: PropagationLoss = 0.0,
+        extra_loss: Loss = 0.0,
+        n_group: float = 0,
+        tau_fc: TimeDelay = 0,
+        dn_fc: Interpolator = _zero,
+        tau_th: TimeDelay = 0,
+        dn_th: Interpolator = _zero,
+    ):
+        super().__init__(
+            n_eff=n_eff,
+            length=length,
+            propagation_loss=propagation_loss,
+            extra_loss=extra_loss,
+            n_group=n_group,
+            tau_fc=tau_fc,
+            dn_fc=dn_fc,
+            tau_th=tau_th,
+            dn_th=dn_th,
+        )
+
+    def setup_state(
+        self,
+        *,
+        component: Component,
+        time_step: TimeDelay,
+        carrier_frequency: Frequency,
+        **kwargs,
+    ):
+        """Initialize internal state.
+
+        Args:
+            component: Component representing the laser source.
+            time_step: The interval between time steps (in seconds).
+            carrier_frequency: The carrier frequency used to construct the time
+              stepper. The carrier should be omitted from the input signals, as
+              it is handled automatically by the time stepper.
+            kwargs: Unused.
+        """
+        ports = sorted(component.select_ports("optical"))
+        if len(ports) != 2:
+            raise RuntimeError(
+                "AnalyticWaveguideTimeStepper can only be used in components with 2 optical ports."
+            )
+        self.keys = (ports[0] + "@0", ports[1] + "@0")
+
+        p = self.parametric_kwargs
+
+        length = p["length"]
+        if length is None:
+            length = 0
+            port0 = component.ports[ports[0]]
+            port1 = component.ports[ports[1]]
+            for _, _, layer in port0.spec.path_profiles_list():
+                length = max(length, route_length(component, layer))
+            if length <= 0:
+                length = numpy.sqrt(numpy.sum((port0.center - port1.center) ** 2))
+
+        self._alpha_fc = min(1.0, time_step / p["tau_fc"]) if p["tau_fc"] > 0 else 0.0
+        self._alpha_th = min(1.0, time_step / p["tau_th"]) if p["tau_th"] > 0 else 0.0
+
+        self._n_eff = p["n_eff"]
+        self._dn_fc_interp = p["dn_fc"]
+        self._dn_th_interp = p["dn_th"]
+
+        self._phi0 = 2.0 * numpy.pi * carrier_frequency * length / C_0
+        self._gain = 10.0 ** ((length * p["propagation_loss"] + p["extra_loss"]) / -20.0)
+
+        self._delay = max(0, int(numpy.round(p["n_group"] * length / C_0 / time_step)))
+        self._buffer = numpy.empty((self._delay, 2), dtype=complex)
+
+        self.reset()
+
+    def reset(self):
+        """Reset internal state."""
+        self._dn_fc = 0.0
+        self._dn_th = 0.0
+        self._buffer[:, :] = 0.0j
+        self._index = 0
+
+    def step_single(
+        self,
+        inputs: numpy.ndarray,
+        outputs: numpy.ndarray,
+        time_index: int,
+        update_state: bool,
+        shutdown: bool,
+    ) -> None:
+        """Take a single time step on the given inputs.
+
+        Args:
+            inputs: Input values at the current time step. Must be a 1D array of
+              complex values ordered according to :attr:`keys`.
+            outputs: Pre-allocated output array where results will be stored.
+              Same size and type as ``inputs``.
+            time_index: Time series index for the current input.
+            update_state: Whether to update the internal stepper state.
+            shutdown: Whether this is the last call to the single stepping
+              function for the provided :class:`TimeSeries`.
+        """
+        if self._delay > 0:
+            a0, a1 = self._buffer[self._index]
+        else:
+            a0 = inputs[0]
+            a1 = inputs[1]
+
+        factor = self._gain * numpy.exp(1j * self._phi0 * (self._n_eff + self._dn_fc + self._dn_th))
+        outputs[0] = factor * a1
+        outputs[1] = factor * a0
+
+        if update_state:
+            powers = numpy.abs(inputs) ** 2
+            dn_fc0, dn_fc1 = self._dn_fc_interp(powers)
+            dn_th0, dn_th1 = self._dn_th_interp(powers)
+            self._dn_fc = (1.0 - self._alpha_fc) * self._dn_fc + self._alpha_fc * (dn_fc0 + dn_fc1)
+            self._dn_th = (1.0 - self._alpha_th) * self._dn_th + self._alpha_th * (dn_th0 + dn_th1)
+
+            if self._delay > 0:
+                self._buffer[self._index] = inputs
+                self._index = (self._index + 1) % self._delay
+
+
 register_time_stepper_class(DelayedTimeStepper)
+register_time_stepper_class(AnalyticWaveguideTimeStepper)

photonforge/{circuit_time_stepper.py → time_steppers/circuit.py}

@@ -6,10 +6,10 @@ from typing import Any
 
 import numpy
 
-from . import typing as pft
-from .cache import _mode_overlap_cache
-from .circuit_base import _gather_status, _process_component_netlist
-from .extension import (
+from .. import typing as pft
+from ..cache import _mode_overlap_cache
+from ..circuit_base import _process_component_netlist
+from ..extension import (
     Component,
     FiberPort,
     GaussianPort,
@@ -18,7 +18,8 @@ from .extension import (
     config,
     register_time_stepper_class,
 )
-from .tidy3d_model import _align_and_overlap
+from ..models.tidy3d import _align_and_overlap
+from ..utils import _gather_status
 
 
 def _stepper(work_queue, *steppers):