PoleResidueMatrix

PoleResidueMatrix(
    poles, residues, frequency_scaling=6.283185, ports=None, delays=None
)

Pole-residue representation of an S matrix.

Each element $v$ is represented by a rational function of the form:

$$S_v = e^{i 2 \pi f d} \sum_{n=0}^{N-1} \frac{r_{vn}}{s - p_n} + r_{vN}$$

in which $p_n$ are the poles (shared by all elements) and $r_{vn}$ are the residues for matrix element $v$, $d$ is the delay, $h$ is a frequency scaling factor, and $s = -i h f$.

Args

• poles (Sequence[float]): Complex poles shared by all matrix elements.
• residues (dict[tuple[str, str] | Sequence[complex]]): Residues, one per matrix element. Each item is a sequence of complex residues used for that element.
• frequency_scaling (float): Scaling applied to the frequencies in evaluation.
• ports (dict[str, Port | FiberPort | GaussianPort | None] | None): Mapping from port names to ports or to None.
• delays (dict[tuple[str, str], float] | float | None): Explicit time delays (in seconds), one per matrix element. Missing elements have no time delay applied. If a single number is given, this is used as a global delay for all matrix elements.

Note

The number of residues for each element is 1 more that the number of poles because of the last term in the representation.

The variable s = -i h f follows the physics time convention exp(-i 2 pi f t) used throughout PhotonForge and Tidy3D: causal (stable) responses have poles with negative real part. Poles taken from the engineering exp(+i omega t) convention must be negated.

Including explicit delays in the model can reduce the number of poles required to obtain a good fit. However, if the delays are too large, it can be difficult to obtain a good stable fit.

Example

An SMatrix instance can be obtained by calling an instance of PoleResidueMatrix with the desired frequencies:

>>> pole_res = pf.PoleResidueMatrix(
...     poles=[-pf.C_0 / 1.0],
...     residues={("P0", "P0"): [2.0 * pf.C_0, 0.0]},
... )
>>> s_matrix = pole_res(pf.C_0 / 1.55)
>>> s_matrix.elements
{('P0', 'P0'): array([...])}

Methods

Method	Description
copy	Create a copy of this pole_residue_matrix.
enforce_passivity	Attempt to make the pole-residue matrix passive, while minimizing the
get_rms_error	Compute the error between this pole-residue matrix and another S matrix.
is_passive	Check whether the pole-residue matrix is passive.

copy

copy(self)

Create a copy of this pole_residue_matrix.

Returns

PoleResidueMatrix: New copy.

enforce_passivity

enforce_passivity(
    self, frequencies, max_iterations=20, real=False, feedthrough=False
)

Attempt to make the pole-residue matrix passive, while minimizing the perturbation at the specified frequencies.

Args

• frequencies (Sequence[float]): Frequencies at which the perturbation should be minimized. This is usually the frequencies of the S matrix data being fit.
• max_iterations (int): Maximal number of passivity enforcement iterations.
• real (bool): Whether the poles come in conjugate pairs, representing a real-valued (non-baseband) system.
• feedthrough (bool): Whether to include a feedthrough (constant) term in the pole-residue model.

Returns

bool: Value representing whether passivity enforcement succeeded.

get_rms_error

get_rms_error(self, s_matrix)

Compute the error between this pole-residue matrix and another S matrix.

Args

• s_matrix (SMatrix): S matrix to compare and calculate the RMS error.

Returns

float: The RMS error between matrices.

is_passive

is_passive(self)

Check whether the pole-residue matrix is passive.

Returns

bool: Passivity result.

Attributes

Attribute	Description
delays	dict[tuple[str, str], float]: Delays for each element, in seconds (read only).
frequency_scaling	float: Frequency scaling factor
poles	ndarray: Poles for all elements (read only).
ports	dict[str, Port | FiberPort | GaussianPort | None]: Associated ports (read only).
properties	Properties: Object properties.
residues	dict[tuple[str, str], ndarray]: Residues for each element (read only).

delays

dict[tuple[str, str], float]: Delays for each element, in seconds (read only).

frequency_scaling

float: Frequency scaling factor

poles

ndarray: Poles for all elements (read only).

ports

dict[str, Port | FiberPort | GaussianPort | None]: Associated ports (read only).

properties

Properties: Object properties.

residues

dict[tuple[str, str], ndarray]: Residues for each element (read only).