SMatrixTester

class ip_manager.testing.SMatrixTester

Tools for conveniently testing an S-matrix as part of regression tests.

Is initialized with an ipkiss3.all.circuit_sim.SMatrix1DSweep object, as returned by get_smatrix(wavelengths) on a CircuitModelView.

After initialization, the methods can be used to test properties of the S-matrix.

Examples

from ip_manager.testing import SMatrixTester

def test_mycomponent_smatrix():
    my_cell = MyComponent()
    circuitmodel = my_cell.CircuitModel()
    wavelengths=np.linspace(1.26, 1.36, 101)
    S = circuitmodel.get_smatrix(wavelengths=wavelengths)

    tester = SMatrixTester(S, central_wl=1.31, print_peaks=True)
    assert tester.is_passive()
    # select transmission from port in mode 0 to port out mode 1 for analysis
    tester.select_ports("out:1", "in:0")
    tester.fsr_isclose(0.01)  # FSR should be close to 10nm
    tester.il_isclose(1.2)  # IL should be close to 1.2dB

wavelengths: Wavelength array [um] used by the S-model.

smatrix: S-matrix calculated by the circuit model.

print_peaks: Whether to print peak info when selecting a link.

is_reciprocal()

Returns whether the S-matrix is reciprocal (i.e. symmetric) for almost all calculated wavelengths.

This test is top-level only.

is_passive()

Returns whether the S-matrix is passive for almost all calculated wavelengths.

This test is top-level only.

is_lossless(): Returns whether the S-matrix is lossless (i.e. unitary) for almost all calculated wavelengths.

select_ports(term_from, term_to)

Specifies a term link for future peak tests.

It is recommended that you always call this function after initalisation.

power_at(wl): Returns the linearly interpolated power (magnitude squared) at the given wavelength.

powerdB_at(wl): Returns the linearly interpolated power (magnitude squared) [dB] at the given wavelength.

angle_at(wl): Returns the linearly interpolated complex angle [rad] at the given wavelength.

has_peak_at(centre=1.55, rtol_centre=0.001, test_fwhm=True, fwhm=0.005, rtol_fwhm=0.1)

Returns whether the S-matrix has a peak (positive or negative) at approximately the given wavelength, with approximately the given Full Width Half Maximum or Minimum.

The rtol_centre and rtol_fwhm arguments specify how much relative deviation is allowed, e.g. 0.1 means a maximum of 10%. To discard the FWHM test, supply ‘test_fwhm=False’.

fsr_isclose(desired, rtol=0.01)

Returns whether the free spectral range [um] around central_wl is close to the given value, with the specified tolerance.

rtol: how much relative deviation is allowed, e.g. 0.01 means a maximum of 1%.

il_isclose(desired, rtol=0.001): Returns whether the insertion loss [dB] at central_wl is close to the given value, with the specified tolerance. rtol: how much relative deviation is allowed, e.g. 0.001 means a maximum of 0.1%.

test_port_comparison(expected_values, metric, atol=0.01, amp_threshold=1e-12, wavelengths=None)

Test if the phase or transmission between specified port combinations in the S-matrix matches the expected values.

Parameters:

expected_valuesdict: Dictionary specifying the expected phase or transmission values for each link. Format: {(i, j): expected_value, …}
metric{‘phase’, ‘transmission_dB’, ‘transmission_linear’}: Specifying which metric to compare. The phase values should be in radians. The phase normalized to the [0, 2pi) range (not unwrapped) is compared. The linear transmission is calculated using np.abs(S)**2, where S is the S-matrix.
atolfloat, optional: Absolute tolerance for comparison.
amp_thresholdfloat, optional: Amplitude threshold below which phase comparisons are ignored. Amplitude is calculated as np.abs(S), where S is the S-matrix. Note: if the ‘phase’ metric is used, then even if an amp_threshold value is chosen, it would not be taken it into account.
wavelengthslist, optional: List of wavelengths to consider for comparison. By default, all wavelengths are used.

Returns:

bool: True if all specified port combinations match the expected phase or transmission values within the tolerance, False otherwise.

Raises:

ValueError: If the metric is not ‘phase’, ‘transmission_dB’ or ‘transmission_linear’.