"""Provides methods to configure the SParams measurement."""
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
[docs]
class SParamsConfiguration(object):
"""Provides methods to configure the SParams measurement."""
def __init__(self, signal_obj):
"""Provides methods to configure the SParams measurement."""
self._signal_obj = signal_obj
self._session_function_lock = signal_obj._session_function_lock
self._interpreter = signal_obj._interpreter
[docs]
@_raise_if_disposed
def get_measurement_enabled(self, selector_string):
r"""Gets whether to enable the Sparams measurement.
You do not need to use a selector string to configure or read this attribute for the default signal instance.
Refer to the `Selector String <https://www.ni.com/docs/en-US/bundle/rfmx/page/selector-strings-net.html>`_ topic for
information about the string syntax for named signals.
The default value is **False**.
Args:
selector_string (string):
Pass an empty string.
Returns:
Tuple (attr_val, error_code):
attr_val (bool):
Specifies whether to enable the Sparams 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_MEASUREMENT_ENABLED.value
)
attr_val = bool(attr_val)
finally:
self._session_function_lock.exit_read_lock()
return attr_val, error_code
[docs]
@_raise_if_disposed
def set_measurement_enabled(self, selector_string, value):
r"""Sets whether to enable the Sparams measurement.
You do not need to use a selector string to configure or read this attribute for the default signal instance.
Refer to the `Selector String <https://www.ni.com/docs/en-US/bundle/rfmx/page/selector-strings-net.html>`_ topic for
information about the string syntax for named signals.
The default value is **False**.
Args:
selector_string (string):
Pass an empty string.
value (bool):
Specifies whether to enable the Sparams measurement.
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()
updated_selector_string = _helper.validate_and_update_selector_string(
selector_string, self._signal_obj
)
error_code = self._interpreter.set_attribute_i32(
updated_selector_string,
attributes.AttributeID.SPARAMS_MEASUREMENT_ENABLED.value,
int(value),
)
finally:
self._session_function_lock.exit_read_lock()
return error_code
[docs]
@_raise_if_disposed
def get_number_of_s_parameters(self, selector_string):
r"""Gets the number of S-Parameters to measure.
**Note1**: S-Parameters of a N-port DUT can be represented by N^2 canonical S-Parameters viz. S11,
S12,...,S1N, S21, S22,...,S2N, SN1, SN2,...,SNN such that
**B = S A**
where **S** denotes the S-Parameter matrix with Sij being the element in the i\ :sup:`th`\ row and j\
:sup:`th`\ column. Similarly **A** denotes the matrix composed of the incident waves. Element Aij denotes the wave
parameter a\ :sub:`ij`\ i.e., wave measured at the reference reciever on port <i> with port <j> as the source.
Similarly **B** denotes the matrix composed of the scatterred waves. Element Bij denotes the wave parameter b\
:sub:`ij`\ i.e., wave measured at the test reciever on port <i> with port <j> as the source.
You can configure each measured S-Parameter in RFmxVNA SParams measurement to be returned in one of several
supported formats using :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_FORMAT` attribute. Example1: If you want to
fetch magnitude and phase information of S11, then set Number of S-Parameters attribute to 2, then for both SParam
indices 0 and 1, set Parameter attribute to "S11". Then set :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_FORMAT`
attribute to Magnitude for Sparam index 0 and to Phase for SParam index 1.
**Note2**: You can set many SParam indices to share the same Parameter and Format attribute values making them
duplicates of each other.
If you increase this attribute value from N to N+K, then existing N SParams are not affected but K new SParams
are added. If you reduce number of SParams from N to N-K, then last K SParams are deleted without affecting the
remaining N-K SParams.
You do not need to use a selector string to configure or read this attribute for the default signal instance.
Refer to the `Selector String <https://www.ni.com/docs/en-US/bundle/rfmx/page/selector-strings-net.html>`_ topic for
information about the string syntax for named signals.
The default value is 1.
Args:
selector_string (string):
Pass an empty string.
Returns:
Tuple (attr_val, error_code):
attr_val (int):
Specifies the number of S-Parameters to measure.
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_NUMBER_OF_SPARAMETERS.value
)
finally:
self._session_function_lock.exit_read_lock()
return attr_val, error_code
[docs]
@_raise_if_disposed
def set_number_of_s_parameters(self, selector_string, value):
r"""Sets the number of S-Parameters to measure.
**Note1**: S-Parameters of a N-port DUT can be represented by N^2 canonical S-Parameters viz. S11,
S12,...,S1N, S21, S22,...,S2N, SN1, SN2,...,SNN such that
**B = S A**
where **S** denotes the S-Parameter matrix with Sij being the element in the i\ :sup:`th`\ row and j\
:sup:`th`\ column. Similarly **A** denotes the matrix composed of the incident waves. Element Aij denotes the wave
parameter a\ :sub:`ij`\ i.e., wave measured at the reference reciever on port <i> with port <j> as the source.
Similarly **B** denotes the matrix composed of the scatterred waves. Element Bij denotes the wave parameter b\
:sub:`ij`\ i.e., wave measured at the test reciever on port <i> with port <j> as the source.
You can configure each measured S-Parameter in RFmxVNA SParams measurement to be returned in one of several
supported formats using :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_FORMAT` attribute. Example1: If you want to
fetch magnitude and phase information of S11, then set Number of S-Parameters attribute to 2, then for both SParam
indices 0 and 1, set Parameter attribute to "S11". Then set :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_FORMAT`
attribute to Magnitude for Sparam index 0 and to Phase for SParam index 1.
**Note2**: You can set many SParam indices to share the same Parameter and Format attribute values making them
duplicates of each other.
If you increase this attribute value from N to N+K, then existing N SParams are not affected but K new SParams
are added. If you reduce number of SParams from N to N-K, then last K SParams are deleted without affecting the
remaining N-K SParams.
You do not need to use a selector string to configure or read this attribute for the default signal instance.
Refer to the `Selector String <https://www.ni.com/docs/en-US/bundle/rfmx/page/selector-strings-net.html>`_ topic for
information about the string syntax for named signals.
The default value is 1.
Args:
selector_string (string):
Pass an empty string.
value (int):
Specifies the number of S-Parameters to measure.
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()
updated_selector_string = _helper.validate_and_update_selector_string(
selector_string, self._signal_obj
)
error_code = self._interpreter.set_attribute_i32(
updated_selector_string,
attributes.AttributeID.SPARAMS_NUMBER_OF_SPARAMETERS.value,
value,
)
finally:
self._session_function_lock.exit_read_lock()
return error_code
[docs]
@_raise_if_disposed
def get_receiver_port(self, selector_string):
r"""Gets the receiver port name of the S-Parameter. S-Parameter is denoted by "S_<*receiver port name*>_<*source port
name*>".
For example, to measure S21, set this attribute to "port2".
Use "sparam<*n*>" as the selector string to configure or read this attribute.
The default value is "port1".
Args:
selector_string (string):
Pass an empty string.
Returns:
Tuple (attr_val, error_code):
attr_val (string):
Specifies the receiver port name of the S-Parameter. S-Parameter is denoted by "S_<*receiver port name*>_<*source port
name*>".
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_RECEIVER_PORT.value
)
finally:
self._session_function_lock.exit_read_lock()
return attr_val, error_code
[docs]
@_raise_if_disposed
def set_receiver_port(self, selector_string, value):
r"""Sets the receiver port name of the S-Parameter. S-Parameter is denoted by "S_<*receiver port name*>_<*source port
name*>".
For example, to measure S21, set this attribute to "port2".
Use "sparam<*n*>" as the selector string to configure or read this attribute.
The default value is "port1".
Args:
selector_string (string):
Pass an empty string.
value (string):
Specifies the receiver port name of the S-Parameter. S-Parameter is denoted by "S_<*receiver port name*>_<*source port
name*>".
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()
updated_selector_string = _helper.validate_and_update_selector_string(
selector_string, self._signal_obj
)
_helper.validate_not_none(value, "value")
error_code = self._interpreter.set_attribute_string(
updated_selector_string, attributes.AttributeID.SPARAMS_RECEIVER_PORT.value, value
)
finally:
self._session_function_lock.exit_read_lock()
return error_code
[docs]
@_raise_if_disposed
def get_source_port(self, selector_string):
r"""Gets the source port name of the S-Parameter. S-Parameter is denoted by "S_<*receiver port name*>_<*source port
name*>".
For example, to measure S21, set this attribute to "port1".
Use "sparam<*n*>" as the selector string to configure or read this attribute.
The default value is "port1".
Args:
selector_string (string):
Pass an empty string.
Returns:
Tuple (attr_val, error_code):
attr_val (string):
Specifies the source port name of the S-Parameter. S-Parameter is denoted by "S_<*receiver port name*>_<*source port
name*>".
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_SOURCE_PORT.value
)
finally:
self._session_function_lock.exit_read_lock()
return attr_val, error_code
[docs]
@_raise_if_disposed
def set_source_port(self, selector_string, value):
r"""Sets the source port name of the S-Parameter. S-Parameter is denoted by "S_<*receiver port name*>_<*source port
name*>".
For example, to measure S21, set this attribute to "port1".
Use "sparam<*n*>" as the selector string to configure or read this attribute.
The default value is "port1".
Args:
selector_string (string):
Pass an empty string.
value (string):
Specifies the source port name of the S-Parameter. S-Parameter is denoted by "S_<*receiver port name*>_<*source port
name*>".
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()
updated_selector_string = _helper.validate_and_update_selector_string(
selector_string, self._signal_obj
)
_helper.validate_not_none(value, "value")
error_code = self._interpreter.set_attribute_string(
updated_selector_string, attributes.AttributeID.SPARAMS_SOURCE_PORT.value, value
)
finally:
self._session_function_lock.exit_read_lock()
return error_code
[docs]
@_raise_if_disposed
def get_magnitude_units(self, selector_string):
r"""Gets the magnitude units for all S-Parameters for which you set
:py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_FORMAT` attribute to **Magnitude**.
You do not need to use a selector string to configure or read this attribute for the default signal instance.
Refer to the `Selector String <https://www.ni.com/docs/en-US/bundle/rfmx/page/selector-strings-net.html>`_ topic for
information about the string syntax for named signals.
The default value is **dB**.
+--------------+-------------------------------------------------------------------------------------------------------+
| Name (Value) | Description |
+==============+=======================================================================================================+
| dB (0) | Sets S-Parameter magnitude units to dB. |
+--------------+-------------------------------------------------------------------------------------------------------+
| Linear (1) | Sets S-Parameter magnitude units to linear such that S-Parameters are reported in linear scale (V/V). |
+--------------+-------------------------------------------------------------------------------------------------------+
Args:
selector_string (string):
Pass an empty string.
Returns:
Tuple (attr_val, error_code):
attr_val (enums.SParamsMagnitudeUnits):
Specifies the magnitude units for all S-Parameters for which you set
:py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_FORMAT` attribute to **Magnitude**.
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_MAGNITUDE_UNITS.value
)
attr_val = enums.SParamsMagnitudeUnits(attr_val)
except (KeyError, ValueError):
raise errors.DriverTooNewError() # type: ignore
finally:
self._session_function_lock.exit_read_lock()
return attr_val, error_code
[docs]
@_raise_if_disposed
def set_magnitude_units(self, selector_string, value):
r"""Sets the magnitude units for all S-Parameters for which you set
:py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_FORMAT` attribute to **Magnitude**.
You do not need to use a selector string to configure or read this attribute for the default signal instance.
Refer to the `Selector String <https://www.ni.com/docs/en-US/bundle/rfmx/page/selector-strings-net.html>`_ topic for
information about the string syntax for named signals.
The default value is **dB**.
+--------------+-------------------------------------------------------------------------------------------------------+
| Name (Value) | Description |
+==============+=======================================================================================================+
| dB (0) | Sets S-Parameter magnitude units to dB. |
+--------------+-------------------------------------------------------------------------------------------------------+
| Linear (1) | Sets S-Parameter magnitude units to linear such that S-Parameters are reported in linear scale (V/V). |
+--------------+-------------------------------------------------------------------------------------------------------+
Args:
selector_string (string):
Pass an empty string.
value (enums.SParamsMagnitudeUnits, int):
Specifies the magnitude units for all S-Parameters for which you set
:py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_FORMAT` attribute to **Magnitude**.
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()
updated_selector_string = _helper.validate_and_update_selector_string(
selector_string, self._signal_obj
)
value = value.value if type(value) is enums.SParamsMagnitudeUnits else value
error_code = self._interpreter.set_attribute_i32(
updated_selector_string, attributes.AttributeID.SPARAMS_MAGNITUDE_UNITS.value, value
)
finally:
self._session_function_lock.exit_read_lock()
return error_code
[docs]
@_raise_if_disposed
def get_phase_trace_type(self, selector_string):
r"""Gets the phase type for all S-Parameters for which :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_FORMAT`
attribute is set to **Phase**. Phase can be represented in two mathematically equivalent ways viz. phase wrapped
between the range [-180, 180) degrees, and phase can be represented in an unwrapped manner.
You do not need to use a selector string to configure or read this attribute for the default signal instance.
Refer to the `Selector String <https://www.ni.com/docs/en-US/bundle/rfmx/page/selector-strings-net.html>`_ topic for
information about the string syntax for named signals.
The default value is **Wrapped**.
+---------------+---------------------------------------------------------------------------------+
| Name (Value) | Description |
+===============+=================================================================================+
| Wrapped (0) | The reported S-Parameter phase is wrapped between -180 degress to +180 degrees. |
+---------------+---------------------------------------------------------------------------------+
| Unwrapped (1) | The reported S-Parameter phase is unwrapped. |
+---------------+---------------------------------------------------------------------------------+
Args:
selector_string (string):
Pass an empty string.
Returns:
Tuple (attr_val, error_code):
attr_val (enums.SParamsPhaseTraceType):
Specifies the phase type for all S-Parameters for which :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_FORMAT`
attribute is set to **Phase**. Phase can be represented in two mathematically equivalent ways viz. phase wrapped
between the range [-180, 180) degrees, and phase can be represented in an unwrapped manner.
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_PHASE_TRACE_TYPE.value
)
attr_val = enums.SParamsPhaseTraceType(attr_val)
except (KeyError, ValueError):
raise errors.DriverTooNewError() # type: ignore
finally:
self._session_function_lock.exit_read_lock()
return attr_val, error_code
[docs]
@_raise_if_disposed
def set_phase_trace_type(self, selector_string, value):
r"""Sets the phase type for all S-Parameters for which :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_FORMAT`
attribute is set to **Phase**. Phase can be represented in two mathematically equivalent ways viz. phase wrapped
between the range [-180, 180) degrees, and phase can be represented in an unwrapped manner.
You do not need to use a selector string to configure or read this attribute for the default signal instance.
Refer to the `Selector String <https://www.ni.com/docs/en-US/bundle/rfmx/page/selector-strings-net.html>`_ topic for
information about the string syntax for named signals.
The default value is **Wrapped**.
+---------------+---------------------------------------------------------------------------------+
| Name (Value) | Description |
+===============+=================================================================================+
| Wrapped (0) | The reported S-Parameter phase is wrapped between -180 degress to +180 degrees. |
+---------------+---------------------------------------------------------------------------------+
| Unwrapped (1) | The reported S-Parameter phase is unwrapped. |
+---------------+---------------------------------------------------------------------------------+
Args:
selector_string (string):
Pass an empty string.
value (enums.SParamsPhaseTraceType, int):
Specifies the phase type for all S-Parameters for which :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_FORMAT`
attribute is set to **Phase**. Phase can be represented in two mathematically equivalent ways viz. phase wrapped
between the range [-180, 180) degrees, and phase can be represented in an unwrapped manner.
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()
updated_selector_string = _helper.validate_and_update_selector_string(
selector_string, self._signal_obj
)
value = value.value if type(value) is enums.SParamsPhaseTraceType else value
error_code = self._interpreter.set_attribute_i32(
updated_selector_string,
attributes.AttributeID.SPARAMS_PHASE_TRACE_TYPE.value,
value,
)
finally:
self._session_function_lock.exit_read_lock()
return error_code
[docs]
@_raise_if_disposed
def get_group_delay_aperture_mode(self, selector_string):
r"""Gets the aperture mode to be used for the computation of group delay for all S-Parameters for which
:py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_FORMAT` attribute is set to **Group Delay**.
You do not need to use a selector string to configure or read this attribute for the default signal instance.
Refer to the `Selector String <https://www.ni.com/docs/en-US/bundle/rfmx/page/selector-strings-net.html>`_ topic for
information about the string syntax for named signals.
The default value is **Points**.
+--------------------+--------------------------------------------------------------------------------------------------------------------------+
| Name (Value) | Description |
+====================+==========================================================================================================================+
| Points (0) | Sets group delay aperture mode to Points. You can specify the aperture in terms of the number of frequency points by |
| | configuring SParams Group Delay Aperture Points. |
+--------------------+--------------------------------------------------------------------------------------------------------------------------+
| Percentage (1) | Sets group delay aperture mode to Percentage. You can specify the aperture in terms of the frequency separation |
| | expressed in percentage by configuring SParams Group Delay Aperture Percentage. |
+--------------------+--------------------------------------------------------------------------------------------------------------------------+
| Frequency Span (2) | Sets group delay aperture to Frequency Span. You can specify the aperture in terms of the frequency separation by |
| | configuring SParams Group Delay Aperture Frequency Span. |
+--------------------+--------------------------------------------------------------------------------------------------------------------------+
Args:
selector_string (string):
Pass an empty string.
Returns:
Tuple (attr_val, error_code):
attr_val (enums.SParamsGroupDelayApertureMode):
Specifies the aperture mode to be used for the computation of group delay for all S-Parameters for which
:py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_FORMAT` attribute is set to **Group Delay**.
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_GROUP_DELAY_APERTURE_MODE.value,
)
attr_val = enums.SParamsGroupDelayApertureMode(attr_val)
except (KeyError, ValueError):
raise errors.DriverTooNewError() # type: ignore
finally:
self._session_function_lock.exit_read_lock()
return attr_val, error_code
[docs]
@_raise_if_disposed
def set_group_delay_aperture_mode(self, selector_string, value):
r"""Sets the aperture mode to be used for the computation of group delay for all S-Parameters for which
:py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_FORMAT` attribute is set to **Group Delay**.
You do not need to use a selector string to configure or read this attribute for the default signal instance.
Refer to the `Selector String <https://www.ni.com/docs/en-US/bundle/rfmx/page/selector-strings-net.html>`_ topic for
information about the string syntax for named signals.
The default value is **Points**.
+--------------------+--------------------------------------------------------------------------------------------------------------------------+
| Name (Value) | Description |
+====================+==========================================================================================================================+
| Points (0) | Sets group delay aperture mode to Points. You can specify the aperture in terms of the number of frequency points by |
| | configuring SParams Group Delay Aperture Points. |
+--------------------+--------------------------------------------------------------------------------------------------------------------------+
| Percentage (1) | Sets group delay aperture mode to Percentage. You can specify the aperture in terms of the frequency separation |
| | expressed in percentage by configuring SParams Group Delay Aperture Percentage. |
+--------------------+--------------------------------------------------------------------------------------------------------------------------+
| Frequency Span (2) | Sets group delay aperture to Frequency Span. You can specify the aperture in terms of the frequency separation by |
| | configuring SParams Group Delay Aperture Frequency Span. |
+--------------------+--------------------------------------------------------------------------------------------------------------------------+
Args:
selector_string (string):
Pass an empty string.
value (enums.SParamsGroupDelayApertureMode, int):
Specifies the aperture mode to be used for the computation of group delay for all S-Parameters for which
:py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_FORMAT` attribute is set to **Group Delay**.
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()
updated_selector_string = _helper.validate_and_update_selector_string(
selector_string, self._signal_obj
)
value = value.value if type(value) is enums.SParamsGroupDelayApertureMode else value
error_code = self._interpreter.set_attribute_i32(
updated_selector_string,
attributes.AttributeID.SPARAMS_GROUP_DELAY_APERTURE_MODE.value,
value,
)
finally:
self._session_function_lock.exit_read_lock()
return error_code
[docs]
@_raise_if_disposed
def get_group_delay_aperture_points(self, selector_string):
r"""Gets the group delay aperture in terms of the number of frequency points that separates the two frequency points
for all S-Parameters for which :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_FORMAT` attribute is set to **Group
Delay** and :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_GROUP_DELAY_APERTURE_MODE` attribute is set to
**Points**. You must set the value of this attribute between 2 and the total number of frequency points in the
measurement frequency range.
You do not need to use a selector string to configure or read this attribute for the default signal instance.
Refer to the `Selector String <https://www.ni.com/docs/en-US/bundle/rfmx/page/selector-strings-net.html>`_ topic for
information about the string syntax for named signals.
The default value is 11.
Args:
selector_string (string):
Pass an empty string.
Returns:
Tuple (attr_val, error_code):
attr_val (float):
Specifies the group delay aperture in terms of the number of frequency points that separates the two frequency points
for all S-Parameters for which :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_FORMAT` attribute is set to **Group
Delay** and :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_GROUP_DELAY_APERTURE_MODE` attribute is set to
**Points**. You must set the value of this attribute between 2 and the total number of frequency points in the
measurement frequency range.
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_f64(
updated_selector_string,
attributes.AttributeID.SPARAMS_GROUP_DELAY_APERTURE_POINTS.value,
)
finally:
self._session_function_lock.exit_read_lock()
return attr_val, error_code
[docs]
@_raise_if_disposed
def set_group_delay_aperture_points(self, selector_string, value):
r"""Sets the group delay aperture in terms of the number of frequency points that separates the two frequency points
for all S-Parameters for which :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_FORMAT` attribute is set to **Group
Delay** and :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_GROUP_DELAY_APERTURE_MODE` attribute is set to
**Points**. You must set the value of this attribute between 2 and the total number of frequency points in the
measurement frequency range.
You do not need to use a selector string to configure or read this attribute for the default signal instance.
Refer to the `Selector String <https://www.ni.com/docs/en-US/bundle/rfmx/page/selector-strings-net.html>`_ topic for
information about the string syntax for named signals.
The default value is 11.
Args:
selector_string (string):
Pass an empty string.
value (float):
Specifies the group delay aperture in terms of the number of frequency points that separates the two frequency points
for all S-Parameters for which :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_FORMAT` attribute is set to **Group
Delay** and :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_GROUP_DELAY_APERTURE_MODE` attribute is set to
**Points**. You must set the value of this attribute between 2 and the total number of frequency points in the
measurement frequency range.
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()
updated_selector_string = _helper.validate_and_update_selector_string(
selector_string, self._signal_obj
)
error_code = self._interpreter.set_attribute_f64(
updated_selector_string,
attributes.AttributeID.SPARAMS_GROUP_DELAY_APERTURE_POINTS.value,
value,
)
finally:
self._session_function_lock.exit_read_lock()
return error_code
[docs]
@_raise_if_disposed
def get_group_delay_aperture_percentage(self, selector_string):
r"""Gets the group delay aperture in terms of the frequency separation between the two frequency points selected for
group delay computation, where separation is expressed as a percentage of the total measurement frequency range for all
S-Parameters for which :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_FORMAT` attribute is set to **Group Delay**
and :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_GROUP_DELAY_APERTURE_MODE` attribute is set to **Percentage**.
You do not need to use a selector string to configure or read this attribute for the default signal instance.
Refer to the `Selector String <https://www.ni.com/docs/en-US/bundle/rfmx/page/selector-strings-net.html>`_ topic for
information about the string syntax for named signals.
The default value is 5 %.
Args:
selector_string (string):
Pass an empty string.
Returns:
Tuple (attr_val, error_code):
attr_val (float):
Specifies the group delay aperture in terms of the frequency separation between the two frequency points selected for
group delay computation, where separation is expressed as a percentage of the total measurement frequency range for all
S-Parameters for which :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_FORMAT` attribute is set to **Group Delay**
and :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_GROUP_DELAY_APERTURE_MODE` attribute is set to **Percentage**.
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_f64(
updated_selector_string,
attributes.AttributeID.SPARAMS_GROUP_DELAY_APERTURE_PERCENTAGE.value,
)
finally:
self._session_function_lock.exit_read_lock()
return attr_val, error_code
[docs]
@_raise_if_disposed
def set_group_delay_aperture_percentage(self, selector_string, value):
r"""Sets the group delay aperture in terms of the frequency separation between the two frequency points selected for
group delay computation, where separation is expressed as a percentage of the total measurement frequency range for all
S-Parameters for which :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_FORMAT` attribute is set to **Group Delay**
and :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_GROUP_DELAY_APERTURE_MODE` attribute is set to **Percentage**.
You do not need to use a selector string to configure or read this attribute for the default signal instance.
Refer to the `Selector String <https://www.ni.com/docs/en-US/bundle/rfmx/page/selector-strings-net.html>`_ topic for
information about the string syntax for named signals.
The default value is 5 %.
Args:
selector_string (string):
Pass an empty string.
value (float):
Specifies the group delay aperture in terms of the frequency separation between the two frequency points selected for
group delay computation, where separation is expressed as a percentage of the total measurement frequency range for all
S-Parameters for which :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_FORMAT` attribute is set to **Group Delay**
and :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_GROUP_DELAY_APERTURE_MODE` attribute is set to **Percentage**.
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()
updated_selector_string = _helper.validate_and_update_selector_string(
selector_string, self._signal_obj
)
error_code = self._interpreter.set_attribute_f64(
updated_selector_string,
attributes.AttributeID.SPARAMS_GROUP_DELAY_APERTURE_PERCENTAGE.value,
value,
)
finally:
self._session_function_lock.exit_read_lock()
return error_code
[docs]
@_raise_if_disposed
def get_group_delay_aperture_frequency_span(self, selector_string):
r"""Gets the group delay aperture in terms of the frequency separation between the two frequency points selected for
group delay computation for all S-Parameters for which :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_FORMAT`
attribute is set to **Group Delay** and :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_GROUP_DELAY_APERTURE_MODE`
attribute is set to **Frequency Span**.
You do not need to use a selector string to configure or read this attribute for the default signal instance.
Refer to the `Selector String <https://www.ni.com/docs/en-US/bundle/rfmx/page/selector-strings-net.html>`_ topic for
information about the string syntax for named signals.
The default value is 50 MHz.
Args:
selector_string (string):
Pass an empty string.
Returns:
Tuple (attr_val, error_code):
attr_val (float):
Specifies the group delay aperture in terms of the frequency separation between the two frequency points selected for
group delay computation for all S-Parameters for which :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_FORMAT`
attribute is set to **Group Delay** and :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_GROUP_DELAY_APERTURE_MODE`
attribute is set to **Frequency Span**.
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_f64(
updated_selector_string,
attributes.AttributeID.SPARAMS_GROUP_DELAY_APERTURE_FREQUENCY_SPAN.value,
)
finally:
self._session_function_lock.exit_read_lock()
return attr_val, error_code
[docs]
@_raise_if_disposed
def set_group_delay_aperture_frequency_span(self, selector_string, value):
r"""Sets the group delay aperture in terms of the frequency separation between the two frequency points selected for
group delay computation for all S-Parameters for which :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_FORMAT`
attribute is set to **Group Delay** and :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_GROUP_DELAY_APERTURE_MODE`
attribute is set to **Frequency Span**.
You do not need to use a selector string to configure or read this attribute for the default signal instance.
Refer to the `Selector String <https://www.ni.com/docs/en-US/bundle/rfmx/page/selector-strings-net.html>`_ topic for
information about the string syntax for named signals.
The default value is 50 MHz.
Args:
selector_string (string):
Pass an empty string.
value (float):
Specifies the group delay aperture in terms of the frequency separation between the two frequency points selected for
group delay computation for all S-Parameters for which :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_FORMAT`
attribute is set to **Group Delay** and :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_GROUP_DELAY_APERTURE_MODE`
attribute is set to **Frequency Span**.
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()
updated_selector_string = _helper.validate_and_update_selector_string(
selector_string, self._signal_obj
)
error_code = self._interpreter.set_attribute_f64(
updated_selector_string,
attributes.AttributeID.SPARAMS_GROUP_DELAY_APERTURE_FREQUENCY_SPAN.value,
value,
)
finally:
self._session_function_lock.exit_read_lock()
return error_code
[docs]
@_raise_if_disposed
def get_math_function(self, selector_string):
r"""Gets the mathematical operation between the configured S-Parameter and its active measurement memory. All
mathematical operations are applied on complex data before being formatted.
Use "sparam<*n*>" as the selector string to configure or read this attribute.
The default value is **Off**.
+--------------+-------------------------------------------------------------------+
| Name (Value) | Description |
+==============+===================================================================+
| Off (0) | No mathematical operation is performed. |
+--------------+-------------------------------------------------------------------+
| Add (1) | Data in measurement memory is added to S-Parameter data. |
+--------------+-------------------------------------------------------------------+
| Subtract (2) | Data in measurement memory is subtracted from S-Parameter data. |
+--------------+-------------------------------------------------------------------+
| Multiply (3) | S-Parameter data is multiplied by the data in measurement memory. |
+--------------+-------------------------------------------------------------------+
| Divide (4) | S-Parameter data is divided by the data in measurement memory. |
+--------------+-------------------------------------------------------------------+
Args:
selector_string (string):
Pass an empty string.
Returns:
Tuple (attr_val, error_code):
attr_val (enums.SParamsMathFunction):
Specifies the mathematical operation between the configured S-Parameter and its active measurement memory. All
mathematical operations are applied on complex data before being formatted.
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_MATH_FUNCTION.value
)
attr_val = enums.SParamsMathFunction(attr_val)
except (KeyError, ValueError):
raise errors.DriverTooNewError() # type: ignore
finally:
self._session_function_lock.exit_read_lock()
return attr_val, error_code
[docs]
@_raise_if_disposed
def set_math_function(self, selector_string, value):
r"""Sets the mathematical operation between the configured S-Parameter and its active measurement memory. All
mathematical operations are applied on complex data before being formatted.
Use "sparam<*n*>" as the selector string to configure or read this attribute.
The default value is **Off**.
+--------------+-------------------------------------------------------------------+
| Name (Value) | Description |
+==============+===================================================================+
| Off (0) | No mathematical operation is performed. |
+--------------+-------------------------------------------------------------------+
| Add (1) | Data in measurement memory is added to S-Parameter data. |
+--------------+-------------------------------------------------------------------+
| Subtract (2) | Data in measurement memory is subtracted from S-Parameter data. |
+--------------+-------------------------------------------------------------------+
| Multiply (3) | S-Parameter data is multiplied by the data in measurement memory. |
+--------------+-------------------------------------------------------------------+
| Divide (4) | S-Parameter data is divided by the data in measurement memory. |
+--------------+-------------------------------------------------------------------+
Args:
selector_string (string):
Pass an empty string.
value (enums.SParamsMathFunction, int):
Specifies the mathematical operation between the configured S-Parameter and its active measurement memory. All
mathematical operations are applied on complex data before being formatted.
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()
updated_selector_string = _helper.validate_and_update_selector_string(
selector_string, self._signal_obj
)
value = value.value if type(value) is enums.SParamsMathFunction else value
error_code = self._interpreter.set_attribute_i32(
updated_selector_string, attributes.AttributeID.SPARAMS_MATH_FUNCTION.value, value
)
finally:
self._session_function_lock.exit_read_lock()
return error_code
[docs]
@_raise_if_disposed
def get_math_active_measurement_memory(self, selector_string):
r"""Gets the active measurement memory for performing mathematical operations when several measurement memories are
associated with the configured S-Parameter. If only one measurement memory is associated with the configured
S-Parameter, that measurement memory will be used for mathematical operations.
Use "sparam<*n*>" as the selector string to configure or read this attribute.
Args:
selector_string (string):
Pass an empty string.
Returns:
Tuple (attr_val, error_code):
attr_val (string):
Specifies the active measurement memory for performing mathematical operations when several measurement memories are
associated with the configured S-Parameter. If only one measurement memory is associated with the configured
S-Parameter, that measurement memory will be used for mathematical operations.
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_MATH_ACTIVE_MEASUREMENT_MEMORY.value,
)
finally:
self._session_function_lock.exit_read_lock()
return attr_val, error_code
[docs]
@_raise_if_disposed
def set_math_active_measurement_memory(self, selector_string, value):
r"""Sets the active measurement memory for performing mathematical operations when several measurement memories are
associated with the configured S-Parameter. If only one measurement memory is associated with the configured
S-Parameter, that measurement memory will be used for mathematical operations.
Use "sparam<*n*>" as the selector string to configure or read this attribute.
Args:
selector_string (string):
Pass an empty string.
value (string):
Specifies the active measurement memory for performing mathematical operations when several measurement memories are
associated with the configured S-Parameter. If only one measurement memory is associated with the configured
S-Parameter, that measurement memory will be used for mathematical operations.
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()
updated_selector_string = _helper.validate_and_update_selector_string(
selector_string, self._signal_obj
)
_helper.validate_not_none(value, "value")
error_code = self._interpreter.set_attribute_string(
updated_selector_string,
attributes.AttributeID.SPARAMS_MATH_ACTIVE_MEASUREMENT_MEMORY.value,
value,
)
finally:
self._session_function_lock.exit_read_lock()
return error_code
[docs]
@_raise_if_disposed
def get_snp_ports(self, selector_string):
r"""Gets the ports for which the measured S-parameters are saved to file.
You do not need to use a selector string to configure or read this attribute for the default signal instance.
Refer to the `Selector String <https://www.ni.com/docs/en-US/bundle/rfmx/page/selector-strings-net.html>`_ topic for
information about the string syntax for named signals.
Args:
selector_string (string):
Pass an empty string.
Returns:
Tuple (attr_val, error_code):
attr_val (string):
Specifies the ports for which the measured S-parameters are saved to file.
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_SNP_PORTS.value
)
finally:
self._session_function_lock.exit_read_lock()
return attr_val, error_code
[docs]
@_raise_if_disposed
def set_snp_ports(self, selector_string, value):
r"""Sets the ports for which the measured S-parameters are saved to file.
You do not need to use a selector string to configure or read this attribute for the default signal instance.
Refer to the `Selector String <https://www.ni.com/docs/en-US/bundle/rfmx/page/selector-strings-net.html>`_ topic for
information about the string syntax for named signals.
Args:
selector_string (string):
Pass an empty string.
value (string):
Specifies the ports for which the measured S-parameters are saved to file.
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()
updated_selector_string = _helper.validate_and_update_selector_string(
selector_string, self._signal_obj
)
_helper.validate_not_none(value, "value")
error_code = self._interpreter.set_attribute_string(
updated_selector_string, attributes.AttributeID.SPARAMS_SNP_PORTS.value, value
)
finally:
self._session_function_lock.exit_read_lock()
return error_code
[docs]
@_raise_if_disposed
def export_to_snp_file(self, selector_string, snp_file_path):
r"""Exports the measured S-parameters to a SnP file.
You can set format of the exported S-Parameters using
:py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_SNP_DATA_FORMAT` attribute, use
:py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_SNP_USER_COMMENT` attribute to add any additional comments and use
:py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_SNP_PORTS` attribute to specify a subset of VNA ports. This method
exports the S-Parameters associated with :py:attr:`~nirfmxvna.attributes.AttributeID.SPARAMS_SNP_PORTS`.
For a N-port VNA, assume that you measure S11, S12, …, S1M, S21, S22, ..., S2M, SM1, SM2, ..., SMM parameters,
where M<=N. SnP file export behaviors for various scenarios are as follows:
**Case 1:** You specify file extension as S<N>P. S-Parameter data for ports M+1, M+2, .., N in the exported
file are zero-filled when S-Parameter data is in linear format, and are filled with -200 dB magnitude and 45 degrees
angle in log format.
**Example:** For a 2-Port VNA, if you measure only S11 and export the S-Parameters to a *.s2p file, then
resulting file will contain measured S11 data and zero-filled S21, S12 and S22 data.
**Case 2:** You specify file extension as S<M>P. Resulting *.s<M>p file contains S-Parameters S11, …, SMM data.
**Example:** For a 2-Port VNA, if you measure only S11 and export the S-Parameters to a *.s1p file, then
resulting file will contain measured S11 data
Args:
selector_string (string):
This parameter specifies a selector string comprising of result name.
Example:
""
"result::r1"
You can use the :py:meth:`build_s_parameter_string` method to build the selector string.
snp_file_path (string):
This parameter Specifies the full path to the exported *.snp file. If the specified file doesn't exist, RFmx creates a
new file, whereas contents of an already existing file are overwritten.
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(snp_file_path, "snp_file_path")
updated_selector_string = _helper.validate_and_update_selector_string(
selector_string, self._signal_obj
)
error_code = self._interpreter.s_params_export_to_snp_file(
updated_selector_string, snp_file_path
)
finally:
self._session_function_lock.exit_read_lock()
return error_code
[docs]
@_raise_if_disposed
def get_s_parameter(self, selector_string):
r"""Returns the S-Parameter being measured in format S(receiver port number)(source port number)
Use "sparam(n)" as the selector string for this method.
**Supported devices**: NI PXIe-5633
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.
Returns:
Tuple (s_parameter, error_code):
s_parameter (string):
This parameter returns the S-Parameter being measured in format S<*receiver port number*><*source port number*>.
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
)
s_parameter, error_code = self._interpreter.get_s_parameter(updated_selector_string)
finally:
self._session_function_lock.exit_read_lock()
return s_parameter, error_code