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

photonforge/time_steppers/math.py

@@ -0,0 +1,331 @@
+from collections.abc import Sequence
+from typing import Literal
+
+import numpy
+
+from ..extension import (
+    Component,
+    Expression,
+    TimeStepper,
+    register_time_stepper_class,
+)
+from ..typing import FieldAmplitude, annotate
+
+
+class ExpressionTimeStepper(TimeStepper):
+    r"""Expression time stepper for electrical signals.
+
+    Args:
+        expressions: Dictionary of expression strings for all output ports,
+          indexed by name.
+
+    Example:
+        Example time stepper to be used on a component with 3 electrical
+        ports: "E0", "E1", "E2". The first has a 0.1 reflection coefficient,
+        the second has no output (zero, by default), and the third has a
+        non-linear combination of all 3 inputs.
+
+        >>> time_stepper = pf.ExpressionTimeStepper(
+        ...     expressions={
+        ...         "E0": "0.1 * E0",
+        ...         "E2": "0.5 * E0 * E2 + abs(E1) * E1",
+        ...     }
+        ... )
+
+    Note:
+        Expressions can use all operators supported by :class:`Expression`.
+    """
+
+    def __init__(self, *, expressions: dict[str, str]):
+        super().__init__(expressions=expressions)
+
+    def setup_state(self, *, component: Component, **kwargs):
+        """Initialize internal state.
+
+        Args:
+            component: Component representing the time stepper.
+            kwargs: Unused.
+        """
+        expressions = self.parametric_kwargs["expressions"]
+        component_ports = sorted(component.select_ports("electrical"))
+        if any(port not in component_ports for port in expressions):
+            raise RuntimeError(
+                f"Not all ports required by ExpressionTimeStepper were found in component "
+                f"{component.name!r}."
+            )
+        self.keys = tuple(port + "@0" for port in component_ports)
+        self.expression = Expression(
+            component_ports, [expressions.get(port, "0.0") for port in component_ports]
+        )
+
+    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`.
+        """
+        numpy.copyto(outputs, self.expression(*inputs.real))
+
+
+class DifferentialTimeStepper(TimeStepper):
+    r"""Time stepper for differentiating electrical signals in time.
+
+    The "backwards" scheme, implements:
+
+    .. math:: y_k = s \frac{x_k - x_{k-1}}{\Delta t}
+
+    whereas the "central" scheme uses:
+
+    .. math:: y_k = s \frac{x_k - x_{k-2}}{2 \Delta t}
+
+    Args:
+        scheme: Differentiation scheme.
+        scale: Output scaling factor :math:`s`.
+        output_port: Name of the port used as output. If ``None``, the last
+          port is used (in the sorted list of ports).
+    """
+
+    def __init__(
+        self,
+        *,
+        scheme: Literal["backwards", "central"] = "backwards",
+        scale: annotate(float, units="s") = 1.0,
+        output_port: str | None = None,
+    ):
+        super().__init__(scheme=scheme, scale=scale, output_port=output_port)
+
+    def setup_state(self, *, time_step: float, component: Component, **kwargs):
+        """Initialize internal state.
+
+        Args:
+            time_step: The interval between time steps (in seconds).
+            component: Component representing the time stepper.
+            kwargs: Unused.
+        """
+        p = self.parametric_kwargs
+        component_ports = sorted(component.select_ports("electrical"))
+        if len(component_ports) != 2:
+            raise RuntimeError(
+                f"DifferentialTimeStepper can only be used on components with 2 electrical "
+                f"ports. Component {component.name!r} has {len(component_ports)}."
+            )
+
+        output_port = p["output_port"]
+        if output_port == component_ports[0]:
+            component_ports = (component_ports[1], component_ports[0])
+        elif output_port is not None and output_port != component_ports[1]:
+            raise RuntimeError(
+                f"Port {output_port!r} required by DifferentialTimeStepper was not found in "
+                f"component {component.name!r}."
+            )
+        self.keys = tuple(p + "@0" for p in component_ports)
+
+        scheme = p["scheme"]
+        if scheme not in ("backwards", "central"):
+            raise ValueError("DifferentialTimeStepper 'scheme' must be 'backwards' or 'central'.")
+        self._buffer = numpy.empty(1 if scheme == "backwards" else 2)
+        self._scale = p["scale"] / (self._buffer.size * time_step)
+
+        self.reset()
+
+    def reset(self):
+        self._buffer[:] = 0.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`.
+        """
+        x = inputs[0].real
+        outputs[1] = self._scale * (x - self._buffer[0])
+
+        if update_state:
+            if self._buffer.size == 1:
+                self._buffer[0] = x
+            else:
+                self._buffer[0] = self._buffer[1]
+                self._buffer[1] = x
+
+
+class IntegralTimeStepper(TimeStepper):
+    r"""Time stepper for integrating electrical signals in time.
+
+    .. math:: y_k = y_{k - 1} + s x_k \Delta t
+
+    Args:
+        scale: Input scaling factor :math:`s`.
+        start_value: Starting output value after reset.
+        limits: Output value limits.
+        output_port: Name of the port used as output. If ``None``, the last
+          port is used (in the sorted list of ports).
+        reset_port: Name of the port used as reset signal. If ``None``, the
+          reset feature is disabled.
+        reset_trigger: Type of edge used for triggering a reset.
+        reset_tolerance: Value change tolerance for triggering a reset.
+    """
+
+    def __init__(
+        self,
+        *,
+        scale: annotate(float, units="s⁻¹") = 1.0,
+        start_value: FieldAmplitude = 0.0,
+        limits: annotate(Sequence[FieldAmplitude | None], minItems=2, maxItems=2) = (
+            None,
+            None,
+        ),
+        output_port: str | None = None,
+        reset_port: str | None = None,
+        reset_trigger: Literal["fall", "rise", "both"] = "rise",
+        reset_tolerance: float = 0.0,
+    ):
+        super().__init__(
+            scale=scale,
+            start_value=start_value,
+            limits=limits,
+            output_port=output_port,
+            reset_port=reset_port,
+            reset_trigger=reset_trigger,
+            reset_tolerance=reset_tolerance,
+        )
+
+    def setup_state(self, *, time_step: float, component: Component, **kwargs):
+        """Initialize internal state.
+
+        Args:
+            time_step: The interval between time steps (in seconds).
+            component: Component representing the time stepper.
+            kwargs: Unused.
+        """
+        p = self.parametric_kwargs
+        reset_port = p["reset_port"]
+        output_port = p["output_port"]
+
+        required_ports = 2 if reset_port is None else 3
+        component_ports = sorted(component.select_ports("electrical"))
+        if len(component_ports) != required_ports:
+            raise RuntimeError(
+                f"IntegralTimeStepper can only be used on components with {required_ports} "
+                f"electrical ports. Component {component.name!r} has {len(component_ports)}."
+            )
+        for required in (output_port, reset_port):
+            if required is not None and required not in component_ports:
+                raise RuntimeError(
+                    f"Port {required!r} required by IntegralTimeStepper was not found in "
+                    f"component {component.name!r}."
+                )
+
+        if reset_port is not None:
+            component_ports.remove(reset_port)
+            if reset_port == output_port:
+                raise ValueError("'output_port' and 'reset_port' cannot be the same.")
+
+        if output_port is None:
+            input_port, output_port = component_ports
+        else:
+            component_ports.remove(output_port)
+            input_port = component_ports[0]
+
+        if reset_port is None:
+            self.keys = (input_port + "@0", output_port + "@0")
+        else:
+            self.keys = (input_port + "@0", output_port + "@0", reset_port + "@0")
+
+        self._reset_trigger = p["reset_trigger"]
+        if self._reset_trigger not in ("fall", "rise", "both"):
+            raise ValueError(
+                "IntegralTimeStepper 'reset_trigger' must be 'fall', 'rise', or 'both'."
+            )
+
+        self._scale = p["scale"] * time_step
+        self._y0 = p["start_value"]
+        self._reset_tolerance = abs(p["reset_tolerance"])
+
+        self._y_lo, self._y_hi = p["limits"]
+        if self._y_lo is None:
+            self._y_lo = -numpy.inf
+        if self._y_hi is None:
+            self._y_hi = numpy.inf
+
+        self.reset()
+
+    def reset(self):
+        self._y = self._y0
+        self._r = 0.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 len(self.keys) == 3:
+            r = inputs[2].real
+        else:
+            r = 0.0
+
+        edge = r - self._r
+        if len(self.keys) == 3 and (
+            (edge > self._reset_tolerance and self._reset_trigger != "fall")
+            or (-edge > self._reset_tolerance and self._reset_trigger != "rise")
+        ):
+            y = self._y0
+        else:
+            y = self._y + self._scale * inputs[0].real
+
+        y = min(self._y_hi, max(self._y_lo, y))
+        outputs[1] = y
+
+        if update_state:
+            self._y = y
+            self._r = r
+
+
+register_time_stepper_class(ExpressionTimeStepper)
+register_time_stepper_class(DifferentialTimeStepper)
+register_time_stepper_class(IntegralTimeStepper)

photonforge/{modulator_time_steppers.py → time_steppers/modulator.py}

@@ -5,9 +5,7 @@ from typing import Literal
 
 import numpy
 
-from .analytic_models import _port_with_x_section
-from .circuit_base import _gather_status
-from .extension import (
+from ..extension import (
     Component,
     Interpolator,
     Port,
@@ -16,8 +14,9 @@ from .extension import (
     TimeStepper,
     register_time_stepper_class,
 )
-from .tidy3d_model import _isotropic_uniform, _ModeSolverRunner
-from .typing import (
+from ..models.analytic import _port_with_x_section
+from ..models.tidy3d import _isotropic_uniform, _ModeSolverRunner
+from ..typing import (
     Coordinate,
     Frequency,
     Impedance,
@@ -27,7 +26,7 @@ from .typing import (
     TimeDelay,
     annotate,
 )
-from .utils import C_0, route_length
+from ..utils import C_0, _gather_status, route_length
 
 
 def _impedance_monitor(time_stepper, runner):
@@ -220,10 +219,7 @@ class PhaseModTimeStepper(TimeStepper):
                 "PhaseModTimeStepper can only be used in components with 2 optical and 1 "
                 "electrical ports."
             )
-        self._e = e_ports[0] + "@0"
-        self._opt0 = ports[0] + "@0"
-        self._opt1 = ports[1] + "@0"
-        self.keys = (self._opt0, self._opt1, self._e)
+        self.keys = (ports[0] + "@0", ports[1] + "@0", e_ports[0] + "@0")
 
         p = self.parametric_kwargs
 
@@ -308,9 +304,7 @@ class PhaseModTimeStepper(TimeStepper):
         if update_state:
             self._v = v
             if self._delay > 0:
-                a0 = inputs[0]
-                a1 = inputs[1]
-                self._buffer[self._index] = (a0, a1)
+                self._buffer[self._index] = inputs[:2]
                 self._index = (self._index + 1) % self._delay
 
 
@@ -485,10 +479,7 @@ class TerminatedModTimeStepper(TimeStepper):
                     f"Optical input port {port_name!r} not found in component {component.name!r}."
                 )
         e_port = e_ports[0]
-        self._e = e_port + "@0"
-        self._opt0 = ports[0] + "@0"
-        self._opt1 = ports[1] + "@0"
-        self.keys = (self._opt0, self._opt1, self._e)
+        self.keys = (ports[0] + "@0", ports[1] + "@0", e_port + "@0")
 
         f_nyquist = 0.5 / time_step
         self._freqs = numpy.linspace(0, f_nyquist, p["fir_taps"])
@@ -784,9 +775,7 @@ class TerminatedModTimeStepper(TimeStepper):
             self._v[1:] = self._v[:-1]
             self._v[0] = v_in
             if self._delay > 0:
-                a0 = inputs[0]
-                a1 = inputs[1]
-                self._buffer[self._index] = (a0, a1)
+                self._buffer[self._index] = inputs[:2]
                 self._index = (self._index + 1) % self._delay
 
 

photonforge/{s_matrix_time_stepper.py → time_steppers/s_matrix.py}

@@ -6,8 +6,8 @@ from typing import Any, Literal
 
 import numpy
 
-from .cache import _pole_residue_fit_cache
-from .extension import (
+from ..cache import _pole_residue_fit_cache
+from ..extension import (
     Component,
     PoleResidueMatrix,
     SMatrix,
@@ -19,7 +19,7 @@ from .extension import (
     pole_residue_fit,
     register_time_stepper_class,
 )
-from .typing import Frequency, NonNegativeInt, PositiveFloat, PositiveInt, TimeDelay
+from ..typing import Frequency, NonNegativeInt, PositiveFloat, PositiveInt, TimeDelay
 
 
 class SMatrixTimeStepper(TimeStepper):

photonforge/{sink_time_steppers.py → time_steppers/sink.py}

@@ -2,9 +2,8 @@ import numpy
 from numpy.random import SeedSequence, default_rng
 from scipy.signal import firwin2
 
-from .extension import Component, Interpolator, TimeStepper, register_time_stepper_class
-from .modulator_time_steppers import _get_impedance_runner
-from .typing import (
+from ..extension import Component, Interpolator, TimeStepper, register_time_stepper_class
+from ..typing import (
     Frequency,
     Impedance,
     NonNegativeFloat,
@@ -13,7 +12,8 @@ from .typing import (
     TimeDelay,
     annotate,
 )
-from .utils import Q as _Q
+from ..utils import Q as _Q
+from .modulator import _get_impedance_runner
 
 _PINK_TAPS = 2048
 _PINK_SAMPLES = 100
@@ -202,9 +202,7 @@ class PhotodiodeTimeStepper(TimeStepper):
                 "PhotodiodeTimeStepper can only be used in components with 1 optical port and 1 "
                 "electrical port."
             )
-        self._port = ports[0] + "@0"
-        self._e_port = e_ports[0] + "@0"
-        self.keys = (self._port, self._e_port)
+        self.keys = (ports[0] + "@0", e_ports[0] + "@0")
 
         self._time_step = time_step
 
@@ -222,7 +220,7 @@ class PhotodiodeTimeStepper(TimeStepper):
         tau = p["current_time_constant"]
         if tau <= 0:
             tau = 100 * time_step
-        self._current_factor = 1 - numpy.exp(-time_step / tau)
+        self._current_factor = 1.0 - numpy.exp(-time_step / tau)
 
         self._filter = None
         if p["filter_frequency"] > 0:

photonforge/{source_time_steppers.py → time_steppers/source.py}

@@ -7,7 +7,7 @@ import numpy
 from numpy.random import SeedSequence, default_rng
 from scipy.integrate import solve_ivp
 
-from .extension import (
+from ..extension import (
     Component,
     Interpolator,
     TimeStepper,
@@ -16,9 +16,9 @@ from .extension import (
     _prbs31,
     register_time_stepper_class,
 )
-from .modulator_time_steppers import _get_impedance_runner
-from .typing import (
+from ..typing import (
     Angle,
+    FieldAmplitude,
     Fraction,
     Frequency,
     Impedance,
@@ -30,7 +30,8 @@ from .typing import (
     TimeDelay,
     annotate,
 )
-from .utils import C_0, H, Q
+from ..utils import C_0, H, Q
+from .modulator import _get_impedance_runner
 
 RIN = annotate(NonNegativeFloat, label="Relative Intensity Noise", units="1/Hz")
 
@@ -110,8 +111,7 @@ class CWLaserTimeStepper(TimeStepper):
             raise RuntimeError(
                 "CWLaserTimeStepper can only be used in components with 1 optical port."
             )
-        self._port = next(iter(ports)) + "@0"
-        self.keys = (self._port,)
+        self.keys = (next(iter(ports)) + "@0",)
 
         p = self.parametric_kwargs
 
@@ -347,19 +347,24 @@ class DMLaserTimeStepper(TimeStepper):
                 "PhotodiodeTimeStepper can only be used in components with 1 optical port and 1 "
                 "electrical port."
             )
-        self._port = ports[0] + "@0"
-        self._e_port = e_ports[0] + "@0"
-        self.keys = (self._port, self._e_port)
+        self.keys = (ports[0] + "@0", e_ports[0] + "@0")
 
         self._time_step = time_step
 
         p = self.parametric_kwargs
+
         self._r = complex(p["reflection"])
+
+        n_group = p["n_group"]
+        if n_group == 0.0:
+            raise RuntimeError("'n_group' cannot be zero.")
+        self._vg_a0 = C_0 * 1e-6 / n_group * p["differential_gain"]
+
         self._kp = float(
             (H * carrier_frequency * p["quantum_efficiency"] * p["active_region_volume"])
             / (2.0 * p["confinement_factor"] * p["photon_lifetime"])
         )
-        self._vg_a0 = C_0 * 1e-6 / p["n_group"] * p["differential_gain"]
+
         self._tau_n = p["carrier_lifetime"]
         self._gamma = p["confinement_factor"]
         self._eps = p["gain_compression_factor"]
@@ -548,8 +553,7 @@ class OpticalPulseTimeStepper(TimeStepper):
             raise RuntimeError(
                 "OpticalPulseTimeStepper can only be used in components with 1 optical port."
             )
-        self._port = next(iter(ports)) + "@0"
-        self.keys = (self._port,)
+        self.keys = (next(iter(ports)) + "@0",)
 
         repetition_rate = p["repetition_rate"]
         if repetition_rate > 0.5 / time_step:
@@ -747,8 +751,7 @@ class OpticalNoiseTimeStepper(TimeStepper):
             raise RuntimeError(
                 "OpticalNoiseTimeStepper can only be used in components with 1 optical port."
             )
-        self._port = next(iter(ports)) + "@0"
-        self.keys = (self._port,)
+        self.keys = (next(iter(ports)) + "@0",)
 
         p = self.parametric_kwargs
 
@@ -835,8 +838,8 @@ class WaveformTimeStepper(TimeStepper):
         self,
         *,
         frequency: Frequency,
-        amplitude: annotate(float, units="√W") = 1,
-        offset: annotate(float, units="√W") = 0,
+        amplitude: FieldAmplitude = 1,
+        offset: FieldAmplitude = 0,
         start: Time | None = None,
         stop: Time | None = None,
         waveform: Literal["sine", "triangle", "trapezoid", "raised-cosine", "gaussian"] = "sine",
@@ -883,8 +886,7 @@ class WaveformTimeStepper(TimeStepper):
             raise RuntimeError(
                 "WaveformTimeStepper can only be used in components with 1 electrical port."
             )
-        self._port = next(iter(ports)) + "@0"
-        self.keys = (self._port,)
+        self.keys = (next(iter(ports)) + "@0",)
 
         freq = p["frequency"]
         if freq > 0.5 / time_step:

photonforge/typing.py

@@ -265,7 +265,12 @@ Voltage = annotate(float, units="V")  #:
 Impedance = annotate(complex, units="Ω")  #:
 
 Power = annotate(float, minimum=0, units="W")  #:
+Power_dBm = annotate(float, units="dBm")  #:
 
+FieldAmplitude = annotate(float, units="√W")  #:
+ComplexFieldAmplitude = annotate(complex, units="√W")  #:
+
+Gain = annotate(float, units="dB")  #:
 Loss = annotate(float, minimum=0, units="dB")  #:
 PropagationLoss = annotate(float, minimum=0, units="dB/μm")  #: