Vector Fitting (`skrf.vectorFitting`)¶

class skrf.vectorFitting.VectorFitting(network)[source]¶

This class provides a Python implementation of the Vector Fitting algorithm and various functions for the fit analysis, passivity evaluation and enforcement, and export of SPICE equivalent circuits.

Parameters: network (skrf.network.Network) – Network instance of the \(N\)-port holding the frequency responses to be fitted, for example a scattering, impedance or admittance matrix.

Examples

Load the Network, create a VectorFitting instance, perform the fit with a given number of real and complex-conjugate starting poles:

>>> nw_3port = skrf.Network('my3port.s3p')
>>> vf = skrf.VectorFitting(nw_3port)
>>> vf.vector_fit(n_poles_real=1, n_poles_cmplx=4)

Notes

The fitting code is based on the original algorithm 1 and on two improvements for relaxed pole relocation 2 and efficient (fast) solving 3. See also the Vector Fitting website 4 for further information and download of the papers listed below. A Matlab implementation is also available there for reference.

References

1: B. Gustavsen, A. Semlyen, “Rational Approximation of Frequency Domain Responses by Vector Fitting”, IEEE Transactions on Power Delivery, vol. 14, no. 3, pp. 1052-1061, July 1999, DOI: https://doi.org/10.1109/61.772353
2: B. Gustavsen, “Improving the Pole Relocating Properties of Vector Fitting”, IEEE Transactions on Power Delivery, vol. 21, no. 3, pp. 1587-1592, July 2006, DOI: https://doi.org/10.1109/TPWRD.2005.860281
3: D. Deschrijver, M. Mrozowski, T. Dhaene, D. De Zutter, “Marcomodeling of Multiport Systems Using a Fast Implementation of the Vector Fitting Method”, IEEE Microwave and Wireless Components Letters, vol. 18, no. 6, pp. 383-385, June 2008, DOI: https://doi.org/10.1109/LMWC.2008.922585
4: Vector Fitting website: https://www.sintef.no/projectweb/vectorfitting/

get_model_response(i, j, freqs=None)[source]¶

Returns one of the frequency responses \(H_{i+1,j+1}\) of the fitted model \(H\).

Parameters

i (int) – Row index of the response in the response matrix.
j (int) – Column index of the response in the response matrix.
freqs (list of float or ndarray or None, optional) – List of frequencies for the response plot. If None, the sample frequencies of the fitted network in network are used.

Returns

response – Model response \(H_{i+1,j+1}\) at the frequencies specified in freqs (complex-valued Numpy array).

Return type

ndarray

is_passive(parameter_type='s')[source]¶

Returns the passivity status of the model as a boolean value.

Parameters: parameter_type (str, optional) – Representation type of the fitted frequency responses. Either scattering (s or S), impedance (z or Z) or admittance (y or Y). Currently, only scattering parameters are supported for passivity evaluation.
Returns: passivity – True if model is passive, else False.
Return type: bool

See also

passivity_test: Verbose passivity evaluation routine.
passivity_enforce: Enforces the passivity of the vector fitted model, if required.

passivity_enforce(n_samples=100, parameter_type='s')[source]¶

Enforces the passivity of the vector fitted model, if required. This is an implementation of the method presented in 5.

Parameters

n_samples (int, optional) – Number of linearly spaced frequency samples at which passivity will be evaluated and enforce. (Default: 100)
parameter_type (str, optional) – Representation type of the fitted frequency responses. Either scattering (s or S), impedance (z or Z) or admittance (y or Y). Currently, only scattering parameters are supported for passivity evaluation.

Returns

Return type

None

Raises

NotImplementedError – If the function is called for parameter_type different than S (scattering).
ValueError – If the function is used with a model containing nonzero proportional coefficients.

See also

is_passive: Returns the passivity status of the model as a boolean value.
passivity_test: Verbose passivity evaluation routine.
plot_passivation: Convergence plot for passivity enforcement iterations.

References

5: T. Dhaene, D. Deschrijver and N. Stevens, “Efficient Algorithm for Passivity Enforcement of S-Parameter- Based Macromodels,” in IEEE Transactions on Microwave Theory and Techniques, vol. 57, no. 2, pp. 415-420, Feb. 2009, DOI: 10.1109/TMTT.2008.2011201.

passivity_test(parameter_type='s')[source]¶

Evaluates the passivity of reciprocal vector fitted models by means of a half-size test matrix 6. Any existing frequency bands of passivity violations will be returned as a sorted list.

Parameters

parameter_type (str, optional) – Representation type of the fitted frequency responses. Either scattering (s or S), impedance (z or Z) or admittance (y or Y). Currently, only scattering parameters are supported for passivity evaluation.

Raises

NotImplementedError – If the function is called for parameter_type different than S (scattering).
ValueError – If the function is used with a model containing nonzero proportional coefficients.

Returns

violation_bands – NumPy array with frequency bands of passivity violation: [[f_start_1, f_stop_1], [f_start_2, f_stop_2], …].

Return type

ndarray

See also

is_passive: Query the model passivity as a boolean value.
passivity_enforce: Enforces the passivity of the vector fitted model, if required.

References

6: B. Gustavsen and A. Semlyen, “Fast Passivity Assessment for S-Parameter Rational Models Via a Half-Size Test Matrix,” in IEEE Transactions on Microwave Theory and Techniques, vol. 56, no. 12, pp. 2701-2708, Dec. 2008, DOI: 10.1109/TMTT.2008.2007319.

plot_convergence(ax=None)[source]¶

Plots the history of the model residue parameter d_res during the iterative pole relocation process of the vector fitting, which should eventually converge to a fixed value. Additionally, the relative change of the maximum singular value of the coefficient matrix A are plotted, which serve as a convergence indicator.

Parameters: ax (matplotlib.Axes object or None) – matplotlib axes to draw on. If None, the current axes is fetched with gca().
Returns: matplotlib axes used for drawing. Either the passed ax argument or the one fetch from the current figure.
Return type: matplotlib.Axes

plot_passivation(ax=None)[source]¶

Plots the history of the greatest singular value during the iterative passivity enforcement process, which should eventually converge to a value slightly lower than 1.0 or stop after exceeding the maximum number of iterations specified in the class variable history_max_sigma.

Parameters: ax (matplotlib.Axes object or None) – matplotlib axes to draw on. If None, the current axes is fetched with gca().
Returns: matplotlib axes used for drawing. Either the passed ax argument or the one fetch from the current figure.
Return type: matplotlib.Axes

plot_pz(i, j, ax=None)[source]¶

Plots a pole-zero diagram of the fit of the model response \(H_{i+1,j+1}\).

Parameters

i (int) – Row index of the response.
j (int) – Column index of the response.
ax (matplotlib.Axes object or None) – matplotlib axes to draw on. If None, the current axes is fetched with gca().

Returns

matplotlib axes used for drawing. Either the passed ax argument or the one fetch from the current figure.

Return type

matplotlib.Axes

plot_s_db(i, j, freqs=None, ax=None)[source]¶

Plots the magnitude in dB of the scattering parameter response \(S_{i+1,j+1}\) in the fit.

Parameters

i (int) – Row index of the response.
j (int) – Column index of the response.
freqs (list of float or ndarray or None, optional) – List of frequencies for the response plot. If None, the sample frequencies of the fitted network in network are used.
ax (matplotlib.Axes object or None) – matplotlib axes to draw on. If None, the current axes is fetched with gca().

Returns

matplotlib axes used for drawing. Either the passed ax argument or the one fetch from the current figure.

Return type

matplotlib.Axes

plot_s_mag(i, j, freqs=None, ax=None)[source]¶

Plots the magnitude in linear scale of the scattering parameter response \(S_{i+1,j+1}\) in the fit.

Parameters

i (int) – Row index of the response.
j (int) – Column index of the response.
freqs (list of float or ndarray or None, optional) – List of frequencies for the response plot. If None, the sample frequencies of the fitted network in network are used.
ax (matplotlib.Axes object or None) – matplotlib axes to draw on. If None, the current axes is fetched with gca().

Returns

matplotlib axes used for drawing. Either the passed ax argument or the one fetch from the current figure.

Return type

matplotlib.Axes

plot_s_singular(freqs=None, ax=None)[source]¶

Plots the singular values of the vector fitted S-matrix in linear scale.

Parameters

freqs (list of float or ndarray or None, optional) – List of frequencies for the response plot. If None, the sample frequencies of the fitted network in network are used.
ax (matplotlib.Axes object or None) – matplotlib axes to draw on. If None, the current axes is fetched with gca().

Returns

matplotlib axes used for drawing. Either the passed ax argument or the one fetch from the current figure.

Return type

matplotlib.Axes

read_npz(file)[source]¶

Reads all model parameters poles, zeros, proportional_coeff and constant_coeff from a labeled NumPy .npz file.

Parameters: file (str) – NumPy .npz file containing the parameters. See notes.
Returns
Return type: None

Notes

The .npz file needs to include the model parameters as individual NumPy arrays (ndarray) labeled ‘poles’, ‘zeros’, ‘proportionals’ and ‘constants’. The shapes of those arrays need to match the network properties in network (correct number of ports). Preferably, the .npz file was created by write_npz().

See also

write_npz: Writes all model parameters to a .npz file

vector_fit(n_poles_real=2, n_poles_cmplx=2, init_pole_spacing='lin', parameter_type='s', fit_constant=True, fit_proportional=False)[source]¶

Main work routine performing the vector fit. The results will be stored in the class variables poles, zeros, proportional_coeff and constant_coeff.

Parameters

n_poles_real (int, optional) – Number of initial real poles. See notes.
n_poles_cmplx (int, optional) – Number of initial complex conjugate poles. See notes.
init_pole_spacing (str, optional) – Type of initial pole spacing across the frequency interval of the S-matrix. Either linear (lin) or logarithmic (log).
parameter_type (str, optional) – Representation type of the frequency responses to be fitted. Either scattering (s or S), impedance (z or Z) or admittance (y or Y). As scikit-rf can currently only read S parameters from a Touchstone file, the fit should also be performed on the original S parameters. Otherwise, scikit-rf will convert the responses from S to Z or Y, which might work for the fit but can cause other issues.
fit_constant (bool, optional) – Include a constant term d in the fit.
fit_proportional (bool, optional) – Include a proportional term e in the fit.

Returns

No return value.

Return type

None

Notes

The required number of real or complex conjugate starting poles depends on the behaviour of the frequency responses. To fit a smooth response such as a low-pass characteristic, 1-3 real poles and no complex conjugate poles is usually sufficient. If resonances or other types of peaks are present in some or all of the responses, a similar number of complex conjugate poles is required. Be careful not to use too many poles, as excessive poles will not only increase the computation workload during the fitting and the subsequent use of the model, but they can also introduce unwanted resonances at frequencies well outside the fit interval.

write_npz(path)[source]¶

Writes the model parameters in poles, zeros, proportional_coeff and constant_coeff to a labeled NumPy .npz file.

Parameters: path (str) – Target path without filename for the export. The filename will be added automatically based on the network name in network
Returns
Return type: None

See also

read_npz: Reads all model parameters from a .npz file

write_spice_subcircuit_s(file)[source]¶

Creates an equivalent N-port SPICE subcircuit based on its vector fitted S parameter responses.

Parameters: file (str) – Path and filename including file extension (usually .sp) for the SPICE subcircuit file.
Returns
Return type: None

Notes

In the SPICE subcircuit, all ports will share a common reference node (global SPICE ground on node 0). The equivalent circuit uses linear dependent current sources on all ports, which are controlled by the currents through equivalent admittances modelling the parameters from a vector fit. This approach is based on 7.

References

7: G. Antonini, “SPICE Equivalent Circuits of Frequency-Domain Responses”, IEEE Transactions on Electromagnetic Compatibility, vol. 45, no. 3, pp. 502-512, August 2003, DOI: https://doi.org/10.1109/TEMC.2003.815528

constant_coeff¶: Instance variable holding the list of fitted constants. Will be initialized by vector_fit().

max_iterations¶: Instance variable specifying the maximum number of iterations for the fitting process. To be changed by the user before calling vector_fit().

max_tol¶: Instance variable specifying the convergence criterion in terms of relative tolerance. To be changed by the user before calling vector_fit().

poles¶: Instance variable holding the list of fitted poles. Will be initialized by vector_fit().

proportional_coeff¶: Instance variable holding the list of fitted proportional coefficients. Will be initialized by vector_fit().

zeros¶: Instance variable holding the list of fitted zeros. Will be initialized by vector_fit().

Vector Fitting (skrf.vectorFitting)¶

Vector Fitting (`skrf.vectorFitting`)¶