nirfmxvna 26.3.0__py3-none-any.whl

nirfmxvna/s_params_results.py

@@ -0,0 +1,244 @@
+"""Provides methods to fetch and read the SParams measurement results."""
+
+import functools
+
+import nirfmxvna.attributes as attributes
+import nirfmxvna.enums as enums
+import nirfmxvna.errors as errors
+import nirfmxvna.internal._helper as _helper
+
+
+def _raise_if_disposed(f):
+    """From https://stackoverflow.com/questions/5929107/decorators-with-parameters."""
+
+    @functools.wraps(f)
+    def aux(*xs, **kws):
+        meas_obj = xs[0]  # parameter 0 is 'self' which is the measurement object
+        if meas_obj._signal_obj.is_disposed:
+            raise Exception("Cannot access a disposed Vna signal configuration")
+        return f(*xs, **kws)
+
+    return aux
+
+
+class SParamsResults(object):
+    """Provides methods to fetch and read the SParams measurement results."""
+
+    def __init__(self, signal_obj):
+        """Provides methods to fetch and read the SParams measurement results."""
+        self._signal_obj = signal_obj
+        self._session_function_lock = signal_obj._session_function_lock
+        self._interpreter = signal_obj._interpreter
+
+    @_raise_if_disposed
+    def get_correction_state(self, selector_string):
+        r"""Gets the error correction state of the VNA S-Parameter measurement.
+
+        Use "sparam<*n*>" as the selector string to read this attribute.
+
+        +-----------------------+---------------------------------------------------------------------------------------------------------------------+
+        | Name (Value)          | Description                                                                                                         |
+        +=======================+=====================================================================================================================+
+        | None (0)              | Error correction is not applied.                                                                                    |
+        +-----------------------+---------------------------------------------------------------------------------------------------------------------+
+        | Corrected (1)         | Error correction is applied without interpolation using the error terms from the calset.                            |
+        +-----------------------+---------------------------------------------------------------------------------------------------------------------+
+        | Interpolated (2)      | Error correction is applied with error terms for at least one sweep point interpolated from the calset error terms. |
+        +-----------------------+---------------------------------------------------------------------------------------------------------------------+
+        | Settings Modified (3) | Settings during the measurment differ from those used during calibration.                                           |
+        +-----------------------+---------------------------------------------------------------------------------------------------------------------+
+
+        Args:
+            selector_string (string):
+                Pass an empty string.
+
+        Returns:
+            Tuple (attr_val, error_code):
+
+            attr_val (enums.SParamsCorrectionState):
+                Returns the error correction state of the VNA S-Parameter measurement.
+
+            error_code (int):
+                Returns the status code of this method. The status code either indicates success or describes a warning condition.
+        """
+        try:
+            self._session_function_lock.enter_read_lock()
+            updated_selector_string = _helper.validate_and_update_selector_string(
+                selector_string, self._signal_obj
+            )
+            attr_val, error_code = self._interpreter.get_attribute_i32(
+                updated_selector_string,
+                attributes.AttributeID.SPARAMS_RESULTS_CORRECTION_STATE.value,
+            )
+            attr_val = enums.SParamsCorrectionState(attr_val)
+        except (KeyError, ValueError):
+            raise errors.DriverTooNewError()  # type: ignore
+        finally:
+            self._session_function_lock.exit_read_lock()
+
+        return attr_val, error_code
+
+    @_raise_if_disposed
+    def get_correction_level(self, selector_string):
+        r"""Gets the level of error correction applied to the specified S-Parameter measurement.
+
+        Use "sparam<*n*>" as the selector string to read this attribute.
+
+        +--------------+--------------------------------------------------------------------------------------------------------------------------+
+        | Name (value) | Description                                                                                                              |
+        +==============+==========================================================================================================================+
+        | Uncorrected  | Correction is not applied to the configured S-Parameter.                                                                 |
+        +--------------+--------------------------------------------------------------------------------------------------------------------------+
+        | N-Port       | Full N-Port correction is applied to the configured S-Parameter, where N refers to the number of VNA ports involved in   |
+        |              | the correction.                                                                                                          |
+        +--------------+--------------------------------------------------------------------------------------------------------------------------+
+        | 1-Path       | One Path Two Port correction is applied to the configured transmission measurement. Refer to                             |
+        |              | :py:attr:`~nirfmxvna.attributes.AttributeID.CORRECTION_PORT_SUBSET_RESPONSE_PORTS` attribute for more information about  |
+        |              | one-path two-port correction.                                                                                            |
+        +--------------+--------------------------------------------------------------------------------------------------------------------------+
+
+        Args:
+            selector_string (string):
+                Pass an empty string.
+
+        Returns:
+            Tuple (attr_val, error_code):
+
+            attr_val (string):
+                Returns the level of error correction applied to the specified S-Parameter measurement.
+
+            error_code (int):
+                Returns the status code of this method. The status code either indicates success or describes a warning condition.
+        """
+        try:
+            self._session_function_lock.enter_read_lock()
+            updated_selector_string = _helper.validate_and_update_selector_string(
+                selector_string, self._signal_obj
+            )
+            attr_val, error_code = self._interpreter.get_attribute_string(
+                updated_selector_string,
+                attributes.AttributeID.SPARAMS_RESULTS_CORRECTION_LEVEL.value,
+            )
+        finally:
+            self._session_function_lock.exit_read_lock()
+
+        return attr_val, error_code
+
+    @_raise_if_disposed
+    def fetch_x_data(self, selector_string, timeout):
+        r"""Fetches an array of frequency values when you perform S-Parameter measurement with
+        :py:attr:`~nirfmxvna.attributes.AttributeID.SWEEP_TYPE` attribute set to **List** or **Linear** or **Segment**. It
+        fetches an array of time values when you perform S-Parameter measurement with
+        :py:attr:`~nirfmxvna.attributes.AttributeID.SWEEP_TYPE` attribute set to **CW Time**.
+
+        Args:
+            selector_string (string):
+                This parameter specifies a selector string comprising of result name.
+
+                Example:
+
+                ""
+
+                "result::r1"
+
+
+            timeout (float):
+                This parameter specifies the timeout, in seconds, for fetching the specified measurement. Set this value to an
+                appropriate time, longer than expected for fetching the measurement.A value of -1 specifies that the method waits until
+                the measurement is complete. The default value is 10.
+
+        Returns:
+            Tuple (x, error_code):
+
+            x (float):
+                This parameter returns X-Axis Data.
+
+            error_code (int):
+                Returns the status code of this method. The status code either indicates success or describes a warning condition.
+        """
+        try:
+            self._session_function_lock.enter_read_lock()
+            _helper.validate_not_none(selector_string, "selector_string")
+            updated_selector_string = _helper.validate_and_update_selector_string(
+                selector_string, self._signal_obj
+            )
+            x, error_code = self._interpreter.s_params_fetch_x_data(
+                updated_selector_string, timeout
+            )
+        finally:
+            self._session_function_lock.exit_read_lock()
+
+        return x, error_code
+
+    @_raise_if_disposed
+    def fetch_y_data(self, selector_string, timeout):
+        r"""Fetches the S-Parameter data for all :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_FORMAT` types.
+
+        Use "sparam<*n*>" as the selector string to read results from this method.
+
+        For different :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_FORMAT`, the data is returned as follows:
+
+        +----------------------+------------------------------------------------------------------------+-----------------------------------------------------------------------------+
+        | SParam Format        | Y1                                                                     | Y2                                                                          |
+        +======================+========================================================================+=============================================================================+
+        | Magnitude (0)        | Magnitude of the S-Parameter data                                      | Empty array                                                                 |
+        +----------------------+------------------------------------------------------------------------+-----------------------------------------------------------------------------+
+        | Phase (1)            | Phase of the S-Parameter data                                          | Empty array                                                                 |
+        +----------------------+------------------------------------------------------------------------+-----------------------------------------------------------------------------+
+        | Complex (2)          | Real part of the complex S-Parameter data                              | Imaginary part of the complex S-Parameter data                              |
+        +----------------------+------------------------------------------------------------------------+-----------------------------------------------------------------------------+
+        | SWR (3)              | Standing wave ratio computed from the S-Parameter data                 | Empty array                                                                 |
+        +----------------------+------------------------------------------------------------------------+-----------------------------------------------------------------------------+
+        | Smith Impedance (4)  | Real part of the complex impedance computed from the S-Parameter data  | Imaginary part of the complex impedance computed from the S-Parameter data  |
+        +----------------------+------------------------------------------------------------------------+-----------------------------------------------------------------------------+
+        | Smith Admittance (5) | Real part of the complex admittance computed from the S-Parameter data | Imaginary part of the complex admittance computed from the S-Parameter data |
+        +----------------------+------------------------------------------------------------------------+-----------------------------------------------------------------------------+
+        | Polar (6)            | Magnitude of the S-Parameter data                                      | Phase of the S-Parameter data                                               |
+        +----------------------+------------------------------------------------------------------------+-----------------------------------------------------------------------------+
+        | Group Delay (7)      | Group delay computed from the S-Parameter data                         | Empty array                                                                 |
+        +----------------------+------------------------------------------------------------------------+-----------------------------------------------------------------------------+
+
+        Args:
+            selector_string (string):
+                This parameter specifies a selector string comprising of result name, and S-Parameter number.
+
+                Example:
+
+                "sparam0"
+
+                "result::r1/sparam0"
+
+                You can use the :py:meth:`build_s_parameter_string` method to build the selector string.
+
+            timeout (float):
+                This parameter specifies the timeout, in seconds, for fetching the specified measurement. Set this value to an
+                appropriate time, longer than expected for fetching the measurement.A value of -1 specifies that the method waits until
+                the measurement is complete. The default value is 10.
+
+        Returns:
+            Tuple (y1, y2, error_code):
+
+            y1 (float):
+                This parameter returns Y1 data array. You can refer to the method description for interpreting Y data based on
+                :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_FORMAT` type.
+
+            y2 (float):
+                This parameter returns Y2 data array. You can refer to the method description for interpreting Y data based on
+                :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_FORMAT` type.
+
+            error_code (int):
+                Returns the status code of this method. The status code either indicates success or describes a warning condition.
+        """
+        try:
+            self._session_function_lock.enter_read_lock()
+            _helper.validate_not_none(selector_string, "selector_string")
+            updated_selector_string = _helper.validate_and_update_selector_string(
+                selector_string, self._signal_obj
+            )
+            y1, y2, error_code = self._interpreter.s_params_fetch_y_data(
+                updated_selector_string, timeout
+            )
+        finally:
+            self._session_function_lock.exit_read_lock()
+
+        return y1, y2, error_code