pole_residue_fit

photonforge.pole_residue_fit(s_matrix, initial_poles=(), min_poles=0, max_poles=30, loss_factor=0.001, rms_error_tolerance=0.0001, max_iterations=100, max_stale_iterations=3, real=False, passive=True, feedthrough=False, delays=0, stable=True, silence_warnings=False)

Fit S matrix elements with rational functions sharing a set of poles.

If no initial pole guess is provided, the initial guess is evenly spaced over the provided frequencies, logarithmically if real is True and linearly otherwise. Logarithmic spacing requires a positive band, so the initial guess uses the frequency magnitudes |f|.

The fit uses the physics time convention exp(-i 2 pi f t) shared by PhotonForge and Tidy3D: models are evaluated at s = -i h f (see PoleResidueMatrix), so causal responses have poles with negative real part. Data sampled in the engineering exp(+i omega t) convention is anti-causal here and cannot be fit with stable poles; conjugate such data (and negate any known poles) before fitting.

Parameters:

  • s_matrix (SMatrix) – S matrix to be fitted.

  • initial_poles (Sequence[complex]) – Sequence of poles used as initial guess, in the s = -i h f convention. Complex poles should come in conjugate pairs if real is True. If stable is set, poles with positive real part are reflected onto the stable half-plane with a warning.

  • min_poles (int) – Minimal number of poles to try. It has no effect when initial pole guesses are provided.

  • max_poles (int) – Maximal number of poles to try. It has no effect when initial pole guesses are provided.

  • loss_factor (float) – For complex initial pole guesses, ratio between their real and imaginary parts.

  • rms_error_tolerance (float) – RMS error level to break the fitting loop.

  • max_iterations (int) – Maximal number of fitting iterations.

  • max_stale_iterations (int) – Maximal number of iterations without error progress.

  • real (bool) – Whether the poles come in conjugate pairs, representing a real-valued (non-baseband) system.

  • passive (bool) – Whether to attempt to enforce passivity.

  • feedthrough (bool) – Whether to include a feedthrough (constant) term in the pole-residue model.

  • delays (Literal["auto"] | dict[tuple[str, str], float] | float) – 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. If "auto", the delays are estimated from the provided data.

  • stable (bool) – Whether to ensure stability (non-positive real part) of the poles of the resulting model. When False, the signs of initial_poles real parts are respected. Only used for troubleshooting.

  • silence_warnings (bool) – Whether to silence all warnings.

Returns:

Resulting matrix and RMS error.

Return type:

tuple[PoleResidueMatrix, float]

Note

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.