PoleResidueMatrix

class photonforge.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$.

Parameters:

• 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) – 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.

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 = PoleResidueMatrix(
...     poles=[-C_0 / 1.0],
...     residues={("P0", "P0"): [2.0 * C_0, 0.0]},
... )
>>> s_matrix = pole_res(C_0 / 1.55)
>>> s_matrix.elements
{('P0', 'P0'): array([0.11473006+0.46507755j])}

Methods

copy()	Create a copy of this pole_residue_matrix.
enforce_passivity(frequencies[, ...])	Attempt to make the pole-residue matrix passive, while minimizing the perturbation at the specified frequencies.
get_rms_error(s_matrix)	Compute the error between this pole-residue matrix and another S matrix.
is_passive()	Check whether the pole-residue matrix is passive.

Attributes

delays	Delays for each element, in seconds (read only).
frequency_scaling	Frequency scaling factor
poles	Poles for all elements (read only).
ports	Associated ports (read only).
properties	Object properties.
residues	Residues for each element (read only).

copy()

Create a copy of this pole_residue_matrix.

Returns:

New copy.

Return type:

PoleResidueMatrix

delays

Delays for each element, in seconds (read only).

Type:

dict[tuple[str, str], float]

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

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

Parameters:

• 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:

Value representing whether passivity enforcement succeeded.

Return type:

bool

frequency_scaling

Frequency scaling factor

Type:

float

get_rms_error(s_matrix)

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

Parameters:

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

Returns:

The RMS error between matrices.

Return type:

float

is_passive()

Check whether the pole-residue matrix is passive.

Returns:

Passivity result.

Return type:

bool

poles

Poles for all elements (read only).

Type:

ndarray

ports

Associated ports (read only).

Type:

dict[str, Port | FiberPort | GaussianPort | None]

properties

Object properties.

Type:

Properties

residues

Residues for each element (read only).

Type:

dict[tuple[str, str], ndarray]