nirfmxvna 26.3.0__py3-none-any.whl

nirfmxvna/marker_configuration.py

@@ -0,0 +1,429 @@
+"""Provides methods to configure the Marker measurement."""
+
+import functools
+
+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 MarkerConfiguration(object):
+    """Provides methods to configure the Marker measurement."""
+
+    def __init__(self, signal_obj):
+        """Provides methods to configure the Marker measurement."""
+        self._signal_obj = signal_obj
+        self._session_function_lock = signal_obj._session_function_lock
+        self._interpreter = signal_obj._interpreter
+
+    @_raise_if_disposed
+    def configure_number_of_markers(self, selector_string, number_of_markers):
+        r"""Configures the number of markers.
+
+        Args:
+            selector_string (string):
+                Pass an empty string.
+                The signal name that is passed when creating the signal configuration is used.
+
+            number_of_markers (int):
+                This parameter specifies the number of markers. If you increase number of markers from N to N+K, then existing N
+                markers are not affected but K new markers are added. If you reduce number of markers from N to N-K, then last K
+                markers are deleted without affecting the remaining N-K markers.
+
+        Returns:
+            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
+            )
+            error_code = self._interpreter.marker_configure_number_of_markers(
+                updated_selector_string, number_of_markers
+            )
+        finally:
+            self._session_function_lock.exit_read_lock()
+
+        return error_code
+
+    @_raise_if_disposed
+    def configure_type(self, selector_string, marker_type):
+        r"""Configures the marker type.
+        Use "marker<*n*>" as the selector string to configure this method.
+
+        Args:
+            selector_string (string):
+                Specifies a selector string. Pass an empty string.
+
+            marker_type (enums.MarkerType, int):
+                This parameter specifies whether the marker is disabled (Off) or is enabled (On) as a normal marker, delta marker or a
+                fixed marker. The default value is **Off**.
+
+                +--------------+-------------------------------------------+
+                | Name (Value) | Description                               |
+                +==============+===========================================+
+                | Off (0)      | The marker is disabled.                   |
+                +--------------+-------------------------------------------+
+                | Normal (1)   | The marker is enabled as a normal marker. |
+                +--------------+-------------------------------------------+
+                | Delta (3)    | The marker is enabled as a delta marker.  |
+                +--------------+-------------------------------------------+
+                | Fixed (4)    | The marker is enabled as a fixed marker.  |
+                +--------------+-------------------------------------------+
+
+        Returns:
+            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")
+            marker_type = (
+                marker_type.value if type(marker_type) is enums.MarkerType else marker_type
+            )
+            updated_selector_string = _helper.validate_and_update_selector_string(
+                selector_string, self._signal_obj
+            )
+            error_code = self._interpreter.marker_configure_type(
+                updated_selector_string, marker_type
+            )
+        finally:
+            self._session_function_lock.exit_read_lock()
+
+        return error_code
+
+    @_raise_if_disposed
+    def configure_reference_marker(self, selector_string, reference_marker):
+        r"""Configures an associated reference marker for a delta marker. Markers with Marker Type attribute set to Delta must be
+        associated with a reference marker. You cannot associate a reference marker for other markers whose Marker Type is not
+        Delta.
+
+        Use "marker<*n*>" as the selector string to configure this method.
+
+        Args:
+            selector_string (string):
+                Specifies a selector string. Pass an empty string.
+
+            reference_marker (int):
+                This parameter specifies the marker index to be used as reference for the specified delta marker. All types of markers
+                including **Normal**, **Delta** and **Fixed** can be used as a reference marker.
+
+        Returns:
+            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
+            )
+            error_code = self._interpreter.marker_configure_reference_marker(
+                updated_selector_string, reference_marker
+            )
+        finally:
+            self._session_function_lock.exit_read_lock()
+
+        return error_code
+
+    @_raise_if_disposed
+    def configure_x(self, selector_string, marker_x):
+        r"""Configures the X value of the marker. You must configure the X value of reference marker or perform any marker search
+        operation on the reference marker before configuring the X value for the **Delta** marker.
+
+        Use "marker<*n*>" as the selector string to configure this method.
+
+        Args:
+            selector_string (string):
+                Specifies a selector string. Pass an empty string.
+
+            marker_x (float):
+                This parameter specifies the X value of the marker on the trace when you set the Marker Type to **Normal** or
+                **Fixed**. The X value of the delta marker is relative to the X value of the reference marker when you set the Marker
+                Type to **Delta**.
+
+        Returns:
+            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
+            )
+            error_code = self._interpreter.marker_configure_x(updated_selector_string, marker_x)
+        finally:
+            self._session_function_lock.exit_read_lock()
+
+        return error_code
+
+    @_raise_if_disposed
+    def configure_y(self, selector_string, marker_y1, marker_y2):
+        r"""Configures the Y value of the marker. You can configure the Y location of **Fixed** markers only. Y value can be a real
+        or a complex number depending on format of the selected measurement for the configured data source. Y is a complex
+        number for Complex, Smith and Polar formats. For all other formats, Y is a real number.
+
+        If Y value is a complex number, use Marker Y1 and Marker Y2 to set its real and imaginary components
+        respectively. If Y value is a real number, use Marker Y1 to set the Y location and set Marker Y2 to 0.
+
+        When you want to use a **Fixed** marker as a reference marker for a Delta marker, then you must configure the Y
+        value of the **Fixed** reference marker by calling this method or by performing any marker search operation on the
+        reference marker before configuring the X value of the **Delta** marker.
+
+        Use "marker<*n*>" as the selector string to configure this method.
+
+        Args:
+            selector_string (string):
+                Specifies a selector string. Pass an empty string.
+
+            marker_y1 (float):
+                This parameter specifies the Y1 component of the **(Fixed)** marker's Y value.
+
+            marker_y2 (float):
+                This parameter specifies the Y2 component of the **(Fixed)** marker's Y value..
+
+        Returns:
+            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
+            )
+            error_code = self._interpreter.marker_configure_y(
+                updated_selector_string, marker_y1, marker_y2
+            )
+        finally:
+            self._session_function_lock.exit_read_lock()
+
+        return error_code
+
+    @_raise_if_disposed
+    def configure_data_source(self, selector_string, data_source):
+        r"""Configures the data source on which marker operations are performed.
+        Use "marker<*n*>" as the selector string to configure this method.
+
+        Args:
+            selector_string (string):
+                Specifies a selector string. Pass an empty string.
+
+            data_source (string):
+                This parameter specifies the measurement or memory data on which markers are placed. If you want to place markers on
+                **SParams** measurement data, then specify this parameter as "sparam<*n*>".
+                If you want to place markers on **SParams** measurement memory data, then specify this parameter as
+                "sparam<*n*>/measmem::<*measMemoryName*>". Similarly, if you want to place markers on **Wave** measurement data, then
+                specify this parameter as "wave<*n*>".
+
+        Returns:
+            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")
+            _helper.validate_not_none(data_source, "data_source")
+            updated_selector_string = _helper.validate_and_update_selector_string(
+                selector_string, self._signal_obj
+            )
+            error_code = self._interpreter.marker_configure_data_source(
+                updated_selector_string, data_source
+            )
+        finally:
+            self._session_function_lock.exit_read_lock()
+
+        return error_code
+
+    @_raise_if_disposed
+    def configure_peak_search_threshold(self, selector_string, threshold_enabled, threshold):
+        r"""Configures the peak-search threshold. When peak-thresholding is enabled, Marker Search method in peak search mode finds
+        the peaks that exceed this value and discards all other peaks.
+
+        Use "marker<*n*>" as the selector string to configure this method.
+
+        Args:
+            selector_string (string):
+                Specifies a selector string. Pass an empty string.
+
+            threshold_enabled (enums.MarkerPeakSearchThresholdEnabled, int):
+                This parameter specifies whether :py:meth:`marker_search` finds a peak above specified Threshold or finds a peak
+                without considering any Threshold constraint.
+
+                +--------------+-----------------------------+
+                | Name (Value) | Description                 |
+                +==============+=============================+
+                | False (0)    | Disables peak-thresholding. |
+                +--------------+-----------------------------+
+                | True (1)     | Enables peak-thresholding.  |
+                +--------------+-----------------------------+
+
+            threshold (float):
+                This parameter specifies the threshold value that a valid peak must exceed when you use :py:meth:`marker_search` to
+                find peaks. The threshold is expressed in the same units as the source data.
+
+        Returns:
+            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")
+            threshold_enabled = (
+                threshold_enabled.value
+                if type(threshold_enabled) is enums.MarkerPeakSearchThresholdEnabled
+                else threshold_enabled
+            )
+            updated_selector_string = _helper.validate_and_update_selector_string(
+                selector_string, self._signal_obj
+            )
+            error_code = self._interpreter.marker_configure_peak_search_threshold(
+                updated_selector_string, threshold_enabled, threshold
+            )
+        finally:
+            self._session_function_lock.exit_read_lock()
+
+        return error_code
+
+    @_raise_if_disposed
+    def configure_peak_search_excursion(
+        self, selector_string, peak_excursion_enabled, peak_excursion
+    ):
+        r"""Configures the peak-search excursion. When peak-excursion is enabled, peak search using Marker Search method finds a
+        peak such that the data value rises and falls around the peak by at least the specified peak excursion value.
+
+        Use "marker<*n*>" as the selector string to configure this method.
+
+        Args:
+            selector_string (string):
+                Specifies a selector string. Pass an empty string.
+
+            peak_excursion_enabled (enums.MarkerPeakSearchExcursionEnabled, int):
+                This parameter specifies whether :py:meth:`marker_search` finds a peak such that the data value rises and falls around
+                the peak by atleast the specified peak excursion value or finds a peak without considering any peak excursion
+                constraint.
+
+                +--------------+------------------------------+
+                | Name (Value) | Description                  |
+                +==============+==============================+
+                | False (0)    | Disables the peak excursion. |
+                +--------------+------------------------------+
+                | True (1)     | Enables the peak excursion.  |
+                +--------------+------------------------------+
+
+            peak_excursion (float):
+                This parameter specifies the peak excursion value that :py:meth:`marker_search` uses to find a peak such that the data
+                value rises and falls around the peak by atleast the specified peak excursion value. The threshold is expressed in the
+                same units as the source data.
+
+        Returns:
+            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")
+            peak_excursion_enabled = (
+                peak_excursion_enabled.value
+                if type(peak_excursion_enabled) is enums.MarkerPeakSearchExcursionEnabled
+                else peak_excursion_enabled
+            )
+            updated_selector_string = _helper.validate_and_update_selector_string(
+                selector_string, self._signal_obj
+            )
+            error_code = self._interpreter.marker_configure_peak_search_excursion(
+                updated_selector_string, peak_excursion_enabled, peak_excursion
+            )
+        finally:
+            self._session_function_lock.exit_read_lock()
+
+        return error_code
+
+    @_raise_if_disposed
+    def configure_mode(self, selector_string, marker_mode):
+        r"""Configures the marker mode.
+        Use "marker<*n*>" as the selector string to configure this method.
+
+        Args:
+            selector_string (string):
+                Specifies a selector string. Pass an empty string.
+
+            marker_mode (enums.MarkerMode, int):
+                This parameter specifies the mode for placing the marker.
+
+                +----------------+-----------------------------------------------------------------------------------------------------------------------+
+                | Name (Value)   | Description                                                                                                           |
+                +================+=======================================================================================================================+
+                | Continuous (0) | Marker can be placed at any point and its response value is obtained by interpolation of actual measured data points. |
+                +----------------+-----------------------------------------------------------------------------------------------------------------------+
+                | Discrete (1)   | Marker can be placed only at actual measured data points.                                                             |
+                +----------------+-----------------------------------------------------------------------------------------------------------------------+
+
+        Returns:
+            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")
+            marker_mode = (
+                marker_mode.value if type(marker_mode) is enums.MarkerMode else marker_mode
+            )
+            updated_selector_string = _helper.validate_and_update_selector_string(
+                selector_string, self._signal_obj
+            )
+            error_code = self._interpreter.marker_configure_mode(
+                updated_selector_string, marker_mode
+            )
+        finally:
+            self._session_function_lock.exit_read_lock()
+
+        return error_code
+
+    @_raise_if_disposed
+    def configure_target_value(self, selector_string, target_value):
+        r"""Configures the target value for the specified marker when performing Target search using Marker Search method.
+
+        Use "marker<*n*>" as the selector string to configure this method.
+
+        Args:
+            selector_string (string):
+                Specifies a selector string. Pass an empty string.
+
+            target_value (float):
+                This parameter specifies the target value for target search. The target value is expressed in the same units as the
+                source data.
+
+        Returns:
+            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
+            )
+            error_code = self._interpreter.marker_configure_target_value(
+                updated_selector_string, target_value
+            )
+        finally:
+            self._session_function_lock.exit_read_lock()
+
+        return error_code

nirfmxvna/marker_results.py

@@ -0,0 +1,168 @@
+"""Provides methods to fetch and read the Marker measurement results."""
+
+import functools
+
+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 MarkerResults(object):
+    """Provides methods to fetch and read the Marker measurement results."""
+
+    def __init__(self, signal_obj):
+        """Provides methods to fetch and read the Marker 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 marker_search(self, selector_string, search_mode):
+        r"""Performs the marker search operation that you specify using Search Mode.
+
+        .. note::
+           Marker search operation is performed on real-valued data only. No search operation is performed on complex-valued data.
+
+        Args:
+            selector_string (string):
+                Specifies a selector string. Pass an empty string.
+
+            search_mode (enums.MarkerSearchMode, int):
+                This parameter specifies the search-target. If search is successful, RFmx updates the marker X and Y values to the
+                location at which search-target is found.
+
+                +-----------------------+--------------------------------------------------------------------------------------------------------------------------+
+                | Name (Value)          | Description                                                                                                              |
+                +=======================+==========================================================================================================================+
+                | None (0)              | No search operation is performed.                                                                                        |
+                +-----------------------+--------------------------------------------------------------------------------------------------------------------------+
+                | Max (1)               | Moves the marker to the highest measured value on the configured data source.                                            |
+                +-----------------------+--------------------------------------------------------------------------------------------------------------------------+
+                | Min (2)               | Moves the marker to the lowest measured value on the configured data source.                                             |
+                +-----------------------+--------------------------------------------------------------------------------------------------------------------------+
+                | Peak (3)              | Moves the marker to the highest peak that satisfies peak threshold and peak excursion criteria.                          |
+                +-----------------------+--------------------------------------------------------------------------------------------------------------------------+
+                | Next Peak (4)         | Moves the marker to the next peak that satisfies peak threshold and peak excursion criteria.                             |
+                +-----------------------+--------------------------------------------------------------------------------------------------------------------------+
+                | Next Left Peak (5)    | Moves the marker to the next left peak that satisfies peak threshold and peak excursion criteria.                        |
+                +-----------------------+--------------------------------------------------------------------------------------------------------------------------+
+                | Next Right Peak (6)   | Moves the marker to the next right peak that satisfies peak threshold and peak excursion criteria.                       |
+                +-----------------------+--------------------------------------------------------------------------------------------------------------------------+
+                | Target (7)            | Moves the marker to the first right target encountered from the current marker position, wraps around if no target       |
+                |                       | found. If marker mode is Discrete,marker moves to the data point closest to the first right target.                      |
+                +-----------------------+--------------------------------------------------------------------------------------------------------------------------+
+                | Next Left Target (8)  | Moves the marker to the next left target encountered from the current marker position. If marker mode is                 |
+                |                       | Discrete,marker moves to the data point closest to the next left target.                                                 |
+                +-----------------------+--------------------------------------------------------------------------------------------------------------------------+
+                | Next Right Target (9) | Moves the marker to the next right target encountered from the current marker position. If marker mode is                |
+                |                       | Discrete,marker moves to the data point closest to the next right target.                                                |
+                +-----------------------+--------------------------------------------------------------------------------------------------------------------------+
+
+        Returns:
+            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")
+            search_mode = (
+                search_mode.value if type(search_mode) is enums.MarkerSearchMode else search_mode
+            )
+            updated_selector_string = _helper.validate_and_update_selector_string(
+                selector_string, self._signal_obj
+            )
+            error_code = self._interpreter.marker_marker_search(
+                updated_selector_string, search_mode
+            )
+        finally:
+            self._session_function_lock.exit_read_lock()
+
+        return error_code
+
+    @_raise_if_disposed
+    def fetch_x(self, selector_string):
+        r"""Returns the X value of the marker. X value of the **Delta** marker is relative to its reference marker.
+
+        Args:
+            selector_string (string):
+                Specifies a selector string. Pass an empty string.
+
+        Returns:
+            Tuple (marker_x, error_code):
+
+            marker_x (float):
+                This parameter returns the marker X value.
+
+            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
+            )
+            marker_x, error_code = self._interpreter.marker_fetch_x(updated_selector_string)
+        finally:
+            self._session_function_lock.exit_read_lock()
+
+        return marker_x, error_code
+
+    @_raise_if_disposed
+    def fetch_y(self, selector_string):
+        r"""Returns the Y value of the marker. Y value of a **Delta** marker is relative to its reference marker.
+
+        Y value can be a real or a complex number depending on format of the selected measurement for the configured data
+        source. Y is a complex number for Complex, Smith and Polar formats. For all other formats, Y is a real number. If Y
+        value is a complex number, Marker Y1 and Marker Y2 return its real and imaginary components respectively. If Y value is
+        a real number, Marker Y1 returns the Y location and Marker Y2 returns 0.
+
+        Args:
+            selector_string (string):
+                Specifies a selector string. Pass an empty string.
+
+        Returns:
+            Tuple (marker_y1, marker_y2, error_code):
+
+            marker_y1 (float):
+                This parameter returns the Y1 component of marker's Y value.
+
+            marker_y2 (float):
+                This parameter returns the Y2 component of marker's Y value.
+
+                Y value is always returned as two components (Y1,Y2). The format of the Y value depends on the format of the
+                selected measurement.
+
+                If the format is Complex, Smith or Polar (Y1,Y2) are (Real, Imaginary).
+
+                For all other formats (Y1,Y2) are (Value,0).
+
+            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
+            )
+            marker_y1, marker_y2, error_code = self._interpreter.marker_fetch_y(
+                updated_selector_string
+            )
+        finally:
+            self._session_function_lock.exit_read_lock()
+
+        return marker_y1, marker_y2, error_code

nirfmxvna/s_params.py

@@ -0,0 +1,31 @@
+"""Represents the SParams measurement."""
+
+import functools
+
+import nirfmxvna.s_params_configuration as configuration
+import nirfmxvna.s_params_results as results
+
+
+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 SParams(object):
+    """Represents the SParams measurement."""
+
+    def __init__(self, signal_obj):
+        """Represents the SParams measurement."""
+        self._signal_obj = signal_obj
+        self._session_function_lock = signal_obj._session_function_lock
+        self._interpreter = signal_obj._interpreter
+        self.configuration = configuration.SParamsConfiguration(signal_obj)  # type: ignore
+        self.results = results.SParamsResults(signal_obj)  # type: ignore