Utilities

Utilities module is mostly used for development of Quantify, not for the serving end user purposes. Here we store several examples of what is already there and how to work with them.

Deprecation helper

Note that the name of the current module is __main__, that gets normalized into --main-- by the @deprecated helper. If you use these helpers in the actual code, the name of the package will appear instead.

import warnings
from quantify_core.utilities import deprecated

@deprecated("99.99", 'Initialize the "foo" literal directly.')
def get_foo():
    return "foo"


with warnings.catch_warnings(record=True) as w:
    warnings.simplefilter("always")
    get_foo()  # issues deprecation warning.

assert len(w) == 1
assert w[0].category is FutureWarning
print(w[0].message)

Function __main__.get_foo() is deprecated and will be removed in --main---99.99. Initialize the "foo" literal directly.

class NewClass:
    def __init__(self, val):
        self._val = val

    def val(self):
        return self._val

@deprecated("99.99", NewClass)
class OldClass:
    pass

with warnings.catch_warnings(record=True) as w:
    warnings.simplefilter("always")
    obj = OldClass(42)  # type: ignore

assert len(w) == 1
assert w[0].category is FutureWarning
print(w[0].message)
print("obj.val() =", obj.val())  # type: ignore

Class __main__.OldClass is deprecated and will be removed in --main---99.99. Use __main__.NewClass instead.
obj.val() = 42

class SomeClass:
    def __init__(self, val):
        self._val = val

    def val(self):
        return self._val

    @deprecated("7.77", val)
    def get_val(self):
        '''Deprecated alias'''

with warnings.catch_warnings(record=True) as w:
    warnings.simplefilter("always")
    val = SomeClass(42).get_val()  # issues deprecation warning.

assert len(w) == 1
assert w[0].category is FutureWarning
print(w[0].message)
print("obj.get_val() =", val)

Function __main__.SomeClass.get_val() is deprecated and will be removed in --main---7.77. Use __main__.SomeClass.val() instead.
obj.get_val() = 42

Providing example data

When writing documentation, author frequently needs to provide some semi-realistic data to provide a reader with more context and intended use case. We have some helpers to do so for the context of typical quantum computing data.

Trace readout mock data

import matplotlib.pyplot as plt

from quantify_core.utilities.examples_support import mk_trace_for_iq_shot, mk_trace_time

SHOT = 0.6 + 1.2j

time = mk_trace_time()
trace = mk_trace_for_iq_shot(SHOT)

fig, ax = plt.subplots(1, 1, figsize=(12, 12 / 1.61 / 2))
_ = ax.plot(time * 1e6, trace.imag, ".-", label="I-quadrature")
_ = ax.plot(time * 1e6, trace.real, ".-", label="Q-quadrature")
_ = ax.set_xlabel("Time [µs]")
_ = ax.set_ylabel("Amplitude [V]")
_ = ax.legend()

Single-shot readout mock data

import matplotlib.pyplot as plt

from quantify_core.utilities.examples_support import mk_iq_shots

center_0, center_1, center_2 = 0.6 + 1.2j, -0.2 + 0.5j, 0 + 1.5j

data = mk_iq_shots(
    100,
    sigmas=[0.1] * 2,
    centers=(center_0, center_1),
    probabilities=(0.3, 1 - 0.3),
)

fig, ax = plt.subplots()
ax.plot(data.real, data.imag, "o", label="Shots")
ax.plot(center_0.real, center_0.imag, "^", label="|0>", markersize=10)
ax.plot(center_1.real, center_1.imag, "d", label="|1>", markersize=10)
_ = ax.legend()

data = mk_iq_shots(
    200,
    sigmas=[0.1] * 3,
    centers=(center_0, center_1, center_2),
    probabilities=[0.35, 0.35, 1 - 0.35 - 0.35],
)

fig, ax = plt.subplots()
ax.plot(data.real, data.imag, "o", label="Shots")
ax.plot(center_0.real, center_0.imag, "^", label="|0>", markersize=10)
ax.plot(center_1.real, center_1.imag, "d", label="|1>", markersize=10)
ax.plot(center_2.real, center_2.imag, "*", label="|2>", markersize=10)
_ = ax.legend()

Inspect utilities

We have a small set of utilities to generate list of classes, functions, members of module, etc. They are mostly useful for writing documentation, but probably autogenerated API documentation is a better fit in most cases.

from typing import Dict

from quantify_core.utilities import inspect_utils
import quantify_core.analysis.base_analysis as ba

class_dict: Dict[str, type] = inspect_utils.get_classes(ba)
print(class_dict)

{'AnalysisMeta': <class 'quantify_core.analysis.base_analysis.AnalysisMeta'>, 'AnalysisSteps': <enum 'AnalysisSteps'>, 'BaseAnalysis': <class 'quantify_core.analysis.base_analysis.BaseAnalysis'>, 'Basic1DAnalysis': <class 'quantify_core.analysis.base_analysis.Basic1DAnalysis'>, 'Basic2DAnalysis': <class 'quantify_core.analysis.base_analysis.Basic2DAnalysis'>, 'BasicAnalysis': <class 'quantify_core.analysis.base_analysis.BasicAnalysis'>, '_FiguresMplCache': <class 'quantify_core.analysis.base_analysis._FiguresMplCache'>}

from quantify_core.utilities import inspect_utils

function_dict: Dict[str, type] = inspect_utils.get_functions(inspect_utils)
print(function_dict)

{'display_source_code': <function display_source_code at 0x7e38812d2b80>, 'get_classes': <function get_classes at 0x7e3881bf6550>, 'get_functions': <function get_functions at 0x7e38812d2f70>, 'get_members_of_module': <function get_members_of_module at 0x7e38813b5ee0>}