"""Provides methods to fetch and read the Acp measurement results."""
import functools
import nirfmxcdma2k.attributes as attributes
import nirfmxcdma2k.errors as errors
import nirfmxcdma2k.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 Cdma2k signal configuration")
return f(*xs, **kws)
return aux
[docs]
class AcpResults(object):
"""Provides methods to fetch and read the Acp measurement results."""
def __init__(self, signal_obj):
"""Provides methods to fetch and read the Acp measurement results."""
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_carrier_absolute_power(self, selector_string):
r"""Gets the absolute measured carrier power. This value is expressed in dBm.
You do not need to use a selector string to read this result for the default signal and result 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 and named results.
Args:
selector_string (string):
Pass an empty string.
Returns:
Tuple (attr_val, error_code):
attr_val (float):
Returns the absolute measured carrier power. This value is expressed in dBm.
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.ACP_RESULTS_CARRIER_ABSOLUTE_POWER.value,
)
finally:
self._session_function_lock.exit_read_lock()
return attr_val, error_code
[docs]
@_raise_if_disposed
def get_lower_offset_absolute_power(self, selector_string):
r"""Gets the absolute measured lower offset channel power. This value is expressed in dBm.
Use "offset<
<format type="monospace-italic">n</format>
>" as the `Selector String <https://www.ni.com/docs/en-US/bundle/rfmx/page/selector-strings-net.html>`_ to read
this result.
Args:
selector_string (string):
Pass an empty string.
Returns:
Tuple (attr_val, error_code):
attr_val (float):
Returns the absolute measured lower offset channel power. This value is expressed in dBm.
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.ACP_RESULTS_LOWER_OFFSET_ABSOLUTE_POWER.value,
)
finally:
self._session_function_lock.exit_read_lock()
return attr_val, error_code
[docs]
@_raise_if_disposed
def get_lower_offset_relative_power(self, selector_string):
r"""Gets the lower offset channel power measured relative to the carrier absolute integrated power. This value is
expressed in dB.
Use "offset<
<format type="monospace-italic">n</format>
>" as the `Selector String <https://www.ni.com/docs/en-US/bundle/rfmx/page/selector-strings-net.html>`_ to read
this result.
Args:
selector_string (string):
Pass an empty string.
Returns:
Tuple (attr_val, error_code):
attr_val (float):
Returns the lower offset channel power measured relative to the carrier absolute integrated power. This value is
expressed in dB.
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.ACP_RESULTS_LOWER_OFFSET_RELATIVE_POWER.value,
)
finally:
self._session_function_lock.exit_read_lock()
return attr_val, error_code
[docs]
@_raise_if_disposed
def get_upper_offset_absolute_power(self, selector_string):
r"""Gets the absolute measured upper offset channel power. This value is expressed in dBm.
Use "offset<
<format type="monospace-italic">n</format>
>" as the `Selector String <https://www.ni.com/docs/en-US/bundle/rfmx/page/selector-strings-net.html>`_ to read
this result.
Args:
selector_string (string):
Pass an empty string.
Returns:
Tuple (attr_val, error_code):
attr_val (float):
Returns the absolute measured upper offset channel power. This value is expressed in dBm.
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.ACP_RESULTS_UPPER_OFFSET_ABSOLUTE_POWER.value,
)
finally:
self._session_function_lock.exit_read_lock()
return attr_val, error_code
[docs]
@_raise_if_disposed
def get_upper_offset_relative_power(self, selector_string):
r"""Gets the upper offset channel power measured relative to the carrier absolute integrated power. This value is
expressed in dB.
Use "offset<
<format type="monospace-italic">n</format>
>" as the `Selector String <https://www.ni.com/docs/en-US/bundle/rfmx/page/selector-strings-net.html>`_ to read
this result.
Args:
selector_string (string):
Pass an empty string.
Returns:
Tuple (attr_val, error_code):
attr_val (float):
Returns the upper offset channel power measured relative to the carrier absolute integrated power. This value is
expressed in dB.
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.ACP_RESULTS_UPPER_OFFSET_RELATIVE_POWER.value,
)
finally:
self._session_function_lock.exit_read_lock()
return attr_val, error_code
[docs]
@_raise_if_disposed
def fetch_offset_measurement_array(self, selector_string, timeout):
r"""Returns the absolute and relative powers measured in the offset channel. The relative powers are measured relative to
the carrier absolute power.
Args:
selector_string (string):
This parameter specifies a `Selector String
<https://www.ni.com/docs/en-US/bundle/rfmx/page/selector-strings-net.html>`_ comprising of result
name. Examples:
""
"signal::sig1"
"result::r1"
"signal::sig1/result::r1"
You can use the :py:meth:`build_result_string` method to build the selector string.
timeout (float):
This parameter specifies the timeout for fetching the specified measurement. This value is expressed in seconds. 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 (lower_relative_power, upper_relative_power, lower_absolute_power, upper_absolute_power, error_code):
lower_relative_power (float):
This parameter returns the array of lower offset channel powers measured relative to the carrier absolute power. This
value is expressed in dB.
upper_relative_power (float):
This parameter returns the array of upper offset channel powers measured relative to the carrier absolute power. This
value is expressed in dB.
lower_absolute_power (float):
This parameter returns the array of lower offset channel absolute powers.
upper_absolute_power (float):
This parameter returns the array of upper offset channel absolute powers.
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
)
(
lower_relative_power,
upper_relative_power,
lower_absolute_power,
upper_absolute_power,
error_code,
) = self._interpreter.acp_fetch_offset_measurement_array(
updated_selector_string, timeout
)
finally:
self._session_function_lock.exit_read_lock()
return (
lower_relative_power,
upper_relative_power,
lower_absolute_power,
upper_absolute_power,
error_code,
)
[docs]
@_raise_if_disposed
def fetch_offset_measurement(self, selector_string, timeout):
r"""Returns the absolute and relative powers measured in the specified offset channel. The relative powers are measured
relative to the carrier absolute power.
Use "offset<n>" as the selector string to read results from this method.
Args:
selector_string (string):
This parameter specifies a `Selector String
<https://www.ni.com/docs/en-US/bundle/rfmx/page/selector-strings-net.html>`_ comprising of result
name, and offset number. Examples:
"offset0"
"signal::sig1/offset0"
"result::r1/offset0"
"signal::sig1/result::r1/offset0"
You can use the :py:meth:`build_offset_string` method to build the selector string.
timeout (float):
This parameter specifies the timeout for fetching the specified measurement. This value is expressed in seconds. 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 (lower_relative_power, upper_relative_power, lower_absolute_power, upper_absolute_power, error_code):
lower_relative_power (float):
This parameter returns the lower offset channel power measured relative to the carrier absolute power. This value is
expressed in dB.
upper_relative_power (float):
This parameter returns the upper offset channel power measured relative to the carrier absolute power. This value is
expressed in dB.
lower_absolute_power (float):
This parameter returns the lower offset channel absolute power.
upper_absolute_power (float):
This parameter returns the upper offset channel absolute power.
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
)
(
lower_relative_power,
upper_relative_power,
lower_absolute_power,
upper_absolute_power,
error_code,
) = self._interpreter.acp_fetch_offset_measurement(updated_selector_string, timeout)
finally:
self._session_function_lock.exit_read_lock()
return (
lower_relative_power,
upper_relative_power,
lower_absolute_power,
upper_absolute_power,
error_code,
)
[docs]
@_raise_if_disposed
def fetch_spectrum(self, selector_string, timeout, spectrum):
r"""Fetches the spectrum used for the ACP measurement.
Args:
selector_string (string):
This parameter specifies a `Selector String
<https://www.ni.com/docs/en-US/bundle/rfmx/page/selector-strings-net.html>`_ comprising of result
name. Examples:
""
"signal::sig1"
"result::r1"
"signal::sig1/result::r1"
You can use the :py:meth:`build_result_string` method to build the selector string.
timeout (float):
This parameter specifies the timeout for fetching the specified measurement. This value is expressed in seconds. 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.
spectrum (numpy.float32):
This parameter returns the averaged power measured at each frequency bin. This value is expressed in dBm or dBm/Hz.
Returns:
Tuple (x0, dx, error_code):
x0 (float):
This parameter returns the start frequency. This value is expressed in Hz.
dx (float):
This parameter returns the frequency bin spacing. This value is expressed in Hz.
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
)
x0, dx, error_code = self._interpreter.acp_fetch_spectrum(
updated_selector_string, timeout, spectrum
)
finally:
self._session_function_lock.exit_read_lock()
return x0, dx, error_code
[docs]
@_raise_if_disposed
def fetch_carrier_absolute_power(self, selector_string, timeout):
r"""Returns the absolute carrier power.
Args:
selector_string (string):
This parameter specifies a `Selector String
<https://www.ni.com/docs/en-US/bundle/rfmx/page/selector-strings-net.html>`_ comprising of result
name. Examples:
""
"signal::sig1"
"result::r1"
"signal::sig1/result::r1"
You can use the :py:meth:`build_result_string` method to build the selector string.
timeout (float):
This parameter specifies the timeout for fetching the specified measurement. This value is expressed in seconds. 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 (carrier_absolute_power, error_code):
carrier_absolute_power (float):
This parameter returns the averaged channel power measured in the specified integration bandwidth. This value is
expressed in dBm.
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
)
carrier_absolute_power, error_code = self._interpreter.acp_fetch_carrier_absolute_power(
updated_selector_string, timeout
)
finally:
self._session_function_lock.exit_read_lock()
return carrier_absolute_power, error_code
[docs]
@_raise_if_disposed
def fetch_absolute_powers_trace(
self, selector_string, timeout, trace_index, absolute_powers_trace
):
r"""Fetches the absolute powers trace for the ACP measurement.
Args:
selector_string (string):
This parameter specifies a `Selector String
<https://www.ni.com/docs/en-US/bundle/rfmx/page/selector-strings-net.html>`_ comprising of result
name. Examples:
""
"signal::sig1"
"result::r1"
"signal::sig1/result::r1"
You can use the :py:meth:`build_result_string` method to build the selector string.
timeout (float):
This parameter specifies the timeout for fetching the specified measurement. This value is expressed in seconds. 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.
trace_index (int):
Specifies the index of the trace to fetch. The **traceIndex** can range from 0 to (Number of carriers + 2*Number of
offsets).
absolute_powers_trace (numpy.float32):
This parameter returns the array of traces of absolute integrated power measured in each offset channel.
Returns:
Tuple (x0, dx, error_code):
x0 (float):
This parameter returns the start frequency. This value is expressed in Hz.
dx (float):
This parameter returns the frequency bin spacing. This value is expressed in Hz.
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
)
x0, dx, error_code = self._interpreter.acp_fetch_absolute_powers_trace(
updated_selector_string, timeout, trace_index, absolute_powers_trace
)
finally:
self._session_function_lock.exit_read_lock()
return x0, dx, error_code
[docs]
@_raise_if_disposed
def fetch_relative_powers_trace(
self, selector_string, timeout, trace_index, relative_powers_trace
):
r"""Fetches the relative powers trace for the ACP measurement.
Args:
selector_string (string):
This parameter specifies a `Selector String
<https://www.ni.com/docs/en-US/bundle/rfmx/page/selector-strings-net.html>`_ comprising of result
name. Examples:
""
"signal::sig1"
"result::r1"
"signal::sig1/result::r1"
You can use the :py:meth:`build_result_string` method to build the selector string.
timeout (float):
This parameter specifies the timeout for fetching the specified measurement. This value is expressed in seconds. 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.
trace_index (int):
Specifies the index of the trace to fetch. The **traceIndex** can range from 0 to (Number of carriers + 2*Number of
offsets).
relative_powers_trace (numpy.float32):
This parameter returns the array of relative power traces measured in each offset channel relative to the absolute
carrier power.
Returns:
Tuple (x0, dx, error_code):
x0 (float):
This parameter returns the start frequency. This value is expressed in Hz.
dx (float):
This parameter returns the frequency bin spacing. This value is expressed in Hz.
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
)
x0, dx, error_code = self._interpreter.acp_fetch_relative_powers_trace(
updated_selector_string, timeout, trace_index, relative_powers_trace
)
finally:
self._session_function_lock.exit_read_lock()
return x0, dx, error_code