diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 00000000..e69de29b diff --git a/404.html b/404.html new file mode 100644 index 00000000..27d680e8 --- /dev/null +++ b/404.html @@ -0,0 +1,862 @@ + + + + + + + + + + + + + + + + + + + + + The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ +

404 - Not found

+ +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API_references/components/basic_quam/index.html b/API_references/components/basic_quam/index.html new file mode 100644 index 00000000..b1a6d2da --- /dev/null +++ b/API_references/components/basic_quam/index.html @@ -0,0 +1,1021 @@ + + + + + + + + + + + + + + + + + + + + + Basic quam - The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ + + + +

Basic quam

+ +
+ + + + +
+ + + +
+ + + + + + + + +
+ + + +

+ BasicQuAM + + +

+ + +
+

+ Bases: QuamRoot

+ + +

Basic top-level QuAM root component.

+

If custom QuAM components are used, a custom QuAM root component should be created.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
channels + Dict[str, Channel] + +
+

A dictionary of channels.

+
+ 		+ required +
octaves + Dict[str, Octave] + +
+

A dictionary of octaves.

+
+ 		+ required +
+ +
+ Source code in quam/components/basic_quam.py + 
14
+15
+16
+17
+18
+19
+20
+21
+22
+23
+24
+25
+26
@quam_dataclass
+class BasicQuAM(QuamRoot):
+    """Basic top-level QuAM root component.
+
+    If custom QuAM components are used, a custom QuAM root component should be created.
+
+    Args:
+        channels (Dict[str, Channel], optional): A dictionary of channels.
+        octaves (Dict[str, Octave], optional): A dictionary of octaves.
+    """
+
+    channels: Dict[str, Channel] = field(default_factory=dict)
+    octaves: Dict[str, Octave] = field(default_factory=dict)
+
+
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ + + + +
+ +
+ +
+ + + + + + + + + + + + + +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API_references/components/basic_quam_API/index.html b/API_references/components/basic_quam_API/index.html new file mode 100644 index 00000000..e229ca94 --- /dev/null +++ b/API_references/components/basic_quam_API/index.html @@ -0,0 +1,1088 @@ + + + + + + + + + + + + + + + + + + + + + + + + + BasicQuAM API - The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ + + + +

BasicQuAM API

+ + +
+ + + + +
+ + + +
+ + + + + + + + +
+ + + +

+ BasicQuAM + + +

+ + +
+

+ Bases: QuamRoot

+ + +

Basic top-level QuAM root component.

+

If custom QuAM components are used, a custom QuAM root component should be created.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
channels + Dict[str, Channel] + +
+

A dictionary of channels.

+
+ 		+ required +
octaves + Dict[str, Octave] + +
+

A dictionary of octaves.

+
+ 		+ required +
+ +
+ Source code in quam/components/basic_quam.py + 
14
+15
+16
+17
+18
+19
+20
+21
+22
+23
+24
+25
+26
@quam_dataclass
+class BasicQuAM(QuamRoot):
+    """Basic top-level QuAM root component.
+
+    If custom QuAM components are used, a custom QuAM root component should be created.
+
+    Args:
+        channels (Dict[str, Channel], optional): A dictionary of channels.
+        octaves (Dict[str, Octave], optional): A dictionary of octaves.
+    """
+
+    channels: Dict[str, Channel] = field(default_factory=dict)
+    octaves: Dict[str, Octave] = field(default_factory=dict)
+
+
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ + + + +
+ +
+ +
+ + + + + + + + + + + + + +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API_references/components/channels/index.html b/API_references/components/channels/index.html new file mode 100644 index 00000000..ad3a6a4c --- /dev/null +++ b/API_references/components/channels/index.html @@ -0,0 +1,9403 @@ + + + + + + + + + + + + + + + + + + + + + Channels - The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ + + + +

Channels

+ +
+ + + + +
+ + + +
+ + + + + + + + +
+ + + +

+ Channel + + +

+ + +
+

+ Bases: QuamComponent

+ + +

Base QuAM component for a channel, can be output, input or both.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
operations + Dict[str, Pulse] + +
+

A dictionary of pulses to be played on this +channel. The key is the pulse label (e.g. "X90") and value is a Pulse.

+
+ 		+ required +
id + (str, int) + +
+

The id of the channel, used to generate the name. +Can be a string, or an integer in which case it will add +Channel._default_label.

+
+ 		+ required +
+ +
+ Source code in quam/components/channels.py + 
155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
+182
+183
+184
+185
+186
+187
+188
+189
+190
+191
+192
+193
+194
+195
+196
+197
+198
+199
+200
+201
+202
+203
+204
+205
+206
+207
+208
+209
+210
+211
+212
+213
+214
+215
+216
+217
+218
+219
+220
+221
+222
+223
+224
+225
+226
+227
+228
+229
+230
+231
+232
+233
+234
+235
+236
+237
+238
+239
+240
+241
+242
+243
+244
+245
+246
+247
+248
+249
+250
+251
+252
+253
+254
+255
+256
+257
+258
+259
+260
+261
+262
+263
+264
+265
+266
+267
+268
+269
+270
+271
+272
+273
+274
+275
+276
+277
+278
+279
+280
+281
+282
+283
+284
+285
+286
+287
+288
+289
+290
+291
+292
+293
+294
+295
+296
+297
+298
+299
+300
+301
+302
+303
+304
+305
+306
+307
+308
+309
+310
+311
+312
+313
+314
+315
+316
+317
+318
+319
+320
+321
+322
+323
+324
+325
+326
+327
+328
+329
+330
+331
+332
+333
+334
+335
+336
+337
+338
+339
+340
+341
+342
+343
+344
+345
+346
+347
+348
+349
+350
+351
+352
+353
+354
+355
+356
+357
+358
+359
+360
+361
+362
+363
+364
+365
+366
+367
+368
+369
+370
+371
+372
+373
+374
+375
+376
+377
+378
+379
+380
+381
+382
+383
+384
+385
+386
+387
+388
+389
+390
+391
+392
+393
+394
+395
+396
+397
+398
+399
+400
+401
+402
+403
+404
+405
+406
+407
+408
+409
+410
+411
+412
+413
+414
+415
+416
+417
+418
+419
+420
+421
+422
+423
+424
+425
+426
+427
+428
+429
+430
+431
+432
+433
+434
+435
+436
+437
+438
+439
+440
+441
+442
+443
+444
+445
+446
+447
+448
+449
+450
+451
+452
+453
+454
+455
+456
+457
+458
@quam_dataclass
+class Channel(QuamComponent):
+    """Base QuAM component for a channel, can be output, input or both.
+
+    Args:
+        operations (Dict[str, Pulse]): A dictionary of pulses to be played on this
+            channel. The key is the pulse label (e.g. "X90") and value is a Pulse.
+        id (str, int): The id of the channel, used to generate the name.
+            Can be a string, or an integer in which case it will add
+            `Channel._default_label`.
+    """
+
+    operations: Dict[str, Pulse] = field(default_factory=dict)
+
+    id: Union[str, int] = None
+    _default_label: ClassVar[str] = "ch"  # Used to determine name from id
+
+    digital_outputs: Dict[str, DigitalOutputChannel] = field(default_factory=dict)
+
+    @property
+    def name(self) -> str:
+        cls_name = self.__class__.__name__
+
+        if self.id is not None:
+            if str_ref.is_reference(self.id):
+                raise AttributeError(
+                    f"{cls_name}.name cannot be determined. "
+                    f"Please either set {cls_name}.id to a string or integer, "
+                    f"or {cls_name} should be an attribute of another QuAM component."
+                )
+            if isinstance(self.id, str):
+                return self.id
+            else:
+                return f"{self._default_label}{self.id}"
+        if self.parent is None:
+            raise AttributeError(
+                f"{cls_name}.name cannot be determined. "
+                f"Please either set {cls_name}.id to a string or integer, "
+                f"or {cls_name} should be an attribute of another QuAM component with "
+                "a name."
+            )
+        if isinstance(self.parent, QuamDict):
+            return self.parent.get_attr_name(self)
+        if not hasattr(self.parent, "name"):
+            raise AttributeError(
+                f"{cls_name}.name cannot be determined. "
+                f"Please either set {cls_name}.id to a string or integer, "
+                f"or {cls_name} should be an attribute of another QuAM component with "
+                "a name."
+            )
+        return f"{self.parent.name}{str_ref.DELIMITER}{self.parent.get_attr_name(self)}"
+
+    @property
+    def pulse_mapping(self):
+        return {label: pulse.pulse_name for label, pulse in self.operations.items()}
+
+    def play(
+        self,
+        pulse_name: str,
+        amplitude_scale: Union[float, AmpValuesType] = None,
+        duration: QuaNumberType = None,
+        condition: QuaExpressionType = None,
+        chirp: ChirpType = None,
+        truncate: QuaNumberType = None,
+        timestamp_stream: StreamType = None,
+        continue_chirp: bool = False,
+        target: str = "",
+        validate: bool = True,
+    ):
+        """Play a pulse on this channel.
+
+        Args:
+            pulse_name (str): The name of the pulse to play. Should be registered in
+                `self.operations`.
+            amplitude_scale (float, _PulseAmp): Amplitude scale of the pulse.
+                Can be either a float, or qua.amp(float).
+            duration (int): Duration of the pulse in units of the clock cycle (4ns).
+                If not provided, the default pulse duration will be used. It is possible
+                to dynamically change the duration of both constant and arbitrary
+                pulses. Arbitrary pulses can only be stretched, not compressed.
+            chirp (Union[(list[int], str), (int, str)]): Allows to perform
+                piecewise linear sweep of the element's intermediate
+                frequency in time. Input should be a tuple, with the 1st
+                element being a list of rates and the second should be a
+                string with the units. The units can be either: 'Hz/nsec',
+                'mHz/nsec', 'uHz/nsec', 'pHz/nsec' or 'GHz/sec', 'MHz/sec',
+                'KHz/sec', 'Hz/sec', 'mHz/sec'.
+            truncate (Union[int, QUA variable of type int]): Allows playing
+                only part of the pulse, truncating the end. If provided,
+                will play only up to the given time in units of the clock
+                cycle (4ns).
+            condition (A logical expression to evaluate.): Will play analog
+                pulse only if the condition's value is true. Any digital
+                pulses associated with the operation will always play.
+            timestamp_stream (Union[str, _ResultSource]): (Supported from
+                QOP 2.2) Adding a `timestamp_stream` argument will save the
+                time at which the operation occurred to a stream. If the
+                `timestamp_stream` is a string ``label``, then the timestamp
+                handle can be retrieved with
+                `qm._results.JobResults.get` with the same ``label``.
+            validate (bool): If True (default), validate that the pulse is registered
+                in Channel.operations
+
+        Note:
+            The `element` argument from `qm.qua.play()`is not needed, as it is
+            automatically set to `self.name`.
+
+        """
+        if validate and pulse_name not in self.operations:
+            raise KeyError(
+                f"Operation '{pulse_name}' not found in channel '{self.name}'"
+            )
+
+        if amplitude_scale is not None:
+            if not isinstance(amplitude_scale, _PulseAmp):
+                amplitude_scale = amp(amplitude_scale)
+            pulse = pulse_name * amplitude_scale
+        else:
+            pulse = pulse_name
+
+        # At the moment, self.name is not defined for Channel because it could
+        # be a property or dataclass field in a subclass.
+        # # TODO Find elegant solution for Channel.name.
+        play(
+            pulse=pulse,
+            element=self.name,
+            duration=duration,
+            condition=condition,
+            chirp=chirp,
+            truncate=truncate,
+            timestamp_stream=timestamp_stream,
+            continue_chirp=continue_chirp,
+            target=target,
+        )
+
+    def wait(self, duration: QuaNumberType, *other_elements: Union[str, "Channel"]):
+        """Wait for the given duration on all provided elements without outputting anything.
+
+        Duration is in units of the clock cycle (4ns)
+
+        Args:
+            duration (Union[int,QUA variable of type int]): time to wait in
+                units of the clock cycle (4ns). Range: [4, $2^{31}-1$]
+                in steps of 1.
+            *other_elements (Union[str,sequence of str]): elements to wait on,
+                in addition to this channel
+
+        Warning:
+            In case the value of this is outside the range above, unexpected results may occur.
+
+        Note:
+            The current channel element is always included in the wait operation.
+
+        Note:
+            The purpose of the `wait` operation is to add latency. In most cases, the
+            latency added will be exactly the same as that specified by the QUA variable or
+            the literal used. However, in some cases an additional computational latency may
+            be added. If the actual wait time has significance, such as in characterization
+            experiments, the actual wait time should always be verified with a simulator.
+        """
+        other_elements_str = [
+            element if isinstance(element, str) else str(element)
+            for element in other_elements
+        ]
+        wait(duration, self.name, *other_elements_str)
+
+    def align(self, *other_elements):
+        if not other_elements:
+            align()
+        else:
+            other_elements_str = [
+                element if isinstance(element, str) else str(element)
+                for element in other_elements
+            ]
+            align(self.name, *other_elements_str)
+
+    def update_frequency(
+        self,
+        new_frequency: QuaNumberType,
+        units: str = "Hz",
+        keep_phase: bool = False,
+    ):
+        """Dynamically update the frequency of the associated oscillator.
+
+        This changes the frequency from the value defined in the channel.
+
+        The behavior of the phase (continuous vs. coherent) is controlled by the
+        ``keep_phase`` parameter and is discussed in the documentation.
+
+        Args:
+            new_frequency (int): The new frequency value to set in units set
+                by ``units`` parameter. In steps of 1.
+            units (str): units of new frequency. Useful when sub-Hz
+                precision is required. Allowed units are "Hz", "mHz", "uHz",
+                "nHz", "pHz"
+            keep_phase (bool): Determine whether phase will be continuous
+                through the change (if ``True``) or it will be coherent,
+                only the frequency will change (if ``False``).
+
+        Example:
+            ```python
+            with program() as prog:
+                update_frequency("q1", 4e6) # will set the frequency to 4 MHz
+
+                ### Example for sub-Hz resolution
+                # will set the frequency to 100 Hz (due to casting to int)
+                update_frequency("q1", 100.7)
+
+                # will set the frequency to 100.7 Hz
+                update_frequency("q1", 100700, units='mHz')
+            ```
+        """
+        update_frequency(self.name, new_frequency, units, keep_phase)
+
+    def frame_rotation(self, angle: QuaNumberType):
+        r"""Shift the phase of the channel element's oscillator by the given angle.
+
+        This is typically used for virtual z-rotations.
+
+        Note:
+            The fixed point format of QUA variables of type fixed is 4.28, meaning the
+            phase must be between $-8$ and $8-2^{28}$. Otherwise the phase value will be
+            invalid. It is therefore better to use `frame_rotation_2pi()` which avoids
+            this issue.
+
+        Note:
+            The phase is accumulated with a resolution of 16 bit.
+            Therefore, *N* changes to the phase can result in a phase (and amplitude)
+            inaccuracy of about :math:`N \cdot 2^{-16}`. To null out this accumulated
+            error, it is recommended to use `reset_frame(el)` from time to time.
+
+        Args:
+            angle (Union[float, QUA variable of type fixed]): The angle to
+                add to the current phase (in radians)
+            *elements (str): a single element whose oscillator's phase will
+                be shifted. multiple elements can be given, in which case
+                all of their oscillators' phases will be shifted
+
+        """
+        frame_rotation(angle, self.name)
+
+    def frame_rotation_2pi(self, angle: QuaNumberType):
+        r"""Shift the phase of the oscillator associated with an element by the given
+        angle in units of 2pi radians.
+
+        This is typically used for virtual z-rotations.
+
+        Note:
+            Unlike the case of frame_rotation(), this method performs the 2-pi radian
+            wrap around of the angle automatically.
+
+        Note:
+            The phase is accumulated with a resolution of 16 bit.
+            Therefore, *N* changes to the phase can result in a phase inaccuracy of
+            about :math:`N \cdot 2^{-16}`. To null out this accumulated error, it is
+            recommended to use `reset_frame(el)` from time to time.
+
+        Args:
+            angle (Union[float,QUA variable of type real]): The angle to add
+                to the current phase (in $2\pi$ radians)
+        """
+        frame_rotation_2pi(angle, self.name)
+
+    def _config_add_digital_outputs(self, config: Dict[str, dict]) -> None:
+        """Adds the digital outputs to the QUA config.
+
+        config.elements.<element_name>.digitalInputs will be updated with the digital
+        outputs of this channel.
+
+        Note that the digital outputs are added separately to the controller config in
+        `DigitalOutputChannel.apply_to_config`.
+
+        Args:
+            config (dict): The QUA config that's in the process of being generated.
+        """
+        if not self.digital_outputs:
+            return
+
+        element_cfg = config["elements"][self.name]
+        element_cfg.setdefault("digitalInputs", {})
+
+        for name, digital_output in self.digital_outputs.items():
+            digital_cfg = digital_output.generate_element_config()
+            element_cfg["digitalInputs"][name] = digital_cfg
+
+    def apply_to_config(self, config: Dict[str, dict]) -> None:
+        """Adds this Channel to the QUA configuration.
+
+        config.elements.<element_name> will be created, and the operations are added.
+
+        Args:
+            config (dict): The QUA config that's in the process of being generated.
+
+        Raises:
+            ValueError: If the channel already exists in the config.
+        """
+        if self.name in config["elements"]:
+            raise ValueError(
+                f"Cannot add channel '{self.name}' to the config because it already "
+                f"exists. Existing entry: {config['elements'][self.name]}"
+            )
+        config["elements"][self.name] = {"operations": self.pulse_mapping}
+
+        self._config_add_digital_outputs(config)
+
+
+ + + +
+ + + + + + + + + +
+ + +

+ apply_to_config(config) + +

+ + +
+ +

Adds this Channel to the QUA configuration.

+

config.elements. will be created, and the operations are added.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
config + dict + +
+

The QUA config that's in the process of being generated.

+
+ 		+ required +
+ + +

Raises:

+ + + + + + + + + + + + + +
TypeDescription
+ ValueError + +
+

If the channel already exists in the config.

+
+
+ +
+ Source code in quam/components/channels.py + 
440
+441
+442
+443
+444
+445
+446
+447
+448
+449
+450
+451
+452
+453
+454
+455
+456
+457
+458
def apply_to_config(self, config: Dict[str, dict]) -> None:
+    """Adds this Channel to the QUA configuration.
+
+    config.elements.<element_name> will be created, and the operations are added.
+
+    Args:
+        config (dict): The QUA config that's in the process of being generated.
+
+    Raises:
+        ValueError: If the channel already exists in the config.
+    """
+    if self.name in config["elements"]:
+        raise ValueError(
+            f"Cannot add channel '{self.name}' to the config because it already "
+            f"exists. Existing entry: {config['elements'][self.name]}"
+        )
+    config["elements"][self.name] = {"operations": self.pulse_mapping}
+
+    self._config_add_digital_outputs(config)
+
+
+
+ +
+ +
+ + +

+ frame_rotation(angle) + +

+ + +
+ +

Shift the phase of the channel element's oscillator by the given angle.

+

This is typically used for virtual z-rotations.

+ + +
+ Note +

The fixed point format of QUA variables of type fixed is 4.28, meaning the +phase must be between $-8$ and $8-2^{28}$. Otherwise the phase value will be +invalid. It is therefore better to use frame_rotation_2pi() which avoids +this issue.

+
+ +
+ Note +

The phase is accumulated with a resolution of 16 bit. +Therefore, N changes to the phase can result in a phase (and amplitude) +inaccuracy of about :math:N \cdot 2^{-16}. To null out this accumulated +error, it is recommended to use reset_frame(el) from time to time.

+
+ +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
angle + Union[float, QUA variable of type fixed] + +
+

The angle to +add to the current phase (in radians)

+
+ 		+ required +
*elements + str + +
+

a single element whose oscillator's phase will +be shifted. multiple elements can be given, in which case +all of their oscillators' phases will be shifted

+
+ 		+ required +
+ +
+ Source code in quam/components/channels.py + 
369
+370
+371
+372
+373
+374
+375
+376
+377
+378
+379
+380
+381
+382
+383
+384
+385
+386
+387
+388
+389
+390
+391
+392
+393
+394
def frame_rotation(self, angle: QuaNumberType):
+    r"""Shift the phase of the channel element's oscillator by the given angle.
+
+    This is typically used for virtual z-rotations.
+
+    Note:
+        The fixed point format of QUA variables of type fixed is 4.28, meaning the
+        phase must be between $-8$ and $8-2^{28}$. Otherwise the phase value will be
+        invalid. It is therefore better to use `frame_rotation_2pi()` which avoids
+        this issue.
+
+    Note:
+        The phase is accumulated with a resolution of 16 bit.
+        Therefore, *N* changes to the phase can result in a phase (and amplitude)
+        inaccuracy of about :math:`N \cdot 2^{-16}`. To null out this accumulated
+        error, it is recommended to use `reset_frame(el)` from time to time.
+
+    Args:
+        angle (Union[float, QUA variable of type fixed]): The angle to
+            add to the current phase (in radians)
+        *elements (str): a single element whose oscillator's phase will
+            be shifted. multiple elements can be given, in which case
+            all of their oscillators' phases will be shifted
+
+    """
+    frame_rotation(angle, self.name)
+
+
+
+ +
+ +
+ + +

+ frame_rotation_2pi(angle) + +

+ + +
+ +

Shift the phase of the oscillator associated with an element by the given +angle in units of 2pi radians.

+

This is typically used for virtual z-rotations.

+ + +
+ Note +

Unlike the case of frame_rotation(), this method performs the 2-pi radian +wrap around of the angle automatically.

+
+ +
+ Note +

The phase is accumulated with a resolution of 16 bit. +Therefore, N changes to the phase can result in a phase inaccuracy of +about :math:N \cdot 2^{-16}. To null out this accumulated error, it is +recommended to use reset_frame(el) from time to time.

+
+ +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
angle + Union[float,QUA variable of type real] + +
+

The angle to add +to the current phase (in $2\pi$ radians)

+
+ 		+ required +
+ +
+ Source code in quam/components/channels.py + 
396
+397
+398
+399
+400
+401
+402
+403
+404
+405
+406
+407
+408
+409
+410
+411
+412
+413
+414
+415
+416
def frame_rotation_2pi(self, angle: QuaNumberType):
+    r"""Shift the phase of the oscillator associated with an element by the given
+    angle in units of 2pi radians.
+
+    This is typically used for virtual z-rotations.
+
+    Note:
+        Unlike the case of frame_rotation(), this method performs the 2-pi radian
+        wrap around of the angle automatically.
+
+    Note:
+        The phase is accumulated with a resolution of 16 bit.
+        Therefore, *N* changes to the phase can result in a phase inaccuracy of
+        about :math:`N \cdot 2^{-16}`. To null out this accumulated error, it is
+        recommended to use `reset_frame(el)` from time to time.
+
+    Args:
+        angle (Union[float,QUA variable of type real]): The angle to add
+            to the current phase (in $2\pi$ radians)
+    """
+    frame_rotation_2pi(angle, self.name)
+
+
+
+ +
+ +
+ + +

+ play(pulse_name, amplitude_scale=None, duration=None, condition=None, chirp=None, truncate=None, timestamp_stream=None, continue_chirp=False, target='', validate=True) + +

+ + +
+ +

Play a pulse on this channel.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
pulse_name + str + +
+

The name of the pulse to play. Should be registered in +self.operations.

+
+ 		+ required +
amplitude_scale + (float, _PulseAmp) + +
+

Amplitude scale of the pulse. +Can be either a float, or qua.amp(float).

+
+ 		+ None +
duration + int + +
+

Duration of the pulse in units of the clock cycle (4ns). +If not provided, the default pulse duration will be used. It is possible +to dynamically change the duration of both constant and arbitrary +pulses. Arbitrary pulses can only be stretched, not compressed.

+
+ 		+ None +
chirp + Union[(list[int], str), (int, str)] + +
+

Allows to perform +piecewise linear sweep of the element's intermediate +frequency in time. Input should be a tuple, with the 1st +element being a list of rates and the second should be a +string with the units. The units can be either: 'Hz/nsec', +'mHz/nsec', 'uHz/nsec', 'pHz/nsec' or 'GHz/sec', 'MHz/sec', +'KHz/sec', 'Hz/sec', 'mHz/sec'.

+
+ 		+ None +
truncate + Union[int, QUA variable of type int] + +
+

Allows playing +only part of the pulse, truncating the end. If provided, +will play only up to the given time in units of the clock +cycle (4ns).

+
+ 		+ None +
condition + A logical expression to evaluate. + +
+

Will play analog +pulse only if the condition's value is true. Any digital +pulses associated with the operation will always play.

+
+ 		+ None +
timestamp_stream + Union[str, _ResultSource] + +
+

(Supported from +QOP 2.2) Adding a timestamp_stream argument will save the +time at which the operation occurred to a stream. If the +timestamp_stream is a string label, then the timestamp +handle can be retrieved with +qm._results.JobResults.get with the same label.

+
+ 		+ None +
validate + bool + +
+

If True (default), validate that the pulse is registered +in Channel.operations

+
+ 		+ True +
+ + +
+ Note +

The element argument from qm.qua.play()is not needed, as it is +automatically set to self.name.

+
+
+ Source code in quam/components/channels.py + 
211
+212
+213
+214
+215
+216
+217
+218
+219
+220
+221
+222
+223
+224
+225
+226
+227
+228
+229
+230
+231
+232
+233
+234
+235
+236
+237
+238
+239
+240
+241
+242
+243
+244
+245
+246
+247
+248
+249
+250
+251
+252
+253
+254
+255
+256
+257
+258
+259
+260
+261
+262
+263
+264
+265
+266
+267
+268
+269
+270
+271
+272
+273
+274
+275
+276
+277
+278
+279
+280
+281
+282
+283
+284
+285
+286
+287
+288
def play(
+    self,
+    pulse_name: str,
+    amplitude_scale: Union[float, AmpValuesType] = None,
+    duration: QuaNumberType = None,
+    condition: QuaExpressionType = None,
+    chirp: ChirpType = None,
+    truncate: QuaNumberType = None,
+    timestamp_stream: StreamType = None,
+    continue_chirp: bool = False,
+    target: str = "",
+    validate: bool = True,
+):
+    """Play a pulse on this channel.
+
+    Args:
+        pulse_name (str): The name of the pulse to play. Should be registered in
+            `self.operations`.
+        amplitude_scale (float, _PulseAmp): Amplitude scale of the pulse.
+            Can be either a float, or qua.amp(float).
+        duration (int): Duration of the pulse in units of the clock cycle (4ns).
+            If not provided, the default pulse duration will be used. It is possible
+            to dynamically change the duration of both constant and arbitrary
+            pulses. Arbitrary pulses can only be stretched, not compressed.
+        chirp (Union[(list[int], str), (int, str)]): Allows to perform
+            piecewise linear sweep of the element's intermediate
+            frequency in time. Input should be a tuple, with the 1st
+            element being a list of rates and the second should be a
+            string with the units. The units can be either: 'Hz/nsec',
+            'mHz/nsec', 'uHz/nsec', 'pHz/nsec' or 'GHz/sec', 'MHz/sec',
+            'KHz/sec', 'Hz/sec', 'mHz/sec'.
+        truncate (Union[int, QUA variable of type int]): Allows playing
+            only part of the pulse, truncating the end. If provided,
+            will play only up to the given time in units of the clock
+            cycle (4ns).
+        condition (A logical expression to evaluate.): Will play analog
+            pulse only if the condition's value is true. Any digital
+            pulses associated with the operation will always play.
+        timestamp_stream (Union[str, _ResultSource]): (Supported from
+            QOP 2.2) Adding a `timestamp_stream` argument will save the
+            time at which the operation occurred to a stream. If the
+            `timestamp_stream` is a string ``label``, then the timestamp
+            handle can be retrieved with
+            `qm._results.JobResults.get` with the same ``label``.
+        validate (bool): If True (default), validate that the pulse is registered
+            in Channel.operations
+
+    Note:
+        The `element` argument from `qm.qua.play()`is not needed, as it is
+        automatically set to `self.name`.
+
+    """
+    if validate and pulse_name not in self.operations:
+        raise KeyError(
+            f"Operation '{pulse_name}' not found in channel '{self.name}'"
+        )
+
+    if amplitude_scale is not None:
+        if not isinstance(amplitude_scale, _PulseAmp):
+            amplitude_scale = amp(amplitude_scale)
+        pulse = pulse_name * amplitude_scale
+    else:
+        pulse = pulse_name
+
+    # At the moment, self.name is not defined for Channel because it could
+    # be a property or dataclass field in a subclass.
+    # # TODO Find elegant solution for Channel.name.
+    play(
+        pulse=pulse,
+        element=self.name,
+        duration=duration,
+        condition=condition,
+        chirp=chirp,
+        truncate=truncate,
+        timestamp_stream=timestamp_stream,
+        continue_chirp=continue_chirp,
+        target=target,
+    )
+
+
+
+ +
+ +
+ + +

+ update_frequency(new_frequency, units='Hz', keep_phase=False) + +

+ + +
+ +

Dynamically update the frequency of the associated oscillator.

+

This changes the frequency from the value defined in the channel.

+

The behavior of the phase (continuous vs. coherent) is controlled by the +keep_phase parameter and is discussed in the documentation.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
new_frequency + int + +
+

The new frequency value to set in units set +by units parameter. In steps of 1.

+
+ 		+ required +
units + str + +
+

units of new frequency. Useful when sub-Hz +precision is required. Allowed units are "Hz", "mHz", "uHz", +"nHz", "pHz"

+
+ 		+ 'Hz' +
keep_phase + bool + +
+

Determine whether phase will be continuous +through the change (if True) or it will be coherent, +only the frequency will change (if False).

+
+ 		+ False +
+ + +
+ Example + 
with program() as prog:
+    update_frequency("q1", 4e6) # will set the frequency to 4 MHz
+
+    ### Example for sub-Hz resolution
+    # will set the frequency to 100 Hz (due to casting to int)
+    update_frequency("q1", 100.7)
+
+    # will set the frequency to 100.7 Hz
+    update_frequency("q1", 100700, units='mHz')
+
+
+
+ Source code in quam/components/channels.py + 
331
+332
+333
+334
+335
+336
+337
+338
+339
+340
+341
+342
+343
+344
+345
+346
+347
+348
+349
+350
+351
+352
+353
+354
+355
+356
+357
+358
+359
+360
+361
+362
+363
+364
+365
+366
+367
def update_frequency(
+    self,
+    new_frequency: QuaNumberType,
+    units: str = "Hz",
+    keep_phase: bool = False,
+):
+    """Dynamically update the frequency of the associated oscillator.
+
+    This changes the frequency from the value defined in the channel.
+
+    The behavior of the phase (continuous vs. coherent) is controlled by the
+    ``keep_phase`` parameter and is discussed in the documentation.
+
+    Args:
+        new_frequency (int): The new frequency value to set in units set
+            by ``units`` parameter. In steps of 1.
+        units (str): units of new frequency. Useful when sub-Hz
+            precision is required. Allowed units are "Hz", "mHz", "uHz",
+            "nHz", "pHz"
+        keep_phase (bool): Determine whether phase will be continuous
+            through the change (if ``True``) or it will be coherent,
+            only the frequency will change (if ``False``).
+
+    Example:
+        ```python
+        with program() as prog:
+            update_frequency("q1", 4e6) # will set the frequency to 4 MHz
+
+            ### Example for sub-Hz resolution
+            # will set the frequency to 100 Hz (due to casting to int)
+            update_frequency("q1", 100.7)
+
+            # will set the frequency to 100.7 Hz
+            update_frequency("q1", 100700, units='mHz')
+        ```
+    """
+    update_frequency(self.name, new_frequency, units, keep_phase)
+
+
+
+ +
+ +
+ + +

+ wait(duration, *other_elements) + +

+ + +
+ +

Wait for the given duration on all provided elements without outputting anything.

+

Duration is in units of the clock cycle (4ns)

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
duration + Union[int,QUA variable of type int] + +
+

time to wait in +units of the clock cycle (4ns). Range: [4, $2^{31}-1$] +in steps of 1.

+
+ 		+ required +
*other_elements + Union[str,sequence of str] + +
+

elements to wait on, +in addition to this channel

+
+ 		+ () +
+ + +
+ Warning +

In case the value of this is outside the range above, unexpected results may occur.

+
+ +
+ Note +

The current channel element is always included in the wait operation.

+
+ +
+ Note +

The purpose of the wait operation is to add latency. In most cases, the +latency added will be exactly the same as that specified by the QUA variable or +the literal used. However, in some cases an additional computational latency may +be added. If the actual wait time has significance, such as in characterization +experiments, the actual wait time should always be verified with a simulator.

+
+
+ Source code in quam/components/channels.py + 
290
+291
+292
+293
+294
+295
+296
+297
+298
+299
+300
+301
+302
+303
+304
+305
+306
+307
+308
+309
+310
+311
+312
+313
+314
+315
+316
+317
+318
+319
def wait(self, duration: QuaNumberType, *other_elements: Union[str, "Channel"]):
+    """Wait for the given duration on all provided elements without outputting anything.
+
+    Duration is in units of the clock cycle (4ns)
+
+    Args:
+        duration (Union[int,QUA variable of type int]): time to wait in
+            units of the clock cycle (4ns). Range: [4, $2^{31}-1$]
+            in steps of 1.
+        *other_elements (Union[str,sequence of str]): elements to wait on,
+            in addition to this channel
+
+    Warning:
+        In case the value of this is outside the range above, unexpected results may occur.
+
+    Note:
+        The current channel element is always included in the wait operation.
+
+    Note:
+        The purpose of the `wait` operation is to add latency. In most cases, the
+        latency added will be exactly the same as that specified by the QUA variable or
+        the literal used. However, in some cases an additional computational latency may
+        be added. If the actual wait time has significance, such as in characterization
+        experiments, the actual wait time should always be verified with a simulator.
+    """
+    other_elements_str = [
+        element if isinstance(element, str) else str(element)
+        for element in other_elements
+    ]
+    wait(duration, self.name, *other_elements_str)
+
+
+
+ +
+ + + +
+ +
+ +
+ +
+ + + +

+ DigitalOutputChannel + + +

+ + +
+

+ Bases: QuamComponent

+ + +

QuAM component for a digital output channel (signal going out of the OPX)

+

Should be added to Channel.digital_outputs so that it's also added to the +respective element in the QUA config.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
opx_output + Tuple[str, int] + +
+

Channel output port from the OPX perspective, +E.g. ("con1", 1)

+
+ 		+ required +
delay + int + +
+

Delay in nanoseconds. An intrinsic negative delay of +136 ns exists by default.

+
+ 		+ required +
buffer + int + +
+

Digital pulses played to this element will be convolved +with a digital pulse of value 1 with this length [ns].

+
+ 		+ required +
shareable + bool + +
+

If True, the digital output can be shared with other +QM instances. Default is False

+
+ 		+ required +
inverted + bool + +
+

If True, the digital output is inverted. +Default is False.

+
+ 		+ required +
+

.

+ +
+ Source code in quam/components/channels.py + 
 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
@quam_dataclass
+class DigitalOutputChannel(QuamComponent):
+    """QuAM component for a digital output channel (signal going out of the OPX)
+
+    Should be added to `Channel.digital_outputs` so that it's also added to the
+    respective element in the QUA config.
+
+    Args:
+        opx_output (Tuple[str, int]): Channel output port from the OPX perspective,
+            E.g. ("con1", 1)
+        delay (int, optional): Delay in nanoseconds. An intrinsic negative delay of
+            136 ns exists by default.
+        buffer (int, optional): Digital pulses played to this element will be convolved
+            with a digital pulse of value 1 with this length [ns].
+        shareable (bool, optional): If True, the digital output can be shared with other
+            QM instances. Default is False
+        inverted (bool, optional): If True, the digital output is inverted.
+            Default is False.
+    ."""
+
+    opx_output: Union[Tuple[str, int], Tuple[str, int, int], DigitalOutputPort]
+    delay: int = None
+    buffer: int = None
+
+    shareable: bool = None
+    inverted: bool = None
+
+    def generate_element_config(self) -> Dict[str, int]:
+        """Generates the config entry for a digital channel in the QUA config.
+
+        This config entry goes into:
+        config.elements.<element_name>.digitalInputs.<opx_output[1]>
+
+        Returns:
+            Dict[str, int]: The digital channel config entry.
+                Contains "port", and optionally "delay", "buffer" if specified
+        """
+        if isinstance(self.opx_output, DigitalOutputPort):
+            opx_output = self.opx_output.port_tuple
+        else:
+            opx_output = tuple(self.opx_output)
+
+        digital_cfg: Dict[str, Any] = {"port": opx_output}
+        if self.delay is not None:
+            digital_cfg["delay"] = self.delay
+        if self.buffer is not None:
+            digital_cfg["buffer"] = self.buffer
+        return digital_cfg
+
+    def apply_to_config(self, config: dict) -> None:
+        """Adds this DigitalOutputChannel to the QUA configuration.
+
+        config.controllers.<controller_name>.digital_outputs.<port> will be updated
+        with the shareable and inverted settings of this channel if specified.
+
+        See [`QuamComponent.apply_to_config`][quam.core.quam_classes.QuamComponent.apply_to_config]
+        for details.
+        """
+        if isinstance(self.opx_output, DigitalOutputPort):
+            if self.shareable is not None:
+                warnings.warn(
+                    f"Property {self.name}.shareable (={self.shareable}) is ignored "
+                    "because it should be set in {self.name}.opx_output.shareable"
+                )
+            if self.inverted is not None:
+                warnings.warn(
+                    f"Property {self.name}.inverted (={self.inverted}) is ignored "
+                    "because it should be set in {self.name}.opx_output.inverted"
+                )
+            return
+
+        shareable = self.shareable if self.shareable is not None else False
+        inverted = self.inverted if self.inverted is not None else False
+        if len(self.opx_output) == 2:
+            digital_output_port = OPXPlusDigitalOutputPort(
+                *self.opx_output, shareable=shareable, inverted=inverted
+            )
+        else:
+            digital_output_port = FEMDigitalOutputPort(
+                *self.opx_output, shareable=shareable, inverted=inverted
+            )
+        digital_output_port.apply_to_config(config)
+
+
+ + + +
+ + + + + + + + + +
+ + +

+ apply_to_config(config) + +

+ + +
+ +

Adds this DigitalOutputChannel to the QUA configuration.

+

config.controllers..digital_outputs. will be updated +with the shareable and inverted settings of this channel if specified.

+

See QuamComponent.apply_to_config +for details.

+ +
+ Source code in quam/components/channels.py + 
120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
def apply_to_config(self, config: dict) -> None:
+    """Adds this DigitalOutputChannel to the QUA configuration.
+
+    config.controllers.<controller_name>.digital_outputs.<port> will be updated
+    with the shareable and inverted settings of this channel if specified.
+
+    See [`QuamComponent.apply_to_config`][quam.core.quam_classes.QuamComponent.apply_to_config]
+    for details.
+    """
+    if isinstance(self.opx_output, DigitalOutputPort):
+        if self.shareable is not None:
+            warnings.warn(
+                f"Property {self.name}.shareable (={self.shareable}) is ignored "
+                "because it should be set in {self.name}.opx_output.shareable"
+            )
+        if self.inverted is not None:
+            warnings.warn(
+                f"Property {self.name}.inverted (={self.inverted}) is ignored "
+                "because it should be set in {self.name}.opx_output.inverted"
+            )
+        return
+
+    shareable = self.shareable if self.shareable is not None else False
+    inverted = self.inverted if self.inverted is not None else False
+    if len(self.opx_output) == 2:
+        digital_output_port = OPXPlusDigitalOutputPort(
+            *self.opx_output, shareable=shareable, inverted=inverted
+        )
+    else:
+        digital_output_port = FEMDigitalOutputPort(
+            *self.opx_output, shareable=shareable, inverted=inverted
+        )
+    digital_output_port.apply_to_config(config)
+
+
+
+ +
+ +
+ + +

+ generate_element_config() + +

+ + +
+ +

Generates the config entry for a digital channel in the QUA config.

+

This config entry goes into: +config.elements..digitalInputs.

+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ Dict[str, int] + +
+

Dict[str, int]: The digital channel config entry. +Contains "port", and optionally "delay", "buffer" if specified

+
+
+ +
+ Source code in quam/components/channels.py + 
 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
def generate_element_config(self) -> Dict[str, int]:
+    """Generates the config entry for a digital channel in the QUA config.
+
+    This config entry goes into:
+    config.elements.<element_name>.digitalInputs.<opx_output[1]>
+
+    Returns:
+        Dict[str, int]: The digital channel config entry.
+            Contains "port", and optionally "delay", "buffer" if specified
+    """
+    if isinstance(self.opx_output, DigitalOutputPort):
+        opx_output = self.opx_output.port_tuple
+    else:
+        opx_output = tuple(self.opx_output)
+
+    digital_cfg: Dict[str, Any] = {"port": opx_output}
+    if self.delay is not None:
+        digital_cfg["delay"] = self.delay
+    if self.buffer is not None:
+        digital_cfg["buffer"] = self.buffer
+    return digital_cfg
+
+
+
+ +
+ + + +
+ +
+ +
+ +
+ + + +

+ IQChannel + + +

+ + +
+

+ Bases: Channel

+ + +

QuAM component for an IQ output channel.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
operations + Dict[str, Pulse] + +
+

A dictionary of pulses to be played on this +channel. The key is the pulse label (e.g. "X90") and value is a Pulse.

+
+ 		+ required +
id + (str, int) + +
+

The id of the channel, used to generate the name. +Can be a string, or an integer in which case it will add +Channel._default_label.

+
+ 		+ required +
opx_output_I + Tuple[str, int] + +
+

Channel I output port from the OPX perspective, +a tuple of (controller_name, port).

+
+ 		+ required +
opx_output_Q + Tuple[str, int] + +
+

Channel Q output port from the OPX perspective, +a tuple of (controller_name, port).

+
+ 		+ required +
opx_output_offset_I + float + +
+

The offset of the I channel. Default is 0.

+
+ 		+ required +
opx_output_offset_Q + float + +
+

The offset of the Q channel. Default is 0.

+
+ 		+ required +
intermediate_frequency + float + +
+

Intermediate frequency of the mixer. +Default is 0.0

+
+ 		+ required +
LO_frequency + float + +
+

Local oscillator frequency. Default is the LO frequency +of the frequency converter up component.

+
+ 		+ required +
RF_frequency + float + +
+

RF frequency of the mixer. By default, the RF frequency +is inferred by adding the LO frequency and the intermediate frequency.

+
+ 		+ required +
frequency_converter_up + FrequencyConverter + +
+

Frequency converter QuAM component +for the IQ output.

+
+ 		+ required +
+ +
+ Source code in quam/components/channels.py + 
 826
+ 827
+ 828
+ 829
+ 830
+ 831
+ 832
+ 833
+ 834
+ 835
+ 836
+ 837
+ 838
+ 839
+ 840
+ 841
+ 842
+ 843
+ 844
+ 845
+ 846
+ 847
+ 848
+ 849
+ 850
+ 851
+ 852
+ 853
+ 854
+ 855
+ 856
+ 857
+ 858
+ 859
+ 860
+ 861
+ 862
+ 863
+ 864
+ 865
+ 866
+ 867
+ 868
+ 869
+ 870
+ 871
+ 872
+ 873
+ 874
+ 875
+ 876
+ 877
+ 878
+ 879
+ 880
+ 881
+ 882
+ 883
+ 884
+ 885
+ 886
+ 887
+ 888
+ 889
+ 890
+ 891
+ 892
+ 893
+ 894
+ 895
+ 896
+ 897
+ 898
+ 899
+ 900
+ 901
+ 902
+ 903
+ 904
+ 905
+ 906
+ 907
+ 908
+ 909
+ 910
+ 911
+ 912
+ 913
+ 914
+ 915
+ 916
+ 917
+ 918
+ 919
+ 920
+ 921
+ 922
+ 923
+ 924
+ 925
+ 926
+ 927
+ 928
+ 929
+ 930
+ 931
+ 932
+ 933
+ 934
+ 935
+ 936
+ 937
+ 938
+ 939
+ 940
+ 941
+ 942
+ 943
+ 944
+ 945
+ 946
+ 947
+ 948
+ 949
+ 950
+ 951
+ 952
+ 953
+ 954
+ 955
+ 956
+ 957
+ 958
+ 959
+ 960
+ 961
+ 962
+ 963
+ 964
+ 965
+ 966
+ 967
+ 968
+ 969
+ 970
+ 971
+ 972
+ 973
+ 974
+ 975
+ 976
+ 977
+ 978
+ 979
+ 980
+ 981
+ 982
+ 983
+ 984
+ 985
+ 986
+ 987
+ 988
+ 989
+ 990
+ 991
+ 992
+ 993
+ 994
+ 995
+ 996
+ 997
+ 998
+ 999
+1000
+1001
+1002
+1003
+1004
+1005
+1006
+1007
+1008
+1009
+1010
+1011
+1012
+1013
+1014
+1015
+1016
+1017
+1018
+1019
+1020
+1021
+1022
+1023
+1024
+1025
+1026
+1027
+1028
+1029
@quam_dataclass
+class IQChannel(Channel):
+    """QuAM component for an IQ output channel.
+
+    Args:
+        operations (Dict[str, Pulse]): A dictionary of pulses to be played on this
+            channel. The key is the pulse label (e.g. "X90") and value is a Pulse.
+        id (str, int): The id of the channel, used to generate the name.
+            Can be a string, or an integer in which case it will add
+            `Channel._default_label`.
+        opx_output_I (Tuple[str, int]): Channel I output port from the OPX perspective,
+            a tuple of (controller_name, port).
+        opx_output_Q (Tuple[str, int]): Channel Q output port from the OPX perspective,
+            a tuple of (controller_name, port).
+        opx_output_offset_I float: The offset of the I channel. Default is 0.
+        opx_output_offset_Q float: The offset of the Q channel. Default is 0.
+        intermediate_frequency (float): Intermediate frequency of the mixer.
+            Default is 0.0
+        LO_frequency (float): Local oscillator frequency. Default is the LO frequency
+            of the frequency converter up component.
+        RF_frequency (float): RF frequency of the mixer. By default, the RF frequency
+            is inferred by adding the LO frequency and the intermediate frequency.
+        frequency_converter_up (FrequencyConverter): Frequency converter QuAM component
+            for the IQ output.
+    """
+
+    opx_output_I: Union[Tuple[str, int], Tuple[str, int, int], LFAnalogOutputPort]
+    opx_output_Q: Union[Tuple[str, int], Tuple[str, int, int], LFAnalogOutputPort]
+
+    opx_output_offset_I: float = None
+    opx_output_offset_Q: float = None
+
+    frequency_converter_up: BaseFrequencyConverter
+
+    intermediate_frequency: float = 0.0
+    LO_frequency: float = "#./frequency_converter_up/LO_frequency"
+    RF_frequency: float = "#./inferred_RF_frequency"
+
+    _default_label: ClassVar[str] = "IQ"
+
+    @property
+    def inferred_RF_frequency(self) -> float:
+        """Inferred RF frequency by adding LO and IF
+
+        Can be used by having reference `RF_frequency = "#./inferred_RF_frequency"`
+        Returns:
+            self.LO_frequency + self.intermediate_frequency
+        """
+        name = getattr(self, "name", self.__class__.__name__)
+        if not isinstance(self.LO_frequency, (float, int)):
+            raise AttributeError(
+                f"Error inferring RF frequency for channel {name}: "
+                f"LO_frequency is not a number: {self.LO_frequency}"
+            )
+        if not isinstance(self.intermediate_frequency, (float, int)):
+            raise AttributeError(
+                f"Error inferring RF frequency for channel {name}: "
+                f"intermediate_frequency is not a number: {self.intermediate_frequency}"
+            )
+        return self.LO_frequency + self.intermediate_frequency
+
+    @property
+    def inferred_intermediate_frequency(self) -> float:
+        """Inferred intermediate frequency by subtracting LO from RF
+
+        Can be used by having reference
+        `intermediate_frequency = "#./inferred_intermediate_frequency"`
+
+        Returns:
+            self.RF_frequency - self.LO_frequency
+        """
+        name = getattr(self, "name", self.__class__.__name__)
+        if not isinstance(self.LO_frequency, (float, int)):
+            raise AttributeError(
+                f"Error inferring intermediate frequency for channel {name}: "
+                f"LO_frequency is not a number: {self.LO_frequency}"
+            )
+        if not isinstance(self.RF_frequency, (float, int)):
+            raise AttributeError(
+                f"Error inferring intermediate frequency for channel {name}: "
+                f"RF_frequency is not a number: {self.RF_frequency}"
+            )
+        return self.RF_frequency - self.LO_frequency
+
+    @property
+    def inferred_LO_frequency(self) -> float:
+        """Inferred LO frequency by subtracting IF from RF
+
+        Can be used by having reference `LO_frequency = "#./inferred_LO_frequency"`
+
+        Returns:
+            self.RF_frequency - self.intermediate_frequency
+        """
+        name = getattr(self, "name", self.__class__.__name__)
+        if not isinstance(self.RF_frequency, (float, int)):
+            raise AttributeError(
+                f"Error inferring LO frequency for channel {name}: "
+                f"RF_frequency is not a number: {self.RF_frequency}"
+            )
+        if not isinstance(self.intermediate_frequency, (float, int)):
+            raise AttributeError(
+                f"Error inferring LO frequency for channel {name}: "
+                f"intermediate_frequency is not a number: {self.intermediate_frequency}"
+            )
+        return self.RF_frequency - self.intermediate_frequency
+
+    @property
+    def local_oscillator(self) -> Optional[LocalOscillator]:
+        return getattr(self.frequency_converter_up, "local_oscillator", None)
+
+    @property
+    def mixer(self) -> Optional[Mixer]:
+        return getattr(self.frequency_converter_up, "mixer", None)
+
+    @property
+    def rf_frequency(self):
+        warnings.warn(
+            "rf_frequency is deprecated, use RF_frequency instead", DeprecationWarning
+        )
+        return self.frequency_converter_up.LO_frequency + self.intermediate_frequency
+
+    def set_dc_offset(self, offset: QuaNumberType, element_input: Literal["I", "Q"]):
+        """Set the DC offset of an element's input to the given value.
+        This value will remain the DC offset until changed or until the Quantum Machine
+        is closed.
+
+        Args:
+            offset (QuaNumberType): The DC offset to set the input to.
+                This is limited by the OPX output voltage range.
+                The number can be a QUA variable
+            element_input (Literal["I", "Q"]): The element input to set the offset for.
+
+        Raises:
+            ValueError: If element_input is not "I" or "Q"
+        """
+        if element_input not in ["I", "Q"]:
+            raise ValueError(
+                f"element_input should be either 'I' or 'Q', got {element_input}"
+            )
+        set_dc_offset(element=self.name, element_input=element_input, offset=offset)
+
+    def apply_to_config(self, config: dict):
+        """Adds this IQChannel to the QUA configuration.
+
+        See [`QuamComponent.apply_to_config`][quam.core.quam_classes.QuamComponent.apply_to_config]
+        for details.
+        """
+        # Add pulses & waveforms
+        super().apply_to_config(config)
+
+        if str_ref.is_reference(self.name):
+            raise AttributeError(
+                f"Channel {self.get_reference()} cannot be added to the config because"
+                " it doesn't have a name. Either set channel.id to a string or"
+                " integer, or channel should be an attribute of another QuAM component"
+                " with a name."
+            )
+
+        element_cfg = config["elements"][self.name]
+        element_cfg["intermediate_frequency"] = self.intermediate_frequency
+
+        from quam.components.octave import OctaveUpConverter
+
+        if isinstance(self.frequency_converter_up, OctaveUpConverter):
+            octave = self.frequency_converter_up.octave
+            if octave is None:
+                raise ValueError(
+                    f"Error generating config: channel {self.name} has an "
+                    f"OctaveUpConverter (id={self.frequency_converter_up.id}) without "
+                    "an attached Octave"
+                )
+            element_cfg["RF_inputs"] = {
+                "port": (octave.name, self.frequency_converter_up.id)
+            }
+        elif str_ref.is_reference(self.frequency_converter_up):
+            raise ValueError(
+                f"Error generating config: channel {self.name} could not determine "
+                f'"frequency_converter_up", it seems to point to a non-existent '
+                f"reference: {self.frequency_converter_up}"
+            )
+        else:
+
+            element_cfg["mixInputs"] = {}  # To be filled in next section
+            if self.mixer is not None:
+                element_cfg["mixInputs"]["mixer"] = self.mixer.name
+            if self.local_oscillator is not None:
+                element_cfg["mixInputs"][
+                    "lo_frequency"
+                ] = self.local_oscillator.frequency
+
+        opx_outputs = [self.opx_output_I, self.opx_output_Q]
+        offsets = [self.opx_output_offset_I, self.opx_output_offset_Q]
+        for I_or_Q, opx_output, offset in zip("IQ", opx_outputs, offsets):
+            if isinstance(opx_output, LFAnalogOutputPort):
+                opx_port = opx_output
+            elif len(opx_output) == 2:
+                opx_port = OPXPlusAnalogOutputPort(*opx_output, offset=offset)
+                opx_port.apply_to_config(config)
+            else:
+                opx_port = LFFEMAnalogOutputPort(*opx_output, offset=offset)
+                opx_port.apply_to_config(config)
+
+            if "mixInputs" in element_cfg:
+                element_cfg["mixInputs"][I_or_Q] = opx_port.port_tuple
+
+
+ + + +
+ + + + + + + +
+ + + +

+ inferred_LO_frequency: float + + + property + + +

+ + +
+ +

Inferred LO frequency by subtracting IF from RF

+

Can be used by having reference LO_frequency = "#./inferred_LO_frequency"

+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ float + +
+

self.RF_frequency - self.intermediate_frequency

+
+
+
+ +
+ +
+ + + +

+ inferred_RF_frequency: float + + + property + + +

+ + +
+ +

Inferred RF frequency by adding LO and IF

+

Can be used by having reference RF_frequency = "#./inferred_RF_frequency" +Returns: + self.LO_frequency + self.intermediate_frequency

+
+ +
+ +
+ + + +

+ inferred_intermediate_frequency: float + + + property + + +

+ + +
+ +

Inferred intermediate frequency by subtracting LO from RF

+

Can be used by having reference +intermediate_frequency = "#./inferred_intermediate_frequency"

+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ float + +
+

self.RF_frequency - self.LO_frequency

+
+
+
+ +
+ + + +
+ + +

+ apply_to_config(config) + +

+ + +
+ +

Adds this IQChannel to the QUA configuration.

+

See QuamComponent.apply_to_config +for details.

+ +
+ Source code in quam/components/channels.py + 
 967
+ 968
+ 969
+ 970
+ 971
+ 972
+ 973
+ 974
+ 975
+ 976
+ 977
+ 978
+ 979
+ 980
+ 981
+ 982
+ 983
+ 984
+ 985
+ 986
+ 987
+ 988
+ 989
+ 990
+ 991
+ 992
+ 993
+ 994
+ 995
+ 996
+ 997
+ 998
+ 999
+1000
+1001
+1002
+1003
+1004
+1005
+1006
+1007
+1008
+1009
+1010
+1011
+1012
+1013
+1014
+1015
+1016
+1017
+1018
+1019
+1020
+1021
+1022
+1023
+1024
+1025
+1026
+1027
+1028
+1029
def apply_to_config(self, config: dict):
+    """Adds this IQChannel to the QUA configuration.
+
+    See [`QuamComponent.apply_to_config`][quam.core.quam_classes.QuamComponent.apply_to_config]
+    for details.
+    """
+    # Add pulses & waveforms
+    super().apply_to_config(config)
+
+    if str_ref.is_reference(self.name):
+        raise AttributeError(
+            f"Channel {self.get_reference()} cannot be added to the config because"
+            " it doesn't have a name. Either set channel.id to a string or"
+            " integer, or channel should be an attribute of another QuAM component"
+            " with a name."
+        )
+
+    element_cfg = config["elements"][self.name]
+    element_cfg["intermediate_frequency"] = self.intermediate_frequency
+
+    from quam.components.octave import OctaveUpConverter
+
+    if isinstance(self.frequency_converter_up, OctaveUpConverter):
+        octave = self.frequency_converter_up.octave
+        if octave is None:
+            raise ValueError(
+                f"Error generating config: channel {self.name} has an "
+                f"OctaveUpConverter (id={self.frequency_converter_up.id}) without "
+                "an attached Octave"
+            )
+        element_cfg["RF_inputs"] = {
+            "port": (octave.name, self.frequency_converter_up.id)
+        }
+    elif str_ref.is_reference(self.frequency_converter_up):
+        raise ValueError(
+            f"Error generating config: channel {self.name} could not determine "
+            f'"frequency_converter_up", it seems to point to a non-existent '
+            f"reference: {self.frequency_converter_up}"
+        )
+    else:
+
+        element_cfg["mixInputs"] = {}  # To be filled in next section
+        if self.mixer is not None:
+            element_cfg["mixInputs"]["mixer"] = self.mixer.name
+        if self.local_oscillator is not None:
+            element_cfg["mixInputs"][
+                "lo_frequency"
+            ] = self.local_oscillator.frequency
+
+    opx_outputs = [self.opx_output_I, self.opx_output_Q]
+    offsets = [self.opx_output_offset_I, self.opx_output_offset_Q]
+    for I_or_Q, opx_output, offset in zip("IQ", opx_outputs, offsets):
+        if isinstance(opx_output, LFAnalogOutputPort):
+            opx_port = opx_output
+        elif len(opx_output) == 2:
+            opx_port = OPXPlusAnalogOutputPort(*opx_output, offset=offset)
+            opx_port.apply_to_config(config)
+        else:
+            opx_port = LFFEMAnalogOutputPort(*opx_output, offset=offset)
+            opx_port.apply_to_config(config)
+
+        if "mixInputs" in element_cfg:
+            element_cfg["mixInputs"][I_or_Q] = opx_port.port_tuple
+
+
+
+ +
+ +
+ + +

+ set_dc_offset(offset, element_input) + +

+ + +
+ +

Set the DC offset of an element's input to the given value. +This value will remain the DC offset until changed or until the Quantum Machine +is closed.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
offset + QuaNumberType + +
+

The DC offset to set the input to. +This is limited by the OPX output voltage range. +The number can be a QUA variable

+
+ 		+ required +
element_input + Literal['I', 'Q'] + +
+

The element input to set the offset for.

+
+ 		+ required +
+ + +

Raises:

+ + + + + + + + + + + + + +
TypeDescription
+ ValueError + +
+

If element_input is not "I" or "Q"

+
+
+ +
+ Source code in quam/components/channels.py + 
947
+948
+949
+950
+951
+952
+953
+954
+955
+956
+957
+958
+959
+960
+961
+962
+963
+964
+965
def set_dc_offset(self, offset: QuaNumberType, element_input: Literal["I", "Q"]):
+    """Set the DC offset of an element's input to the given value.
+    This value will remain the DC offset until changed or until the Quantum Machine
+    is closed.
+
+    Args:
+        offset (QuaNumberType): The DC offset to set the input to.
+            This is limited by the OPX output voltage range.
+            The number can be a QUA variable
+        element_input (Literal["I", "Q"]): The element input to set the offset for.
+
+    Raises:
+        ValueError: If element_input is not "I" or "Q"
+    """
+    if element_input not in ["I", "Q"]:
+        raise ValueError(
+            f"element_input should be either 'I' or 'Q', got {element_input}"
+        )
+    set_dc_offset(element=self.name, element_input=element_input, offset=offset)
+
+
+
+ +
+ + + +
+ +
+ +
+ +
+ + + +

+ InIQChannel + + +

+ + +
+

+ Bases: Channel

+ + +

QuAM component for an IQ input channel

+

operations (Dict[str, Pulse]): A dictionary of pulses to be played on this + channel. The key is the pulse label (e.g. "readout") and value is a + ReadoutPulse. +id (str, int): The id of the channel, used to generate the name. + Can be a string, or an integer in which case it will add + Channel._default_label. +opx_input_I (Tuple[str, int]): Channel I input port from the OPX perspective, + a tuple of (controller_name, port). +opx_input_Q (Tuple[str, int]): Channel Q input port from the OPX perspective, + a tuple of (controller_name, port). +opx_input_offset_I float: The offset of the I channel. Default is 0. +opx_input_offset_Q float: The offset of the Q channel. Default is 0. +frequency_converter_down (Optional[FrequencyConverter]): Frequency converter + QuAM component for the IQ input port. Only needed for the old Octave. +time_of_flight (int): Round-trip signal duration in nanoseconds. +smearing (int): Additional window of ADC integration in nanoseconds. + Used to account for signal smearing. +input_gain (float): The gain of the input channel. Default is None.

+ +
+ Source code in quam/components/channels.py + 
1032
+1033
+1034
+1035
+1036
+1037
+1038
+1039
+1040
+1041
+1042
+1043
+1044
+1045
+1046
+1047
+1048
+1049
+1050
+1051
+1052
+1053
+1054
+1055
+1056
+1057
+1058
+1059
+1060
+1061
+1062
+1063
+1064
+1065
+1066
+1067
+1068
+1069
+1070
+1071
+1072
+1073
+1074
+1075
+1076
+1077
+1078
+1079
+1080
+1081
+1082
+1083
+1084
+1085
+1086
+1087
+1088
+1089
+1090
+1091
+1092
+1093
+1094
+1095
+1096
+1097
+1098
+1099
+1100
+1101
+1102
+1103
+1104
+1105
+1106
+1107
+1108
+1109
+1110
+1111
+1112
+1113
+1114
+1115
+1116
+1117
+1118
+1119
+1120
+1121
+1122
+1123
+1124
+1125
+1126
+1127
+1128
+1129
+1130
+1131
+1132
+1133
+1134
+1135
+1136
+1137
+1138
+1139
+1140
+1141
+1142
+1143
+1144
+1145
+1146
+1147
+1148
+1149
+1150
+1151
+1152
+1153
+1154
+1155
+1156
+1157
+1158
+1159
+1160
+1161
+1162
+1163
+1164
+1165
+1166
+1167
+1168
+1169
+1170
+1171
+1172
+1173
+1174
+1175
+1176
+1177
+1178
+1179
+1180
+1181
+1182
+1183
+1184
+1185
+1186
+1187
+1188
+1189
+1190
+1191
+1192
+1193
+1194
+1195
+1196
+1197
+1198
+1199
+1200
+1201
+1202
+1203
+1204
+1205
+1206
+1207
+1208
+1209
+1210
+1211
+1212
+1213
+1214
+1215
+1216
+1217
+1218
+1219
+1220
+1221
+1222
+1223
+1224
+1225
+1226
+1227
+1228
+1229
+1230
+1231
+1232
+1233
+1234
+1235
+1236
+1237
+1238
+1239
+1240
+1241
+1242
+1243
+1244
+1245
+1246
+1247
+1248
+1249
+1250
+1251
+1252
+1253
+1254
+1255
+1256
+1257
+1258
+1259
+1260
+1261
+1262
+1263
+1264
+1265
+1266
+1267
+1268
+1269
+1270
+1271
+1272
+1273
+1274
+1275
+1276
+1277
+1278
+1279
+1280
+1281
+1282
+1283
+1284
+1285
+1286
+1287
+1288
+1289
+1290
+1291
+1292
+1293
+1294
+1295
+1296
+1297
+1298
+1299
+1300
+1301
+1302
+1303
+1304
+1305
+1306
+1307
+1308
+1309
+1310
+1311
+1312
+1313
+1314
+1315
+1316
+1317
+1318
+1319
+1320
+1321
+1322
+1323
+1324
+1325
+1326
+1327
+1328
+1329
+1330
+1331
+1332
+1333
+1334
+1335
+1336
+1337
+1338
+1339
+1340
+1341
+1342
+1343
+1344
+1345
+1346
+1347
+1348
+1349
+1350
+1351
+1352
+1353
+1354
+1355
+1356
+1357
+1358
+1359
@quam_dataclass
+class InIQChannel(Channel):
+    """QuAM component for an IQ input channel
+
+    operations (Dict[str, Pulse]): A dictionary of pulses to be played on this
+        channel. The key is the pulse label (e.g. "readout") and value is a
+        ReadoutPulse.
+    id (str, int): The id of the channel, used to generate the name.
+        Can be a string, or an integer in which case it will add
+        `Channel._default_label`.
+    opx_input_I (Tuple[str, int]): Channel I input port from the OPX perspective,
+        a tuple of (controller_name, port).
+    opx_input_Q (Tuple[str, int]): Channel Q input port from the OPX perspective,
+        a tuple of (controller_name, port).
+    opx_input_offset_I float: The offset of the I channel. Default is 0.
+    opx_input_offset_Q float: The offset of the Q channel. Default is 0.
+    frequency_converter_down (Optional[FrequencyConverter]): Frequency converter
+        QuAM component for the IQ input port. Only needed for the old Octave.
+    time_of_flight (int): Round-trip signal duration in nanoseconds.
+    smearing (int): Additional window of ADC integration in nanoseconds.
+        Used to account for signal smearing.
+    input_gain (float): The gain of the input channel. Default is None.
+    """
+
+    opx_input_I: Union[Tuple[str, int], Tuple[str, int, int], LFAnalogInputPort]
+    opx_input_Q: Union[Tuple[str, int], Tuple[str, int, int], LFAnalogInputPort]
+
+    time_of_flight: int = 24
+    smearing: int = 0
+
+    opx_input_offset_I: float = None
+    opx_input_offset_Q: float = None
+
+    input_gain: Optional[int] = None
+
+    frequency_converter_down: BaseFrequencyConverter = None
+
+    _default_label: ClassVar[str] = "IQ"
+
+    def apply_to_config(self, config: dict):
+        """Adds this InOutIQChannel to the QUA configuration.
+
+        See [`QuamComponent.apply_to_config`][quam.core.quam_classes.QuamComponent.apply_to_config]
+        for details.
+        """
+        super().apply_to_config(config)
+
+        # Note outputs instead of inputs because it's w.r.t. the QPU
+        element_cfg = config["elements"][self.name]
+        element_cfg["smearing"] = self.smearing
+        element_cfg["time_of_flight"] = self.time_of_flight
+
+        from quam.components.octave import OctaveDownConverter
+
+        if isinstance(self.frequency_converter_down, OctaveDownConverter):
+            octave = self.frequency_converter_down.octave
+            if octave is None:
+                raise ValueError(
+                    f"Error generating config: channel {self.name} has an "
+                    f"OctaveDownConverter (id={self.frequency_converter_down.id}) "
+                    "without an attached Octave"
+                )
+            element_cfg["RF_outputs"] = {
+                "port": (octave.name, self.frequency_converter_down.id)
+            }
+        elif str_ref.is_reference(self.frequency_converter_down):
+            raise ValueError(
+                f"Error generating config: channel {self.name} could not determine "
+                f'"frequency_converter_down", it seems to point to a non-existent '
+                f"reference: {self.frequency_converter_down}"
+            )
+        else:
+            # To be filled in next section
+            element_cfg["outputs"] = {}
+
+        opx_inputs = [self.opx_input_I, self.opx_input_Q]
+        offsets = [self.opx_input_offset_I, self.opx_input_offset_Q]
+        input_gain = int(self.input_gain if self.input_gain is not None else 0)
+        for k, (opx_input, offset) in enumerate(zip(opx_inputs, offsets), start=1):
+            if isinstance(opx_input, LFAnalogInputPort):
+                opx_port = opx_input
+            elif len(opx_input) == 2:
+                opx_port = OPXPlusAnalogInputPort(
+                    *opx_input, offset=offset, gain_db=input_gain
+                )
+                opx_port.apply_to_config(config)
+            else:
+                opx_port = LFFEMAnalogInputPort(
+                    *opx_input, offset=offset, gain_db=input_gain
+                )
+                opx_port.apply_to_config(config)
+            if not isinstance(self.frequency_converter_down, OctaveDownConverter):
+                element_cfg["outputs"][f"out{k}"] = opx_port.port_tuple
+
+    def measure(
+        self,
+        pulse_name: str,
+        amplitude_scale: Union[float, AmpValuesType] = None,
+        qua_vars: Tuple[QuaVariableType, QuaVariableType] = None,
+        stream=None,
+    ) -> Tuple[QuaVariableType, QuaVariableType]:
+        """Perform a full dual demodulation measurement on this channel.
+
+        Args:
+            pulse_name (str): The name of the pulse to play. Should be registered in
+                `self.operations`.
+            amplitude_scale (float, _PulseAmp): Amplitude scale of the pulse.
+                Can be either a float, or qua.amp(float).
+            qua_vars (Tuple[QuaVariableType, QuaVariableType], optional): Two QUA
+                variables to store the I and Q measurement results. If not provided,
+                new variables will be declared and returned.
+            stream (Optional[StreamType]): The stream to save the measurement result to.
+                If not provided, the raw ADC signal will not be streamed.
+
+        Returns:
+            I, Q: The QUA variables used to store the measurement results.
+                If provided as input, the same variables will be returned.
+                If not provided, new variables will be declared and returned.
+        """
+        pulse: BaseReadoutPulse = self.operations[pulse_name]
+
+        if qua_vars is not None:
+            if not isinstance(qua_vars, Sequence) or len(qua_vars) != 2:
+                raise ValueError(
+                    f"InOutIQChannel.measure received kwarg 'qua_vars' which is not a "
+                    f"tuple of two QUA variables. Received {qua_vars=}"
+                )
+        else:
+            qua_vars = [declare(fixed) for _ in range(2)]
+
+        if amplitude_scale is not None:
+            if not isinstance(amplitude_scale, _PulseAmp):
+                amplitude_scale = amp(amplitude_scale)
+            pulse_name *= amplitude_scale
+
+        integration_weight_labels = list(pulse.integration_weights_mapping)
+        measure(
+            pulse_name,
+            self.name,
+            stream,
+            dual_demod.full(
+                iw1=integration_weight_labels[0],
+                element_output1="out1",
+                iw2=integration_weight_labels[1],
+                element_output2="out2",
+                target=qua_vars[0],
+            ),
+            dual_demod.full(
+                iw1=integration_weight_labels[2],
+                element_output1="out1",
+                iw2=integration_weight_labels[0],
+                element_output2="out2",
+                target=qua_vars[1],
+            ),
+        )
+        return tuple(qua_vars)
+
+    def measure_accumulated(
+        self,
+        pulse_name: str,
+        amplitude_scale: Union[float, AmpValuesType] = None,
+        num_segments: int = None,
+        segment_length: int = None,
+        qua_vars: Tuple[QuaVariableType, ...] = None,
+        stream=None,
+    ) -> Tuple[QuaVariableType, QuaVariableType, QuaVariableType, QuaVariableType]:
+        """Perform an accumulated dual demodulation measurement on this channel.
+
+        Instead of two QUA variables (I and Q), this method returns four variables
+        (II, IQ, QI, QQ)
+
+        Args:
+            pulse_name (str): The name of the pulse to play. Should be registered in
+                `self.operations`.
+            amplitude_scale (float, _PulseAmp): Amplitude scale of the pulse.
+                Can be either a float, or qua.amp(float).
+            num_segments (int): The number of segments to accumulate.
+                Should either specify this or `segment_length`.
+            segment_length (int): The length of the segment to accumulate the
+                measurement.
+                Should either specify this or `num_segments`.
+            qua_vars (Tuple[QuaVariableType, ...], optional): Four QUA
+                variables to store the II, IQ, QI, QQ measurement results.
+                If not provided, new variables will be declared and returned.
+            stream (Optional[StreamType]): The stream to save the measurement result to.
+                If not provided, the raw ADC signal will not be streamed.
+
+        Returns:
+            II, IQ, QI, QQ: The QUA variables used to store the measurement results.
+                If provided as input, the same variables will be returned.
+                If not provided, new variables will be declared and returned.
+        """
+        pulse: BaseReadoutPulse = self.operations[pulse_name]
+
+        if num_segments is None and segment_length is None:
+            raise ValueError(
+                "InOutSingleChannel.measure_accumulated requires either 'segment_length' "
+                "or 'num_segments' to be provided."
+            )
+        elif num_segments is not None and segment_length is not None:
+            raise ValueError(
+                "InOutSingleChannel.measure_accumulated received both 'segment_length' "
+                "and 'num_segments'. Please provide only one."
+            )
+        elif num_segments is None:
+            num_segments = int(pulse.length / (4 * segment_length))  # Number of slices
+        elif segment_length is None:
+            segment_length = int(pulse.length / (4 * num_segments))
+
+        if qua_vars is not None:
+            if not isinstance(qua_vars, Sequence) or len(qua_vars) != 4:
+                raise ValueError(
+                    f"InOutSingleChannel.measure_accumulated received kwarg 'qua_vars' "
+                    f"which is not a tuple of four QUA variables. Received {qua_vars=}"
+                )
+        else:
+            qua_vars = [declare(fixed, size=num_segments) for _ in range(4)]
+
+        if amplitude_scale is not None:
+            if not isinstance(amplitude_scale, _PulseAmp):
+                amplitude_scale = amp(amplitude_scale)
+            pulse_name *= amplitude_scale
+
+        integration_weight_labels = list(pulse.integration_weights_mapping)
+        measure(
+            pulse_name,
+            self.name,
+            stream,
+            demod.accumulated(
+                integration_weight_labels[0], qua_vars[0], segment_length, "out1"
+            ),
+            demod.accumulated(
+                integration_weight_labels[1], qua_vars[1], segment_length, "out2"
+            ),
+            demod.accumulated(
+                integration_weight_labels[2], qua_vars[2], segment_length, "out1"
+            ),
+            demod.accumulated(
+                integration_weight_labels[0], qua_vars[3], segment_length, "out2"
+            ),
+        )
+        return tuple(qua_vars)
+
+    def measure_sliced(
+        self,
+        pulse_name: str,
+        amplitude_scale: Union[float, AmpValuesType] = None,
+        num_segments: int = None,
+        segment_length: int = None,
+        qua_vars: Tuple[QuaVariableType, ...] = None,
+        stream=None,
+    ) -> Tuple[QuaVariableType, QuaVariableType, QuaVariableType, QuaVariableType]:
+        """Perform a sliced dual demodulation measurement on this channel.
+
+        Instead of two QUA variables (I and Q), this method returns four variables
+        (II, IQ, QI, QQ)
+
+        Args:
+            pulse_name (str): The name of the pulse to play. Should be registered in
+                `self.operations`.
+            amplitude_scale (float, _PulseAmp): Amplitude scale of the pulse.
+                Can be either a float, or qua.amp(float).
+            num_segments (int): The number of segments to accumulate.
+                Should either specify this or `segment_length`.
+            segment_length (int): The length of the segment to accumulate the
+                measurement.
+                Should either specify this or `num_segments`.
+            qua_vars (Tuple[QuaVariableType, ...], optional): Four QUA
+                variables to store the II, IQ, QI, QQ measurement results.
+                If not provided, new variables will be declared and returned.
+            stream (Optional[StreamType]): The stream to save the measurement result to.
+                If not provided, the raw ADC signal will not be streamed.
+
+        Returns:
+            II, IQ, QI, QQ: The QUA variables used to store the measurement results.
+                If provided as input, the same variables will be returned.
+                If not provided, new variables will be declared and returned.
+        """
+        pulse: BaseReadoutPulse = self.operations[pulse_name]
+
+        if num_segments is None and segment_length is None:
+            raise ValueError(
+                "InOutSingleChannel.measure_sliced requires either 'segment_length' "
+                "or 'num_segments' to be provided."
+            )
+        elif num_segments is not None and segment_length is not None:
+            raise ValueError(
+                "InOutSingleChannel.measure_sliced received both 'segment_length' "
+                "and 'num_segments'. Please provide only one."
+            )
+        elif num_segments is None:
+            num_segments = int(pulse.length / (4 * segment_length))  # Number of slices
+        elif segment_length is None:
+            segment_length = int(pulse.length / (4 * num_segments))
+
+        if qua_vars is not None:
+            if not isinstance(qua_vars, Sequence) or len(qua_vars) != 4:
+                raise ValueError(
+                    f"InOutSingleChannel.measure_sliced received kwarg 'qua_vars' "
+                    f"which is not a tuple of four QUA variables. Received {qua_vars=}"
+                )
+        else:
+            qua_vars = [declare(fixed, size=num_segments) for _ in range(4)]
+
+        if amplitude_scale is not None:
+            if not isinstance(amplitude_scale, _PulseAmp):
+                amplitude_scale = amp(amplitude_scale)
+            pulse_name *= amplitude_scale
+
+        integration_weight_labels = list(pulse.integration_weights_mapping)
+        measure(
+            pulse_name,
+            self.name,
+            stream,
+            demod.sliced(
+                integration_weight_labels[0], qua_vars[0], segment_length, "out1"
+            ),
+            demod.sliced(
+                integration_weight_labels[1], qua_vars[1], segment_length, "out2"
+            ),
+            demod.sliced(
+                integration_weight_labels[2], qua_vars[2], segment_length, "out1"
+            ),
+            demod.sliced(
+                integration_weight_labels[0], qua_vars[3], segment_length, "out2"
+            ),
+        )
+        return tuple(qua_vars)
+
+
+ + + +
+ + + + + + + + + +
+ + +

+ apply_to_config(config) + +

+ + +
+ +

Adds this InOutIQChannel to the QUA configuration.

+

See QuamComponent.apply_to_config +for details.

+ +
+ Source code in quam/components/channels.py + 
1071
+1072
+1073
+1074
+1075
+1076
+1077
+1078
+1079
+1080
+1081
+1082
+1083
+1084
+1085
+1086
+1087
+1088
+1089
+1090
+1091
+1092
+1093
+1094
+1095
+1096
+1097
+1098
+1099
+1100
+1101
+1102
+1103
+1104
+1105
+1106
+1107
+1108
+1109
+1110
+1111
+1112
+1113
+1114
+1115
+1116
+1117
+1118
+1119
+1120
+1121
+1122
+1123
+1124
def apply_to_config(self, config: dict):
+    """Adds this InOutIQChannel to the QUA configuration.
+
+    See [`QuamComponent.apply_to_config`][quam.core.quam_classes.QuamComponent.apply_to_config]
+    for details.
+    """
+    super().apply_to_config(config)
+
+    # Note outputs instead of inputs because it's w.r.t. the QPU
+    element_cfg = config["elements"][self.name]
+    element_cfg["smearing"] = self.smearing
+    element_cfg["time_of_flight"] = self.time_of_flight
+
+    from quam.components.octave import OctaveDownConverter
+
+    if isinstance(self.frequency_converter_down, OctaveDownConverter):
+        octave = self.frequency_converter_down.octave
+        if octave is None:
+            raise ValueError(
+                f"Error generating config: channel {self.name} has an "
+                f"OctaveDownConverter (id={self.frequency_converter_down.id}) "
+                "without an attached Octave"
+            )
+        element_cfg["RF_outputs"] = {
+            "port": (octave.name, self.frequency_converter_down.id)
+        }
+    elif str_ref.is_reference(self.frequency_converter_down):
+        raise ValueError(
+            f"Error generating config: channel {self.name} could not determine "
+            f'"frequency_converter_down", it seems to point to a non-existent '
+            f"reference: {self.frequency_converter_down}"
+        )
+    else:
+        # To be filled in next section
+        element_cfg["outputs"] = {}
+
+    opx_inputs = [self.opx_input_I, self.opx_input_Q]
+    offsets = [self.opx_input_offset_I, self.opx_input_offset_Q]
+    input_gain = int(self.input_gain if self.input_gain is not None else 0)
+    for k, (opx_input, offset) in enumerate(zip(opx_inputs, offsets), start=1):
+        if isinstance(opx_input, LFAnalogInputPort):
+            opx_port = opx_input
+        elif len(opx_input) == 2:
+            opx_port = OPXPlusAnalogInputPort(
+                *opx_input, offset=offset, gain_db=input_gain
+            )
+            opx_port.apply_to_config(config)
+        else:
+            opx_port = LFFEMAnalogInputPort(
+                *opx_input, offset=offset, gain_db=input_gain
+            )
+            opx_port.apply_to_config(config)
+        if not isinstance(self.frequency_converter_down, OctaveDownConverter):
+            element_cfg["outputs"][f"out{k}"] = opx_port.port_tuple
+
+
+
+ +
+ +
+ + +

+ measure(pulse_name, amplitude_scale=None, qua_vars=None, stream=None) + +

+ + +
+ +

Perform a full dual demodulation measurement on this channel.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
pulse_name + str + +
+

The name of the pulse to play. Should be registered in +self.operations.

+
+ 		+ required +
amplitude_scale + (float, _PulseAmp) + +
+

Amplitude scale of the pulse. +Can be either a float, or qua.amp(float).

+
+ 		+ None +
qua_vars + Tuple[QuaVariableType, QuaVariableType] + +
+

Two QUA +variables to store the I and Q measurement results. If not provided, +new variables will be declared and returned.

+
+ 		+ None +
stream + Optional[StreamType] + +
+

The stream to save the measurement result to. +If not provided, the raw ADC signal will not be streamed.

+
+ 		+ None +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ Tuple[QuaVariableType, QuaVariableType] + +
+

I, Q: The QUA variables used to store the measurement results. +If provided as input, the same variables will be returned. +If not provided, new variables will be declared and returned.

+
+
+ +
+ Source code in quam/components/channels.py + 
1126
+1127
+1128
+1129
+1130
+1131
+1132
+1133
+1134
+1135
+1136
+1137
+1138
+1139
+1140
+1141
+1142
+1143
+1144
+1145
+1146
+1147
+1148
+1149
+1150
+1151
+1152
+1153
+1154
+1155
+1156
+1157
+1158
+1159
+1160
+1161
+1162
+1163
+1164
+1165
+1166
+1167
+1168
+1169
+1170
+1171
+1172
+1173
+1174
+1175
+1176
+1177
+1178
+1179
+1180
+1181
+1182
+1183
+1184
+1185
+1186
+1187
def measure(
+    self,
+    pulse_name: str,
+    amplitude_scale: Union[float, AmpValuesType] = None,
+    qua_vars: Tuple[QuaVariableType, QuaVariableType] = None,
+    stream=None,
+) -> Tuple[QuaVariableType, QuaVariableType]:
+    """Perform a full dual demodulation measurement on this channel.
+
+    Args:
+        pulse_name (str): The name of the pulse to play. Should be registered in
+            `self.operations`.
+        amplitude_scale (float, _PulseAmp): Amplitude scale of the pulse.
+            Can be either a float, or qua.amp(float).
+        qua_vars (Tuple[QuaVariableType, QuaVariableType], optional): Two QUA
+            variables to store the I and Q measurement results. If not provided,
+            new variables will be declared and returned.
+        stream (Optional[StreamType]): The stream to save the measurement result to.
+            If not provided, the raw ADC signal will not be streamed.
+
+    Returns:
+        I, Q: The QUA variables used to store the measurement results.
+            If provided as input, the same variables will be returned.
+            If not provided, new variables will be declared and returned.
+    """
+    pulse: BaseReadoutPulse = self.operations[pulse_name]
+
+    if qua_vars is not None:
+        if not isinstance(qua_vars, Sequence) or len(qua_vars) != 2:
+            raise ValueError(
+                f"InOutIQChannel.measure received kwarg 'qua_vars' which is not a "
+                f"tuple of two QUA variables. Received {qua_vars=}"
+            )
+    else:
+        qua_vars = [declare(fixed) for _ in range(2)]
+
+    if amplitude_scale is not None:
+        if not isinstance(amplitude_scale, _PulseAmp):
+            amplitude_scale = amp(amplitude_scale)
+        pulse_name *= amplitude_scale
+
+    integration_weight_labels = list(pulse.integration_weights_mapping)
+    measure(
+        pulse_name,
+        self.name,
+        stream,
+        dual_demod.full(
+            iw1=integration_weight_labels[0],
+            element_output1="out1",
+            iw2=integration_weight_labels[1],
+            element_output2="out2",
+            target=qua_vars[0],
+        ),
+        dual_demod.full(
+            iw1=integration_weight_labels[2],
+            element_output1="out1",
+            iw2=integration_weight_labels[0],
+            element_output2="out2",
+            target=qua_vars[1],
+        ),
+    )
+    return tuple(qua_vars)
+
+
+
+ +
+ +
+ + +

+ measure_accumulated(pulse_name, amplitude_scale=None, num_segments=None, segment_length=None, qua_vars=None, stream=None) + +

+ + +
+ +

Perform an accumulated dual demodulation measurement on this channel.

+

Instead of two QUA variables (I and Q), this method returns four variables +(II, IQ, QI, QQ)

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
pulse_name + str + +
+

The name of the pulse to play. Should be registered in +self.operations.

+
+ 		+ required +
amplitude_scale + (float, _PulseAmp) + +
+

Amplitude scale of the pulse. +Can be either a float, or qua.amp(float).

+
+ 		+ None +
num_segments + int + +
+

The number of segments to accumulate. +Should either specify this or segment_length.

+
+ 		+ None +
segment_length + int + +
+

The length of the segment to accumulate the +measurement. +Should either specify this or num_segments.

+
+ 		+ None +
qua_vars + Tuple[QuaVariableType, ...] + +
+

Four QUA +variables to store the II, IQ, QI, QQ measurement results. +If not provided, new variables will be declared and returned.

+
+ 		+ None +
stream + Optional[StreamType] + +
+

The stream to save the measurement result to. +If not provided, the raw ADC signal will not be streamed.

+
+ 		+ None +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ Tuple[QuaVariableType, QuaVariableType, QuaVariableType, QuaVariableType] + +
+

II, IQ, QI, QQ: The QUA variables used to store the measurement results. +If provided as input, the same variables will be returned. +If not provided, new variables will be declared and returned.

+
+
+ +
+ Source code in quam/components/channels.py + 
1189
+1190
+1191
+1192
+1193
+1194
+1195
+1196
+1197
+1198
+1199
+1200
+1201
+1202
+1203
+1204
+1205
+1206
+1207
+1208
+1209
+1210
+1211
+1212
+1213
+1214
+1215
+1216
+1217
+1218
+1219
+1220
+1221
+1222
+1223
+1224
+1225
+1226
+1227
+1228
+1229
+1230
+1231
+1232
+1233
+1234
+1235
+1236
+1237
+1238
+1239
+1240
+1241
+1242
+1243
+1244
+1245
+1246
+1247
+1248
+1249
+1250
+1251
+1252
+1253
+1254
+1255
+1256
+1257
+1258
+1259
+1260
+1261
+1262
+1263
+1264
+1265
+1266
+1267
+1268
+1269
+1270
+1271
+1272
+1273
def measure_accumulated(
+    self,
+    pulse_name: str,
+    amplitude_scale: Union[float, AmpValuesType] = None,
+    num_segments: int = None,
+    segment_length: int = None,
+    qua_vars: Tuple[QuaVariableType, ...] = None,
+    stream=None,
+) -> Tuple[QuaVariableType, QuaVariableType, QuaVariableType, QuaVariableType]:
+    """Perform an accumulated dual demodulation measurement on this channel.
+
+    Instead of two QUA variables (I and Q), this method returns four variables
+    (II, IQ, QI, QQ)
+
+    Args:
+        pulse_name (str): The name of the pulse to play. Should be registered in
+            `self.operations`.
+        amplitude_scale (float, _PulseAmp): Amplitude scale of the pulse.
+            Can be either a float, or qua.amp(float).
+        num_segments (int): The number of segments to accumulate.
+            Should either specify this or `segment_length`.
+        segment_length (int): The length of the segment to accumulate the
+            measurement.
+            Should either specify this or `num_segments`.
+        qua_vars (Tuple[QuaVariableType, ...], optional): Four QUA
+            variables to store the II, IQ, QI, QQ measurement results.
+            If not provided, new variables will be declared and returned.
+        stream (Optional[StreamType]): The stream to save the measurement result to.
+            If not provided, the raw ADC signal will not be streamed.
+
+    Returns:
+        II, IQ, QI, QQ: The QUA variables used to store the measurement results.
+            If provided as input, the same variables will be returned.
+            If not provided, new variables will be declared and returned.
+    """
+    pulse: BaseReadoutPulse = self.operations[pulse_name]
+
+    if num_segments is None and segment_length is None:
+        raise ValueError(
+            "InOutSingleChannel.measure_accumulated requires either 'segment_length' "
+            "or 'num_segments' to be provided."
+        )
+    elif num_segments is not None and segment_length is not None:
+        raise ValueError(
+            "InOutSingleChannel.measure_accumulated received both 'segment_length' "
+            "and 'num_segments'. Please provide only one."
+        )
+    elif num_segments is None:
+        num_segments = int(pulse.length / (4 * segment_length))  # Number of slices
+    elif segment_length is None:
+        segment_length = int(pulse.length / (4 * num_segments))
+
+    if qua_vars is not None:
+        if not isinstance(qua_vars, Sequence) or len(qua_vars) != 4:
+            raise ValueError(
+                f"InOutSingleChannel.measure_accumulated received kwarg 'qua_vars' "
+                f"which is not a tuple of four QUA variables. Received {qua_vars=}"
+            )
+    else:
+        qua_vars = [declare(fixed, size=num_segments) for _ in range(4)]
+
+    if amplitude_scale is not None:
+        if not isinstance(amplitude_scale, _PulseAmp):
+            amplitude_scale = amp(amplitude_scale)
+        pulse_name *= amplitude_scale
+
+    integration_weight_labels = list(pulse.integration_weights_mapping)
+    measure(
+        pulse_name,
+        self.name,
+        stream,
+        demod.accumulated(
+            integration_weight_labels[0], qua_vars[0], segment_length, "out1"
+        ),
+        demod.accumulated(
+            integration_weight_labels[1], qua_vars[1], segment_length, "out2"
+        ),
+        demod.accumulated(
+            integration_weight_labels[2], qua_vars[2], segment_length, "out1"
+        ),
+        demod.accumulated(
+            integration_weight_labels[0], qua_vars[3], segment_length, "out2"
+        ),
+    )
+    return tuple(qua_vars)
+
+
+
+ +
+ +
+ + +

+ measure_sliced(pulse_name, amplitude_scale=None, num_segments=None, segment_length=None, qua_vars=None, stream=None) + +

+ + +
+ +

Perform a sliced dual demodulation measurement on this channel.

+

Instead of two QUA variables (I and Q), this method returns four variables +(II, IQ, QI, QQ)

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
pulse_name + str + +
+

The name of the pulse to play. Should be registered in +self.operations.

+
+ 		+ required +
amplitude_scale + (float, _PulseAmp) + +
+

Amplitude scale of the pulse. +Can be either a float, or qua.amp(float).

+
+ 		+ None +
num_segments + int + +
+

The number of segments to accumulate. +Should either specify this or segment_length.

+
+ 		+ None +
segment_length + int + +
+

The length of the segment to accumulate the +measurement. +Should either specify this or num_segments.

+
+ 		+ None +
qua_vars + Tuple[QuaVariableType, ...] + +
+

Four QUA +variables to store the II, IQ, QI, QQ measurement results. +If not provided, new variables will be declared and returned.

+
+ 		+ None +
stream + Optional[StreamType] + +
+

The stream to save the measurement result to. +If not provided, the raw ADC signal will not be streamed.

+
+ 		+ None +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ Tuple[QuaVariableType, QuaVariableType, QuaVariableType, QuaVariableType] + +
+

II, IQ, QI, QQ: The QUA variables used to store the measurement results. +If provided as input, the same variables will be returned. +If not provided, new variables will be declared and returned.

+
+
+ +
+ Source code in quam/components/channels.py + 
1275
+1276
+1277
+1278
+1279
+1280
+1281
+1282
+1283
+1284
+1285
+1286
+1287
+1288
+1289
+1290
+1291
+1292
+1293
+1294
+1295
+1296
+1297
+1298
+1299
+1300
+1301
+1302
+1303
+1304
+1305
+1306
+1307
+1308
+1309
+1310
+1311
+1312
+1313
+1314
+1315
+1316
+1317
+1318
+1319
+1320
+1321
+1322
+1323
+1324
+1325
+1326
+1327
+1328
+1329
+1330
+1331
+1332
+1333
+1334
+1335
+1336
+1337
+1338
+1339
+1340
+1341
+1342
+1343
+1344
+1345
+1346
+1347
+1348
+1349
+1350
+1351
+1352
+1353
+1354
+1355
+1356
+1357
+1358
+1359
def measure_sliced(
+    self,
+    pulse_name: str,
+    amplitude_scale: Union[float, AmpValuesType] = None,
+    num_segments: int = None,
+    segment_length: int = None,
+    qua_vars: Tuple[QuaVariableType, ...] = None,
+    stream=None,
+) -> Tuple[QuaVariableType, QuaVariableType, QuaVariableType, QuaVariableType]:
+    """Perform a sliced dual demodulation measurement on this channel.
+
+    Instead of two QUA variables (I and Q), this method returns four variables
+    (II, IQ, QI, QQ)
+
+    Args:
+        pulse_name (str): The name of the pulse to play. Should be registered in
+            `self.operations`.
+        amplitude_scale (float, _PulseAmp): Amplitude scale of the pulse.
+            Can be either a float, or qua.amp(float).
+        num_segments (int): The number of segments to accumulate.
+            Should either specify this or `segment_length`.
+        segment_length (int): The length of the segment to accumulate the
+            measurement.
+            Should either specify this or `num_segments`.
+        qua_vars (Tuple[QuaVariableType, ...], optional): Four QUA
+            variables to store the II, IQ, QI, QQ measurement results.
+            If not provided, new variables will be declared and returned.
+        stream (Optional[StreamType]): The stream to save the measurement result to.
+            If not provided, the raw ADC signal will not be streamed.
+
+    Returns:
+        II, IQ, QI, QQ: The QUA variables used to store the measurement results.
+            If provided as input, the same variables will be returned.
+            If not provided, new variables will be declared and returned.
+    """
+    pulse: BaseReadoutPulse = self.operations[pulse_name]
+
+    if num_segments is None and segment_length is None:
+        raise ValueError(
+            "InOutSingleChannel.measure_sliced requires either 'segment_length' "
+            "or 'num_segments' to be provided."
+        )
+    elif num_segments is not None and segment_length is not None:
+        raise ValueError(
+            "InOutSingleChannel.measure_sliced received both 'segment_length' "
+            "and 'num_segments'. Please provide only one."
+        )
+    elif num_segments is None:
+        num_segments = int(pulse.length / (4 * segment_length))  # Number of slices
+    elif segment_length is None:
+        segment_length = int(pulse.length / (4 * num_segments))
+
+    if qua_vars is not None:
+        if not isinstance(qua_vars, Sequence) or len(qua_vars) != 4:
+            raise ValueError(
+                f"InOutSingleChannel.measure_sliced received kwarg 'qua_vars' "
+                f"which is not a tuple of four QUA variables. Received {qua_vars=}"
+            )
+    else:
+        qua_vars = [declare(fixed, size=num_segments) for _ in range(4)]
+
+    if amplitude_scale is not None:
+        if not isinstance(amplitude_scale, _PulseAmp):
+            amplitude_scale = amp(amplitude_scale)
+        pulse_name *= amplitude_scale
+
+    integration_weight_labels = list(pulse.integration_weights_mapping)
+    measure(
+        pulse_name,
+        self.name,
+        stream,
+        demod.sliced(
+            integration_weight_labels[0], qua_vars[0], segment_length, "out1"
+        ),
+        demod.sliced(
+            integration_weight_labels[1], qua_vars[1], segment_length, "out2"
+        ),
+        demod.sliced(
+            integration_weight_labels[2], qua_vars[2], segment_length, "out1"
+        ),
+        demod.sliced(
+            integration_weight_labels[0], qua_vars[3], segment_length, "out2"
+        ),
+    )
+    return tuple(qua_vars)
+
+
+
+ +
+ + + +
+ +
+ +
+ +
+ + + +

+ InIQOutSingleChannel + + +

+ + +
+

+ Bases: SingleChannel, InIQChannel

+ + +

QuAM component for an IQ input channel with a single output.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
operations + Dict[str, Pulse] + +
+

A dictionary of pulses to be played on this +channel. The key is the pulse label (e.g. "readout") and value is a +ReadoutPulse.

+
+ 		+ required +
id + (str, int) + +
+

The id of the channel, used to generate the name. +Can be a string, or an integer in which case it will add +Channel._default_label.

+
+ 		+ required +
opx_output + Tuple[str, int] + +
+

Channel output port from the OPX perspective, +a tuple of (controller_name, port).

+
+ 		+ required +
opx_output_offset + float + +
+

DC offset for the output port.

+
+ 		+ required +
opx_input_I + Tuple[str, int] + +
+

Channel I input port from the OPX perspective, +a tuple of (controller_name, port).

+
+ 		+ required +
opx_input_Q + Tuple[str, int] + +
+

Channel Q input port from the OPX perspective, +a tuple of (controller_name, port).

+
+ 		+ required +
opx_input_offset_I + float + +
+

The offset of the I channel. Default is 0.

+
+ 		+ required +
opx_input_offset_Q + float + +
+

The offset of the Q channel. Default is 0.

+
+ 		+ required +
filter_fir_taps + List[float] + +
+

FIR filter taps for the output port.

+
+ 		+ required +
filter_iir_taps + List[float] + +
+

IIR filter taps for the output port.

+
+ 		+ required +
intermediate_frequency + float + +
+

Intermediate frequency of OPX output, default +is None.

+
+ 		+ required +
time_of_flight + int + +
+

Round-trip signal duration in nanoseconds.

+
+ 		+ required +
smearing + int + +
+

Additional window of ADC integration in nanoseconds. +Used to account for signal smearing.

+
+ 		+ required +
+ +
+ Source code in quam/components/channels.py + 
1470
+1471
+1472
+1473
+1474
+1475
+1476
+1477
+1478
+1479
+1480
+1481
+1482
+1483
+1484
+1485
+1486
+1487
+1488
+1489
+1490
+1491
+1492
+1493
+1494
+1495
+1496
+1497
+1498
+1499
@quam_dataclass
+class InIQOutSingleChannel(SingleChannel, InIQChannel):
+    """QuAM component for an IQ input channel with a single output.
+
+    Args:
+        operations (Dict[str, Pulse]): A dictionary of pulses to be played on this
+            channel. The key is the pulse label (e.g. "readout") and value is a
+            ReadoutPulse.
+        id (str, int): The id of the channel, used to generate the name.
+            Can be a string, or an integer in which case it will add
+            `Channel._default_label`.
+        opx_output (Tuple[str, int]): Channel output port from the OPX perspective,
+            a tuple of (controller_name, port).
+        opx_output_offset (float): DC offset for the output port.
+        opx_input_I (Tuple[str, int]): Channel I input port from the OPX perspective,
+            a tuple of (controller_name, port).
+        opx_input_Q (Tuple[str, int]): Channel Q input port from the OPX perspective,
+            a tuple of (controller_name, port).
+        opx_input_offset_I float: The offset of the I channel. Default is 0.
+        opx_input_offset_Q float: The offset of the Q channel. Default is 0.
+        filter_fir_taps (List[float]): FIR filter taps for the output port.
+        filter_iir_taps (List[float]): IIR filter taps for the output port.
+        intermediate_frequency (float): Intermediate frequency of OPX output, default
+            is None.
+        time_of_flight (int): Round-trip signal duration in nanoseconds.
+        smearing (int): Additional window of ADC integration in nanoseconds.
+            Used to account for signal smearing.
+    """
+
+    pass
+
+
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ +
+ + + +

+ InOutIQChannel + + +

+ + +
+

+ Bases: IQChannel, InIQChannel

+ + +

QuAM component for an IQ channel with both input and output.

+

An example of such a channel is a readout resonator, where you may want to +apply a readout tone and then measure the response.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
operations + Dict[str, Pulse] + +
+

A dictionary of pulses to be played on this +channel. The key is the pulse label (e.g. "readout") and value is a +ReadoutPulse.

+
+ 		+ required +
id + (str, int) + +
+

The id of the channel, used to generate the name. +Can be a string, or an integer in which case it will add +Channel._default_label.

+
+ 		+ required +
opx_output_I + Tuple[str, int] + +
+

Channel I output port from the OPX perspective, +a tuple of (controller_name, port).

+
+ 		+ required +
opx_output_Q + Tuple[str, int] + +
+

Channel Q output port from the OPX perspective, +a tuple of (controller_name, port).

+
+ 		+ required +
opx_output_offset_I + float + +
+

The offset of the I channel. Default is 0.

+
+ 		+ required +
opx_output_offset_Q + float + +
+

The offset of the Q channel. Default is 0.

+
+ 		+ required +
opx_input_I + Tuple[str, int] + +
+

Channel I input port from the OPX perspective, +a tuple of (controller_name, port).

+
+ 		+ required +
opx_input_Q + Tuple[str, int] + +
+

Channel Q input port from the OPX perspective, +a tuple of (controller_name, port).

+
+ 		+ required +
opx_input_offset_I + float + +
+

The offset of the I channel. Default is 0.

+
+ 		+ required +
opx_input_offset_Q + float + +
+

The offset of the Q channel. Default is 0.

+
+ 		+ required +
intermediate_frequency + float + +
+

Intermediate frequency of the mixer. +Default is 0.0

+
+ 		+ required +
LO_frequency + float + +
+

Local oscillator frequency. Default is the LO frequency +of the frequency converter up component.

+
+ 		+ required +
RF_frequency + float + +
+

RF frequency of the mixer. By default, the RF frequency +is inferred by adding the LO frequency and the intermediate frequency.

+
+ 		+ required +
frequency_converter_up + FrequencyConverter + +
+

Frequency converter QuAM component +for the IQ output.

+
+ 		+ required +
frequency_converter_down + Optional[FrequencyConverter] + +
+

Frequency converter +QuAM component for the IQ input port. Only needed for the old Octave.

+
+ 		+ required +
time_of_flight + int + +
+

Round-trip signal duration in nanoseconds.

+
+ 		+ required +
smearing + int + +
+

Additional window of ADC integration in nanoseconds. +Used to account for signal smearing.

+
+ 		+ required +
+ +
+ Source code in quam/components/channels.py + 
1390
+1391
+1392
+1393
+1394
+1395
+1396
+1397
+1398
+1399
+1400
+1401
+1402
+1403
+1404
+1405
+1406
+1407
+1408
+1409
+1410
+1411
+1412
+1413
+1414
+1415
+1416
+1417
+1418
+1419
+1420
+1421
+1422
+1423
+1424
+1425
+1426
+1427
+1428
+1429
+1430
+1431
@quam_dataclass
+class InOutIQChannel(IQChannel, InIQChannel):
+    """QuAM component for an IQ channel with both input and output.
+
+    An example of such a channel is a readout resonator, where you may want to
+    apply a readout tone and then measure the response.
+
+    Args:
+        operations (Dict[str, Pulse]): A dictionary of pulses to be played on this
+            channel. The key is the pulse label (e.g. "readout") and value is a
+            ReadoutPulse.
+        id (str, int): The id of the channel, used to generate the name.
+            Can be a string, or an integer in which case it will add
+            `Channel._default_label`.
+        opx_output_I (Tuple[str, int]): Channel I output port from the OPX perspective,
+            a tuple of (controller_name, port).
+        opx_output_Q (Tuple[str, int]): Channel Q output port from the OPX perspective,
+            a tuple of (controller_name, port).
+        opx_output_offset_I float: The offset of the I channel. Default is 0.
+        opx_output_offset_Q float: The offset of the Q channel. Default is 0.
+        opx_input_I (Tuple[str, int]): Channel I input port from the OPX perspective,
+            a tuple of (controller_name, port).
+        opx_input_Q (Tuple[str, int]): Channel Q input port from the OPX perspective,
+            a tuple of (controller_name, port).
+        opx_input_offset_I float: The offset of the I channel. Default is 0.
+        opx_input_offset_Q float: The offset of the Q channel. Default is 0.
+        intermediate_frequency (float): Intermediate frequency of the mixer.
+            Default is 0.0
+        LO_frequency (float): Local oscillator frequency. Default is the LO frequency
+            of the frequency converter up component.
+        RF_frequency (float): RF frequency of the mixer. By default, the RF frequency
+            is inferred by adding the LO frequency and the intermediate frequency.
+        frequency_converter_up (FrequencyConverter): Frequency converter QuAM component
+            for the IQ output.
+        frequency_converter_down (Optional[FrequencyConverter]): Frequency converter
+            QuAM component for the IQ input port. Only needed for the old Octave.
+        time_of_flight (int): Round-trip signal duration in nanoseconds.
+        smearing (int): Additional window of ADC integration in nanoseconds.
+            Used to account for signal smearing.
+    """
+
+    pass
+
+
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ +
+ + + +

+ InOutSingleChannel + + +

+ + +
+

+ Bases: SingleChannel, InSingleChannel

+ + +

QuAM component for a single (not IQ) input + output channel.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
operations + Dict[str, Pulse] + +
+

A dictionary of pulses to be played on this +channel. The key is the pulse label (e.g. "X90") and value is a Pulse.

+
+ 		+ required +
id + (str, int) + +
+

The id of the channel, used to generate the name. +Can be a string, or an integer in which case it will add +Channel._default_label.

+
+ 		+ required +
opx_output + Tuple[str, int] + +
+

Channel output port from the OPX perspective, +a tuple of (controller_name, port).

+
+ 		+ required +
opx_output_offset + float + +
+

DC offset for the output port.

+
+ 		+ required +
opx_input + Tuple[str, int] + +
+

Channel input port from OPX perspective, +a tuple of (controller_name, port).

+
+ 		+ required +
opx_input_offset + float + +
+

DC offset for the input port.

+
+ 		+ required +
filter_fir_taps + List[float] + +
+

FIR filter taps for the output port.

+
+ 		+ required +
filter_iir_taps + List[float] + +
+

IIR filter taps for the output port.

+
+ 		+ required +
intermediate_frequency + float + +
+

Intermediate frequency of OPX output, default +is None.

+
+ 		+ required +
time_of_flight + int + +
+

Round-trip signal duration in nanoseconds.

+
+ 		+ required +
smearing + int + +
+

Additional window of ADC integration in nanoseconds. +Used to account for signal smearing.

+
+ 		+ required +
+ +
+ Source code in quam/components/channels.py + 
1362
+1363
+1364
+1365
+1366
+1367
+1368
+1369
+1370
+1371
+1372
+1373
+1374
+1375
+1376
+1377
+1378
+1379
+1380
+1381
+1382
+1383
+1384
+1385
+1386
+1387
@quam_dataclass
+class InOutSingleChannel(SingleChannel, InSingleChannel):
+    """QuAM component for a single (not IQ) input + output channel.
+
+    Args:
+        operations (Dict[str, Pulse]): A dictionary of pulses to be played on this
+            channel. The key is the pulse label (e.g. "X90") and value is a Pulse.
+        id (str, int): The id of the channel, used to generate the name.
+            Can be a string, or an integer in which case it will add
+            `Channel._default_label`.
+        opx_output (Tuple[str, int]): Channel output port from the OPX perspective,
+            a tuple of (controller_name, port).
+        opx_output_offset (float): DC offset for the output port.
+        opx_input (Tuple[str, int]): Channel input port from OPX perspective,
+            a tuple of (controller_name, port).
+        opx_input_offset (float): DC offset for the input port.
+        filter_fir_taps (List[float]): FIR filter taps for the output port.
+        filter_iir_taps (List[float]): IIR filter taps for the output port.
+        intermediate_frequency (float): Intermediate frequency of OPX output, default
+            is None.
+        time_of_flight (int): Round-trip signal duration in nanoseconds.
+        smearing (int): Additional window of ADC integration in nanoseconds.
+            Used to account for signal smearing.
+    """
+
+    pass
+
+
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ +
+ + + +

+ InSingleChannel + + +

+ + +
+

+ Bases: Channel

+ + +

QuAM component for a single (not IQ) input channel.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
operations + Dict[str, Pulse] + +
+

A dictionary of pulses to be played on this +channel. The key is the pulse label (e.g. "X90") and value is a Pulse.

+
+ 		+ required +
id + (str, int) + +
+

The id of the channel, used to generate the name. +Can be a string, or an integer in which case it will add +Channel._default_label.

+
+ 		+ required +
opx_input + Tuple[str, int] + +
+

Channel input port from OPX perspective, +a tuple of (controller_name, port).

+
+ 		+ required +
opx_input_offset + float + +
+

DC offset for the input port.

+
+ 		+ required +
intermediate_frequency + float + +
+

Intermediate frequency of OPX input, +default is None.

+
+ 		+ required +
time_of_flight + int + +
+

Round-trip signal duration in nanoseconds.

+
+ 		+ required +
smearing + int + +
+

Additional window of ADC integration in nanoseconds. +Used to account for signal smearing.

+
+ 		+ required +
+ +
+ Source code in quam/components/channels.py + 
550
+551
+552
+553
+554
+555
+556
+557
+558
+559
+560
+561
+562
+563
+564
+565
+566
+567
+568
+569
+570
+571
+572
+573
+574
+575
+576
+577
+578
+579
+580
+581
+582
+583
+584
+585
+586
+587
+588
+589
+590
+591
+592
+593
+594
+595
+596
+597
+598
+599
+600
+601
+602
+603
+604
+605
+606
+607
+608
+609
+610
+611
+612
+613
+614
+615
+616
+617
+618
+619
+620
+621
+622
+623
+624
+625
+626
+627
+628
+629
+630
+631
+632
+633
+634
+635
+636
+637
+638
+639
+640
+641
+642
+643
+644
+645
+646
+647
+648
+649
+650
+651
+652
+653
+654
+655
+656
+657
+658
+659
+660
+661
+662
+663
+664
+665
+666
+667
+668
+669
+670
+671
+672
+673
+674
+675
+676
+677
+678
+679
+680
+681
+682
+683
+684
+685
+686
+687
+688
+689
+690
+691
+692
+693
+694
+695
+696
+697
+698
+699
+700
+701
+702
+703
+704
+705
+706
+707
+708
+709
+710
+711
+712
+713
+714
+715
+716
+717
+718
+719
+720
+721
+722
+723
+724
+725
+726
+727
+728
+729
+730
+731
+732
+733
+734
+735
+736
+737
+738
+739
+740
+741
+742
+743
+744
+745
+746
+747
+748
+749
+750
+751
+752
+753
+754
+755
+756
+757
+758
+759
+760
+761
+762
+763
+764
+765
+766
+767
+768
+769
+770
+771
+772
+773
+774
+775
+776
+777
+778
+779
+780
+781
+782
+783
+784
+785
+786
+787
+788
+789
+790
+791
+792
+793
+794
+795
+796
+797
+798
+799
+800
+801
+802
+803
+804
+805
+806
+807
+808
+809
+810
+811
+812
+813
+814
+815
+816
+817
+818
+819
+820
+821
+822
+823
@quam_dataclass
+class InSingleChannel(Channel):
+    """QuAM component for a single (not IQ) input channel.
+
+    Args:
+        operations (Dict[str, Pulse]): A dictionary of pulses to be played on this
+            channel. The key is the pulse label (e.g. "X90") and value is a Pulse.
+        id (str, int): The id of the channel, used to generate the name.
+            Can be a string, or an integer in which case it will add
+            `Channel._default_label`.
+        opx_input (Tuple[str, int]): Channel input port from OPX perspective,
+            a tuple of (controller_name, port).
+        opx_input_offset (float): DC offset for the input port.
+        intermediate_frequency (float): Intermediate frequency of OPX input,
+            default is None.
+        time_of_flight (int): Round-trip signal duration in nanoseconds.
+        smearing (int): Additional window of ADC integration in nanoseconds.
+            Used to account for signal smearing.
+    """
+
+    opx_input: Union[Tuple[str, int], Tuple[str, int, int], LFAnalogInputPort]
+    opx_input_offset: float = None
+
+    time_of_flight: int = 24
+    smearing: int = 0
+
+    def apply_to_config(self, config: dict):
+        """Adds this InSingleChannel to the QUA configuration.
+
+        See [`QuamComponent.apply_to_config`][quam.core.quam_classes.QuamComponent.apply_to_config]
+        for details.
+        """
+        # Add output to config
+        super().apply_to_config(config)
+
+        # Note outputs instead of inputs because it's w.r.t. the QPU
+        element_config = config["elements"][self.name]
+        element_config["smearing"] = self.smearing
+        element_config["time_of_flight"] = self.time_of_flight
+
+        if isinstance(self.opx_input, LFAnalogInputPort):
+            opx_port = self.opx_input
+        elif len(self.opx_input) == 2:
+            opx_port = OPXPlusAnalogInputPort(
+                *self.opx_input, offset=self.opx_input_offset
+            )
+            opx_port.apply_to_config(config)
+        else:
+            opx_port = LFFEMAnalogInputPort(
+                *self.opx_input, offset=self.opx_input_offset
+            )
+            opx_port.apply_to_config(config)
+
+        element_config["outputs"] = {"out1": opx_port.port_tuple}
+
+    def measure(
+        self,
+        pulse_name: str,
+        amplitude_scale: Union[float, AmpValuesType] = None,
+        qua_vars: Tuple[QuaVariableType, ...] = None,
+        stream=None,
+    ) -> Tuple[QuaVariableType, QuaVariableType]:
+        """Perform a full demodulation measurement on this channel.
+
+        Args:
+            pulse_name (str): The name of the pulse to play. Should be registered in
+                `self.operations`.
+            amplitude_scale (float, _PulseAmp): Amplitude scale of the pulse.
+                Can be either a float, or qua.amp(float).
+            qua_vars (Tuple[QuaVariableType, ...], optional): Two QUA
+                variables to store the I, Q measurement results.
+                If not provided, new variables will be declared and returned.
+            stream (Optional[StreamType]): The stream to save the measurement result to.
+                If not provided, the raw ADC signal will not be streamed.
+
+        Returns:
+            I, Q: The QUA variables used to store the measurement results.
+                If provided as input, the same variables will be returned.
+                If not provided, new variables will be declared and returned.
+
+        Raises:
+            ValueError: If `qua_vars` is provided and is not a tuple of two QUA
+                variables.
+        """
+
+        pulse: BaseReadoutPulse = self.operations[pulse_name]
+
+        if qua_vars is not None:
+            if not isinstance(qua_vars, Sequence) or len(qua_vars) != 2:
+                raise ValueError(
+                    f"InOutSingleChannel.measure received kwarg 'qua_vars' "
+                    f"which is not a tuple of two QUA variables. Received {qua_vars=}"
+                )
+        else:
+            qua_vars = [declare(fixed) for _ in range(2)]
+
+        if amplitude_scale is not None:
+            if not isinstance(amplitude_scale, _PulseAmp):
+                amplitude_scale = amp(amplitude_scale)
+            pulse_name *= amplitude_scale
+
+        integration_weight_labels = list(pulse.integration_weights_mapping)
+        measure(
+            pulse_name,
+            self.name,
+            stream,
+            demod.full(integration_weight_labels[0], qua_vars[0], "out1"),
+            demod.full(integration_weight_labels[1], qua_vars[1], "out1"),
+        )
+        return tuple(qua_vars)
+
+    def measure_accumulated(
+        self,
+        pulse_name: str,
+        amplitude_scale: Union[float, AmpValuesType] = None,
+        num_segments: int = None,
+        segment_length: int = None,
+        qua_vars: Tuple[QuaVariableType, ...] = None,
+        stream=None,
+    ) -> Tuple[QuaVariableType, QuaVariableType]:
+        """Perform an accumulated demodulation measurement on this channel.
+
+        Args:
+            pulse_name (str): The name of the pulse to play. Should be registered in
+                `self.operations`.
+            amplitude_scale (float, _PulseAmp): Amplitude scale of the pulse.
+                Can be either a float, or qua.amp(float).
+            num_segments (int): The number of segments to accumulate.
+                Should either specify this or `segment_length`.
+            segment_length (int): The length of the segment to accumulate.
+                Should either specify this or `num_segments`.
+            qua_vars (Tuple[QuaVariableType, ...], optional): Two QUA
+                variables to store the I, Q measurement results.
+                If not provided, new variables will be declared and returned.
+            stream (Optional[StreamType]): The stream to save the measurement result to.
+                If not provided, the raw ADC signal will not be streamed.
+
+        Returns:
+            I, Q: The QUA variables used to store the measurement results.
+                If provided as input, the same variables will be returned.
+                If not provided, new variables will be declared and returned.
+
+        Raises:
+            ValueError: If both `num_segments` and `segment_length` are provided, or if
+                neither are provided.
+            ValueError: If `qua_vars` is provided and is not a tuple of two QUA
+                variables.
+        """
+        pulse: BaseReadoutPulse = self.operations[pulse_name]
+
+        if num_segments is None and segment_length is None:
+            raise ValueError(
+                "InOutSingleChannel.measure_accumulated requires either 'segment_length' "
+                "or 'num_segments' to be provided."
+            )
+        elif num_segments is not None and segment_length is not None:
+            raise ValueError(
+                "InOutSingleChannel.measure_accumulated received both 'segment_length' "
+                "and 'num_segments'. Please provide only one."
+            )
+        elif num_segments is None:
+            num_segments = int(pulse.length / (4 * segment_length))  # Number of slices
+        elif segment_length is None:
+            segment_length = int(pulse.length / (4 * num_segments))
+
+        if qua_vars is not None:
+            if not isinstance(qua_vars, Sequence) or len(qua_vars) != 2:
+                raise ValueError(
+                    f"InOutSingleChannel.measure_accumulated received kwarg 'qua_vars' "
+                    f"which is not a tuple of two QUA variables. Received {qua_vars=}"
+                )
+        else:
+            qua_vars = [declare(fixed, size=num_segments) for _ in range(2)]
+
+        if amplitude_scale is not None:
+            if not isinstance(amplitude_scale, _PulseAmp):
+                amplitude_scale = amp(amplitude_scale)
+            pulse_name *= amplitude_scale
+
+        integration_weight_labels = list(pulse.integration_weights_mapping)
+        measure(
+            pulse_name,
+            self.name,
+            stream,
+            demod.accumulated(
+                integration_weight_labels[0], qua_vars[0], segment_length, "out1"
+            ),
+            demod.accumulated(
+                integration_weight_labels[1], qua_vars[1], segment_length, "out1"
+            ),
+        )
+        return tuple(qua_vars)
+
+    def measure_sliced(
+        self,
+        pulse_name: str,
+        amplitude_scale: Union[float, AmpValuesType] = None,
+        num_segments: int = None,
+        segment_length: int = None,
+        qua_vars: Tuple[QuaVariableType, ...] = None,
+        stream=None,
+    ) -> Tuple[QuaVariableType, QuaVariableType]:
+        """Perform an accumulated demodulation measurement on this channel.
+
+        Args:
+            pulse_name (str): The name of the pulse to play. Should be registered in
+                `self.operations`.
+            amplitude_scale (float, _PulseAmp): Amplitude scale of the pulse.
+                Can be either a float, or qua.amp(float).
+            num_segments (int): The number of segments to accumulate.
+                Should either specify this or `segment_length`.
+            segment_length (int): The length of the segment to accumulate.
+                Should either specify this or `num_segments`.
+            qua_vars (Tuple[QuaVariableType, ...], optional): Two QUA
+                variables to store the I, Q measurement results.
+                If not provided, new variables will be declared and returned.
+            stream (Optional[StreamType]): The stream to save the measurement result to.
+                If not provided, the raw ADC signal will not be streamed.
+
+        Returns:
+            I, Q: The QUA variables used to store the measurement results.
+                If provided as input, the same variables will be returned.
+                If not provided, new variables will be declared and returned.
+
+        Raises:
+            ValueError: If both `num_segments` and `segment_length` are provided, or if
+                neither are provided.
+            ValueError: If `qua_vars` is provided and is not a tuple of two QUA
+                variables.
+        """
+        pulse: BaseReadoutPulse = self.operations[pulse_name]
+
+        if num_segments is None and segment_length is None:
+            raise ValueError(
+                "InOutSingleChannel.measure_sliced requires either 'segment_length' "
+                "or 'num_segments' to be provided."
+            )
+        elif num_segments is not None and segment_length is not None:
+            raise ValueError(
+                "InOutSingleChannel.measure_sliced received both 'segment_length' "
+                "and 'num_segments'. Please provide only one."
+            )
+        elif num_segments is None:
+            num_segments = int(pulse.length / (4 * segment_length))  # Number of slices
+        elif segment_length is None:
+            segment_length = int(pulse.length / (4 * num_segments))
+
+        if qua_vars is not None:
+            if not isinstance(qua_vars, Sequence) or len(qua_vars) != 2:
+                raise ValueError(
+                    f"InOutSingleChannel.measure_sliced received kwarg 'qua_vars' "
+                    f"which is not a tuple of two QUA variables. Received {qua_vars=}"
+                )
+        else:
+            qua_vars = [declare(fixed, size=num_segments) for _ in range(2)]
+
+        if amplitude_scale is not None:
+            if not isinstance(amplitude_scale, _PulseAmp):
+                amplitude_scale = amp(amplitude_scale)
+            pulse_name *= amplitude_scale
+
+        integration_weight_labels = list(pulse.integration_weights_mapping)
+        measure(
+            pulse_name,
+            self.name,
+            stream,
+            demod.sliced(
+                integration_weight_labels[0], qua_vars[0], segment_length, "out1"
+            ),
+            demod.sliced(
+                integration_weight_labels[1], qua_vars[1], segment_length, "out1"
+            ),
+        )
+        return tuple(qua_vars)
+
+
+ + + +
+ + + + + + + + + +
+ + +

+ apply_to_config(config) + +

+ + +
+ +

Adds this InSingleChannel to the QUA configuration.

+

See QuamComponent.apply_to_config +for details.

+ +
+ Source code in quam/components/channels.py + 
576
+577
+578
+579
+580
+581
+582
+583
+584
+585
+586
+587
+588
+589
+590
+591
+592
+593
+594
+595
+596
+597
+598
+599
+600
+601
+602
+603
def apply_to_config(self, config: dict):
+    """Adds this InSingleChannel to the QUA configuration.
+
+    See [`QuamComponent.apply_to_config`][quam.core.quam_classes.QuamComponent.apply_to_config]
+    for details.
+    """
+    # Add output to config
+    super().apply_to_config(config)
+
+    # Note outputs instead of inputs because it's w.r.t. the QPU
+    element_config = config["elements"][self.name]
+    element_config["smearing"] = self.smearing
+    element_config["time_of_flight"] = self.time_of_flight
+
+    if isinstance(self.opx_input, LFAnalogInputPort):
+        opx_port = self.opx_input
+    elif len(self.opx_input) == 2:
+        opx_port = OPXPlusAnalogInputPort(
+            *self.opx_input, offset=self.opx_input_offset
+        )
+        opx_port.apply_to_config(config)
+    else:
+        opx_port = LFFEMAnalogInputPort(
+            *self.opx_input, offset=self.opx_input_offset
+        )
+        opx_port.apply_to_config(config)
+
+    element_config["outputs"] = {"out1": opx_port.port_tuple}
+
+
+
+ +
+ +
+ + +

+ measure(pulse_name, amplitude_scale=None, qua_vars=None, stream=None) + +

+ + +
+ +

Perform a full demodulation measurement on this channel.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
pulse_name + str + +
+

The name of the pulse to play. Should be registered in +self.operations.

+
+ 		+ required +
amplitude_scale + (float, _PulseAmp) + +
+

Amplitude scale of the pulse. +Can be either a float, or qua.amp(float).

+
+ 		+ None +
qua_vars + Tuple[QuaVariableType, ...] + +
+

Two QUA +variables to store the I, Q measurement results. +If not provided, new variables will be declared and returned.

+
+ 		+ None +
stream + Optional[StreamType] + +
+

The stream to save the measurement result to. +If not provided, the raw ADC signal will not be streamed.

+
+ 		+ None +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ Tuple[QuaVariableType, QuaVariableType] + +
+

I, Q: The QUA variables used to store the measurement results. +If provided as input, the same variables will be returned. +If not provided, new variables will be declared and returned.

+
+
+ + +

Raises:

+ + + + + + + + + + + + + +
TypeDescription
+ ValueError + +
+

If qua_vars is provided and is not a tuple of two QUA +variables.

+
+
+ +
+ Source code in quam/components/channels.py + 
605
+606
+607
+608
+609
+610
+611
+612
+613
+614
+615
+616
+617
+618
+619
+620
+621
+622
+623
+624
+625
+626
+627
+628
+629
+630
+631
+632
+633
+634
+635
+636
+637
+638
+639
+640
+641
+642
+643
+644
+645
+646
+647
+648
+649
+650
+651
+652
+653
+654
+655
+656
+657
+658
+659
def measure(
+    self,
+    pulse_name: str,
+    amplitude_scale: Union[float, AmpValuesType] = None,
+    qua_vars: Tuple[QuaVariableType, ...] = None,
+    stream=None,
+) -> Tuple[QuaVariableType, QuaVariableType]:
+    """Perform a full demodulation measurement on this channel.
+
+    Args:
+        pulse_name (str): The name of the pulse to play. Should be registered in
+            `self.operations`.
+        amplitude_scale (float, _PulseAmp): Amplitude scale of the pulse.
+            Can be either a float, or qua.amp(float).
+        qua_vars (Tuple[QuaVariableType, ...], optional): Two QUA
+            variables to store the I, Q measurement results.
+            If not provided, new variables will be declared and returned.
+        stream (Optional[StreamType]): The stream to save the measurement result to.
+            If not provided, the raw ADC signal will not be streamed.
+
+    Returns:
+        I, Q: The QUA variables used to store the measurement results.
+            If provided as input, the same variables will be returned.
+            If not provided, new variables will be declared and returned.
+
+    Raises:
+        ValueError: If `qua_vars` is provided and is not a tuple of two QUA
+            variables.
+    """
+
+    pulse: BaseReadoutPulse = self.operations[pulse_name]
+
+    if qua_vars is not None:
+        if not isinstance(qua_vars, Sequence) or len(qua_vars) != 2:
+            raise ValueError(
+                f"InOutSingleChannel.measure received kwarg 'qua_vars' "
+                f"which is not a tuple of two QUA variables. Received {qua_vars=}"
+            )
+    else:
+        qua_vars = [declare(fixed) for _ in range(2)]
+
+    if amplitude_scale is not None:
+        if not isinstance(amplitude_scale, _PulseAmp):
+            amplitude_scale = amp(amplitude_scale)
+        pulse_name *= amplitude_scale
+
+    integration_weight_labels = list(pulse.integration_weights_mapping)
+    measure(
+        pulse_name,
+        self.name,
+        stream,
+        demod.full(integration_weight_labels[0], qua_vars[0], "out1"),
+        demod.full(integration_weight_labels[1], qua_vars[1], "out1"),
+    )
+    return tuple(qua_vars)
+
+
+
+ +
+ +
+ + +

+ measure_accumulated(pulse_name, amplitude_scale=None, num_segments=None, segment_length=None, qua_vars=None, stream=None) + +

+ + +
+ +

Perform an accumulated demodulation measurement on this channel.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
pulse_name + str + +
+

The name of the pulse to play. Should be registered in +self.operations.

+
+ 		+ required +
amplitude_scale + (float, _PulseAmp) + +
+

Amplitude scale of the pulse. +Can be either a float, or qua.amp(float).

+
+ 		+ None +
num_segments + int + +
+

The number of segments to accumulate. +Should either specify this or segment_length.

+
+ 		+ None +
segment_length + int + +
+

The length of the segment to accumulate. +Should either specify this or num_segments.

+
+ 		+ None +
qua_vars + Tuple[QuaVariableType, ...] + +
+

Two QUA +variables to store the I, Q measurement results. +If not provided, new variables will be declared and returned.

+
+ 		+ None +
stream + Optional[StreamType] + +
+

The stream to save the measurement result to. +If not provided, the raw ADC signal will not be streamed.

+
+ 		+ None +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ Tuple[QuaVariableType, QuaVariableType] + +
+

I, Q: The QUA variables used to store the measurement results. +If provided as input, the same variables will be returned. +If not provided, new variables will be declared and returned.

+
+
+ + +

Raises:

+ + + + + + + + + + + + + + + + + +
TypeDescription
+ ValueError + +
+

If both num_segments and segment_length are provided, or if +neither are provided.

+
+
+ ValueError + +
+

If qua_vars is provided and is not a tuple of two QUA +variables.

+
+
+ +
+ Source code in quam/components/channels.py + 
661
+662
+663
+664
+665
+666
+667
+668
+669
+670
+671
+672
+673
+674
+675
+676
+677
+678
+679
+680
+681
+682
+683
+684
+685
+686
+687
+688
+689
+690
+691
+692
+693
+694
+695
+696
+697
+698
+699
+700
+701
+702
+703
+704
+705
+706
+707
+708
+709
+710
+711
+712
+713
+714
+715
+716
+717
+718
+719
+720
+721
+722
+723
+724
+725
+726
+727
+728
+729
+730
+731
+732
+733
+734
+735
+736
+737
+738
+739
+740
+741
def measure_accumulated(
+    self,
+    pulse_name: str,
+    amplitude_scale: Union[float, AmpValuesType] = None,
+    num_segments: int = None,
+    segment_length: int = None,
+    qua_vars: Tuple[QuaVariableType, ...] = None,
+    stream=None,
+) -> Tuple[QuaVariableType, QuaVariableType]:
+    """Perform an accumulated demodulation measurement on this channel.
+
+    Args:
+        pulse_name (str): The name of the pulse to play. Should be registered in
+            `self.operations`.
+        amplitude_scale (float, _PulseAmp): Amplitude scale of the pulse.
+            Can be either a float, or qua.amp(float).
+        num_segments (int): The number of segments to accumulate.
+            Should either specify this or `segment_length`.
+        segment_length (int): The length of the segment to accumulate.
+            Should either specify this or `num_segments`.
+        qua_vars (Tuple[QuaVariableType, ...], optional): Two QUA
+            variables to store the I, Q measurement results.
+            If not provided, new variables will be declared and returned.
+        stream (Optional[StreamType]): The stream to save the measurement result to.
+            If not provided, the raw ADC signal will not be streamed.
+
+    Returns:
+        I, Q: The QUA variables used to store the measurement results.
+            If provided as input, the same variables will be returned.
+            If not provided, new variables will be declared and returned.
+
+    Raises:
+        ValueError: If both `num_segments` and `segment_length` are provided, or if
+            neither are provided.
+        ValueError: If `qua_vars` is provided and is not a tuple of two QUA
+            variables.
+    """
+    pulse: BaseReadoutPulse = self.operations[pulse_name]
+
+    if num_segments is None and segment_length is None:
+        raise ValueError(
+            "InOutSingleChannel.measure_accumulated requires either 'segment_length' "
+            "or 'num_segments' to be provided."
+        )
+    elif num_segments is not None and segment_length is not None:
+        raise ValueError(
+            "InOutSingleChannel.measure_accumulated received both 'segment_length' "
+            "and 'num_segments'. Please provide only one."
+        )
+    elif num_segments is None:
+        num_segments = int(pulse.length / (4 * segment_length))  # Number of slices
+    elif segment_length is None:
+        segment_length = int(pulse.length / (4 * num_segments))
+
+    if qua_vars is not None:
+        if not isinstance(qua_vars, Sequence) or len(qua_vars) != 2:
+            raise ValueError(
+                f"InOutSingleChannel.measure_accumulated received kwarg 'qua_vars' "
+                f"which is not a tuple of two QUA variables. Received {qua_vars=}"
+            )
+    else:
+        qua_vars = [declare(fixed, size=num_segments) for _ in range(2)]
+
+    if amplitude_scale is not None:
+        if not isinstance(amplitude_scale, _PulseAmp):
+            amplitude_scale = amp(amplitude_scale)
+        pulse_name *= amplitude_scale
+
+    integration_weight_labels = list(pulse.integration_weights_mapping)
+    measure(
+        pulse_name,
+        self.name,
+        stream,
+        demod.accumulated(
+            integration_weight_labels[0], qua_vars[0], segment_length, "out1"
+        ),
+        demod.accumulated(
+            integration_weight_labels[1], qua_vars[1], segment_length, "out1"
+        ),
+    )
+    return tuple(qua_vars)
+
+
+
+ +
+ +
+ + +

+ measure_sliced(pulse_name, amplitude_scale=None, num_segments=None, segment_length=None, qua_vars=None, stream=None) + +

+ + +
+ +

Perform an accumulated demodulation measurement on this channel.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
pulse_name + str + +
+

The name of the pulse to play. Should be registered in +self.operations.

+
+ 		+ required +
amplitude_scale + (float, _PulseAmp) + +
+

Amplitude scale of the pulse. +Can be either a float, or qua.amp(float).

+
+ 		+ None +
num_segments + int + +
+

The number of segments to accumulate. +Should either specify this or segment_length.

+
+ 		+ None +
segment_length + int + +
+

The length of the segment to accumulate. +Should either specify this or num_segments.

+
+ 		+ None +
qua_vars + Tuple[QuaVariableType, ...] + +
+

Two QUA +variables to store the I, Q measurement results. +If not provided, new variables will be declared and returned.

+
+ 		+ None +
stream + Optional[StreamType] + +
+

The stream to save the measurement result to. +If not provided, the raw ADC signal will not be streamed.

+
+ 		+ None +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ Tuple[QuaVariableType, QuaVariableType] + +
+

I, Q: The QUA variables used to store the measurement results. +If provided as input, the same variables will be returned. +If not provided, new variables will be declared and returned.

+
+
+ + +

Raises:

+ + + + + + + + + + + + + + + + + +
TypeDescription
+ ValueError + +
+

If both num_segments and segment_length are provided, or if +neither are provided.

+
+
+ ValueError + +
+

If qua_vars is provided and is not a tuple of two QUA +variables.

+
+
+ +
+ Source code in quam/components/channels.py + 
743
+744
+745
+746
+747
+748
+749
+750
+751
+752
+753
+754
+755
+756
+757
+758
+759
+760
+761
+762
+763
+764
+765
+766
+767
+768
+769
+770
+771
+772
+773
+774
+775
+776
+777
+778
+779
+780
+781
+782
+783
+784
+785
+786
+787
+788
+789
+790
+791
+792
+793
+794
+795
+796
+797
+798
+799
+800
+801
+802
+803
+804
+805
+806
+807
+808
+809
+810
+811
+812
+813
+814
+815
+816
+817
+818
+819
+820
+821
+822
+823
def measure_sliced(
+    self,
+    pulse_name: str,
+    amplitude_scale: Union[float, AmpValuesType] = None,
+    num_segments: int = None,
+    segment_length: int = None,
+    qua_vars: Tuple[QuaVariableType, ...] = None,
+    stream=None,
+) -> Tuple[QuaVariableType, QuaVariableType]:
+    """Perform an accumulated demodulation measurement on this channel.
+
+    Args:
+        pulse_name (str): The name of the pulse to play. Should be registered in
+            `self.operations`.
+        amplitude_scale (float, _PulseAmp): Amplitude scale of the pulse.
+            Can be either a float, or qua.amp(float).
+        num_segments (int): The number of segments to accumulate.
+            Should either specify this or `segment_length`.
+        segment_length (int): The length of the segment to accumulate.
+            Should either specify this or `num_segments`.
+        qua_vars (Tuple[QuaVariableType, ...], optional): Two QUA
+            variables to store the I, Q measurement results.
+            If not provided, new variables will be declared and returned.
+        stream (Optional[StreamType]): The stream to save the measurement result to.
+            If not provided, the raw ADC signal will not be streamed.
+
+    Returns:
+        I, Q: The QUA variables used to store the measurement results.
+            If provided as input, the same variables will be returned.
+            If not provided, new variables will be declared and returned.
+
+    Raises:
+        ValueError: If both `num_segments` and `segment_length` are provided, or if
+            neither are provided.
+        ValueError: If `qua_vars` is provided and is not a tuple of two QUA
+            variables.
+    """
+    pulse: BaseReadoutPulse = self.operations[pulse_name]
+
+    if num_segments is None and segment_length is None:
+        raise ValueError(
+            "InOutSingleChannel.measure_sliced requires either 'segment_length' "
+            "or 'num_segments' to be provided."
+        )
+    elif num_segments is not None and segment_length is not None:
+        raise ValueError(
+            "InOutSingleChannel.measure_sliced received both 'segment_length' "
+            "and 'num_segments'. Please provide only one."
+        )
+    elif num_segments is None:
+        num_segments = int(pulse.length / (4 * segment_length))  # Number of slices
+    elif segment_length is None:
+        segment_length = int(pulse.length / (4 * num_segments))
+
+    if qua_vars is not None:
+        if not isinstance(qua_vars, Sequence) or len(qua_vars) != 2:
+            raise ValueError(
+                f"InOutSingleChannel.measure_sliced received kwarg 'qua_vars' "
+                f"which is not a tuple of two QUA variables. Received {qua_vars=}"
+            )
+    else:
+        qua_vars = [declare(fixed, size=num_segments) for _ in range(2)]
+
+    if amplitude_scale is not None:
+        if not isinstance(amplitude_scale, _PulseAmp):
+            amplitude_scale = amp(amplitude_scale)
+        pulse_name *= amplitude_scale
+
+    integration_weight_labels = list(pulse.integration_weights_mapping)
+    measure(
+        pulse_name,
+        self.name,
+        stream,
+        demod.sliced(
+            integration_weight_labels[0], qua_vars[0], segment_length, "out1"
+        ),
+        demod.sliced(
+            integration_weight_labels[1], qua_vars[1], segment_length, "out1"
+        ),
+    )
+    return tuple(qua_vars)
+
+
+
+ +
+ + + +
+ +
+ +
+ +
+ + + +

+ InSingleOutIQChannel + + +

+ + +
+

+ Bases: IQChannel, InSingleChannel

+ + +

QuAM component for an IQ output channel with a single input.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
operations + Dict[str, Pulse] + +
+

A dictionary of pulses to be played on this +channel. The key is the pulse label (e.g. "readout") and value is a +ReadoutPulse.

+
+ 		+ required +
id + (str, int) + +
+

The id of the channel, used to generate the name. +Can be a string, or an integer in which case it will add +Channel._default_label.

+
+ 		+ required +
opx_output_I + Tuple[str, int] + +
+

Channel I output port from the OPX perspective, +a tuple of (controller_name, port).

+
+ 		+ required +
opx_output_Q + Tuple[str, int] + +
+

Channel Q output port from the OPX perspective, +a tuple of (controller_name, port).

+
+ 		+ required +
opx_output_offset_I + float + +
+

The offset of the I channel. Default is 0.

+
+ 		+ required +
opx_output_offset_Q + float + +
+

The offset of the Q channel. Default is 0.

+
+ 		+ required +
opx_input + Tuple[str, int] + +
+

Channel input port from OPX perspective, +a tuple of (controller_name, port).

+
+ 		+ required +
opx_input_offset + float + +
+

DC offset for the input port.

+
+ 		+ required +
intermediate_frequency + float + +
+

Intermediate frequency of the mixer. +Default is 0.0

+
+ 		+ required +
LO_frequency + float + +
+

Local oscillator frequency. Default is the LO frequency +of the frequency converter up component.

+
+ 		+ required +
RF_frequency + float + +
+

RF frequency of the mixer. By default, the RF frequency +is inferred by adding the LO frequency and the intermediate frequency.

+
+ 		+ required +
frequency_converter_up + FrequencyConverter + +
+

Frequency converter QuAM component +for the IQ output.

+
+ 		+ required +
time_of_flight + int + +
+

Round-trip signal duration in nanoseconds.

+
+ 		+ required +
smearing + int + +
+

Additional window of ADC integration in nanoseconds. +Used to account for signal smearing.

+
+ 		+ required +
+ +
+ Source code in quam/components/channels.py + 
1434
+1435
+1436
+1437
+1438
+1439
+1440
+1441
+1442
+1443
+1444
+1445
+1446
+1447
+1448
+1449
+1450
+1451
+1452
+1453
+1454
+1455
+1456
+1457
+1458
+1459
+1460
+1461
+1462
+1463
+1464
+1465
+1466
+1467
@quam_dataclass
+class InSingleOutIQChannel(IQChannel, InSingleChannel):
+    """QuAM component for an IQ output channel with a single input.
+
+    Args:
+        operations (Dict[str, Pulse]): A dictionary of pulses to be played on this
+            channel. The key is the pulse label (e.g. "readout") and value is a
+            ReadoutPulse.
+        id (str, int): The id of the channel, used to generate the name.
+            Can be a string, or an integer in which case it will add
+            `Channel._default_label`.
+        opx_output_I (Tuple[str, int]): Channel I output port from the OPX perspective,
+            a tuple of (controller_name, port).
+        opx_output_Q (Tuple[str, int]): Channel Q output port from the OPX perspective,
+            a tuple of (controller_name, port).
+        opx_output_offset_I float: The offset of the I channel. Default is 0.
+        opx_output_offset_Q float: The offset of the Q channel. Default is 0.
+        opx_input (Tuple[str, int]): Channel input port from OPX perspective,
+            a tuple of (controller_name, port).
+        opx_input_offset (float): DC offset for the input port.
+        intermediate_frequency (float): Intermediate frequency of the mixer.
+            Default is 0.0
+        LO_frequency (float): Local oscillator frequency. Default is the LO frequency
+            of the frequency converter up component.
+        RF_frequency (float): RF frequency of the mixer. By default, the RF frequency
+            is inferred by adding the LO frequency and the intermediate frequency.
+        frequency_converter_up (FrequencyConverter): Frequency converter QuAM component
+            for the IQ output.
+        time_of_flight (int): Round-trip signal duration in nanoseconds.
+        smearing (int): Additional window of ADC integration in nanoseconds.
+            Used to account for signal smearing.
+    """
+
+    pass
+
+
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ +
+ + + +

+ SingleChannel + + +

+ + +
+

+ Bases: Channel

+ + +

QuAM component for a single (not IQ) output channel.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
operations + Dict[str, Pulse] + +
+

A dictionary of pulses to be played on this +channel. The key is the pulse label (e.g. "X90") and value is a Pulse.

+
+ 		+ required +
id + (str, int) + +
+

The id of the channel, used to generate the name. +Can be a string, or an integer in which case it will add +Channel._default_label.

+
+ 		+ required +
opx_output + Tuple[str, int] + +
+

Channel output port from the OPX perspective, +a tuple of (controller_name, port).

+
+ 		+ required +
filter_fir_taps + List[float] + +
+

FIR filter taps for the output port.

+
+ 		+ required +
filter_iir_taps + List[float] + +
+

IIR filter taps for the output port.

+
+ 		+ required +
opx_output_offset + float + +
+

DC offset for the output port.

+
+ 		+ required +
intermediate_frequency + float + +
+

Intermediate frequency of OPX output, default +is None.

+
+ 		+ required +
+ +
+ Source code in quam/components/channels.py + 
461
+462
+463
+464
+465
+466
+467
+468
+469
+470
+471
+472
+473
+474
+475
+476
+477
+478
+479
+480
+481
+482
+483
+484
+485
+486
+487
+488
+489
+490
+491
+492
+493
+494
+495
+496
+497
+498
+499
+500
+501
+502
+503
+504
+505
+506
+507
+508
+509
+510
+511
+512
+513
+514
+515
+516
+517
+518
+519
+520
+521
+522
+523
+524
+525
+526
+527
+528
+529
+530
+531
+532
+533
+534
+535
+536
+537
+538
+539
+540
+541
+542
+543
+544
+545
+546
+547
@quam_dataclass
+class SingleChannel(Channel):
+    """QuAM component for a single (not IQ) output channel.
+
+    Args:
+        operations (Dict[str, Pulse]): A dictionary of pulses to be played on this
+            channel. The key is the pulse label (e.g. "X90") and value is a Pulse.
+        id (str, int): The id of the channel, used to generate the name.
+            Can be a string, or an integer in which case it will add
+            `Channel._default_label`.
+        opx_output (Tuple[str, int]): Channel output port from the OPX perspective,
+            a tuple of (controller_name, port).
+        filter_fir_taps (List[float]): FIR filter taps for the output port.
+        filter_iir_taps (List[float]): IIR filter taps for the output port.
+        opx_output_offset (float): DC offset for the output port.
+        intermediate_frequency (float): Intermediate frequency of OPX output, default
+            is None.
+    """
+
+    opx_output: Union[Tuple[str, int], Tuple[str, int, int], LFAnalogOutputPort]
+    filter_fir_taps: List[float] = None
+    filter_iir_taps: List[float] = None
+
+    opx_output_offset: float = None
+    intermediate_frequency: float = None
+
+    def set_dc_offset(self, offset: QuaNumberType):
+        """Set the DC offset of an element's input to the given value.
+        This value will remain the DC offset until changed or until the Quantum Machine
+        is closed.
+
+        Args:
+            offset (QuaNumberType): The DC offset to set the input to.
+                This is limited by the OPX output voltage range.
+                The number can be a QUA variable
+        """
+        set_dc_offset(element=self.name, element_input="single", offset=offset)
+
+    def apply_to_config(self, config: dict):
+        """Adds this SingleChannel to the QUA configuration.
+
+        See [`QuamComponent.apply_to_config`][quam.core.quam_classes.QuamComponent.apply_to_config]
+        for details.
+        """
+        # Add pulses & waveforms
+        super().apply_to_config(config)
+
+        if str_ref.is_reference(self.name):
+            raise AttributeError(
+                f"Channel {self.get_reference()} cannot be added to the config because"
+                " it doesn't have a name. Either set channel.id to a string or"
+                " integer, or channel should be an attribute of another QuAM component"
+                " with a name."
+            )
+
+        element_config = config["elements"][self.name]
+
+        if self.intermediate_frequency is not None:
+            element_config["intermediate_frequency"] = self.intermediate_frequency
+
+        filter_fir_taps = self.filter_fir_taps
+        if filter_fir_taps is not None:
+            filter_fir_taps = list(filter_fir_taps)
+        filter_iir_taps = self.filter_iir_taps
+        if filter_iir_taps is not None:
+            filter_iir_taps = list(filter_iir_taps)
+
+        if isinstance(self.opx_output, LFAnalogOutputPort):
+            opx_port = self.opx_output
+        elif len(self.opx_output) == 2:
+            opx_port = OPXPlusAnalogOutputPort(
+                *self.opx_output,
+                offset=self.opx_output_offset,
+                feedforward_filter=filter_fir_taps,
+                feedback_filter=filter_iir_taps,
+            )
+            opx_port.apply_to_config(config)
+        else:
+            opx_port = LFFEMAnalogOutputPort(
+                *self.opx_output,
+                offset=self.opx_output_offset,
+                feedforward_filter=filter_fir_taps,
+                feedback_filter=filter_iir_taps,
+            )
+            opx_port.apply_to_config(config)
+
+        element_config["singleInput"] = {"port": opx_port.port_tuple}
+
+
+ + + +
+ + + + + + + + + +
+ + +

+ apply_to_config(config) + +

+ + +
+ +

Adds this SingleChannel to the QUA configuration.

+

See QuamComponent.apply_to_config +for details.

+ +
+ Source code in quam/components/channels.py + 
499
+500
+501
+502
+503
+504
+505
+506
+507
+508
+509
+510
+511
+512
+513
+514
+515
+516
+517
+518
+519
+520
+521
+522
+523
+524
+525
+526
+527
+528
+529
+530
+531
+532
+533
+534
+535
+536
+537
+538
+539
+540
+541
+542
+543
+544
+545
+546
+547
def apply_to_config(self, config: dict):
+    """Adds this SingleChannel to the QUA configuration.
+
+    See [`QuamComponent.apply_to_config`][quam.core.quam_classes.QuamComponent.apply_to_config]
+    for details.
+    """
+    # Add pulses & waveforms
+    super().apply_to_config(config)
+
+    if str_ref.is_reference(self.name):
+        raise AttributeError(
+            f"Channel {self.get_reference()} cannot be added to the config because"
+            " it doesn't have a name. Either set channel.id to a string or"
+            " integer, or channel should be an attribute of another QuAM component"
+            " with a name."
+        )
+
+    element_config = config["elements"][self.name]
+
+    if self.intermediate_frequency is not None:
+        element_config["intermediate_frequency"] = self.intermediate_frequency
+
+    filter_fir_taps = self.filter_fir_taps
+    if filter_fir_taps is not None:
+        filter_fir_taps = list(filter_fir_taps)
+    filter_iir_taps = self.filter_iir_taps
+    if filter_iir_taps is not None:
+        filter_iir_taps = list(filter_iir_taps)
+
+    if isinstance(self.opx_output, LFAnalogOutputPort):
+        opx_port = self.opx_output
+    elif len(self.opx_output) == 2:
+        opx_port = OPXPlusAnalogOutputPort(
+            *self.opx_output,
+            offset=self.opx_output_offset,
+            feedforward_filter=filter_fir_taps,
+            feedback_filter=filter_iir_taps,
+        )
+        opx_port.apply_to_config(config)
+    else:
+        opx_port = LFFEMAnalogOutputPort(
+            *self.opx_output,
+            offset=self.opx_output_offset,
+            feedforward_filter=filter_fir_taps,
+            feedback_filter=filter_iir_taps,
+        )
+        opx_port.apply_to_config(config)
+
+    element_config["singleInput"] = {"port": opx_port.port_tuple}
+
+
+
+ +
+ +
+ + +

+ set_dc_offset(offset) + +

+ + +
+ +

Set the DC offset of an element's input to the given value. +This value will remain the DC offset until changed or until the Quantum Machine +is closed.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
offset + QuaNumberType + +
+

The DC offset to set the input to. +This is limited by the OPX output voltage range. +The number can be a QUA variable

+
+ 		+ required +
+ +
+ Source code in quam/components/channels.py + 
487
+488
+489
+490
+491
+492
+493
+494
+495
+496
+497
def set_dc_offset(self, offset: QuaNumberType):
+    """Set the DC offset of an element's input to the given value.
+    This value will remain the DC offset until changed or until the Quantum Machine
+    is closed.
+
+    Args:
+        offset (QuaNumberType): The DC offset to set the input to.
+            This is limited by the OPX output voltage range.
+            The number can be a QUA variable
+    """
+    set_dc_offset(element=self.name, element_input="single", offset=offset)
+
+
+
+ +
+ + + +
+ +
+ +
+ + + + +
+ +
+ +
+ + + + + + + + + + + + + +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API_references/components/channels_API/index.html b/API_references/components/channels_API/index.html new file mode 100644 index 00000000..b651f812 --- /dev/null +++ b/API_references/components/channels_API/index.html @@ -0,0 +1,9794 @@ + + + + + + + + + + + + + + + + + + + + + + + + + QuAM Channels API - The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ + + + +

QuAM Channels API

+ + +
+ + + + +
+ + + +
+ + + + + + + + +
+ + + +

+ Channel + + +

+ + +
+

+ Bases: QuamComponent

+ + +

Base QuAM component for a channel, can be output, input or both.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
operations + Dict[str, Pulse] + +
+

A dictionary of pulses to be played on this +channel. The key is the pulse label (e.g. "X90") and value is a Pulse.

+
+ 		+ required +
id + (str, int) + +
+

The id of the channel, used to generate the name. +Can be a string, or an integer in which case it will add +Channel._default_label.

+
+ 		+ required +
+ +
+ Source code in quam/components/channels.py + 
155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
+182
+183
+184
+185
+186
+187
+188
+189
+190
+191
+192
+193
+194
+195
+196
+197
+198
+199
+200
+201
+202
+203
+204
+205
+206
+207
+208
+209
+210
+211
+212
+213
+214
+215
+216
+217
+218
+219
+220
+221
+222
+223
+224
+225
+226
+227
+228
+229
+230
+231
+232
+233
+234
+235
+236
+237
+238
+239
+240
+241
+242
+243
+244
+245
+246
+247
+248
+249
+250
+251
+252
+253
+254
+255
+256
+257
+258
+259
+260
+261
+262
+263
+264
+265
+266
+267
+268
+269
+270
+271
+272
+273
+274
+275
+276
+277
+278
+279
+280
+281
+282
+283
+284
+285
+286
+287
+288
+289
+290
+291
+292
+293
+294
+295
+296
+297
+298
+299
+300
+301
+302
+303
+304
+305
+306
+307
+308
+309
+310
+311
+312
+313
+314
+315
+316
+317
+318
+319
+320
+321
+322
+323
+324
+325
+326
+327
+328
+329
+330
+331
+332
+333
+334
+335
+336
+337
+338
+339
+340
+341
+342
+343
+344
+345
+346
+347
+348
+349
+350
+351
+352
+353
+354
+355
+356
+357
+358
+359
+360
+361
+362
+363
+364
+365
+366
+367
+368
+369
+370
+371
+372
+373
+374
+375
+376
+377
+378
+379
+380
+381
+382
+383
+384
+385
+386
+387
+388
+389
+390
+391
+392
+393
+394
+395
+396
+397
+398
+399
+400
+401
+402
+403
+404
+405
+406
+407
+408
+409
+410
+411
+412
+413
+414
+415
+416
+417
+418
+419
+420
+421
+422
+423
+424
+425
+426
+427
+428
+429
+430
+431
+432
+433
+434
+435
+436
+437
+438
+439
+440
+441
+442
+443
+444
+445
+446
+447
+448
+449
+450
+451
+452
+453
+454
+455
+456
+457
+458
@quam_dataclass
+class Channel(QuamComponent):
+    """Base QuAM component for a channel, can be output, input or both.
+
+    Args:
+        operations (Dict[str, Pulse]): A dictionary of pulses to be played on this
+            channel. The key is the pulse label (e.g. "X90") and value is a Pulse.
+        id (str, int): The id of the channel, used to generate the name.
+            Can be a string, or an integer in which case it will add
+            `Channel._default_label`.
+    """
+
+    operations: Dict[str, Pulse] = field(default_factory=dict)
+
+    id: Union[str, int] = None
+    _default_label: ClassVar[str] = "ch"  # Used to determine name from id
+
+    digital_outputs: Dict[str, DigitalOutputChannel] = field(default_factory=dict)
+
+    @property
+    def name(self) -> str:
+        cls_name = self.__class__.__name__
+
+        if self.id is not None:
+            if str_ref.is_reference(self.id):
+                raise AttributeError(
+                    f"{cls_name}.name cannot be determined. "
+                    f"Please either set {cls_name}.id to a string or integer, "
+                    f"or {cls_name} should be an attribute of another QuAM component."
+                )
+            if isinstance(self.id, str):
+                return self.id
+            else:
+                return f"{self._default_label}{self.id}"
+        if self.parent is None:
+            raise AttributeError(
+                f"{cls_name}.name cannot be determined. "
+                f"Please either set {cls_name}.id to a string or integer, "
+                f"or {cls_name} should be an attribute of another QuAM component with "
+                "a name."
+            )
+        if isinstance(self.parent, QuamDict):
+            return self.parent.get_attr_name(self)
+        if not hasattr(self.parent, "name"):
+            raise AttributeError(
+                f"{cls_name}.name cannot be determined. "
+                f"Please either set {cls_name}.id to a string or integer, "
+                f"or {cls_name} should be an attribute of another QuAM component with "
+                "a name."
+            )
+        return f"{self.parent.name}{str_ref.DELIMITER}{self.parent.get_attr_name(self)}"
+
+    @property
+    def pulse_mapping(self):
+        return {label: pulse.pulse_name for label, pulse in self.operations.items()}
+
+    def play(
+        self,
+        pulse_name: str,
+        amplitude_scale: Union[float, AmpValuesType] = None,
+        duration: QuaNumberType = None,
+        condition: QuaExpressionType = None,
+        chirp: ChirpType = None,
+        truncate: QuaNumberType = None,
+        timestamp_stream: StreamType = None,
+        continue_chirp: bool = False,
+        target: str = "",
+        validate: bool = True,
+    ):
+        """Play a pulse on this channel.
+
+        Args:
+            pulse_name (str): The name of the pulse to play. Should be registered in
+                `self.operations`.
+            amplitude_scale (float, _PulseAmp): Amplitude scale of the pulse.
+                Can be either a float, or qua.amp(float).
+            duration (int): Duration of the pulse in units of the clock cycle (4ns).
+                If not provided, the default pulse duration will be used. It is possible
+                to dynamically change the duration of both constant and arbitrary
+                pulses. Arbitrary pulses can only be stretched, not compressed.
+            chirp (Union[(list[int], str), (int, str)]): Allows to perform
+                piecewise linear sweep of the element's intermediate
+                frequency in time. Input should be a tuple, with the 1st
+                element being a list of rates and the second should be a
+                string with the units. The units can be either: 'Hz/nsec',
+                'mHz/nsec', 'uHz/nsec', 'pHz/nsec' or 'GHz/sec', 'MHz/sec',
+                'KHz/sec', 'Hz/sec', 'mHz/sec'.
+            truncate (Union[int, QUA variable of type int]): Allows playing
+                only part of the pulse, truncating the end. If provided,
+                will play only up to the given time in units of the clock
+                cycle (4ns).
+            condition (A logical expression to evaluate.): Will play analog
+                pulse only if the condition's value is true. Any digital
+                pulses associated with the operation will always play.
+            timestamp_stream (Union[str, _ResultSource]): (Supported from
+                QOP 2.2) Adding a `timestamp_stream` argument will save the
+                time at which the operation occurred to a stream. If the
+                `timestamp_stream` is a string ``label``, then the timestamp
+                handle can be retrieved with
+                `qm._results.JobResults.get` with the same ``label``.
+            validate (bool): If True (default), validate that the pulse is registered
+                in Channel.operations
+
+        Note:
+            The `element` argument from `qm.qua.play()`is not needed, as it is
+            automatically set to `self.name`.
+
+        """
+        if validate and pulse_name not in self.operations:
+            raise KeyError(
+                f"Operation '{pulse_name}' not found in channel '{self.name}'"
+            )
+
+        if amplitude_scale is not None:
+            if not isinstance(amplitude_scale, _PulseAmp):
+                amplitude_scale = amp(amplitude_scale)
+            pulse = pulse_name * amplitude_scale
+        else:
+            pulse = pulse_name
+
+        # At the moment, self.name is not defined for Channel because it could
+        # be a property or dataclass field in a subclass.
+        # # TODO Find elegant solution for Channel.name.
+        play(
+            pulse=pulse,
+            element=self.name,
+            duration=duration,
+            condition=condition,
+            chirp=chirp,
+            truncate=truncate,
+            timestamp_stream=timestamp_stream,
+            continue_chirp=continue_chirp,
+            target=target,
+        )
+
+    def wait(self, duration: QuaNumberType, *other_elements: Union[str, "Channel"]):
+        """Wait for the given duration on all provided elements without outputting anything.
+
+        Duration is in units of the clock cycle (4ns)
+
+        Args:
+            duration (Union[int,QUA variable of type int]): time to wait in
+                units of the clock cycle (4ns). Range: [4, $2^{31}-1$]
+                in steps of 1.
+            *other_elements (Union[str,sequence of str]): elements to wait on,
+                in addition to this channel
+
+        Warning:
+            In case the value of this is outside the range above, unexpected results may occur.
+
+        Note:
+            The current channel element is always included in the wait operation.
+
+        Note:
+            The purpose of the `wait` operation is to add latency. In most cases, the
+            latency added will be exactly the same as that specified by the QUA variable or
+            the literal used. However, in some cases an additional computational latency may
+            be added. If the actual wait time has significance, such as in characterization
+            experiments, the actual wait time should always be verified with a simulator.
+        """
+        other_elements_str = [
+            element if isinstance(element, str) else str(element)
+            for element in other_elements
+        ]
+        wait(duration, self.name, *other_elements_str)
+
+    def align(self, *other_elements):
+        if not other_elements:
+            align()
+        else:
+            other_elements_str = [
+                element if isinstance(element, str) else str(element)
+                for element in other_elements
+            ]
+            align(self.name, *other_elements_str)
+
+    def update_frequency(
+        self,
+        new_frequency: QuaNumberType,
+        units: str = "Hz",
+        keep_phase: bool = False,
+    ):
+        """Dynamically update the frequency of the associated oscillator.
+
+        This changes the frequency from the value defined in the channel.
+
+        The behavior of the phase (continuous vs. coherent) is controlled by the
+        ``keep_phase`` parameter and is discussed in the documentation.
+
+        Args:
+            new_frequency (int): The new frequency value to set in units set
+                by ``units`` parameter. In steps of 1.
+            units (str): units of new frequency. Useful when sub-Hz
+                precision is required. Allowed units are "Hz", "mHz", "uHz",
+                "nHz", "pHz"
+            keep_phase (bool): Determine whether phase will be continuous
+                through the change (if ``True``) or it will be coherent,
+                only the frequency will change (if ``False``).
+
+        Example:
+            ```python
+            with program() as prog:
+                update_frequency("q1", 4e6) # will set the frequency to 4 MHz
+
+                ### Example for sub-Hz resolution
+                # will set the frequency to 100 Hz (due to casting to int)
+                update_frequency("q1", 100.7)
+
+                # will set the frequency to 100.7 Hz
+                update_frequency("q1", 100700, units='mHz')
+            ```
+        """
+        update_frequency(self.name, new_frequency, units, keep_phase)
+
+    def frame_rotation(self, angle: QuaNumberType):
+        r"""Shift the phase of the channel element's oscillator by the given angle.
+
+        This is typically used for virtual z-rotations.
+
+        Note:
+            The fixed point format of QUA variables of type fixed is 4.28, meaning the
+            phase must be between $-8$ and $8-2^{28}$. Otherwise the phase value will be
+            invalid. It is therefore better to use `frame_rotation_2pi()` which avoids
+            this issue.
+
+        Note:
+            The phase is accumulated with a resolution of 16 bit.
+            Therefore, *N* changes to the phase can result in a phase (and amplitude)
+            inaccuracy of about :math:`N \cdot 2^{-16}`. To null out this accumulated
+            error, it is recommended to use `reset_frame(el)` from time to time.
+
+        Args:
+            angle (Union[float, QUA variable of type fixed]): The angle to
+                add to the current phase (in radians)
+            *elements (str): a single element whose oscillator's phase will
+                be shifted. multiple elements can be given, in which case
+                all of their oscillators' phases will be shifted
+
+        """
+        frame_rotation(angle, self.name)
+
+    def frame_rotation_2pi(self, angle: QuaNumberType):
+        r"""Shift the phase of the oscillator associated with an element by the given
+        angle in units of 2pi radians.
+
+        This is typically used for virtual z-rotations.
+
+        Note:
+            Unlike the case of frame_rotation(), this method performs the 2-pi radian
+            wrap around of the angle automatically.
+
+        Note:
+            The phase is accumulated with a resolution of 16 bit.
+            Therefore, *N* changes to the phase can result in a phase inaccuracy of
+            about :math:`N \cdot 2^{-16}`. To null out this accumulated error, it is
+            recommended to use `reset_frame(el)` from time to time.
+
+        Args:
+            angle (Union[float,QUA variable of type real]): The angle to add
+                to the current phase (in $2\pi$ radians)
+        """
+        frame_rotation_2pi(angle, self.name)
+
+    def _config_add_digital_outputs(self, config: Dict[str, dict]) -> None:
+        """Adds the digital outputs to the QUA config.
+
+        config.elements.<element_name>.digitalInputs will be updated with the digital
+        outputs of this channel.
+
+        Note that the digital outputs are added separately to the controller config in
+        `DigitalOutputChannel.apply_to_config`.
+
+        Args:
+            config (dict): The QUA config that's in the process of being generated.
+        """
+        if not self.digital_outputs:
+            return
+
+        element_cfg = config["elements"][self.name]
+        element_cfg.setdefault("digitalInputs", {})
+
+        for name, digital_output in self.digital_outputs.items():
+            digital_cfg = digital_output.generate_element_config()
+            element_cfg["digitalInputs"][name] = digital_cfg
+
+    def apply_to_config(self, config: Dict[str, dict]) -> None:
+        """Adds this Channel to the QUA configuration.
+
+        config.elements.<element_name> will be created, and the operations are added.
+
+        Args:
+            config (dict): The QUA config that's in the process of being generated.
+
+        Raises:
+            ValueError: If the channel already exists in the config.
+        """
+        if self.name in config["elements"]:
+            raise ValueError(
+                f"Cannot add channel '{self.name}' to the config because it already "
+                f"exists. Existing entry: {config['elements'][self.name]}"
+            )
+        config["elements"][self.name] = {"operations": self.pulse_mapping}
+
+        self._config_add_digital_outputs(config)
+
+
+ + + +
+ + + + + + + + + +
+ + +

+ apply_to_config(config) + +

+ + +
+ +

Adds this Channel to the QUA configuration.

+

config.elements. will be created, and the operations are added.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
config + dict + +
+

The QUA config that's in the process of being generated.

+
+ 		+ required +
+ + +

Raises:

+ + + + + + + + + + + + + +
TypeDescription
+ ValueError + +
+

If the channel already exists in the config.

+
+
+ +
+ Source code in quam/components/channels.py + 
440
+441
+442
+443
+444
+445
+446
+447
+448
+449
+450
+451
+452
+453
+454
+455
+456
+457
+458
def apply_to_config(self, config: Dict[str, dict]) -> None:
+    """Adds this Channel to the QUA configuration.
+
+    config.elements.<element_name> will be created, and the operations are added.
+
+    Args:
+        config (dict): The QUA config that's in the process of being generated.
+
+    Raises:
+        ValueError: If the channel already exists in the config.
+    """
+    if self.name in config["elements"]:
+        raise ValueError(
+            f"Cannot add channel '{self.name}' to the config because it already "
+            f"exists. Existing entry: {config['elements'][self.name]}"
+        )
+    config["elements"][self.name] = {"operations": self.pulse_mapping}
+
+    self._config_add_digital_outputs(config)
+
+
+
+ +
+ +
+ + +

+ frame_rotation(angle) + +

+ + +
+ +

Shift the phase of the channel element's oscillator by the given angle.

+

This is typically used for virtual z-rotations.

+ + +
+ Note +

The fixed point format of QUA variables of type fixed is 4.28, meaning the +phase must be between $-8$ and $8-2^{28}$. Otherwise the phase value will be +invalid. It is therefore better to use frame_rotation_2pi() which avoids +this issue.

+
+ +
+ Note +

The phase is accumulated with a resolution of 16 bit. +Therefore, N changes to the phase can result in a phase (and amplitude) +inaccuracy of about :math:N \cdot 2^{-16}. To null out this accumulated +error, it is recommended to use reset_frame(el) from time to time.

+
+ +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
angle + Union[float, QUA variable of type fixed] + +
+

The angle to +add to the current phase (in radians)

+
+ 		+ required +
*elements + str + +
+

a single element whose oscillator's phase will +be shifted. multiple elements can be given, in which case +all of their oscillators' phases will be shifted

+
+ 		+ required +
+ +
+ Source code in quam/components/channels.py + 
369
+370
+371
+372
+373
+374
+375
+376
+377
+378
+379
+380
+381
+382
+383
+384
+385
+386
+387
+388
+389
+390
+391
+392
+393
+394
def frame_rotation(self, angle: QuaNumberType):
+    r"""Shift the phase of the channel element's oscillator by the given angle.
+
+    This is typically used for virtual z-rotations.
+
+    Note:
+        The fixed point format of QUA variables of type fixed is 4.28, meaning the
+        phase must be between $-8$ and $8-2^{28}$. Otherwise the phase value will be
+        invalid. It is therefore better to use `frame_rotation_2pi()` which avoids
+        this issue.
+
+    Note:
+        The phase is accumulated with a resolution of 16 bit.
+        Therefore, *N* changes to the phase can result in a phase (and amplitude)
+        inaccuracy of about :math:`N \cdot 2^{-16}`. To null out this accumulated
+        error, it is recommended to use `reset_frame(el)` from time to time.
+
+    Args:
+        angle (Union[float, QUA variable of type fixed]): The angle to
+            add to the current phase (in radians)
+        *elements (str): a single element whose oscillator's phase will
+            be shifted. multiple elements can be given, in which case
+            all of their oscillators' phases will be shifted
+
+    """
+    frame_rotation(angle, self.name)
+
+
+
+ +
+ +
+ + +

+ frame_rotation_2pi(angle) + +

+ + +
+ +

Shift the phase of the oscillator associated with an element by the given +angle in units of 2pi radians.

+

This is typically used for virtual z-rotations.

+ + +
+ Note +

Unlike the case of frame_rotation(), this method performs the 2-pi radian +wrap around of the angle automatically.

+
+ +
+ Note +

The phase is accumulated with a resolution of 16 bit. +Therefore, N changes to the phase can result in a phase inaccuracy of +about :math:N \cdot 2^{-16}. To null out this accumulated error, it is +recommended to use reset_frame(el) from time to time.

+
+ +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
angle + Union[float,QUA variable of type real] + +
+

The angle to add +to the current phase (in $2\pi$ radians)

+
+ 		+ required +
+ +
+ Source code in quam/components/channels.py + 
396
+397
+398
+399
+400
+401
+402
+403
+404
+405
+406
+407
+408
+409
+410
+411
+412
+413
+414
+415
+416
def frame_rotation_2pi(self, angle: QuaNumberType):
+    r"""Shift the phase of the oscillator associated with an element by the given
+    angle in units of 2pi radians.
+
+    This is typically used for virtual z-rotations.
+
+    Note:
+        Unlike the case of frame_rotation(), this method performs the 2-pi radian
+        wrap around of the angle automatically.
+
+    Note:
+        The phase is accumulated with a resolution of 16 bit.
+        Therefore, *N* changes to the phase can result in a phase inaccuracy of
+        about :math:`N \cdot 2^{-16}`. To null out this accumulated error, it is
+        recommended to use `reset_frame(el)` from time to time.
+
+    Args:
+        angle (Union[float,QUA variable of type real]): The angle to add
+            to the current phase (in $2\pi$ radians)
+    """
+    frame_rotation_2pi(angle, self.name)
+
+
+
+ +
+ +
+ + +

+ play(pulse_name, amplitude_scale=None, duration=None, condition=None, chirp=None, truncate=None, timestamp_stream=None, continue_chirp=False, target='', validate=True) + +

+ + +
+ +

Play a pulse on this channel.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
pulse_name + str + +
+

The name of the pulse to play. Should be registered in +self.operations.

+
+ 		+ required +
amplitude_scale + (float, _PulseAmp) + +
+

Amplitude scale of the pulse. +Can be either a float, or qua.amp(float).

+
+ 		+ None +
duration + int + +
+

Duration of the pulse in units of the clock cycle (4ns). +If not provided, the default pulse duration will be used. It is possible +to dynamically change the duration of both constant and arbitrary +pulses. Arbitrary pulses can only be stretched, not compressed.

+
+ 		+ None +
chirp + Union[(list[int], str), (int, str)] + +
+

Allows to perform +piecewise linear sweep of the element's intermediate +frequency in time. Input should be a tuple, with the 1st +element being a list of rates and the second should be a +string with the units. The units can be either: 'Hz/nsec', +'mHz/nsec', 'uHz/nsec', 'pHz/nsec' or 'GHz/sec', 'MHz/sec', +'KHz/sec', 'Hz/sec', 'mHz/sec'.

+
+ 		+ None +
truncate + Union[int, QUA variable of type int] + +
+

Allows playing +only part of the pulse, truncating the end. If provided, +will play only up to the given time in units of the clock +cycle (4ns).

+
+ 		+ None +
condition + A logical expression to evaluate. + +
+

Will play analog +pulse only if the condition's value is true. Any digital +pulses associated with the operation will always play.

+
+ 		+ None +
timestamp_stream + Union[str, _ResultSource] + +
+

(Supported from +QOP 2.2) Adding a timestamp_stream argument will save the +time at which the operation occurred to a stream. If the +timestamp_stream is a string label, then the timestamp +handle can be retrieved with +qm._results.JobResults.get with the same label.

+
+ 		+ None +
validate + bool + +
+

If True (default), validate that the pulse is registered +in Channel.operations

+
+ 		+ True +
+ + +
+ Note +

The element argument from qm.qua.play()is not needed, as it is +automatically set to self.name.

+
+
+ Source code in quam/components/channels.py + 
211
+212
+213
+214
+215
+216
+217
+218
+219
+220
+221
+222
+223
+224
+225
+226
+227
+228
+229
+230
+231
+232
+233
+234
+235
+236
+237
+238
+239
+240
+241
+242
+243
+244
+245
+246
+247
+248
+249
+250
+251
+252
+253
+254
+255
+256
+257
+258
+259
+260
+261
+262
+263
+264
+265
+266
+267
+268
+269
+270
+271
+272
+273
+274
+275
+276
+277
+278
+279
+280
+281
+282
+283
+284
+285
+286
+287
+288
def play(
+    self,
+    pulse_name: str,
+    amplitude_scale: Union[float, AmpValuesType] = None,
+    duration: QuaNumberType = None,
+    condition: QuaExpressionType = None,
+    chirp: ChirpType = None,
+    truncate: QuaNumberType = None,
+    timestamp_stream: StreamType = None,
+    continue_chirp: bool = False,
+    target: str = "",
+    validate: bool = True,
+):
+    """Play a pulse on this channel.
+
+    Args:
+        pulse_name (str): The name of the pulse to play. Should be registered in
+            `self.operations`.
+        amplitude_scale (float, _PulseAmp): Amplitude scale of the pulse.
+            Can be either a float, or qua.amp(float).
+        duration (int): Duration of the pulse in units of the clock cycle (4ns).
+            If not provided, the default pulse duration will be used. It is possible
+            to dynamically change the duration of both constant and arbitrary
+            pulses. Arbitrary pulses can only be stretched, not compressed.
+        chirp (Union[(list[int], str), (int, str)]): Allows to perform
+            piecewise linear sweep of the element's intermediate
+            frequency in time. Input should be a tuple, with the 1st
+            element being a list of rates and the second should be a
+            string with the units. The units can be either: 'Hz/nsec',
+            'mHz/nsec', 'uHz/nsec', 'pHz/nsec' or 'GHz/sec', 'MHz/sec',
+            'KHz/sec', 'Hz/sec', 'mHz/sec'.
+        truncate (Union[int, QUA variable of type int]): Allows playing
+            only part of the pulse, truncating the end. If provided,
+            will play only up to the given time in units of the clock
+            cycle (4ns).
+        condition (A logical expression to evaluate.): Will play analog
+            pulse only if the condition's value is true. Any digital
+            pulses associated with the operation will always play.
+        timestamp_stream (Union[str, _ResultSource]): (Supported from
+            QOP 2.2) Adding a `timestamp_stream` argument will save the
+            time at which the operation occurred to a stream. If the
+            `timestamp_stream` is a string ``label``, then the timestamp
+            handle can be retrieved with
+            `qm._results.JobResults.get` with the same ``label``.
+        validate (bool): If True (default), validate that the pulse is registered
+            in Channel.operations
+
+    Note:
+        The `element` argument from `qm.qua.play()`is not needed, as it is
+        automatically set to `self.name`.
+
+    """
+    if validate and pulse_name not in self.operations:
+        raise KeyError(
+            f"Operation '{pulse_name}' not found in channel '{self.name}'"
+        )
+
+    if amplitude_scale is not None:
+        if not isinstance(amplitude_scale, _PulseAmp):
+            amplitude_scale = amp(amplitude_scale)
+        pulse = pulse_name * amplitude_scale
+    else:
+        pulse = pulse_name
+
+    # At the moment, self.name is not defined for Channel because it could
+    # be a property or dataclass field in a subclass.
+    # # TODO Find elegant solution for Channel.name.
+    play(
+        pulse=pulse,
+        element=self.name,
+        duration=duration,
+        condition=condition,
+        chirp=chirp,
+        truncate=truncate,
+        timestamp_stream=timestamp_stream,
+        continue_chirp=continue_chirp,
+        target=target,
+    )
+
+
+
+ +
+ +
+ + +

+ update_frequency(new_frequency, units='Hz', keep_phase=False) + +

+ + +
+ +

Dynamically update the frequency of the associated oscillator.

+

This changes the frequency from the value defined in the channel.

+

The behavior of the phase (continuous vs. coherent) is controlled by the +keep_phase parameter and is discussed in the documentation.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
new_frequency + int + +
+

The new frequency value to set in units set +by units parameter. In steps of 1.

+
+ 		+ required +
units + str + +
+

units of new frequency. Useful when sub-Hz +precision is required. Allowed units are "Hz", "mHz", "uHz", +"nHz", "pHz"

+
+ 		+ 'Hz' +
keep_phase + bool + +
+

Determine whether phase will be continuous +through the change (if True) or it will be coherent, +only the frequency will change (if False).

+
+ 		+ False +
+ + +
+ Example + 
with program() as prog:
+    update_frequency("q1", 4e6) # will set the frequency to 4 MHz
+
+    ### Example for sub-Hz resolution
+    # will set the frequency to 100 Hz (due to casting to int)
+    update_frequency("q1", 100.7)
+
+    # will set the frequency to 100.7 Hz
+    update_frequency("q1", 100700, units='mHz')
+
+
+
+ Source code in quam/components/channels.py + 
331
+332
+333
+334
+335
+336
+337
+338
+339
+340
+341
+342
+343
+344
+345
+346
+347
+348
+349
+350
+351
+352
+353
+354
+355
+356
+357
+358
+359
+360
+361
+362
+363
+364
+365
+366
+367
def update_frequency(
+    self,
+    new_frequency: QuaNumberType,
+    units: str = "Hz",
+    keep_phase: bool = False,
+):
+    """Dynamically update the frequency of the associated oscillator.
+
+    This changes the frequency from the value defined in the channel.
+
+    The behavior of the phase (continuous vs. coherent) is controlled by the
+    ``keep_phase`` parameter and is discussed in the documentation.
+
+    Args:
+        new_frequency (int): The new frequency value to set in units set
+            by ``units`` parameter. In steps of 1.
+        units (str): units of new frequency. Useful when sub-Hz
+            precision is required. Allowed units are "Hz", "mHz", "uHz",
+            "nHz", "pHz"
+        keep_phase (bool): Determine whether phase will be continuous
+            through the change (if ``True``) or it will be coherent,
+            only the frequency will change (if ``False``).
+
+    Example:
+        ```python
+        with program() as prog:
+            update_frequency("q1", 4e6) # will set the frequency to 4 MHz
+
+            ### Example for sub-Hz resolution
+            # will set the frequency to 100 Hz (due to casting to int)
+            update_frequency("q1", 100.7)
+
+            # will set the frequency to 100.7 Hz
+            update_frequency("q1", 100700, units='mHz')
+        ```
+    """
+    update_frequency(self.name, new_frequency, units, keep_phase)
+
+
+
+ +
+ +
+ + +

+ wait(duration, *other_elements) + +

+ + +
+ +

Wait for the given duration on all provided elements without outputting anything.

+

Duration is in units of the clock cycle (4ns)

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
duration + Union[int,QUA variable of type int] + +
+

time to wait in +units of the clock cycle (4ns). Range: [4, $2^{31}-1$] +in steps of 1.

+
+ 		+ required +
*other_elements + Union[str,sequence of str] + +
+

elements to wait on, +in addition to this channel

+
+ 		+ () +
+ + +
+ Warning +

In case the value of this is outside the range above, unexpected results may occur.

+
+ +
+ Note +

The current channel element is always included in the wait operation.

+
+ +
+ Note +

The purpose of the wait operation is to add latency. In most cases, the +latency added will be exactly the same as that specified by the QUA variable or +the literal used. However, in some cases an additional computational latency may +be added. If the actual wait time has significance, such as in characterization +experiments, the actual wait time should always be verified with a simulator.

+
+
+ Source code in quam/components/channels.py + 
290
+291
+292
+293
+294
+295
+296
+297
+298
+299
+300
+301
+302
+303
+304
+305
+306
+307
+308
+309
+310
+311
+312
+313
+314
+315
+316
+317
+318
+319
def wait(self, duration: QuaNumberType, *other_elements: Union[str, "Channel"]):
+    """Wait for the given duration on all provided elements without outputting anything.
+
+    Duration is in units of the clock cycle (4ns)
+
+    Args:
+        duration (Union[int,QUA variable of type int]): time to wait in
+            units of the clock cycle (4ns). Range: [4, $2^{31}-1$]
+            in steps of 1.
+        *other_elements (Union[str,sequence of str]): elements to wait on,
+            in addition to this channel
+
+    Warning:
+        In case the value of this is outside the range above, unexpected results may occur.
+
+    Note:
+        The current channel element is always included in the wait operation.
+
+    Note:
+        The purpose of the `wait` operation is to add latency. In most cases, the
+        latency added will be exactly the same as that specified by the QUA variable or
+        the literal used. However, in some cases an additional computational latency may
+        be added. If the actual wait time has significance, such as in characterization
+        experiments, the actual wait time should always be verified with a simulator.
+    """
+    other_elements_str = [
+        element if isinstance(element, str) else str(element)
+        for element in other_elements
+    ]
+    wait(duration, self.name, *other_elements_str)
+
+
+
+ +
+ + + +
+ +
+ +
+ +
+ + + +

+ DigitalOutputChannel + + +

+ + +
+

+ Bases: QuamComponent

+ + +

QuAM component for a digital output channel (signal going out of the OPX)

+

Should be added to Channel.digital_outputs so that it's also added to the +respective element in the QUA config.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
opx_output + Tuple[str, int] + +
+

Channel output port from the OPX perspective, +E.g. ("con1", 1)

+
+ 		+ required +
delay + int + +
+

Delay in nanoseconds. An intrinsic negative delay of +136 ns exists by default.

+
+ 		+ required +
buffer + int + +
+

Digital pulses played to this element will be convolved +with a digital pulse of value 1 with this length [ns].

+
+ 		+ required +
shareable + bool + +
+

If True, the digital output can be shared with other +QM instances. Default is False

+
+ 		+ required +
inverted + bool + +
+

If True, the digital output is inverted. +Default is False.

+
+ 		+ required +
+

.

+ +
+ Source code in quam/components/channels.py + 
 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
@quam_dataclass
+class DigitalOutputChannel(QuamComponent):
+    """QuAM component for a digital output channel (signal going out of the OPX)
+
+    Should be added to `Channel.digital_outputs` so that it's also added to the
+    respective element in the QUA config.
+
+    Args:
+        opx_output (Tuple[str, int]): Channel output port from the OPX perspective,
+            E.g. ("con1", 1)
+        delay (int, optional): Delay in nanoseconds. An intrinsic negative delay of
+            136 ns exists by default.
+        buffer (int, optional): Digital pulses played to this element will be convolved
+            with a digital pulse of value 1 with this length [ns].
+        shareable (bool, optional): If True, the digital output can be shared with other
+            QM instances. Default is False
+        inverted (bool, optional): If True, the digital output is inverted.
+            Default is False.
+    ."""
+
+    opx_output: Union[Tuple[str, int], Tuple[str, int, int], DigitalOutputPort]
+    delay: int = None
+    buffer: int = None
+
+    shareable: bool = None
+    inverted: bool = None
+
+    def generate_element_config(self) -> Dict[str, int]:
+        """Generates the config entry for a digital channel in the QUA config.
+
+        This config entry goes into:
+        config.elements.<element_name>.digitalInputs.<opx_output[1]>
+
+        Returns:
+            Dict[str, int]: The digital channel config entry.
+                Contains "port", and optionally "delay", "buffer" if specified
+        """
+        if isinstance(self.opx_output, DigitalOutputPort):
+            opx_output = self.opx_output.port_tuple
+        else:
+            opx_output = tuple(self.opx_output)
+
+        digital_cfg: Dict[str, Any] = {"port": opx_output}
+        if self.delay is not None:
+            digital_cfg["delay"] = self.delay
+        if self.buffer is not None:
+            digital_cfg["buffer"] = self.buffer
+        return digital_cfg
+
+    def apply_to_config(self, config: dict) -> None:
+        """Adds this DigitalOutputChannel to the QUA configuration.
+
+        config.controllers.<controller_name>.digital_outputs.<port> will be updated
+        with the shareable and inverted settings of this channel if specified.
+
+        See [`QuamComponent.apply_to_config`][quam.core.quam_classes.QuamComponent.apply_to_config]
+        for details.
+        """
+        if isinstance(self.opx_output, DigitalOutputPort):
+            if self.shareable is not None:
+                warnings.warn(
+                    f"Property {self.name}.shareable (={self.shareable}) is ignored "
+                    "because it should be set in {self.name}.opx_output.shareable"
+                )
+            if self.inverted is not None:
+                warnings.warn(
+                    f"Property {self.name}.inverted (={self.inverted}) is ignored "
+                    "because it should be set in {self.name}.opx_output.inverted"
+                )
+            return
+
+        shareable = self.shareable if self.shareable is not None else False
+        inverted = self.inverted if self.inverted is not None else False
+        if len(self.opx_output) == 2:
+            digital_output_port = OPXPlusDigitalOutputPort(
+                *self.opx_output, shareable=shareable, inverted=inverted
+            )
+        else:
+            digital_output_port = FEMDigitalOutputPort(
+                *self.opx_output, shareable=shareable, inverted=inverted
+            )
+        digital_output_port.apply_to_config(config)
+
+
+ + + +
+ + + + + + + + + +
+ + +

+ apply_to_config(config) + +

+ + +
+ +

Adds this DigitalOutputChannel to the QUA configuration.

+

config.controllers..digital_outputs. will be updated +with the shareable and inverted settings of this channel if specified.

+

See QuamComponent.apply_to_config +for details.

+ +
+ Source code in quam/components/channels.py + 
120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
def apply_to_config(self, config: dict) -> None:
+    """Adds this DigitalOutputChannel to the QUA configuration.
+
+    config.controllers.<controller_name>.digital_outputs.<port> will be updated
+    with the shareable and inverted settings of this channel if specified.
+
+    See [`QuamComponent.apply_to_config`][quam.core.quam_classes.QuamComponent.apply_to_config]
+    for details.
+    """
+    if isinstance(self.opx_output, DigitalOutputPort):
+        if self.shareable is not None:
+            warnings.warn(
+                f"Property {self.name}.shareable (={self.shareable}) is ignored "
+                "because it should be set in {self.name}.opx_output.shareable"
+            )
+        if self.inverted is not None:
+            warnings.warn(
+                f"Property {self.name}.inverted (={self.inverted}) is ignored "
+                "because it should be set in {self.name}.opx_output.inverted"
+            )
+        return
+
+    shareable = self.shareable if self.shareable is not None else False
+    inverted = self.inverted if self.inverted is not None else False
+    if len(self.opx_output) == 2:
+        digital_output_port = OPXPlusDigitalOutputPort(
+            *self.opx_output, shareable=shareable, inverted=inverted
+        )
+    else:
+        digital_output_port = FEMDigitalOutputPort(
+            *self.opx_output, shareable=shareable, inverted=inverted
+        )
+    digital_output_port.apply_to_config(config)
+
+
+
+ +
+ +
+ + +

+ generate_element_config() + +

+ + +
+ +

Generates the config entry for a digital channel in the QUA config.

+

This config entry goes into: +config.elements..digitalInputs.

+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ Dict[str, int] + +
+

Dict[str, int]: The digital channel config entry. +Contains "port", and optionally "delay", "buffer" if specified

+
+
+ +
+ Source code in quam/components/channels.py + 
 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
def generate_element_config(self) -> Dict[str, int]:
+    """Generates the config entry for a digital channel in the QUA config.
+
+    This config entry goes into:
+    config.elements.<element_name>.digitalInputs.<opx_output[1]>
+
+    Returns:
+        Dict[str, int]: The digital channel config entry.
+            Contains "port", and optionally "delay", "buffer" if specified
+    """
+    if isinstance(self.opx_output, DigitalOutputPort):
+        opx_output = self.opx_output.port_tuple
+    else:
+        opx_output = tuple(self.opx_output)
+
+    digital_cfg: Dict[str, Any] = {"port": opx_output}
+    if self.delay is not None:
+        digital_cfg["delay"] = self.delay
+    if self.buffer is not None:
+        digital_cfg["buffer"] = self.buffer
+    return digital_cfg
+
+
+
+ +
+ + + +
+ +
+ +
+ +
+ + + +

+ IQChannel + + +

+ + +
+

+ Bases: Channel

+ + +

QuAM component for an IQ output channel.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
operations + Dict[str, Pulse] + +
+

A dictionary of pulses to be played on this +channel. The key is the pulse label (e.g. "X90") and value is a Pulse.

+
+ 		+ required +
id + (str, int) + +
+

The id of the channel, used to generate the name. +Can be a string, or an integer in which case it will add +Channel._default_label.

+
+ 		+ required +
opx_output_I + Tuple[str, int] + +
+

Channel I output port from the OPX perspective, +a tuple of (controller_name, port).

+
+ 		+ required +
opx_output_Q + Tuple[str, int] + +
+

Channel Q output port from the OPX perspective, +a tuple of (controller_name, port).

+
+ 		+ required +
opx_output_offset_I + float + +
+

The offset of the I channel. Default is 0.

+
+ 		+ required +
opx_output_offset_Q + float + +
+

The offset of the Q channel. Default is 0.

+
+ 		+ required +
intermediate_frequency + float + +
+

Intermediate frequency of the mixer. +Default is 0.0

+
+ 		+ required +
LO_frequency + float + +
+

Local oscillator frequency. Default is the LO frequency +of the frequency converter up component.

+
+ 		+ required +
RF_frequency + float + +
+

RF frequency of the mixer. By default, the RF frequency +is inferred by adding the LO frequency and the intermediate frequency.

+
+ 		+ required +
frequency_converter_up + FrequencyConverter + +
+

Frequency converter QuAM component +for the IQ output.

+
+ 		+ required +
+ +
+ Source code in quam/components/channels.py + 
 826
+ 827
+ 828
+ 829
+ 830
+ 831
+ 832
+ 833
+ 834
+ 835
+ 836
+ 837
+ 838
+ 839
+ 840
+ 841
+ 842
+ 843
+ 844
+ 845
+ 846
+ 847
+ 848
+ 849
+ 850
+ 851
+ 852
+ 853
+ 854
+ 855
+ 856
+ 857
+ 858
+ 859
+ 860
+ 861
+ 862
+ 863
+ 864
+ 865
+ 866
+ 867
+ 868
+ 869
+ 870
+ 871
+ 872
+ 873
+ 874
+ 875
+ 876
+ 877
+ 878
+ 879
+ 880
+ 881
+ 882
+ 883
+ 884
+ 885
+ 886
+ 887
+ 888
+ 889
+ 890
+ 891
+ 892
+ 893
+ 894
+ 895
+ 896
+ 897
+ 898
+ 899
+ 900
+ 901
+ 902
+ 903
+ 904
+ 905
+ 906
+ 907
+ 908
+ 909
+ 910
+ 911
+ 912
+ 913
+ 914
+ 915
+ 916
+ 917
+ 918
+ 919
+ 920
+ 921
+ 922
+ 923
+ 924
+ 925
+ 926
+ 927
+ 928
+ 929
+ 930
+ 931
+ 932
+ 933
+ 934
+ 935
+ 936
+ 937
+ 938
+ 939
+ 940
+ 941
+ 942
+ 943
+ 944
+ 945
+ 946
+ 947
+ 948
+ 949
+ 950
+ 951
+ 952
+ 953
+ 954
+ 955
+ 956
+ 957
+ 958
+ 959
+ 960
+ 961
+ 962
+ 963
+ 964
+ 965
+ 966
+ 967
+ 968
+ 969
+ 970
+ 971
+ 972
+ 973
+ 974
+ 975
+ 976
+ 977
+ 978
+ 979
+ 980
+ 981
+ 982
+ 983
+ 984
+ 985
+ 986
+ 987
+ 988
+ 989
+ 990
+ 991
+ 992
+ 993
+ 994
+ 995
+ 996
+ 997
+ 998
+ 999
+1000
+1001
+1002
+1003
+1004
+1005
+1006
+1007
+1008
+1009
+1010
+1011
+1012
+1013
+1014
+1015
+1016
+1017
+1018
+1019
+1020
+1021
+1022
+1023
+1024
+1025
+1026
+1027
+1028
+1029
@quam_dataclass
+class IQChannel(Channel):
+    """QuAM component for an IQ output channel.
+
+    Args:
+        operations (Dict[str, Pulse]): A dictionary of pulses to be played on this
+            channel. The key is the pulse label (e.g. "X90") and value is a Pulse.
+        id (str, int): The id of the channel, used to generate the name.
+            Can be a string, or an integer in which case it will add
+            `Channel._default_label`.
+        opx_output_I (Tuple[str, int]): Channel I output port from the OPX perspective,
+            a tuple of (controller_name, port).
+        opx_output_Q (Tuple[str, int]): Channel Q output port from the OPX perspective,
+            a tuple of (controller_name, port).
+        opx_output_offset_I float: The offset of the I channel. Default is 0.
+        opx_output_offset_Q float: The offset of the Q channel. Default is 0.
+        intermediate_frequency (float): Intermediate frequency of the mixer.
+            Default is 0.0
+        LO_frequency (float): Local oscillator frequency. Default is the LO frequency
+            of the frequency converter up component.
+        RF_frequency (float): RF frequency of the mixer. By default, the RF frequency
+            is inferred by adding the LO frequency and the intermediate frequency.
+        frequency_converter_up (FrequencyConverter): Frequency converter QuAM component
+            for the IQ output.
+    """
+
+    opx_output_I: Union[Tuple[str, int], Tuple[str, int, int], LFAnalogOutputPort]
+    opx_output_Q: Union[Tuple[str, int], Tuple[str, int, int], LFAnalogOutputPort]
+
+    opx_output_offset_I: float = None
+    opx_output_offset_Q: float = None
+
+    frequency_converter_up: BaseFrequencyConverter
+
+    intermediate_frequency: float = 0.0
+    LO_frequency: float = "#./frequency_converter_up/LO_frequency"
+    RF_frequency: float = "#./inferred_RF_frequency"
+
+    _default_label: ClassVar[str] = "IQ"
+
+    @property
+    def inferred_RF_frequency(self) -> float:
+        """Inferred RF frequency by adding LO and IF
+
+        Can be used by having reference `RF_frequency = "#./inferred_RF_frequency"`
+        Returns:
+            self.LO_frequency + self.intermediate_frequency
+        """
+        name = getattr(self, "name", self.__class__.__name__)
+        if not isinstance(self.LO_frequency, (float, int)):
+            raise AttributeError(
+                f"Error inferring RF frequency for channel {name}: "
+                f"LO_frequency is not a number: {self.LO_frequency}"
+            )
+        if not isinstance(self.intermediate_frequency, (float, int)):
+            raise AttributeError(
+                f"Error inferring RF frequency for channel {name}: "
+                f"intermediate_frequency is not a number: {self.intermediate_frequency}"
+            )
+        return self.LO_frequency + self.intermediate_frequency
+
+    @property
+    def inferred_intermediate_frequency(self) -> float:
+        """Inferred intermediate frequency by subtracting LO from RF
+
+        Can be used by having reference
+        `intermediate_frequency = "#./inferred_intermediate_frequency"`
+
+        Returns:
+            self.RF_frequency - self.LO_frequency
+        """
+        name = getattr(self, "name", self.__class__.__name__)
+        if not isinstance(self.LO_frequency, (float, int)):
+            raise AttributeError(
+                f"Error inferring intermediate frequency for channel {name}: "
+                f"LO_frequency is not a number: {self.LO_frequency}"
+            )
+        if not isinstance(self.RF_frequency, (float, int)):
+            raise AttributeError(
+                f"Error inferring intermediate frequency for channel {name}: "
+                f"RF_frequency is not a number: {self.RF_frequency}"
+            )
+        return self.RF_frequency - self.LO_frequency
+
+    @property
+    def inferred_LO_frequency(self) -> float:
+        """Inferred LO frequency by subtracting IF from RF
+
+        Can be used by having reference `LO_frequency = "#./inferred_LO_frequency"`
+
+        Returns:
+            self.RF_frequency - self.intermediate_frequency
+        """
+        name = getattr(self, "name", self.__class__.__name__)
+        if not isinstance(self.RF_frequency, (float, int)):
+            raise AttributeError(
+                f"Error inferring LO frequency for channel {name}: "
+                f"RF_frequency is not a number: {self.RF_frequency}"
+            )
+        if not isinstance(self.intermediate_frequency, (float, int)):
+            raise AttributeError(
+                f"Error inferring LO frequency for channel {name}: "
+                f"intermediate_frequency is not a number: {self.intermediate_frequency}"
+            )
+        return self.RF_frequency - self.intermediate_frequency
+
+    @property
+    def local_oscillator(self) -> Optional[LocalOscillator]:
+        return getattr(self.frequency_converter_up, "local_oscillator", None)
+
+    @property
+    def mixer(self) -> Optional[Mixer]:
+        return getattr(self.frequency_converter_up, "mixer", None)
+
+    @property
+    def rf_frequency(self):
+        warnings.warn(
+            "rf_frequency is deprecated, use RF_frequency instead", DeprecationWarning
+        )
+        return self.frequency_converter_up.LO_frequency + self.intermediate_frequency
+
+    def set_dc_offset(self, offset: QuaNumberType, element_input: Literal["I", "Q"]):
+        """Set the DC offset of an element's input to the given value.
+        This value will remain the DC offset until changed or until the Quantum Machine
+        is closed.
+
+        Args:
+            offset (QuaNumberType): The DC offset to set the input to.
+                This is limited by the OPX output voltage range.
+                The number can be a QUA variable
+            element_input (Literal["I", "Q"]): The element input to set the offset for.
+
+        Raises:
+            ValueError: If element_input is not "I" or "Q"
+        """
+        if element_input not in ["I", "Q"]:
+            raise ValueError(
+                f"element_input should be either 'I' or 'Q', got {element_input}"
+            )
+        set_dc_offset(element=self.name, element_input=element_input, offset=offset)
+
+    def apply_to_config(self, config: dict):
+        """Adds this IQChannel to the QUA configuration.
+
+        See [`QuamComponent.apply_to_config`][quam.core.quam_classes.QuamComponent.apply_to_config]
+        for details.
+        """
+        # Add pulses & waveforms
+        super().apply_to_config(config)
+
+        if str_ref.is_reference(self.name):
+            raise AttributeError(
+                f"Channel {self.get_reference()} cannot be added to the config because"
+                " it doesn't have a name. Either set channel.id to a string or"
+                " integer, or channel should be an attribute of another QuAM component"
+                " with a name."
+            )
+
+        element_cfg = config["elements"][self.name]
+        element_cfg["intermediate_frequency"] = self.intermediate_frequency
+
+        from quam.components.octave import OctaveUpConverter
+
+        if isinstance(self.frequency_converter_up, OctaveUpConverter):
+            octave = self.frequency_converter_up.octave
+            if octave is None:
+                raise ValueError(
+                    f"Error generating config: channel {self.name} has an "
+                    f"OctaveUpConverter (id={self.frequency_converter_up.id}) without "
+                    "an attached Octave"
+                )
+            element_cfg["RF_inputs"] = {
+                "port": (octave.name, self.frequency_converter_up.id)
+            }
+        elif str_ref.is_reference(self.frequency_converter_up):
+            raise ValueError(
+                f"Error generating config: channel {self.name} could not determine "
+                f'"frequency_converter_up", it seems to point to a non-existent '
+                f"reference: {self.frequency_converter_up}"
+            )
+        else:
+
+            element_cfg["mixInputs"] = {}  # To be filled in next section
+            if self.mixer is not None:
+                element_cfg["mixInputs"]["mixer"] = self.mixer.name
+            if self.local_oscillator is not None:
+                element_cfg["mixInputs"][
+                    "lo_frequency"
+                ] = self.local_oscillator.frequency
+
+        opx_outputs = [self.opx_output_I, self.opx_output_Q]
+        offsets = [self.opx_output_offset_I, self.opx_output_offset_Q]
+        for I_or_Q, opx_output, offset in zip("IQ", opx_outputs, offsets):
+            if isinstance(opx_output, LFAnalogOutputPort):
+                opx_port = opx_output
+            elif len(opx_output) == 2:
+                opx_port = OPXPlusAnalogOutputPort(*opx_output, offset=offset)
+                opx_port.apply_to_config(config)
+            else:
+                opx_port = LFFEMAnalogOutputPort(*opx_output, offset=offset)
+                opx_port.apply_to_config(config)
+
+            if "mixInputs" in element_cfg:
+                element_cfg["mixInputs"][I_or_Q] = opx_port.port_tuple
+
+
+ + + +
+ + + + + + + +
+ + + +

+ inferred_LO_frequency: float + + + property + + +

+ + +
+ +

Inferred LO frequency by subtracting IF from RF

+

Can be used by having reference LO_frequency = "#./inferred_LO_frequency"

+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ float + +
+

self.RF_frequency - self.intermediate_frequency

+
+
+
+ +
+ +
+ + + +

+ inferred_RF_frequency: float + + + property + + +

+ + +
+ +

Inferred RF frequency by adding LO and IF

+

Can be used by having reference RF_frequency = "#./inferred_RF_frequency" +Returns: + self.LO_frequency + self.intermediate_frequency

+
+ +
+ +
+ + + +

+ inferred_intermediate_frequency: float + + + property + + +

+ + +
+ +

Inferred intermediate frequency by subtracting LO from RF

+

Can be used by having reference +intermediate_frequency = "#./inferred_intermediate_frequency"

+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ float + +
+

self.RF_frequency - self.LO_frequency

+
+
+
+ +
+ + + +
+ + +

+ apply_to_config(config) + +

+ + +
+ +

Adds this IQChannel to the QUA configuration.

+

See QuamComponent.apply_to_config +for details.

+ +
+ Source code in quam/components/channels.py + 
 967
+ 968
+ 969
+ 970
+ 971
+ 972
+ 973
+ 974
+ 975
+ 976
+ 977
+ 978
+ 979
+ 980
+ 981
+ 982
+ 983
+ 984
+ 985
+ 986
+ 987
+ 988
+ 989
+ 990
+ 991
+ 992
+ 993
+ 994
+ 995
+ 996
+ 997
+ 998
+ 999
+1000
+1001
+1002
+1003
+1004
+1005
+1006
+1007
+1008
+1009
+1010
+1011
+1012
+1013
+1014
+1015
+1016
+1017
+1018
+1019
+1020
+1021
+1022
+1023
+1024
+1025
+1026
+1027
+1028
+1029
def apply_to_config(self, config: dict):
+    """Adds this IQChannel to the QUA configuration.
+
+    See [`QuamComponent.apply_to_config`][quam.core.quam_classes.QuamComponent.apply_to_config]
+    for details.
+    """
+    # Add pulses & waveforms
+    super().apply_to_config(config)
+
+    if str_ref.is_reference(self.name):
+        raise AttributeError(
+            f"Channel {self.get_reference()} cannot be added to the config because"
+            " it doesn't have a name. Either set channel.id to a string or"
+            " integer, or channel should be an attribute of another QuAM component"
+            " with a name."
+        )
+
+    element_cfg = config["elements"][self.name]
+    element_cfg["intermediate_frequency"] = self.intermediate_frequency
+
+    from quam.components.octave import OctaveUpConverter
+
+    if isinstance(self.frequency_converter_up, OctaveUpConverter):
+        octave = self.frequency_converter_up.octave
+        if octave is None:
+            raise ValueError(
+                f"Error generating config: channel {self.name} has an "
+                f"OctaveUpConverter (id={self.frequency_converter_up.id}) without "
+                "an attached Octave"
+            )
+        element_cfg["RF_inputs"] = {
+            "port": (octave.name, self.frequency_converter_up.id)
+        }
+    elif str_ref.is_reference(self.frequency_converter_up):
+        raise ValueError(
+            f"Error generating config: channel {self.name} could not determine "
+            f'"frequency_converter_up", it seems to point to a non-existent '
+            f"reference: {self.frequency_converter_up}"
+        )
+    else:
+
+        element_cfg["mixInputs"] = {}  # To be filled in next section
+        if self.mixer is not None:
+            element_cfg["mixInputs"]["mixer"] = self.mixer.name
+        if self.local_oscillator is not None:
+            element_cfg["mixInputs"][
+                "lo_frequency"
+            ] = self.local_oscillator.frequency
+
+    opx_outputs = [self.opx_output_I, self.opx_output_Q]
+    offsets = [self.opx_output_offset_I, self.opx_output_offset_Q]
+    for I_or_Q, opx_output, offset in zip("IQ", opx_outputs, offsets):
+        if isinstance(opx_output, LFAnalogOutputPort):
+            opx_port = opx_output
+        elif len(opx_output) == 2:
+            opx_port = OPXPlusAnalogOutputPort(*opx_output, offset=offset)
+            opx_port.apply_to_config(config)
+        else:
+            opx_port = LFFEMAnalogOutputPort(*opx_output, offset=offset)
+            opx_port.apply_to_config(config)
+
+        if "mixInputs" in element_cfg:
+            element_cfg["mixInputs"][I_or_Q] = opx_port.port_tuple
+
+
+
+ +
+ +
+ + +

+ set_dc_offset(offset, element_input) + +

+ + +
+ +

Set the DC offset of an element's input to the given value. +This value will remain the DC offset until changed or until the Quantum Machine +is closed.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
offset + QuaNumberType + +
+

The DC offset to set the input to. +This is limited by the OPX output voltage range. +The number can be a QUA variable

+
+ 		+ required +
element_input + Literal['I', 'Q'] + +
+

The element input to set the offset for.

+
+ 		+ required +
+ + +

Raises:

+ + + + + + + + + + + + + +
TypeDescription
+ ValueError + +
+

If element_input is not "I" or "Q"

+
+
+ +
+ Source code in quam/components/channels.py + 
947
+948
+949
+950
+951
+952
+953
+954
+955
+956
+957
+958
+959
+960
+961
+962
+963
+964
+965
def set_dc_offset(self, offset: QuaNumberType, element_input: Literal["I", "Q"]):
+    """Set the DC offset of an element's input to the given value.
+    This value will remain the DC offset until changed or until the Quantum Machine
+    is closed.
+
+    Args:
+        offset (QuaNumberType): The DC offset to set the input to.
+            This is limited by the OPX output voltage range.
+            The number can be a QUA variable
+        element_input (Literal["I", "Q"]): The element input to set the offset for.
+
+    Raises:
+        ValueError: If element_input is not "I" or "Q"
+    """
+    if element_input not in ["I", "Q"]:
+        raise ValueError(
+            f"element_input should be either 'I' or 'Q', got {element_input}"
+        )
+    set_dc_offset(element=self.name, element_input=element_input, offset=offset)
+
+
+
+ +
+ + + +
+ +
+ +
+ +
+ + + +

+ InIQChannel + + +

+ + +
+

+ Bases: Channel

+ + +

QuAM component for an IQ input channel

+

operations (Dict[str, Pulse]): A dictionary of pulses to be played on this + channel. The key is the pulse label (e.g. "readout") and value is a + ReadoutPulse. +id (str, int): The id of the channel, used to generate the name. + Can be a string, or an integer in which case it will add + Channel._default_label. +opx_input_I (Tuple[str, int]): Channel I input port from the OPX perspective, + a tuple of (controller_name, port). +opx_input_Q (Tuple[str, int]): Channel Q input port from the OPX perspective, + a tuple of (controller_name, port). +opx_input_offset_I float: The offset of the I channel. Default is 0. +opx_input_offset_Q float: The offset of the Q channel. Default is 0. +frequency_converter_down (Optional[FrequencyConverter]): Frequency converter + QuAM component for the IQ input port. Only needed for the old Octave. +time_of_flight (int): Round-trip signal duration in nanoseconds. +smearing (int): Additional window of ADC integration in nanoseconds. + Used to account for signal smearing. +input_gain (float): The gain of the input channel. Default is None.

+ +
+ Source code in quam/components/channels.py + 
1032
+1033
+1034
+1035
+1036
+1037
+1038
+1039
+1040
+1041
+1042
+1043
+1044
+1045
+1046
+1047
+1048
+1049
+1050
+1051
+1052
+1053
+1054
+1055
+1056
+1057
+1058
+1059
+1060
+1061
+1062
+1063
+1064
+1065
+1066
+1067
+1068
+1069
+1070
+1071
+1072
+1073
+1074
+1075
+1076
+1077
+1078
+1079
+1080
+1081
+1082
+1083
+1084
+1085
+1086
+1087
+1088
+1089
+1090
+1091
+1092
+1093
+1094
+1095
+1096
+1097
+1098
+1099
+1100
+1101
+1102
+1103
+1104
+1105
+1106
+1107
+1108
+1109
+1110
+1111
+1112
+1113
+1114
+1115
+1116
+1117
+1118
+1119
+1120
+1121
+1122
+1123
+1124
+1125
+1126
+1127
+1128
+1129
+1130
+1131
+1132
+1133
+1134
+1135
+1136
+1137
+1138
+1139
+1140
+1141
+1142
+1143
+1144
+1145
+1146
+1147
+1148
+1149
+1150
+1151
+1152
+1153
+1154
+1155
+1156
+1157
+1158
+1159
+1160
+1161
+1162
+1163
+1164
+1165
+1166
+1167
+1168
+1169
+1170
+1171
+1172
+1173
+1174
+1175
+1176
+1177
+1178
+1179
+1180
+1181
+1182
+1183
+1184
+1185
+1186
+1187
+1188
+1189
+1190
+1191
+1192
+1193
+1194
+1195
+1196
+1197
+1198
+1199
+1200
+1201
+1202
+1203
+1204
+1205
+1206
+1207
+1208
+1209
+1210
+1211
+1212
+1213
+1214
+1215
+1216
+1217
+1218
+1219
+1220
+1221
+1222
+1223
+1224
+1225
+1226
+1227
+1228
+1229
+1230
+1231
+1232
+1233
+1234
+1235
+1236
+1237
+1238
+1239
+1240
+1241
+1242
+1243
+1244
+1245
+1246
+1247
+1248
+1249
+1250
+1251
+1252
+1253
+1254
+1255
+1256
+1257
+1258
+1259
+1260
+1261
+1262
+1263
+1264
+1265
+1266
+1267
+1268
+1269
+1270
+1271
+1272
+1273
+1274
+1275
+1276
+1277
+1278
+1279
+1280
+1281
+1282
+1283
+1284
+1285
+1286
+1287
+1288
+1289
+1290
+1291
+1292
+1293
+1294
+1295
+1296
+1297
+1298
+1299
+1300
+1301
+1302
+1303
+1304
+1305
+1306
+1307
+1308
+1309
+1310
+1311
+1312
+1313
+1314
+1315
+1316
+1317
+1318
+1319
+1320
+1321
+1322
+1323
+1324
+1325
+1326
+1327
+1328
+1329
+1330
+1331
+1332
+1333
+1334
+1335
+1336
+1337
+1338
+1339
+1340
+1341
+1342
+1343
+1344
+1345
+1346
+1347
+1348
+1349
+1350
+1351
+1352
+1353
+1354
+1355
+1356
+1357
+1358
+1359
@quam_dataclass
+class InIQChannel(Channel):
+    """QuAM component for an IQ input channel
+
+    operations (Dict[str, Pulse]): A dictionary of pulses to be played on this
+        channel. The key is the pulse label (e.g. "readout") and value is a
+        ReadoutPulse.
+    id (str, int): The id of the channel, used to generate the name.
+        Can be a string, or an integer in which case it will add
+        `Channel._default_label`.
+    opx_input_I (Tuple[str, int]): Channel I input port from the OPX perspective,
+        a tuple of (controller_name, port).
+    opx_input_Q (Tuple[str, int]): Channel Q input port from the OPX perspective,
+        a tuple of (controller_name, port).
+    opx_input_offset_I float: The offset of the I channel. Default is 0.
+    opx_input_offset_Q float: The offset of the Q channel. Default is 0.
+    frequency_converter_down (Optional[FrequencyConverter]): Frequency converter
+        QuAM component for the IQ input port. Only needed for the old Octave.
+    time_of_flight (int): Round-trip signal duration in nanoseconds.
+    smearing (int): Additional window of ADC integration in nanoseconds.
+        Used to account for signal smearing.
+    input_gain (float): The gain of the input channel. Default is None.
+    """
+
+    opx_input_I: Union[Tuple[str, int], Tuple[str, int, int], LFAnalogInputPort]
+    opx_input_Q: Union[Tuple[str, int], Tuple[str, int, int], LFAnalogInputPort]
+
+    time_of_flight: int = 24
+    smearing: int = 0
+
+    opx_input_offset_I: float = None
+    opx_input_offset_Q: float = None
+
+    input_gain: Optional[int] = None
+
+    frequency_converter_down: BaseFrequencyConverter = None
+
+    _default_label: ClassVar[str] = "IQ"
+
+    def apply_to_config(self, config: dict):
+        """Adds this InOutIQChannel to the QUA configuration.
+
+        See [`QuamComponent.apply_to_config`][quam.core.quam_classes.QuamComponent.apply_to_config]
+        for details.
+        """
+        super().apply_to_config(config)
+
+        # Note outputs instead of inputs because it's w.r.t. the QPU
+        element_cfg = config["elements"][self.name]
+        element_cfg["smearing"] = self.smearing
+        element_cfg["time_of_flight"] = self.time_of_flight
+
+        from quam.components.octave import OctaveDownConverter
+
+        if isinstance(self.frequency_converter_down, OctaveDownConverter):
+            octave = self.frequency_converter_down.octave
+            if octave is None:
+                raise ValueError(
+                    f"Error generating config: channel {self.name} has an "
+                    f"OctaveDownConverter (id={self.frequency_converter_down.id}) "
+                    "without an attached Octave"
+                )
+            element_cfg["RF_outputs"] = {
+                "port": (octave.name, self.frequency_converter_down.id)
+            }
+        elif str_ref.is_reference(self.frequency_converter_down):
+            raise ValueError(
+                f"Error generating config: channel {self.name} could not determine "
+                f'"frequency_converter_down", it seems to point to a non-existent '
+                f"reference: {self.frequency_converter_down}"
+            )
+        else:
+            # To be filled in next section
+            element_cfg["outputs"] = {}
+
+        opx_inputs = [self.opx_input_I, self.opx_input_Q]
+        offsets = [self.opx_input_offset_I, self.opx_input_offset_Q]
+        input_gain = int(self.input_gain if self.input_gain is not None else 0)
+        for k, (opx_input, offset) in enumerate(zip(opx_inputs, offsets), start=1):
+            if isinstance(opx_input, LFAnalogInputPort):
+                opx_port = opx_input
+            elif len(opx_input) == 2:
+                opx_port = OPXPlusAnalogInputPort(
+                    *opx_input, offset=offset, gain_db=input_gain
+                )
+                opx_port.apply_to_config(config)
+            else:
+                opx_port = LFFEMAnalogInputPort(
+                    *opx_input, offset=offset, gain_db=input_gain
+                )
+                opx_port.apply_to_config(config)
+            if not isinstance(self.frequency_converter_down, OctaveDownConverter):
+                element_cfg["outputs"][f"out{k}"] = opx_port.port_tuple
+
+    def measure(
+        self,
+        pulse_name: str,
+        amplitude_scale: Union[float, AmpValuesType] = None,
+        qua_vars: Tuple[QuaVariableType, QuaVariableType] = None,
+        stream=None,
+    ) -> Tuple[QuaVariableType, QuaVariableType]:
+        """Perform a full dual demodulation measurement on this channel.
+
+        Args:
+            pulse_name (str): The name of the pulse to play. Should be registered in
+                `self.operations`.
+            amplitude_scale (float, _PulseAmp): Amplitude scale of the pulse.
+                Can be either a float, or qua.amp(float).
+            qua_vars (Tuple[QuaVariableType, QuaVariableType], optional): Two QUA
+                variables to store the I and Q measurement results. If not provided,
+                new variables will be declared and returned.
+            stream (Optional[StreamType]): The stream to save the measurement result to.
+                If not provided, the raw ADC signal will not be streamed.
+
+        Returns:
+            I, Q: The QUA variables used to store the measurement results.
+                If provided as input, the same variables will be returned.
+                If not provided, new variables will be declared and returned.
+        """
+        pulse: BaseReadoutPulse = self.operations[pulse_name]
+
+        if qua_vars is not None:
+            if not isinstance(qua_vars, Sequence) or len(qua_vars) != 2:
+                raise ValueError(
+                    f"InOutIQChannel.measure received kwarg 'qua_vars' which is not a "
+                    f"tuple of two QUA variables. Received {qua_vars=}"
+                )
+        else:
+            qua_vars = [declare(fixed) for _ in range(2)]
+
+        if amplitude_scale is not None:
+            if not isinstance(amplitude_scale, _PulseAmp):
+                amplitude_scale = amp(amplitude_scale)
+            pulse_name *= amplitude_scale
+
+        integration_weight_labels = list(pulse.integration_weights_mapping)
+        measure(
+            pulse_name,
+            self.name,
+            stream,
+            dual_demod.full(
+                iw1=integration_weight_labels[0],
+                element_output1="out1",
+                iw2=integration_weight_labels[1],
+                element_output2="out2",
+                target=qua_vars[0],
+            ),
+            dual_demod.full(
+                iw1=integration_weight_labels[2],
+                element_output1="out1",
+                iw2=integration_weight_labels[0],
+                element_output2="out2",
+                target=qua_vars[1],
+            ),
+        )
+        return tuple(qua_vars)
+
+    def measure_accumulated(
+        self,
+        pulse_name: str,
+        amplitude_scale: Union[float, AmpValuesType] = None,
+        num_segments: int = None,
+        segment_length: int = None,
+        qua_vars: Tuple[QuaVariableType, ...] = None,
+        stream=None,
+    ) -> Tuple[QuaVariableType, QuaVariableType, QuaVariableType, QuaVariableType]:
+        """Perform an accumulated dual demodulation measurement on this channel.
+
+        Instead of two QUA variables (I and Q), this method returns four variables
+        (II, IQ, QI, QQ)
+
+        Args:
+            pulse_name (str): The name of the pulse to play. Should be registered in
+                `self.operations`.
+            amplitude_scale (float, _PulseAmp): Amplitude scale of the pulse.
+                Can be either a float, or qua.amp(float).
+            num_segments (int): The number of segments to accumulate.
+                Should either specify this or `segment_length`.
+            segment_length (int): The length of the segment to accumulate the
+                measurement.
+                Should either specify this or `num_segments`.
+            qua_vars (Tuple[QuaVariableType, ...], optional): Four QUA
+                variables to store the II, IQ, QI, QQ measurement results.
+                If not provided, new variables will be declared and returned.
+            stream (Optional[StreamType]): The stream to save the measurement result to.
+                If not provided, the raw ADC signal will not be streamed.
+
+        Returns:
+            II, IQ, QI, QQ: The QUA variables used to store the measurement results.
+                If provided as input, the same variables will be returned.
+                If not provided, new variables will be declared and returned.
+        """
+        pulse: BaseReadoutPulse = self.operations[pulse_name]
+
+        if num_segments is None and segment_length is None:
+            raise ValueError(
+                "InOutSingleChannel.measure_accumulated requires either 'segment_length' "
+                "or 'num_segments' to be provided."
+            )
+        elif num_segments is not None and segment_length is not None:
+            raise ValueError(
+                "InOutSingleChannel.measure_accumulated received both 'segment_length' "
+                "and 'num_segments'. Please provide only one."
+            )
+        elif num_segments is None:
+            num_segments = int(pulse.length / (4 * segment_length))  # Number of slices
+        elif segment_length is None:
+            segment_length = int(pulse.length / (4 * num_segments))
+
+        if qua_vars is not None:
+            if not isinstance(qua_vars, Sequence) or len(qua_vars) != 4:
+                raise ValueError(
+                    f"InOutSingleChannel.measure_accumulated received kwarg 'qua_vars' "
+                    f"which is not a tuple of four QUA variables. Received {qua_vars=}"
+                )
+        else:
+            qua_vars = [declare(fixed, size=num_segments) for _ in range(4)]
+
+        if amplitude_scale is not None:
+            if not isinstance(amplitude_scale, _PulseAmp):
+                amplitude_scale = amp(amplitude_scale)
+            pulse_name *= amplitude_scale
+
+        integration_weight_labels = list(pulse.integration_weights_mapping)
+        measure(
+            pulse_name,
+            self.name,
+            stream,
+            demod.accumulated(
+                integration_weight_labels[0], qua_vars[0], segment_length, "out1"
+            ),
+            demod.accumulated(
+                integration_weight_labels[1], qua_vars[1], segment_length, "out2"
+            ),
+            demod.accumulated(
+                integration_weight_labels[2], qua_vars[2], segment_length, "out1"
+            ),
+            demod.accumulated(
+                integration_weight_labels[0], qua_vars[3], segment_length, "out2"
+            ),
+        )
+        return tuple(qua_vars)
+
+    def measure_sliced(
+        self,
+        pulse_name: str,
+        amplitude_scale: Union[float, AmpValuesType] = None,
+        num_segments: int = None,
+        segment_length: int = None,
+        qua_vars: Tuple[QuaVariableType, ...] = None,
+        stream=None,
+    ) -> Tuple[QuaVariableType, QuaVariableType, QuaVariableType, QuaVariableType]:
+        """Perform a sliced dual demodulation measurement on this channel.
+
+        Instead of two QUA variables (I and Q), this method returns four variables
+        (II, IQ, QI, QQ)
+
+        Args:
+            pulse_name (str): The name of the pulse to play. Should be registered in
+                `self.operations`.
+            amplitude_scale (float, _PulseAmp): Amplitude scale of the pulse.
+                Can be either a float, or qua.amp(float).
+            num_segments (int): The number of segments to accumulate.
+                Should either specify this or `segment_length`.
+            segment_length (int): The length of the segment to accumulate the
+                measurement.
+                Should either specify this or `num_segments`.
+            qua_vars (Tuple[QuaVariableType, ...], optional): Four QUA
+                variables to store the II, IQ, QI, QQ measurement results.
+                If not provided, new variables will be declared and returned.
+            stream (Optional[StreamType]): The stream to save the measurement result to.
+                If not provided, the raw ADC signal will not be streamed.
+
+        Returns:
+            II, IQ, QI, QQ: The QUA variables used to store the measurement results.
+                If provided as input, the same variables will be returned.
+                If not provided, new variables will be declared and returned.
+        """
+        pulse: BaseReadoutPulse = self.operations[pulse_name]
+
+        if num_segments is None and segment_length is None:
+            raise ValueError(
+                "InOutSingleChannel.measure_sliced requires either 'segment_length' "
+                "or 'num_segments' to be provided."
+            )
+        elif num_segments is not None and segment_length is not None:
+            raise ValueError(
+                "InOutSingleChannel.measure_sliced received both 'segment_length' "
+                "and 'num_segments'. Please provide only one."
+            )
+        elif num_segments is None:
+            num_segments = int(pulse.length / (4 * segment_length))  # Number of slices
+        elif segment_length is None:
+            segment_length = int(pulse.length / (4 * num_segments))
+
+        if qua_vars is not None:
+            if not isinstance(qua_vars, Sequence) or len(qua_vars) != 4:
+                raise ValueError(
+                    f"InOutSingleChannel.measure_sliced received kwarg 'qua_vars' "
+                    f"which is not a tuple of four QUA variables. Received {qua_vars=}"
+                )
+        else:
+            qua_vars = [declare(fixed, size=num_segments) for _ in range(4)]
+
+        if amplitude_scale is not None:
+            if not isinstance(amplitude_scale, _PulseAmp):
+                amplitude_scale = amp(amplitude_scale)
+            pulse_name *= amplitude_scale
+
+        integration_weight_labels = list(pulse.integration_weights_mapping)
+        measure(
+            pulse_name,
+            self.name,
+            stream,
+            demod.sliced(
+                integration_weight_labels[0], qua_vars[0], segment_length, "out1"
+            ),
+            demod.sliced(
+                integration_weight_labels[1], qua_vars[1], segment_length, "out2"
+            ),
+            demod.sliced(
+                integration_weight_labels[2], qua_vars[2], segment_length, "out1"
+            ),
+            demod.sliced(
+                integration_weight_labels[0], qua_vars[3], segment_length, "out2"
+            ),
+        )
+        return tuple(qua_vars)
+
+
+ + + +
+ + + + + + + + + +
+ + +

+ apply_to_config(config) + +

+ + +
+ +

Adds this InOutIQChannel to the QUA configuration.

+

See QuamComponent.apply_to_config +for details.

+ +
+ Source code in quam/components/channels.py + 
1071
+1072
+1073
+1074
+1075
+1076
+1077
+1078
+1079
+1080
+1081
+1082
+1083
+1084
+1085
+1086
+1087
+1088
+1089
+1090
+1091
+1092
+1093
+1094
+1095
+1096
+1097
+1098
+1099
+1100
+1101
+1102
+1103
+1104
+1105
+1106
+1107
+1108
+1109
+1110
+1111
+1112
+1113
+1114
+1115
+1116
+1117
+1118
+1119
+1120
+1121
+1122
+1123
+1124
def apply_to_config(self, config: dict):
+    """Adds this InOutIQChannel to the QUA configuration.
+
+    See [`QuamComponent.apply_to_config`][quam.core.quam_classes.QuamComponent.apply_to_config]
+    for details.
+    """
+    super().apply_to_config(config)
+
+    # Note outputs instead of inputs because it's w.r.t. the QPU
+    element_cfg = config["elements"][self.name]
+    element_cfg["smearing"] = self.smearing
+    element_cfg["time_of_flight"] = self.time_of_flight
+
+    from quam.components.octave import OctaveDownConverter
+
+    if isinstance(self.frequency_converter_down, OctaveDownConverter):
+        octave = self.frequency_converter_down.octave
+        if octave is None:
+            raise ValueError(
+                f"Error generating config: channel {self.name} has an "
+                f"OctaveDownConverter (id={self.frequency_converter_down.id}) "
+                "without an attached Octave"
+            )
+        element_cfg["RF_outputs"] = {
+            "port": (octave.name, self.frequency_converter_down.id)
+        }
+    elif str_ref.is_reference(self.frequency_converter_down):
+        raise ValueError(
+            f"Error generating config: channel {self.name} could not determine "
+            f'"frequency_converter_down", it seems to point to a non-existent '
+            f"reference: {self.frequency_converter_down}"
+        )
+    else:
+        # To be filled in next section
+        element_cfg["outputs"] = {}
+
+    opx_inputs = [self.opx_input_I, self.opx_input_Q]
+    offsets = [self.opx_input_offset_I, self.opx_input_offset_Q]
+    input_gain = int(self.input_gain if self.input_gain is not None else 0)
+    for k, (opx_input, offset) in enumerate(zip(opx_inputs, offsets), start=1):
+        if isinstance(opx_input, LFAnalogInputPort):
+            opx_port = opx_input
+        elif len(opx_input) == 2:
+            opx_port = OPXPlusAnalogInputPort(
+                *opx_input, offset=offset, gain_db=input_gain
+            )
+            opx_port.apply_to_config(config)
+        else:
+            opx_port = LFFEMAnalogInputPort(
+                *opx_input, offset=offset, gain_db=input_gain
+            )
+            opx_port.apply_to_config(config)
+        if not isinstance(self.frequency_converter_down, OctaveDownConverter):
+            element_cfg["outputs"][f"out{k}"] = opx_port.port_tuple
+
+
+
+ +
+ +
+ + +

+ measure(pulse_name, amplitude_scale=None, qua_vars=None, stream=None) + +

+ + +
+ +

Perform a full dual demodulation measurement on this channel.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
pulse_name + str + +
+

The name of the pulse to play. Should be registered in +self.operations.

+
+ 		+ required +
amplitude_scale + (float, _PulseAmp) + +
+

Amplitude scale of the pulse. +Can be either a float, or qua.amp(float).

+
+ 		+ None +
qua_vars + Tuple[QuaVariableType, QuaVariableType] + +
+

Two QUA +variables to store the I and Q measurement results. If not provided, +new variables will be declared and returned.

+
+ 		+ None +
stream + Optional[StreamType] + +
+

The stream to save the measurement result to. +If not provided, the raw ADC signal will not be streamed.

+
+ 		+ None +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ Tuple[QuaVariableType, QuaVariableType] + +
+

I, Q: The QUA variables used to store the measurement results. +If provided as input, the same variables will be returned. +If not provided, new variables will be declared and returned.

+
+
+ +
+ Source code in quam/components/channels.py + 
1126
+1127
+1128
+1129
+1130
+1131
+1132
+1133
+1134
+1135
+1136
+1137
+1138
+1139
+1140
+1141
+1142
+1143
+1144
+1145
+1146
+1147
+1148
+1149
+1150
+1151
+1152
+1153
+1154
+1155
+1156
+1157
+1158
+1159
+1160
+1161
+1162
+1163
+1164
+1165
+1166
+1167
+1168
+1169
+1170
+1171
+1172
+1173
+1174
+1175
+1176
+1177
+1178
+1179
+1180
+1181
+1182
+1183
+1184
+1185
+1186
+1187
def measure(
+    self,
+    pulse_name: str,
+    amplitude_scale: Union[float, AmpValuesType] = None,
+    qua_vars: Tuple[QuaVariableType, QuaVariableType] = None,
+    stream=None,
+) -> Tuple[QuaVariableType, QuaVariableType]:
+    """Perform a full dual demodulation measurement on this channel.
+
+    Args:
+        pulse_name (str): The name of the pulse to play. Should be registered in
+            `self.operations`.
+        amplitude_scale (float, _PulseAmp): Amplitude scale of the pulse.
+            Can be either a float, or qua.amp(float).
+        qua_vars (Tuple[QuaVariableType, QuaVariableType], optional): Two QUA
+            variables to store the I and Q measurement results. If not provided,
+            new variables will be declared and returned.
+        stream (Optional[StreamType]): The stream to save the measurement result to.
+            If not provided, the raw ADC signal will not be streamed.
+
+    Returns:
+        I, Q: The QUA variables used to store the measurement results.
+            If provided as input, the same variables will be returned.
+            If not provided, new variables will be declared and returned.
+    """
+    pulse: BaseReadoutPulse = self.operations[pulse_name]
+
+    if qua_vars is not None:
+        if not isinstance(qua_vars, Sequence) or len(qua_vars) != 2:
+            raise ValueError(
+                f"InOutIQChannel.measure received kwarg 'qua_vars' which is not a "
+                f"tuple of two QUA variables. Received {qua_vars=}"
+            )
+    else:
+        qua_vars = [declare(fixed) for _ in range(2)]
+
+    if amplitude_scale is not None:
+        if not isinstance(amplitude_scale, _PulseAmp):
+            amplitude_scale = amp(amplitude_scale)
+        pulse_name *= amplitude_scale
+
+    integration_weight_labels = list(pulse.integration_weights_mapping)
+    measure(
+        pulse_name,
+        self.name,
+        stream,
+        dual_demod.full(
+            iw1=integration_weight_labels[0],
+            element_output1="out1",
+            iw2=integration_weight_labels[1],
+            element_output2="out2",
+            target=qua_vars[0],
+        ),
+        dual_demod.full(
+            iw1=integration_weight_labels[2],
+            element_output1="out1",
+            iw2=integration_weight_labels[0],
+            element_output2="out2",
+            target=qua_vars[1],
+        ),
+    )
+    return tuple(qua_vars)
+
+
+
+ +
+ +
+ + +

+ measure_accumulated(pulse_name, amplitude_scale=None, num_segments=None, segment_length=None, qua_vars=None, stream=None) + +

+ + +
+ +

Perform an accumulated dual demodulation measurement on this channel.

+

Instead of two QUA variables (I and Q), this method returns four variables +(II, IQ, QI, QQ)

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
pulse_name + str + +
+

The name of the pulse to play. Should be registered in +self.operations.

+
+ 		+ required +
amplitude_scale + (float, _PulseAmp) + +
+

Amplitude scale of the pulse. +Can be either a float, or qua.amp(float).

+
+ 		+ None +
num_segments + int + +
+

The number of segments to accumulate. +Should either specify this or segment_length.

+
+ 		+ None +
segment_length + int + +
+

The length of the segment to accumulate the +measurement. +Should either specify this or num_segments.

+
+ 		+ None +
qua_vars + Tuple[QuaVariableType, ...] + +
+

Four QUA +variables to store the II, IQ, QI, QQ measurement results. +If not provided, new variables will be declared and returned.

+
+ 		+ None +
stream + Optional[StreamType] + +
+

The stream to save the measurement result to. +If not provided, the raw ADC signal will not be streamed.

+
+ 		+ None +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ Tuple[QuaVariableType, QuaVariableType, QuaVariableType, QuaVariableType] + +
+

II, IQ, QI, QQ: The QUA variables used to store the measurement results. +If provided as input, the same variables will be returned. +If not provided, new variables will be declared and returned.

+
+
+ +
+ Source code in quam/components/channels.py + 
1189
+1190
+1191
+1192
+1193
+1194
+1195
+1196
+1197
+1198
+1199
+1200
+1201
+1202
+1203
+1204
+1205
+1206
+1207
+1208
+1209
+1210
+1211
+1212
+1213
+1214
+1215
+1216
+1217
+1218
+1219
+1220
+1221
+1222
+1223
+1224
+1225
+1226
+1227
+1228
+1229
+1230
+1231
+1232
+1233
+1234
+1235
+1236
+1237
+1238
+1239
+1240
+1241
+1242
+1243
+1244
+1245
+1246
+1247
+1248
+1249
+1250
+1251
+1252
+1253
+1254
+1255
+1256
+1257
+1258
+1259
+1260
+1261
+1262
+1263
+1264
+1265
+1266
+1267
+1268
+1269
+1270
+1271
+1272
+1273
def measure_accumulated(
+    self,
+    pulse_name: str,
+    amplitude_scale: Union[float, AmpValuesType] = None,
+    num_segments: int = None,
+    segment_length: int = None,
+    qua_vars: Tuple[QuaVariableType, ...] = None,
+    stream=None,
+) -> Tuple[QuaVariableType, QuaVariableType, QuaVariableType, QuaVariableType]:
+    """Perform an accumulated dual demodulation measurement on this channel.
+
+    Instead of two QUA variables (I and Q), this method returns four variables
+    (II, IQ, QI, QQ)
+
+    Args:
+        pulse_name (str): The name of the pulse to play. Should be registered in
+            `self.operations`.
+        amplitude_scale (float, _PulseAmp): Amplitude scale of the pulse.
+            Can be either a float, or qua.amp(float).
+        num_segments (int): The number of segments to accumulate.
+            Should either specify this or `segment_length`.
+        segment_length (int): The length of the segment to accumulate the
+            measurement.
+            Should either specify this or `num_segments`.
+        qua_vars (Tuple[QuaVariableType, ...], optional): Four QUA
+            variables to store the II, IQ, QI, QQ measurement results.
+            If not provided, new variables will be declared and returned.
+        stream (Optional[StreamType]): The stream to save the measurement result to.
+            If not provided, the raw ADC signal will not be streamed.
+
+    Returns:
+        II, IQ, QI, QQ: The QUA variables used to store the measurement results.
+            If provided as input, the same variables will be returned.
+            If not provided, new variables will be declared and returned.
+    """
+    pulse: BaseReadoutPulse = self.operations[pulse_name]
+
+    if num_segments is None and segment_length is None:
+        raise ValueError(
+            "InOutSingleChannel.measure_accumulated requires either 'segment_length' "
+            "or 'num_segments' to be provided."
+        )
+    elif num_segments is not None and segment_length is not None:
+        raise ValueError(
+            "InOutSingleChannel.measure_accumulated received both 'segment_length' "
+            "and 'num_segments'. Please provide only one."
+        )
+    elif num_segments is None:
+        num_segments = int(pulse.length / (4 * segment_length))  # Number of slices
+    elif segment_length is None:
+        segment_length = int(pulse.length / (4 * num_segments))
+
+    if qua_vars is not None:
+        if not isinstance(qua_vars, Sequence) or len(qua_vars) != 4:
+            raise ValueError(
+                f"InOutSingleChannel.measure_accumulated received kwarg 'qua_vars' "
+                f"which is not a tuple of four QUA variables. Received {qua_vars=}"
+            )
+    else:
+        qua_vars = [declare(fixed, size=num_segments) for _ in range(4)]
+
+    if amplitude_scale is not None:
+        if not isinstance(amplitude_scale, _PulseAmp):
+            amplitude_scale = amp(amplitude_scale)
+        pulse_name *= amplitude_scale
+
+    integration_weight_labels = list(pulse.integration_weights_mapping)
+    measure(
+        pulse_name,
+        self.name,
+        stream,
+        demod.accumulated(
+            integration_weight_labels[0], qua_vars[0], segment_length, "out1"
+        ),
+        demod.accumulated(
+            integration_weight_labels[1], qua_vars[1], segment_length, "out2"
+        ),
+        demod.accumulated(
+            integration_weight_labels[2], qua_vars[2], segment_length, "out1"
+        ),
+        demod.accumulated(
+            integration_weight_labels[0], qua_vars[3], segment_length, "out2"
+        ),
+    )
+    return tuple(qua_vars)
+
+
+
+ +
+ +
+ + +

+ measure_sliced(pulse_name, amplitude_scale=None, num_segments=None, segment_length=None, qua_vars=None, stream=None) + +

+ + +
+ +

Perform a sliced dual demodulation measurement on this channel.

+

Instead of two QUA variables (I and Q), this method returns four variables +(II, IQ, QI, QQ)

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
pulse_name + str + +
+

The name of the pulse to play. Should be registered in +self.operations.

+
+ 		+ required +
amplitude_scale + (float, _PulseAmp) + +
+

Amplitude scale of the pulse. +Can be either a float, or qua.amp(float).

+
+ 		+ None +
num_segments + int + +
+

The number of segments to accumulate. +Should either specify this or segment_length.

+
+ 		+ None +
segment_length + int + +
+

The length of the segment to accumulate the +measurement. +Should either specify this or num_segments.

+
+ 		+ None +
qua_vars + Tuple[QuaVariableType, ...] + +
+

Four QUA +variables to store the II, IQ, QI, QQ measurement results. +If not provided, new variables will be declared and returned.

+
+ 		+ None +
stream + Optional[StreamType] + +
+

The stream to save the measurement result to. +If not provided, the raw ADC signal will not be streamed.

+
+ 		+ None +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ Tuple[QuaVariableType, QuaVariableType, QuaVariableType, QuaVariableType] + +
+

II, IQ, QI, QQ: The QUA variables used to store the measurement results. +If provided as input, the same variables will be returned. +If not provided, new variables will be declared and returned.

+
+
+ +
+ Source code in quam/components/channels.py + 
1275
+1276
+1277
+1278
+1279
+1280
+1281
+1282
+1283
+1284
+1285
+1286
+1287
+1288
+1289
+1290
+1291
+1292
+1293
+1294
+1295
+1296
+1297
+1298
+1299
+1300
+1301
+1302
+1303
+1304
+1305
+1306
+1307
+1308
+1309
+1310
+1311
+1312
+1313
+1314
+1315
+1316
+1317
+1318
+1319
+1320
+1321
+1322
+1323
+1324
+1325
+1326
+1327
+1328
+1329
+1330
+1331
+1332
+1333
+1334
+1335
+1336
+1337
+1338
+1339
+1340
+1341
+1342
+1343
+1344
+1345
+1346
+1347
+1348
+1349
+1350
+1351
+1352
+1353
+1354
+1355
+1356
+1357
+1358
+1359
def measure_sliced(
+    self,
+    pulse_name: str,
+    amplitude_scale: Union[float, AmpValuesType] = None,
+    num_segments: int = None,
+    segment_length: int = None,
+    qua_vars: Tuple[QuaVariableType, ...] = None,
+    stream=None,
+) -> Tuple[QuaVariableType, QuaVariableType, QuaVariableType, QuaVariableType]:
+    """Perform a sliced dual demodulation measurement on this channel.
+
+    Instead of two QUA variables (I and Q), this method returns four variables
+    (II, IQ, QI, QQ)
+
+    Args:
+        pulse_name (str): The name of the pulse to play. Should be registered in
+            `self.operations`.
+        amplitude_scale (float, _PulseAmp): Amplitude scale of the pulse.
+            Can be either a float, or qua.amp(float).
+        num_segments (int): The number of segments to accumulate.
+            Should either specify this or `segment_length`.
+        segment_length (int): The length of the segment to accumulate the
+            measurement.
+            Should either specify this or `num_segments`.
+        qua_vars (Tuple[QuaVariableType, ...], optional): Four QUA
+            variables to store the II, IQ, QI, QQ measurement results.
+            If not provided, new variables will be declared and returned.
+        stream (Optional[StreamType]): The stream to save the measurement result to.
+            If not provided, the raw ADC signal will not be streamed.
+
+    Returns:
+        II, IQ, QI, QQ: The QUA variables used to store the measurement results.
+            If provided as input, the same variables will be returned.
+            If not provided, new variables will be declared and returned.
+    """
+    pulse: BaseReadoutPulse = self.operations[pulse_name]
+
+    if num_segments is None and segment_length is None:
+        raise ValueError(
+            "InOutSingleChannel.measure_sliced requires either 'segment_length' "
+            "or 'num_segments' to be provided."
+        )
+    elif num_segments is not None and segment_length is not None:
+        raise ValueError(
+            "InOutSingleChannel.measure_sliced received both 'segment_length' "
+            "and 'num_segments'. Please provide only one."
+        )
+    elif num_segments is None:
+        num_segments = int(pulse.length / (4 * segment_length))  # Number of slices
+    elif segment_length is None:
+        segment_length = int(pulse.length / (4 * num_segments))
+
+    if qua_vars is not None:
+        if not isinstance(qua_vars, Sequence) or len(qua_vars) != 4:
+            raise ValueError(
+                f"InOutSingleChannel.measure_sliced received kwarg 'qua_vars' "
+                f"which is not a tuple of four QUA variables. Received {qua_vars=}"
+            )
+    else:
+        qua_vars = [declare(fixed, size=num_segments) for _ in range(4)]
+
+    if amplitude_scale is not None:
+        if not isinstance(amplitude_scale, _PulseAmp):
+            amplitude_scale = amp(amplitude_scale)
+        pulse_name *= amplitude_scale
+
+    integration_weight_labels = list(pulse.integration_weights_mapping)
+    measure(
+        pulse_name,
+        self.name,
+        stream,
+        demod.sliced(
+            integration_weight_labels[0], qua_vars[0], segment_length, "out1"
+        ),
+        demod.sliced(
+            integration_weight_labels[1], qua_vars[1], segment_length, "out2"
+        ),
+        demod.sliced(
+            integration_weight_labels[2], qua_vars[2], segment_length, "out1"
+        ),
+        demod.sliced(
+            integration_weight_labels[0], qua_vars[3], segment_length, "out2"
+        ),
+    )
+    return tuple(qua_vars)
+
+
+
+ +
+ + + +
+ +
+ +
+ +
+ + + +

+ InIQOutSingleChannel + + +

+ + +
+

+ Bases: SingleChannel, InIQChannel

+ + +

QuAM component for an IQ input channel with a single output.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
operations + Dict[str, Pulse] + +
+

A dictionary of pulses to be played on this +channel. The key is the pulse label (e.g. "readout") and value is a +ReadoutPulse.

+
+ 		+ required +
id + (str, int) + +
+

The id of the channel, used to generate the name. +Can be a string, or an integer in which case it will add +Channel._default_label.

+
+ 		+ required +
opx_output + Tuple[str, int] + +
+

Channel output port from the OPX perspective, +a tuple of (controller_name, port).

+
+ 		+ required +
opx_output_offset + float + +
+

DC offset for the output port.

+
+ 		+ required +
opx_input_I + Tuple[str, int] + +
+

Channel I input port from the OPX perspective, +a tuple of (controller_name, port).

+
+ 		+ required +
opx_input_Q + Tuple[str, int] + +
+

Channel Q input port from the OPX perspective, +a tuple of (controller_name, port).

+
+ 		+ required +
opx_input_offset_I + float + +
+

The offset of the I channel. Default is 0.

+
+ 		+ required +
opx_input_offset_Q + float + +
+

The offset of the Q channel. Default is 0.

+
+ 		+ required +
filter_fir_taps + List[float] + +
+

FIR filter taps for the output port.

+
+ 		+ required +
filter_iir_taps + List[float] + +
+

IIR filter taps for the output port.

+
+ 		+ required +
intermediate_frequency + float + +
+

Intermediate frequency of OPX output, default +is None.

+
+ 		+ required +
time_of_flight + int + +
+

Round-trip signal duration in nanoseconds.

+
+ 		+ required +
smearing + int + +
+

Additional window of ADC integration in nanoseconds. +Used to account for signal smearing.

+
+ 		+ required +
+ +
+ Source code in quam/components/channels.py + 
1470
+1471
+1472
+1473
+1474
+1475
+1476
+1477
+1478
+1479
+1480
+1481
+1482
+1483
+1484
+1485
+1486
+1487
+1488
+1489
+1490
+1491
+1492
+1493
+1494
+1495
+1496
+1497
+1498
+1499
@quam_dataclass
+class InIQOutSingleChannel(SingleChannel, InIQChannel):
+    """QuAM component for an IQ input channel with a single output.
+
+    Args:
+        operations (Dict[str, Pulse]): A dictionary of pulses to be played on this
+            channel. The key is the pulse label (e.g. "readout") and value is a
+            ReadoutPulse.
+        id (str, int): The id of the channel, used to generate the name.
+            Can be a string, or an integer in which case it will add
+            `Channel._default_label`.
+        opx_output (Tuple[str, int]): Channel output port from the OPX perspective,
+            a tuple of (controller_name, port).
+        opx_output_offset (float): DC offset for the output port.
+        opx_input_I (Tuple[str, int]): Channel I input port from the OPX perspective,
+            a tuple of (controller_name, port).
+        opx_input_Q (Tuple[str, int]): Channel Q input port from the OPX perspective,
+            a tuple of (controller_name, port).
+        opx_input_offset_I float: The offset of the I channel. Default is 0.
+        opx_input_offset_Q float: The offset of the Q channel. Default is 0.
+        filter_fir_taps (List[float]): FIR filter taps for the output port.
+        filter_iir_taps (List[float]): IIR filter taps for the output port.
+        intermediate_frequency (float): Intermediate frequency of OPX output, default
+            is None.
+        time_of_flight (int): Round-trip signal duration in nanoseconds.
+        smearing (int): Additional window of ADC integration in nanoseconds.
+            Used to account for signal smearing.
+    """
+
+    pass
+
+
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ +
+ + + +

+ InOutIQChannel + + +

+ + +
+

+ Bases: IQChannel, InIQChannel

+ + +

QuAM component for an IQ channel with both input and output.

+

An example of such a channel is a readout resonator, where you may want to +apply a readout tone and then measure the response.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
operations + Dict[str, Pulse] + +
+

A dictionary of pulses to be played on this +channel. The key is the pulse label (e.g. "readout") and value is a +ReadoutPulse.

+
+ 		+ required +
id + (str, int) + +
+

The id of the channel, used to generate the name. +Can be a string, or an integer in which case it will add +Channel._default_label.

+
+ 		+ required +
opx_output_I + Tuple[str, int] + +
+

Channel I output port from the OPX perspective, +a tuple of (controller_name, port).

+
+ 		+ required +
opx_output_Q + Tuple[str, int] + +
+

Channel Q output port from the OPX perspective, +a tuple of (controller_name, port).

+
+ 		+ required +
opx_output_offset_I + float + +
+

The offset of the I channel. Default is 0.

+
+ 		+ required +
opx_output_offset_Q + float + +
+

The offset of the Q channel. Default is 0.

+
+ 		+ required +
opx_input_I + Tuple[str, int] + +
+

Channel I input port from the OPX perspective, +a tuple of (controller_name, port).

+
+ 		+ required +
opx_input_Q + Tuple[str, int] + +
+

Channel Q input port from the OPX perspective, +a tuple of (controller_name, port).

+
+ 		+ required +
opx_input_offset_I + float + +
+

The offset of the I channel. Default is 0.

+
+ 		+ required +
opx_input_offset_Q + float + +
+

The offset of the Q channel. Default is 0.

+
+ 		+ required +
intermediate_frequency + float + +
+

Intermediate frequency of the mixer. +Default is 0.0

+
+ 		+ required +
LO_frequency + float + +
+

Local oscillator frequency. Default is the LO frequency +of the frequency converter up component.

+
+ 		+ required +
RF_frequency + float + +
+

RF frequency of the mixer. By default, the RF frequency +is inferred by adding the LO frequency and the intermediate frequency.

+
+ 		+ required +
frequency_converter_up + FrequencyConverter + +
+

Frequency converter QuAM component +for the IQ output.

+
+ 		+ required +
frequency_converter_down + Optional[FrequencyConverter] + +
+

Frequency converter +QuAM component for the IQ input port. Only needed for the old Octave.

+
+ 		+ required +
time_of_flight + int + +
+

Round-trip signal duration in nanoseconds.

+
+ 		+ required +
smearing + int + +
+

Additional window of ADC integration in nanoseconds. +Used to account for signal smearing.

+
+ 		+ required +
+ +
+ Source code in quam/components/channels.py + 
1390
+1391
+1392
+1393
+1394
+1395
+1396
+1397
+1398
+1399
+1400
+1401
+1402
+1403
+1404
+1405
+1406
+1407
+1408
+1409
+1410
+1411
+1412
+1413
+1414
+1415
+1416
+1417
+1418
+1419
+1420
+1421
+1422
+1423
+1424
+1425
+1426
+1427
+1428
+1429
+1430
+1431
@quam_dataclass
+class InOutIQChannel(IQChannel, InIQChannel):
+    """QuAM component for an IQ channel with both input and output.
+
+    An example of such a channel is a readout resonator, where you may want to
+    apply a readout tone and then measure the response.
+
+    Args:
+        operations (Dict[str, Pulse]): A dictionary of pulses to be played on this
+            channel. The key is the pulse label (e.g. "readout") and value is a
+            ReadoutPulse.
+        id (str, int): The id of the channel, used to generate the name.
+            Can be a string, or an integer in which case it will add
+            `Channel._default_label`.
+        opx_output_I (Tuple[str, int]): Channel I output port from the OPX perspective,
+            a tuple of (controller_name, port).
+        opx_output_Q (Tuple[str, int]): Channel Q output port from the OPX perspective,
+            a tuple of (controller_name, port).
+        opx_output_offset_I float: The offset of the I channel. Default is 0.
+        opx_output_offset_Q float: The offset of the Q channel. Default is 0.
+        opx_input_I (Tuple[str, int]): Channel I input port from the OPX perspective,
+            a tuple of (controller_name, port).
+        opx_input_Q (Tuple[str, int]): Channel Q input port from the OPX perspective,
+            a tuple of (controller_name, port).
+        opx_input_offset_I float: The offset of the I channel. Default is 0.
+        opx_input_offset_Q float: The offset of the Q channel. Default is 0.
+        intermediate_frequency (float): Intermediate frequency of the mixer.
+            Default is 0.0
+        LO_frequency (float): Local oscillator frequency. Default is the LO frequency
+            of the frequency converter up component.
+        RF_frequency (float): RF frequency of the mixer. By default, the RF frequency
+            is inferred by adding the LO frequency and the intermediate frequency.
+        frequency_converter_up (FrequencyConverter): Frequency converter QuAM component
+            for the IQ output.
+        frequency_converter_down (Optional[FrequencyConverter]): Frequency converter
+            QuAM component for the IQ input port. Only needed for the old Octave.
+        time_of_flight (int): Round-trip signal duration in nanoseconds.
+        smearing (int): Additional window of ADC integration in nanoseconds.
+            Used to account for signal smearing.
+    """
+
+    pass
+
+
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ +
+ + + +

+ InOutSingleChannel + + +

+ + +
+

+ Bases: SingleChannel, InSingleChannel

+ + +

QuAM component for a single (not IQ) input + output channel.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
operations + Dict[str, Pulse] + +
+

A dictionary of pulses to be played on this +channel. The key is the pulse label (e.g. "X90") and value is a Pulse.

+
+ 		+ required +
id + (str, int) + +
+

The id of the channel, used to generate the name. +Can be a string, or an integer in which case it will add +Channel._default_label.

+
+ 		+ required +
opx_output + Tuple[str, int] + +
+

Channel output port from the OPX perspective, +a tuple of (controller_name, port).

+
+ 		+ required +
opx_output_offset + float + +
+

DC offset for the output port.

+
+ 		+ required +
opx_input + Tuple[str, int] + +
+

Channel input port from OPX perspective, +a tuple of (controller_name, port).

+
+ 		+ required +
opx_input_offset + float + +
+

DC offset for the input port.

+
+ 		+ required +
filter_fir_taps + List[float] + +
+

FIR filter taps for the output port.

+
+ 		+ required +
filter_iir_taps + List[float] + +
+

IIR filter taps for the output port.

+
+ 		+ required +
intermediate_frequency + float + +
+

Intermediate frequency of OPX output, default +is None.

+
+ 		+ required +
time_of_flight + int + +
+

Round-trip signal duration in nanoseconds.

+
+ 		+ required +
smearing + int + +
+

Additional window of ADC integration in nanoseconds. +Used to account for signal smearing.

+
+ 		+ required +
+ +
+ Source code in quam/components/channels.py + 
1362
+1363
+1364
+1365
+1366
+1367
+1368
+1369
+1370
+1371
+1372
+1373
+1374
+1375
+1376
+1377
+1378
+1379
+1380
+1381
+1382
+1383
+1384
+1385
+1386
+1387
@quam_dataclass
+class InOutSingleChannel(SingleChannel, InSingleChannel):
+    """QuAM component for a single (not IQ) input + output channel.
+
+    Args:
+        operations (Dict[str, Pulse]): A dictionary of pulses to be played on this
+            channel. The key is the pulse label (e.g. "X90") and value is a Pulse.
+        id (str, int): The id of the channel, used to generate the name.
+            Can be a string, or an integer in which case it will add
+            `Channel._default_label`.
+        opx_output (Tuple[str, int]): Channel output port from the OPX perspective,
+            a tuple of (controller_name, port).
+        opx_output_offset (float): DC offset for the output port.
+        opx_input (Tuple[str, int]): Channel input port from OPX perspective,
+            a tuple of (controller_name, port).
+        opx_input_offset (float): DC offset for the input port.
+        filter_fir_taps (List[float]): FIR filter taps for the output port.
+        filter_iir_taps (List[float]): IIR filter taps for the output port.
+        intermediate_frequency (float): Intermediate frequency of OPX output, default
+            is None.
+        time_of_flight (int): Round-trip signal duration in nanoseconds.
+        smearing (int): Additional window of ADC integration in nanoseconds.
+            Used to account for signal smearing.
+    """
+
+    pass
+
+
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ +
+ + + +

+ InSingleChannel + + +

+ + +
+

+ Bases: Channel

+ + +

QuAM component for a single (not IQ) input channel.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
operations + Dict[str, Pulse] + +
+

A dictionary of pulses to be played on this +channel. The key is the pulse label (e.g. "X90") and value is a Pulse.

+
+ 		+ required +
id + (str, int) + +
+

The id of the channel, used to generate the name. +Can be a string, or an integer in which case it will add +Channel._default_label.

+
+ 		+ required +
opx_input + Tuple[str, int] + +
+

Channel input port from OPX perspective, +a tuple of (controller_name, port).

+
+ 		+ required +
opx_input_offset + float + +
+

DC offset for the input port.

+
+ 		+ required +
intermediate_frequency + float + +
+

Intermediate frequency of OPX input, +default is None.

+
+ 		+ required +
time_of_flight + int + +
+

Round-trip signal duration in nanoseconds.

+
+ 		+ required +
smearing + int + +
+

Additional window of ADC integration in nanoseconds. +Used to account for signal smearing.

+
+ 		+ required +
+ +
+ Source code in quam/components/channels.py + 
550
+551
+552
+553
+554
+555
+556
+557
+558
+559
+560
+561
+562
+563
+564
+565
+566
+567
+568
+569
+570
+571
+572
+573
+574
+575
+576
+577
+578
+579
+580
+581
+582
+583
+584
+585
+586
+587
+588
+589
+590
+591
+592
+593
+594
+595
+596
+597
+598
+599
+600
+601
+602
+603
+604
+605
+606
+607
+608
+609
+610
+611
+612
+613
+614
+615
+616
+617
+618
+619
+620
+621
+622
+623
+624
+625
+626
+627
+628
+629
+630
+631
+632
+633
+634
+635
+636
+637
+638
+639
+640
+641
+642
+643
+644
+645
+646
+647
+648
+649
+650
+651
+652
+653
+654
+655
+656
+657
+658
+659
+660
+661
+662
+663
+664
+665
+666
+667
+668
+669
+670
+671
+672
+673
+674
+675
+676
+677
+678
+679
+680
+681
+682
+683
+684
+685
+686
+687
+688
+689
+690
+691
+692
+693
+694
+695
+696
+697
+698
+699
+700
+701
+702
+703
+704
+705
+706
+707
+708
+709
+710
+711
+712
+713
+714
+715
+716
+717
+718
+719
+720
+721
+722
+723
+724
+725
+726
+727
+728
+729
+730
+731
+732
+733
+734
+735
+736
+737
+738
+739
+740
+741
+742
+743
+744
+745
+746
+747
+748
+749
+750
+751
+752
+753
+754
+755
+756
+757
+758
+759
+760
+761
+762
+763
+764
+765
+766
+767
+768
+769
+770
+771
+772
+773
+774
+775
+776
+777
+778
+779
+780
+781
+782
+783
+784
+785
+786
+787
+788
+789
+790
+791
+792
+793
+794
+795
+796
+797
+798
+799
+800
+801
+802
+803
+804
+805
+806
+807
+808
+809
+810
+811
+812
+813
+814
+815
+816
+817
+818
+819
+820
+821
+822
+823
@quam_dataclass
+class InSingleChannel(Channel):
+    """QuAM component for a single (not IQ) input channel.
+
+    Args:
+        operations (Dict[str, Pulse]): A dictionary of pulses to be played on this
+            channel. The key is the pulse label (e.g. "X90") and value is a Pulse.
+        id (str, int): The id of the channel, used to generate the name.
+            Can be a string, or an integer in which case it will add
+            `Channel._default_label`.
+        opx_input (Tuple[str, int]): Channel input port from OPX perspective,
+            a tuple of (controller_name, port).
+        opx_input_offset (float): DC offset for the input port.
+        intermediate_frequency (float): Intermediate frequency of OPX input,
+            default is None.
+        time_of_flight (int): Round-trip signal duration in nanoseconds.
+        smearing (int): Additional window of ADC integration in nanoseconds.
+            Used to account for signal smearing.
+    """
+
+    opx_input: Union[Tuple[str, int], Tuple[str, int, int], LFAnalogInputPort]
+    opx_input_offset: float = None
+
+    time_of_flight: int = 24
+    smearing: int = 0
+
+    def apply_to_config(self, config: dict):
+        """Adds this InSingleChannel to the QUA configuration.
+
+        See [`QuamComponent.apply_to_config`][quam.core.quam_classes.QuamComponent.apply_to_config]
+        for details.
+        """
+        # Add output to config
+        super().apply_to_config(config)
+
+        # Note outputs instead of inputs because it's w.r.t. the QPU
+        element_config = config["elements"][self.name]
+        element_config["smearing"] = self.smearing
+        element_config["time_of_flight"] = self.time_of_flight
+
+        if isinstance(self.opx_input, LFAnalogInputPort):
+            opx_port = self.opx_input
+        elif len(self.opx_input) == 2:
+            opx_port = OPXPlusAnalogInputPort(
+                *self.opx_input, offset=self.opx_input_offset
+            )
+            opx_port.apply_to_config(config)
+        else:
+            opx_port = LFFEMAnalogInputPort(
+                *self.opx_input, offset=self.opx_input_offset
+            )
+            opx_port.apply_to_config(config)
+
+        element_config["outputs"] = {"out1": opx_port.port_tuple}
+
+    def measure(
+        self,
+        pulse_name: str,
+        amplitude_scale: Union[float, AmpValuesType] = None,
+        qua_vars: Tuple[QuaVariableType, ...] = None,
+        stream=None,
+    ) -> Tuple[QuaVariableType, QuaVariableType]:
+        """Perform a full demodulation measurement on this channel.
+
+        Args:
+            pulse_name (str): The name of the pulse to play. Should be registered in
+                `self.operations`.
+            amplitude_scale (float, _PulseAmp): Amplitude scale of the pulse.
+                Can be either a float, or qua.amp(float).
+            qua_vars (Tuple[QuaVariableType, ...], optional): Two QUA
+                variables to store the I, Q measurement results.
+                If not provided, new variables will be declared and returned.
+            stream (Optional[StreamType]): The stream to save the measurement result to.
+                If not provided, the raw ADC signal will not be streamed.
+
+        Returns:
+            I, Q: The QUA variables used to store the measurement results.
+                If provided as input, the same variables will be returned.
+                If not provided, new variables will be declared and returned.
+
+        Raises:
+            ValueError: If `qua_vars` is provided and is not a tuple of two QUA
+                variables.
+        """
+
+        pulse: BaseReadoutPulse = self.operations[pulse_name]
+
+        if qua_vars is not None:
+            if not isinstance(qua_vars, Sequence) or len(qua_vars) != 2:
+                raise ValueError(
+                    f"InOutSingleChannel.measure received kwarg 'qua_vars' "
+                    f"which is not a tuple of two QUA variables. Received {qua_vars=}"
+                )
+        else:
+            qua_vars = [declare(fixed) for _ in range(2)]
+
+        if amplitude_scale is not None:
+            if not isinstance(amplitude_scale, _PulseAmp):
+                amplitude_scale = amp(amplitude_scale)
+            pulse_name *= amplitude_scale
+
+        integration_weight_labels = list(pulse.integration_weights_mapping)
+        measure(
+            pulse_name,
+            self.name,
+            stream,
+            demod.full(integration_weight_labels[0], qua_vars[0], "out1"),
+            demod.full(integration_weight_labels[1], qua_vars[1], "out1"),
+        )
+        return tuple(qua_vars)
+
+    def measure_accumulated(
+        self,
+        pulse_name: str,
+        amplitude_scale: Union[float, AmpValuesType] = None,
+        num_segments: int = None,
+        segment_length: int = None,
+        qua_vars: Tuple[QuaVariableType, ...] = None,
+        stream=None,
+    ) -> Tuple[QuaVariableType, QuaVariableType]:
+        """Perform an accumulated demodulation measurement on this channel.
+
+        Args:
+            pulse_name (str): The name of the pulse to play. Should be registered in
+                `self.operations`.
+            amplitude_scale (float, _PulseAmp): Amplitude scale of the pulse.
+                Can be either a float, or qua.amp(float).
+            num_segments (int): The number of segments to accumulate.
+                Should either specify this or `segment_length`.
+            segment_length (int): The length of the segment to accumulate.
+                Should either specify this or `num_segments`.
+            qua_vars (Tuple[QuaVariableType, ...], optional): Two QUA
+                variables to store the I, Q measurement results.
+                If not provided, new variables will be declared and returned.
+            stream (Optional[StreamType]): The stream to save the measurement result to.
+                If not provided, the raw ADC signal will not be streamed.
+
+        Returns:
+            I, Q: The QUA variables used to store the measurement results.
+                If provided as input, the same variables will be returned.
+                If not provided, new variables will be declared and returned.
+
+        Raises:
+            ValueError: If both `num_segments` and `segment_length` are provided, or if
+                neither are provided.
+            ValueError: If `qua_vars` is provided and is not a tuple of two QUA
+                variables.
+        """
+        pulse: BaseReadoutPulse = self.operations[pulse_name]
+
+        if num_segments is None and segment_length is None:
+            raise ValueError(
+                "InOutSingleChannel.measure_accumulated requires either 'segment_length' "
+                "or 'num_segments' to be provided."
+            )
+        elif num_segments is not None and segment_length is not None:
+            raise ValueError(
+                "InOutSingleChannel.measure_accumulated received both 'segment_length' "
+                "and 'num_segments'. Please provide only one."
+            )
+        elif num_segments is None:
+            num_segments = int(pulse.length / (4 * segment_length))  # Number of slices
+        elif segment_length is None:
+            segment_length = int(pulse.length / (4 * num_segments))
+
+        if qua_vars is not None:
+            if not isinstance(qua_vars, Sequence) or len(qua_vars) != 2:
+                raise ValueError(
+                    f"InOutSingleChannel.measure_accumulated received kwarg 'qua_vars' "
+                    f"which is not a tuple of two QUA variables. Received {qua_vars=}"
+                )
+        else:
+            qua_vars = [declare(fixed, size=num_segments) for _ in range(2)]
+
+        if amplitude_scale is not None:
+            if not isinstance(amplitude_scale, _PulseAmp):
+                amplitude_scale = amp(amplitude_scale)
+            pulse_name *= amplitude_scale
+
+        integration_weight_labels = list(pulse.integration_weights_mapping)
+        measure(
+            pulse_name,
+            self.name,
+            stream,
+            demod.accumulated(
+                integration_weight_labels[0], qua_vars[0], segment_length, "out1"
+            ),
+            demod.accumulated(
+                integration_weight_labels[1], qua_vars[1], segment_length, "out1"
+            ),
+        )
+        return tuple(qua_vars)
+
+    def measure_sliced(
+        self,
+        pulse_name: str,
+        amplitude_scale: Union[float, AmpValuesType] = None,
+        num_segments: int = None,
+        segment_length: int = None,
+        qua_vars: Tuple[QuaVariableType, ...] = None,
+        stream=None,
+    ) -> Tuple[QuaVariableType, QuaVariableType]:
+        """Perform an accumulated demodulation measurement on this channel.
+
+        Args:
+            pulse_name (str): The name of the pulse to play. Should be registered in
+                `self.operations`.
+            amplitude_scale (float, _PulseAmp): Amplitude scale of the pulse.
+                Can be either a float, or qua.amp(float).
+            num_segments (int): The number of segments to accumulate.
+                Should either specify this or `segment_length`.
+            segment_length (int): The length of the segment to accumulate.
+                Should either specify this or `num_segments`.
+            qua_vars (Tuple[QuaVariableType, ...], optional): Two QUA
+                variables to store the I, Q measurement results.
+                If not provided, new variables will be declared and returned.
+            stream (Optional[StreamType]): The stream to save the measurement result to.
+                If not provided, the raw ADC signal will not be streamed.
+
+        Returns:
+            I, Q: The QUA variables used to store the measurement results.
+                If provided as input, the same variables will be returned.
+                If not provided, new variables will be declared and returned.
+
+        Raises:
+            ValueError: If both `num_segments` and `segment_length` are provided, or if
+                neither are provided.
+            ValueError: If `qua_vars` is provided and is not a tuple of two QUA
+                variables.
+        """
+        pulse: BaseReadoutPulse = self.operations[pulse_name]
+
+        if num_segments is None and segment_length is None:
+            raise ValueError(
+                "InOutSingleChannel.measure_sliced requires either 'segment_length' "
+                "or 'num_segments' to be provided."
+            )
+        elif num_segments is not None and segment_length is not None:
+            raise ValueError(
+                "InOutSingleChannel.measure_sliced received both 'segment_length' "
+                "and 'num_segments'. Please provide only one."
+            )
+        elif num_segments is None:
+            num_segments = int(pulse.length / (4 * segment_length))  # Number of slices
+        elif segment_length is None:
+            segment_length = int(pulse.length / (4 * num_segments))
+
+        if qua_vars is not None:
+            if not isinstance(qua_vars, Sequence) or len(qua_vars) != 2:
+                raise ValueError(
+                    f"InOutSingleChannel.measure_sliced received kwarg 'qua_vars' "
+                    f"which is not a tuple of two QUA variables. Received {qua_vars=}"
+                )
+        else:
+            qua_vars = [declare(fixed, size=num_segments) for _ in range(2)]
+
+        if amplitude_scale is not None:
+            if not isinstance(amplitude_scale, _PulseAmp):
+                amplitude_scale = amp(amplitude_scale)
+            pulse_name *= amplitude_scale
+
+        integration_weight_labels = list(pulse.integration_weights_mapping)
+        measure(
+            pulse_name,
+            self.name,
+            stream,
+            demod.sliced(
+                integration_weight_labels[0], qua_vars[0], segment_length, "out1"
+            ),
+            demod.sliced(
+                integration_weight_labels[1], qua_vars[1], segment_length, "out1"
+            ),
+        )
+        return tuple(qua_vars)
+
+
+ + + +
+ + + + + + + + + +
+ + +

+ apply_to_config(config) + +

+ + +
+ +

Adds this InSingleChannel to the QUA configuration.

+

See QuamComponent.apply_to_config +for details.

+ +
+ Source code in quam/components/channels.py + 
576
+577
+578
+579
+580
+581
+582
+583
+584
+585
+586
+587
+588
+589
+590
+591
+592
+593
+594
+595
+596
+597
+598
+599
+600
+601
+602
+603
def apply_to_config(self, config: dict):
+    """Adds this InSingleChannel to the QUA configuration.
+
+    See [`QuamComponent.apply_to_config`][quam.core.quam_classes.QuamComponent.apply_to_config]
+    for details.
+    """
+    # Add output to config
+    super().apply_to_config(config)
+
+    # Note outputs instead of inputs because it's w.r.t. the QPU
+    element_config = config["elements"][self.name]
+    element_config["smearing"] = self.smearing
+    element_config["time_of_flight"] = self.time_of_flight
+
+    if isinstance(self.opx_input, LFAnalogInputPort):
+        opx_port = self.opx_input
+    elif len(self.opx_input) == 2:
+        opx_port = OPXPlusAnalogInputPort(
+            *self.opx_input, offset=self.opx_input_offset
+        )
+        opx_port.apply_to_config(config)
+    else:
+        opx_port = LFFEMAnalogInputPort(
+            *self.opx_input, offset=self.opx_input_offset
+        )
+        opx_port.apply_to_config(config)
+
+    element_config["outputs"] = {"out1": opx_port.port_tuple}
+
+
+
+ +
+ +
+ + +

+ measure(pulse_name, amplitude_scale=None, qua_vars=None, stream=None) + +

+ + +
+ +

Perform a full demodulation measurement on this channel.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
pulse_name + str + +
+

The name of the pulse to play. Should be registered in +self.operations.

+
+ 		+ required +
amplitude_scale + (float, _PulseAmp) + +
+

Amplitude scale of the pulse. +Can be either a float, or qua.amp(float).

+
+ 		+ None +
qua_vars + Tuple[QuaVariableType, ...] + +
+

Two QUA +variables to store the I, Q measurement results. +If not provided, new variables will be declared and returned.

+
+ 		+ None +
stream + Optional[StreamType] + +
+

The stream to save the measurement result to. +If not provided, the raw ADC signal will not be streamed.

+
+ 		+ None +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ Tuple[QuaVariableType, QuaVariableType] + +
+

I, Q: The QUA variables used to store the measurement results. +If provided as input, the same variables will be returned. +If not provided, new variables will be declared and returned.

+
+
+ + +

Raises:

+ + + + + + + + + + + + + +
TypeDescription
+ ValueError + +
+

If qua_vars is provided and is not a tuple of two QUA +variables.

+
+
+ +
+ Source code in quam/components/channels.py + 
605
+606
+607
+608
+609
+610
+611
+612
+613
+614
+615
+616
+617
+618
+619
+620
+621
+622
+623
+624
+625
+626
+627
+628
+629
+630
+631
+632
+633
+634
+635
+636
+637
+638
+639
+640
+641
+642
+643
+644
+645
+646
+647
+648
+649
+650
+651
+652
+653
+654
+655
+656
+657
+658
+659
def measure(
+    self,
+    pulse_name: str,
+    amplitude_scale: Union[float, AmpValuesType] = None,
+    qua_vars: Tuple[QuaVariableType, ...] = None,
+    stream=None,
+) -> Tuple[QuaVariableType, QuaVariableType]:
+    """Perform a full demodulation measurement on this channel.
+
+    Args:
+        pulse_name (str): The name of the pulse to play. Should be registered in
+            `self.operations`.
+        amplitude_scale (float, _PulseAmp): Amplitude scale of the pulse.
+            Can be either a float, or qua.amp(float).
+        qua_vars (Tuple[QuaVariableType, ...], optional): Two QUA
+            variables to store the I, Q measurement results.
+            If not provided, new variables will be declared and returned.
+        stream (Optional[StreamType]): The stream to save the measurement result to.
+            If not provided, the raw ADC signal will not be streamed.
+
+    Returns:
+        I, Q: The QUA variables used to store the measurement results.
+            If provided as input, the same variables will be returned.
+            If not provided, new variables will be declared and returned.
+
+    Raises:
+        ValueError: If `qua_vars` is provided and is not a tuple of two QUA
+            variables.
+    """
+
+    pulse: BaseReadoutPulse = self.operations[pulse_name]
+
+    if qua_vars is not None:
+        if not isinstance(qua_vars, Sequence) or len(qua_vars) != 2:
+            raise ValueError(
+                f"InOutSingleChannel.measure received kwarg 'qua_vars' "
+                f"which is not a tuple of two QUA variables. Received {qua_vars=}"
+            )
+    else:
+        qua_vars = [declare(fixed) for _ in range(2)]
+
+    if amplitude_scale is not None:
+        if not isinstance(amplitude_scale, _PulseAmp):
+            amplitude_scale = amp(amplitude_scale)
+        pulse_name *= amplitude_scale
+
+    integration_weight_labels = list(pulse.integration_weights_mapping)
+    measure(
+        pulse_name,
+        self.name,
+        stream,
+        demod.full(integration_weight_labels[0], qua_vars[0], "out1"),
+        demod.full(integration_weight_labels[1], qua_vars[1], "out1"),
+    )
+    return tuple(qua_vars)
+
+
+
+ +
+ +
+ + +

+ measure_accumulated(pulse_name, amplitude_scale=None, num_segments=None, segment_length=None, qua_vars=None, stream=None) + +

+ + +
+ +

Perform an accumulated demodulation measurement on this channel.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
pulse_name + str + +
+

The name of the pulse to play. Should be registered in +self.operations.

+
+ 		+ required +
amplitude_scale + (float, _PulseAmp) + +
+

Amplitude scale of the pulse. +Can be either a float, or qua.amp(float).

+
+ 		+ None +
num_segments + int + +
+

The number of segments to accumulate. +Should either specify this or segment_length.

+
+ 		+ None +
segment_length + int + +
+

The length of the segment to accumulate. +Should either specify this or num_segments.

+
+ 		+ None +
qua_vars + Tuple[QuaVariableType, ...] + +
+

Two QUA +variables to store the I, Q measurement results. +If not provided, new variables will be declared and returned.

+
+ 		+ None +
stream + Optional[StreamType] + +
+

The stream to save the measurement result to. +If not provided, the raw ADC signal will not be streamed.

+
+ 		+ None +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ Tuple[QuaVariableType, QuaVariableType] + +
+

I, Q: The QUA variables used to store the measurement results. +If provided as input, the same variables will be returned. +If not provided, new variables will be declared and returned.

+
+
+ + +

Raises:

+ + + + + + + + + + + + + + + + + +
TypeDescription
+ ValueError + +
+

If both num_segments and segment_length are provided, or if +neither are provided.

+
+
+ ValueError + +
+

If qua_vars is provided and is not a tuple of two QUA +variables.

+
+
+ +
+ Source code in quam/components/channels.py + 
661
+662
+663
+664
+665
+666
+667
+668
+669
+670
+671
+672
+673
+674
+675
+676
+677
+678
+679
+680
+681
+682
+683
+684
+685
+686
+687
+688
+689
+690
+691
+692
+693
+694
+695
+696
+697
+698
+699
+700
+701
+702
+703
+704
+705
+706
+707
+708
+709
+710
+711
+712
+713
+714
+715
+716
+717
+718
+719
+720
+721
+722
+723
+724
+725
+726
+727
+728
+729
+730
+731
+732
+733
+734
+735
+736
+737
+738
+739
+740
+741
def measure_accumulated(
+    self,
+    pulse_name: str,
+    amplitude_scale: Union[float, AmpValuesType] = None,
+    num_segments: int = None,
+    segment_length: int = None,
+    qua_vars: Tuple[QuaVariableType, ...] = None,
+    stream=None,
+) -> Tuple[QuaVariableType, QuaVariableType]:
+    """Perform an accumulated demodulation measurement on this channel.
+
+    Args:
+        pulse_name (str): The name of the pulse to play. Should be registered in
+            `self.operations`.
+        amplitude_scale (float, _PulseAmp): Amplitude scale of the pulse.
+            Can be either a float, or qua.amp(float).
+        num_segments (int): The number of segments to accumulate.
+            Should either specify this or `segment_length`.
+        segment_length (int): The length of the segment to accumulate.
+            Should either specify this or `num_segments`.
+        qua_vars (Tuple[QuaVariableType, ...], optional): Two QUA
+            variables to store the I, Q measurement results.
+            If not provided, new variables will be declared and returned.
+        stream (Optional[StreamType]): The stream to save the measurement result to.
+            If not provided, the raw ADC signal will not be streamed.
+
+    Returns:
+        I, Q: The QUA variables used to store the measurement results.
+            If provided as input, the same variables will be returned.
+            If not provided, new variables will be declared and returned.
+
+    Raises:
+        ValueError: If both `num_segments` and `segment_length` are provided, or if
+            neither are provided.
+        ValueError: If `qua_vars` is provided and is not a tuple of two QUA
+            variables.
+    """
+    pulse: BaseReadoutPulse = self.operations[pulse_name]
+
+    if num_segments is None and segment_length is None:
+        raise ValueError(
+            "InOutSingleChannel.measure_accumulated requires either 'segment_length' "
+            "or 'num_segments' to be provided."
+        )
+    elif num_segments is not None and segment_length is not None:
+        raise ValueError(
+            "InOutSingleChannel.measure_accumulated received both 'segment_length' "
+            "and 'num_segments'. Please provide only one."
+        )
+    elif num_segments is None:
+        num_segments = int(pulse.length / (4 * segment_length))  # Number of slices
+    elif segment_length is None:
+        segment_length = int(pulse.length / (4 * num_segments))
+
+    if qua_vars is not None:
+        if not isinstance(qua_vars, Sequence) or len(qua_vars) != 2:
+            raise ValueError(
+                f"InOutSingleChannel.measure_accumulated received kwarg 'qua_vars' "
+                f"which is not a tuple of two QUA variables. Received {qua_vars=}"
+            )
+    else:
+        qua_vars = [declare(fixed, size=num_segments) for _ in range(2)]
+
+    if amplitude_scale is not None:
+        if not isinstance(amplitude_scale, _PulseAmp):
+            amplitude_scale = amp(amplitude_scale)
+        pulse_name *= amplitude_scale
+
+    integration_weight_labels = list(pulse.integration_weights_mapping)
+    measure(
+        pulse_name,
+        self.name,
+        stream,
+        demod.accumulated(
+            integration_weight_labels[0], qua_vars[0], segment_length, "out1"
+        ),
+        demod.accumulated(
+            integration_weight_labels[1], qua_vars[1], segment_length, "out1"
+        ),
+    )
+    return tuple(qua_vars)
+
+
+
+ +
+ +
+ + +

+ measure_sliced(pulse_name, amplitude_scale=None, num_segments=None, segment_length=None, qua_vars=None, stream=None) + +

+ + +
+ +

Perform an accumulated demodulation measurement on this channel.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
pulse_name + str + +
+

The name of the pulse to play. Should be registered in +self.operations.

+
+ 		+ required +
amplitude_scale + (float, _PulseAmp) + +
+

Amplitude scale of the pulse. +Can be either a float, or qua.amp(float).

+
+ 		+ None +
num_segments + int + +
+

The number of segments to accumulate. +Should either specify this or segment_length.

+
+ 		+ None +
segment_length + int + +
+

The length of the segment to accumulate. +Should either specify this or num_segments.

+
+ 		+ None +
qua_vars + Tuple[QuaVariableType, ...] + +
+

Two QUA +variables to store the I, Q measurement results. +If not provided, new variables will be declared and returned.

+
+ 		+ None +
stream + Optional[StreamType] + +
+

The stream to save the measurement result to. +If not provided, the raw ADC signal will not be streamed.

+
+ 		+ None +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ Tuple[QuaVariableType, QuaVariableType] + +
+

I, Q: The QUA variables used to store the measurement results. +If provided as input, the same variables will be returned. +If not provided, new variables will be declared and returned.

+
+
+ + +

Raises:

+ + + + + + + + + + + + + + + + + +
TypeDescription
+ ValueError + +
+

If both num_segments and segment_length are provided, or if +neither are provided.

+
+
+ ValueError + +
+

If qua_vars is provided and is not a tuple of two QUA +variables.

+
+
+ +
+ Source code in quam/components/channels.py + 
743
+744
+745
+746
+747
+748
+749
+750
+751
+752
+753
+754
+755
+756
+757
+758
+759
+760
+761
+762
+763
+764
+765
+766
+767
+768
+769
+770
+771
+772
+773
+774
+775
+776
+777
+778
+779
+780
+781
+782
+783
+784
+785
+786
+787
+788
+789
+790
+791
+792
+793
+794
+795
+796
+797
+798
+799
+800
+801
+802
+803
+804
+805
+806
+807
+808
+809
+810
+811
+812
+813
+814
+815
+816
+817
+818
+819
+820
+821
+822
+823
def measure_sliced(
+    self,
+    pulse_name: str,
+    amplitude_scale: Union[float, AmpValuesType] = None,
+    num_segments: int = None,
+    segment_length: int = None,
+    qua_vars: Tuple[QuaVariableType, ...] = None,
+    stream=None,
+) -> Tuple[QuaVariableType, QuaVariableType]:
+    """Perform an accumulated demodulation measurement on this channel.
+
+    Args:
+        pulse_name (str): The name of the pulse to play. Should be registered in
+            `self.operations`.
+        amplitude_scale (float, _PulseAmp): Amplitude scale of the pulse.
+            Can be either a float, or qua.amp(float).
+        num_segments (int): The number of segments to accumulate.
+            Should either specify this or `segment_length`.
+        segment_length (int): The length of the segment to accumulate.
+            Should either specify this or `num_segments`.
+        qua_vars (Tuple[QuaVariableType, ...], optional): Two QUA
+            variables to store the I, Q measurement results.
+            If not provided, new variables will be declared and returned.
+        stream (Optional[StreamType]): The stream to save the measurement result to.
+            If not provided, the raw ADC signal will not be streamed.
+
+    Returns:
+        I, Q: The QUA variables used to store the measurement results.
+            If provided as input, the same variables will be returned.
+            If not provided, new variables will be declared and returned.
+
+    Raises:
+        ValueError: If both `num_segments` and `segment_length` are provided, or if
+            neither are provided.
+        ValueError: If `qua_vars` is provided and is not a tuple of two QUA
+            variables.
+    """
+    pulse: BaseReadoutPulse = self.operations[pulse_name]
+
+    if num_segments is None and segment_length is None:
+        raise ValueError(
+            "InOutSingleChannel.measure_sliced requires either 'segment_length' "
+            "or 'num_segments' to be provided."
+        )
+    elif num_segments is not None and segment_length is not None:
+        raise ValueError(
+            "InOutSingleChannel.measure_sliced received both 'segment_length' "
+            "and 'num_segments'. Please provide only one."
+        )
+    elif num_segments is None:
+        num_segments = int(pulse.length / (4 * segment_length))  # Number of slices
+    elif segment_length is None:
+        segment_length = int(pulse.length / (4 * num_segments))
+
+    if qua_vars is not None:
+        if not isinstance(qua_vars, Sequence) or len(qua_vars) != 2:
+            raise ValueError(
+                f"InOutSingleChannel.measure_sliced received kwarg 'qua_vars' "
+                f"which is not a tuple of two QUA variables. Received {qua_vars=}"
+            )
+    else:
+        qua_vars = [declare(fixed, size=num_segments) for _ in range(2)]
+
+    if amplitude_scale is not None:
+        if not isinstance(amplitude_scale, _PulseAmp):
+            amplitude_scale = amp(amplitude_scale)
+        pulse_name *= amplitude_scale
+
+    integration_weight_labels = list(pulse.integration_weights_mapping)
+    measure(
+        pulse_name,
+        self.name,
+        stream,
+        demod.sliced(
+            integration_weight_labels[0], qua_vars[0], segment_length, "out1"
+        ),
+        demod.sliced(
+            integration_weight_labels[1], qua_vars[1], segment_length, "out1"
+        ),
+    )
+    return tuple(qua_vars)
+
+
+
+ +
+ + + +
+ +
+ +
+ +
+ + + +

+ InSingleOutIQChannel + + +

+ + +
+

+ Bases: IQChannel, InSingleChannel

+ + +

QuAM component for an IQ output channel with a single input.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
operations + Dict[str, Pulse] + +
+

A dictionary of pulses to be played on this +channel. The key is the pulse label (e.g. "readout") and value is a +ReadoutPulse.

+
+ 		+ required +
id + (str, int) + +
+

The id of the channel, used to generate the name. +Can be a string, or an integer in which case it will add +Channel._default_label.

+
+ 		+ required +
opx_output_I + Tuple[str, int] + +
+

Channel I output port from the OPX perspective, +a tuple of (controller_name, port).

+
+ 		+ required +
opx_output_Q + Tuple[str, int] + +
+

Channel Q output port from the OPX perspective, +a tuple of (controller_name, port).

+
+ 		+ required +
opx_output_offset_I + float + +
+

The offset of the I channel. Default is 0.

+
+ 		+ required +
opx_output_offset_Q + float + +
+

The offset of the Q channel. Default is 0.

+
+ 		+ required +
opx_input + Tuple[str, int] + +
+

Channel input port from OPX perspective, +a tuple of (controller_name, port).

+
+ 		+ required +
opx_input_offset + float + +
+

DC offset for the input port.

+
+ 		+ required +
intermediate_frequency + float + +
+

Intermediate frequency of the mixer. +Default is 0.0

+
+ 		+ required +
LO_frequency + float + +
+

Local oscillator frequency. Default is the LO frequency +of the frequency converter up component.

+
+ 		+ required +
RF_frequency + float + +
+

RF frequency of the mixer. By default, the RF frequency +is inferred by adding the LO frequency and the intermediate frequency.

+
+ 		+ required +
frequency_converter_up + FrequencyConverter + +
+

Frequency converter QuAM component +for the IQ output.

+
+ 		+ required +
time_of_flight + int + +
+

Round-trip signal duration in nanoseconds.

+
+ 		+ required +
smearing + int + +
+

Additional window of ADC integration in nanoseconds. +Used to account for signal smearing.

+
+ 		+ required +
+ +
+ Source code in quam/components/channels.py + 
1434
+1435
+1436
+1437
+1438
+1439
+1440
+1441
+1442
+1443
+1444
+1445
+1446
+1447
+1448
+1449
+1450
+1451
+1452
+1453
+1454
+1455
+1456
+1457
+1458
+1459
+1460
+1461
+1462
+1463
+1464
+1465
+1466
+1467
@quam_dataclass
+class InSingleOutIQChannel(IQChannel, InSingleChannel):
+    """QuAM component for an IQ output channel with a single input.
+
+    Args:
+        operations (Dict[str, Pulse]): A dictionary of pulses to be played on this
+            channel. The key is the pulse label (e.g. "readout") and value is a
+            ReadoutPulse.
+        id (str, int): The id of the channel, used to generate the name.
+            Can be a string, or an integer in which case it will add
+            `Channel._default_label`.
+        opx_output_I (Tuple[str, int]): Channel I output port from the OPX perspective,
+            a tuple of (controller_name, port).
+        opx_output_Q (Tuple[str, int]): Channel Q output port from the OPX perspective,
+            a tuple of (controller_name, port).
+        opx_output_offset_I float: The offset of the I channel. Default is 0.
+        opx_output_offset_Q float: The offset of the Q channel. Default is 0.
+        opx_input (Tuple[str, int]): Channel input port from OPX perspective,
+            a tuple of (controller_name, port).
+        opx_input_offset (float): DC offset for the input port.
+        intermediate_frequency (float): Intermediate frequency of the mixer.
+            Default is 0.0
+        LO_frequency (float): Local oscillator frequency. Default is the LO frequency
+            of the frequency converter up component.
+        RF_frequency (float): RF frequency of the mixer. By default, the RF frequency
+            is inferred by adding the LO frequency and the intermediate frequency.
+        frequency_converter_up (FrequencyConverter): Frequency converter QuAM component
+            for the IQ output.
+        time_of_flight (int): Round-trip signal duration in nanoseconds.
+        smearing (int): Additional window of ADC integration in nanoseconds.
+            Used to account for signal smearing.
+    """
+
+    pass
+
+
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ +
+ + + +

+ SingleChannel + + +

+ + +
+

+ Bases: Channel

+ + +

QuAM component for a single (not IQ) output channel.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
operations + Dict[str, Pulse] + +
+

A dictionary of pulses to be played on this +channel. The key is the pulse label (e.g. "X90") and value is a Pulse.

+
+ 		+ required +
id + (str, int) + +
+

The id of the channel, used to generate the name. +Can be a string, or an integer in which case it will add +Channel._default_label.

+
+ 		+ required +
opx_output + Tuple[str, int] + +
+

Channel output port from the OPX perspective, +a tuple of (controller_name, port).

+
+ 		+ required +
filter_fir_taps + List[float] + +
+

FIR filter taps for the output port.

+
+ 		+ required +
filter_iir_taps + List[float] + +
+

IIR filter taps for the output port.

+
+ 		+ required +
opx_output_offset + float + +
+

DC offset for the output port.

+
+ 		+ required +
intermediate_frequency + float + +
+

Intermediate frequency of OPX output, default +is None.

+
+ 		+ required +
+ +
+ Source code in quam/components/channels.py + 
461
+462
+463
+464
+465
+466
+467
+468
+469
+470
+471
+472
+473
+474
+475
+476
+477
+478
+479
+480
+481
+482
+483
+484
+485
+486
+487
+488
+489
+490
+491
+492
+493
+494
+495
+496
+497
+498
+499
+500
+501
+502
+503
+504
+505
+506
+507
+508
+509
+510
+511
+512
+513
+514
+515
+516
+517
+518
+519
+520
+521
+522
+523
+524
+525
+526
+527
+528
+529
+530
+531
+532
+533
+534
+535
+536
+537
+538
+539
+540
+541
+542
+543
+544
+545
+546
+547
@quam_dataclass
+class SingleChannel(Channel):
+    """QuAM component for a single (not IQ) output channel.
+
+    Args:
+        operations (Dict[str, Pulse]): A dictionary of pulses to be played on this
+            channel. The key is the pulse label (e.g. "X90") and value is a Pulse.
+        id (str, int): The id of the channel, used to generate the name.
+            Can be a string, or an integer in which case it will add
+            `Channel._default_label`.
+        opx_output (Tuple[str, int]): Channel output port from the OPX perspective,
+            a tuple of (controller_name, port).
+        filter_fir_taps (List[float]): FIR filter taps for the output port.
+        filter_iir_taps (List[float]): IIR filter taps for the output port.
+        opx_output_offset (float): DC offset for the output port.
+        intermediate_frequency (float): Intermediate frequency of OPX output, default
+            is None.
+    """
+
+    opx_output: Union[Tuple[str, int], Tuple[str, int, int], LFAnalogOutputPort]
+    filter_fir_taps: List[float] = None
+    filter_iir_taps: List[float] = None
+
+    opx_output_offset: float = None
+    intermediate_frequency: float = None
+
+    def set_dc_offset(self, offset: QuaNumberType):
+        """Set the DC offset of an element's input to the given value.
+        This value will remain the DC offset until changed or until the Quantum Machine
+        is closed.
+
+        Args:
+            offset (QuaNumberType): The DC offset to set the input to.
+                This is limited by the OPX output voltage range.
+                The number can be a QUA variable
+        """
+        set_dc_offset(element=self.name, element_input="single", offset=offset)
+
+    def apply_to_config(self, config: dict):
+        """Adds this SingleChannel to the QUA configuration.
+
+        See [`QuamComponent.apply_to_config`][quam.core.quam_classes.QuamComponent.apply_to_config]
+        for details.
+        """
+        # Add pulses & waveforms
+        super().apply_to_config(config)
+
+        if str_ref.is_reference(self.name):
+            raise AttributeError(
+                f"Channel {self.get_reference()} cannot be added to the config because"
+                " it doesn't have a name. Either set channel.id to a string or"
+                " integer, or channel should be an attribute of another QuAM component"
+                " with a name."
+            )
+
+        element_config = config["elements"][self.name]
+
+        if self.intermediate_frequency is not None:
+            element_config["intermediate_frequency"] = self.intermediate_frequency
+
+        filter_fir_taps = self.filter_fir_taps
+        if filter_fir_taps is not None:
+            filter_fir_taps = list(filter_fir_taps)
+        filter_iir_taps = self.filter_iir_taps
+        if filter_iir_taps is not None:
+            filter_iir_taps = list(filter_iir_taps)
+
+        if isinstance(self.opx_output, LFAnalogOutputPort):
+            opx_port = self.opx_output
+        elif len(self.opx_output) == 2:
+            opx_port = OPXPlusAnalogOutputPort(
+                *self.opx_output,
+                offset=self.opx_output_offset,
+                feedforward_filter=filter_fir_taps,
+                feedback_filter=filter_iir_taps,
+            )
+            opx_port.apply_to_config(config)
+        else:
+            opx_port = LFFEMAnalogOutputPort(
+                *self.opx_output,
+                offset=self.opx_output_offset,
+                feedforward_filter=filter_fir_taps,
+                feedback_filter=filter_iir_taps,
+            )
+            opx_port.apply_to_config(config)
+
+        element_config["singleInput"] = {"port": opx_port.port_tuple}
+
+
+ + + +
+ + + + + + + + + +
+ + +

+ apply_to_config(config) + +

+ + +
+ +

Adds this SingleChannel to the QUA configuration.

+

See QuamComponent.apply_to_config +for details.

+ +
+ Source code in quam/components/channels.py + 
499
+500
+501
+502
+503
+504
+505
+506
+507
+508
+509
+510
+511
+512
+513
+514
+515
+516
+517
+518
+519
+520
+521
+522
+523
+524
+525
+526
+527
+528
+529
+530
+531
+532
+533
+534
+535
+536
+537
+538
+539
+540
+541
+542
+543
+544
+545
+546
+547
def apply_to_config(self, config: dict):
+    """Adds this SingleChannel to the QUA configuration.
+
+    See [`QuamComponent.apply_to_config`][quam.core.quam_classes.QuamComponent.apply_to_config]
+    for details.
+    """
+    # Add pulses & waveforms
+    super().apply_to_config(config)
+
+    if str_ref.is_reference(self.name):
+        raise AttributeError(
+            f"Channel {self.get_reference()} cannot be added to the config because"
+            " it doesn't have a name. Either set channel.id to a string or"
+            " integer, or channel should be an attribute of another QuAM component"
+            " with a name."
+        )
+
+    element_config = config["elements"][self.name]
+
+    if self.intermediate_frequency is not None:
+        element_config["intermediate_frequency"] = self.intermediate_frequency
+
+    filter_fir_taps = self.filter_fir_taps
+    if filter_fir_taps is not None:
+        filter_fir_taps = list(filter_fir_taps)
+    filter_iir_taps = self.filter_iir_taps
+    if filter_iir_taps is not None:
+        filter_iir_taps = list(filter_iir_taps)
+
+    if isinstance(self.opx_output, LFAnalogOutputPort):
+        opx_port = self.opx_output
+    elif len(self.opx_output) == 2:
+        opx_port = OPXPlusAnalogOutputPort(
+            *self.opx_output,
+            offset=self.opx_output_offset,
+            feedforward_filter=filter_fir_taps,
+            feedback_filter=filter_iir_taps,
+        )
+        opx_port.apply_to_config(config)
+    else:
+        opx_port = LFFEMAnalogOutputPort(
+            *self.opx_output,
+            offset=self.opx_output_offset,
+            feedforward_filter=filter_fir_taps,
+            feedback_filter=filter_iir_taps,
+        )
+        opx_port.apply_to_config(config)
+
+    element_config["singleInput"] = {"port": opx_port.port_tuple}
+
+
+
+ +
+ +
+ + +

+ set_dc_offset(offset) + +

+ + +
+ +

Set the DC offset of an element's input to the given value. +This value will remain the DC offset until changed or until the Quantum Machine +is closed.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
offset + QuaNumberType + +
+

The DC offset to set the input to. +This is limited by the OPX output voltage range. +The number can be a QUA variable

+
+ 		+ required +
+ +
+ Source code in quam/components/channels.py + 
487
+488
+489
+490
+491
+492
+493
+494
+495
+496
+497
def set_dc_offset(self, offset: QuaNumberType):
+    """Set the DC offset of an element's input to the given value.
+    This value will remain the DC offset until changed or until the Quantum Machine
+    is closed.
+
+    Args:
+        offset (QuaNumberType): The DC offset to set the input to.
+            This is limited by the OPX output voltage range.
+            The number can be a QUA variable
+    """
+    set_dc_offset(element=self.name, element_input="single", offset=offset)
+
+
+
+ +
+ + + +
+ +
+ +
+ + + + +
+ +
+ +
+ + + + + + + + + + + + + +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API_references/components/hardware/index.html b/API_references/components/hardware/index.html new file mode 100644 index 00000000..a6566aa3 --- /dev/null +++ b/API_references/components/hardware/index.html @@ -0,0 +1,1619 @@ + + + + + + + + + + + + + + + + + + + + + Hardware - The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ + + + +

Hardware

+ +
+ + + + +
+ + + +
+ + + + + + + + +
+ + + +

+ BaseFrequencyConverter + + +

+ + +
+

+ Bases: QuamComponent

+ + +

Base class for frequency converters.

+ +
+ Source code in quam/components/hardware.py + 
110
+111
+112
+113
+114
@quam_dataclass
+class BaseFrequencyConverter(QuamComponent):
+    """Base class for frequency converters."""
+
+    pass
+
+
+ +
+ +
+ +
+ + + +

+ FrequencyConverter + + +

+ + +
+

+ Bases: BaseFrequencyConverter

+ + +

Frequency up/down converter component.

+

This component encapsulates the local oscillator and mixer used to upconvert or +downconvert an RF signal.

+

The FrequencyConverter component is attached to IQ channels through

+
    +
  • IQChannel.frequency_converter_up
    • +
  • InOutIQChannel.frequency_converter_down
    • +
+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
local_oscillator + LocalOscillator + +
+

The local oscillator for the frequency converter.

+
+ 		+ required +
mixer + Mixer + +
+

The mixer for the frequency converter.

+
+ 		+ required +
gain + float + +
+

The gain of the frequency converter.

+
+ 		+ required +
+ +
+ Source code in quam/components/hardware.py + 
117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
@quam_dataclass
+class FrequencyConverter(BaseFrequencyConverter):
+    """Frequency up/down converter component.
+
+    This component encapsulates the local oscillator and mixer used to upconvert or
+    downconvert an RF signal.
+
+    The FrequencyConverter component is attached to IQ channels through
+
+    - `IQChannel.frequency_converter_up`
+    - `InOutIQChannel.frequency_converter_down`
+
+    Args:
+        local_oscillator (LocalOscillator): The local oscillator for the frequency converter.
+        mixer (Mixer): The mixer for the frequency converter.
+        gain (float): The gain of the frequency converter.
+    """
+
+    local_oscillator: LocalOscillator = None
+    mixer: Mixer = None
+    gain: float = None
+
+    @property
+    def LO_frequency(self):
+        return self.local_oscillator.frequency
+
+    def configure(self):
+        if self.local_oscillator is not None:
+            self.local_oscillator.configure()
+
+
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ +
+ + + +

+ LocalOscillator + + +

+ + +
+

+ Bases: QuamComponent

+ + +

QuAM component for a local oscillator.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
frequency + float + +
+

The frequency of the local oscillator. +Used by the mixer to determine the intermediate frequency.

+
+ 		+ required +
power + float + +
+

The power of the local oscillator. +Not used for the QUA configuration

+
+ 		+ required +
+ +
+ Source code in quam/components/hardware.py + 
15
+16
+17
+18
+19
+20
+21
+22
+23
+24
+25
+26
+27
+28
+29
@quam_dataclass
+class LocalOscillator(QuamComponent):
+    """QuAM component for a local oscillator.
+
+    Args:
+        frequency (float): The frequency of the local oscillator.
+            Used by the mixer to determine the intermediate frequency.
+        power (float, optional): The power of the local oscillator.
+            Not used for the QUA configuration
+    """
+
+    frequency: float = None
+    power: float = None
+
+    def configure(self): ...
+
+
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ +
+ + + +

+ Mixer + + +

+ + +
+

+ Bases: QuamComponent

+ + +

QuAM component for a mixer.

+

All properties are optional, so it can be instantiated as Mixer(). +For the default values, it is assumed that the mixer parent is an IQChannel +that has a LocalOscillator.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
local_oscillator_frequency + float + +
+

The frequency of the local +oscillator. Default is #../local_oscillator/frequency, meaning that +the frequency is extracted from the the local_oscillator of the parent.

+
+ 		+ required +
intermediate_frequency + float + +
+

The intermediate frequency of the +mixer. Default is #../intermediate_frequency, meaning that the frequency +references the intermediate_frequency of the parent.

+
+ 		+ required +
correction_gain + float + +
+

The gain imbalance of the mixer. +Default is 0, see Mixer.IQ_imbalance for details.

+
+ 		+ required +
correction_phase + float + +
+

The phase imbalance of the mixer in radians.

+
+ 		+ required +
+ +
+ Source code in quam/components/hardware.py + 
 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
@quam_dataclass
+class Mixer(QuamComponent):
+    """QuAM component for a mixer.
+
+    All properties are optional, so it can be instantiated as `Mixer()`.
+    For the default values, it is assumed that the mixer parent is an `IQChannel`
+    that has a `LocalOscillator`.
+
+    Args:
+        local_oscillator_frequency (float, optional): The frequency of the local
+            oscillator. Default is `#../local_oscillator/frequency`, meaning that
+            the frequency is extracted from the the local_oscillator of the parent.
+        intermediate_frequency (float, optional): The intermediate frequency of the
+            mixer. Default is `#../intermediate_frequency`, meaning that the frequency
+            references the intermediate_frequency of the parent.
+        correction_gain (float, optional): The gain imbalance of the mixer.
+            Default is 0, see `Mixer.IQ_imbalance` for details.
+        correction_phase (float, optional): The phase imbalance of the mixer in radians.
+    """
+
+    local_oscillator_frequency: float = "#../local_oscillator/frequency"
+    intermediate_frequency: float = "#../../intermediate_frequency"
+
+    correction_gain: float = 0
+    correction_phase: float = 0
+
+    @property
+    def name(self):
+        frequency_converter = getattr(self, "parent", None)
+        if frequency_converter is None:
+            raise AttributeError(
+                f"Mixer.parent must be a frequency converter for {self}"
+            )
+
+        channel = getattr(frequency_converter, "parent", None)
+        channel_name = getattr(channel, "name", None)
+        if channel is None or channel_name is None:
+            raise AttributeError(f"Mixer.parent.parent must be a channel for {self}")
+
+        return f"{channel_name}{str_ref.DELIMITER}mixer"
+
+    def apply_to_config(self, config: dict):
+        """Adds this mixer to the QUA configuration.
+
+        See [`QuamComponent.apply_to_config`][quam.core.quam_classes.QuamComponent.apply_to_config]
+        for details.
+        """
+        correction_matrix = self.IQ_imbalance(
+            self.correction_gain, self.correction_phase
+        )
+
+        config["mixers"][self.name] = [
+            {
+                "intermediate_frequency": self.intermediate_frequency,
+                "lo_frequency": self.local_oscillator_frequency,
+                "correction": correction_matrix,
+            }
+        ]
+
+    @staticmethod
+    def IQ_imbalance(g: float, phi: float) -> List[float]:
+        """
+        Creates the correction matrix for the mixer imbalance caused by the gain and
+        phase imbalances, more information can be seen here:
+        https://docs.qualang.io/libs/examples/mixer-calibration/#non-ideal-mixer
+        :param g: relative gain imbalance between the I & Q ports. (unit-less),
+            set to 0 for no gain imbalance.
+        :param phi: relative phase imbalance between the I & Q ports (radians),
+            set to 0 for no phase imbalance.
+        """
+        c = np.cos(phi)
+        s = np.sin(phi)
+        N = 1 / ((1 - g**2) * (2 * c**2 - 1))
+        return [
+            float(N * x) for x in [(1 - g) * c, (1 + g) * s, (1 - g) * s, (1 + g) * c]
+        ]
+
+
+ + + +
+ + + + + + + + + +
+ + +

+ IQ_imbalance(g, phi) + + + staticmethod + + +

+ + +
+ +

Creates the correction matrix for the mixer imbalance caused by the gain and +phase imbalances, more information can be seen here: +https://docs.qualang.io/libs/examples/mixer-calibration/#non-ideal-mixer +:param g: relative gain imbalance between the I & Q ports. (unit-less), + set to 0 for no gain imbalance. +:param phi: relative phase imbalance between the I & Q ports (radians), + set to 0 for no phase imbalance.

+ +
+ Source code in quam/components/hardware.py + 
 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
@staticmethod
+def IQ_imbalance(g: float, phi: float) -> List[float]:
+    """
+    Creates the correction matrix for the mixer imbalance caused by the gain and
+    phase imbalances, more information can be seen here:
+    https://docs.qualang.io/libs/examples/mixer-calibration/#non-ideal-mixer
+    :param g: relative gain imbalance between the I & Q ports. (unit-less),
+        set to 0 for no gain imbalance.
+    :param phi: relative phase imbalance between the I & Q ports (radians),
+        set to 0 for no phase imbalance.
+    """
+    c = np.cos(phi)
+    s = np.sin(phi)
+    N = 1 / ((1 - g**2) * (2 * c**2 - 1))
+    return [
+        float(N * x) for x in [(1 - g) * c, (1 + g) * s, (1 - g) * s, (1 + g) * c]
+    ]
+
+
+
+ +
+ +
+ + +

+ apply_to_config(config) + +

+ + +
+ +

Adds this mixer to the QUA configuration.

+

See QuamComponent.apply_to_config +for details.

+ +
+ Source code in quam/components/hardware.py + 
73
+74
+75
+76
+77
+78
+79
+80
+81
+82
+83
+84
+85
+86
+87
+88
+89
def apply_to_config(self, config: dict):
+    """Adds this mixer to the QUA configuration.
+
+    See [`QuamComponent.apply_to_config`][quam.core.quam_classes.QuamComponent.apply_to_config]
+    for details.
+    """
+    correction_matrix = self.IQ_imbalance(
+        self.correction_gain, self.correction_phase
+    )
+
+    config["mixers"][self.name] = [
+        {
+            "intermediate_frequency": self.intermediate_frequency,
+            "lo_frequency": self.local_oscillator_frequency,
+            "correction": correction_matrix,
+        }
+    ]
+
+
+
+ +
+ + + +
+ +
+ +
+ + + + +
+ +
+ +
+ + + + + + + + + + + + + +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API_references/components/hardware_API/index.html b/API_references/components/hardware_API/index.html new file mode 100644 index 00000000..1f49cd72 --- /dev/null +++ b/API_references/components/hardware_API/index.html @@ -0,0 +1,1737 @@ + + + + + + + + + + + + + + + + + + + + + + + + + QuAM Hardware API - The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ + + + +

QuAM Hardware API

+ + +
+ + + + +
+ + + +
+ + + + + + + + +
+ + + +

+ BaseFrequencyConverter + + +

+ + +
+

+ Bases: QuamComponent

+ + +

Base class for frequency converters.

+ +
+ Source code in quam/components/hardware.py + 
110
+111
+112
+113
+114
@quam_dataclass
+class BaseFrequencyConverter(QuamComponent):
+    """Base class for frequency converters."""
+
+    pass
+
+
+ +
+ +
+ +
+ + + +

+ FrequencyConverter + + +

+ + +
+

+ Bases: BaseFrequencyConverter

+ + +

Frequency up/down converter component.

+

This component encapsulates the local oscillator and mixer used to upconvert or +downconvert an RF signal.

+

The FrequencyConverter component is attached to IQ channels through

+
    +
  • IQChannel.frequency_converter_up
    • +
  • InOutIQChannel.frequency_converter_down
    • +
+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
local_oscillator + LocalOscillator + +
+

The local oscillator for the frequency converter.

+
+ 		+ required +
mixer + Mixer + +
+

The mixer for the frequency converter.

+
+ 		+ required +
gain + float + +
+

The gain of the frequency converter.

+
+ 		+ required +
+ +
+ Source code in quam/components/hardware.py + 
117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
@quam_dataclass
+class FrequencyConverter(BaseFrequencyConverter):
+    """Frequency up/down converter component.
+
+    This component encapsulates the local oscillator and mixer used to upconvert or
+    downconvert an RF signal.
+
+    The FrequencyConverter component is attached to IQ channels through
+
+    - `IQChannel.frequency_converter_up`
+    - `InOutIQChannel.frequency_converter_down`
+
+    Args:
+        local_oscillator (LocalOscillator): The local oscillator for the frequency converter.
+        mixer (Mixer): The mixer for the frequency converter.
+        gain (float): The gain of the frequency converter.
+    """
+
+    local_oscillator: LocalOscillator = None
+    mixer: Mixer = None
+    gain: float = None
+
+    @property
+    def LO_frequency(self):
+        return self.local_oscillator.frequency
+
+    def configure(self):
+        if self.local_oscillator is not None:
+            self.local_oscillator.configure()
+
+
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ +
+ + + +

+ LocalOscillator + + +

+ + +
+

+ Bases: QuamComponent

+ + +

QuAM component for a local oscillator.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
frequency + float + +
+

The frequency of the local oscillator. +Used by the mixer to determine the intermediate frequency.

+
+ 		+ required +
power + float + +
+

The power of the local oscillator. +Not used for the QUA configuration

+
+ 		+ required +
+ +
+ Source code in quam/components/hardware.py + 
15
+16
+17
+18
+19
+20
+21
+22
+23
+24
+25
+26
+27
+28
+29
@quam_dataclass
+class LocalOscillator(QuamComponent):
+    """QuAM component for a local oscillator.
+
+    Args:
+        frequency (float): The frequency of the local oscillator.
+            Used by the mixer to determine the intermediate frequency.
+        power (float, optional): The power of the local oscillator.
+            Not used for the QUA configuration
+    """
+
+    frequency: float = None
+    power: float = None
+
+    def configure(self): ...
+
+
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ +
+ + + +

+ Mixer + + +

+ + +
+

+ Bases: QuamComponent

+ + +

QuAM component for a mixer.

+

All properties are optional, so it can be instantiated as Mixer(). +For the default values, it is assumed that the mixer parent is an IQChannel +that has a LocalOscillator.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
local_oscillator_frequency + float + +
+

The frequency of the local +oscillator. Default is #../local_oscillator/frequency, meaning that +the frequency is extracted from the the local_oscillator of the parent.

+
+ 		+ required +
intermediate_frequency + float + +
+

The intermediate frequency of the +mixer. Default is #../intermediate_frequency, meaning that the frequency +references the intermediate_frequency of the parent.

+
+ 		+ required +
correction_gain + float + +
+

The gain imbalance of the mixer. +Default is 0, see Mixer.IQ_imbalance for details.

+
+ 		+ required +
correction_phase + float + +
+

The phase imbalance of the mixer in radians.

+
+ 		+ required +
+ +
+ Source code in quam/components/hardware.py + 
 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
@quam_dataclass
+class Mixer(QuamComponent):
+    """QuAM component for a mixer.
+
+    All properties are optional, so it can be instantiated as `Mixer()`.
+    For the default values, it is assumed that the mixer parent is an `IQChannel`
+    that has a `LocalOscillator`.
+
+    Args:
+        local_oscillator_frequency (float, optional): The frequency of the local
+            oscillator. Default is `#../local_oscillator/frequency`, meaning that
+            the frequency is extracted from the the local_oscillator of the parent.
+        intermediate_frequency (float, optional): The intermediate frequency of the
+            mixer. Default is `#../intermediate_frequency`, meaning that the frequency
+            references the intermediate_frequency of the parent.
+        correction_gain (float, optional): The gain imbalance of the mixer.
+            Default is 0, see `Mixer.IQ_imbalance` for details.
+        correction_phase (float, optional): The phase imbalance of the mixer in radians.
+    """
+
+    local_oscillator_frequency: float = "#../local_oscillator/frequency"
+    intermediate_frequency: float = "#../../intermediate_frequency"
+
+    correction_gain: float = 0
+    correction_phase: float = 0
+
+    @property
+    def name(self):
+        frequency_converter = getattr(self, "parent", None)
+        if frequency_converter is None:
+            raise AttributeError(
+                f"Mixer.parent must be a frequency converter for {self}"
+            )
+
+        channel = getattr(frequency_converter, "parent", None)
+        channel_name = getattr(channel, "name", None)
+        if channel is None or channel_name is None:
+            raise AttributeError(f"Mixer.parent.parent must be a channel for {self}")
+
+        return f"{channel_name}{str_ref.DELIMITER}mixer"
+
+    def apply_to_config(self, config: dict):
+        """Adds this mixer to the QUA configuration.
+
+        See [`QuamComponent.apply_to_config`][quam.core.quam_classes.QuamComponent.apply_to_config]
+        for details.
+        """
+        correction_matrix = self.IQ_imbalance(
+            self.correction_gain, self.correction_phase
+        )
+
+        config["mixers"][self.name] = [
+            {
+                "intermediate_frequency": self.intermediate_frequency,
+                "lo_frequency": self.local_oscillator_frequency,
+                "correction": correction_matrix,
+            }
+        ]
+
+    @staticmethod
+    def IQ_imbalance(g: float, phi: float) -> List[float]:
+        """
+        Creates the correction matrix for the mixer imbalance caused by the gain and
+        phase imbalances, more information can be seen here:
+        https://docs.qualang.io/libs/examples/mixer-calibration/#non-ideal-mixer
+        :param g: relative gain imbalance between the I & Q ports. (unit-less),
+            set to 0 for no gain imbalance.
+        :param phi: relative phase imbalance between the I & Q ports (radians),
+            set to 0 for no phase imbalance.
+        """
+        c = np.cos(phi)
+        s = np.sin(phi)
+        N = 1 / ((1 - g**2) * (2 * c**2 - 1))
+        return [
+            float(N * x) for x in [(1 - g) * c, (1 + g) * s, (1 - g) * s, (1 + g) * c]
+        ]
+
+
+ + + +
+ + + + + + + + + +
+ + +

+ IQ_imbalance(g, phi) + + + staticmethod + + +

+ + +
+ +

Creates the correction matrix for the mixer imbalance caused by the gain and +phase imbalances, more information can be seen here: +https://docs.qualang.io/libs/examples/mixer-calibration/#non-ideal-mixer +:param g: relative gain imbalance between the I & Q ports. (unit-less), + set to 0 for no gain imbalance. +:param phi: relative phase imbalance between the I & Q ports (radians), + set to 0 for no phase imbalance.

+ +
+ Source code in quam/components/hardware.py + 
 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
@staticmethod
+def IQ_imbalance(g: float, phi: float) -> List[float]:
+    """
+    Creates the correction matrix for the mixer imbalance caused by the gain and
+    phase imbalances, more information can be seen here:
+    https://docs.qualang.io/libs/examples/mixer-calibration/#non-ideal-mixer
+    :param g: relative gain imbalance between the I & Q ports. (unit-less),
+        set to 0 for no gain imbalance.
+    :param phi: relative phase imbalance between the I & Q ports (radians),
+        set to 0 for no phase imbalance.
+    """
+    c = np.cos(phi)
+    s = np.sin(phi)
+    N = 1 / ((1 - g**2) * (2 * c**2 - 1))
+    return [
+        float(N * x) for x in [(1 - g) * c, (1 + g) * s, (1 - g) * s, (1 + g) * c]
+    ]
+
+
+
+ +
+ +
+ + +

+ apply_to_config(config) + +

+ + +
+ +

Adds this mixer to the QUA configuration.

+

See QuamComponent.apply_to_config +for details.

+ +
+ Source code in quam/components/hardware.py + 
73
+74
+75
+76
+77
+78
+79
+80
+81
+82
+83
+84
+85
+86
+87
+88
+89
def apply_to_config(self, config: dict):
+    """Adds this mixer to the QUA configuration.
+
+    See [`QuamComponent.apply_to_config`][quam.core.quam_classes.QuamComponent.apply_to_config]
+    for details.
+    """
+    correction_matrix = self.IQ_imbalance(
+        self.correction_gain, self.correction_phase
+    )
+
+    config["mixers"][self.name] = [
+        {
+            "intermediate_frequency": self.intermediate_frequency,
+            "lo_frequency": self.local_oscillator_frequency,
+            "correction": correction_matrix,
+        }
+    ]
+
+
+
+ +
+ + + +
+ +
+ +
+ + + + +
+ +
+ +
+ + + + + + + + + + + + + +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API_references/components/octave/index.html b/API_references/components/octave/index.html new file mode 100644 index 00000000..73957a1f --- /dev/null +++ b/API_references/components/octave/index.html @@ -0,0 +1,3129 @@ + + + + + + + + + + + + + + + + + + + + + Octave - The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ + + + +

Octave

+ +
+ + + + +
+ + + +
+ + + + + + + + +
+ + + +

+ Octave + + +

+ + +
+

+ Bases: QuamComponent

+ + +

QuAM component for the QM Octave.

+

The QM Octave is a device that can be used to upconvert and downconvert signals. It +has 5 RF outputs and 2 RF inputs. Each RF_output has an associated +OctaveUpConverter, and similarly each RF_input has an OctaveDownConverter.

+

In many cases the Octave is connected to a single OPX in the default configuration, +i.e. OPX outputs are connected to the corresponding Octave I/Q input, and Octave IF +outputs are connected to the corresponding OPX input. In this case you can configure +the Octave with the correct FrequencyConverters using +Octave.initialize_default_connectivity().

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
name + +
+

The name of the Octave. Must be unique

+
+ 		+ required +
ip + +
+

The IP address of the Octave. Used in Octave.get_octave_config()

+
+ 		+ required +
port + +
+

The port number of the Octave. Used in Octave.get_octave_config()

+
+ 		+ required +
calibration_db_path + +
+

The path to the calibration database. If not specified, the +current working directory is used.

+
+ 		+ required +
RF_outputs + +
+

A dictionary of OctaveUpConverter objects. The keys are the +output numbers (1-5).

+
+ 		+ required +
RF_inputs + +
+

A dictionary of OctaveDownConverter objects. The keys are the +input numbers (1-2).

+
+ 		+ required +
loopbacks + +
+

A list of loopback connections, for example to connect a local +oscillator. See the QUA Octave documentation for details.

+
+ 		+ required +
+ +
+ Source code in quam/components/octave.py + 
 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
@quam_dataclass
+class Octave(QuamComponent):
+    """QuAM component for the QM Octave.
+
+    The QM Octave is a device that can be used to upconvert and downconvert signals. It
+    has 5 RF outputs and 2 RF inputs. Each RF_output has an associated
+    `OctaveUpConverter`, and similarly each RF_input has an `OctaveDownConverter`.
+
+    In many cases the Octave is connected to a single OPX in the default configuration,
+    i.e. OPX outputs are connected to the corresponding Octave I/Q input, and Octave IF
+    outputs are connected to the corresponding OPX input. In this case you can configure
+    the Octave with the correct `FrequencyConverter`s using
+    `Octave.initialize_default_connectivity()`.
+
+    Args:
+        name: The name of the Octave. Must be unique
+        ip: The IP address of the Octave. Used in `Octave.get_octave_config()`
+        port: The port number of the Octave. Used in `Octave.get_octave_config()`
+        calibration_db_path: The path to the calibration database. If not specified, the
+            current working directory is used.
+        RF_outputs: A dictionary of `OctaveUpConverter` objects. The keys are the
+            output numbers (1-5).
+        RF_inputs: A dictionary of `OctaveDownConverter` objects. The keys are the
+            input numbers (1-2).
+        loopbacks: A list of loopback connections, for example to connect a local
+            oscillator. See the QUA Octave documentation for details.
+    """
+
+    name: str
+    ip: str
+    port: int
+    calibration_db_path: str = None
+
+    RF_outputs: Dict[int, "OctaveUpConverter"] = field(default_factory=dict)
+    RF_inputs: Dict[int, "OctaveDownConverter"] = field(default_factory=dict)
+    loopbacks: List[Tuple[Tuple[str, str], str]] = field(default_factory=list)
+
+    def initialize_frequency_converters(self):
+        """Initialize the Octave frequency converterswith default connectivity.
+
+        This method initializes the Octave with default connectivity, i.e. it connects
+        the Octave to a single OPX. It creates an `OctaveUpConverter` for each RF output
+        and an `OctaveDownConverter` for each RF input. The `OctaveUpConverter` objects
+        are added to `Octave.RF_outputs` and the `OctaveDownConverter` objects are added
+        to `Octave.RF_inputs`.
+
+        Raises:
+            ValueError: If the Octave already has RF_outputs or RF_inputs.
+
+        """
+        if self.RF_outputs:
+            raise ValueError(
+                "Error initializing Octave with default connectivity. "
+                "octave.RF_outputs is not empty"
+            )
+        if self.RF_inputs:
+            raise ValueError(
+                "Error initializing Octave with default connectivity. "
+                "octave.IF_outputs is not empty"
+            )
+
+        for idx in range(1, 6):
+            self.RF_outputs[idx] = OctaveUpConverter(
+                id=idx,
+                LO_frequency=None,  # TODO What should default be?
+            )
+
+        for idx in range(1, 3):
+            LO_source = "internal" if idx == 1 else "external"
+            self.RF_inputs[idx] = OctaveDownConverter(
+                id=idx, LO_frequency=None, LO_source=LO_source
+            )
+
+    def get_octave_config(self) -> QmOctaveConfig:
+        """Return a QmOctaveConfig object with the current Octave configuration."""
+        octave_config = QmOctaveConfig()
+
+        if self.calibration_db_path is not None:
+            octave_config.set_calibration_db(self.calibration_db_path)
+        else:
+            octave_config.set_calibration_db(os.getcwd())
+
+        octave_config.add_device_info(self.name, self.ip, self.port)
+        return octave_config
+
+    def apply_to_config(self, config: Dict) -> None:
+        """Add the Octave configuration to a config dictionary.
+
+        This method is called by the `QuamComponent.generate_config` method.
+
+        Args:
+            config: A dictionary representing a QUA config file.
+
+        Raises:
+            KeyError: If the Octave is already in the config.
+        """
+        if "octaves" not in config:
+            config["octaves"] = {}
+        if self.name in config["octaves"]:
+            raise KeyError(
+                f'Error generating config: config["octaves"] already contains an entry '
+                f' for Octave "{self.name}"'
+            )
+
+        config["octaves"][self.name] = {
+            "RF_outputs": {},
+            "IF_outputs": {},
+            "RF_inputs": {},
+            "loopbacks": list(self.loopbacks),
+        }
+
+
+ + + +
+ + + + + + + + + +
+ + +

+ apply_to_config(config) + +

+ + +
+ +

Add the Octave configuration to a config dictionary.

+

This method is called by the QuamComponent.generate_config method.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
config + Dict + +
+

A dictionary representing a QUA config file.

+
+ 		+ required +
+ + +

Raises:

+ + + + + + + + + + + + + +
TypeDescription
+ KeyError + +
+

If the Octave is already in the config.

+
+
+ +
+ Source code in quam/components/octave.py + 
117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
def apply_to_config(self, config: Dict) -> None:
+    """Add the Octave configuration to a config dictionary.
+
+    This method is called by the `QuamComponent.generate_config` method.
+
+    Args:
+        config: A dictionary representing a QUA config file.
+
+    Raises:
+        KeyError: If the Octave is already in the config.
+    """
+    if "octaves" not in config:
+        config["octaves"] = {}
+    if self.name in config["octaves"]:
+        raise KeyError(
+            f'Error generating config: config["octaves"] already contains an entry '
+            f' for Octave "{self.name}"'
+        )
+
+    config["octaves"][self.name] = {
+        "RF_outputs": {},
+        "IF_outputs": {},
+        "RF_inputs": {},
+        "loopbacks": list(self.loopbacks),
+    }
+
+
+
+ +
+ +
+ + +

+ get_octave_config() + +

+ + +
+ +

Return a QmOctaveConfig object with the current Octave configuration.

+ +
+ Source code in quam/components/octave.py + 
105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
def get_octave_config(self) -> QmOctaveConfig:
+    """Return a QmOctaveConfig object with the current Octave configuration."""
+    octave_config = QmOctaveConfig()
+
+    if self.calibration_db_path is not None:
+        octave_config.set_calibration_db(self.calibration_db_path)
+    else:
+        octave_config.set_calibration_db(os.getcwd())
+
+    octave_config.add_device_info(self.name, self.ip, self.port)
+    return octave_config
+
+
+
+ +
+ +
+ + +

+ initialize_frequency_converters() + +

+ + +
+ +

Initialize the Octave frequency converterswith default connectivity.

+

This method initializes the Octave with default connectivity, i.e. it connects +the Octave to a single OPX. It creates an OctaveUpConverter for each RF output +and an OctaveDownConverter for each RF input. The OctaveUpConverter objects +are added to Octave.RF_outputs and the OctaveDownConverter objects are added +to Octave.RF_inputs.

+ + +

Raises:

+ + + + + + + + + + + + + +
TypeDescription
+ ValueError + +
+

If the Octave already has RF_outputs or RF_inputs.

+
+
+ +
+ Source code in quam/components/octave.py + 
 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
def initialize_frequency_converters(self):
+    """Initialize the Octave frequency converterswith default connectivity.
+
+    This method initializes the Octave with default connectivity, i.e. it connects
+    the Octave to a single OPX. It creates an `OctaveUpConverter` for each RF output
+    and an `OctaveDownConverter` for each RF input. The `OctaveUpConverter` objects
+    are added to `Octave.RF_outputs` and the `OctaveDownConverter` objects are added
+    to `Octave.RF_inputs`.
+
+    Raises:
+        ValueError: If the Octave already has RF_outputs or RF_inputs.
+
+    """
+    if self.RF_outputs:
+        raise ValueError(
+            "Error initializing Octave with default connectivity. "
+            "octave.RF_outputs is not empty"
+        )
+    if self.RF_inputs:
+        raise ValueError(
+            "Error initializing Octave with default connectivity. "
+            "octave.IF_outputs is not empty"
+        )
+
+    for idx in range(1, 6):
+        self.RF_outputs[idx] = OctaveUpConverter(
+            id=idx,
+            LO_frequency=None,  # TODO What should default be?
+        )
+
+    for idx in range(1, 3):
+        LO_source = "internal" if idx == 1 else "external"
+        self.RF_inputs[idx] = OctaveDownConverter(
+            id=idx, LO_frequency=None, LO_source=LO_source
+        )
+
+
+
+ +
+ + + +
+ +
+ +
+ +
+ + + +

+ OctaveDownConverter + + +

+ + +
+

+ Bases: OctaveFrequencyConverter

+ + +

A frequency downconverter for the QM Octave.

+

The OctaveDownConverter represents a frequency downconverter in the QM Octave. The +OctaveDownConverter is usually connected to an InOutIQChannel, in which case the +two OPX inputs are connected to the IF outputs of the OctaveDownConverter. The +OPX inputs are specified in the OctaveDownConverter.channel attribute. The +channel is either an InOutIQChannel or an InOutSingleChannel.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
id + +
+

The RF input id, must be between 1-2.

+
+ 		+ required +
LO_frequency + +
+

The local oscillator frequency in Hz, between 2 and 18 GHz.

+
+ 		+ required +
LO_source + +
+

The local oscillator source, "internal" or "external. +For down converter 1 "internal" is the default, +for down converter 2 "external" is the default.

+
+ 		+ required +
IF_mode_I + +
+

Sets the mode of the I port of the IF Down Converter module as can be +seen in the octave block diagram (see Octave page in QUA documentation). +Can be "direct" / "envelope" / "mixer" / "off". The default is "direct". +- "direct" - The signal bypasses the IF module. +- "envelope" - The signal passes through an envelope detector. +- "mixer" - The signal passes through a low-frequency mixer. +- "off" - the signal doesn't pass to the output port.

+
+ 		+ required +
IF_mode_Q + +
+

Sets the mode of the Q port of the IF Down Converter module.

+
+ 		+ required +
IF_output_I + +
+

The output port of the IF Down Converter module for the I port. +Can be 1 or 2. The default is 1. This will be 2 if the IF outputs +are connected to the opposite OPX inputs

+
+ 		+ required +
IF_output_Q + +
+

The output port of the IF Down Converter module for the Q port. +Can be 1 or 2. The default is 2. This will be 1 if the IF outputs +are connected to the opposite OPX inputs.

+
+ 		+ required +
+ +
+ Source code in quam/components/octave.py + 
297
+298
+299
+300
+301
+302
+303
+304
+305
+306
+307
+308
+309
+310
+311
+312
+313
+314
+315
+316
+317
+318
+319
+320
+321
+322
+323
+324
+325
+326
+327
+328
+329
+330
+331
+332
+333
+334
+335
+336
+337
+338
+339
+340
+341
+342
+343
+344
+345
+346
+347
+348
+349
+350
+351
+352
+353
+354
+355
+356
+357
+358
+359
+360
+361
+362
+363
+364
+365
+366
+367
+368
+369
+370
+371
+372
+373
+374
+375
+376
+377
+378
+379
+380
+381
+382
+383
+384
+385
+386
+387
+388
+389
+390
+391
+392
+393
+394
+395
+396
+397
+398
+399
+400
+401
+402
+403
+404
+405
+406
+407
+408
+409
+410
+411
@quam_dataclass
+class OctaveDownConverter(OctaveFrequencyConverter):
+    """A frequency downconverter for the QM Octave.
+
+    The OctaveDownConverter represents a frequency downconverter in the QM Octave. The
+    OctaveDownConverter is usually connected to an InOutIQChannel, in which case the
+    two OPX inputs are connected to the IF outputs of the OctaveDownConverter. The
+    OPX inputs are specified in the `OctaveDownConverter.channel` attribute. The
+    channel is either an InOutIQChannel or an InOutSingleChannel.
+
+    Args:
+        id: The RF input id, must be between 1-2.
+        LO_frequency: The local oscillator frequency in Hz, between 2 and 18 GHz.
+        LO_source: The local oscillator source, "internal" or "external.
+            For down converter 1 "internal" is the default,
+            for down converter 2 "external" is the default.
+        IF_mode_I: Sets the mode of the I port of the IF Down Converter module as can be
+            seen in the octave block diagram (see Octave page in QUA documentation).
+            Can be "direct" / "envelope" / "mixer" / "off". The default is "direct".
+            - "direct" - The signal bypasses the IF module.
+            - "envelope" - The signal passes through an envelope detector.
+            - "mixer" - The signal passes through a low-frequency mixer.
+            - "off" - the signal doesn't pass to the output port.
+        IF_mode_Q: Sets the mode of the Q port of the IF Down Converter module.
+        IF_output_I: The output port of the IF Down Converter module for the I port.
+            Can be 1 or 2. The default is 1. This will be 2 if the IF outputs
+            are connected to the opposite OPX inputs
+        IF_output_Q: The output port of the IF Down Converter module for the Q port.
+            Can be 1 or 2. The default is 2. This will be 1 if the IF outputs
+            are connected to the opposite OPX inputs.
+    """
+
+    LO_frequency: float = None
+    LO_source: Literal["internal", "external"] = "internal"
+    IF_mode_I: Literal["direct", "envelope", "mixer", "off"] = "direct"
+    IF_mode_Q: Literal["direct", "envelope", "mixer", "off"] = "direct"
+    IF_output_I: Literal[1, 2] = 1
+    IF_output_Q: Literal[1, 2] = 2
+
+    @property
+    def config_settings(self):
+        """Specifies that the converter will be added to the config after the Octave."""
+        return {"after": [self.octave]}
+
+    def apply_to_config(self, config: Dict) -> None:
+        """Add information about the frequency down-converter to the QUA config
+
+        This method is called by the `QuamComponent.generate_config` method.
+
+        Nothing is added to the config if the `OctaveDownConverter.channel` is not
+        specified or if the `OctaveDownConverter.LO_frequency` is not specified.
+
+        Args:
+            config: A dictionary representing a QUA config file.
+
+        Raises:
+            ValueError: If the LO_frequency is not specified.
+            KeyError: If the Octave is not in the config, or if config["octaves"] does
+                not exist.
+            KeyError: If the Octave already has an entry for the OctaveDownConverter.
+            ValueError: If the IF_output_I and IF_output_Q are already assigned to
+                other ports.
+        """
+        if not isinstance(self.LO_frequency, (int, float)):
+            if self.channel is None:
+                return
+            else:
+                raise ValueError(
+                    f"Error generating config for Octave upconverter id={self.id}: "
+                    "LO_frequency must be specified."
+                )
+
+        super().apply_to_config(config)
+
+        if self.id in config["octaves"][self.octave.name]["RF_inputs"]:
+            raise KeyError(
+                f"Error generating config: "
+                f'config["octaves"]["{self.octave.name}"]["RF_inputs"] '
+                f'already has an entry for OctaveDownConverter with id "{self.id}"'
+            )
+
+        config["octaves"][self.octave.name]["RF_inputs"][self.id] = {
+            "RF_source": "RF_in",
+            "LO_frequency": self.LO_frequency,
+            "LO_source": self.LO_source,
+            "IF_mode_I": self.IF_mode_I,
+            "IF_mode_Q": self.IF_mode_Q,
+        }
+
+        if isinstance(self.channel, InOutIQChannel):
+            IF_channels = [self.IF_output_I, self.IF_output_Q]
+            opx_channels = [self.channel.opx_input_I, self.channel.opx_input_Q]
+        elif isinstance(self.channel, InOutSingleChannel):
+            IF_channels = [self.IF_output_I]
+            opx_channels = [self.channel.opx_input]
+        else:
+            IF_channels = []
+            opx_channels = []
+
+        opx_port_tuples = [
+            p.port_tuple if isinstance(p, BasePort) else tuple(p) for p in opx_channels
+        ]
+
+        IF_config = config["octaves"][self.octave.name]["IF_outputs"]
+        for k, (IF_ch, opx_port_tuples) in enumerate(
+            zip(IF_channels, opx_port_tuples), start=1
+        ):
+            label = f"IF_out{IF_ch}"
+            IF_config.setdefault(label, {"port": opx_port_tuples, "name": f"out{k}"})
+            if IF_config[label]["port"] != opx_port_tuples:
+                raise ValueError(
+                    f"Error generating config for Octave downconverter id={self.id}: "
+                    f"Unable to assign {label} to  port {opx_port_tuples} because it is already "
+                    f"assigned to port {IF_config[label]['port']} "
+                )
+
+
+ + + +
+ + + + + + + +
+ + + +

+ config_settings + + + property + + +

+ + +
+ +

Specifies that the converter will be added to the config after the Octave.

+
+ +
+ + + +
+ + +

+ apply_to_config(config) + +

+ + +
+ +

Add information about the frequency down-converter to the QUA config

+

This method is called by the QuamComponent.generate_config method.

+

Nothing is added to the config if the OctaveDownConverter.channel is not +specified or if the OctaveDownConverter.LO_frequency is not specified.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
config + Dict + +
+

A dictionary representing a QUA config file.

+
+ 		+ required +
+ + +

Raises:

+ + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDescription
+ ValueError + +
+

If the LO_frequency is not specified.

+
+
+ KeyError + +
+

If the Octave is not in the config, or if config["octaves"] does +not exist.

+
+
+ KeyError + +
+

If the Octave already has an entry for the OctaveDownConverter.

+
+
+ ValueError + +
+

If the IF_output_I and IF_output_Q are already assigned to +other ports.

+
+
+ +
+ Source code in quam/components/octave.py + 
341
+342
+343
+344
+345
+346
+347
+348
+349
+350
+351
+352
+353
+354
+355
+356
+357
+358
+359
+360
+361
+362
+363
+364
+365
+366
+367
+368
+369
+370
+371
+372
+373
+374
+375
+376
+377
+378
+379
+380
+381
+382
+383
+384
+385
+386
+387
+388
+389
+390
+391
+392
+393
+394
+395
+396
+397
+398
+399
+400
+401
+402
+403
+404
+405
+406
+407
+408
+409
+410
+411
def apply_to_config(self, config: Dict) -> None:
+    """Add information about the frequency down-converter to the QUA config
+
+    This method is called by the `QuamComponent.generate_config` method.
+
+    Nothing is added to the config if the `OctaveDownConverter.channel` is not
+    specified or if the `OctaveDownConverter.LO_frequency` is not specified.
+
+    Args:
+        config: A dictionary representing a QUA config file.
+
+    Raises:
+        ValueError: If the LO_frequency is not specified.
+        KeyError: If the Octave is not in the config, or if config["octaves"] does
+            not exist.
+        KeyError: If the Octave already has an entry for the OctaveDownConverter.
+        ValueError: If the IF_output_I and IF_output_Q are already assigned to
+            other ports.
+    """
+    if not isinstance(self.LO_frequency, (int, float)):
+        if self.channel is None:
+            return
+        else:
+            raise ValueError(
+                f"Error generating config for Octave upconverter id={self.id}: "
+                "LO_frequency must be specified."
+            )
+
+    super().apply_to_config(config)
+
+    if self.id in config["octaves"][self.octave.name]["RF_inputs"]:
+        raise KeyError(
+            f"Error generating config: "
+            f'config["octaves"]["{self.octave.name}"]["RF_inputs"] '
+            f'already has an entry for OctaveDownConverter with id "{self.id}"'
+        )
+
+    config["octaves"][self.octave.name]["RF_inputs"][self.id] = {
+        "RF_source": "RF_in",
+        "LO_frequency": self.LO_frequency,
+        "LO_source": self.LO_source,
+        "IF_mode_I": self.IF_mode_I,
+        "IF_mode_Q": self.IF_mode_Q,
+    }
+
+    if isinstance(self.channel, InOutIQChannel):
+        IF_channels = [self.IF_output_I, self.IF_output_Q]
+        opx_channels = [self.channel.opx_input_I, self.channel.opx_input_Q]
+    elif isinstance(self.channel, InOutSingleChannel):
+        IF_channels = [self.IF_output_I]
+        opx_channels = [self.channel.opx_input]
+    else:
+        IF_channels = []
+        opx_channels = []
+
+    opx_port_tuples = [
+        p.port_tuple if isinstance(p, BasePort) else tuple(p) for p in opx_channels
+    ]
+
+    IF_config = config["octaves"][self.octave.name]["IF_outputs"]
+    for k, (IF_ch, opx_port_tuples) in enumerate(
+        zip(IF_channels, opx_port_tuples), start=1
+    ):
+        label = f"IF_out{IF_ch}"
+        IF_config.setdefault(label, {"port": opx_port_tuples, "name": f"out{k}"})
+        if IF_config[label]["port"] != opx_port_tuples:
+            raise ValueError(
+                f"Error generating config for Octave downconverter id={self.id}: "
+                f"Unable to assign {label} to  port {opx_port_tuples} because it is already "
+                f"assigned to port {IF_config[label]['port']} "
+            )
+
+
+
+ +
+ + + +
+ +
+ +
+ +
+ + + +

+ OctaveFrequencyConverter + + +

+ + +
+

+ Bases: BaseFrequencyConverter, ABC

+ + +

Base class for OctaveUpConverter and OctaveDownConverter.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
id + +
+

The id of the converter. Must be unique within the Octave. +For OctaveUpConverter, the id is used as the RF output number. +For OctaveDownConverter, the id is used as the RF input number.

+
+ 		+ required +
channel + +
+

The channel that the converter is connected to.

+
+ 		+ required +
+ +
+ Source code in quam/components/octave.py + 
144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
+182
+183
+184
+185
+186
+187
+188
+189
+190
+191
+192
+193
+194
+195
+196
+197
+198
+199
@quam_dataclass
+class OctaveFrequencyConverter(BaseFrequencyConverter, ABC):
+    """Base class for OctaveUpConverter and OctaveDownConverter.
+
+    Args:
+        id: The id of the converter. Must be unique within the Octave.
+            For OctaveUpConverter, the id is used as the RF output number.
+            For OctaveDownConverter, the id is used as the RF input number.
+        channel: The channel that the converter is connected to.
+    """
+
+    id: int
+    channel: Channel = None
+
+    @property
+    def octave(self) -> Optional[Octave]:
+        if self.parent is None:
+            return None
+        parent_parent = getattr(self.parent, "parent")
+        if not isinstance(parent_parent, Octave):
+            return None
+        return parent_parent
+
+    @property
+    def config_settings(self) -> Dict[str, Any]:
+        """Specifies that the converter will be added to the config after the Octave."""
+        return {"after": [self.octave]}
+
+    def apply_to_config(self, config: Dict) -> None:
+        """Add information about the frequency converter to the QUA config
+
+        This method is called by the `QuamComponent.generate_config` method.
+
+        Args:
+            config: A dictionary representing a QUA config file.
+
+        Raises:
+            KeyError: If the Octave is not in the config, or if config["octaves"] does
+                not exist.
+        """
+        super().apply_to_config(config)
+
+        if "octaves" not in config:
+            raise KeyError('Error generating config: "octaves" entry not found')
+
+        if self.octave is None:
+            raise KeyError(
+                f"Error generating config: OctaveConverter with id {self.id} does not "
+                "have an Octave parent"
+            )
+
+        if self.octave.name not in config["octaves"]:
+            raise KeyError(
+                'Error generating config: config["octaves"] does not have Octave'
+                f' entry config["octaves"]["{self.octave.name}"]'
+            )
+
+
+ + + +
+ + + + + + + +
+ + + +

+ config_settings: Dict[str, Any] + + + property + + +

+ + +
+ +

Specifies that the converter will be added to the config after the Octave.

+
+ +
+ + + +
+ + +

+ apply_to_config(config) + +

+ + +
+ +

Add information about the frequency converter to the QUA config

+

This method is called by the QuamComponent.generate_config method.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
config + Dict + +
+

A dictionary representing a QUA config file.

+
+ 		+ required +
+ + +

Raises:

+ + + + + + + + + + + + + +
TypeDescription
+ KeyError + +
+

If the Octave is not in the config, or if config["octaves"] does +not exist.

+
+
+ +
+ Source code in quam/components/octave.py + 
172
+173
+174
+175
+176
+177
+178
+179
+180
+181
+182
+183
+184
+185
+186
+187
+188
+189
+190
+191
+192
+193
+194
+195
+196
+197
+198
+199
def apply_to_config(self, config: Dict) -> None:
+    """Add information about the frequency converter to the QUA config
+
+    This method is called by the `QuamComponent.generate_config` method.
+
+    Args:
+        config: A dictionary representing a QUA config file.
+
+    Raises:
+        KeyError: If the Octave is not in the config, or if config["octaves"] does
+            not exist.
+    """
+    super().apply_to_config(config)
+
+    if "octaves" not in config:
+        raise KeyError('Error generating config: "octaves" entry not found')
+
+    if self.octave is None:
+        raise KeyError(
+            f"Error generating config: OctaveConverter with id {self.id} does not "
+            "have an Octave parent"
+        )
+
+    if self.octave.name not in config["octaves"]:
+        raise KeyError(
+            'Error generating config: config["octaves"] does not have Octave'
+            f' entry config["octaves"]["{self.octave.name}"]'
+        )
+
+
+
+ +
+ + + +
+ +
+ +
+ +
+ + + +

+ OctaveUpConverter + + +

+ + +
+

+ Bases: OctaveFrequencyConverter

+ + +

A frequency upconverter for the QM Octave.

+

The OctaveUpConverter represents a frequency upconverter in the QM Octave. Usually +an IQChannel is connected OctaveUpconverter.channel, in which case the two OPX +outputs are connected to the I and Q inputs of the OctaveUpConverter. +The OPX outputs are specified in the OctaveUpConverter.channel attribute. +The channel is either an IQChannel or a SingleChannel.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
id + +
+

The RF output id, must be between 1-5.

+
+ 		+ required +
LO_frequency + +
+

The local oscillator frequency in Hz, between 2 and 18 GHz.

+
+ 		+ required +
LO_source + +
+

The local oscillator source, "internal" (default) or "external".

+
+ 		+ required +
gain + +
+

The gain of the output, between -20 and 20 dB in steps of 0.5. +Default is 0 dB.

+
+ 		+ required +
output_mode + +
+

Sets the fast switch's mode of the up converter module. +Can be "always_on" / "always_off" / "triggered" / "triggered_reversed". +The default is "always_off". +- "always_on" - Output is always on +- "always_off" - Output is always off +- "triggered" - The output will play when rising edge is detected in the + octave's digital port. +- "triggered_reversed" - The output will play when falling edge is detected + in the octave's digital port.

+
+ 		+ required +
input_attenuators + +
+

Whether the I and Q ports have a 10 dB attenuator before +entering the mixer. Off by default.

+
+ 		+ required +
+ +
+ Source code in quam/components/octave.py + 
202
+203
+204
+205
+206
+207
+208
+209
+210
+211
+212
+213
+214
+215
+216
+217
+218
+219
+220
+221
+222
+223
+224
+225
+226
+227
+228
+229
+230
+231
+232
+233
+234
+235
+236
+237
+238
+239
+240
+241
+242
+243
+244
+245
+246
+247
+248
+249
+250
+251
+252
+253
+254
+255
+256
+257
+258
+259
+260
+261
+262
+263
+264
+265
+266
+267
+268
+269
+270
+271
+272
+273
+274
+275
+276
+277
+278
+279
+280
+281
+282
+283
+284
+285
+286
+287
+288
+289
+290
+291
+292
+293
+294
@quam_dataclass
+class OctaveUpConverter(OctaveFrequencyConverter):
+    """A frequency upconverter for the QM Octave.
+
+    The OctaveUpConverter represents a frequency upconverter in the QM Octave. Usually
+    an IQChannel is connected `OctaveUpconverter.channel`, in which case the two OPX
+    outputs are connected to the I and Q inputs of the OctaveUpConverter.
+    The OPX outputs are specified in the `OctaveUpConverter.channel` attribute.
+    The channel is either an IQChannel or a SingleChannel.
+
+    Args:
+        id: The RF output id, must be between 1-5.
+        LO_frequency: The local oscillator frequency in Hz, between 2 and 18 GHz.
+        LO_source: The local oscillator source, "internal" (default) or "external".
+        gain: The gain of the output, between -20 and 20 dB in steps of 0.5.
+            Default is 0 dB.
+        output_mode: Sets the fast switch's mode of the up converter module.
+            Can be "always_on" / "always_off" / "triggered" / "triggered_reversed".
+            The default is "always_off".
+            - "always_on" - Output is always on
+            - "always_off" - Output is always off
+            - "triggered" - The output will play when rising edge is detected in the
+              octave's digital port.
+            - "triggered_reversed" - The output will play when falling edge is detected
+              in the octave's digital port.
+        input_attenuators: Whether the I and Q ports have a 10 dB attenuator before
+            entering the mixer. Off by default.
+    """
+
+    LO_frequency: float = None
+    LO_source: Literal["internal", "external"] = "internal"
+    gain: float = 0
+    output_mode: Literal[
+        "always_on", "always_off", "triggered", "triggered_reversed"
+    ] = "always_off"
+    input_attenuators: Literal["off", "on"] = "off"
+
+    def apply_to_config(self, config: Dict) -> None:
+        """Add information about the frequency up-converter to the QUA config
+
+        This method is called by the `QuamComponent.generate_config` method.
+
+        Nothing is added to the config if the `OctaveUpConverter.channel` is not
+        specified or if the `OctaveUpConverter.LO_frequency` is not specified.
+
+        Args:
+            config: A dictionary representing a QUA config file.
+
+        Raises:
+            ValueError: If the LO_frequency is not specified.
+            KeyError: If the Octave is not in the config, or if config["octaves"] does
+                not exist.
+            KeyError: If the Octave already has an entry for the OctaveUpConverter.
+        """
+        if not isinstance(self.LO_frequency, (int, float)):
+            if self.channel is None:
+                return
+            else:
+                raise ValueError(
+                    f"Error generating config for Octave upconverter id={self.id}: "
+                    "LO_frequency must be specified."
+                )
+
+        super().apply_to_config(config)
+
+        if self.id in config["octaves"][self.octave.name]["RF_outputs"]:
+            raise KeyError(
+                f"Error generating config: "
+                f'config["octaves"]["{self.octave.name}"]["RF_outputs"] '
+                f'already has an entry for OctaveDownConverter with id "{self.id}"'
+            )
+
+        output_config = config["octaves"][self.octave.name]["RF_outputs"][self.id] = {
+            "LO_frequency": self.LO_frequency,
+            "LO_source": self.LO_source,
+            "gain": self.gain,
+            "output_mode": self.output_mode,
+            "input_attenuators": self.input_attenuators,
+        }
+        if isinstance(self.channel, SingleChannel):
+            if isinstance(self.channel.opx_output, LFAnalogOutputPort):
+                output_config["I_connection"] = self.channel.opx_output.port_tuple
+            else:
+                output_config["I_connection"] = self.channel.opx_output
+        elif isinstance(self.channel, IQChannel):
+            if isinstance(self.channel.opx_output_I, LFAnalogOutputPort):
+                output_config["I_connection"] = self.channel.opx_output_I.port_tuple
+            else:
+                output_config["I_connection"] = tuple(self.channel.opx_output_I)
+            if isinstance(self.channel.opx_output_Q, LFAnalogOutputPort):
+                output_config["Q_connection"] = self.channel.opx_output_Q.port_tuple
+            else:
+                output_config["Q_connection"] = tuple(self.channel.opx_output_Q)
+
+
+ + + +
+ + + + + + + + + +
+ + +

+ apply_to_config(config) + +

+ + +
+ +

Add information about the frequency up-converter to the QUA config

+

This method is called by the QuamComponent.generate_config method.

+

Nothing is added to the config if the OctaveUpConverter.channel is not +specified or if the OctaveUpConverter.LO_frequency is not specified.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
config + Dict + +
+

A dictionary representing a QUA config file.

+
+ 		+ required +
+ + +

Raises:

+ + + + + + + + + + + + + + + + + + + + + +
TypeDescription
+ ValueError + +
+

If the LO_frequency is not specified.

+
+
+ KeyError + +
+

If the Octave is not in the config, or if config["octaves"] does +not exist.

+
+
+ KeyError + +
+

If the Octave already has an entry for the OctaveUpConverter.

+
+
+ +
+ Source code in quam/components/octave.py + 
239
+240
+241
+242
+243
+244
+245
+246
+247
+248
+249
+250
+251
+252
+253
+254
+255
+256
+257
+258
+259
+260
+261
+262
+263
+264
+265
+266
+267
+268
+269
+270
+271
+272
+273
+274
+275
+276
+277
+278
+279
+280
+281
+282
+283
+284
+285
+286
+287
+288
+289
+290
+291
+292
+293
+294
def apply_to_config(self, config: Dict) -> None:
+    """Add information about the frequency up-converter to the QUA config
+
+    This method is called by the `QuamComponent.generate_config` method.
+
+    Nothing is added to the config if the `OctaveUpConverter.channel` is not
+    specified or if the `OctaveUpConverter.LO_frequency` is not specified.
+
+    Args:
+        config: A dictionary representing a QUA config file.
+
+    Raises:
+        ValueError: If the LO_frequency is not specified.
+        KeyError: If the Octave is not in the config, or if config["octaves"] does
+            not exist.
+        KeyError: If the Octave already has an entry for the OctaveUpConverter.
+    """
+    if not isinstance(self.LO_frequency, (int, float)):
+        if self.channel is None:
+            return
+        else:
+            raise ValueError(
+                f"Error generating config for Octave upconverter id={self.id}: "
+                "LO_frequency must be specified."
+            )
+
+    super().apply_to_config(config)
+
+    if self.id in config["octaves"][self.octave.name]["RF_outputs"]:
+        raise KeyError(
+            f"Error generating config: "
+            f'config["octaves"]["{self.octave.name}"]["RF_outputs"] '
+            f'already has an entry for OctaveDownConverter with id "{self.id}"'
+        )
+
+    output_config = config["octaves"][self.octave.name]["RF_outputs"][self.id] = {
+        "LO_frequency": self.LO_frequency,
+        "LO_source": self.LO_source,
+        "gain": self.gain,
+        "output_mode": self.output_mode,
+        "input_attenuators": self.input_attenuators,
+    }
+    if isinstance(self.channel, SingleChannel):
+        if isinstance(self.channel.opx_output, LFAnalogOutputPort):
+            output_config["I_connection"] = self.channel.opx_output.port_tuple
+        else:
+            output_config["I_connection"] = self.channel.opx_output
+    elif isinstance(self.channel, IQChannel):
+        if isinstance(self.channel.opx_output_I, LFAnalogOutputPort):
+            output_config["I_connection"] = self.channel.opx_output_I.port_tuple
+        else:
+            output_config["I_connection"] = tuple(self.channel.opx_output_I)
+        if isinstance(self.channel.opx_output_Q, LFAnalogOutputPort):
+            output_config["Q_connection"] = self.channel.opx_output_Q.port_tuple
+        else:
+            output_config["Q_connection"] = tuple(self.channel.opx_output_Q)
+
+
+
+ +
+ + + +
+ +
+ +
+ + + + +
+ +
+ +
+ + + + + + + + + + + + + +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API_references/components/octave_API/index.html b/API_references/components/octave_API/index.html new file mode 100644 index 00000000..71b46896 --- /dev/null +++ b/API_references/components/octave_API/index.html @@ -0,0 +1,3320 @@ + + + + + + + + + + + + + + + + + + + + + + + + + QuAM Octave API - The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ + + + +

Welcome to the QuAM Octave API Documentation

+

The Octave component in the Quantum Abstract Machine (QuAM) manages signal upconversion and downconversion through its frequency converters. This section provides an API guide for setting up and customizing the Octave, detailing its integration with quantum processors for efficient signal processing. Explore the capabilities, configuration options, and practical examples to enhance your quantum operations with Octave's advanced functionalities.

+ + +
+ + + + +
+ + + +
+ + + + + + + + +
+ + + +

+ Octave + + +

+ + +
+

+ Bases: QuamComponent

+ + +

QuAM component for the QM Octave.

+

The QM Octave is a device that can be used to upconvert and downconvert signals. It +has 5 RF outputs and 2 RF inputs. Each RF_output has an associated +OctaveUpConverter, and similarly each RF_input has an OctaveDownConverter.

+

In many cases the Octave is connected to a single OPX in the default configuration, +i.e. OPX outputs are connected to the corresponding Octave I/Q input, and Octave IF +outputs are connected to the corresponding OPX input. In this case you can configure +the Octave with the correct FrequencyConverters using +Octave.initialize_default_connectivity().

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
name + +
+

The name of the Octave. Must be unique

+
+ 		+ required +
ip + +
+

The IP address of the Octave. Used in Octave.get_octave_config()

+
+ 		+ required +
port + +
+

The port number of the Octave. Used in Octave.get_octave_config()

+
+ 		+ required +
calibration_db_path + +
+

The path to the calibration database. If not specified, the +current working directory is used.

+
+ 		+ required +
RF_outputs + +
+

A dictionary of OctaveUpConverter objects. The keys are the +output numbers (1-5).

+
+ 		+ required +
RF_inputs + +
+

A dictionary of OctaveDownConverter objects. The keys are the +input numbers (1-2).

+
+ 		+ required +
loopbacks + +
+

A list of loopback connections, for example to connect a local +oscillator. See the QUA Octave documentation for details.

+
+ 		+ required +
+ +
+ Source code in quam/components/octave.py + 
 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
@quam_dataclass
+class Octave(QuamComponent):
+    """QuAM component for the QM Octave.
+
+    The QM Octave is a device that can be used to upconvert and downconvert signals. It
+    has 5 RF outputs and 2 RF inputs. Each RF_output has an associated
+    `OctaveUpConverter`, and similarly each RF_input has an `OctaveDownConverter`.
+
+    In many cases the Octave is connected to a single OPX in the default configuration,
+    i.e. OPX outputs are connected to the corresponding Octave I/Q input, and Octave IF
+    outputs are connected to the corresponding OPX input. In this case you can configure
+    the Octave with the correct `FrequencyConverter`s using
+    `Octave.initialize_default_connectivity()`.
+
+    Args:
+        name: The name of the Octave. Must be unique
+        ip: The IP address of the Octave. Used in `Octave.get_octave_config()`
+        port: The port number of the Octave. Used in `Octave.get_octave_config()`
+        calibration_db_path: The path to the calibration database. If not specified, the
+            current working directory is used.
+        RF_outputs: A dictionary of `OctaveUpConverter` objects. The keys are the
+            output numbers (1-5).
+        RF_inputs: A dictionary of `OctaveDownConverter` objects. The keys are the
+            input numbers (1-2).
+        loopbacks: A list of loopback connections, for example to connect a local
+            oscillator. See the QUA Octave documentation for details.
+    """
+
+    name: str
+    ip: str
+    port: int
+    calibration_db_path: str = None
+
+    RF_outputs: Dict[int, "OctaveUpConverter"] = field(default_factory=dict)
+    RF_inputs: Dict[int, "OctaveDownConverter"] = field(default_factory=dict)
+    loopbacks: List[Tuple[Tuple[str, str], str]] = field(default_factory=list)
+
+    def initialize_frequency_converters(self):
+        """Initialize the Octave frequency converterswith default connectivity.
+
+        This method initializes the Octave with default connectivity, i.e. it connects
+        the Octave to a single OPX. It creates an `OctaveUpConverter` for each RF output
+        and an `OctaveDownConverter` for each RF input. The `OctaveUpConverter` objects
+        are added to `Octave.RF_outputs` and the `OctaveDownConverter` objects are added
+        to `Octave.RF_inputs`.
+
+        Raises:
+            ValueError: If the Octave already has RF_outputs or RF_inputs.
+
+        """
+        if self.RF_outputs:
+            raise ValueError(
+                "Error initializing Octave with default connectivity. "
+                "octave.RF_outputs is not empty"
+            )
+        if self.RF_inputs:
+            raise ValueError(
+                "Error initializing Octave with default connectivity. "
+                "octave.IF_outputs is not empty"
+            )
+
+        for idx in range(1, 6):
+            self.RF_outputs[idx] = OctaveUpConverter(
+                id=idx,
+                LO_frequency=None,  # TODO What should default be?
+            )
+
+        for idx in range(1, 3):
+            LO_source = "internal" if idx == 1 else "external"
+            self.RF_inputs[idx] = OctaveDownConverter(
+                id=idx, LO_frequency=None, LO_source=LO_source
+            )
+
+    def get_octave_config(self) -> QmOctaveConfig:
+        """Return a QmOctaveConfig object with the current Octave configuration."""
+        octave_config = QmOctaveConfig()
+
+        if self.calibration_db_path is not None:
+            octave_config.set_calibration_db(self.calibration_db_path)
+        else:
+            octave_config.set_calibration_db(os.getcwd())
+
+        octave_config.add_device_info(self.name, self.ip, self.port)
+        return octave_config
+
+    def apply_to_config(self, config: Dict) -> None:
+        """Add the Octave configuration to a config dictionary.
+
+        This method is called by the `QuamComponent.generate_config` method.
+
+        Args:
+            config: A dictionary representing a QUA config file.
+
+        Raises:
+            KeyError: If the Octave is already in the config.
+        """
+        if "octaves" not in config:
+            config["octaves"] = {}
+        if self.name in config["octaves"]:
+            raise KeyError(
+                f'Error generating config: config["octaves"] already contains an entry '
+                f' for Octave "{self.name}"'
+            )
+
+        config["octaves"][self.name] = {
+            "RF_outputs": {},
+            "IF_outputs": {},
+            "RF_inputs": {},
+            "loopbacks": list(self.loopbacks),
+        }
+
+
+ + + +
+ + + + + + + + + +
+ + +

+ apply_to_config(config) + +

+ + +
+ +

Add the Octave configuration to a config dictionary.

+

This method is called by the QuamComponent.generate_config method.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
config + Dict + +
+

A dictionary representing a QUA config file.

+
+ 		+ required +
+ + +

Raises:

+ + + + + + + + + + + + + +
TypeDescription
+ KeyError + +
+

If the Octave is already in the config.

+
+
+ +
+ Source code in quam/components/octave.py + 
117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
def apply_to_config(self, config: Dict) -> None:
+    """Add the Octave configuration to a config dictionary.
+
+    This method is called by the `QuamComponent.generate_config` method.
+
+    Args:
+        config: A dictionary representing a QUA config file.
+
+    Raises:
+        KeyError: If the Octave is already in the config.
+    """
+    if "octaves" not in config:
+        config["octaves"] = {}
+    if self.name in config["octaves"]:
+        raise KeyError(
+            f'Error generating config: config["octaves"] already contains an entry '
+            f' for Octave "{self.name}"'
+        )
+
+    config["octaves"][self.name] = {
+        "RF_outputs": {},
+        "IF_outputs": {},
+        "RF_inputs": {},
+        "loopbacks": list(self.loopbacks),
+    }
+
+
+
+ +
+ +
+ + +

+ get_octave_config() + +

+ + +
+ +

Return a QmOctaveConfig object with the current Octave configuration.

+ +
+ Source code in quam/components/octave.py + 
105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
def get_octave_config(self) -> QmOctaveConfig:
+    """Return a QmOctaveConfig object with the current Octave configuration."""
+    octave_config = QmOctaveConfig()
+
+    if self.calibration_db_path is not None:
+        octave_config.set_calibration_db(self.calibration_db_path)
+    else:
+        octave_config.set_calibration_db(os.getcwd())
+
+    octave_config.add_device_info(self.name, self.ip, self.port)
+    return octave_config
+
+
+
+ +
+ +
+ + +

+ initialize_frequency_converters() + +

+ + +
+ +

Initialize the Octave frequency converterswith default connectivity.

+

This method initializes the Octave with default connectivity, i.e. it connects +the Octave to a single OPX. It creates an OctaveUpConverter for each RF output +and an OctaveDownConverter for each RF input. The OctaveUpConverter objects +are added to Octave.RF_outputs and the OctaveDownConverter objects are added +to Octave.RF_inputs.

+ + +

Raises:

+ + + + + + + + + + + + + +
TypeDescription
+ ValueError + +
+

If the Octave already has RF_outputs or RF_inputs.

+
+
+ +
+ Source code in quam/components/octave.py + 
 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
def initialize_frequency_converters(self):
+    """Initialize the Octave frequency converterswith default connectivity.
+
+    This method initializes the Octave with default connectivity, i.e. it connects
+    the Octave to a single OPX. It creates an `OctaveUpConverter` for each RF output
+    and an `OctaveDownConverter` for each RF input. The `OctaveUpConverter` objects
+    are added to `Octave.RF_outputs` and the `OctaveDownConverter` objects are added
+    to `Octave.RF_inputs`.
+
+    Raises:
+        ValueError: If the Octave already has RF_outputs or RF_inputs.
+
+    """
+    if self.RF_outputs:
+        raise ValueError(
+            "Error initializing Octave with default connectivity. "
+            "octave.RF_outputs is not empty"
+        )
+    if self.RF_inputs:
+        raise ValueError(
+            "Error initializing Octave with default connectivity. "
+            "octave.IF_outputs is not empty"
+        )
+
+    for idx in range(1, 6):
+        self.RF_outputs[idx] = OctaveUpConverter(
+            id=idx,
+            LO_frequency=None,  # TODO What should default be?
+        )
+
+    for idx in range(1, 3):
+        LO_source = "internal" if idx == 1 else "external"
+        self.RF_inputs[idx] = OctaveDownConverter(
+            id=idx, LO_frequency=None, LO_source=LO_source
+        )
+
+
+
+ +
+ + + +
+ +
+ +
+ +
+ + + +

+ OctaveFrequencyConverter + + +

+ + +
+

+ Bases: BaseFrequencyConverter, ABC

+ + +

Base class for OctaveUpConverter and OctaveDownConverter.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
id + +
+

The id of the converter. Must be unique within the Octave. +For OctaveUpConverter, the id is used as the RF output number. +For OctaveDownConverter, the id is used as the RF input number.

+
+ 		+ required +
channel + +
+

The channel that the converter is connected to.

+
+ 		+ required +
+ +
+ Source code in quam/components/octave.py + 
144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
+182
+183
+184
+185
+186
+187
+188
+189
+190
+191
+192
+193
+194
+195
+196
+197
+198
+199
@quam_dataclass
+class OctaveFrequencyConverter(BaseFrequencyConverter, ABC):
+    """Base class for OctaveUpConverter and OctaveDownConverter.
+
+    Args:
+        id: The id of the converter. Must be unique within the Octave.
+            For OctaveUpConverter, the id is used as the RF output number.
+            For OctaveDownConverter, the id is used as the RF input number.
+        channel: The channel that the converter is connected to.
+    """
+
+    id: int
+    channel: Channel = None
+
+    @property
+    def octave(self) -> Optional[Octave]:
+        if self.parent is None:
+            return None
+        parent_parent = getattr(self.parent, "parent")
+        if not isinstance(parent_parent, Octave):
+            return None
+        return parent_parent
+
+    @property
+    def config_settings(self) -> Dict[str, Any]:
+        """Specifies that the converter will be added to the config after the Octave."""
+        return {"after": [self.octave]}
+
+    def apply_to_config(self, config: Dict) -> None:
+        """Add information about the frequency converter to the QUA config
+
+        This method is called by the `QuamComponent.generate_config` method.
+
+        Args:
+            config: A dictionary representing a QUA config file.
+
+        Raises:
+            KeyError: If the Octave is not in the config, or if config["octaves"] does
+                not exist.
+        """
+        super().apply_to_config(config)
+
+        if "octaves" not in config:
+            raise KeyError('Error generating config: "octaves" entry not found')
+
+        if self.octave is None:
+            raise KeyError(
+                f"Error generating config: OctaveConverter with id {self.id} does not "
+                "have an Octave parent"
+            )
+
+        if self.octave.name not in config["octaves"]:
+            raise KeyError(
+                'Error generating config: config["octaves"] does not have Octave'
+                f' entry config["octaves"]["{self.octave.name}"]'
+            )
+
+
+ + + +
+ + + + + + + +
+ + + +

+ config_settings: Dict[str, Any] + + + property + + +

+ + +
+ +

Specifies that the converter will be added to the config after the Octave.

+
+ +
+ + + +
+ + +

+ apply_to_config(config) + +

+ + +
+ +

Add information about the frequency converter to the QUA config

+

This method is called by the QuamComponent.generate_config method.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
config + Dict + +
+

A dictionary representing a QUA config file.

+
+ 		+ required +
+ + +

Raises:

+ + + + + + + + + + + + + +
TypeDescription
+ KeyError + +
+

If the Octave is not in the config, or if config["octaves"] does +not exist.

+
+
+ +
+ Source code in quam/components/octave.py + 
172
+173
+174
+175
+176
+177
+178
+179
+180
+181
+182
+183
+184
+185
+186
+187
+188
+189
+190
+191
+192
+193
+194
+195
+196
+197
+198
+199
def apply_to_config(self, config: Dict) -> None:
+    """Add information about the frequency converter to the QUA config
+
+    This method is called by the `QuamComponent.generate_config` method.
+
+    Args:
+        config: A dictionary representing a QUA config file.
+
+    Raises:
+        KeyError: If the Octave is not in the config, or if config["octaves"] does
+            not exist.
+    """
+    super().apply_to_config(config)
+
+    if "octaves" not in config:
+        raise KeyError('Error generating config: "octaves" entry not found')
+
+    if self.octave is None:
+        raise KeyError(
+            f"Error generating config: OctaveConverter with id {self.id} does not "
+            "have an Octave parent"
+        )
+
+    if self.octave.name not in config["octaves"]:
+        raise KeyError(
+            'Error generating config: config["octaves"] does not have Octave'
+            f' entry config["octaves"]["{self.octave.name}"]'
+        )
+
+
+
+ +
+ + + +
+ +
+ +
+ +
+ + + +

+ OctaveUpConverter + + +

+ + +
+

+ Bases: OctaveFrequencyConverter

+ + +

A frequency upconverter for the QM Octave.

+

The OctaveUpConverter represents a frequency upconverter in the QM Octave. Usually +an IQChannel is connected OctaveUpconverter.channel, in which case the two OPX +outputs are connected to the I and Q inputs of the OctaveUpConverter. +The OPX outputs are specified in the OctaveUpConverter.channel attribute. +The channel is either an IQChannel or a SingleChannel.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
id + +
+

The RF output id, must be between 1-5.

+
+ 		+ required +
LO_frequency + +
+

The local oscillator frequency in Hz, between 2 and 18 GHz.

+
+ 		+ required +
LO_source + +
+

The local oscillator source, "internal" (default) or "external".

+
+ 		+ required +
gain + +
+

The gain of the output, between -20 and 20 dB in steps of 0.5. +Default is 0 dB.

+
+ 		+ required +
output_mode + +
+

Sets the fast switch's mode of the up converter module. +Can be "always_on" / "always_off" / "triggered" / "triggered_reversed". +The default is "always_off". +- "always_on" - Output is always on +- "always_off" - Output is always off +- "triggered" - The output will play when rising edge is detected in the + octave's digital port. +- "triggered_reversed" - The output will play when falling edge is detected + in the octave's digital port.

+
+ 		+ required +
input_attenuators + +
+

Whether the I and Q ports have a 10 dB attenuator before +entering the mixer. Off by default.

+
+ 		+ required +
+ +
+ Source code in quam/components/octave.py + 
202
+203
+204
+205
+206
+207
+208
+209
+210
+211
+212
+213
+214
+215
+216
+217
+218
+219
+220
+221
+222
+223
+224
+225
+226
+227
+228
+229
+230
+231
+232
+233
+234
+235
+236
+237
+238
+239
+240
+241
+242
+243
+244
+245
+246
+247
+248
+249
+250
+251
+252
+253
+254
+255
+256
+257
+258
+259
+260
+261
+262
+263
+264
+265
+266
+267
+268
+269
+270
+271
+272
+273
+274
+275
+276
+277
+278
+279
+280
+281
+282
+283
+284
+285
+286
+287
+288
+289
+290
+291
+292
+293
+294
@quam_dataclass
+class OctaveUpConverter(OctaveFrequencyConverter):
+    """A frequency upconverter for the QM Octave.
+
+    The OctaveUpConverter represents a frequency upconverter in the QM Octave. Usually
+    an IQChannel is connected `OctaveUpconverter.channel`, in which case the two OPX
+    outputs are connected to the I and Q inputs of the OctaveUpConverter.
+    The OPX outputs are specified in the `OctaveUpConverter.channel` attribute.
+    The channel is either an IQChannel or a SingleChannel.
+
+    Args:
+        id: The RF output id, must be between 1-5.
+        LO_frequency: The local oscillator frequency in Hz, between 2 and 18 GHz.
+        LO_source: The local oscillator source, "internal" (default) or "external".
+        gain: The gain of the output, between -20 and 20 dB in steps of 0.5.
+            Default is 0 dB.
+        output_mode: Sets the fast switch's mode of the up converter module.
+            Can be "always_on" / "always_off" / "triggered" / "triggered_reversed".
+            The default is "always_off".
+            - "always_on" - Output is always on
+            - "always_off" - Output is always off
+            - "triggered" - The output will play when rising edge is detected in the
+              octave's digital port.
+            - "triggered_reversed" - The output will play when falling edge is detected
+              in the octave's digital port.
+        input_attenuators: Whether the I and Q ports have a 10 dB attenuator before
+            entering the mixer. Off by default.
+    """
+
+    LO_frequency: float = None
+    LO_source: Literal["internal", "external"] = "internal"
+    gain: float = 0
+    output_mode: Literal[
+        "always_on", "always_off", "triggered", "triggered_reversed"
+    ] = "always_off"
+    input_attenuators: Literal["off", "on"] = "off"
+
+    def apply_to_config(self, config: Dict) -> None:
+        """Add information about the frequency up-converter to the QUA config
+
+        This method is called by the `QuamComponent.generate_config` method.
+
+        Nothing is added to the config if the `OctaveUpConverter.channel` is not
+        specified or if the `OctaveUpConverter.LO_frequency` is not specified.
+
+        Args:
+            config: A dictionary representing a QUA config file.
+
+        Raises:
+            ValueError: If the LO_frequency is not specified.
+            KeyError: If the Octave is not in the config, or if config["octaves"] does
+                not exist.
+            KeyError: If the Octave already has an entry for the OctaveUpConverter.
+        """
+        if not isinstance(self.LO_frequency, (int, float)):
+            if self.channel is None:
+                return
+            else:
+                raise ValueError(
+                    f"Error generating config for Octave upconverter id={self.id}: "
+                    "LO_frequency must be specified."
+                )
+
+        super().apply_to_config(config)
+
+        if self.id in config["octaves"][self.octave.name]["RF_outputs"]:
+            raise KeyError(
+                f"Error generating config: "
+                f'config["octaves"]["{self.octave.name}"]["RF_outputs"] '
+                f'already has an entry for OctaveDownConverter with id "{self.id}"'
+            )
+
+        output_config = config["octaves"][self.octave.name]["RF_outputs"][self.id] = {
+            "LO_frequency": self.LO_frequency,
+            "LO_source": self.LO_source,
+            "gain": self.gain,
+            "output_mode": self.output_mode,
+            "input_attenuators": self.input_attenuators,
+        }
+        if isinstance(self.channel, SingleChannel):
+            if isinstance(self.channel.opx_output, LFAnalogOutputPort):
+                output_config["I_connection"] = self.channel.opx_output.port_tuple
+            else:
+                output_config["I_connection"] = self.channel.opx_output
+        elif isinstance(self.channel, IQChannel):
+            if isinstance(self.channel.opx_output_I, LFAnalogOutputPort):
+                output_config["I_connection"] = self.channel.opx_output_I.port_tuple
+            else:
+                output_config["I_connection"] = tuple(self.channel.opx_output_I)
+            if isinstance(self.channel.opx_output_Q, LFAnalogOutputPort):
+                output_config["Q_connection"] = self.channel.opx_output_Q.port_tuple
+            else:
+                output_config["Q_connection"] = tuple(self.channel.opx_output_Q)
+
+
+ + + +
+ + + + + + + + + +
+ + +

+ apply_to_config(config) + +

+ + +
+ +

Add information about the frequency up-converter to the QUA config

+

This method is called by the QuamComponent.generate_config method.

+

Nothing is added to the config if the OctaveUpConverter.channel is not +specified or if the OctaveUpConverter.LO_frequency is not specified.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
config + Dict + +
+

A dictionary representing a QUA config file.

+
+ 		+ required +
+ + +

Raises:

+ + + + + + + + + + + + + + + + + + + + + +
TypeDescription
+ ValueError + +
+

If the LO_frequency is not specified.

+
+
+ KeyError + +
+

If the Octave is not in the config, or if config["octaves"] does +not exist.

+
+
+ KeyError + +
+

If the Octave already has an entry for the OctaveUpConverter.

+
+
+ +
+ Source code in quam/components/octave.py + 
239
+240
+241
+242
+243
+244
+245
+246
+247
+248
+249
+250
+251
+252
+253
+254
+255
+256
+257
+258
+259
+260
+261
+262
+263
+264
+265
+266
+267
+268
+269
+270
+271
+272
+273
+274
+275
+276
+277
+278
+279
+280
+281
+282
+283
+284
+285
+286
+287
+288
+289
+290
+291
+292
+293
+294
def apply_to_config(self, config: Dict) -> None:
+    """Add information about the frequency up-converter to the QUA config
+
+    This method is called by the `QuamComponent.generate_config` method.
+
+    Nothing is added to the config if the `OctaveUpConverter.channel` is not
+    specified or if the `OctaveUpConverter.LO_frequency` is not specified.
+
+    Args:
+        config: A dictionary representing a QUA config file.
+
+    Raises:
+        ValueError: If the LO_frequency is not specified.
+        KeyError: If the Octave is not in the config, or if config["octaves"] does
+            not exist.
+        KeyError: If the Octave already has an entry for the OctaveUpConverter.
+    """
+    if not isinstance(self.LO_frequency, (int, float)):
+        if self.channel is None:
+            return
+        else:
+            raise ValueError(
+                f"Error generating config for Octave upconverter id={self.id}: "
+                "LO_frequency must be specified."
+            )
+
+    super().apply_to_config(config)
+
+    if self.id in config["octaves"][self.octave.name]["RF_outputs"]:
+        raise KeyError(
+            f"Error generating config: "
+            f'config["octaves"]["{self.octave.name}"]["RF_outputs"] '
+            f'already has an entry for OctaveDownConverter with id "{self.id}"'
+        )
+
+    output_config = config["octaves"][self.octave.name]["RF_outputs"][self.id] = {
+        "LO_frequency": self.LO_frequency,
+        "LO_source": self.LO_source,
+        "gain": self.gain,
+        "output_mode": self.output_mode,
+        "input_attenuators": self.input_attenuators,
+    }
+    if isinstance(self.channel, SingleChannel):
+        if isinstance(self.channel.opx_output, LFAnalogOutputPort):
+            output_config["I_connection"] = self.channel.opx_output.port_tuple
+        else:
+            output_config["I_connection"] = self.channel.opx_output
+    elif isinstance(self.channel, IQChannel):
+        if isinstance(self.channel.opx_output_I, LFAnalogOutputPort):
+            output_config["I_connection"] = self.channel.opx_output_I.port_tuple
+        else:
+            output_config["I_connection"] = tuple(self.channel.opx_output_I)
+        if isinstance(self.channel.opx_output_Q, LFAnalogOutputPort):
+            output_config["Q_connection"] = self.channel.opx_output_Q.port_tuple
+        else:
+            output_config["Q_connection"] = tuple(self.channel.opx_output_Q)
+
+
+
+ +
+ + + +
+ +
+ +
+ +
+ + + +

+ OctaveDownConverter + + +

+ + +
+

+ Bases: OctaveFrequencyConverter

+ + +

A frequency downconverter for the QM Octave.

+

The OctaveDownConverter represents a frequency downconverter in the QM Octave. The +OctaveDownConverter is usually connected to an InOutIQChannel, in which case the +two OPX inputs are connected to the IF outputs of the OctaveDownConverter. The +OPX inputs are specified in the OctaveDownConverter.channel attribute. The +channel is either an InOutIQChannel or an InOutSingleChannel.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
id + +
+

The RF input id, must be between 1-2.

+
+ 		+ required +
LO_frequency + +
+

The local oscillator frequency in Hz, between 2 and 18 GHz.

+
+ 		+ required +
LO_source + +
+

The local oscillator source, "internal" or "external. +For down converter 1 "internal" is the default, +for down converter 2 "external" is the default.

+
+ 		+ required +
IF_mode_I + +
+

Sets the mode of the I port of the IF Down Converter module as can be +seen in the octave block diagram (see Octave page in QUA documentation). +Can be "direct" / "envelope" / "mixer" / "off". The default is "direct". +- "direct" - The signal bypasses the IF module. +- "envelope" - The signal passes through an envelope detector. +- "mixer" - The signal passes through a low-frequency mixer. +- "off" - the signal doesn't pass to the output port.

+
+ 		+ required +
IF_mode_Q + +
+

Sets the mode of the Q port of the IF Down Converter module.

+
+ 		+ required +
IF_output_I + +
+

The output port of the IF Down Converter module for the I port. +Can be 1 or 2. The default is 1. This will be 2 if the IF outputs +are connected to the opposite OPX inputs

+
+ 		+ required +
IF_output_Q + +
+

The output port of the IF Down Converter module for the Q port. +Can be 1 or 2. The default is 2. This will be 1 if the IF outputs +are connected to the opposite OPX inputs.

+
+ 		+ required +
+ +
+ Source code in quam/components/octave.py + 
297
+298
+299
+300
+301
+302
+303
+304
+305
+306
+307
+308
+309
+310
+311
+312
+313
+314
+315
+316
+317
+318
+319
+320
+321
+322
+323
+324
+325
+326
+327
+328
+329
+330
+331
+332
+333
+334
+335
+336
+337
+338
+339
+340
+341
+342
+343
+344
+345
+346
+347
+348
+349
+350
+351
+352
+353
+354
+355
+356
+357
+358
+359
+360
+361
+362
+363
+364
+365
+366
+367
+368
+369
+370
+371
+372
+373
+374
+375
+376
+377
+378
+379
+380
+381
+382
+383
+384
+385
+386
+387
+388
+389
+390
+391
+392
+393
+394
+395
+396
+397
+398
+399
+400
+401
+402
+403
+404
+405
+406
+407
+408
+409
+410
+411
@quam_dataclass
+class OctaveDownConverter(OctaveFrequencyConverter):
+    """A frequency downconverter for the QM Octave.
+
+    The OctaveDownConverter represents a frequency downconverter in the QM Octave. The
+    OctaveDownConverter is usually connected to an InOutIQChannel, in which case the
+    two OPX inputs are connected to the IF outputs of the OctaveDownConverter. The
+    OPX inputs are specified in the `OctaveDownConverter.channel` attribute. The
+    channel is either an InOutIQChannel or an InOutSingleChannel.
+
+    Args:
+        id: The RF input id, must be between 1-2.
+        LO_frequency: The local oscillator frequency in Hz, between 2 and 18 GHz.
+        LO_source: The local oscillator source, "internal" or "external.
+            For down converter 1 "internal" is the default,
+            for down converter 2 "external" is the default.
+        IF_mode_I: Sets the mode of the I port of the IF Down Converter module as can be
+            seen in the octave block diagram (see Octave page in QUA documentation).
+            Can be "direct" / "envelope" / "mixer" / "off". The default is "direct".
+            - "direct" - The signal bypasses the IF module.
+            - "envelope" - The signal passes through an envelope detector.
+            - "mixer" - The signal passes through a low-frequency mixer.
+            - "off" - the signal doesn't pass to the output port.
+        IF_mode_Q: Sets the mode of the Q port of the IF Down Converter module.
+        IF_output_I: The output port of the IF Down Converter module for the I port.
+            Can be 1 or 2. The default is 1. This will be 2 if the IF outputs
+            are connected to the opposite OPX inputs
+        IF_output_Q: The output port of the IF Down Converter module for the Q port.
+            Can be 1 or 2. The default is 2. This will be 1 if the IF outputs
+            are connected to the opposite OPX inputs.
+    """
+
+    LO_frequency: float = None
+    LO_source: Literal["internal", "external"] = "internal"
+    IF_mode_I: Literal["direct", "envelope", "mixer", "off"] = "direct"
+    IF_mode_Q: Literal["direct", "envelope", "mixer", "off"] = "direct"
+    IF_output_I: Literal[1, 2] = 1
+    IF_output_Q: Literal[1, 2] = 2
+
+    @property
+    def config_settings(self):
+        """Specifies that the converter will be added to the config after the Octave."""
+        return {"after": [self.octave]}
+
+    def apply_to_config(self, config: Dict) -> None:
+        """Add information about the frequency down-converter to the QUA config
+
+        This method is called by the `QuamComponent.generate_config` method.
+
+        Nothing is added to the config if the `OctaveDownConverter.channel` is not
+        specified or if the `OctaveDownConverter.LO_frequency` is not specified.
+
+        Args:
+            config: A dictionary representing a QUA config file.
+
+        Raises:
+            ValueError: If the LO_frequency is not specified.
+            KeyError: If the Octave is not in the config, or if config["octaves"] does
+                not exist.
+            KeyError: If the Octave already has an entry for the OctaveDownConverter.
+            ValueError: If the IF_output_I and IF_output_Q are already assigned to
+                other ports.
+        """
+        if not isinstance(self.LO_frequency, (int, float)):
+            if self.channel is None:
+                return
+            else:
+                raise ValueError(
+                    f"Error generating config for Octave upconverter id={self.id}: "
+                    "LO_frequency must be specified."
+                )
+
+        super().apply_to_config(config)
+
+        if self.id in config["octaves"][self.octave.name]["RF_inputs"]:
+            raise KeyError(
+                f"Error generating config: "
+                f'config["octaves"]["{self.octave.name}"]["RF_inputs"] '
+                f'already has an entry for OctaveDownConverter with id "{self.id}"'
+            )
+
+        config["octaves"][self.octave.name]["RF_inputs"][self.id] = {
+            "RF_source": "RF_in",
+            "LO_frequency": self.LO_frequency,
+            "LO_source": self.LO_source,
+            "IF_mode_I": self.IF_mode_I,
+            "IF_mode_Q": self.IF_mode_Q,
+        }
+
+        if isinstance(self.channel, InOutIQChannel):
+            IF_channels = [self.IF_output_I, self.IF_output_Q]
+            opx_channels = [self.channel.opx_input_I, self.channel.opx_input_Q]
+        elif isinstance(self.channel, InOutSingleChannel):
+            IF_channels = [self.IF_output_I]
+            opx_channels = [self.channel.opx_input]
+        else:
+            IF_channels = []
+            opx_channels = []
+
+        opx_port_tuples = [
+            p.port_tuple if isinstance(p, BasePort) else tuple(p) for p in opx_channels
+        ]
+
+        IF_config = config["octaves"][self.octave.name]["IF_outputs"]
+        for k, (IF_ch, opx_port_tuples) in enumerate(
+            zip(IF_channels, opx_port_tuples), start=1
+        ):
+            label = f"IF_out{IF_ch}"
+            IF_config.setdefault(label, {"port": opx_port_tuples, "name": f"out{k}"})
+            if IF_config[label]["port"] != opx_port_tuples:
+                raise ValueError(
+                    f"Error generating config for Octave downconverter id={self.id}: "
+                    f"Unable to assign {label} to  port {opx_port_tuples} because it is already "
+                    f"assigned to port {IF_config[label]['port']} "
+                )
+
+
+ + + +
+ + + + + + + +
+ + + +

+ config_settings + + + property + + +

+ + +
+ +

Specifies that the converter will be added to the config after the Octave.

+
+ +
+ + + +
+ + +

+ apply_to_config(config) + +

+ + +
+ +

Add information about the frequency down-converter to the QUA config

+

This method is called by the QuamComponent.generate_config method.

+

Nothing is added to the config if the OctaveDownConverter.channel is not +specified or if the OctaveDownConverter.LO_frequency is not specified.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
config + Dict + +
+

A dictionary representing a QUA config file.

+
+ 		+ required +
+ + +

Raises:

+ + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDescription
+ ValueError + +
+

If the LO_frequency is not specified.

+
+
+ KeyError + +
+

If the Octave is not in the config, or if config["octaves"] does +not exist.

+
+
+ KeyError + +
+

If the Octave already has an entry for the OctaveDownConverter.

+
+
+ ValueError + +
+

If the IF_output_I and IF_output_Q are already assigned to +other ports.

+
+
+ +
+ Source code in quam/components/octave.py + 
341
+342
+343
+344
+345
+346
+347
+348
+349
+350
+351
+352
+353
+354
+355
+356
+357
+358
+359
+360
+361
+362
+363
+364
+365
+366
+367
+368
+369
+370
+371
+372
+373
+374
+375
+376
+377
+378
+379
+380
+381
+382
+383
+384
+385
+386
+387
+388
+389
+390
+391
+392
+393
+394
+395
+396
+397
+398
+399
+400
+401
+402
+403
+404
+405
+406
+407
+408
+409
+410
+411
def apply_to_config(self, config: Dict) -> None:
+    """Add information about the frequency down-converter to the QUA config
+
+    This method is called by the `QuamComponent.generate_config` method.
+
+    Nothing is added to the config if the `OctaveDownConverter.channel` is not
+    specified or if the `OctaveDownConverter.LO_frequency` is not specified.
+
+    Args:
+        config: A dictionary representing a QUA config file.
+
+    Raises:
+        ValueError: If the LO_frequency is not specified.
+        KeyError: If the Octave is not in the config, or if config["octaves"] does
+            not exist.
+        KeyError: If the Octave already has an entry for the OctaveDownConverter.
+        ValueError: If the IF_output_I and IF_output_Q are already assigned to
+            other ports.
+    """
+    if not isinstance(self.LO_frequency, (int, float)):
+        if self.channel is None:
+            return
+        else:
+            raise ValueError(
+                f"Error generating config for Octave upconverter id={self.id}: "
+                "LO_frequency must be specified."
+            )
+
+    super().apply_to_config(config)
+
+    if self.id in config["octaves"][self.octave.name]["RF_inputs"]:
+        raise KeyError(
+            f"Error generating config: "
+            f'config["octaves"]["{self.octave.name}"]["RF_inputs"] '
+            f'already has an entry for OctaveDownConverter with id "{self.id}"'
+        )
+
+    config["octaves"][self.octave.name]["RF_inputs"][self.id] = {
+        "RF_source": "RF_in",
+        "LO_frequency": self.LO_frequency,
+        "LO_source": self.LO_source,
+        "IF_mode_I": self.IF_mode_I,
+        "IF_mode_Q": self.IF_mode_Q,
+    }
+
+    if isinstance(self.channel, InOutIQChannel):
+        IF_channels = [self.IF_output_I, self.IF_output_Q]
+        opx_channels = [self.channel.opx_input_I, self.channel.opx_input_Q]
+    elif isinstance(self.channel, InOutSingleChannel):
+        IF_channels = [self.IF_output_I]
+        opx_channels = [self.channel.opx_input]
+    else:
+        IF_channels = []
+        opx_channels = []
+
+    opx_port_tuples = [
+        p.port_tuple if isinstance(p, BasePort) else tuple(p) for p in opx_channels
+    ]
+
+    IF_config = config["octaves"][self.octave.name]["IF_outputs"]
+    for k, (IF_ch, opx_port_tuples) in enumerate(
+        zip(IF_channels, opx_port_tuples), start=1
+    ):
+        label = f"IF_out{IF_ch}"
+        IF_config.setdefault(label, {"port": opx_port_tuples, "name": f"out{k}"})
+        if IF_config[label]["port"] != opx_port_tuples:
+            raise ValueError(
+                f"Error generating config for Octave downconverter id={self.id}: "
+                f"Unable to assign {label} to  port {opx_port_tuples} because it is already "
+                f"assigned to port {IF_config[label]['port']} "
+            )
+
+
+
+ +
+ + + +
+ +
+ +
+ + + + +
+ +
+ +
+ + + + + + + + + + + + + +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API_references/components/ports/analog_inputs/index.html b/API_references/components/ports/analog_inputs/index.html new file mode 100644 index 00000000..e4924027 --- /dev/null +++ b/API_references/components/ports/analog_inputs/index.html @@ -0,0 +1,909 @@ + + + + + + + + + + + + + + + + + + + + + Analog inputs - The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ + + + +

Analog inputs

+ +
+ + + + +
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ + + + + + + + + + + + + +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API_references/components/ports/analog_outputs/index.html b/API_references/components/ports/analog_outputs/index.html new file mode 100644 index 00000000..8aa98137 --- /dev/null +++ b/API_references/components/ports/analog_outputs/index.html @@ -0,0 +1,909 @@ + + + + + + + + + + + + + + + + + + + + + Analog outputs - The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ + + + +

Analog outputs

+ +
+ + + + +
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ + + + + + + + + + + + + +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API_references/components/ports/base_ports/index.html b/API_references/components/ports/base_ports/index.html new file mode 100644 index 00000000..9503dccc --- /dev/null +++ b/API_references/components/ports/base_ports/index.html @@ -0,0 +1,909 @@ + + + + + + + + + + + + + + + + + + + + + Base ports - The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ + + + +

Base ports

+ +
+ + + + +
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ + + + + + + + + + + + + +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API_references/components/ports/digital_inputs/index.html b/API_references/components/ports/digital_inputs/index.html new file mode 100644 index 00000000..e899b7fc --- /dev/null +++ b/API_references/components/ports/digital_inputs/index.html @@ -0,0 +1,909 @@ + + + + + + + + + + + + + + + + + + + + + Digital inputs - The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ + + + +

Digital inputs

+ +
+ + + + +
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ + + + + + + + + + + + + +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API_references/components/ports/digital_outputs/index.html b/API_references/components/ports/digital_outputs/index.html new file mode 100644 index 00000000..71551a68 --- /dev/null +++ b/API_references/components/ports/digital_outputs/index.html @@ -0,0 +1,909 @@ + + + + + + + + + + + + + + + + + + + + + Digital outputs - The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ + + + +

Digital outputs

+ +
+ + + + +
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ + + + + + + + + + + + + +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API_references/components/ports/ports_containers/index.html b/API_references/components/ports/ports_containers/index.html new file mode 100644 index 00000000..9858f4ca --- /dev/null +++ b/API_references/components/ports/ports_containers/index.html @@ -0,0 +1,909 @@ + + + + + + + + + + + + + + + + + + + + + Ports containers - The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ + + + +

Ports containers

+ +
+ + + + +
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ + + + + + + + + + + + + +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API_references/components/pulses/index.html b/API_references/components/pulses/index.html new file mode 100644 index 00000000..5ff35951 --- /dev/null +++ b/API_references/components/pulses/index.html @@ -0,0 +1,3521 @@ + + + + + + + + + + + + + + + + + + + + + Pulses - The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ + + + +

Pulses

+ +
+ + + + +
+ + + +
+ + + + + + + + +
+ + + +

+ BaseReadoutPulse + + +

+ + +
+

+ Bases: Pulse, ABC

+ + +

QuAM abstract base component for a general readout pulse.

+

Readout pulse classes should usually inherit from ReadoutPulse, the +exception being when a custom integration weights function is required.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
length + int + +
+

The length of the pulse in samples.

+
+ 		+ required +
digital_marker + (str, list) + +
+

The digital marker to use for the pulse. +Default is "ON".

+
+ 		+ required +
+ +
+ Source code in quam/components/pulses.py + 
284
+285
+286
+287
+288
+289
+290
+291
+292
+293
+294
+295
+296
+297
+298
+299
+300
+301
+302
+303
+304
+305
+306
+307
+308
+309
+310
+311
+312
+313
+314
+315
+316
+317
+318
+319
+320
+321
+322
+323
+324
+325
+326
+327
+328
+329
+330
+331
+332
+333
+334
+335
+336
+337
+338
+339
+340
+341
+342
+343
+344
+345
+346
+347
+348
+349
+350
+351
@quam_dataclass
+class BaseReadoutPulse(Pulse, ABC):
+    """QuAM abstract base component for a general  readout pulse.
+
+    Readout pulse classes should usually inherit from `ReadoutPulse`, the
+    exception being when a custom integration weights function is required.
+
+    Args:
+        length (int): The length of the pulse in samples.
+        digital_marker (str, list, optional): The digital marker to use for the pulse.
+            Default is "ON".
+    """
+
+    operation: ClassVar[str] = "measurement"
+    digital_marker: str = "ON"
+
+    # TODO Understand why the thresholds were added.
+    threshold: float = None
+    rus_exit_threshold: float = None
+
+    _weight_labels: ClassVar[List[str]] = ["iw1", "iw2", "iw3"]
+
+    @property
+    def integration_weights_names(self):
+        return [f"{self.name}{str_ref.DELIMITER}{name}" for name in self._weight_labels]
+
+    @property
+    def integration_weights_mapping(self):
+        return dict(zip(self._weight_labels, self.integration_weights_names))
+
+    @abstractmethod
+    def integration_weights_function(self) -> Dict[str, List[Tuple[float, int]]]:
+        """Abstract method to calculate the integration weights.
+
+        Returns:
+            Dict containing keys "real", "imag", "minus_real", "minus_imag".
+            Values are lists of tuples of (weight, length) pairs.
+        """
+        ...
+
+    def _config_add_integration_weights(self, config: dict):
+        """Add the integration weights to the config"""
+        integration_weights = self.integration_weights_function()
+
+        config["integration_weights"][self.integration_weights_names[0]] = {
+            "cosine": integration_weights["real"],
+            "sine": integration_weights["minus_imag"],
+        }
+        config["integration_weights"][self.integration_weights_names[1]] = {
+            "cosine": integration_weights["imag"],
+            "sine": integration_weights["real"],
+        }
+        config["integration_weights"][self.integration_weights_names[2]] = {
+            "cosine": integration_weights["minus_imag"],
+            "sine": integration_weights["minus_real"],
+        }
+
+        pulse_config = config["pulses"][self.pulse_name]
+        pulse_config["integration_weights"] = self.integration_weights_mapping
+
+    def apply_to_config(self, config: dict) -> None:
+        """Adds this readout pulse to the QUA configuration.
+
+        See [`QuamComponent.apply_to_config`][quam.core.quam_classes.QuamComponent.apply_to_config]
+        for details.
+        """
+        super().apply_to_config(config)
+        self._config_add_integration_weights(config)
+
+
+ + + +
+ + + + + + + + + +
+ + +

+ apply_to_config(config) + +

+ + +
+ +

Adds this readout pulse to the QUA configuration.

+

See QuamComponent.apply_to_config +for details.

+ +
+ Source code in quam/components/pulses.py + 
344
+345
+346
+347
+348
+349
+350
+351
def apply_to_config(self, config: dict) -> None:
+    """Adds this readout pulse to the QUA configuration.
+
+    See [`QuamComponent.apply_to_config`][quam.core.quam_classes.QuamComponent.apply_to_config]
+    for details.
+    """
+    super().apply_to_config(config)
+    self._config_add_integration_weights(config)
+
+
+
+ +
+ +
+ + +

+ integration_weights_function() + + + abstractmethod + + +

+ + +
+ +

Abstract method to calculate the integration weights.

+ + +

Returns:

+ + + + + + + + + + + + + + + + + +
TypeDescription
+ Dict[str, List[Tuple[float, int]]] + +
+

Dict containing keys "real", "imag", "minus_real", "minus_imag".

+
+
+ Dict[str, List[Tuple[float, int]]] + +
+

Values are lists of tuples of (weight, length) pairs.

+
+
+ +
+ Source code in quam/components/pulses.py + 
314
+315
+316
+317
+318
+319
+320
+321
+322
@abstractmethod
+def integration_weights_function(self) -> Dict[str, List[Tuple[float, int]]]:
+    """Abstract method to calculate the integration weights.
+
+    Returns:
+        Dict containing keys "real", "imag", "minus_real", "minus_imag".
+        Values are lists of tuples of (weight, length) pairs.
+    """
+    ...
+
+
+
+ +
+ + + +
+ +
+ +
+ +
+ + + +

+ DragPulse + + +

+ + +
+

+ Bases: Pulse

+ + +

Gaussian-based DRAG pulse that compensate for the leakage and AC stark shift.

+

These DRAG waveforms has been implemented following the next Refs.: +Chen et al. PRL, 116, 020501 (2016) +https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.116.020501 +and Chen's thesis +https://web.physics.ucsb.edu/~martinisgroup/theses/Chen2018.pdf

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
length + int + +
+

The pulse length in ns.

+
+ 		+ required +
axis_angle + float + +
+

IQ axis angle of the output pulse in radians. +If None (default), the pulse is meant for a single channel or the I port + of an IQ channel +If not None, the pulse is meant for an IQ channel (0 is X, pi/2 is Y).

+
+ 		+ required +
amplitude + float + +
+

The amplitude in volts.

+
+ 		+ required +
sigma + float + +
+

The gaussian standard deviation.

+
+ 		+ required +
alpha + float + +
+

The DRAG coefficient.

+
+ 		+ required +
anharmonicity + float + +
+

f_21 - f_10 - The differences in energy between the 2-1 +and the 1-0 energy levels, in Hz.

+
+ 		+ required +
detuning + float + +
+

The frequency shift to correct for AC stark shift, in Hz.

+
+ 		+ required +
subtracted + bool + +
+

If true, returns a subtracted Gaussian, such that the first +and last points will be at 0 volts. This reduces high-frequency components +due to the initial and final points offset. Default is true.

+
+ 		+ required +
+ +
+ Source code in quam/components/pulses.py + 
398
+399
+400
+401
+402
+403
+404
+405
+406
+407
+408
+409
+410
+411
+412
+413
+414
+415
+416
+417
+418
+419
+420
+421
+422
+423
+424
+425
+426
+427
+428
+429
+430
+431
+432
+433
+434
+435
+436
+437
+438
+439
+440
+441
+442
+443
+444
+445
+446
+447
+448
+449
+450
+451
@quam_dataclass
+class DragPulse(Pulse):
+    """Gaussian-based DRAG pulse that compensate for the leakage and AC stark shift.
+
+    These DRAG waveforms has been implemented following the next Refs.:
+    Chen et al. PRL, 116, 020501 (2016)
+    https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.116.020501
+    and Chen's thesis
+    https://web.physics.ucsb.edu/~martinisgroup/theses/Chen2018.pdf
+
+    Args:
+        length (int): The pulse length in ns.
+        axis_angle (float, optional): IQ axis angle of the output pulse in radians.
+            If None (default), the pulse is meant for a single channel or the I port
+                of an IQ channel
+            If not None, the pulse is meant for an IQ channel (0 is X, pi/2 is Y).
+        amplitude (float): The amplitude in volts.
+        sigma (float): The gaussian standard deviation.
+        alpha (float): The DRAG coefficient.
+        anharmonicity (float): f_21 - f_10 - The differences in energy between the 2-1
+            and the 1-0 energy levels, in Hz.
+        detuning (float): The frequency shift to correct for AC stark shift, in Hz.
+        subtracted (bool): If true, returns a subtracted Gaussian, such that the first
+            and last points will be at 0 volts. This reduces high-frequency components
+            due to the initial and final points offset. Default is true.
+
+    """
+
+    axis_angle: float
+    amplitude: float
+    sigma: float
+    alpha: float
+    anharmonicity: float
+    detuning: float = 0.0
+    subtracted: bool = True
+
+    def waveform_function(self):
+        from qualang_tools.config.waveform_tools import drag_gaussian_pulse_waveforms
+
+        I, Q = drag_gaussian_pulse_waveforms(
+            amplitude=self.amplitude,
+            length=self.length,
+            sigma=self.sigma,
+            alpha=self.alpha,
+            anharmonicity=self.anharmonicity,
+            detuning=self.detuning,
+            subtracted=self.subtracted,
+        )
+        I, Q = np.array(I), np.array(Q)
+
+        I_rot = I * np.cos(self.axis_angle) - Q * np.sin(self.axis_angle)
+        Q_rot = I * np.sin(self.axis_angle) + Q * np.cos(self.axis_angle)
+
+        return I_rot + 1.0j * Q_rot
+
+
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ +
+ + + +

+ FlatTopGaussianPulse + + +

+ + +
+

+ Bases: Pulse

+ + +

Gaussian pulse with flat top QuAM component.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
length + int + +
+

The total length of the pulse in samples.

+
+ 		+ required +
amplitude + float + +
+

The amplitude of the pulse in volts.

+
+ 		+ required +
axis_angle + float + +
+

IQ axis angle of the output pulse in radians. +If None (default), the pulse is meant for a single channel or the I port + of an IQ channel +If not None, the pulse is meant for an IQ channel (0 is X, pi/2 is Y).

+
+ 		+ required +
flat_length + int + +
+

The length of the pulse's flat top in samples. +The rise and fall lengths are calculated from the total length and the +flat length.

+
+ 		+ required +
+ +
+ Source code in quam/components/pulses.py + 
552
+553
+554
+555
+556
+557
+558
+559
+560
+561
+562
+563
+564
+565
+566
+567
+568
+569
+570
+571
+572
+573
+574
+575
+576
+577
+578
+579
+580
+581
+582
+583
+584
+585
+586
+587
+588
+589
+590
+591
+592
+593
+594
@quam_dataclass
+class FlatTopGaussianPulse(Pulse):
+    """Gaussian pulse with flat top QuAM component.
+
+    Args:
+        length (int): The total length of the pulse in samples.
+        amplitude (float): The amplitude of the pulse in volts.
+        axis_angle (float, optional): IQ axis angle of the output pulse in radians.
+            If None (default), the pulse is meant for a single channel or the I port
+                of an IQ channel
+            If not None, the pulse is meant for an IQ channel (0 is X, pi/2 is Y).
+        flat_length (int): The length of the pulse's flat top in samples.
+            The rise and fall lengths are calculated from the total length and the
+            flat length.
+    """
+
+    amplitude: float
+    axis_angle: float = None
+    flat_length: int
+
+    def waveform_function(self):
+        from qualang_tools.config.waveform_tools import flattop_gaussian_waveform
+
+        rise_fall_length = (self.length - self.flat_length) // 2
+        if not self.flat_length + 2 * rise_fall_length == self.length:
+            raise ValueError(
+                "FlatTopGaussianPulse rise_fall_length (=length-flat_length) must be"
+                f" a multiple of 2 ({self.length} - {self.flat_length} ="
+                f" {self.length - self.flat_length})"
+            )
+
+        waveform = flattop_gaussian_waveform(
+            amplitude=self.amplitude,
+            flat_length=self.flat_length,
+            rise_fall_length=rise_fall_length,
+            return_part="all",
+        )
+        waveform = np.array(waveform)
+
+        if self.axis_angle is not None:
+            waveform = waveform * np.exp(1j * self.axis_angle)
+
+        return waveform
+
+
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ +
+ + + +

+ GaussianPulse + + +

+ + +
+

+ Bases: Pulse

+ + +

Gaussian pulse QuAM component.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
amplitude + float + +
+

The amplitude of the pulse in volts.

+
+ 		+ required +
length + int + +
+

The length of the pulse in samples.

+
+ 		+ required +
sigma + float + +
+

The standard deviation of the gaussian pulse. +Should generally be less than half the length of the pulse.

+
+ 		+ required +
axis_angle + float + +
+

IQ axis angle of the output pulse in radians. +If None (default), the pulse is meant for a single channel or the I port + of an IQ channel +If not None, the pulse is meant for an IQ channel (0 is X, pi/2 is Y).

+
+ 		+ required +
subtracted + bool + +
+

If true, returns a subtracted Gaussian, such that the first +and last points will be at 0 volts. This reduces high-frequency components +due to the initial and final points offset. Default is true.

+
+ 		+ required +
+ +
+ Source code in quam/components/pulses.py + 
514
+515
+516
+517
+518
+519
+520
+521
+522
+523
+524
+525
+526
+527
+528
+529
+530
+531
+532
+533
+534
+535
+536
+537
+538
+539
+540
+541
+542
+543
+544
+545
+546
+547
+548
+549
@quam_dataclass
+class GaussianPulse(Pulse):
+    """Gaussian pulse QuAM component.
+
+    Args:
+        amplitude (float): The amplitude of the pulse in volts.
+        length (int): The length of the pulse in samples.
+        sigma (float): The standard deviation of the gaussian pulse.
+            Should generally be less than half the length of the pulse.
+        axis_angle (float, optional): IQ axis angle of the output pulse in radians.
+            If None (default), the pulse is meant for a single channel or the I port
+                of an IQ channel
+            If not None, the pulse is meant for an IQ channel (0 is X, pi/2 is Y).
+        subtracted (bool): If true, returns a subtracted Gaussian, such that the first
+            and last points will be at 0 volts. This reduces high-frequency components
+            due to the initial and final points offset. Default is true.
+    """
+
+    amplitude: float
+    length: int
+    sigma: float
+    axis_angle: float = None
+    subtracted: bool = True
+
+    def waveform_function(self):
+        t = np.arange(self.length, dtype=int)
+        center = (self.length - 1) / 2
+        waveform = self.amplitude * np.exp(-((t - center) ** 2) / (2 * self.sigma**2))
+
+        if self.subtracted:
+            waveform = waveform - waveform[-1]
+
+        if self.axis_angle is not None:
+            waveform = waveform * np.exp(1j * self.axis_angle)
+
+        return waveform
+
+
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ +
+ + + +

+ Pulse + + +

+ + +
+

+ Bases: QuamComponent

+ + +

QuAM base component for a pulse.

+

Pulses are added to a channel using +

channel.operations["pulse_name"] = pulse
+

+

The Pulse class is an abstract base class, and should not be instantiated +directly. Instead, use one of the subclasses such as: +- ConstantReadoutPulse +- DragPulse +- SquarePulse +- GaussianPulse +or create a custom subclass. In this case, the method waveform_function should +be implemented.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
operation + str + +
+

The operation of the pulse, either "control" or "measurement". +Default is "control".

+
+ 		+ required +
length + int + +
+

The length of the pulse in samples.

+
+ 		+ required +
digital_marker + (str, list) + +
+

The digital marker to use for the pulse. +Can be a string, in which case it is a reference to a digital marker in the +config, or a list of tuples of (sample, length) pairs. Default is None.

+
+ 		+ required +
+ + +
+ Note +

The unique pulse label is automatically generated from the channel name and +the pulse name, the same for the waveform and digital marker names. +The pulse label is defined as "{channel_name}.{pulse_name}.pulse". +The waveform label is defined as "{channel_name}.{pulse_name}.wf". +The digital marker label is defined as "{channel_name}.{pulse_name}.dm".

+
+
+ Source code in quam/components/pulses.py + 
 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
+182
+183
+184
+185
+186
+187
+188
+189
+190
+191
+192
+193
+194
+195
+196
+197
+198
+199
+200
+201
+202
+203
+204
+205
+206
+207
+208
+209
+210
+211
+212
+213
+214
+215
+216
+217
+218
+219
+220
+221
+222
+223
+224
+225
+226
+227
+228
+229
+230
+231
+232
+233
+234
+235
+236
+237
+238
+239
+240
+241
+242
+243
+244
+245
+246
+247
+248
+249
+250
+251
+252
+253
+254
+255
+256
+257
+258
+259
+260
+261
+262
+263
+264
+265
+266
+267
+268
+269
+270
+271
+272
+273
+274
+275
+276
+277
+278
+279
+280
+281
@quam_dataclass
+class Pulse(QuamComponent):
+    """QuAM base component for a pulse.
+
+    Pulses are added to a channel using
+    ```
+    channel.operations["pulse_name"] = pulse
+    ```
+
+    The `Pulse` class is an abstract base class, and should not be instantiated
+    directly. Instead, use one of the subclasses such as:
+    - `ConstantReadoutPulse`
+    - `DragPulse`
+    - `SquarePulse`
+    - `GaussianPulse`
+    or create a custom subclass. In this case, the method `waveform_function` should
+    be implemented.
+
+    Args:
+        operation (str): The operation of the pulse, either "control" or "measurement".
+            Default is "control".
+        length (int): The length of the pulse in samples.
+        digital_marker (str, list, optional): The digital marker to use for the pulse.
+            Can be a string, in which case it is a reference to a digital marker in the
+            config, or a list of tuples of (sample, length) pairs. Default is None.
+
+    Note:
+        The unique pulse label is automatically generated from the channel name and
+        the pulse name, the same for the waveform and digital marker names.
+        The pulse label is defined as `"{channel_name}.{pulse_name}.pulse"`.
+        The waveform label is defined as `"{channel_name}.{pulse_name}.wf"`.
+        The digital marker label is defined as `"{channel_name}.{pulse_name}.dm"`.
+
+    """
+
+    operation: ClassVar[str] = "control"
+    length: int
+    id: str = None
+
+    digital_marker: Union[str, List[Tuple[int, int]]] = None
+
+    @property
+    def channel(self):
+        """The channel to which the pulse is attached, None if no channel is attached"""
+        from quam.components.channels import Channel
+
+        if isinstance(self.parent, Channel):
+            return self.parent
+        elif hasattr(self.parent, "parent") and isinstance(self.parent.parent, Channel):
+            return self.parent.parent
+        else:
+            return None
+
+    @property
+    def name(self):
+        if self.channel is None:
+            raise AttributeError(
+                f"Cannot get full name of pulse '{self}' because it is not"
+                " attached to a channel"
+            )
+
+        if self.id is not None:
+            name = self.id
+        else:
+            name = self.parent.get_attr_name(self)
+
+        return f"{self.channel.name}{str_ref.DELIMITER}{name}"
+
+    @property
+    def pulse_name(self):
+        return f"{self.name}{str_ref.DELIMITER}pulse"
+
+    @property
+    def waveform_name(self):
+        return f"{self.name}{str_ref.DELIMITER}wf"
+
+    @property
+    def digital_marker_name(self):
+        return f"{self.name}{str_ref.DELIMITER}dm"
+
+    def calculate_waveform(self) -> Union[float, complex, List[float], List[complex]]:
+        """Calculate the waveform of the pulse.
+
+        This function calls `Pulse.waveform_function`, which should generally be
+        subclassed, to generate the waveform.
+
+        This function then processes the results such that IQ waveforms are cast
+        into complex values.
+
+        Returns:
+            The processed waveform, which can be either
+            - a single float for a constant single-channel waveform,
+            - a single complex number for a constant IQ waveform,
+            - a list of floats for an arbitrary single-channel waveform,
+            - a list of complex numbers for an arbitrary IQ waveform,
+        """
+        waveform = self.waveform_function()
+
+        # Optionally convert IQ waveforms to complex waveform
+        if isinstance(waveform, tuple) and len(waveform) == 2:
+            if isinstance(waveform[0], (list, np.ndarray)):
+                waveform = np.array(waveform[0]) + 1.0j * np.array(waveform[1])
+            else:
+                waveform = waveform[0] + 1.0j * waveform[1]
+
+        return waveform
+
+    def waveform_function(
+        self,
+    ) -> Union[
+        float,
+        complex,
+        List[float],
+        List[complex],
+        Tuple[float, float],
+        Tuple[List[float], List[float]],
+    ]:
+        """Function that returns the waveform of the pulse.
+
+        The waveform function should use the relevant parameters from the pulse, which
+        is passed as the only argument.
+
+        This function is called from `Pulse.calculate_waveform`
+
+        Returns:
+            The waveform of the pulse. Can be one of the following:
+            - a single float for a constant single-channel waveform,
+            - a single complex number for a constant IQ waveform,
+            - a list of floats for an arbitrary single-channel waveform,
+            - a list of complex numbers for an arbitrary IQ waveform,
+            - a tuple of floats or float lists for an arbitrary IQ waveform
+        """
+        ...
+
+    def _config_add_pulse(self, config: Dict[str, Any]):
+        """Add the pulse to the config
+
+        The config entry is added to `config["pulses"][self.pulse_name]`
+        """
+        assert self.operation in ["control", "measurement"]
+        assert isinstance(self.length, int)
+
+        pulse_config = config["pulses"][self.pulse_name] = {
+            "operation": self.operation,
+            "length": self.length,
+        }
+        if self.digital_marker is not None:
+            pulse_config["digital_marker"] = self.digital_marker
+
+    def _config_add_waveforms(self, config):
+        """Add the waveform to the config
+
+        For a single waveform, the config entry is added to
+        `config["waveforms"]["{channel_name}.{pulse_name}.wf"]`.
+        For an IQ waveform, two config entries are added to
+        `config["waveforms"]["{channel_name}.{pulse_name}.wf.I"]` and with suffix `Q`.
+
+        Raises:
+            ValueError: If the waveform type (single or IQ) does not match the parent
+                channel type (SingleChannel, IQChannel, InOutIQChannel).
+        """
+
+        from quam.components.channels import SingleChannel, IQChannel
+
+        pulse_config = config["pulses"][self.pulse_name]
+
+        waveform = self.calculate_waveform()
+        if waveform is None:
+            return
+
+        pulse_config["waveforms"] = {}
+
+        if isinstance(waveform, numbers.Number):
+            wf_type = "constant"
+            if isinstance(waveform, complex):
+                waveforms = {"I": waveform.real, "Q": waveform.imag}
+            elif isinstance(self.channel, IQChannel):
+                waveforms = {"I": waveform, "Q": 0.0}
+            else:
+                waveforms = {"single": waveform}
+
+        elif isinstance(waveform, (list, np.ndarray)):
+            wf_type = "arbitrary"
+            if np.iscomplexobj(waveform):
+                waveforms = {"I": list(waveform.real), "Q": list(waveform.imag)}
+            elif isinstance(self.channel, IQChannel):
+                waveforms = {"I": waveform, "Q": np.zeros_like(waveform)}
+            else:
+                waveforms = {"single": list(waveform)}
+        else:
+            raise ValueError("unsupported return type")
+
+        # Add check that waveform type (single or IQ) matches parent
+        if "single" in waveforms and not isinstance(self.channel, SingleChannel):
+            raise ValueError(
+                "Waveform type 'single' not allowed for IQChannel"
+                f" '{self.channel.name}'"
+            )
+        elif "I" in waveforms and not isinstance(self.channel, IQChannel):
+            raise ValueError(
+                "Waveform type 'IQ' not allowed for SingleChannel"
+                f" '{self.channel.name}'"
+            )
+
+        for suffix, waveform in waveforms.items():
+            waveform_name = self.waveform_name
+            if suffix != "single":
+                waveform_name += f"{str_ref.DELIMITER}{suffix}"
+
+            sample_label = "sample" if wf_type == "constant" else "samples"
+
+            config["waveforms"][waveform_name] = {
+                "type": wf_type,
+                sample_label: waveform,
+            }
+            pulse_config["waveforms"][suffix] = waveform_name
+
+    def _config_add_digital_markers(self, config):
+        """Add the digital marker to the config
+
+        The config entry is added to
+        `config["digital_waveforms"]["{channel_name}.{pulse_name}.dm"]` and also
+        registered in
+        `config["pulses"]["{channel_name}.{pulse_name}.pulse"]["digital_marker"]`.
+
+        If the digital marker is a string, it is assumed to be a reference to a
+        digital marker already defined in the config.
+        """
+        if isinstance(self.digital_marker, str):
+            # Use a common config digital marker
+            if self.digital_marker not in config["digital_waveforms"]:
+                raise KeyError(
+                    "{self.name}.digital_marker={self.digital_marker} not in"
+                    " config['digital_waveforms']"
+                )
+            digital_marker_name = self.digital_marker
+        else:
+            config["digital_waveforms"][self.digital_marker_name] = {
+                "samples": self.digital_marker
+            }
+            digital_marker_name = self.digital_marker_name
+
+        config["pulses"][self.pulse_name]["digital_marker"] = digital_marker_name
+
+    def apply_to_config(self, config: dict) -> None:
+        """Adds this pulse, waveform, and digital marker to the QUA configuration.
+
+        See [`QuamComponent.apply_to_config`][quam.core.quam_classes.QuamComponent.apply_to_config]
+        for details.
+        """
+        if self.channel is None:
+            return
+
+        self._config_add_pulse(config)
+        self._config_add_waveforms(config)
+
+        if self.digital_marker:
+            self._config_add_digital_markers(config)
+
+
+ + + +
+ + + + + + + +
+ + + +

+ channel + + + property + + +

+ + +
+ +

The channel to which the pulse is attached, None if no channel is attached

+
+ +
+ + + +
+ + +

+ apply_to_config(config) + +

+ + +
+ +

Adds this pulse, waveform, and digital marker to the QUA configuration.

+

See QuamComponent.apply_to_config +for details.

+ +
+ Source code in quam/components/pulses.py + 
268
+269
+270
+271
+272
+273
+274
+275
+276
+277
+278
+279
+280
+281
def apply_to_config(self, config: dict) -> None:
+    """Adds this pulse, waveform, and digital marker to the QUA configuration.
+
+    See [`QuamComponent.apply_to_config`][quam.core.quam_classes.QuamComponent.apply_to_config]
+    for details.
+    """
+    if self.channel is None:
+        return
+
+    self._config_add_pulse(config)
+    self._config_add_waveforms(config)
+
+    if self.digital_marker:
+        self._config_add_digital_markers(config)
+
+
+
+ +
+ +
+ + +

+ calculate_waveform() + +

+ + +
+ +

Calculate the waveform of the pulse.

+

This function calls Pulse.waveform_function, which should generally be +subclassed, to generate the waveform.

+

This function then processes the results such that IQ waveforms are cast +into complex values.

+ + +

Returns:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDescription
+ Union[float, complex, List[float], List[complex]] + +
+

The processed waveform, which can be either

+
+
+ Union[float, complex, List[float], List[complex]] + +
+
    +
  • a single float for a constant single-channel waveform,
    • +
+
+
+ Union[float, complex, List[float], List[complex]] + +
+
    +
  • a single complex number for a constant IQ waveform,
    • +
+
+
+ Union[float, complex, List[float], List[complex]] + +
+
    +
  • a list of floats for an arbitrary single-channel waveform,
    • +
+
+
+ Union[float, complex, List[float], List[complex]] + +
+
    +
  • a list of complex numbers for an arbitrary IQ waveform,
    • +
+
+
+ +
+ Source code in quam/components/pulses.py + 
104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
def calculate_waveform(self) -> Union[float, complex, List[float], List[complex]]:
+    """Calculate the waveform of the pulse.
+
+    This function calls `Pulse.waveform_function`, which should generally be
+    subclassed, to generate the waveform.
+
+    This function then processes the results such that IQ waveforms are cast
+    into complex values.
+
+    Returns:
+        The processed waveform, which can be either
+        - a single float for a constant single-channel waveform,
+        - a single complex number for a constant IQ waveform,
+        - a list of floats for an arbitrary single-channel waveform,
+        - a list of complex numbers for an arbitrary IQ waveform,
+    """
+    waveform = self.waveform_function()
+
+    # Optionally convert IQ waveforms to complex waveform
+    if isinstance(waveform, tuple) and len(waveform) == 2:
+        if isinstance(waveform[0], (list, np.ndarray)):
+            waveform = np.array(waveform[0]) + 1.0j * np.array(waveform[1])
+        else:
+            waveform = waveform[0] + 1.0j * waveform[1]
+
+    return waveform
+
+
+
+ +
+ +
+ + +

+ waveform_function() + +

+ + +
+ +

Function that returns the waveform of the pulse.

+

The waveform function should use the relevant parameters from the pulse, which +is passed as the only argument.

+

This function is called from Pulse.calculate_waveform

+ + +

Returns:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDescription
+ Union[float, complex, List[float], List[complex], Tuple[float, float], Tuple[List[float], List[float]]] + +
+

The waveform of the pulse. Can be one of the following:

+
+
+ Union[float, complex, List[float], List[complex], Tuple[float, float], Tuple[List[float], List[float]]] + +
+
    +
  • a single float for a constant single-channel waveform,
    • +
+
+
+ Union[float, complex, List[float], List[complex], Tuple[float, float], Tuple[List[float], List[float]]] + +
+
    +
  • a single complex number for a constant IQ waveform,
    • +
+
+
+ Union[float, complex, List[float], List[complex], Tuple[float, float], Tuple[List[float], List[float]]] + +
+
    +
  • a list of floats for an arbitrary single-channel waveform,
    • +
+
+
+ Union[float, complex, List[float], List[complex], Tuple[float, float], Tuple[List[float], List[float]]] + +
+
    +
  • a list of complex numbers for an arbitrary IQ waveform,
    • +
+
+
+ Union[float, complex, List[float], List[complex], Tuple[float, float], Tuple[List[float], List[float]]] + +
+
    +
  • a tuple of floats or float lists for an arbitrary IQ waveform
    • +
+
+
+ +
+ Source code in quam/components/pulses.py + 
131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
def waveform_function(
+    self,
+) -> Union[
+    float,
+    complex,
+    List[float],
+    List[complex],
+    Tuple[float, float],
+    Tuple[List[float], List[float]],
+]:
+    """Function that returns the waveform of the pulse.
+
+    The waveform function should use the relevant parameters from the pulse, which
+    is passed as the only argument.
+
+    This function is called from `Pulse.calculate_waveform`
+
+    Returns:
+        The waveform of the pulse. Can be one of the following:
+        - a single float for a constant single-channel waveform,
+        - a single complex number for a constant IQ waveform,
+        - a list of floats for an arbitrary single-channel waveform,
+        - a list of complex numbers for an arbitrary IQ waveform,
+        - a tuple of floats or float lists for an arbitrary IQ waveform
+    """
+    ...
+
+
+
+ +
+ + + +
+ +
+ +
+ +
+ + + +

+ ReadoutPulse + + +

+ + +
+

+ Bases: BaseReadoutPulse, ABC

+ + +

QuAM abstract base component for most readout pulses.

+

This class is a subclass of ReadoutPulse and should be used for most readout +pulses. It provides a default implementation of the integration_weights_function +method, which is suitable for most cases.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
length + int + +
+

The length of the pulse in samples.

+
+ 		+ required +
digital_marker + (str, list) + +
+

The digital marker to use for the pulse. +Default is "ON".

+
+ 		+ required +
integration_weights + (list[float], list[tuple[float, int]]) + +
+

The +integration weights, can be either +- a list of floats (one per sample), the length must match the pulse length +- a list of tuples of (weight, length) pairs, the sum of the lengths must + match the pulse length

+
+ 		+ required +
integration_weights_angle + float + +
+

The rotation angle for the +integration weights in radians.

+
+ 		+ required +
+ +
+ Source code in quam/components/pulses.py + 
354
+355
+356
+357
+358
+359
+360
+361
+362
+363
+364
+365
+366
+367
+368
+369
+370
+371
+372
+373
+374
+375
+376
+377
+378
+379
+380
+381
+382
+383
+384
+385
+386
+387
+388
+389
+390
+391
+392
+393
+394
+395
@quam_dataclass
+class ReadoutPulse(BaseReadoutPulse, ABC):
+    """QuAM abstract base component for most readout pulses.
+
+    This class is a subclass of `ReadoutPulse` and should be used for most readout
+    pulses. It provides a default implementation of the `integration_weights_function`
+    method, which is suitable for most cases.
+
+    Args:
+        length (int): The length of the pulse in samples.
+        digital_marker (str, list, optional): The digital marker to use for the pulse.
+            Default is "ON".
+        integration_weights (list[float], list[tuple[float, int]], optional): The
+            integration weights, can be either
+            - a list of floats (one per sample), the length must match the pulse length
+            - a list of tuples of (weight, length) pairs, the sum of the lengths must
+              match the pulse length
+        integration_weights_angle (float, optional): The rotation angle for the
+            integration weights in radians.
+    """
+
+    integration_weights: Union[List[float], List[Tuple[float, int]]] = None
+    integration_weights_angle: float = 0
+
+    def integration_weights_function(self) -> List[Tuple[Union[complex, float], int]]:
+        from qualang_tools.config import convert_integration_weights
+
+        phase = np.exp(1j * self.integration_weights_angle)
+
+        if self.integration_weights is None or not len(self.integration_weights):
+            integration_weights = [(1, self.length)]
+        elif isinstance(self.integration_weights[0], float):
+            integration_weights = convert_integration_weights(self.integration_weights)
+        else:
+            integration_weights = self.integration_weights
+
+        return {
+            "real": [(phase.real * w, l) for w, l in integration_weights],
+            "imag": [(phase.imag * w, l) for w, l in integration_weights],
+            "minus_real": [(-phase.real * w, l) for w, l in integration_weights],
+            "minus_imag": [(-phase.imag * w, l) for w, l in integration_weights],
+        }
+
+
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ +
+ + + +

+ SquarePulse + + +

+ + +
+

+ Bases: Pulse

+ + +

Square pulse QuAM component.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
length + int + +
+

The length of the pulse in samples.

+
+ 		+ required +
digital_marker + (str, list) + +
+

The digital marker to use for the pulse.

+
+ 		+ required +
amplitude + float + +
+

The amplitude of the pulse in volts.

+
+ 		+ required +
axis_angle + float + +
+

IQ axis angle of the output pulse in radians. +If None (default), the pulse is meant for a single channel or the I port + of an IQ channel +If not None, the pulse is meant for an IQ channel (0 is X, pi/2 is Y).

+
+ 		+ required +
+ +
+ Source code in quam/components/pulses.py + 
454
+455
+456
+457
+458
+459
+460
+461
+462
+463
+464
+465
+466
+467
+468
+469
+470
+471
+472
+473
+474
+475
+476
@quam_dataclass
+class SquarePulse(Pulse):
+    """Square pulse QuAM component.
+
+    Args:
+        length (int): The length of the pulse in samples.
+        digital_marker (str, list, optional): The digital marker to use for the pulse.
+        amplitude (float): The amplitude of the pulse in volts.
+        axis_angle (float, optional): IQ axis angle of the output pulse in radians.
+            If None (default), the pulse is meant for a single channel or the I port
+                of an IQ channel
+            If not None, the pulse is meant for an IQ channel (0 is X, pi/2 is Y).
+    """
+
+    amplitude: float
+    axis_angle: float = None
+
+    def waveform_function(self):
+        waveform = self.amplitude
+
+        if self.axis_angle is not None:
+            waveform = waveform * np.exp(1j * self.axis_angle)
+        return waveform
+
+
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ +
+ + + +

+ SquareReadoutPulse + + +

+ + +
+

+ Bases: ReadoutPulse, SquarePulse

+ + +

QuAM component for a square readout pulse.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
length + int + +
+

The length of the pulse in samples.

+
+ 		+ required +
digital_marker + (str, list) + +
+

The digital marker to use for the pulse. +Default is "ON".

+
+ 		+ required +
amplitude + float + +
+

The constant amplitude of the pulse.

+
+ 		+ required +
axis_angle + float + +
+

IQ axis angle of the output pulse in radians. +If None (default), the pulse is meant for a single channel or the I port + of an IQ channel +If not None, the pulse is meant for an IQ channel (0 is X, pi/2 is Y).

+
+ 		+ required +
integration_weights + (list[float], list[tuple[float, int]]) + +
+

The +integration weights, can be either +- a list of floats (one per sample), the length must match the pulse length +- a list of tuples of (weight, length) pairs, the sum of the lengths must + match the pulse length

+
+ 		+ required +
integration_weights_angle + float + +
+

The rotation angle for the +integration weights in radians.

+
+ 		+ required +
+ +
+ Source code in quam/components/pulses.py + 
479
+480
+481
+482
+483
+484
+485
+486
+487
+488
+489
+490
+491
+492
+493
+494
+495
+496
+497
+498
+499
+500
+501
@quam_dataclass
+class SquareReadoutPulse(ReadoutPulse, SquarePulse):
+    """QuAM component for a square readout pulse.
+
+    Args:
+        length (int): The length of the pulse in samples.
+        digital_marker (str, list, optional): The digital marker to use for the pulse.
+            Default is "ON".
+        amplitude (float): The constant amplitude of the pulse.
+        axis_angle (float, optional): IQ axis angle of the output pulse in radians.
+            If None (default), the pulse is meant for a single channel or the I port
+                of an IQ channel
+            If not None, the pulse is meant for an IQ channel (0 is X, pi/2 is Y).
+        integration_weights (list[float], list[tuple[float, int]], optional): The
+            integration weights, can be either
+            - a list of floats (one per sample), the length must match the pulse length
+            - a list of tuples of (weight, length) pairs, the sum of the lengths must
+              match the pulse length
+        integration_weights_angle (float, optional): The rotation angle for the
+            integration weights in radians.
+    """
+
+    ...
+
+
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ + + + +
+ +
+ +
+ + + + + + + + + + + + + +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API_references/components/pulses_API/index.html b/API_references/components/pulses_API/index.html new file mode 100644 index 00000000..9c6a8e54 --- /dev/null +++ b/API_references/components/pulses_API/index.html @@ -0,0 +1,3721 @@ + + + + + + + + + + + + + + + + + + + + + + + + + QuAM Pulses API - The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ + + + +

QuAM Pulses API

+

Welcome to the QuAM Pulses API Documentation. +The QuAM Pulses module offers a versatile framework for creating and controlling pulse schemes essential for quantum operations. +Information can be found in QuAM Pulses Documentation in the User Guide.

+

This section provides detailed API references for various pulse types—ranging from simple waveforms to complex modulated pulses—tailored for precise quantum state manipulation and measurement. Explore the properties, methods, and examples to effectively integrate these pulse components into your quantum experiments.

+ + +
+ + + + +
+ + + +
+ + + + + + + + +
+ + + +

+ BaseReadoutPulse + + +

+ + +
+

+ Bases: Pulse, ABC

+ + +

QuAM abstract base component for a general readout pulse.

+

Readout pulse classes should usually inherit from ReadoutPulse, the +exception being when a custom integration weights function is required.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
length + int + +
+

The length of the pulse in samples.

+
+ 		+ required +
digital_marker + (str, list) + +
+

The digital marker to use for the pulse. +Default is "ON".

+
+ 		+ required +
+ +
+ Source code in quam/components/pulses.py + 
284
+285
+286
+287
+288
+289
+290
+291
+292
+293
+294
+295
+296
+297
+298
+299
+300
+301
+302
+303
+304
+305
+306
+307
+308
+309
+310
+311
+312
+313
+314
+315
+316
+317
+318
+319
+320
+321
+322
+323
+324
+325
+326
+327
+328
+329
+330
+331
+332
+333
+334
+335
+336
+337
+338
+339
+340
+341
+342
+343
+344
+345
+346
+347
+348
+349
+350
+351
@quam_dataclass
+class BaseReadoutPulse(Pulse, ABC):
+    """QuAM abstract base component for a general  readout pulse.
+
+    Readout pulse classes should usually inherit from `ReadoutPulse`, the
+    exception being when a custom integration weights function is required.
+
+    Args:
+        length (int): The length of the pulse in samples.
+        digital_marker (str, list, optional): The digital marker to use for the pulse.
+            Default is "ON".
+    """
+
+    operation: ClassVar[str] = "measurement"
+    digital_marker: str = "ON"
+
+    # TODO Understand why the thresholds were added.
+    threshold: float = None
+    rus_exit_threshold: float = None
+
+    _weight_labels: ClassVar[List[str]] = ["iw1", "iw2", "iw3"]
+
+    @property
+    def integration_weights_names(self):
+        return [f"{self.name}{str_ref.DELIMITER}{name}" for name in self._weight_labels]
+
+    @property
+    def integration_weights_mapping(self):
+        return dict(zip(self._weight_labels, self.integration_weights_names))
+
+    @abstractmethod
+    def integration_weights_function(self) -> Dict[str, List[Tuple[float, int]]]:
+        """Abstract method to calculate the integration weights.
+
+        Returns:
+            Dict containing keys "real", "imag", "minus_real", "minus_imag".
+            Values are lists of tuples of (weight, length) pairs.
+        """
+        ...
+
+    def _config_add_integration_weights(self, config: dict):
+        """Add the integration weights to the config"""
+        integration_weights = self.integration_weights_function()
+
+        config["integration_weights"][self.integration_weights_names[0]] = {
+            "cosine": integration_weights["real"],
+            "sine": integration_weights["minus_imag"],
+        }
+        config["integration_weights"][self.integration_weights_names[1]] = {
+            "cosine": integration_weights["imag"],
+            "sine": integration_weights["real"],
+        }
+        config["integration_weights"][self.integration_weights_names[2]] = {
+            "cosine": integration_weights["minus_imag"],
+            "sine": integration_weights["minus_real"],
+        }
+
+        pulse_config = config["pulses"][self.pulse_name]
+        pulse_config["integration_weights"] = self.integration_weights_mapping
+
+    def apply_to_config(self, config: dict) -> None:
+        """Adds this readout pulse to the QUA configuration.
+
+        See [`QuamComponent.apply_to_config`][quam.core.quam_classes.QuamComponent.apply_to_config]
+        for details.
+        """
+        super().apply_to_config(config)
+        self._config_add_integration_weights(config)
+
+
+ + + +
+ + + + + + + + + +
+ + +

+ apply_to_config(config) + +

+ + +
+ +

Adds this readout pulse to the QUA configuration.

+

See QuamComponent.apply_to_config +for details.

+ +
+ Source code in quam/components/pulses.py + 
344
+345
+346
+347
+348
+349
+350
+351
def apply_to_config(self, config: dict) -> None:
+    """Adds this readout pulse to the QUA configuration.
+
+    See [`QuamComponent.apply_to_config`][quam.core.quam_classes.QuamComponent.apply_to_config]
+    for details.
+    """
+    super().apply_to_config(config)
+    self._config_add_integration_weights(config)
+
+
+
+ +
+ +
+ + +

+ integration_weights_function() + + + abstractmethod + + +

+ + +
+ +

Abstract method to calculate the integration weights.

+ + +

Returns:

+ + + + + + + + + + + + + + + + + +
TypeDescription
+ Dict[str, List[Tuple[float, int]]] + +
+

Dict containing keys "real", "imag", "minus_real", "minus_imag".

+
+
+ Dict[str, List[Tuple[float, int]]] + +
+

Values are lists of tuples of (weight, length) pairs.

+
+
+ +
+ Source code in quam/components/pulses.py + 
314
+315
+316
+317
+318
+319
+320
+321
+322
@abstractmethod
+def integration_weights_function(self) -> Dict[str, List[Tuple[float, int]]]:
+    """Abstract method to calculate the integration weights.
+
+    Returns:
+        Dict containing keys "real", "imag", "minus_real", "minus_imag".
+        Values are lists of tuples of (weight, length) pairs.
+    """
+    ...
+
+
+
+ +
+ + + +
+ +
+ +
+ +
+ + + +

+ DragPulse + + +

+ + +
+

+ Bases: Pulse

+ + +

Gaussian-based DRAG pulse that compensate for the leakage and AC stark shift.

+

These DRAG waveforms has been implemented following the next Refs.: +Chen et al. PRL, 116, 020501 (2016) +https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.116.020501 +and Chen's thesis +https://web.physics.ucsb.edu/~martinisgroup/theses/Chen2018.pdf

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
length + int + +
+

The pulse length in ns.

+
+ 		+ required +
axis_angle + float + +
+

IQ axis angle of the output pulse in radians. +If None (default), the pulse is meant for a single channel or the I port + of an IQ channel +If not None, the pulse is meant for an IQ channel (0 is X, pi/2 is Y).

+
+ 		+ required +
amplitude + float + +
+

The amplitude in volts.

+
+ 		+ required +
sigma + float + +
+

The gaussian standard deviation.

+
+ 		+ required +
alpha + float + +
+

The DRAG coefficient.

+
+ 		+ required +
anharmonicity + float + +
+

f_21 - f_10 - The differences in energy between the 2-1 +and the 1-0 energy levels, in Hz.

+
+ 		+ required +
detuning + float + +
+

The frequency shift to correct for AC stark shift, in Hz.

+
+ 		+ required +
subtracted + bool + +
+

If true, returns a subtracted Gaussian, such that the first +and last points will be at 0 volts. This reduces high-frequency components +due to the initial and final points offset. Default is true.

+
+ 		+ required +
+ +
+ Source code in quam/components/pulses.py + 
398
+399
+400
+401
+402
+403
+404
+405
+406
+407
+408
+409
+410
+411
+412
+413
+414
+415
+416
+417
+418
+419
+420
+421
+422
+423
+424
+425
+426
+427
+428
+429
+430
+431
+432
+433
+434
+435
+436
+437
+438
+439
+440
+441
+442
+443
+444
+445
+446
+447
+448
+449
+450
+451
@quam_dataclass
+class DragPulse(Pulse):
+    """Gaussian-based DRAG pulse that compensate for the leakage and AC stark shift.
+
+    These DRAG waveforms has been implemented following the next Refs.:
+    Chen et al. PRL, 116, 020501 (2016)
+    https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.116.020501
+    and Chen's thesis
+    https://web.physics.ucsb.edu/~martinisgroup/theses/Chen2018.pdf
+
+    Args:
+        length (int): The pulse length in ns.
+        axis_angle (float, optional): IQ axis angle of the output pulse in radians.
+            If None (default), the pulse is meant for a single channel or the I port
+                of an IQ channel
+            If not None, the pulse is meant for an IQ channel (0 is X, pi/2 is Y).
+        amplitude (float): The amplitude in volts.
+        sigma (float): The gaussian standard deviation.
+        alpha (float): The DRAG coefficient.
+        anharmonicity (float): f_21 - f_10 - The differences in energy between the 2-1
+            and the 1-0 energy levels, in Hz.
+        detuning (float): The frequency shift to correct for AC stark shift, in Hz.
+        subtracted (bool): If true, returns a subtracted Gaussian, such that the first
+            and last points will be at 0 volts. This reduces high-frequency components
+            due to the initial and final points offset. Default is true.
+
+    """
+
+    axis_angle: float
+    amplitude: float
+    sigma: float
+    alpha: float
+    anharmonicity: float
+    detuning: float = 0.0
+    subtracted: bool = True
+
+    def waveform_function(self):
+        from qualang_tools.config.waveform_tools import drag_gaussian_pulse_waveforms
+
+        I, Q = drag_gaussian_pulse_waveforms(
+            amplitude=self.amplitude,
+            length=self.length,
+            sigma=self.sigma,
+            alpha=self.alpha,
+            anharmonicity=self.anharmonicity,
+            detuning=self.detuning,
+            subtracted=self.subtracted,
+        )
+        I, Q = np.array(I), np.array(Q)
+
+        I_rot = I * np.cos(self.axis_angle) - Q * np.sin(self.axis_angle)
+        Q_rot = I * np.sin(self.axis_angle) + Q * np.cos(self.axis_angle)
+
+        return I_rot + 1.0j * Q_rot
+
+
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ +
+ + + +

+ FlatTopGaussianPulse + + +

+ + +
+

+ Bases: Pulse

+ + +

Gaussian pulse with flat top QuAM component.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
length + int + +
+

The total length of the pulse in samples.

+
+ 		+ required +
amplitude + float + +
+

The amplitude of the pulse in volts.

+
+ 		+ required +
axis_angle + float + +
+

IQ axis angle of the output pulse in radians. +If None (default), the pulse is meant for a single channel or the I port + of an IQ channel +If not None, the pulse is meant for an IQ channel (0 is X, pi/2 is Y).

+
+ 		+ required +
flat_length + int + +
+

The length of the pulse's flat top in samples. +The rise and fall lengths are calculated from the total length and the +flat length.

+
+ 		+ required +
+ +
+ Source code in quam/components/pulses.py + 
552
+553
+554
+555
+556
+557
+558
+559
+560
+561
+562
+563
+564
+565
+566
+567
+568
+569
+570
+571
+572
+573
+574
+575
+576
+577
+578
+579
+580
+581
+582
+583
+584
+585
+586
+587
+588
+589
+590
+591
+592
+593
+594
@quam_dataclass
+class FlatTopGaussianPulse(Pulse):
+    """Gaussian pulse with flat top QuAM component.
+
+    Args:
+        length (int): The total length of the pulse in samples.
+        amplitude (float): The amplitude of the pulse in volts.
+        axis_angle (float, optional): IQ axis angle of the output pulse in radians.
+            If None (default), the pulse is meant for a single channel or the I port
+                of an IQ channel
+            If not None, the pulse is meant for an IQ channel (0 is X, pi/2 is Y).
+        flat_length (int): The length of the pulse's flat top in samples.
+            The rise and fall lengths are calculated from the total length and the
+            flat length.
+    """
+
+    amplitude: float
+    axis_angle: float = None
+    flat_length: int
+
+    def waveform_function(self):
+        from qualang_tools.config.waveform_tools import flattop_gaussian_waveform
+
+        rise_fall_length = (self.length - self.flat_length) // 2
+        if not self.flat_length + 2 * rise_fall_length == self.length:
+            raise ValueError(
+                "FlatTopGaussianPulse rise_fall_length (=length-flat_length) must be"
+                f" a multiple of 2 ({self.length} - {self.flat_length} ="
+                f" {self.length - self.flat_length})"
+            )
+
+        waveform = flattop_gaussian_waveform(
+            amplitude=self.amplitude,
+            flat_length=self.flat_length,
+            rise_fall_length=rise_fall_length,
+            return_part="all",
+        )
+        waveform = np.array(waveform)
+
+        if self.axis_angle is not None:
+            waveform = waveform * np.exp(1j * self.axis_angle)
+
+        return waveform
+
+
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ +
+ + + +

+ GaussianPulse + + +

+ + +
+

+ Bases: Pulse

+ + +

Gaussian pulse QuAM component.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
amplitude + float + +
+

The amplitude of the pulse in volts.

+
+ 		+ required +
length + int + +
+

The length of the pulse in samples.

+
+ 		+ required +
sigma + float + +
+

The standard deviation of the gaussian pulse. +Should generally be less than half the length of the pulse.

+
+ 		+ required +
axis_angle + float + +
+

IQ axis angle of the output pulse in radians. +If None (default), the pulse is meant for a single channel or the I port + of an IQ channel +If not None, the pulse is meant for an IQ channel (0 is X, pi/2 is Y).

+
+ 		+ required +
subtracted + bool + +
+

If true, returns a subtracted Gaussian, such that the first +and last points will be at 0 volts. This reduces high-frequency components +due to the initial and final points offset. Default is true.

+
+ 		+ required +
+ +
+ Source code in quam/components/pulses.py + 
514
+515
+516
+517
+518
+519
+520
+521
+522
+523
+524
+525
+526
+527
+528
+529
+530
+531
+532
+533
+534
+535
+536
+537
+538
+539
+540
+541
+542
+543
+544
+545
+546
+547
+548
+549
@quam_dataclass
+class GaussianPulse(Pulse):
+    """Gaussian pulse QuAM component.
+
+    Args:
+        amplitude (float): The amplitude of the pulse in volts.
+        length (int): The length of the pulse in samples.
+        sigma (float): The standard deviation of the gaussian pulse.
+            Should generally be less than half the length of the pulse.
+        axis_angle (float, optional): IQ axis angle of the output pulse in radians.
+            If None (default), the pulse is meant for a single channel or the I port
+                of an IQ channel
+            If not None, the pulse is meant for an IQ channel (0 is X, pi/2 is Y).
+        subtracted (bool): If true, returns a subtracted Gaussian, such that the first
+            and last points will be at 0 volts. This reduces high-frequency components
+            due to the initial and final points offset. Default is true.
+    """
+
+    amplitude: float
+    length: int
+    sigma: float
+    axis_angle: float = None
+    subtracted: bool = True
+
+    def waveform_function(self):
+        t = np.arange(self.length, dtype=int)
+        center = (self.length - 1) / 2
+        waveform = self.amplitude * np.exp(-((t - center) ** 2) / (2 * self.sigma**2))
+
+        if self.subtracted:
+            waveform = waveform - waveform[-1]
+
+        if self.axis_angle is not None:
+            waveform = waveform * np.exp(1j * self.axis_angle)
+
+        return waveform
+
+
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ +
+ + + +

+ Pulse + + +

+ + +
+

+ Bases: QuamComponent

+ + +

QuAM base component for a pulse.

+

Pulses are added to a channel using +

channel.operations["pulse_name"] = pulse
+

+

The Pulse class is an abstract base class, and should not be instantiated +directly. Instead, use one of the subclasses such as: +- ConstantReadoutPulse +- DragPulse +- SquarePulse +- GaussianPulse +or create a custom subclass. In this case, the method waveform_function should +be implemented.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
operation + str + +
+

The operation of the pulse, either "control" or "measurement". +Default is "control".

+
+ 		+ required +
length + int + +
+

The length of the pulse in samples.

+
+ 		+ required +
digital_marker + (str, list) + +
+

The digital marker to use for the pulse. +Can be a string, in which case it is a reference to a digital marker in the +config, or a list of tuples of (sample, length) pairs. Default is None.

+
+ 		+ required +
+ + +
+ Note +

The unique pulse label is automatically generated from the channel name and +the pulse name, the same for the waveform and digital marker names. +The pulse label is defined as "{channel_name}.{pulse_name}.pulse". +The waveform label is defined as "{channel_name}.{pulse_name}.wf". +The digital marker label is defined as "{channel_name}.{pulse_name}.dm".

+
+
+ Source code in quam/components/pulses.py + 
 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
+182
+183
+184
+185
+186
+187
+188
+189
+190
+191
+192
+193
+194
+195
+196
+197
+198
+199
+200
+201
+202
+203
+204
+205
+206
+207
+208
+209
+210
+211
+212
+213
+214
+215
+216
+217
+218
+219
+220
+221
+222
+223
+224
+225
+226
+227
+228
+229
+230
+231
+232
+233
+234
+235
+236
+237
+238
+239
+240
+241
+242
+243
+244
+245
+246
+247
+248
+249
+250
+251
+252
+253
+254
+255
+256
+257
+258
+259
+260
+261
+262
+263
+264
+265
+266
+267
+268
+269
+270
+271
+272
+273
+274
+275
+276
+277
+278
+279
+280
+281
@quam_dataclass
+class Pulse(QuamComponent):
+    """QuAM base component for a pulse.
+
+    Pulses are added to a channel using
+    ```
+    channel.operations["pulse_name"] = pulse
+    ```
+
+    The `Pulse` class is an abstract base class, and should not be instantiated
+    directly. Instead, use one of the subclasses such as:
+    - `ConstantReadoutPulse`
+    - `DragPulse`
+    - `SquarePulse`
+    - `GaussianPulse`
+    or create a custom subclass. In this case, the method `waveform_function` should
+    be implemented.
+
+    Args:
+        operation (str): The operation of the pulse, either "control" or "measurement".
+            Default is "control".
+        length (int): The length of the pulse in samples.
+        digital_marker (str, list, optional): The digital marker to use for the pulse.
+            Can be a string, in which case it is a reference to a digital marker in the
+            config, or a list of tuples of (sample, length) pairs. Default is None.
+
+    Note:
+        The unique pulse label is automatically generated from the channel name and
+        the pulse name, the same for the waveform and digital marker names.
+        The pulse label is defined as `"{channel_name}.{pulse_name}.pulse"`.
+        The waveform label is defined as `"{channel_name}.{pulse_name}.wf"`.
+        The digital marker label is defined as `"{channel_name}.{pulse_name}.dm"`.
+
+    """
+
+    operation: ClassVar[str] = "control"
+    length: int
+    id: str = None
+
+    digital_marker: Union[str, List[Tuple[int, int]]] = None
+
+    @property
+    def channel(self):
+        """The channel to which the pulse is attached, None if no channel is attached"""
+        from quam.components.channels import Channel
+
+        if isinstance(self.parent, Channel):
+            return self.parent
+        elif hasattr(self.parent, "parent") and isinstance(self.parent.parent, Channel):
+            return self.parent.parent
+        else:
+            return None
+
+    @property
+    def name(self):
+        if self.channel is None:
+            raise AttributeError(
+                f"Cannot get full name of pulse '{self}' because it is not"
+                " attached to a channel"
+            )
+
+        if self.id is not None:
+            name = self.id
+        else:
+            name = self.parent.get_attr_name(self)
+
+        return f"{self.channel.name}{str_ref.DELIMITER}{name}"
+
+    @property
+    def pulse_name(self):
+        return f"{self.name}{str_ref.DELIMITER}pulse"
+
+    @property
+    def waveform_name(self):
+        return f"{self.name}{str_ref.DELIMITER}wf"
+
+    @property
+    def digital_marker_name(self):
+        return f"{self.name}{str_ref.DELIMITER}dm"
+
+    def calculate_waveform(self) -> Union[float, complex, List[float], List[complex]]:
+        """Calculate the waveform of the pulse.
+
+        This function calls `Pulse.waveform_function`, which should generally be
+        subclassed, to generate the waveform.
+
+        This function then processes the results such that IQ waveforms are cast
+        into complex values.
+
+        Returns:
+            The processed waveform, which can be either
+            - a single float for a constant single-channel waveform,
+            - a single complex number for a constant IQ waveform,
+            - a list of floats for an arbitrary single-channel waveform,
+            - a list of complex numbers for an arbitrary IQ waveform,
+        """
+        waveform = self.waveform_function()
+
+        # Optionally convert IQ waveforms to complex waveform
+        if isinstance(waveform, tuple) and len(waveform) == 2:
+            if isinstance(waveform[0], (list, np.ndarray)):
+                waveform = np.array(waveform[0]) + 1.0j * np.array(waveform[1])
+            else:
+                waveform = waveform[0] + 1.0j * waveform[1]
+
+        return waveform
+
+    def waveform_function(
+        self,
+    ) -> Union[
+        float,
+        complex,
+        List[float],
+        List[complex],
+        Tuple[float, float],
+        Tuple[List[float], List[float]],
+    ]:
+        """Function that returns the waveform of the pulse.
+
+        The waveform function should use the relevant parameters from the pulse, which
+        is passed as the only argument.
+
+        This function is called from `Pulse.calculate_waveform`
+
+        Returns:
+            The waveform of the pulse. Can be one of the following:
+            - a single float for a constant single-channel waveform,
+            - a single complex number for a constant IQ waveform,
+            - a list of floats for an arbitrary single-channel waveform,
+            - a list of complex numbers for an arbitrary IQ waveform,
+            - a tuple of floats or float lists for an arbitrary IQ waveform
+        """
+        ...
+
+    def _config_add_pulse(self, config: Dict[str, Any]):
+        """Add the pulse to the config
+
+        The config entry is added to `config["pulses"][self.pulse_name]`
+        """
+        assert self.operation in ["control", "measurement"]
+        assert isinstance(self.length, int)
+
+        pulse_config = config["pulses"][self.pulse_name] = {
+            "operation": self.operation,
+            "length": self.length,
+        }
+        if self.digital_marker is not None:
+            pulse_config["digital_marker"] = self.digital_marker
+
+    def _config_add_waveforms(self, config):
+        """Add the waveform to the config
+
+        For a single waveform, the config entry is added to
+        `config["waveforms"]["{channel_name}.{pulse_name}.wf"]`.
+        For an IQ waveform, two config entries are added to
+        `config["waveforms"]["{channel_name}.{pulse_name}.wf.I"]` and with suffix `Q`.
+
+        Raises:
+            ValueError: If the waveform type (single or IQ) does not match the parent
+                channel type (SingleChannel, IQChannel, InOutIQChannel).
+        """
+
+        from quam.components.channels import SingleChannel, IQChannel
+
+        pulse_config = config["pulses"][self.pulse_name]
+
+        waveform = self.calculate_waveform()
+        if waveform is None:
+            return
+
+        pulse_config["waveforms"] = {}
+
+        if isinstance(waveform, numbers.Number):
+            wf_type = "constant"
+            if isinstance(waveform, complex):
+                waveforms = {"I": waveform.real, "Q": waveform.imag}
+            elif isinstance(self.channel, IQChannel):
+                waveforms = {"I": waveform, "Q": 0.0}
+            else:
+                waveforms = {"single": waveform}
+
+        elif isinstance(waveform, (list, np.ndarray)):
+            wf_type = "arbitrary"
+            if np.iscomplexobj(waveform):
+                waveforms = {"I": list(waveform.real), "Q": list(waveform.imag)}
+            elif isinstance(self.channel, IQChannel):
+                waveforms = {"I": waveform, "Q": np.zeros_like(waveform)}
+            else:
+                waveforms = {"single": list(waveform)}
+        else:
+            raise ValueError("unsupported return type")
+
+        # Add check that waveform type (single or IQ) matches parent
+        if "single" in waveforms and not isinstance(self.channel, SingleChannel):
+            raise ValueError(
+                "Waveform type 'single' not allowed for IQChannel"
+                f" '{self.channel.name}'"
+            )
+        elif "I" in waveforms and not isinstance(self.channel, IQChannel):
+            raise ValueError(
+                "Waveform type 'IQ' not allowed for SingleChannel"
+                f" '{self.channel.name}'"
+            )
+
+        for suffix, waveform in waveforms.items():
+            waveform_name = self.waveform_name
+            if suffix != "single":
+                waveform_name += f"{str_ref.DELIMITER}{suffix}"
+
+            sample_label = "sample" if wf_type == "constant" else "samples"
+
+            config["waveforms"][waveform_name] = {
+                "type": wf_type,
+                sample_label: waveform,
+            }
+            pulse_config["waveforms"][suffix] = waveform_name
+
+    def _config_add_digital_markers(self, config):
+        """Add the digital marker to the config
+
+        The config entry is added to
+        `config["digital_waveforms"]["{channel_name}.{pulse_name}.dm"]` and also
+        registered in
+        `config["pulses"]["{channel_name}.{pulse_name}.pulse"]["digital_marker"]`.
+
+        If the digital marker is a string, it is assumed to be a reference to a
+        digital marker already defined in the config.
+        """
+        if isinstance(self.digital_marker, str):
+            # Use a common config digital marker
+            if self.digital_marker not in config["digital_waveforms"]:
+                raise KeyError(
+                    "{self.name}.digital_marker={self.digital_marker} not in"
+                    " config['digital_waveforms']"
+                )
+            digital_marker_name = self.digital_marker
+        else:
+            config["digital_waveforms"][self.digital_marker_name] = {
+                "samples": self.digital_marker
+            }
+            digital_marker_name = self.digital_marker_name
+
+        config["pulses"][self.pulse_name]["digital_marker"] = digital_marker_name
+
+    def apply_to_config(self, config: dict) -> None:
+        """Adds this pulse, waveform, and digital marker to the QUA configuration.
+
+        See [`QuamComponent.apply_to_config`][quam.core.quam_classes.QuamComponent.apply_to_config]
+        for details.
+        """
+        if self.channel is None:
+            return
+
+        self._config_add_pulse(config)
+        self._config_add_waveforms(config)
+
+        if self.digital_marker:
+            self._config_add_digital_markers(config)
+
+
+ + + +
+ + + + + + + +
+ + + +

+ channel + + + property + + +

+ + +
+ +

The channel to which the pulse is attached, None if no channel is attached

+
+ +
+ + + +
+ + +

+ apply_to_config(config) + +

+ + +
+ +

Adds this pulse, waveform, and digital marker to the QUA configuration.

+

See QuamComponent.apply_to_config +for details.

+ +
+ Source code in quam/components/pulses.py + 
268
+269
+270
+271
+272
+273
+274
+275
+276
+277
+278
+279
+280
+281
def apply_to_config(self, config: dict) -> None:
+    """Adds this pulse, waveform, and digital marker to the QUA configuration.
+
+    See [`QuamComponent.apply_to_config`][quam.core.quam_classes.QuamComponent.apply_to_config]
+    for details.
+    """
+    if self.channel is None:
+        return
+
+    self._config_add_pulse(config)
+    self._config_add_waveforms(config)
+
+    if self.digital_marker:
+        self._config_add_digital_markers(config)
+
+
+
+ +
+ +
+ + +

+ calculate_waveform() + +

+ + +
+ +

Calculate the waveform of the pulse.

+

This function calls Pulse.waveform_function, which should generally be +subclassed, to generate the waveform.

+

This function then processes the results such that IQ waveforms are cast +into complex values.

+ + +

Returns:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDescription
+ Union[float, complex, List[float], List[complex]] + +
+

The processed waveform, which can be either

+
+
+ Union[float, complex, List[float], List[complex]] + +
+
    +
  • a single float for a constant single-channel waveform,
    • +
+
+
+ Union[float, complex, List[float], List[complex]] + +
+
    +
  • a single complex number for a constant IQ waveform,
    • +
+
+
+ Union[float, complex, List[float], List[complex]] + +
+
    +
  • a list of floats for an arbitrary single-channel waveform,
    • +
+
+
+ Union[float, complex, List[float], List[complex]] + +
+
    +
  • a list of complex numbers for an arbitrary IQ waveform,
    • +
+
+
+ +
+ Source code in quam/components/pulses.py + 
104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
def calculate_waveform(self) -> Union[float, complex, List[float], List[complex]]:
+    """Calculate the waveform of the pulse.
+
+    This function calls `Pulse.waveform_function`, which should generally be
+    subclassed, to generate the waveform.
+
+    This function then processes the results such that IQ waveforms are cast
+    into complex values.
+
+    Returns:
+        The processed waveform, which can be either
+        - a single float for a constant single-channel waveform,
+        - a single complex number for a constant IQ waveform,
+        - a list of floats for an arbitrary single-channel waveform,
+        - a list of complex numbers for an arbitrary IQ waveform,
+    """
+    waveform = self.waveform_function()
+
+    # Optionally convert IQ waveforms to complex waveform
+    if isinstance(waveform, tuple) and len(waveform) == 2:
+        if isinstance(waveform[0], (list, np.ndarray)):
+            waveform = np.array(waveform[0]) + 1.0j * np.array(waveform[1])
+        else:
+            waveform = waveform[0] + 1.0j * waveform[1]
+
+    return waveform
+
+
+
+ +
+ +
+ + +

+ waveform_function() + +

+ + +
+ +

Function that returns the waveform of the pulse.

+

The waveform function should use the relevant parameters from the pulse, which +is passed as the only argument.

+

This function is called from Pulse.calculate_waveform

+ + +

Returns:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDescription
+ Union[float, complex, List[float], List[complex], Tuple[float, float], Tuple[List[float], List[float]]] + +
+

The waveform of the pulse. Can be one of the following:

+
+
+ Union[float, complex, List[float], List[complex], Tuple[float, float], Tuple[List[float], List[float]]] + +
+
    +
  • a single float for a constant single-channel waveform,
    • +
+
+
+ Union[float, complex, List[float], List[complex], Tuple[float, float], Tuple[List[float], List[float]]] + +
+
    +
  • a single complex number for a constant IQ waveform,
    • +
+
+
+ Union[float, complex, List[float], List[complex], Tuple[float, float], Tuple[List[float], List[float]]] + +
+
    +
  • a list of floats for an arbitrary single-channel waveform,
    • +
+
+
+ Union[float, complex, List[float], List[complex], Tuple[float, float], Tuple[List[float], List[float]]] + +
+
    +
  • a list of complex numbers for an arbitrary IQ waveform,
    • +
+
+
+ Union[float, complex, List[float], List[complex], Tuple[float, float], Tuple[List[float], List[float]]] + +
+
    +
  • a tuple of floats or float lists for an arbitrary IQ waveform
    • +
+
+
+ +
+ Source code in quam/components/pulses.py + 
131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
def waveform_function(
+    self,
+) -> Union[
+    float,
+    complex,
+    List[float],
+    List[complex],
+    Tuple[float, float],
+    Tuple[List[float], List[float]],
+]:
+    """Function that returns the waveform of the pulse.
+
+    The waveform function should use the relevant parameters from the pulse, which
+    is passed as the only argument.
+
+    This function is called from `Pulse.calculate_waveform`
+
+    Returns:
+        The waveform of the pulse. Can be one of the following:
+        - a single float for a constant single-channel waveform,
+        - a single complex number for a constant IQ waveform,
+        - a list of floats for an arbitrary single-channel waveform,
+        - a list of complex numbers for an arbitrary IQ waveform,
+        - a tuple of floats or float lists for an arbitrary IQ waveform
+    """
+    ...
+
+
+
+ +
+ + + +
+ +
+ +
+ +
+ + + +

+ ReadoutPulse + + +

+ + +
+

+ Bases: BaseReadoutPulse, ABC

+ + +

QuAM abstract base component for most readout pulses.

+

This class is a subclass of ReadoutPulse and should be used for most readout +pulses. It provides a default implementation of the integration_weights_function +method, which is suitable for most cases.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
length + int + +
+

The length of the pulse in samples.

+
+ 		+ required +
digital_marker + (str, list) + +
+

The digital marker to use for the pulse. +Default is "ON".

+
+ 		+ required +
integration_weights + (list[float], list[tuple[float, int]]) + +
+

The +integration weights, can be either +- a list of floats (one per sample), the length must match the pulse length +- a list of tuples of (weight, length) pairs, the sum of the lengths must + match the pulse length

+
+ 		+ required +
integration_weights_angle + float + +
+

The rotation angle for the +integration weights in radians.

+
+ 		+ required +
+ +
+ Source code in quam/components/pulses.py + 
354
+355
+356
+357
+358
+359
+360
+361
+362
+363
+364
+365
+366
+367
+368
+369
+370
+371
+372
+373
+374
+375
+376
+377
+378
+379
+380
+381
+382
+383
+384
+385
+386
+387
+388
+389
+390
+391
+392
+393
+394
+395
@quam_dataclass
+class ReadoutPulse(BaseReadoutPulse, ABC):
+    """QuAM abstract base component for most readout pulses.
+
+    This class is a subclass of `ReadoutPulse` and should be used for most readout
+    pulses. It provides a default implementation of the `integration_weights_function`
+    method, which is suitable for most cases.
+
+    Args:
+        length (int): The length of the pulse in samples.
+        digital_marker (str, list, optional): The digital marker to use for the pulse.
+            Default is "ON".
+        integration_weights (list[float], list[tuple[float, int]], optional): The
+            integration weights, can be either
+            - a list of floats (one per sample), the length must match the pulse length
+            - a list of tuples of (weight, length) pairs, the sum of the lengths must
+              match the pulse length
+        integration_weights_angle (float, optional): The rotation angle for the
+            integration weights in radians.
+    """
+
+    integration_weights: Union[List[float], List[Tuple[float, int]]] = None
+    integration_weights_angle: float = 0
+
+    def integration_weights_function(self) -> List[Tuple[Union[complex, float], int]]:
+        from qualang_tools.config import convert_integration_weights
+
+        phase = np.exp(1j * self.integration_weights_angle)
+
+        if self.integration_weights is None or not len(self.integration_weights):
+            integration_weights = [(1, self.length)]
+        elif isinstance(self.integration_weights[0], float):
+            integration_weights = convert_integration_weights(self.integration_weights)
+        else:
+            integration_weights = self.integration_weights
+
+        return {
+            "real": [(phase.real * w, l) for w, l in integration_weights],
+            "imag": [(phase.imag * w, l) for w, l in integration_weights],
+            "minus_real": [(-phase.real * w, l) for w, l in integration_weights],
+            "minus_imag": [(-phase.imag * w, l) for w, l in integration_weights],
+        }
+
+
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ +
+ + + +

+ SquarePulse + + +

+ + +
+

+ Bases: Pulse

+ + +

Square pulse QuAM component.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
length + int + +
+

The length of the pulse in samples.

+
+ 		+ required +
digital_marker + (str, list) + +
+

The digital marker to use for the pulse.

+
+ 		+ required +
amplitude + float + +
+

The amplitude of the pulse in volts.

+
+ 		+ required +
axis_angle + float + +
+

IQ axis angle of the output pulse in radians. +If None (default), the pulse is meant for a single channel or the I port + of an IQ channel +If not None, the pulse is meant for an IQ channel (0 is X, pi/2 is Y).

+
+ 		+ required +
+ +
+ Source code in quam/components/pulses.py + 
454
+455
+456
+457
+458
+459
+460
+461
+462
+463
+464
+465
+466
+467
+468
+469
+470
+471
+472
+473
+474
+475
+476
@quam_dataclass
+class SquarePulse(Pulse):
+    """Square pulse QuAM component.
+
+    Args:
+        length (int): The length of the pulse in samples.
+        digital_marker (str, list, optional): The digital marker to use for the pulse.
+        amplitude (float): The amplitude of the pulse in volts.
+        axis_angle (float, optional): IQ axis angle of the output pulse in radians.
+            If None (default), the pulse is meant for a single channel or the I port
+                of an IQ channel
+            If not None, the pulse is meant for an IQ channel (0 is X, pi/2 is Y).
+    """
+
+    amplitude: float
+    axis_angle: float = None
+
+    def waveform_function(self):
+        waveform = self.amplitude
+
+        if self.axis_angle is not None:
+            waveform = waveform * np.exp(1j * self.axis_angle)
+        return waveform
+
+
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ +
+ + + +

+ SquareReadoutPulse + + +

+ + +
+

+ Bases: ReadoutPulse, SquarePulse

+ + +

QuAM component for a square readout pulse.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
length + int + +
+

The length of the pulse in samples.

+
+ 		+ required +
digital_marker + (str, list) + +
+

The digital marker to use for the pulse. +Default is "ON".

+
+ 		+ required +
amplitude + float + +
+

The constant amplitude of the pulse.

+
+ 		+ required +
axis_angle + float + +
+

IQ axis angle of the output pulse in radians. +If None (default), the pulse is meant for a single channel or the I port + of an IQ channel +If not None, the pulse is meant for an IQ channel (0 is X, pi/2 is Y).

+
+ 		+ required +
integration_weights + (list[float], list[tuple[float, int]]) + +
+

The +integration weights, can be either +- a list of floats (one per sample), the length must match the pulse length +- a list of tuples of (weight, length) pairs, the sum of the lengths must + match the pulse length

+
+ 		+ required +
integration_weights_angle + float + +
+

The rotation angle for the +integration weights in radians.

+
+ 		+ required +
+ +
+ Source code in quam/components/pulses.py + 
479
+480
+481
+482
+483
+484
+485
+486
+487
+488
+489
+490
+491
+492
+493
+494
+495
+496
+497
+498
+499
+500
+501
@quam_dataclass
+class SquareReadoutPulse(ReadoutPulse, SquarePulse):
+    """QuAM component for a square readout pulse.
+
+    Args:
+        length (int): The length of the pulse in samples.
+        digital_marker (str, list, optional): The digital marker to use for the pulse.
+            Default is "ON".
+        amplitude (float): The constant amplitude of the pulse.
+        axis_angle (float, optional): IQ axis angle of the output pulse in radians.
+            If None (default), the pulse is meant for a single channel or the I port
+                of an IQ channel
+            If not None, the pulse is meant for an IQ channel (0 is X, pi/2 is Y).
+        integration_weights (list[float], list[tuple[float, int]], optional): The
+            integration weights, can be either
+            - a list of floats (one per sample), the length must match the pulse length
+            - a list of tuples of (weight, length) pairs, the sum of the lengths must
+              match the pulse length
+        integration_weights_angle (float, optional): The rotation angle for the
+            integration weights in radians.
+    """
+
+    ...
+
+
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ + + + +
+ +
+ +
+ + + + + + + + + + + + + +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API_references/core/deprecations/index.html b/API_references/core/deprecations/index.html new file mode 100644 index 00000000..47c90dce --- /dev/null +++ b/API_references/core/deprecations/index.html @@ -0,0 +1,909 @@ + + + + + + + + + + + + + + + + + + + + + Deprecations - The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ + + + +

Deprecations

+ +
+ + + + +
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ + + + + + + + + + + + + +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API_references/core/qua_config_template/index.html b/API_references/core/qua_config_template/index.html new file mode 100644 index 00000000..f45dacca --- /dev/null +++ b/API_references/core/qua_config_template/index.html @@ -0,0 +1,909 @@ + + + + + + + + + + + + + + + + + + + + + Qua config template - The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ + + + +

Qua config template

+ +
+ + + + +
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ + + + + + + + + + + + + +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API_references/core/quam_classes/index.html b/API_references/core/quam_classes/index.html new file mode 100644 index 00000000..c8c36ecb --- /dev/null +++ b/API_references/core/quam_classes/index.html @@ -0,0 +1,5548 @@ + + + + + + + + + + + + + + + + + + + + + Quam classes - The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ + + + +

Quam classes

+ +
+ + + + +
+ + + +
+ + + + + + + + +
+ + + +

+ ParentDescriptor + + +

+ + +
+ + +

Descriptor for the parent attribute of QuamBase.

+

This descriptor is used to ensure that the parent attribute of a QuamBase +object is not overwritten. This is to prevent the following situation:

+
parent1 = QuamBase()
+parent2 = QuamBase()
+
+child = QuamBase()
+child.parent = parent1  # This is fine
+child.parent = parent2  # This raises an AttributeError
+
+ +
+ Source code in quam/core/quam_classes.py + 
184
+185
+186
+187
+188
+189
+190
+191
+192
+193
+194
+195
+196
+197
+198
+199
+200
+201
+202
+203
+204
+205
+206
+207
+208
+209
+210
+211
+212
+213
+214
+215
+216
+217
+218
+219
class ParentDescriptor:
+    """Descriptor for the parent attribute of QuamBase.
+
+    This descriptor is used to ensure that the parent attribute of a QuamBase
+    object is not overwritten. This is to prevent the following situation:
+
+    ```
+    parent1 = QuamBase()
+    parent2 = QuamBase()
+
+    child = QuamBase()
+    child.parent = parent1  # This is fine
+    child.parent = parent2  # This raises an AttributeError
+    ```
+    """
+
+    def __get__(self, instance, owner):
+        if instance is None:
+            return self
+
+        if "parent" in instance.__dict__:
+            return instance.__dict__["parent"]
+        return None
+
+    def __set__(self, instance, value):
+        if value is None:
+            instance.__dict__.pop("parent", None)
+            return
+
+        if "parent" in instance.__dict__ and instance.__dict__["parent"] is not value:
+            cls = instance.__class__.__name__
+            raise AttributeError(
+                f"Cannot overwrite parent attribute of {cls}. "
+                f"To modify {cls}.parent, first set {cls}.parent = None"
+            )
+        instance.__dict__["parent"] = value
+
+
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ +
+ + + +

+ QuamBase + + +

+ + +
+

+ Bases: ReferenceClass

+ + +

Base class for any QuAM component class.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
parent + +
+

The parent of this object. This is automatically set when adding +this object to another QuamBase object.

+
+ 		+ required +
_root + +
+

The QuamRoot object. This is automatically set when instantiating +a QuamRoot object.

+
+ 		+ required +
config_settings + +
+

A dictionary of configuration settings for this object. +This is used by QuamRoot.generate_config +to determine the order in which to add the components to the QUA config. +Keys are "before" and "after", and the values are a list of QuamComponents

+
+ 		+ required +
+ + +
+ Note +

This class should not be used directly, but should generally be subclassed. +The subclasses should be dataclasses.

+
+
+ Source code in quam/core/quam_classes.py + 
222
+223
+224
+225
+226
+227
+228
+229
+230
+231
+232
+233
+234
+235
+236
+237
+238
+239
+240
+241
+242
+243
+244
+245
+246
+247
+248
+249
+250
+251
+252
+253
+254
+255
+256
+257
+258
+259
+260
+261
+262
+263
+264
+265
+266
+267
+268
+269
+270
+271
+272
+273
+274
+275
+276
+277
+278
+279
+280
+281
+282
+283
+284
+285
+286
+287
+288
+289
+290
+291
+292
+293
+294
+295
+296
+297
+298
+299
+300
+301
+302
+303
+304
+305
+306
+307
+308
+309
+310
+311
+312
+313
+314
+315
+316
+317
+318
+319
+320
+321
+322
+323
+324
+325
+326
+327
+328
+329
+330
+331
+332
+333
+334
+335
+336
+337
+338
+339
+340
+341
+342
+343
+344
+345
+346
+347
+348
+349
+350
+351
+352
+353
+354
+355
+356
+357
+358
+359
+360
+361
+362
+363
+364
+365
+366
+367
+368
+369
+370
+371
+372
+373
+374
+375
+376
+377
+378
+379
+380
+381
+382
+383
+384
+385
+386
+387
+388
+389
+390
+391
+392
+393
+394
+395
+396
+397
+398
+399
+400
+401
+402
+403
+404
+405
+406
+407
+408
+409
+410
+411
+412
+413
+414
+415
+416
+417
+418
+419
+420
+421
+422
+423
+424
+425
+426
+427
+428
+429
+430
+431
+432
+433
+434
+435
+436
+437
+438
+439
+440
+441
+442
+443
+444
+445
+446
+447
+448
+449
+450
+451
+452
+453
+454
+455
+456
+457
+458
+459
+460
+461
+462
+463
+464
+465
+466
+467
+468
+469
+470
+471
+472
+473
+474
+475
+476
+477
+478
+479
+480
+481
+482
+483
+484
+485
+486
+487
+488
+489
+490
+491
+492
+493
+494
+495
+496
+497
+498
+499
+500
+501
+502
+503
+504
+505
+506
+507
+508
+509
+510
+511
+512
+513
+514
+515
+516
+517
+518
+519
+520
+521
+522
+523
+524
+525
+526
+527
+528
+529
+530
+531
+532
+533
+534
+535
+536
+537
+538
+539
+540
+541
+542
+543
class QuamBase(ReferenceClass):
+    """Base class for any QuAM component class.
+
+    args:
+        parent: The parent of this object. This is automatically set when adding
+            this object to another QuamBase object.
+        _root: The QuamRoot object. This is automatically set when instantiating
+            a QuamRoot object.
+        config_settings: A dictionary of configuration settings for this object.
+            This is used by [`QuamRoot.generate_config`][quam.core.quam_classes.QuamRoot.generate_config]
+            to determine the order in which to add the components to the QUA config.
+            Keys are "before" and "after", and the values are a list of QuamComponents
+
+    Note:
+        This class should not be used directly, but should generally be subclassed.
+        The subclasses should be dataclasses.
+    """
+
+    parent: ClassVar["QuamBase"] = ParentDescriptor()
+    _root: ClassVar["QuamRoot"] = None
+
+    config_settings: ClassVar[Dict[str, Any]] = None
+
+    def __init__(self):
+        # This prohibits instantiating without it being a dataclass
+        # This means that we have to subclass this class and make it a dataclass
+        if not is_dataclass(self):
+            if type(self) in [QuamBase, QuamComponent, QuamRoot]:
+                raise TypeError(
+                    f"Cannot instantiate {self.__class__.__name__} directly. "
+                    "Please create a subclass and make it a dataclass."
+                )
+            else:
+                raise TypeError(
+                    f"Cannot instantiate {self.__class__.__name__}. "
+                    "Please make it a dataclass."
+                )
+
+    def _get_attr_names(self) -> List[str]:
+        """Get names of all dataclass attributes of this object.
+
+        Returns:
+            List of attribute names.
+
+        Raises:
+            AssertionError if not a dataclass.
+        """
+        assert is_dataclass(self)
+        return [data_field.name for data_field in fields(self)]
+
+    def get_attr_name(self, attr_val: Any) -> str:
+        """Get the name of an attribute that matches the value.
+
+        Args:
+            attr_val: The value of the attribute.
+
+        Returns:
+            The name of the attribute.
+
+        Raises:
+            AttributeError if not found.
+        """
+        for attr_name in self._get_attr_names():
+            if getattr(self, attr_name) is attr_val:
+                return attr_name
+        else:
+            raise AttributeError(
+                "Could not find name corresponding to attribute.\n"
+                f"attribute: {attr_val}\n"
+                f"obj: {self}"
+            )
+
+    def _attr_val_is_default(self, attr: str, val: Any) -> bool:
+        """Check whether the value of an attribute is the default value.
+
+        Args:
+            attr: The name of the attribute.
+            val: The value of the attribute.
+
+        Returns:
+            True if the value is the default value, False otherwise.
+            False is also returned if the parent is not a dataclass
+        """
+        if not is_dataclass(self):
+            return False
+
+        dataclass_fields = fields(self)
+        if not any(field.name == attr for field in dataclass_fields):
+            return False
+
+        field = next(field for field in dataclass_fields if field.name == attr)
+        if field.default is not MISSING:
+            return val == field.default
+        elif field.default_factory is not MISSING:
+            try:
+                default_val = field.default_factory()
+                return val == default_val
+            except TypeError:
+                return False
+
+        return False
+
+    @classmethod
+    def _val_matches_attr_annotation(cls, attr: str, val: Any) -> bool:
+        """Check whether the type of an attribute matches the annotation.
+
+        The attribute type must exactly match the annotation.
+        For dict and list, no additional type check of args is performed.
+        """
+        annotated_attrs = get_dataclass_attr_annotations(cls)
+        if attr not in annotated_attrs["allowed"]:
+            return False
+
+        required_type = annotated_attrs["allowed"][attr]
+        if type_is_optional(required_type):
+            required_type = get_args(required_type)[0]
+
+        if required_type == dict or get_origin(required_type) == dict:
+            return isinstance(val, (dict, QuamDict))
+        elif required_type == list or get_origin(required_type) == list:
+            return isinstance(val, (list, QuamList))
+        return type(val) == required_type
+
+    def get_reference(self, attr=None) -> Optional[str]:
+        """Get the reference path of this object.
+
+        Args:
+            attr: The attribute to get the reference path for. If None, the reference
+                path of the object itself is returned.
+
+        Returns:
+            The reference path of this object.
+        """
+
+        if self.parent is None:
+            raise AttributeError(
+                "Unable to extract reference path. Parent must be defined for {self}"
+            )
+        reference = f"{self.parent.get_reference()}/{self.parent.get_attr_name(self)}"
+        if attr is not None:
+            reference = f"{reference}/{attr}"
+        return reference
+
+    def get_attrs(
+        self, follow_references: bool = False, include_defaults: bool = True
+    ) -> Dict[str, Any]:
+        """Get all attributes and corresponding values of this object.
+
+        Args:
+            follow_references: Whether to follow references when getting the value.
+                If False, the reference will be returned as a string.
+            include_defaults: Whether to include attributes that have the default
+                value.
+
+        Returns:
+            A dictionary of attribute names and values.
+
+        """
+        attr_names = self._get_attr_names()
+
+        skip_attrs = getattr(self, "_skip_attrs", [])
+        attr_names = [attr for attr in attr_names if attr not in skip_attrs]
+
+        if not follow_references:
+            attrs = {attr: self.get_unreferenced_value(attr) for attr in attr_names}
+        else:
+            attrs = {attr: getattr(self, attr) for attr in attr_names}
+
+        if not include_defaults:
+            attrs = {
+                attr: val
+                for attr, val in attrs.items()
+                if not self._attr_val_is_default(attr, val)
+            }
+        return attrs
+
+    def to_dict(
+        self, follow_references: bool = False, include_defaults: bool = False
+    ) -> Dict[str, Any]:
+        """Convert this object to a dictionary.
+
+        Args:
+            follow_references: Whether to follow references when getting the value.
+                If False, the reference will be returned as a string.
+            include_defaults: Whether to include attributes that have the default
+
+        Returns:
+            A dictionary representation of this object.
+            Any QuamBase objects will be recursively converted to dictionaries.
+
+        Note:
+            If the value of an attribute does not match the annotation, the
+            `"__class__"` key will be added to the dictionary. This is to ensure
+            that the object can be reconstructed when loading from a file.
+        """
+        attrs = self.get_attrs(
+            follow_references=follow_references, include_defaults=include_defaults
+        )
+        quam_dict = {}
+        for attr, val in attrs.items():
+            if isinstance(val, QuamBase):
+                quam_dict[attr] = val.to_dict(
+                    follow_references=follow_references,
+                    include_defaults=include_defaults,
+                )
+                val_is_list = isinstance(val, (list, UserList))
+                if not self._val_matches_attr_annotation(attr, val) and not val_is_list:
+                    quam_dict[attr]["__class__"] = get_full_class_path(val)
+            else:
+                quam_dict[attr] = val
+        return quam_dict
+
+    def iterate_components(
+        self, skip_elems: bool = None
+    ) -> Generator["QuamBase", None, None]:
+        """Iterate over all QuamBase objects in this object, including nested objects.
+
+        Args:
+            skip_elems: A list of QuamBase objects to skip.
+                This is used to prevent infinite loops when iterating over nested
+                objects.
+
+        Returns:
+            A generator of QuamBase objects.
+        """
+        if skip_elems is None:
+            skip_elems = []
+
+        # We don't use "self in skip_elems" because we want to check for identity,
+        # not equality. The reason is that you would otherwise have to instantiate
+        # dataclasses using @dataclass(eq=False)
+        in_skip_elems = any(self is elem for elem in skip_elems)
+        if isinstance(self, QuamComponent) and not in_skip_elems:
+            skip_elems.append(self)
+            yield self
+
+        attrs = self.get_attrs(follow_references=False, include_defaults=True)
+
+        for attr_val in attrs.values():
+            if any(attr_val is elem for elem in skip_elems):
+                continue
+
+            if isinstance(attr_val, QuamBase):
+                yield from attr_val.iterate_components(skip_elems=skip_elems)
+
+    def _is_reference(self, attr: str) -> bool:
+        """Check whether an attribute is a reference.
+
+        Args:
+            attr: The name of the attribute.
+
+        Returns:
+            True if the attribute is a reference, False otherwise.
+
+        Note:
+            This function is used from the ReferenceClass class.
+        """
+        return string_reference.is_reference(attr)
+
+    def _get_referenced_value(self, reference: str) -> Any:
+        """Get the value of an attribute by reference
+
+        Args:
+            reference: The reference to the attribute.
+
+        Returns:
+            The value of the attribute, or the reference if it is not a reference
+
+        Note:
+            This function is used from the ReferenceClass class.
+        """
+        if not string_reference.is_reference(reference):
+            return reference
+
+        if string_reference.is_absolute_reference(reference) and self._root is None:
+            warnings.warn(
+                f"No QuamRoot initialized, cannot retrieve reference {reference}"
+                f" from {self.__class__.__name__}"
+            )
+            return reference
+
+        try:
+            return string_reference.get_referenced_value(
+                self, reference, root=self._root
+            )
+        except ValueError as e:
+            try:
+                ref = f"{self.__class__.__name__}: {self.get_reference()}"
+            except Exception:
+                ref = self.__class__.__name__
+            warnings.warn(f"Could not get reference {reference} from {ref}.\n{str(e)}")
+            return reference
+
+    def print_summary(self, indent: int = 0):
+        """Print a summary of the QuamBase object.
+
+        Args:
+            indent: The number of spaces to indent the summary.
+        """
+        if self._root is self:
+            full_name = "QuAM:"
+        elif self.parent is None:
+            full_name = f"{self.__class__.__name__} (parent unknown):"
+        else:
+            try:
+                attr_name = self.parent.get_attr_name(self)
+                full_name = f"{attr_name}: {self.__class__.__name__}"
+            except AttributeError:
+                full_name = f"{self.__class__.__name__}:"
+
+        if not self.get_attrs():
+            print(" " * indent + f"{full_name} Empty")
+            return
+
+        print(" " * indent + f"{full_name}")
+        for attr, val in self.get_attrs().items():
+            if isinstance(val, str):
+                val = f'"{val}"'
+            if isinstance(val, QuamBase):
+                val.print_summary(indent=indent + 2)
+            else:
+                print(" " * (indent + 2) + f"{attr}: {val}")
+
+
+ + + +
+ + + + + + + + + +
+ + +

+ get_attr_name(attr_val) + +

+ + +
+ +

Get the name of an attribute that matches the value.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
attr_val + Any + +
+

The value of the attribute.

+
+ 		+ required +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ str + +
+

The name of the attribute.

+
+
+ +
+ Source code in quam/core/quam_classes.py + 
272
+273
+274
+275
+276
+277
+278
+279
+280
+281
+282
+283
+284
+285
+286
+287
+288
+289
+290
+291
+292
def get_attr_name(self, attr_val: Any) -> str:
+    """Get the name of an attribute that matches the value.
+
+    Args:
+        attr_val: The value of the attribute.
+
+    Returns:
+        The name of the attribute.
+
+    Raises:
+        AttributeError if not found.
+    """
+    for attr_name in self._get_attr_names():
+        if getattr(self, attr_name) is attr_val:
+            return attr_name
+    else:
+        raise AttributeError(
+            "Could not find name corresponding to attribute.\n"
+            f"attribute: {attr_val}\n"
+            f"obj: {self}"
+        )
+
+
+
+ +
+ +
+ + +

+ get_attrs(follow_references=False, include_defaults=True) + +

+ + +
+ +

Get all attributes and corresponding values of this object.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
follow_references + bool + +
+

Whether to follow references when getting the value. +If False, the reference will be returned as a string.

+
+ 		+ False +
include_defaults + bool + +
+

Whether to include attributes that have the default +value.

+
+ 		+ True +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ Dict[str, Any] + +
+

A dictionary of attribute names and values.

+
+
+ +
+ Source code in quam/core/quam_classes.py + 
365
+366
+367
+368
+369
+370
+371
+372
+373
+374
+375
+376
+377
+378
+379
+380
+381
+382
+383
+384
+385
+386
+387
+388
+389
+390
+391
+392
+393
+394
+395
+396
def get_attrs(
+    self, follow_references: bool = False, include_defaults: bool = True
+) -> Dict[str, Any]:
+    """Get all attributes and corresponding values of this object.
+
+    Args:
+        follow_references: Whether to follow references when getting the value.
+            If False, the reference will be returned as a string.
+        include_defaults: Whether to include attributes that have the default
+            value.
+
+    Returns:
+        A dictionary of attribute names and values.
+
+    """
+    attr_names = self._get_attr_names()
+
+    skip_attrs = getattr(self, "_skip_attrs", [])
+    attr_names = [attr for attr in attr_names if attr not in skip_attrs]
+
+    if not follow_references:
+        attrs = {attr: self.get_unreferenced_value(attr) for attr in attr_names}
+    else:
+        attrs = {attr: getattr(self, attr) for attr in attr_names}
+
+    if not include_defaults:
+        attrs = {
+            attr: val
+            for attr, val in attrs.items()
+            if not self._attr_val_is_default(attr, val)
+        }
+    return attrs
+
+
+
+ +
+ +
+ + +

+ get_reference(attr=None) + +

+ + +
+ +

Get the reference path of this object.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
attr + +
+

The attribute to get the reference path for. If None, the reference +path of the object itself is returned.

+
+ 		+ None +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ Optional[str] + +
+

The reference path of this object.

+
+
+ +
+ Source code in quam/core/quam_classes.py + 
345
+346
+347
+348
+349
+350
+351
+352
+353
+354
+355
+356
+357
+358
+359
+360
+361
+362
+363
def get_reference(self, attr=None) -> Optional[str]:
+    """Get the reference path of this object.
+
+    Args:
+        attr: The attribute to get the reference path for. If None, the reference
+            path of the object itself is returned.
+
+    Returns:
+        The reference path of this object.
+    """
+
+    if self.parent is None:
+        raise AttributeError(
+            "Unable to extract reference path. Parent must be defined for {self}"
+        )
+    reference = f"{self.parent.get_reference()}/{self.parent.get_attr_name(self)}"
+    if attr is not None:
+        reference = f"{reference}/{attr}"
+    return reference
+
+
+
+ +
+ +
+ + +

+ iterate_components(skip_elems=None) + +

+ + +
+ +

Iterate over all QuamBase objects in this object, including nested objects.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
skip_elems + bool + +
+

A list of QuamBase objects to skip. +This is used to prevent infinite loops when iterating over nested +objects.

+
+ 		+ None +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ Generator[QuamBase, None, None] + +
+

A generator of QuamBase objects.

+
+
+ +
+ Source code in quam/core/quam_classes.py + 
434
+435
+436
+437
+438
+439
+440
+441
+442
+443
+444
+445
+446
+447
+448
+449
+450
+451
+452
+453
+454
+455
+456
+457
+458
+459
+460
+461
+462
+463
+464
+465
def iterate_components(
+    self, skip_elems: bool = None
+) -> Generator["QuamBase", None, None]:
+    """Iterate over all QuamBase objects in this object, including nested objects.
+
+    Args:
+        skip_elems: A list of QuamBase objects to skip.
+            This is used to prevent infinite loops when iterating over nested
+            objects.
+
+    Returns:
+        A generator of QuamBase objects.
+    """
+    if skip_elems is None:
+        skip_elems = []
+
+    # We don't use "self in skip_elems" because we want to check for identity,
+    # not equality. The reason is that you would otherwise have to instantiate
+    # dataclasses using @dataclass(eq=False)
+    in_skip_elems = any(self is elem for elem in skip_elems)
+    if isinstance(self, QuamComponent) and not in_skip_elems:
+        skip_elems.append(self)
+        yield self
+
+    attrs = self.get_attrs(follow_references=False, include_defaults=True)
+
+    for attr_val in attrs.values():
+        if any(attr_val is elem for elem in skip_elems):
+            continue
+
+        if isinstance(attr_val, QuamBase):
+            yield from attr_val.iterate_components(skip_elems=skip_elems)
+
+
+
+ +
+ +
+ + +

+ print_summary(indent=0) + +

+ + +
+ +

Print a summary of the QuamBase object.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
indent + int + +
+

The number of spaces to indent the summary.

+
+ 		+ 0 +
+ +
+ Source code in quam/core/quam_classes.py + 
515
+516
+517
+518
+519
+520
+521
+522
+523
+524
+525
+526
+527
+528
+529
+530
+531
+532
+533
+534
+535
+536
+537
+538
+539
+540
+541
+542
+543
def print_summary(self, indent: int = 0):
+    """Print a summary of the QuamBase object.
+
+    Args:
+        indent: The number of spaces to indent the summary.
+    """
+    if self._root is self:
+        full_name = "QuAM:"
+    elif self.parent is None:
+        full_name = f"{self.__class__.__name__} (parent unknown):"
+    else:
+        try:
+            attr_name = self.parent.get_attr_name(self)
+            full_name = f"{attr_name}: {self.__class__.__name__}"
+        except AttributeError:
+            full_name = f"{self.__class__.__name__}:"
+
+    if not self.get_attrs():
+        print(" " * indent + f"{full_name} Empty")
+        return
+
+    print(" " * indent + f"{full_name}")
+    for attr, val in self.get_attrs().items():
+        if isinstance(val, str):
+            val = f'"{val}"'
+        if isinstance(val, QuamBase):
+            val.print_summary(indent=indent + 2)
+        else:
+            print(" " * (indent + 2) + f"{attr}: {val}")
+
+
+
+ +
+ +
+ + +

+ to_dict(follow_references=False, include_defaults=False) + +

+ + +
+ +

Convert this object to a dictionary.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
follow_references + bool + +
+

Whether to follow references when getting the value. +If False, the reference will be returned as a string.

+
+ 		+ False +
include_defaults + bool + +
+

Whether to include attributes that have the default

+
+ 		+ False +
+ + +

Returns:

+ + + + + + + + + + + + + + + + + +
TypeDescription
+ Dict[str, Any] + +
+

A dictionary representation of this object.

+
+
+ Dict[str, Any] + +
+

Any QuamBase objects will be recursively converted to dictionaries.

+
+
+ + +
+ Note +

If the value of an attribute does not match the annotation, the +"__class__" key will be added to the dictionary. This is to ensure +that the object can be reconstructed when loading from a file.

+
+
+ Source code in quam/core/quam_classes.py + 
398
+399
+400
+401
+402
+403
+404
+405
+406
+407
+408
+409
+410
+411
+412
+413
+414
+415
+416
+417
+418
+419
+420
+421
+422
+423
+424
+425
+426
+427
+428
+429
+430
+431
+432
def to_dict(
+    self, follow_references: bool = False, include_defaults: bool = False
+) -> Dict[str, Any]:
+    """Convert this object to a dictionary.
+
+    Args:
+        follow_references: Whether to follow references when getting the value.
+            If False, the reference will be returned as a string.
+        include_defaults: Whether to include attributes that have the default
+
+    Returns:
+        A dictionary representation of this object.
+        Any QuamBase objects will be recursively converted to dictionaries.
+
+    Note:
+        If the value of an attribute does not match the annotation, the
+        `"__class__"` key will be added to the dictionary. This is to ensure
+        that the object can be reconstructed when loading from a file.
+    """
+    attrs = self.get_attrs(
+        follow_references=follow_references, include_defaults=include_defaults
+    )
+    quam_dict = {}
+    for attr, val in attrs.items():
+        if isinstance(val, QuamBase):
+            quam_dict[attr] = val.to_dict(
+                follow_references=follow_references,
+                include_defaults=include_defaults,
+            )
+            val_is_list = isinstance(val, (list, UserList))
+            if not self._val_matches_attr_annotation(attr, val) and not val_is_list:
+                quam_dict[attr]["__class__"] = get_full_class_path(val)
+        else:
+            quam_dict[attr] = val
+    return quam_dict
+
+
+
+ +
+ + + +
+ +
+ +
+ +
+ + + +

+ QuamComponent + + +

+ + +
+

+ Bases: QuamBase

+ + +

Base class for any QuAM component class.

+

Examples of QuamComponent classes are Mixer, +LocalOscillator, +Pulse, etc.

+ + +
+ Note +

This class should be subclassed and made a dataclass.

+
+
+ Source code in quam/core/quam_classes.py + 
689
+690
+691
+692
+693
+694
+695
+696
+697
+698
+699
+700
+701
+702
+703
+704
+705
+706
+707
+708
+709
+710
+711
+712
+713
+714
+715
+716
+717
+718
+719
+720
+721
class QuamComponent(QuamBase):
+    """Base class for any QuAM component class.
+
+    Examples of QuamComponent classes are [`Mixer`][quam.components.hardware.Mixer],
+    [`LocalOscillator`][quam.components.hardware.LocalOscillator],
+    [`Pulse`][quam.components.pulses.Pulse], etc.
+
+    Note:
+        This class should be subclassed and made a dataclass.
+    """
+
+    def __setattr__(self, name, value):
+        converted_val = convert_dict_and_list(value, cls_or_obj=self, attr=name)
+        super().__setattr__(name, converted_val)
+
+        if isinstance(converted_val, QuamBase) and name != "parent":
+            converted_val.parent = self
+
+    def apply_to_config(self, config: dict) -> None:
+        """Add information to the QUA configuration, such as pulses and waveforms.
+
+        Args:
+            config: The QUA configuration dictionary. Initially this is a nearly empty
+                dictionary, but
+
+        Note:
+            This function is called by
+            [`QuamRoot.generate_config`][quam.core.quam_classes.QuamRoot.generate_config].
+
+        Note:
+            The config has a starting template, defined at [`quam.core.qua_config_template`][]
+        """
+        ...
+
+
+ + + +
+ + + + + + + + + +
+ + +

+ apply_to_config(config) + +

+ + +
+ +

Add information to the QUA configuration, such as pulses and waveforms.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
config + dict + +
+

The QUA configuration dictionary. Initially this is a nearly empty +dictionary, but

+
+ 		+ required +
+ + +
+ Note +

This function is called by +QuamRoot.generate_config.

+
+ +
+ Note +

The config has a starting template, defined at quam.core.qua_config_template

+
+
+ Source code in quam/core/quam_classes.py + 
707
+708
+709
+710
+711
+712
+713
+714
+715
+716
+717
+718
+719
+720
+721
def apply_to_config(self, config: dict) -> None:
+    """Add information to the QUA configuration, such as pulses and waveforms.
+
+    Args:
+        config: The QUA configuration dictionary. Initially this is a nearly empty
+            dictionary, but
+
+    Note:
+        This function is called by
+        [`QuamRoot.generate_config`][quam.core.quam_classes.QuamRoot.generate_config].
+
+    Note:
+        The config has a starting template, defined at [`quam.core.qua_config_template`][]
+    """
+    ...
+
+
+
+ +
+ + + +
+ +
+ +
+ +
+ + + +

+ QuamDict + + +

+ + +
+

+ Bases: UserDict, QuamBase

+ + +

A QuAM dictionary class.

+

Any dict added to a QuamBase object is automatically converted to a QuamDict. +The QuamDict adds the following functionalities to a dict: +- Values can be references (see below) +- Keys can also be accessed through attributes (e.g. d.a instead of d["a"])

+

QuamDict references

+

QuamDict values can be references, which are strings that start with #. See the +documentation for details on references. An example is shown here: +

d = QuamDict({"a": 1, "b": "#./a"})
+assert d["b"] == 1
+

+ + +
+ Warning +

This class is a subclass of QuamBase, but also of UserDict. As a result, +it can be used as a normal dictionary, but it is not a subclass of dict.

+
+
+ Source code in quam/core/quam_classes.py + 
724
+725
+726
+727
+728
+729
+730
+731
+732
+733
+734
+735
+736
+737
+738
+739
+740
+741
+742
+743
+744
+745
+746
+747
+748
+749
+750
+751
+752
+753
+754
+755
+756
+757
+758
+759
+760
+761
+762
+763
+764
+765
+766
+767
+768
+769
+770
+771
+772
+773
+774
+775
+776
+777
+778
+779
+780
+781
+782
+783
+784
+785
+786
+787
+788
+789
+790
+791
+792
+793
+794
+795
+796
+797
+798
+799
+800
+801
+802
+803
+804
+805
+806
+807
+808
+809
+810
+811
+812
+813
+814
+815
+816
+817
+818
+819
+820
+821
+822
+823
+824
+825
+826
+827
+828
+829
+830
+831
+832
+833
+834
+835
+836
+837
+838
+839
+840
+841
+842
+843
+844
+845
+846
+847
+848
+849
+850
+851
+852
+853
+854
+855
+856
+857
+858
+859
+860
+861
+862
+863
+864
+865
+866
+867
+868
+869
+870
+871
+872
+873
+874
+875
+876
+877
+878
+879
+880
+881
+882
+883
+884
+885
+886
+887
+888
+889
+890
+891
+892
+893
+894
+895
+896
+897
+898
+899
+900
+901
+902
+903
+904
+905
+906
+907
+908
@quam_dataclass
+class QuamDict(UserDict, QuamBase):
+    """A QuAM dictionary class.
+
+    Any dict added to a `QuamBase` object is automatically converted to a `QuamDict`.
+    The `QuamDict` adds the following functionalities to a dict:
+    - Values can be references (see below)
+    - Keys can also be accessed through attributes (e.g. `d.a` instead of `d["a"]`)
+
+    # QuamDict references
+    QuamDict values can be references, which are strings that start with `#`. See the
+    documentation for details on references. An example is shown here:
+    ```
+    d = QuamDict({"a": 1, "b": "#./a"})
+    assert d["b"] == 1
+    ```
+
+    Warning:
+        This class is a subclass of `QuamBase`, but also of `UserDict`. As a result,
+        it can be used as a normal dictionary, but it is not a subclass of `dict`.
+    """
+
+    _value_annotation: ClassVar[type] = None
+
+    def __init__(self, dict=None, /, value_annotation: type = None, **kwargs):
+        self.__dict__["data"] = {}
+        self.__dict__["_value_annotation"] = value_annotation
+        self.__dict__["_initialized"] = True
+        super().__init__(dict, **kwargs)
+
+    def __getattr__(self, key):
+        try:
+            return self[key]
+        except KeyError as e:
+            try:
+                repr = f"{self.__class__.__name__}: {self.get_reference()}"
+            except Exception:
+                repr = self.__class__.__name__
+            raise AttributeError(f'{repr} has no attribute "{key}"') from e
+
+    def __setattr__(self, key, value):
+        if key in ["data", "parent", "config_settings", "_initialized"]:
+            super().__setattr__(key, value)
+        else:
+            self[key] = value
+
+    def __getitem__(self, i):
+        elem = super().__getitem__(i)
+        if string_reference.is_reference(elem):
+            try:
+                elem = self._get_referenced_value(elem)
+            except ValueError as e:
+                try:
+                    repr = f"{self.__class__.__name__}: {self.get_reference()}"
+                except Exception:
+                    repr = self.__class__.__name__
+                raise KeyError(
+                    f"Could not get referenced value {elem} from {repr}"
+                ) from e
+        return elem
+
+    # Overriding methods from UserDict
+    def __setitem__(self, key, value):
+        value = convert_dict_and_list(value)
+        self._is_valid_setattr(key, value, error_on_False=True)
+        super().__setitem__(key, value)
+
+        if isinstance(value, QuamBase):
+            value.parent = self
+
+    def __eq__(self, other) -> bool:
+        if isinstance(other, dict):
+            return self.data == other
+        return super().__eq__(other)
+
+    def __repr__(self) -> str:
+        with warnings.catch_warnings():
+            warnings.filterwarnings(
+                "ignore",
+                message="^Could not get reference*",
+                category=UserWarning,
+            )
+            return super().__repr__()
+
+    # QuAM methods
+    def _get_attr_names(self):
+        return list(self.data.keys())
+
+    def get_attrs(
+        self, follow_references=False, include_defaults=True
+    ) -> Dict[str, Any]:
+        # TODO implement reference kwargs
+        return self.data
+
+    def get_attr_name(self, attr_val: Any) -> Union[str, int]:
+        """Get the name of an attribute that matches the value.
+
+        Args:
+            attr_val: The value of the attribute.
+
+        Returns:
+            The name of the attribute. This can also be an int depending on the dict key
+
+        Raises:
+            AttributeError if not found.
+        """
+        for attr_name in self._get_attr_names():
+            if attr_name in self and self[attr_name] is attr_val:
+                return attr_name
+        else:
+            raise AttributeError(
+                "Could not find name corresponding to attribute.\n"
+                f"attribute: {attr_val}\n"
+                f"obj: {self}"
+            )
+
+    def _val_matches_attr_annotation(self, attr: str, val: Any) -> bool:
+        """Check whether the type of an attribute matches the annotation.
+
+        Called by [`QuamDict.to_dict`][quam.core.quam_classes.QuamDict.to_dict] to
+        determine whether to add the __class__ key.
+
+        Args:
+            attr: The name of the attribute. Unused but added to match parent signature
+            val: The value of the attribute.
+
+        Note:
+            The attribute val is compared to `QuamDict._value_annotation`, which is set
+            when a dict is converted to a `QuamDict` using `convert_dict_and_list`.
+        """
+        if isinstance(val, (QuamDict, QuamList)):
+            return True
+        if self._value_annotation is None:
+            return False
+        return type(val) == self._value_annotation
+
+    def _attr_val_is_default(self, attr: str, val: Any):
+        """Check whether the value of an attribute is the default value.
+
+        Overrides parent method.
+        Since a QuamDict does not have any fixed attrs, this is always False.
+
+        """
+        return False
+
+    def get_unreferenced_value(self, attr: str) -> bool:
+        """Get the value of an attribute without following references.
+
+        Args:
+            attr: The name of the attribute.
+
+        Returns:
+            The value of the attribute. If the value is a reference, it returns the
+            reference string instead of the value it is referencing.
+        """
+        try:
+            return self.__dict__["data"][attr]
+        except KeyError as e:
+            raise AttributeError(
+                "Cannot get unreferenced value from attribute {attr} that does not"
+                " exist in {self}"
+            ) from e
+
+    def iterate_components(
+        self, skip_elems: Sequence[QuamBase] = None
+    ) -> Generator["QuamBase", None, None]:
+        """Iterate over all QuamBase objects in this object, including nested objects.
+
+        Args:
+            skip_elems: A list of QuamBase objects to skip.
+                This is used to prevent infinite loops when iterating over nested
+                objects.
+
+        Returns:
+            A generator of QuamBase objects.
+        """
+        if skip_elems is None:
+            skip_elems = []
+
+        for attr_val in self.data.values():
+            if any(attr_val is elem for elem in skip_elems):
+                continue
+
+            if isinstance(attr_val, QuamBase):
+                yield from attr_val.iterate_components(skip_elems=skip_elems)
+
+
+ + + +
+ + + + + + + + + +
+ + +

+ get_attr_name(attr_val) + +

+ + +
+ +

Get the name of an attribute that matches the value.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
attr_val + Any + +
+

The value of the attribute.

+
+ 		+ required +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ Union[str, int] + +
+

The name of the attribute. This can also be an int depending on the dict key

+
+
+ +
+ Source code in quam/core/quam_classes.py + 
818
+819
+820
+821
+822
+823
+824
+825
+826
+827
+828
+829
+830
+831
+832
+833
+834
+835
+836
+837
+838
def get_attr_name(self, attr_val: Any) -> Union[str, int]:
+    """Get the name of an attribute that matches the value.
+
+    Args:
+        attr_val: The value of the attribute.
+
+    Returns:
+        The name of the attribute. This can also be an int depending on the dict key
+
+    Raises:
+        AttributeError if not found.
+    """
+    for attr_name in self._get_attr_names():
+        if attr_name in self and self[attr_name] is attr_val:
+            return attr_name
+    else:
+        raise AttributeError(
+            "Could not find name corresponding to attribute.\n"
+            f"attribute: {attr_val}\n"
+            f"obj: {self}"
+        )
+
+
+
+ +
+ +
+ + +

+ get_unreferenced_value(attr) + +

+ + +
+ +

Get the value of an attribute without following references.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
attr + str + +
+

The name of the attribute.

+
+ 		+ required +
+ + +

Returns:

+ + + + + + + + + + + + + + + + + +
TypeDescription
+ bool + +
+

The value of the attribute. If the value is a reference, it returns the

+
+
+ bool + +
+

reference string instead of the value it is referencing.

+
+
+ +
+ Source code in quam/core/quam_classes.py + 
869
+870
+871
+872
+873
+874
+875
+876
+877
+878
+879
+880
+881
+882
+883
+884
+885
def get_unreferenced_value(self, attr: str) -> bool:
+    """Get the value of an attribute without following references.
+
+    Args:
+        attr: The name of the attribute.
+
+    Returns:
+        The value of the attribute. If the value is a reference, it returns the
+        reference string instead of the value it is referencing.
+    """
+    try:
+        return self.__dict__["data"][attr]
+    except KeyError as e:
+        raise AttributeError(
+            "Cannot get unreferenced value from attribute {attr} that does not"
+            " exist in {self}"
+        ) from e
+
+
+
+ +
+ +
+ + +

+ iterate_components(skip_elems=None) + +

+ + +
+ +

Iterate over all QuamBase objects in this object, including nested objects.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
skip_elems + Sequence[QuamBase] + +
+

A list of QuamBase objects to skip. +This is used to prevent infinite loops when iterating over nested +objects.

+
+ 		+ None +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ Generator[QuamBase, None, None] + +
+

A generator of QuamBase objects.

+
+
+ +
+ Source code in quam/core/quam_classes.py + 
887
+888
+889
+890
+891
+892
+893
+894
+895
+896
+897
+898
+899
+900
+901
+902
+903
+904
+905
+906
+907
+908
def iterate_components(
+    self, skip_elems: Sequence[QuamBase] = None
+) -> Generator["QuamBase", None, None]:
+    """Iterate over all QuamBase objects in this object, including nested objects.
+
+    Args:
+        skip_elems: A list of QuamBase objects to skip.
+            This is used to prevent infinite loops when iterating over nested
+            objects.
+
+    Returns:
+        A generator of QuamBase objects.
+    """
+    if skip_elems is None:
+        skip_elems = []
+
+    for attr_val in self.data.values():
+        if any(attr_val is elem for elem in skip_elems):
+            continue
+
+        if isinstance(attr_val, QuamBase):
+            yield from attr_val.iterate_components(skip_elems=skip_elems)
+
+
+
+ +
+ + + +
+ +
+ +
+ +
+ + + +

+ QuamList + + +

+ + +
+

+ Bases: UserList, QuamBase

+ + +

A QuAM list class.

+

Any list added to a QuamBase object is automatically converted to a QuamList. +The QuamList adds the following functionalities to a list: +- Elements can be references (see below)

+

QuamList references

+

QuamList values can be references, which are strings that start with #. See the +documentation for details on references. An example is shown here: +

d = QuamList([1, "#./0"]])
+assert d[1] == 1
+

+ + +
+ Warning +

This class is a subclass of QuamBase, but also of UserList. As a result, +it can be used as a normal list, but it is not a subclass of list.

+
+
+ Source code in quam/core/quam_classes.py + 
 911
+ 912
+ 913
+ 914
+ 915
+ 916
+ 917
+ 918
+ 919
+ 920
+ 921
+ 922
+ 923
+ 924
+ 925
+ 926
+ 927
+ 928
+ 929
+ 930
+ 931
+ 932
+ 933
+ 934
+ 935
+ 936
+ 937
+ 938
+ 939
+ 940
+ 941
+ 942
+ 943
+ 944
+ 945
+ 946
+ 947
+ 948
+ 949
+ 950
+ 951
+ 952
+ 953
+ 954
+ 955
+ 956
+ 957
+ 958
+ 959
+ 960
+ 961
+ 962
+ 963
+ 964
+ 965
+ 966
+ 967
+ 968
+ 969
+ 970
+ 971
+ 972
+ 973
+ 974
+ 975
+ 976
+ 977
+ 978
+ 979
+ 980
+ 981
+ 982
+ 983
+ 984
+ 985
+ 986
+ 987
+ 988
+ 989
+ 990
+ 991
+ 992
+ 993
+ 994
+ 995
+ 996
+ 997
+ 998
+ 999
+1000
+1001
+1002
+1003
+1004
+1005
+1006
+1007
+1008
+1009
+1010
+1011
+1012
+1013
+1014
+1015
+1016
+1017
+1018
+1019
+1020
+1021
+1022
+1023
+1024
+1025
+1026
+1027
+1028
+1029
+1030
+1031
+1032
+1033
+1034
+1035
+1036
+1037
+1038
+1039
+1040
+1041
+1042
+1043
+1044
+1045
+1046
+1047
+1048
+1049
+1050
+1051
+1052
+1053
+1054
+1055
+1056
+1057
+1058
+1059
+1060
+1061
+1062
+1063
+1064
+1065
+1066
+1067
+1068
+1069
+1070
+1071
+1072
+1073
+1074
+1075
+1076
+1077
+1078
+1079
+1080
+1081
+1082
+1083
+1084
+1085
+1086
+1087
+1088
+1089
+1090
+1091
+1092
+1093
+1094
+1095
+1096
+1097
+1098
+1099
+1100
+1101
+1102
+1103
+1104
+1105
+1106
+1107
+1108
+1109
+1110
+1111
+1112
+1113
+1114
+1115
+1116
+1117
@quam_dataclass
+class QuamList(UserList, QuamBase):
+    """A QuAM list class.
+
+    Any list added to a `QuamBase` object is automatically converted to a `QuamList`.
+    The `QuamList` adds the following functionalities to a list:
+    - Elements can be references (see below)
+
+    # QuamList references
+    QuamList values can be references, which are strings that start with `#`. See the
+    documentation for details on references. An example is shown here:
+    ```
+    d = QuamList([1, "#./0"]])
+    assert d[1] == 1
+    ```
+
+    Warning:
+        This class is a subclass of `QuamBase`, but also of `UserList`. As a result,
+        it can be used as a normal list, but it is not a subclass of `list`.
+    """
+
+    _value_annotation: ClassVar[type] = None
+
+    def __init__(self, *args, value_annotation: type = None):
+        self._value_annotation = value_annotation
+
+        # We manually add elements using extend instead of passing to super()
+        # To ensure that any dicts and lists get converted to QuamDict and QuamList
+        super().__init__()
+        if args:
+            self.extend(*args)
+
+    # Overloading methods from UserList
+    def __eq__(self, value: object) -> bool:
+        return super().__eq__(value)
+
+    def __repr__(self) -> str:
+        with warnings.catch_warnings():
+            warnings.filterwarnings(
+                "ignore",
+                message="^Could not get reference*",
+                category=UserWarning,
+            )
+            return super().__repr__()
+
+    def __getitem__(self, i):
+        elem = super().__getitem__(i)
+        if isinstance(i, slice):
+            # This automatically gets the referenced values
+            return list(elem)
+
+        if string_reference.is_reference(elem):
+            elem = self._get_referenced_value(elem)
+        return elem
+
+    def __setitem__(self, i, item):
+        converted_item = convert_dict_and_list(item)
+        super().__setitem__(i, converted_item)
+
+        if isinstance(converted_item, QuamBase):
+            converted_item.parent = self
+
+    def __iadd__(self, other: Iterable):
+        converted_other = [convert_dict_and_list(elem) for elem in other]
+        return super().__iadd__(converted_other)
+
+    def append(self, item: Any) -> None:
+        converted_item = convert_dict_and_list(item)
+
+        if isinstance(converted_item, QuamBase):
+            converted_item.parent = self
+
+        return super().append(converted_item)
+
+    def insert(self, i: int, item: Any) -> None:
+        converted_item = convert_dict_and_list(item)
+
+        if isinstance(converted_item, QuamBase):
+            converted_item.parent = self
+
+        return super().insert(i, converted_item)
+
+    def extend(self, iterable: Iterator) -> None:
+        converted_iterable = [convert_dict_and_list(elem) for elem in iterable]
+        for converted_item in converted_iterable:
+            if isinstance(converted_item, QuamBase):
+                converted_item.parent = self
+
+        return super().extend(converted_iterable)
+
+    # Quam methods
+    def _val_matches_attr_annotation(self, attr: str, val: Any) -> bool:
+        """Check whether the type of an attribute matches the annotation.
+
+        Called by QuamList.to_dict to determine whether to add the __class__ key.
+        For the QuamList, we compare the type to the _value_annotation.
+        """
+        if isinstance(val, (QuamDict, QuamList)):
+            return True
+        if self._value_annotation is None:
+            return False
+        return type(val) == self._value_annotation
+
+    def get_attr_name(self, attr_val: Any) -> str:
+        for k, elem in enumerate(self.data):
+            if elem is attr_val:
+                return str(k)
+        else:
+            raise AttributeError(
+                "Could not find name corresponding to attribute"
+                f"attribute: {attr_val}\n"
+                f"obj: {self}"
+            )
+
+    def to_dict(
+        self, follow_references: bool = False, include_defaults: bool = False
+    ) -> list:
+        """Convert this object to a list, usually as part of a dictionary representation.
+
+        Args:
+            follow_references: Whether to follow references when getting the value.
+                If False, the reference will be returned as a string.
+            include_defaults: Whether to include attributes that have the default
+                value.
+
+        Returns:
+            A list with the values of this object. Any QuamBase objects will be
+            recursively converted to dictionaries.
+
+        Note:
+            If the value of an attribute does not match the annotation of
+            `QuamList._value_annotation`, the `"__class__"` key will be added to the
+            dictionary. This is to ensure that the object can be reconstructed when
+            loading from a file.
+        """
+        quam_list = []
+        for val in self.data:
+            if isinstance(val, QuamBase):
+                quam_list.append(
+                    val.to_dict(
+                        follow_references=follow_references,
+                        include_defaults=include_defaults,
+                    )
+                )
+                if not self._val_matches_attr_annotation(val=val, attr=None):
+                    quam_list[-1]["__class__"] = get_full_class_path(val)
+            else:
+                quam_list.append(val)
+        return quam_list
+
+    def iterate_components(
+        self, skip_elems: List[QuamBase] = None
+    ) -> Generator["QuamBase", None, None]:
+        """Iterate over all QuamBase objects in this object, including nested objects.
+
+        Args:
+            skip_elems: A list of QuamBase objects to skip.
+                This is used to prevent infinite loops when iterating over nested
+                objects.
+
+        Returns:
+            A generator of QuamBase objects.
+        """
+        if skip_elems is None:
+            skip_elems = []
+
+        for attr_val in self.data:
+            if any(attr_val is elem for elem in skip_elems):
+                continue
+
+            if isinstance(attr_val, QuamBase):
+                yield from attr_val.iterate_components(skip_elems=skip_elems)
+
+    def get_attrs(
+        self, follow_references: bool = False, include_defaults: bool = True
+    ) -> Dict[str, Any]:
+        raise NotImplementedError("QuamList does not have attributes")
+
+    def print_summary(self, indent: int = 0):
+        """Print a summary of the QuamBase object.
+
+        Args:
+            indent: The number of spaces to indent the summary.
+        """
+
+        if self.parent is None:
+            full_name = f"{self.__class__.__name__} (parent unknown):"
+        else:
+            try:
+                attr_name = self.parent.get_attr_name(self)
+                full_name = f"{attr_name}: {self.__class__.__name__}"
+            except AttributeError:
+                full_name = f"{self.__class__.__name__}:"
+
+        if not self.data:
+            print(" " * indent + f"{full_name} = []")
+            return
+
+        print(" " * indent + f"{full_name}:")
+        if len(str(self.data)) + 2 * indent < 80:
+            print(" " * (indent + 2) + f"{self.data}")
+        else:
+            for k, val in enumerate(self.data):
+                if isinstance(val, QuamBase):
+                    val.print_summary(indent=indent + 2)
+                else:
+                    print(" " * (indent + 2) + f"{k}: {val}")
+
+
+ + + +
+ + + + + + + + + +
+ + +

+ iterate_components(skip_elems=None) + +

+ + +
+ +

Iterate over all QuamBase objects in this object, including nested objects.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
skip_elems + List[QuamBase] + +
+

A list of QuamBase objects to skip. +This is used to prevent infinite loops when iterating over nested +objects.

+
+ 		+ None +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ Generator[QuamBase, None, None] + +
+

A generator of QuamBase objects.

+
+
+ +
+ Source code in quam/core/quam_classes.py + 
1061
+1062
+1063
+1064
+1065
+1066
+1067
+1068
+1069
+1070
+1071
+1072
+1073
+1074
+1075
+1076
+1077
+1078
+1079
+1080
+1081
+1082
def iterate_components(
+    self, skip_elems: List[QuamBase] = None
+) -> Generator["QuamBase", None, None]:
+    """Iterate over all QuamBase objects in this object, including nested objects.
+
+    Args:
+        skip_elems: A list of QuamBase objects to skip.
+            This is used to prevent infinite loops when iterating over nested
+            objects.
+
+    Returns:
+        A generator of QuamBase objects.
+    """
+    if skip_elems is None:
+        skip_elems = []
+
+    for attr_val in self.data:
+        if any(attr_val is elem for elem in skip_elems):
+            continue
+
+        if isinstance(attr_val, QuamBase):
+            yield from attr_val.iterate_components(skip_elems=skip_elems)
+
+
+
+ +
+ +
+ + +

+ print_summary(indent=0) + +

+ + +
+ +

Print a summary of the QuamBase object.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
indent + int + +
+

The number of spaces to indent the summary.

+
+ 		+ 0 +
+ +
+ Source code in quam/core/quam_classes.py + 
1089
+1090
+1091
+1092
+1093
+1094
+1095
+1096
+1097
+1098
+1099
+1100
+1101
+1102
+1103
+1104
+1105
+1106
+1107
+1108
+1109
+1110
+1111
+1112
+1113
+1114
+1115
+1116
+1117
def print_summary(self, indent: int = 0):
+    """Print a summary of the QuamBase object.
+
+    Args:
+        indent: The number of spaces to indent the summary.
+    """
+
+    if self.parent is None:
+        full_name = f"{self.__class__.__name__} (parent unknown):"
+    else:
+        try:
+            attr_name = self.parent.get_attr_name(self)
+            full_name = f"{attr_name}: {self.__class__.__name__}"
+        except AttributeError:
+            full_name = f"{self.__class__.__name__}:"
+
+    if not self.data:
+        print(" " * indent + f"{full_name} = []")
+        return
+
+    print(" " * indent + f"{full_name}:")
+    if len(str(self.data)) + 2 * indent < 80:
+        print(" " * (indent + 2) + f"{self.data}")
+    else:
+        for k, val in enumerate(self.data):
+            if isinstance(val, QuamBase):
+                val.print_summary(indent=indent + 2)
+            else:
+                print(" " * (indent + 2) + f"{k}: {val}")
+
+
+
+ +
+ +
+ + +

+ to_dict(follow_references=False, include_defaults=False) + +

+ + +
+ +

Convert this object to a list, usually as part of a dictionary representation.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
follow_references + bool + +
+

Whether to follow references when getting the value. +If False, the reference will be returned as a string.

+
+ 		+ False +
include_defaults + bool + +
+

Whether to include attributes that have the default +value.

+
+ 		+ False +
+ + +

Returns:

+ + + + + + + + + + + + + + + + + +
TypeDescription
+ list + +
+

A list with the values of this object. Any QuamBase objects will be

+
+
+ list + +
+

recursively converted to dictionaries.

+
+
+ + +
+ Note +

If the value of an attribute does not match the annotation of +QuamList._value_annotation, the "__class__" key will be added to the +dictionary. This is to ensure that the object can be reconstructed when +loading from a file.

+
+
+ Source code in quam/core/quam_classes.py + 
1025
+1026
+1027
+1028
+1029
+1030
+1031
+1032
+1033
+1034
+1035
+1036
+1037
+1038
+1039
+1040
+1041
+1042
+1043
+1044
+1045
+1046
+1047
+1048
+1049
+1050
+1051
+1052
+1053
+1054
+1055
+1056
+1057
+1058
+1059
def to_dict(
+    self, follow_references: bool = False, include_defaults: bool = False
+) -> list:
+    """Convert this object to a list, usually as part of a dictionary representation.
+
+    Args:
+        follow_references: Whether to follow references when getting the value.
+            If False, the reference will be returned as a string.
+        include_defaults: Whether to include attributes that have the default
+            value.
+
+    Returns:
+        A list with the values of this object. Any QuamBase objects will be
+        recursively converted to dictionaries.
+
+    Note:
+        If the value of an attribute does not match the annotation of
+        `QuamList._value_annotation`, the `"__class__"` key will be added to the
+        dictionary. This is to ensure that the object can be reconstructed when
+        loading from a file.
+    """
+    quam_list = []
+    for val in self.data:
+        if isinstance(val, QuamBase):
+            quam_list.append(
+                val.to_dict(
+                    follow_references=follow_references,
+                    include_defaults=include_defaults,
+                )
+            )
+            if not self._val_matches_attr_annotation(val=val, attr=None):
+                quam_list[-1]["__class__"] = get_full_class_path(val)
+        else:
+            quam_list.append(val)
+    return quam_list
+
+
+
+ +
+ + + +
+ +
+ +
+ +
+ + + +

+ QuamRoot + + +

+ + +
+

+ Bases: QuamBase

+ + +

Base class for the root of a QuAM object.

+

This class should be subclassed and made a dataclass.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
serialiser + +
+

The serialiser class to use for saving and loading. +The default is to use the JSONSerialiser, but this can be changed.

+
+ 		+ required +
+ + +
+ Note +

This class should not be used directly, but should generally be subclassed and +made a dataclass. The dataclass fields should correspond to the QuAM root +structure.

+
+ +
+ Note +

Upon instantiating a QuamRoot object, it sets the class attribute +QuamBase._root to itself. This is used such that any references with an +absolute path are resolved from the root.

+
+
+ Source code in quam/core/quam_classes.py + 
550
+551
+552
+553
+554
+555
+556
+557
+558
+559
+560
+561
+562
+563
+564
+565
+566
+567
+568
+569
+570
+571
+572
+573
+574
+575
+576
+577
+578
+579
+580
+581
+582
+583
+584
+585
+586
+587
+588
+589
+590
+591
+592
+593
+594
+595
+596
+597
+598
+599
+600
+601
+602
+603
+604
+605
+606
+607
+608
+609
+610
+611
+612
+613
+614
+615
+616
+617
+618
+619
+620
+621
+622
+623
+624
+625
+626
+627
+628
+629
+630
+631
+632
+633
+634
+635
+636
+637
+638
+639
+640
+641
+642
+643
+644
+645
+646
+647
+648
+649
+650
+651
+652
+653
+654
+655
+656
+657
+658
+659
+660
+661
+662
+663
+664
+665
+666
+667
+668
+669
+670
+671
+672
+673
+674
+675
+676
+677
+678
+679
+680
+681
+682
+683
+684
+685
+686
class QuamRoot(QuamBase):
+    """Base class for the root of a QuAM object.
+
+    This class should be subclassed and made a dataclass.
+
+    Args:
+        serialiser: The serialiser class to use for saving and loading.
+            The default is to use the `JSONSerialiser`, but this can be changed.
+
+    Note:
+        This class should not be used directly, but should generally be subclassed and
+        made a dataclass. The dataclass fields should correspond to the QuAM root
+        structure.
+
+    Note:
+        Upon instantiating a `QuamRoot` object, it sets the class attribute
+        `QuamBase._root` to itself. This is used such that any references with an
+        absolute path are resolved from the root.
+    """
+
+    serialiser: AbstractSerialiser = JSONSerialiser
+
+    def __post_init__(self):
+        QuamBase._root = self
+        super().__post_init__()
+
+    def __setattr__(self, name, value):
+        converted_val = convert_dict_and_list(value, cls_or_obj=self, attr=name)
+        super().__setattr__(name, converted_val)
+
+        if isinstance(converted_val, QuamBase) and name != "parent":
+            converted_val.parent = self
+
+    def get_reference(self):
+        return "#"
+
+    def save(
+        self,
+        path: Union[Path, str] = None,
+        content_mapping: Dict[str, str] = None,
+        include_defaults: bool = False,
+        ignore: Sequence[str] = None,
+    ):
+        """Save the entire QuamRoot object to a file. This includes nested objects.
+
+        Args:
+            path: The path to save the file to. If None, the path will be saved to
+                `state.json`.
+            content_mapping: A dictionary of paths to save to and a list of attributes
+                to save to that path. This can be used to save different parts of the
+                QuamRoot object to different files.
+            include_defaults: Whether to include attributes that have the default
+                value.
+            ignore: A list of attributes to ignore.
+        """
+        serialiser = self.serialiser()
+        serialiser.save(
+            quam_obj=self,
+            path=path,
+            content_mapping=content_mapping,
+            include_defaults=include_defaults,
+            ignore=ignore,
+        )
+
+    def to_dict(
+        self, follow_references: bool = False, include_defaults: bool = False
+    ) -> Dict[str, Any]:
+        """Convert this object to a dictionary.
+
+        Args:
+            follow_references: Whether to follow references when getting the value.
+                If False, the reference will be returned as a string.
+            include_defaults: Whether to include attributes that have the default
+                value.
+        """
+        quam_dict = super().to_dict(follow_references, include_defaults)
+        # QuamRoot should always add __class__ because it is generally not
+        # quam.components.quam.QuAM
+        quam_dict["__class__"] = get_full_class_path(self)
+        return quam_dict
+
+    @classmethod
+    def load(
+        cls: QuamRootType,
+        filepath_or_dict: Union[str, Path, dict],
+        validate_type: bool = True,
+        fix_attrs: bool = True,
+    ) -> QuamRootType:
+        """Load a QuamRoot object from a file.
+
+        Args:
+            filepath_or_dict: The path to the file/folder to load, or a dictionary.
+                The dictionary would be the result from a call to `QuamRoot.save()`
+            validate_type: Whether to validate the type of all attributes while loading.
+            fix_attrs: Whether attributes can be added to QuamBase objects that are not
+                defined as dataclass fields.
+
+        Returns:
+            A QuamRoot object instantiated from the file/folder/dict.
+        """
+        if isinstance(filepath_or_dict, dict):
+            contents = filepath_or_dict
+        else:
+            serialiser = cls.serialiser()
+            contents, _ = serialiser.load(filepath_or_dict)
+
+        return instantiate_quam_class(
+            quam_class=cls,
+            contents=contents,
+            fix_attrs=fix_attrs,
+            validate_type=validate_type,
+        )
+
+    def generate_config(self) -> Dict[str, Any]:
+        """Generate the QUA configuration from the QuAM object.
+
+        Returns:
+            A dictionary with the QUA configuration.
+
+        Note:
+            This function collects all the nested QuamComponent objects and calls
+            `QuamComponent.apply_to_config` on them.
+        """
+        qua_config = deepcopy(qua_config_template)
+
+        quam_components = list(self.iterate_components())
+        sorted_components = sort_quam_components(quam_components)
+
+        for quam_component in sorted_components:
+            quam_component.apply_to_config(qua_config)
+
+        generate_config_final_actions(qua_config)
+
+        return qua_config
+
+    def get_unreferenced_value(self, attr: str):
+        return getattr(self, attr)
+
+
+ + + +
+ + + + + + + + + +
+ + +

+ generate_config() + +

+ + +
+ +

Generate the QUA configuration from the QuAM object.

+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ Dict[str, Any] + +
+

A dictionary with the QUA configuration.

+
+
+ + +
+ Note +

This function collects all the nested QuamComponent objects and calls +QuamComponent.apply_to_config on them.

+
+
+ Source code in quam/core/quam_classes.py + 
663
+664
+665
+666
+667
+668
+669
+670
+671
+672
+673
+674
+675
+676
+677
+678
+679
+680
+681
+682
+683
def generate_config(self) -> Dict[str, Any]:
+    """Generate the QUA configuration from the QuAM object.
+
+    Returns:
+        A dictionary with the QUA configuration.
+
+    Note:
+        This function collects all the nested QuamComponent objects and calls
+        `QuamComponent.apply_to_config` on them.
+    """
+    qua_config = deepcopy(qua_config_template)
+
+    quam_components = list(self.iterate_components())
+    sorted_components = sort_quam_components(quam_components)
+
+    for quam_component in sorted_components:
+        quam_component.apply_to_config(qua_config)
+
+    generate_config_final_actions(qua_config)
+
+    return qua_config
+
+
+
+ +
+ +
+ + +

+ load(filepath_or_dict, validate_type=True, fix_attrs=True) + + + classmethod + + +

+ + +
+ +

Load a QuamRoot object from a file.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
filepath_or_dict + Union[str, Path, dict] + +
+

The path to the file/folder to load, or a dictionary. +The dictionary would be the result from a call to QuamRoot.save()

+
+ 		+ required +
validate_type + bool + +
+

Whether to validate the type of all attributes while loading.

+
+ 		+ True +
fix_attrs + bool + +
+

Whether attributes can be added to QuamBase objects that are not +defined as dataclass fields.

+
+ 		+ True +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ QuamRootType + +
+

A QuamRoot object instantiated from the file/folder/dict.

+
+
+ +
+ Source code in quam/core/quam_classes.py + 
631
+632
+633
+634
+635
+636
+637
+638
+639
+640
+641
+642
+643
+644
+645
+646
+647
+648
+649
+650
+651
+652
+653
+654
+655
+656
+657
+658
+659
+660
+661
@classmethod
+def load(
+    cls: QuamRootType,
+    filepath_or_dict: Union[str, Path, dict],
+    validate_type: bool = True,
+    fix_attrs: bool = True,
+) -> QuamRootType:
+    """Load a QuamRoot object from a file.
+
+    Args:
+        filepath_or_dict: The path to the file/folder to load, or a dictionary.
+            The dictionary would be the result from a call to `QuamRoot.save()`
+        validate_type: Whether to validate the type of all attributes while loading.
+        fix_attrs: Whether attributes can be added to QuamBase objects that are not
+            defined as dataclass fields.
+
+    Returns:
+        A QuamRoot object instantiated from the file/folder/dict.
+    """
+    if isinstance(filepath_or_dict, dict):
+        contents = filepath_or_dict
+    else:
+        serialiser = cls.serialiser()
+        contents, _ = serialiser.load(filepath_or_dict)
+
+    return instantiate_quam_class(
+        quam_class=cls,
+        contents=contents,
+        fix_attrs=fix_attrs,
+        validate_type=validate_type,
+    )
+
+
+
+ +
+ +
+ + +

+ save(path=None, content_mapping=None, include_defaults=False, ignore=None) + +

+ + +
+ +

Save the entire QuamRoot object to a file. This includes nested objects.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
path + Union[Path, str] + +
+

The path to save the file to. If None, the path will be saved to +state.json.

+
+ 		+ None +
content_mapping + Dict[str, str] + +
+

A dictionary of paths to save to and a list of attributes +to save to that path. This can be used to save different parts of the +QuamRoot object to different files.

+
+ 		+ None +
include_defaults + bool + +
+

Whether to include attributes that have the default +value.

+
+ 		+ False +
ignore + Sequence[str] + +
+

A list of attributes to ignore.

+
+ 		+ None +
+ +
+ Source code in quam/core/quam_classes.py + 
586
+587
+588
+589
+590
+591
+592
+593
+594
+595
+596
+597
+598
+599
+600
+601
+602
+603
+604
+605
+606
+607
+608
+609
+610
+611
+612
def save(
+    self,
+    path: Union[Path, str] = None,
+    content_mapping: Dict[str, str] = None,
+    include_defaults: bool = False,
+    ignore: Sequence[str] = None,
+):
+    """Save the entire QuamRoot object to a file. This includes nested objects.
+
+    Args:
+        path: The path to save the file to. If None, the path will be saved to
+            `state.json`.
+        content_mapping: A dictionary of paths to save to and a list of attributes
+            to save to that path. This can be used to save different parts of the
+            QuamRoot object to different files.
+        include_defaults: Whether to include attributes that have the default
+            value.
+        ignore: A list of attributes to ignore.
+    """
+    serialiser = self.serialiser()
+    serialiser.save(
+        quam_obj=self,
+        path=path,
+        content_mapping=content_mapping,
+        include_defaults=include_defaults,
+        ignore=ignore,
+    )
+
+
+
+ +
+ +
+ + +

+ to_dict(follow_references=False, include_defaults=False) + +

+ + +
+ +

Convert this object to a dictionary.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
follow_references + bool + +
+

Whether to follow references when getting the value. +If False, the reference will be returned as a string.

+
+ 		+ False +
include_defaults + bool + +
+

Whether to include attributes that have the default +value.

+
+ 		+ False +
+ +
+ Source code in quam/core/quam_classes.py + 
614
+615
+616
+617
+618
+619
+620
+621
+622
+623
+624
+625
+626
+627
+628
+629
def to_dict(
+    self, follow_references: bool = False, include_defaults: bool = False
+) -> Dict[str, Any]:
+    """Convert this object to a dictionary.
+
+    Args:
+        follow_references: Whether to follow references when getting the value.
+            If False, the reference will be returned as a string.
+        include_defaults: Whether to include attributes that have the default
+            value.
+    """
+    quam_dict = super().to_dict(follow_references, include_defaults)
+    # QuamRoot should always add __class__ because it is generally not
+    # quam.components.quam.QuAM
+    quam_dict["__class__"] = get_full_class_path(self)
+    return quam_dict
+
+
+
+ +
+ + + +
+ +
+ +
+ + +
+ + +

+ convert_dict_and_list(value, cls_or_obj=None, attr=None) + +

+ + +
+ +

Convert a dict or list to a QuamDict or QuamList if possible.

+ +
+ Source code in quam/core/quam_classes.py + 
72
+73
+74
+75
+76
+77
+78
+79
+80
+81
def convert_dict_and_list(value, cls_or_obj=None, attr=None):
+    """Convert a dict or list to a QuamDict or QuamList if possible."""
+    if isinstance(value, dict):
+        value_annotation = _get_value_annotation(cls_or_obj=cls_or_obj, attr=attr)
+        return QuamDict(value, value_annotation=value_annotation)
+    elif type(value) == list:
+        value_annotation = _get_value_annotation(cls_or_obj=cls_or_obj, attr=attr)
+        return QuamList(value, value_annotation=value_annotation)
+    else:
+        return value
+
+
+
+ +
+ +
+ + +

+ sort_quam_components(components, max_attempts=5) + +

+ + +
+ +

Sort QuamComponent objects based on their config_settings.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
components + List[QuamComponent] + +
+

A list of QuamComponent objects.

+
+ 		+ required +
max_attempts + +
+

The maximum number of attempts to sort the components. +If the components aren't yet properly sorted after all these attempts, +a warning is raised and the components are returned in the final attempted +ordering.

+
+ 		+ 5 +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ List[QuamComponent] + +
+

A sorted list of QuamComponent objects.

+
+
+ + +
+ Note +

This function is used by +QuamRoot.generate_config +to determine the order in which to add the components to the QUA config. +This sorting isn't guaranteed to be successful.

+
+
+ Source code in quam/core/quam_classes.py + 
 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
def sort_quam_components(
+    components: List["QuamComponent"], max_attempts=5
+) -> List["QuamComponent"]:
+    """Sort QuamComponent objects based on their config_settings.
+
+    Args:
+        components: A list of QuamComponent objects.
+        max_attempts: The maximum number of attempts to sort the components.
+            If the components aren't yet properly sorted after all these attempts,
+            a warning is raised and the components are returned in the final attempted
+            ordering.
+
+    Returns:
+        A sorted list of QuamComponent objects.
+
+    Note:
+        This function is used by
+        [`QuamRoot.generate_config`][quam.core.quam_classes.QuamRoot.generate_config]
+        to determine the order in which to add the components to the QUA config.
+        This sorting isn't guaranteed to be successful.
+    """
+    sorted_components = components.copy()
+    for _ in range(max_attempts):
+        adjustments_made = False
+
+        for component in components:
+            if component.config_settings is None:
+                continue
+
+            component_idx = sorted_components.index(component)
+
+            if "after" in component.config_settings:
+                for after_component in component.config_settings["after"]:
+                    after_component_idx = sorted_components.index(after_component)
+                    if after_component_idx < component_idx:
+                        continue
+                    sorted_components.remove(after_component)
+                    sorted_components.insert(component_idx, after_component)
+                    adjustments_made = True
+
+            if "before" in component.config_settings:
+                for before_component in component.config_settings["before"]:
+                    before_component_idx = sorted_components.index(before_component)
+                    if before_component_idx > component_idx:
+                        continue
+                    sorted_components.remove(before_component)
+                    sorted_components.insert(component_idx + 1, before_component)
+                    adjustments_made = True
+
+        if not adjustments_made:
+            break
+    else:
+        warnings.warn(
+            "Unable to sort QuamComponents based on config_settings. "
+            "This may cause issues when generating the QUA config."
+        )
+
+    return sorted_components
+
+
+
+ +
+ + + +
+ +
+ +
+ + + + + + + + + + + + + +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API_references/core/quam_classes_API/index.html b/API_references/core/quam_classes_API/index.html new file mode 100644 index 00000000..983fae82 --- /dev/null +++ b/API_references/core/quam_classes_API/index.html @@ -0,0 +1,5475 @@ + + + + + + + + + + + + + + + + + + + + + + + QuAM Core Classes API - The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ + + + +

QuAM Classes API

+ + +
+ + + + +
+ + + +
+ + + + + + + + +
+ + + +

+ QuamBase + + +

+ + +
+

+ Bases: ReferenceClass

+ + +

Base class for any QuAM component class.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
parent + +
+

The parent of this object. This is automatically set when adding +this object to another QuamBase object.

+
+ 		+ required +
_root + +
+

The QuamRoot object. This is automatically set when instantiating +a QuamRoot object.

+
+ 		+ required +
config_settings + +
+

A dictionary of configuration settings for this object. +This is used by QuamRoot.generate_config +to determine the order in which to add the components to the QUA config. +Keys are "before" and "after", and the values are a list of QuamComponents

+
+ 		+ required +
+ + +
+ Note +

This class should not be used directly, but should generally be subclassed. +The subclasses should be dataclasses.

+
+
+ Source code in quam/core/quam_classes.py + 
222
+223
+224
+225
+226
+227
+228
+229
+230
+231
+232
+233
+234
+235
+236
+237
+238
+239
+240
+241
+242
+243
+244
+245
+246
+247
+248
+249
+250
+251
+252
+253
+254
+255
+256
+257
+258
+259
+260
+261
+262
+263
+264
+265
+266
+267
+268
+269
+270
+271
+272
+273
+274
+275
+276
+277
+278
+279
+280
+281
+282
+283
+284
+285
+286
+287
+288
+289
+290
+291
+292
+293
+294
+295
+296
+297
+298
+299
+300
+301
+302
+303
+304
+305
+306
+307
+308
+309
+310
+311
+312
+313
+314
+315
+316
+317
+318
+319
+320
+321
+322
+323
+324
+325
+326
+327
+328
+329
+330
+331
+332
+333
+334
+335
+336
+337
+338
+339
+340
+341
+342
+343
+344
+345
+346
+347
+348
+349
+350
+351
+352
+353
+354
+355
+356
+357
+358
+359
+360
+361
+362
+363
+364
+365
+366
+367
+368
+369
+370
+371
+372
+373
+374
+375
+376
+377
+378
+379
+380
+381
+382
+383
+384
+385
+386
+387
+388
+389
+390
+391
+392
+393
+394
+395
+396
+397
+398
+399
+400
+401
+402
+403
+404
+405
+406
+407
+408
+409
+410
+411
+412
+413
+414
+415
+416
+417
+418
+419
+420
+421
+422
+423
+424
+425
+426
+427
+428
+429
+430
+431
+432
+433
+434
+435
+436
+437
+438
+439
+440
+441
+442
+443
+444
+445
+446
+447
+448
+449
+450
+451
+452
+453
+454
+455
+456
+457
+458
+459
+460
+461
+462
+463
+464
+465
+466
+467
+468
+469
+470
+471
+472
+473
+474
+475
+476
+477
+478
+479
+480
+481
+482
+483
+484
+485
+486
+487
+488
+489
+490
+491
+492
+493
+494
+495
+496
+497
+498
+499
+500
+501
+502
+503
+504
+505
+506
+507
+508
+509
+510
+511
+512
+513
+514
+515
+516
+517
+518
+519
+520
+521
+522
+523
+524
+525
+526
+527
+528
+529
+530
+531
+532
+533
+534
+535
+536
+537
+538
+539
+540
+541
+542
+543
class QuamBase(ReferenceClass):
+    """Base class for any QuAM component class.
+
+    args:
+        parent: The parent of this object. This is automatically set when adding
+            this object to another QuamBase object.
+        _root: The QuamRoot object. This is automatically set when instantiating
+            a QuamRoot object.
+        config_settings: A dictionary of configuration settings for this object.
+            This is used by [`QuamRoot.generate_config`][quam.core.quam_classes.QuamRoot.generate_config]
+            to determine the order in which to add the components to the QUA config.
+            Keys are "before" and "after", and the values are a list of QuamComponents
+
+    Note:
+        This class should not be used directly, but should generally be subclassed.
+        The subclasses should be dataclasses.
+    """
+
+    parent: ClassVar["QuamBase"] = ParentDescriptor()
+    _root: ClassVar["QuamRoot"] = None
+
+    config_settings: ClassVar[Dict[str, Any]] = None
+
+    def __init__(self):
+        # This prohibits instantiating without it being a dataclass
+        # This means that we have to subclass this class and make it a dataclass
+        if not is_dataclass(self):
+            if type(self) in [QuamBase, QuamComponent, QuamRoot]:
+                raise TypeError(
+                    f"Cannot instantiate {self.__class__.__name__} directly. "
+                    "Please create a subclass and make it a dataclass."
+                )
+            else:
+                raise TypeError(
+                    f"Cannot instantiate {self.__class__.__name__}. "
+                    "Please make it a dataclass."
+                )
+
+    def _get_attr_names(self) -> List[str]:
+        """Get names of all dataclass attributes of this object.
+
+        Returns:
+            List of attribute names.
+
+        Raises:
+            AssertionError if not a dataclass.
+        """
+        assert is_dataclass(self)
+        return [data_field.name for data_field in fields(self)]
+
+    def get_attr_name(self, attr_val: Any) -> str:
+        """Get the name of an attribute that matches the value.
+
+        Args:
+            attr_val: The value of the attribute.
+
+        Returns:
+            The name of the attribute.
+
+        Raises:
+            AttributeError if not found.
+        """
+        for attr_name in self._get_attr_names():
+            if getattr(self, attr_name) is attr_val:
+                return attr_name
+        else:
+            raise AttributeError(
+                "Could not find name corresponding to attribute.\n"
+                f"attribute: {attr_val}\n"
+                f"obj: {self}"
+            )
+
+    def _attr_val_is_default(self, attr: str, val: Any) -> bool:
+        """Check whether the value of an attribute is the default value.
+
+        Args:
+            attr: The name of the attribute.
+            val: The value of the attribute.
+
+        Returns:
+            True if the value is the default value, False otherwise.
+            False is also returned if the parent is not a dataclass
+        """
+        if not is_dataclass(self):
+            return False
+
+        dataclass_fields = fields(self)
+        if not any(field.name == attr for field in dataclass_fields):
+            return False
+
+        field = next(field for field in dataclass_fields if field.name == attr)
+        if field.default is not MISSING:
+            return val == field.default
+        elif field.default_factory is not MISSING:
+            try:
+                default_val = field.default_factory()
+                return val == default_val
+            except TypeError:
+                return False
+
+        return False
+
+    @classmethod
+    def _val_matches_attr_annotation(cls, attr: str, val: Any) -> bool:
+        """Check whether the type of an attribute matches the annotation.
+
+        The attribute type must exactly match the annotation.
+        For dict and list, no additional type check of args is performed.
+        """
+        annotated_attrs = get_dataclass_attr_annotations(cls)
+        if attr not in annotated_attrs["allowed"]:
+            return False
+
+        required_type = annotated_attrs["allowed"][attr]
+        if type_is_optional(required_type):
+            required_type = get_args(required_type)[0]
+
+        if required_type == dict or get_origin(required_type) == dict:
+            return isinstance(val, (dict, QuamDict))
+        elif required_type == list or get_origin(required_type) == list:
+            return isinstance(val, (list, QuamList))
+        return type(val) == required_type
+
+    def get_reference(self, attr=None) -> Optional[str]:
+        """Get the reference path of this object.
+
+        Args:
+            attr: The attribute to get the reference path for. If None, the reference
+                path of the object itself is returned.
+
+        Returns:
+            The reference path of this object.
+        """
+
+        if self.parent is None:
+            raise AttributeError(
+                "Unable to extract reference path. Parent must be defined for {self}"
+            )
+        reference = f"{self.parent.get_reference()}/{self.parent.get_attr_name(self)}"
+        if attr is not None:
+            reference = f"{reference}/{attr}"
+        return reference
+
+    def get_attrs(
+        self, follow_references: bool = False, include_defaults: bool = True
+    ) -> Dict[str, Any]:
+        """Get all attributes and corresponding values of this object.
+
+        Args:
+            follow_references: Whether to follow references when getting the value.
+                If False, the reference will be returned as a string.
+            include_defaults: Whether to include attributes that have the default
+                value.
+
+        Returns:
+            A dictionary of attribute names and values.
+
+        """
+        attr_names = self._get_attr_names()
+
+        skip_attrs = getattr(self, "_skip_attrs", [])
+        attr_names = [attr for attr in attr_names if attr not in skip_attrs]
+
+        if not follow_references:
+            attrs = {attr: self.get_unreferenced_value(attr) for attr in attr_names}
+        else:
+            attrs = {attr: getattr(self, attr) for attr in attr_names}
+
+        if not include_defaults:
+            attrs = {
+                attr: val
+                for attr, val in attrs.items()
+                if not self._attr_val_is_default(attr, val)
+            }
+        return attrs
+
+    def to_dict(
+        self, follow_references: bool = False, include_defaults: bool = False
+    ) -> Dict[str, Any]:
+        """Convert this object to a dictionary.
+
+        Args:
+            follow_references: Whether to follow references when getting the value.
+                If False, the reference will be returned as a string.
+            include_defaults: Whether to include attributes that have the default
+
+        Returns:
+            A dictionary representation of this object.
+            Any QuamBase objects will be recursively converted to dictionaries.
+
+        Note:
+            If the value of an attribute does not match the annotation, the
+            `"__class__"` key will be added to the dictionary. This is to ensure
+            that the object can be reconstructed when loading from a file.
+        """
+        attrs = self.get_attrs(
+            follow_references=follow_references, include_defaults=include_defaults
+        )
+        quam_dict = {}
+        for attr, val in attrs.items():
+            if isinstance(val, QuamBase):
+                quam_dict[attr] = val.to_dict(
+                    follow_references=follow_references,
+                    include_defaults=include_defaults,
+                )
+                val_is_list = isinstance(val, (list, UserList))
+                if not self._val_matches_attr_annotation(attr, val) and not val_is_list:
+                    quam_dict[attr]["__class__"] = get_full_class_path(val)
+            else:
+                quam_dict[attr] = val
+        return quam_dict
+
+    def iterate_components(
+        self, skip_elems: bool = None
+    ) -> Generator["QuamBase", None, None]:
+        """Iterate over all QuamBase objects in this object, including nested objects.
+
+        Args:
+            skip_elems: A list of QuamBase objects to skip.
+                This is used to prevent infinite loops when iterating over nested
+                objects.
+
+        Returns:
+            A generator of QuamBase objects.
+        """
+        if skip_elems is None:
+            skip_elems = []
+
+        # We don't use "self in skip_elems" because we want to check for identity,
+        # not equality. The reason is that you would otherwise have to instantiate
+        # dataclasses using @dataclass(eq=False)
+        in_skip_elems = any(self is elem for elem in skip_elems)
+        if isinstance(self, QuamComponent) and not in_skip_elems:
+            skip_elems.append(self)
+            yield self
+
+        attrs = self.get_attrs(follow_references=False, include_defaults=True)
+
+        for attr_val in attrs.values():
+            if any(attr_val is elem for elem in skip_elems):
+                continue
+
+            if isinstance(attr_val, QuamBase):
+                yield from attr_val.iterate_components(skip_elems=skip_elems)
+
+    def _is_reference(self, attr: str) -> bool:
+        """Check whether an attribute is a reference.
+
+        Args:
+            attr: The name of the attribute.
+
+        Returns:
+            True if the attribute is a reference, False otherwise.
+
+        Note:
+            This function is used from the ReferenceClass class.
+        """
+        return string_reference.is_reference(attr)
+
+    def _get_referenced_value(self, reference: str) -> Any:
+        """Get the value of an attribute by reference
+
+        Args:
+            reference: The reference to the attribute.
+
+        Returns:
+            The value of the attribute, or the reference if it is not a reference
+
+        Note:
+            This function is used from the ReferenceClass class.
+        """
+        if not string_reference.is_reference(reference):
+            return reference
+
+        if string_reference.is_absolute_reference(reference) and self._root is None:
+            warnings.warn(
+                f"No QuamRoot initialized, cannot retrieve reference {reference}"
+                f" from {self.__class__.__name__}"
+            )
+            return reference
+
+        try:
+            return string_reference.get_referenced_value(
+                self, reference, root=self._root
+            )
+        except ValueError as e:
+            try:
+                ref = f"{self.__class__.__name__}: {self.get_reference()}"
+            except Exception:
+                ref = self.__class__.__name__
+            warnings.warn(f"Could not get reference {reference} from {ref}.\n{str(e)}")
+            return reference
+
+    def print_summary(self, indent: int = 0):
+        """Print a summary of the QuamBase object.
+
+        Args:
+            indent: The number of spaces to indent the summary.
+        """
+        if self._root is self:
+            full_name = "QuAM:"
+        elif self.parent is None:
+            full_name = f"{self.__class__.__name__} (parent unknown):"
+        else:
+            try:
+                attr_name = self.parent.get_attr_name(self)
+                full_name = f"{attr_name}: {self.__class__.__name__}"
+            except AttributeError:
+                full_name = f"{self.__class__.__name__}:"
+
+        if not self.get_attrs():
+            print(" " * indent + f"{full_name} Empty")
+            return
+
+        print(" " * indent + f"{full_name}")
+        for attr, val in self.get_attrs().items():
+            if isinstance(val, str):
+                val = f'"{val}"'
+            if isinstance(val, QuamBase):
+                val.print_summary(indent=indent + 2)
+            else:
+                print(" " * (indent + 2) + f"{attr}: {val}")
+
+
+ + + +
+ + + + + + + + + +
+ + +

+ get_attr_name(attr_val) + +

+ + +
+ +

Get the name of an attribute that matches the value.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
attr_val + Any + +
+

The value of the attribute.

+
+ 		+ required +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ str + +
+

The name of the attribute.

+
+
+ +
+ Source code in quam/core/quam_classes.py + 
272
+273
+274
+275
+276
+277
+278
+279
+280
+281
+282
+283
+284
+285
+286
+287
+288
+289
+290
+291
+292
def get_attr_name(self, attr_val: Any) -> str:
+    """Get the name of an attribute that matches the value.
+
+    Args:
+        attr_val: The value of the attribute.
+
+    Returns:
+        The name of the attribute.
+
+    Raises:
+        AttributeError if not found.
+    """
+    for attr_name in self._get_attr_names():
+        if getattr(self, attr_name) is attr_val:
+            return attr_name
+    else:
+        raise AttributeError(
+            "Could not find name corresponding to attribute.\n"
+            f"attribute: {attr_val}\n"
+            f"obj: {self}"
+        )
+
+
+
+ +
+ +
+ + +

+ get_attrs(follow_references=False, include_defaults=True) + +

+ + +
+ +

Get all attributes and corresponding values of this object.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
follow_references + bool + +
+

Whether to follow references when getting the value. +If False, the reference will be returned as a string.

+
+ 		+ False +
include_defaults + bool + +
+

Whether to include attributes that have the default +value.

+
+ 		+ True +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ Dict[str, Any] + +
+

A dictionary of attribute names and values.

+
+
+ +
+ Source code in quam/core/quam_classes.py + 
365
+366
+367
+368
+369
+370
+371
+372
+373
+374
+375
+376
+377
+378
+379
+380
+381
+382
+383
+384
+385
+386
+387
+388
+389
+390
+391
+392
+393
+394
+395
+396
def get_attrs(
+    self, follow_references: bool = False, include_defaults: bool = True
+) -> Dict[str, Any]:
+    """Get all attributes and corresponding values of this object.
+
+    Args:
+        follow_references: Whether to follow references when getting the value.
+            If False, the reference will be returned as a string.
+        include_defaults: Whether to include attributes that have the default
+            value.
+
+    Returns:
+        A dictionary of attribute names and values.
+
+    """
+    attr_names = self._get_attr_names()
+
+    skip_attrs = getattr(self, "_skip_attrs", [])
+    attr_names = [attr for attr in attr_names if attr not in skip_attrs]
+
+    if not follow_references:
+        attrs = {attr: self.get_unreferenced_value(attr) for attr in attr_names}
+    else:
+        attrs = {attr: getattr(self, attr) for attr in attr_names}
+
+    if not include_defaults:
+        attrs = {
+            attr: val
+            for attr, val in attrs.items()
+            if not self._attr_val_is_default(attr, val)
+        }
+    return attrs
+
+
+
+ +
+ +
+ + +

+ get_reference(attr=None) + +

+ + +
+ +

Get the reference path of this object.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
attr + +
+

The attribute to get the reference path for. If None, the reference +path of the object itself is returned.

+
+ 		+ None +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ Optional[str] + +
+

The reference path of this object.

+
+
+ +
+ Source code in quam/core/quam_classes.py + 
345
+346
+347
+348
+349
+350
+351
+352
+353
+354
+355
+356
+357
+358
+359
+360
+361
+362
+363
def get_reference(self, attr=None) -> Optional[str]:
+    """Get the reference path of this object.
+
+    Args:
+        attr: The attribute to get the reference path for. If None, the reference
+            path of the object itself is returned.
+
+    Returns:
+        The reference path of this object.
+    """
+
+    if self.parent is None:
+        raise AttributeError(
+            "Unable to extract reference path. Parent must be defined for {self}"
+        )
+    reference = f"{self.parent.get_reference()}/{self.parent.get_attr_name(self)}"
+    if attr is not None:
+        reference = f"{reference}/{attr}"
+    return reference
+
+
+
+ +
+ +
+ + +

+ iterate_components(skip_elems=None) + +

+ + +
+ +

Iterate over all QuamBase objects in this object, including nested objects.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
skip_elems + bool + +
+

A list of QuamBase objects to skip. +This is used to prevent infinite loops when iterating over nested +objects.

+
+ 		+ None +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ Generator[QuamBase, None, None] + +
+

A generator of QuamBase objects.

+
+
+ +
+ Source code in quam/core/quam_classes.py + 
434
+435
+436
+437
+438
+439
+440
+441
+442
+443
+444
+445
+446
+447
+448
+449
+450
+451
+452
+453
+454
+455
+456
+457
+458
+459
+460
+461
+462
+463
+464
+465
def iterate_components(
+    self, skip_elems: bool = None
+) -> Generator["QuamBase", None, None]:
+    """Iterate over all QuamBase objects in this object, including nested objects.
+
+    Args:
+        skip_elems: A list of QuamBase objects to skip.
+            This is used to prevent infinite loops when iterating over nested
+            objects.
+
+    Returns:
+        A generator of QuamBase objects.
+    """
+    if skip_elems is None:
+        skip_elems = []
+
+    # We don't use "self in skip_elems" because we want to check for identity,
+    # not equality. The reason is that you would otherwise have to instantiate
+    # dataclasses using @dataclass(eq=False)
+    in_skip_elems = any(self is elem for elem in skip_elems)
+    if isinstance(self, QuamComponent) and not in_skip_elems:
+        skip_elems.append(self)
+        yield self
+
+    attrs = self.get_attrs(follow_references=False, include_defaults=True)
+
+    for attr_val in attrs.values():
+        if any(attr_val is elem for elem in skip_elems):
+            continue
+
+        if isinstance(attr_val, QuamBase):
+            yield from attr_val.iterate_components(skip_elems=skip_elems)
+
+
+
+ +
+ +
+ + +

+ print_summary(indent=0) + +

+ + +
+ +

Print a summary of the QuamBase object.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
indent + int + +
+

The number of spaces to indent the summary.

+
+ 		+ 0 +
+ +
+ Source code in quam/core/quam_classes.py + 
515
+516
+517
+518
+519
+520
+521
+522
+523
+524
+525
+526
+527
+528
+529
+530
+531
+532
+533
+534
+535
+536
+537
+538
+539
+540
+541
+542
+543
def print_summary(self, indent: int = 0):
+    """Print a summary of the QuamBase object.
+
+    Args:
+        indent: The number of spaces to indent the summary.
+    """
+    if self._root is self:
+        full_name = "QuAM:"
+    elif self.parent is None:
+        full_name = f"{self.__class__.__name__} (parent unknown):"
+    else:
+        try:
+            attr_name = self.parent.get_attr_name(self)
+            full_name = f"{attr_name}: {self.__class__.__name__}"
+        except AttributeError:
+            full_name = f"{self.__class__.__name__}:"
+
+    if not self.get_attrs():
+        print(" " * indent + f"{full_name} Empty")
+        return
+
+    print(" " * indent + f"{full_name}")
+    for attr, val in self.get_attrs().items():
+        if isinstance(val, str):
+            val = f'"{val}"'
+        if isinstance(val, QuamBase):
+            val.print_summary(indent=indent + 2)
+        else:
+            print(" " * (indent + 2) + f"{attr}: {val}")
+
+
+
+ +
+ +
+ + +

+ to_dict(follow_references=False, include_defaults=False) + +

+ + +
+ +

Convert this object to a dictionary.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
follow_references + bool + +
+

Whether to follow references when getting the value. +If False, the reference will be returned as a string.

+
+ 		+ False +
include_defaults + bool + +
+

Whether to include attributes that have the default

+
+ 		+ False +
+ + +

Returns:

+ + + + + + + + + + + + + + + + + +
TypeDescription
+ Dict[str, Any] + +
+

A dictionary representation of this object.

+
+
+ Dict[str, Any] + +
+

Any QuamBase objects will be recursively converted to dictionaries.

+
+
+ + +
+ Note +

If the value of an attribute does not match the annotation, the +"__class__" key will be added to the dictionary. This is to ensure +that the object can be reconstructed when loading from a file.

+
+
+ Source code in quam/core/quam_classes.py + 
398
+399
+400
+401
+402
+403
+404
+405
+406
+407
+408
+409
+410
+411
+412
+413
+414
+415
+416
+417
+418
+419
+420
+421
+422
+423
+424
+425
+426
+427
+428
+429
+430
+431
+432
def to_dict(
+    self, follow_references: bool = False, include_defaults: bool = False
+) -> Dict[str, Any]:
+    """Convert this object to a dictionary.
+
+    Args:
+        follow_references: Whether to follow references when getting the value.
+            If False, the reference will be returned as a string.
+        include_defaults: Whether to include attributes that have the default
+
+    Returns:
+        A dictionary representation of this object.
+        Any QuamBase objects will be recursively converted to dictionaries.
+
+    Note:
+        If the value of an attribute does not match the annotation, the
+        `"__class__"` key will be added to the dictionary. This is to ensure
+        that the object can be reconstructed when loading from a file.
+    """
+    attrs = self.get_attrs(
+        follow_references=follow_references, include_defaults=include_defaults
+    )
+    quam_dict = {}
+    for attr, val in attrs.items():
+        if isinstance(val, QuamBase):
+            quam_dict[attr] = val.to_dict(
+                follow_references=follow_references,
+                include_defaults=include_defaults,
+            )
+            val_is_list = isinstance(val, (list, UserList))
+            if not self._val_matches_attr_annotation(attr, val) and not val_is_list:
+                quam_dict[attr]["__class__"] = get_full_class_path(val)
+        else:
+            quam_dict[attr] = val
+    return quam_dict
+
+
+
+ +
+ + + +
+ +
+ +
+ +
+ + + +

+ QuamRoot + + +

+ + +
+

+ Bases: QuamBase

+ + +

Base class for the root of a QuAM object.

+

This class should be subclassed and made a dataclass.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
serialiser + +
+

The serialiser class to use for saving and loading. +The default is to use the JSONSerialiser, but this can be changed.

+
+ 		+ required +
+ + +
+ Note +

This class should not be used directly, but should generally be subclassed and +made a dataclass. The dataclass fields should correspond to the QuAM root +structure.

+
+ +
+ Note +

Upon instantiating a QuamRoot object, it sets the class attribute +QuamBase._root to itself. This is used such that any references with an +absolute path are resolved from the root.

+
+
+ Source code in quam/core/quam_classes.py + 
550
+551
+552
+553
+554
+555
+556
+557
+558
+559
+560
+561
+562
+563
+564
+565
+566
+567
+568
+569
+570
+571
+572
+573
+574
+575
+576
+577
+578
+579
+580
+581
+582
+583
+584
+585
+586
+587
+588
+589
+590
+591
+592
+593
+594
+595
+596
+597
+598
+599
+600
+601
+602
+603
+604
+605
+606
+607
+608
+609
+610
+611
+612
+613
+614
+615
+616
+617
+618
+619
+620
+621
+622
+623
+624
+625
+626
+627
+628
+629
+630
+631
+632
+633
+634
+635
+636
+637
+638
+639
+640
+641
+642
+643
+644
+645
+646
+647
+648
+649
+650
+651
+652
+653
+654
+655
+656
+657
+658
+659
+660
+661
+662
+663
+664
+665
+666
+667
+668
+669
+670
+671
+672
+673
+674
+675
+676
+677
+678
+679
+680
+681
+682
+683
+684
+685
+686
class QuamRoot(QuamBase):
+    """Base class for the root of a QuAM object.
+
+    This class should be subclassed and made a dataclass.
+
+    Args:
+        serialiser: The serialiser class to use for saving and loading.
+            The default is to use the `JSONSerialiser`, but this can be changed.
+
+    Note:
+        This class should not be used directly, but should generally be subclassed and
+        made a dataclass. The dataclass fields should correspond to the QuAM root
+        structure.
+
+    Note:
+        Upon instantiating a `QuamRoot` object, it sets the class attribute
+        `QuamBase._root` to itself. This is used such that any references with an
+        absolute path are resolved from the root.
+    """
+
+    serialiser: AbstractSerialiser = JSONSerialiser
+
+    def __post_init__(self):
+        QuamBase._root = self
+        super().__post_init__()
+
+    def __setattr__(self, name, value):
+        converted_val = convert_dict_and_list(value, cls_or_obj=self, attr=name)
+        super().__setattr__(name, converted_val)
+
+        if isinstance(converted_val, QuamBase) and name != "parent":
+            converted_val.parent = self
+
+    def get_reference(self):
+        return "#"
+
+    def save(
+        self,
+        path: Union[Path, str] = None,
+        content_mapping: Dict[str, str] = None,
+        include_defaults: bool = False,
+        ignore: Sequence[str] = None,
+    ):
+        """Save the entire QuamRoot object to a file. This includes nested objects.
+
+        Args:
+            path: The path to save the file to. If None, the path will be saved to
+                `state.json`.
+            content_mapping: A dictionary of paths to save to and a list of attributes
+                to save to that path. This can be used to save different parts of the
+                QuamRoot object to different files.
+            include_defaults: Whether to include attributes that have the default
+                value.
+            ignore: A list of attributes to ignore.
+        """
+        serialiser = self.serialiser()
+        serialiser.save(
+            quam_obj=self,
+            path=path,
+            content_mapping=content_mapping,
+            include_defaults=include_defaults,
+            ignore=ignore,
+        )
+
+    def to_dict(
+        self, follow_references: bool = False, include_defaults: bool = False
+    ) -> Dict[str, Any]:
+        """Convert this object to a dictionary.
+
+        Args:
+            follow_references: Whether to follow references when getting the value.
+                If False, the reference will be returned as a string.
+            include_defaults: Whether to include attributes that have the default
+                value.
+        """
+        quam_dict = super().to_dict(follow_references, include_defaults)
+        # QuamRoot should always add __class__ because it is generally not
+        # quam.components.quam.QuAM
+        quam_dict["__class__"] = get_full_class_path(self)
+        return quam_dict
+
+    @classmethod
+    def load(
+        cls: QuamRootType,
+        filepath_or_dict: Union[str, Path, dict],
+        validate_type: bool = True,
+        fix_attrs: bool = True,
+    ) -> QuamRootType:
+        """Load a QuamRoot object from a file.
+
+        Args:
+            filepath_or_dict: The path to the file/folder to load, or a dictionary.
+                The dictionary would be the result from a call to `QuamRoot.save()`
+            validate_type: Whether to validate the type of all attributes while loading.
+            fix_attrs: Whether attributes can be added to QuamBase objects that are not
+                defined as dataclass fields.
+
+        Returns:
+            A QuamRoot object instantiated from the file/folder/dict.
+        """
+        if isinstance(filepath_or_dict, dict):
+            contents = filepath_or_dict
+        else:
+            serialiser = cls.serialiser()
+            contents, _ = serialiser.load(filepath_or_dict)
+
+        return instantiate_quam_class(
+            quam_class=cls,
+            contents=contents,
+            fix_attrs=fix_attrs,
+            validate_type=validate_type,
+        )
+
+    def generate_config(self) -> Dict[str, Any]:
+        """Generate the QUA configuration from the QuAM object.
+
+        Returns:
+            A dictionary with the QUA configuration.
+
+        Note:
+            This function collects all the nested QuamComponent objects and calls
+            `QuamComponent.apply_to_config` on them.
+        """
+        qua_config = deepcopy(qua_config_template)
+
+        quam_components = list(self.iterate_components())
+        sorted_components = sort_quam_components(quam_components)
+
+        for quam_component in sorted_components:
+            quam_component.apply_to_config(qua_config)
+
+        generate_config_final_actions(qua_config)
+
+        return qua_config
+
+    def get_unreferenced_value(self, attr: str):
+        return getattr(self, attr)
+
+
+ + + +
+ + + + + + + + + +
+ + +

+ generate_config() + +

+ + +
+ +

Generate the QUA configuration from the QuAM object.

+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ Dict[str, Any] + +
+

A dictionary with the QUA configuration.

+
+
+ + +
+ Note +

This function collects all the nested QuamComponent objects and calls +QuamComponent.apply_to_config on them.

+
+
+ Source code in quam/core/quam_classes.py + 
663
+664
+665
+666
+667
+668
+669
+670
+671
+672
+673
+674
+675
+676
+677
+678
+679
+680
+681
+682
+683
def generate_config(self) -> Dict[str, Any]:
+    """Generate the QUA configuration from the QuAM object.
+
+    Returns:
+        A dictionary with the QUA configuration.
+
+    Note:
+        This function collects all the nested QuamComponent objects and calls
+        `QuamComponent.apply_to_config` on them.
+    """
+    qua_config = deepcopy(qua_config_template)
+
+    quam_components = list(self.iterate_components())
+    sorted_components = sort_quam_components(quam_components)
+
+    for quam_component in sorted_components:
+        quam_component.apply_to_config(qua_config)
+
+    generate_config_final_actions(qua_config)
+
+    return qua_config
+
+
+
+ +
+ +
+ + +

+ load(filepath_or_dict, validate_type=True, fix_attrs=True) + + + classmethod + + +

+ + +
+ +

Load a QuamRoot object from a file.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
filepath_or_dict + Union[str, Path, dict] + +
+

The path to the file/folder to load, or a dictionary. +The dictionary would be the result from a call to QuamRoot.save()

+
+ 		+ required +
validate_type + bool + +
+

Whether to validate the type of all attributes while loading.

+
+ 		+ True +
fix_attrs + bool + +
+

Whether attributes can be added to QuamBase objects that are not +defined as dataclass fields.

+
+ 		+ True +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ QuamRootType + +
+

A QuamRoot object instantiated from the file/folder/dict.

+
+
+ +
+ Source code in quam/core/quam_classes.py + 
631
+632
+633
+634
+635
+636
+637
+638
+639
+640
+641
+642
+643
+644
+645
+646
+647
+648
+649
+650
+651
+652
+653
+654
+655
+656
+657
+658
+659
+660
+661
@classmethod
+def load(
+    cls: QuamRootType,
+    filepath_or_dict: Union[str, Path, dict],
+    validate_type: bool = True,
+    fix_attrs: bool = True,
+) -> QuamRootType:
+    """Load a QuamRoot object from a file.
+
+    Args:
+        filepath_or_dict: The path to the file/folder to load, or a dictionary.
+            The dictionary would be the result from a call to `QuamRoot.save()`
+        validate_type: Whether to validate the type of all attributes while loading.
+        fix_attrs: Whether attributes can be added to QuamBase objects that are not
+            defined as dataclass fields.
+
+    Returns:
+        A QuamRoot object instantiated from the file/folder/dict.
+    """
+    if isinstance(filepath_or_dict, dict):
+        contents = filepath_or_dict
+    else:
+        serialiser = cls.serialiser()
+        contents, _ = serialiser.load(filepath_or_dict)
+
+    return instantiate_quam_class(
+        quam_class=cls,
+        contents=contents,
+        fix_attrs=fix_attrs,
+        validate_type=validate_type,
+    )
+
+
+
+ +
+ +
+ + +

+ save(path=None, content_mapping=None, include_defaults=False, ignore=None) + +

+ + +
+ +

Save the entire QuamRoot object to a file. This includes nested objects.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
path + Union[Path, str] + +
+

The path to save the file to. If None, the path will be saved to +state.json.

+
+ 		+ None +
content_mapping + Dict[str, str] + +
+

A dictionary of paths to save to and a list of attributes +to save to that path. This can be used to save different parts of the +QuamRoot object to different files.

+
+ 		+ None +
include_defaults + bool + +
+

Whether to include attributes that have the default +value.

+
+ 		+ False +
ignore + Sequence[str] + +
+

A list of attributes to ignore.

+
+ 		+ None +
+ +
+ Source code in quam/core/quam_classes.py + 
586
+587
+588
+589
+590
+591
+592
+593
+594
+595
+596
+597
+598
+599
+600
+601
+602
+603
+604
+605
+606
+607
+608
+609
+610
+611
+612
def save(
+    self,
+    path: Union[Path, str] = None,
+    content_mapping: Dict[str, str] = None,
+    include_defaults: bool = False,
+    ignore: Sequence[str] = None,
+):
+    """Save the entire QuamRoot object to a file. This includes nested objects.
+
+    Args:
+        path: The path to save the file to. If None, the path will be saved to
+            `state.json`.
+        content_mapping: A dictionary of paths to save to and a list of attributes
+            to save to that path. This can be used to save different parts of the
+            QuamRoot object to different files.
+        include_defaults: Whether to include attributes that have the default
+            value.
+        ignore: A list of attributes to ignore.
+    """
+    serialiser = self.serialiser()
+    serialiser.save(
+        quam_obj=self,
+        path=path,
+        content_mapping=content_mapping,
+        include_defaults=include_defaults,
+        ignore=ignore,
+    )
+
+
+
+ +
+ +
+ + +

+ to_dict(follow_references=False, include_defaults=False) + +

+ + +
+ +

Convert this object to a dictionary.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
follow_references + bool + +
+

Whether to follow references when getting the value. +If False, the reference will be returned as a string.

+
+ 		+ False +
include_defaults + bool + +
+

Whether to include attributes that have the default +value.

+
+ 		+ False +
+ +
+ Source code in quam/core/quam_classes.py + 
614
+615
+616
+617
+618
+619
+620
+621
+622
+623
+624
+625
+626
+627
+628
+629
def to_dict(
+    self, follow_references: bool = False, include_defaults: bool = False
+) -> Dict[str, Any]:
+    """Convert this object to a dictionary.
+
+    Args:
+        follow_references: Whether to follow references when getting the value.
+            If False, the reference will be returned as a string.
+        include_defaults: Whether to include attributes that have the default
+            value.
+    """
+    quam_dict = super().to_dict(follow_references, include_defaults)
+    # QuamRoot should always add __class__ because it is generally not
+    # quam.components.quam.QuAM
+    quam_dict["__class__"] = get_full_class_path(self)
+    return quam_dict
+
+
+
+ +
+ + + +
+ +
+ +
+ +
+ + + +

+ QuamComponent + + +

+ + +
+

+ Bases: QuamBase

+ + +

Base class for any QuAM component class.

+

Examples of QuamComponent classes are Mixer, +LocalOscillator, +Pulse, etc.

+ + +
+ Note +

This class should be subclassed and made a dataclass.

+
+
+ Source code in quam/core/quam_classes.py + 
689
+690
+691
+692
+693
+694
+695
+696
+697
+698
+699
+700
+701
+702
+703
+704
+705
+706
+707
+708
+709
+710
+711
+712
+713
+714
+715
+716
+717
+718
+719
+720
+721
class QuamComponent(QuamBase):
+    """Base class for any QuAM component class.
+
+    Examples of QuamComponent classes are [`Mixer`][quam.components.hardware.Mixer],
+    [`LocalOscillator`][quam.components.hardware.LocalOscillator],
+    [`Pulse`][quam.components.pulses.Pulse], etc.
+
+    Note:
+        This class should be subclassed and made a dataclass.
+    """
+
+    def __setattr__(self, name, value):
+        converted_val = convert_dict_and_list(value, cls_or_obj=self, attr=name)
+        super().__setattr__(name, converted_val)
+
+        if isinstance(converted_val, QuamBase) and name != "parent":
+            converted_val.parent = self
+
+    def apply_to_config(self, config: dict) -> None:
+        """Add information to the QUA configuration, such as pulses and waveforms.
+
+        Args:
+            config: The QUA configuration dictionary. Initially this is a nearly empty
+                dictionary, but
+
+        Note:
+            This function is called by
+            [`QuamRoot.generate_config`][quam.core.quam_classes.QuamRoot.generate_config].
+
+        Note:
+            The config has a starting template, defined at [`quam.core.qua_config_template`][]
+        """
+        ...
+
+
+ + + +
+ + + + + + + + + +
+ + +

+ apply_to_config(config) + +

+ + +
+ +

Add information to the QUA configuration, such as pulses and waveforms.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
config + dict + +
+

The QUA configuration dictionary. Initially this is a nearly empty +dictionary, but

+
+ 		+ required +
+ + +
+ Note +

This function is called by +QuamRoot.generate_config.

+
+ +
+ Note +

The config has a starting template, defined at quam.core.qua_config_template

+
+
+ Source code in quam/core/quam_classes.py + 
707
+708
+709
+710
+711
+712
+713
+714
+715
+716
+717
+718
+719
+720
+721
def apply_to_config(self, config: dict) -> None:
+    """Add information to the QUA configuration, such as pulses and waveforms.
+
+    Args:
+        config: The QUA configuration dictionary. Initially this is a nearly empty
+            dictionary, but
+
+    Note:
+        This function is called by
+        [`QuamRoot.generate_config`][quam.core.quam_classes.QuamRoot.generate_config].
+
+    Note:
+        The config has a starting template, defined at [`quam.core.qua_config_template`][]
+    """
+    ...
+
+
+
+ +
+ + + +
+ +
+ +
+ +
+ + + +

+ QuamDict + + +

+ + +
+

+ Bases: UserDict, QuamBase

+ + +

A QuAM dictionary class.

+

Any dict added to a QuamBase object is automatically converted to a QuamDict. +The QuamDict adds the following functionalities to a dict: +- Values can be references (see below) +- Keys can also be accessed through attributes (e.g. d.a instead of d["a"])

+

QuamDict references

+

QuamDict values can be references, which are strings that start with #. See the +documentation for details on references. An example is shown here: +

d = QuamDict({"a": 1, "b": "#./a"})
+assert d["b"] == 1
+

+ + +
+ Warning +

This class is a subclass of QuamBase, but also of UserDict. As a result, +it can be used as a normal dictionary, but it is not a subclass of dict.

+
+
+ Source code in quam/core/quam_classes.py + 
724
+725
+726
+727
+728
+729
+730
+731
+732
+733
+734
+735
+736
+737
+738
+739
+740
+741
+742
+743
+744
+745
+746
+747
+748
+749
+750
+751
+752
+753
+754
+755
+756
+757
+758
+759
+760
+761
+762
+763
+764
+765
+766
+767
+768
+769
+770
+771
+772
+773
+774
+775
+776
+777
+778
+779
+780
+781
+782
+783
+784
+785
+786
+787
+788
+789
+790
+791
+792
+793
+794
+795
+796
+797
+798
+799
+800
+801
+802
+803
+804
+805
+806
+807
+808
+809
+810
+811
+812
+813
+814
+815
+816
+817
+818
+819
+820
+821
+822
+823
+824
+825
+826
+827
+828
+829
+830
+831
+832
+833
+834
+835
+836
+837
+838
+839
+840
+841
+842
+843
+844
+845
+846
+847
+848
+849
+850
+851
+852
+853
+854
+855
+856
+857
+858
+859
+860
+861
+862
+863
+864
+865
+866
+867
+868
+869
+870
+871
+872
+873
+874
+875
+876
+877
+878
+879
+880
+881
+882
+883
+884
+885
+886
+887
+888
+889
+890
+891
+892
+893
+894
+895
+896
+897
+898
+899
+900
+901
+902
+903
+904
+905
+906
+907
+908
@quam_dataclass
+class QuamDict(UserDict, QuamBase):
+    """A QuAM dictionary class.
+
+    Any dict added to a `QuamBase` object is automatically converted to a `QuamDict`.
+    The `QuamDict` adds the following functionalities to a dict:
+    - Values can be references (see below)
+    - Keys can also be accessed through attributes (e.g. `d.a` instead of `d["a"]`)
+
+    # QuamDict references
+    QuamDict values can be references, which are strings that start with `#`. See the
+    documentation for details on references. An example is shown here:
+    ```
+    d = QuamDict({"a": 1, "b": "#./a"})
+    assert d["b"] == 1
+    ```
+
+    Warning:
+        This class is a subclass of `QuamBase`, but also of `UserDict`. As a result,
+        it can be used as a normal dictionary, but it is not a subclass of `dict`.
+    """
+
+    _value_annotation: ClassVar[type] = None
+
+    def __init__(self, dict=None, /, value_annotation: type = None, **kwargs):
+        self.__dict__["data"] = {}
+        self.__dict__["_value_annotation"] = value_annotation
+        self.__dict__["_initialized"] = True
+        super().__init__(dict, **kwargs)
+
+    def __getattr__(self, key):
+        try:
+            return self[key]
+        except KeyError as e:
+            try:
+                repr = f"{self.__class__.__name__}: {self.get_reference()}"
+            except Exception:
+                repr = self.__class__.__name__
+            raise AttributeError(f'{repr} has no attribute "{key}"') from e
+
+    def __setattr__(self, key, value):
+        if key in ["data", "parent", "config_settings", "_initialized"]:
+            super().__setattr__(key, value)
+        else:
+            self[key] = value
+
+    def __getitem__(self, i):
+        elem = super().__getitem__(i)
+        if string_reference.is_reference(elem):
+            try:
+                elem = self._get_referenced_value(elem)
+            except ValueError as e:
+                try:
+                    repr = f"{self.__class__.__name__}: {self.get_reference()}"
+                except Exception:
+                    repr = self.__class__.__name__
+                raise KeyError(
+                    f"Could not get referenced value {elem} from {repr}"
+                ) from e
+        return elem
+
+    # Overriding methods from UserDict
+    def __setitem__(self, key, value):
+        value = convert_dict_and_list(value)
+        self._is_valid_setattr(key, value, error_on_False=True)
+        super().__setitem__(key, value)
+
+        if isinstance(value, QuamBase):
+            value.parent = self
+
+    def __eq__(self, other) -> bool:
+        if isinstance(other, dict):
+            return self.data == other
+        return super().__eq__(other)
+
+    def __repr__(self) -> str:
+        with warnings.catch_warnings():
+            warnings.filterwarnings(
+                "ignore",
+                message="^Could not get reference*",
+                category=UserWarning,
+            )
+            return super().__repr__()
+
+    # QuAM methods
+    def _get_attr_names(self):
+        return list(self.data.keys())
+
+    def get_attrs(
+        self, follow_references=False, include_defaults=True
+    ) -> Dict[str, Any]:
+        # TODO implement reference kwargs
+        return self.data
+
+    def get_attr_name(self, attr_val: Any) -> Union[str, int]:
+        """Get the name of an attribute that matches the value.
+
+        Args:
+            attr_val: The value of the attribute.
+
+        Returns:
+            The name of the attribute. This can also be an int depending on the dict key
+
+        Raises:
+            AttributeError if not found.
+        """
+        for attr_name in self._get_attr_names():
+            if attr_name in self and self[attr_name] is attr_val:
+                return attr_name
+        else:
+            raise AttributeError(
+                "Could not find name corresponding to attribute.\n"
+                f"attribute: {attr_val}\n"
+                f"obj: {self}"
+            )
+
+    def _val_matches_attr_annotation(self, attr: str, val: Any) -> bool:
+        """Check whether the type of an attribute matches the annotation.
+
+        Called by [`QuamDict.to_dict`][quam.core.quam_classes.QuamDict.to_dict] to
+        determine whether to add the __class__ key.
+
+        Args:
+            attr: The name of the attribute. Unused but added to match parent signature
+            val: The value of the attribute.
+
+        Note:
+            The attribute val is compared to `QuamDict._value_annotation`, which is set
+            when a dict is converted to a `QuamDict` using `convert_dict_and_list`.
+        """
+        if isinstance(val, (QuamDict, QuamList)):
+            return True
+        if self._value_annotation is None:
+            return False
+        return type(val) == self._value_annotation
+
+    def _attr_val_is_default(self, attr: str, val: Any):
+        """Check whether the value of an attribute is the default value.
+
+        Overrides parent method.
+        Since a QuamDict does not have any fixed attrs, this is always False.
+
+        """
+        return False
+
+    def get_unreferenced_value(self, attr: str) -> bool:
+        """Get the value of an attribute without following references.
+
+        Args:
+            attr: The name of the attribute.
+
+        Returns:
+            The value of the attribute. If the value is a reference, it returns the
+            reference string instead of the value it is referencing.
+        """
+        try:
+            return self.__dict__["data"][attr]
+        except KeyError as e:
+            raise AttributeError(
+                "Cannot get unreferenced value from attribute {attr} that does not"
+                " exist in {self}"
+            ) from e
+
+    def iterate_components(
+        self, skip_elems: Sequence[QuamBase] = None
+    ) -> Generator["QuamBase", None, None]:
+        """Iterate over all QuamBase objects in this object, including nested objects.
+
+        Args:
+            skip_elems: A list of QuamBase objects to skip.
+                This is used to prevent infinite loops when iterating over nested
+                objects.
+
+        Returns:
+            A generator of QuamBase objects.
+        """
+        if skip_elems is None:
+            skip_elems = []
+
+        for attr_val in self.data.values():
+            if any(attr_val is elem for elem in skip_elems):
+                continue
+
+            if isinstance(attr_val, QuamBase):
+                yield from attr_val.iterate_components(skip_elems=skip_elems)
+
+
+ + + +
+ + + + + + + + + +
+ + +

+ get_attr_name(attr_val) + +

+ + +
+ +

Get the name of an attribute that matches the value.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
attr_val + Any + +
+

The value of the attribute.

+
+ 		+ required +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ Union[str, int] + +
+

The name of the attribute. This can also be an int depending on the dict key

+
+
+ +
+ Source code in quam/core/quam_classes.py + 
818
+819
+820
+821
+822
+823
+824
+825
+826
+827
+828
+829
+830
+831
+832
+833
+834
+835
+836
+837
+838
def get_attr_name(self, attr_val: Any) -> Union[str, int]:
+    """Get the name of an attribute that matches the value.
+
+    Args:
+        attr_val: The value of the attribute.
+
+    Returns:
+        The name of the attribute. This can also be an int depending on the dict key
+
+    Raises:
+        AttributeError if not found.
+    """
+    for attr_name in self._get_attr_names():
+        if attr_name in self and self[attr_name] is attr_val:
+            return attr_name
+    else:
+        raise AttributeError(
+            "Could not find name corresponding to attribute.\n"
+            f"attribute: {attr_val}\n"
+            f"obj: {self}"
+        )
+
+
+
+ +
+ +
+ + +

+ get_unreferenced_value(attr) + +

+ + +
+ +

Get the value of an attribute without following references.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
attr + str + +
+

The name of the attribute.

+
+ 		+ required +
+ + +

Returns:

+ + + + + + + + + + + + + + + + + +
TypeDescription
+ bool + +
+

The value of the attribute. If the value is a reference, it returns the

+
+
+ bool + +
+

reference string instead of the value it is referencing.

+
+
+ +
+ Source code in quam/core/quam_classes.py + 
869
+870
+871
+872
+873
+874
+875
+876
+877
+878
+879
+880
+881
+882
+883
+884
+885
def get_unreferenced_value(self, attr: str) -> bool:
+    """Get the value of an attribute without following references.
+
+    Args:
+        attr: The name of the attribute.
+
+    Returns:
+        The value of the attribute. If the value is a reference, it returns the
+        reference string instead of the value it is referencing.
+    """
+    try:
+        return self.__dict__["data"][attr]
+    except KeyError as e:
+        raise AttributeError(
+            "Cannot get unreferenced value from attribute {attr} that does not"
+            " exist in {self}"
+        ) from e
+
+
+
+ +
+ +
+ + +

+ iterate_components(skip_elems=None) + +

+ + +
+ +

Iterate over all QuamBase objects in this object, including nested objects.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
skip_elems + Sequence[QuamBase] + +
+

A list of QuamBase objects to skip. +This is used to prevent infinite loops when iterating over nested +objects.

+
+ 		+ None +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ Generator[QuamBase, None, None] + +
+

A generator of QuamBase objects.

+
+
+ +
+ Source code in quam/core/quam_classes.py + 
887
+888
+889
+890
+891
+892
+893
+894
+895
+896
+897
+898
+899
+900
+901
+902
+903
+904
+905
+906
+907
+908
def iterate_components(
+    self, skip_elems: Sequence[QuamBase] = None
+) -> Generator["QuamBase", None, None]:
+    """Iterate over all QuamBase objects in this object, including nested objects.
+
+    Args:
+        skip_elems: A list of QuamBase objects to skip.
+            This is used to prevent infinite loops when iterating over nested
+            objects.
+
+    Returns:
+        A generator of QuamBase objects.
+    """
+    if skip_elems is None:
+        skip_elems = []
+
+    for attr_val in self.data.values():
+        if any(attr_val is elem for elem in skip_elems):
+            continue
+
+        if isinstance(attr_val, QuamBase):
+            yield from attr_val.iterate_components(skip_elems=skip_elems)
+
+
+
+ +
+ + + +
+ +
+ +
+ +
+ + + +

+ QuamList + + +

+ + +
+

+ Bases: UserList, QuamBase

+ + +

A QuAM list class.

+

Any list added to a QuamBase object is automatically converted to a QuamList. +The QuamList adds the following functionalities to a list: +- Elements can be references (see below)

+

QuamList references

+

QuamList values can be references, which are strings that start with #. See the +documentation for details on references. An example is shown here: +

d = QuamList([1, "#./0"]])
+assert d[1] == 1
+

+ + +
+ Warning +

This class is a subclass of QuamBase, but also of UserList. As a result, +it can be used as a normal list, but it is not a subclass of list.

+
+
+ Source code in quam/core/quam_classes.py + 
 911
+ 912
+ 913
+ 914
+ 915
+ 916
+ 917
+ 918
+ 919
+ 920
+ 921
+ 922
+ 923
+ 924
+ 925
+ 926
+ 927
+ 928
+ 929
+ 930
+ 931
+ 932
+ 933
+ 934
+ 935
+ 936
+ 937
+ 938
+ 939
+ 940
+ 941
+ 942
+ 943
+ 944
+ 945
+ 946
+ 947
+ 948
+ 949
+ 950
+ 951
+ 952
+ 953
+ 954
+ 955
+ 956
+ 957
+ 958
+ 959
+ 960
+ 961
+ 962
+ 963
+ 964
+ 965
+ 966
+ 967
+ 968
+ 969
+ 970
+ 971
+ 972
+ 973
+ 974
+ 975
+ 976
+ 977
+ 978
+ 979
+ 980
+ 981
+ 982
+ 983
+ 984
+ 985
+ 986
+ 987
+ 988
+ 989
+ 990
+ 991
+ 992
+ 993
+ 994
+ 995
+ 996
+ 997
+ 998
+ 999
+1000
+1001
+1002
+1003
+1004
+1005
+1006
+1007
+1008
+1009
+1010
+1011
+1012
+1013
+1014
+1015
+1016
+1017
+1018
+1019
+1020
+1021
+1022
+1023
+1024
+1025
+1026
+1027
+1028
+1029
+1030
+1031
+1032
+1033
+1034
+1035
+1036
+1037
+1038
+1039
+1040
+1041
+1042
+1043
+1044
+1045
+1046
+1047
+1048
+1049
+1050
+1051
+1052
+1053
+1054
+1055
+1056
+1057
+1058
+1059
+1060
+1061
+1062
+1063
+1064
+1065
+1066
+1067
+1068
+1069
+1070
+1071
+1072
+1073
+1074
+1075
+1076
+1077
+1078
+1079
+1080
+1081
+1082
+1083
+1084
+1085
+1086
+1087
+1088
+1089
+1090
+1091
+1092
+1093
+1094
+1095
+1096
+1097
+1098
+1099
+1100
+1101
+1102
+1103
+1104
+1105
+1106
+1107
+1108
+1109
+1110
+1111
+1112
+1113
+1114
+1115
+1116
+1117
@quam_dataclass
+class QuamList(UserList, QuamBase):
+    """A QuAM list class.
+
+    Any list added to a `QuamBase` object is automatically converted to a `QuamList`.
+    The `QuamList` adds the following functionalities to a list:
+    - Elements can be references (see below)
+
+    # QuamList references
+    QuamList values can be references, which are strings that start with `#`. See the
+    documentation for details on references. An example is shown here:
+    ```
+    d = QuamList([1, "#./0"]])
+    assert d[1] == 1
+    ```
+
+    Warning:
+        This class is a subclass of `QuamBase`, but also of `UserList`. As a result,
+        it can be used as a normal list, but it is not a subclass of `list`.
+    """
+
+    _value_annotation: ClassVar[type] = None
+
+    def __init__(self, *args, value_annotation: type = None):
+        self._value_annotation = value_annotation
+
+        # We manually add elements using extend instead of passing to super()
+        # To ensure that any dicts and lists get converted to QuamDict and QuamList
+        super().__init__()
+        if args:
+            self.extend(*args)
+
+    # Overloading methods from UserList
+    def __eq__(self, value: object) -> bool:
+        return super().__eq__(value)
+
+    def __repr__(self) -> str:
+        with warnings.catch_warnings():
+            warnings.filterwarnings(
+                "ignore",
+                message="^Could not get reference*",
+                category=UserWarning,
+            )
+            return super().__repr__()
+
+    def __getitem__(self, i):
+        elem = super().__getitem__(i)
+        if isinstance(i, slice):
+            # This automatically gets the referenced values
+            return list(elem)
+
+        if string_reference.is_reference(elem):
+            elem = self._get_referenced_value(elem)
+        return elem
+
+    def __setitem__(self, i, item):
+        converted_item = convert_dict_and_list(item)
+        super().__setitem__(i, converted_item)
+
+        if isinstance(converted_item, QuamBase):
+            converted_item.parent = self
+
+    def __iadd__(self, other: Iterable):
+        converted_other = [convert_dict_and_list(elem) for elem in other]
+        return super().__iadd__(converted_other)
+
+    def append(self, item: Any) -> None:
+        converted_item = convert_dict_and_list(item)
+
+        if isinstance(converted_item, QuamBase):
+            converted_item.parent = self
+
+        return super().append(converted_item)
+
+    def insert(self, i: int, item: Any) -> None:
+        converted_item = convert_dict_and_list(item)
+
+        if isinstance(converted_item, QuamBase):
+            converted_item.parent = self
+
+        return super().insert(i, converted_item)
+
+    def extend(self, iterable: Iterator) -> None:
+        converted_iterable = [convert_dict_and_list(elem) for elem in iterable]
+        for converted_item in converted_iterable:
+            if isinstance(converted_item, QuamBase):
+                converted_item.parent = self
+
+        return super().extend(converted_iterable)
+
+    # Quam methods
+    def _val_matches_attr_annotation(self, attr: str, val: Any) -> bool:
+        """Check whether the type of an attribute matches the annotation.
+
+        Called by QuamList.to_dict to determine whether to add the __class__ key.
+        For the QuamList, we compare the type to the _value_annotation.
+        """
+        if isinstance(val, (QuamDict, QuamList)):
+            return True
+        if self._value_annotation is None:
+            return False
+        return type(val) == self._value_annotation
+
+    def get_attr_name(self, attr_val: Any) -> str:
+        for k, elem in enumerate(self.data):
+            if elem is attr_val:
+                return str(k)
+        else:
+            raise AttributeError(
+                "Could not find name corresponding to attribute"
+                f"attribute: {attr_val}\n"
+                f"obj: {self}"
+            )
+
+    def to_dict(
+        self, follow_references: bool = False, include_defaults: bool = False
+    ) -> list:
+        """Convert this object to a list, usually as part of a dictionary representation.
+
+        Args:
+            follow_references: Whether to follow references when getting the value.
+                If False, the reference will be returned as a string.
+            include_defaults: Whether to include attributes that have the default
+                value.
+
+        Returns:
+            A list with the values of this object. Any QuamBase objects will be
+            recursively converted to dictionaries.
+
+        Note:
+            If the value of an attribute does not match the annotation of
+            `QuamList._value_annotation`, the `"__class__"` key will be added to the
+            dictionary. This is to ensure that the object can be reconstructed when
+            loading from a file.
+        """
+        quam_list = []
+        for val in self.data:
+            if isinstance(val, QuamBase):
+                quam_list.append(
+                    val.to_dict(
+                        follow_references=follow_references,
+                        include_defaults=include_defaults,
+                    )
+                )
+                if not self._val_matches_attr_annotation(val=val, attr=None):
+                    quam_list[-1]["__class__"] = get_full_class_path(val)
+            else:
+                quam_list.append(val)
+        return quam_list
+
+    def iterate_components(
+        self, skip_elems: List[QuamBase] = None
+    ) -> Generator["QuamBase", None, None]:
+        """Iterate over all QuamBase objects in this object, including nested objects.
+
+        Args:
+            skip_elems: A list of QuamBase objects to skip.
+                This is used to prevent infinite loops when iterating over nested
+                objects.
+
+        Returns:
+            A generator of QuamBase objects.
+        """
+        if skip_elems is None:
+            skip_elems = []
+
+        for attr_val in self.data:
+            if any(attr_val is elem for elem in skip_elems):
+                continue
+
+            if isinstance(attr_val, QuamBase):
+                yield from attr_val.iterate_components(skip_elems=skip_elems)
+
+    def get_attrs(
+        self, follow_references: bool = False, include_defaults: bool = True
+    ) -> Dict[str, Any]:
+        raise NotImplementedError("QuamList does not have attributes")
+
+    def print_summary(self, indent: int = 0):
+        """Print a summary of the QuamBase object.
+
+        Args:
+            indent: The number of spaces to indent the summary.
+        """
+
+        if self.parent is None:
+            full_name = f"{self.__class__.__name__} (parent unknown):"
+        else:
+            try:
+                attr_name = self.parent.get_attr_name(self)
+                full_name = f"{attr_name}: {self.__class__.__name__}"
+            except AttributeError:
+                full_name = f"{self.__class__.__name__}:"
+
+        if not self.data:
+            print(" " * indent + f"{full_name} = []")
+            return
+
+        print(" " * indent + f"{full_name}:")
+        if len(str(self.data)) + 2 * indent < 80:
+            print(" " * (indent + 2) + f"{self.data}")
+        else:
+            for k, val in enumerate(self.data):
+                if isinstance(val, QuamBase):
+                    val.print_summary(indent=indent + 2)
+                else:
+                    print(" " * (indent + 2) + f"{k}: {val}")
+
+
+ + + +
+ + + + + + + + + +
+ + +

+ iterate_components(skip_elems=None) + +

+ + +
+ +

Iterate over all QuamBase objects in this object, including nested objects.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
skip_elems + List[QuamBase] + +
+

A list of QuamBase objects to skip. +This is used to prevent infinite loops when iterating over nested +objects.

+
+ 		+ None +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ Generator[QuamBase, None, None] + +
+

A generator of QuamBase objects.

+
+
+ +
+ Source code in quam/core/quam_classes.py + 
1061
+1062
+1063
+1064
+1065
+1066
+1067
+1068
+1069
+1070
+1071
+1072
+1073
+1074
+1075
+1076
+1077
+1078
+1079
+1080
+1081
+1082
def iterate_components(
+    self, skip_elems: List[QuamBase] = None
+) -> Generator["QuamBase", None, None]:
+    """Iterate over all QuamBase objects in this object, including nested objects.
+
+    Args:
+        skip_elems: A list of QuamBase objects to skip.
+            This is used to prevent infinite loops when iterating over nested
+            objects.
+
+    Returns:
+        A generator of QuamBase objects.
+    """
+    if skip_elems is None:
+        skip_elems = []
+
+    for attr_val in self.data:
+        if any(attr_val is elem for elem in skip_elems):
+            continue
+
+        if isinstance(attr_val, QuamBase):
+            yield from attr_val.iterate_components(skip_elems=skip_elems)
+
+
+
+ +
+ +
+ + +

+ print_summary(indent=0) + +

+ + +
+ +

Print a summary of the QuamBase object.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
indent + int + +
+

The number of spaces to indent the summary.

+
+ 		+ 0 +
+ +
+ Source code in quam/core/quam_classes.py + 
1089
+1090
+1091
+1092
+1093
+1094
+1095
+1096
+1097
+1098
+1099
+1100
+1101
+1102
+1103
+1104
+1105
+1106
+1107
+1108
+1109
+1110
+1111
+1112
+1113
+1114
+1115
+1116
+1117
def print_summary(self, indent: int = 0):
+    """Print a summary of the QuamBase object.
+
+    Args:
+        indent: The number of spaces to indent the summary.
+    """
+
+    if self.parent is None:
+        full_name = f"{self.__class__.__name__} (parent unknown):"
+    else:
+        try:
+            attr_name = self.parent.get_attr_name(self)
+            full_name = f"{attr_name}: {self.__class__.__name__}"
+        except AttributeError:
+            full_name = f"{self.__class__.__name__}:"
+
+    if not self.data:
+        print(" " * indent + f"{full_name} = []")
+        return
+
+    print(" " * indent + f"{full_name}:")
+    if len(str(self.data)) + 2 * indent < 80:
+        print(" " * (indent + 2) + f"{self.data}")
+    else:
+        for k, val in enumerate(self.data):
+            if isinstance(val, QuamBase):
+                val.print_summary(indent=indent + 2)
+            else:
+                print(" " * (indent + 2) + f"{k}: {val}")
+
+
+
+ +
+ +
+ + +

+ to_dict(follow_references=False, include_defaults=False) + +

+ + +
+ +

Convert this object to a list, usually as part of a dictionary representation.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
follow_references + bool + +
+

Whether to follow references when getting the value. +If False, the reference will be returned as a string.

+
+ 		+ False +
include_defaults + bool + +
+

Whether to include attributes that have the default +value.

+
+ 		+ False +
+ + +

Returns:

+ + + + + + + + + + + + + + + + + +
TypeDescription
+ list + +
+

A list with the values of this object. Any QuamBase objects will be

+
+
+ list + +
+

recursively converted to dictionaries.

+
+
+ + +
+ Note +

If the value of an attribute does not match the annotation of +QuamList._value_annotation, the "__class__" key will be added to the +dictionary. This is to ensure that the object can be reconstructed when +loading from a file.

+
+
+ Source code in quam/core/quam_classes.py + 
1025
+1026
+1027
+1028
+1029
+1030
+1031
+1032
+1033
+1034
+1035
+1036
+1037
+1038
+1039
+1040
+1041
+1042
+1043
+1044
+1045
+1046
+1047
+1048
+1049
+1050
+1051
+1052
+1053
+1054
+1055
+1056
+1057
+1058
+1059
def to_dict(
+    self, follow_references: bool = False, include_defaults: bool = False
+) -> list:
+    """Convert this object to a list, usually as part of a dictionary representation.
+
+    Args:
+        follow_references: Whether to follow references when getting the value.
+            If False, the reference will be returned as a string.
+        include_defaults: Whether to include attributes that have the default
+            value.
+
+    Returns:
+        A list with the values of this object. Any QuamBase objects will be
+        recursively converted to dictionaries.
+
+    Note:
+        If the value of an attribute does not match the annotation of
+        `QuamList._value_annotation`, the `"__class__"` key will be added to the
+        dictionary. This is to ensure that the object can be reconstructed when
+        loading from a file.
+    """
+    quam_list = []
+    for val in self.data:
+        if isinstance(val, QuamBase):
+            quam_list.append(
+                val.to_dict(
+                    follow_references=follow_references,
+                    include_defaults=include_defaults,
+                )
+            )
+            if not self._val_matches_attr_annotation(val=val, attr=None):
+                quam_list[-1]["__class__"] = get_full_class_path(val)
+        else:
+            quam_list.append(val)
+    return quam_list
+
+
+
+ +
+ + + +
+ +
+ +
+ + + + +
+ +
+ +
+ + + + + + + + + + + + + +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API_references/core/quam_instantiation/index.html b/API_references/core/quam_instantiation/index.html new file mode 100644 index 00000000..4f641590 --- /dev/null +++ b/API_references/core/quam_instantiation/index.html @@ -0,0 +1,2279 @@ + + + + + + + + + + + + + + + + + + + + + Quam instantiation - The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ + + + +

Quam instantiation

+ +
+ + + + +
+ + + +
+ + + + + + + + + +
+ + +

+ instantiate_attr(attr_val, expected_type, allow_none=False, fix_attrs=True, validate_type=True, str_repr='') + +

+ + +
+ +

Instantiate a single attribute which may be a QuamComponent

+ + +
+ The attribute instantiation behaviour depends on the required attribute type +
    +
  • If the required type is a QuamComponent -> instantiate the QuamComponent
    • +
  • If the required type is a dict -> instantiate all elements of the dict
    • +
  • If the required type is a list -> instantiate all elements of the list
    • +
  • Otherwise, the attribute is not instantiated
    • +
+

Note that references and None are not instantiated, nor validated.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
attr_val + +
+

The value of the to instantiate.

+
+ 		+ required +
required_type + +
+

The required type of the attribute.

+
+ 		+ required +
allow_none + bool + +
+

Whether None is allowed as a value even if it's the wrong type.

+
+ 		+ False +
fix_attrs + bool + +
+

Whether to only allow attributes that have been defined in the class +Only included because it's passed on when instantiating QuamComponents.

+
+ 		+ True +
validate_type + bool + +
+

Whether to validate the type of the attributes. +If True, a TypeError is raised if an attribute has the wrong type.

+
+ 		+ True +
str_repr + str + +
+

A string representation of the object, used for error messages.

+
+ 		+ '' +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ +
+

The instantiated attribute.

+
+
+ +
+ Source code in quam/core/quam_instantiation.py + 
121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
+182
+183
+184
+185
+186
+187
+188
+189
+190
+191
+192
+193
+194
+195
+196
+197
+198
+199
+200
+201
+202
+203
+204
+205
+206
+207
+208
+209
+210
+211
+212
+213
+214
+215
+216
+217
+218
+219
+220
+221
+222
+223
+224
+225
+226
+227
+228
+229
+230
+231
+232
+233
+234
+235
+236
+237
+238
+239
+240
+241
+242
+243
+244
+245
def instantiate_attr(
+    attr_val,
+    expected_type: type,
+    allow_none: bool = False,
+    fix_attrs: bool = True,
+    validate_type: bool = True,
+    str_repr: str = "",
+):
+    """Instantiate a single attribute which may be a QuamComponent
+
+    The attribute instantiation behaviour depends on the required attribute type:
+        - If the required type is a QuamComponent -> instantiate the QuamComponent
+        - If the required type is a dict -> instantiate all elements of the dict
+        - If the required type is a list -> instantiate all elements of the list
+        - Otherwise, the attribute is not instantiated
+
+    Note that references and None are not instantiated, nor validated.
+
+    Args:
+        attr_val: The value of the to instantiate.
+        required_type: The required type of the attribute.
+        allow_none: Whether None is allowed as a value even if it's the wrong type.
+        fix_attrs: Whether to only allow attributes that have been defined in the class
+            Only included because it's passed on when instantiating QuamComponents.
+        validate_type: Whether to validate the type of the attributes.
+            If True, a TypeError is raised if an attribute has the wrong type.
+        str_repr: A string representation of the object, used for error messages.
+
+    Returns:
+        The instantiated attribute.
+    """
+    from quam.core import QuamComponent  # noqa: F811
+
+    # Convert Optional[T] to T with allow_none=True
+    if type_is_optional(expected_type):
+        expected_type = typing.get_args(expected_type)[0]
+        allow_none = True
+
+    if string_reference.is_reference(attr_val):
+        # Value is a reference, add without instantiating
+        instantiated_attr = attr_val
+    elif attr_val is None:
+        instantiated_attr = attr_val
+    elif isclass(expected_type) and issubclass(expected_type, QuamComponent):
+        instantiated_attr = instantiate_quam_class(
+            quam_class=expected_type,
+            contents=attr_val,
+            fix_attrs=fix_attrs,
+            validate_type=validate_type,
+            str_repr=str_repr,
+        )
+    elif isinstance(attr_val, dict) and "__class__" in attr_val:
+        instantiated_attr = instantiate_quam_class(
+            quam_class=expected_type,
+            contents=attr_val,
+            fix_attrs=fix_attrs,
+            validate_type=validate_type,
+            str_repr=str_repr,
+        )
+    elif isinstance(expected_type, dict) or typing.get_origin(expected_type) == dict:
+        instantiated_attr = instantiate_attrs_from_dict(
+            attr_dict=attr_val,
+            required_type=expected_type,
+            fix_attrs=fix_attrs,
+            validate_type=validate_type,
+            str_repr=str_repr,
+        )
+        if typing.get_origin(expected_type) == dict:
+            expected_type = dict
+    elif typing.get_origin(expected_type) in union_types:
+        for union_type in typing.get_args(expected_type):
+            try:
+                instantiated_attr = instantiate_attr(
+                    attr_val=attr_val,
+                    expected_type=union_type,
+                    allow_none=allow_none,
+                    fix_attrs=fix_attrs,
+                    validate_type=validate_type,
+                    str_repr=str_repr,
+                )
+                break
+            except TypeError:
+                continue
+        else:
+            raise TypeError(
+                f"Could not instantiate {str_repr} with any of the types in {expected_type}"
+            )
+    elif (
+        isinstance(expected_type, list)
+        or typing.get_origin(expected_type) == list
+        or isinstance(attr_val, list)
+    ):
+        instantiated_attr = instantiate_attrs_from_list(
+            attr_list=attr_val,
+            required_type=expected_type,
+            fix_attrs=fix_attrs,
+            validate_type=validate_type,
+            str_repr=str_repr,
+        )
+        if typing.get_origin(expected_type) == list:
+            expected_type = list
+        elif typing.get_origin(expected_type) == tuple:
+            instantiated_attr = tuple(instantiated_attr)
+    elif typing.get_origin(expected_type) == tuple:
+        if isinstance(attr_val, list):
+            attr_val = tuple(attr_val)
+        instantiated_attr = attr_val
+    elif typing.get_origin(expected_type) == typing.Literal:
+        instantiated_attr = attr_val
+    elif typing.get_origin(expected_type) is not None and validate_type:
+        raise TypeError(
+            f"Instantiation for type {expected_type} in {str_repr} not implemented"
+        )
+    else:
+        instantiated_attr = attr_val
+
+    if validate_type:
+        # TODO Add logic that required attributes cannot be None
+        validate_obj_type(
+            elem=instantiated_attr,
+            required_type=expected_type,
+            allow_none=allow_none,
+            str_repr=str_repr,
+        )
+    return instantiated_attr
+
+
+
+ +
+ +
+ + +

+ instantiate_attrs(attr_annotations, contents, fix_attrs=True, validate_type=True, str_repr='') + +

+ + +
+ +

Instantiate attributes if they are or contain QuamComponents

+

Dictionaries and lists are instantiated recursively

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
attr_annotations + Dict[str, Dict[str, type]] + +
+

The attributes of the QuamComponent or QuamDict +together with their types. Grouped into "required", "optional" and "allowed"

+
+ 		+ required +
contents + dict + +
+

The attr contents of the QuamRoot, QuamComponent or QuamDict.

+
+ 		+ required +
fix_attrs + bool + +
+

Whether to only allow attributes that have been defined in the +class definition. If False, any attribute can be set. +QuamDicts are never fixed.

+
+ 		+ True +
validate_type + bool + +
+

Whether to validate the type of the attributes. +A TypeError is raised if an attribute has the wrong type.

+
+ 		+ True +
str_repr + str + +
+

A string representation of the object, used for error messages.

+
+ 		+ '' +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ Dict[str, Any] + +
+

A dictionary where each element has been instantiated if it is a QuamComponent

+
+
+ +
+ Source code in quam/core/quam_instantiation.py + 
248
+249
+250
+251
+252
+253
+254
+255
+256
+257
+258
+259
+260
+261
+262
+263
+264
+265
+266
+267
+268
+269
+270
+271
+272
+273
+274
+275
+276
+277
+278
+279
+280
+281
+282
+283
+284
+285
+286
+287
+288
+289
+290
+291
+292
+293
+294
+295
+296
+297
+298
+299
+300
+301
+302
+303
+304
+305
+306
+307
+308
+309
+310
def instantiate_attrs(
+    attr_annotations: Dict[str, Dict[str, type]],
+    contents: dict,
+    fix_attrs: bool = True,
+    validate_type: bool = True,
+    str_repr: str = "",
+) -> Dict[str, Any]:
+    """Instantiate attributes if they are or contain QuamComponents
+
+    Dictionaries and lists are instantiated recursively
+
+    Args:
+        attr_annotations: The attributes of the QuamComponent or QuamDict
+            together with their types. Grouped into "required", "optional" and "allowed"
+        contents: The attr contents of the QuamRoot, QuamComponent or QuamDict.
+        fix_attrs: Whether to only allow attributes that have been defined in the
+            class definition. If False, any attribute can be set.
+            QuamDicts are never fixed.
+        validate_type: Whether to validate the type of the attributes.
+            A TypeError is raised if an attribute has the wrong type.
+        str_repr: A string representation of the object, used for error messages.
+
+    Returns:
+        A dictionary where each element has been instantiated if it is a QuamComponent
+    """
+    instantiated_attrs = {"required": {}, "optional": {}, "extra": {}}
+    for attr_name, attr_val in contents.items():
+        if attr_name == "__class__":
+            continue
+        if attr_name not in attr_annotations["allowed"]:
+            if not fix_attrs:
+                instantiated_attrs["extra"][attr_name] = attr_val
+                continue
+            raise AttributeError(
+                f"Attribute {attr_name} is not a valid attr of {str_repr}"
+            )
+
+        if isinstance(attr_val, dict) and "__class__" in attr_val:
+            expected_type = get_class_from_path(attr_val["__class__"])
+        else:
+            expected_type = attr_annotations["allowed"][attr_name]
+
+        instantiated_attr = instantiate_attr(
+            attr_val=attr_val,
+            expected_type=expected_type,
+            allow_none=attr_name not in attr_annotations["required"],
+            fix_attrs=fix_attrs,
+            validate_type=validate_type,
+            str_repr=f"{str_repr}.{attr_name}",
+        )
+
+        if attr_name in attr_annotations["required"]:
+            instantiated_attrs["required"][attr_name] = instantiated_attr
+        else:
+            instantiated_attrs["optional"][attr_name] = instantiated_attr
+
+    missing_attrs = set(attr_annotations["required"]) - set(
+        instantiated_attrs["required"]
+    )
+    if missing_attrs:
+        raise AttributeError(f"Missing required attrs {missing_attrs} for {str_repr}")
+
+    return instantiated_attrs
+
+
+
+ +
+ +
+ + +

+ instantiate_attrs_from_dict(attr_dict, required_type, fix_attrs=True, validate_type=True, str_repr='') + +

+ + +
+ +

Instantiate the QuamComponent attributes in a dict

+

QuamComponents are only instantiated if required_type is typing.Dict and the value +subtype is a QuamComponent. In this case, the value is instantiated as a +QuamComponent. +Otherwise, no QuamComponents are instantiated.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
attr_dict + dict + +
+

The attributes to instantiate.

+
+ 		+ required +
required_type + type + +
+

The required type of the attributes, either dict or typing.Dict.

+
+ 		+ required +
fix_attrs + bool + +
+

Whether to only allow attributes that have been defined in the class +Only included because it's passed on when instantiating QuamComponents.

+
+ 		+ True +
validate_type + bool + +
+

Whether to validate the type of the attributes. +A TypeError is raised if an attribute has the wrong type.

+
+ 		+ True +
str_repr + str + +
+

A string representation of the object, used for error messages.

+
+ 		+ '' +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ dict + +
+

A dictionary with the instantiated attributes.

+
+
+ +
+ Source code in quam/core/quam_instantiation.py + 
27
+28
+29
+30
+31
+32
+33
+34
+35
+36
+37
+38
+39
+40
+41
+42
+43
+44
+45
+46
+47
+48
+49
+50
+51
+52
+53
+54
+55
+56
+57
+58
+59
+60
+61
+62
+63
+64
+65
+66
+67
+68
+69
+70
+71
def instantiate_attrs_from_dict(
+    attr_dict: dict,
+    required_type: type,
+    fix_attrs: bool = True,
+    validate_type: bool = True,
+    str_repr: str = "",
+) -> dict:
+    """Instantiate the QuamComponent attributes in a dict
+
+    QuamComponents are only instantiated if required_type is typing.Dict and the value
+    subtype is a QuamComponent. In this case, the value is instantiated as a
+    QuamComponent.
+    Otherwise, no QuamComponents are instantiated.
+
+    Args:
+        attr_dict: The attributes to instantiate.
+        required_type: The required type of the attributes, either dict or typing.Dict.
+        fix_attrs: Whether to only allow attributes that have been defined in the class
+            Only included because it's passed on when instantiating QuamComponents.
+        validate_type: Whether to validate the type of the attributes.
+            A TypeError is raised if an attribute has the wrong type.
+        str_repr: A string representation of the object, used for error messages.
+
+    Returns:
+        A dictionary with the instantiated attributes.
+    """
+    from quam.core import QuamComponent  # noqa: F811
+
+    if typing.get_origin(required_type) == dict:
+        required_subtype = typing.get_args(required_type)[1]
+    else:
+        required_subtype = None
+
+    instantiated_attr_dict = {}
+    for attr_name, attr_val in attr_dict.items():
+        instantiated_attr_dict[attr_name] = instantiate_attr(
+            attr_val=attr_val,
+            expected_type=required_subtype,
+            allow_none=False,
+            fix_attrs=fix_attrs,
+            validate_type=validate_type if required_subtype is not None else False,
+            str_repr=f'{str_repr}["{attr_name}"]',
+        )
+
+    return instantiated_attr_dict
+
+
+
+ +
+ +
+ + +

+ instantiate_attrs_from_list(attr_list, required_type, fix_attrs=True, validate_type=True, str_repr='') + +

+ + +
+ +

Instantiate the QuamComponent attributes in a list

+

QuamComponents are only instantiated if required_type is typing.List and the subtype +is a QuamComponent. In this case, the value is instantiated as a QuamComponent. +Otherwise, no QuamComponents are instantiated.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
attr_list + list + +
+

The attributes to instantiate.

+
+ 		+ required +
required_type + type + +
+

The required type of the attributes, either list or typing.List.

+
+ 		+ required +
fix_attrs + bool + +
+

Whether to only allow attributes that have been defined in the class +Only included because it's passed on when instantiating QuamComponents.

+
+ 		+ True +
validate_type + bool + +
+

Whether to validate the type of the attributes. +A TypeError is raised if an attribute has the wrong type.

+
+ 		+ True +
str_repr + str + +
+

A string representation of the object, used for error messages.

+
+ 		+ '' +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ list + +
+

A list with the instantiated attributes.

+
+
+ +
+ Source code in quam/core/quam_instantiation.py + 
 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
def instantiate_attrs_from_list(
+    attr_list: list,
+    required_type: type,
+    fix_attrs: bool = True,
+    validate_type: bool = True,
+    str_repr: str = "",
+) -> list:
+    """Instantiate the QuamComponent attributes in a list
+
+    QuamComponents are only instantiated if required_type is typing.List and the subtype
+    is a QuamComponent. In this case, the value is instantiated as a QuamComponent.
+    Otherwise, no QuamComponents are instantiated.
+
+    Args:
+        attr_list: The attributes to instantiate.
+        required_type: The required type of the attributes, either list or typing.List.
+        fix_attrs: Whether to only allow attributes that have been defined in the class
+            Only included because it's passed on when instantiating QuamComponents.
+        validate_type: Whether to validate the type of the attributes.
+            A TypeError is raised if an attribute has the wrong type.
+        str_repr: A string representation of the object, used for error messages.
+
+    Returns:
+        A list with the instantiated attributes.
+    """
+    from quam.core import QuamComponent  # noqa: F811
+
+    if typing.get_origin(required_type) == list:
+        required_subtype = typing.get_args(required_type)[0]
+    else:
+        required_subtype = None
+
+    instantiated_attr_list = []
+    for k, attr_val in enumerate(attr_list):
+        instantiated_attr_list.append(
+            instantiate_attr(
+                attr_val=attr_val,
+                expected_type=required_subtype,
+                allow_none=False,
+                fix_attrs=fix_attrs,
+                validate_type=validate_type if required_subtype is not None else False,
+                str_repr=f"{str_repr}[{k}]",
+            )
+        )
+    return instantiated_attr_list
+
+
+
+ +
+ +
+ + +

+ instantiate_quam_class(quam_class, contents, fix_attrs=True, validate_type=True, str_repr='') + +

+ + +
+ +

Instantiate a QuamBase from a dict

+

Note that any nested QuamBases are instantiated recursively

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
quam_class + type[QuamBase] + +
+

QuamBase class to instantiate

+
+ 		+ required +
contents + dict + +
+

dict of attributes to instantiate the QuamBase with

+
+ 		+ required +
fix_attrs + bool + +
+

Whether to only allow attributes that have been defined in the class +definition. If False, any attribute can be set. +QuamDicts are never fixed.

+
+ 		+ True +
validate_type + bool + +
+

Whether to validate the type of the attributes. +A TypeError is raised if an attribute has the wrong type.

+
+ 		+ True +
str_repr + str + +
+

A string representation of the object, used for error messages.

+
+ 		+ '' +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ QuamBase + +
+

QuamBase instance

+
+
+ +
+ Source code in quam/core/quam_instantiation.py + 
313
+314
+315
+316
+317
+318
+319
+320
+321
+322
+323
+324
+325
+326
+327
+328
+329
+330
+331
+332
+333
+334
+335
+336
+337
+338
+339
+340
+341
+342
+343
+344
+345
+346
+347
+348
+349
+350
+351
+352
+353
+354
+355
+356
+357
+358
+359
+360
+361
+362
+363
+364
+365
+366
+367
+368
+369
+370
+371
+372
+373
+374
+375
+376
+377
def instantiate_quam_class(
+    quam_class: type[QuamBase],
+    contents: dict,
+    fix_attrs: bool = True,
+    validate_type: bool = True,
+    str_repr: str = "",
+) -> QuamBase:
+    """Instantiate a QuamBase from a dict
+
+    Note that any nested QuamBases are instantiated recursively
+
+    Args:
+        quam_class: QuamBase class to instantiate
+        contents: dict of attributes to instantiate the QuamBase with
+        fix_attrs: Whether to only allow attributes that have been defined in the class
+            definition. If False, any attribute can be set.
+            QuamDicts are never fixed.
+        validate_type: Whether to validate the type of the attributes.
+            A TypeError is raised if an attribute has the wrong type.
+        str_repr: A string representation of the object, used for error messages.
+
+    Returns:
+        QuamBase instance
+    """
+    # Add depcrecation checks
+    for deprecation_rule in instantiation_deprecations:
+        if deprecation_rule.match(quam_class=quam_class, contents=contents):
+            quam_class, contents = deprecation_rule.apply(
+                quam_class=quam_class, contents=contents
+            )
+
+    if not str_repr:
+        str_repr = quam_class.__name__
+    # str_repr = f"{str_repr}.{quam_class.__name__}" if str_repr else quam_class.__name__
+
+    if "__class__" in contents:
+        quam_class = get_class_from_path(contents["__class__"])
+
+    if not isinstance(contents, dict):
+        raise TypeError(
+            f"contents must be a dict, not {type(contents)}, could not instantiate"
+            f" {str_repr}. Contents: {contents}"
+        )
+
+    attr_annotations = get_dataclass_attr_annotations(quam_class)
+
+    instantiated_attrs = instantiate_attrs(
+        attr_annotations=attr_annotations,
+        contents=contents,
+        fix_attrs=fix_attrs,
+        validate_type=validate_type,
+        str_repr=str_repr,
+    )
+
+    quam_component = quam_class(
+        **{**instantiated_attrs["required"], **instantiated_attrs["optional"]}
+    )
+
+    if fix_attrs:
+        assert not instantiated_attrs["extra"]
+    else:
+        for attr, val in instantiated_attrs["extra"].items():
+            setattr(quam_component, attr, val)
+
+    return quam_component
+
+
+
+ +
+ + + +
+ +
+ +
+ + + + + + + + + + + + + +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API_references/examples/superconducting_qubits/components/index.html b/API_references/examples/superconducting_qubits/components/index.html new file mode 100644 index 00000000..d867e824 --- /dev/null +++ b/API_references/examples/superconducting_qubits/components/index.html @@ -0,0 +1,1033 @@ + + + + + + + + + + + + + + + + + + + + + Components - The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ + + + +

Components

+ +
+ + + + +
+ + + +
+ + + + + + + + +
+ + + +

+ QuAM + + +

+ + +
+

+ Bases: QuamRoot

+ + +

Example QuAM root component.

+ +
+ Source code in quam/examples/superconducting_qubits/components.py + 
27
+28
+29
+30
+31
+32
@quam_dataclass
+class QuAM(QuamRoot):
+    """Example QuAM root component."""
+
+    qubits: Dict[str, Transmon] = field(default_factory=dict)
+    wiring: dict = field(default_factory=dict)
+
+
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ +
+ + + +

+ Transmon + + +

+ + +
+

+ Bases: QuamComponent

+ + +

Example QuAM component for a transmon qubit.

+ +
+ Source code in quam/examples/superconducting_qubits/components.py + 
11
+12
+13
+14
+15
+16
+17
+18
+19
+20
+21
+22
+23
+24
@quam_dataclass
+class Transmon(QuamComponent):
+    """Example QuAM component for a transmon qubit."""
+
+    id: Union[int, str]
+
+    xy: IQChannel = None
+    z: SingleChannel = None
+
+    resonator: InOutIQChannel = None
+
+    @property
+    def name(self):
+        return self.id if isinstance(self.id, str) else f"q{self.id}"
+
+
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ + + + +
+ +
+ +
+ + + + + + + + + + + + + +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API_references/examples/superconducting_qubits/generate_superconducting_quam/index.html b/API_references/examples/superconducting_qubits/generate_superconducting_quam/index.html new file mode 100644 index 00000000..f54babe0 --- /dev/null +++ b/API_references/examples/superconducting_qubits/generate_superconducting_quam/index.html @@ -0,0 +1,1091 @@ + + + + + + + + + + + + + + + + + + + + + Generate superconducting quam - The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ + + + +

Generate superconducting quam

+ +
+ + + + +
+ + + +
+ + + + + + + + + +
+ + +

+ create_quam_superconducting_referenced(num_qubits) + +

+ + +
+ +

Create a QuAM with a number of qubits.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
num_qubits + int + +
+

Number of qubits to create.

+
+ 		+ required +
+ + +

Returns:

+ + + + + + + + + + + + + +
Name TypeDescription
QuamRoot + QuamRoot + +
+

A QuAM with the specified number of qubits.

+
+
+ +
+ Source code in quam/examples/superconducting_qubits/generate_superconducting_quam.py + 
10
+11
+12
+13
+14
+15
+16
+17
+18
+19
+20
+21
+22
+23
+24
+25
+26
+27
+28
+29
+30
+31
+32
+33
+34
+35
+36
+37
+38
+39
+40
+41
+42
+43
+44
+45
+46
+47
+48
+49
+50
+51
+52
+53
+54
+55
+56
+57
+58
+59
+60
+61
+62
+63
+64
def create_quam_superconducting_referenced(num_qubits: int) -> QuamRoot:
+    """Create a QuAM with a number of qubits.
+
+    Args:
+        num_qubits (int): Number of qubits to create.
+
+    Returns:
+        QuamRoot: A QuAM with the specified number of qubits.
+    """
+    machine = QuAM()
+    machine.wiring = {
+        "qubits": {
+            f"q{idx}": {
+                "port_I": ("con1", 3 * idx + 3),
+                "port_Q": ("con1", 3 * idx + 4),
+                "port_Z": ("con1", 3 * idx + 5),
+            }
+            for idx in range(num_qubits)
+        },
+        "feedline": {
+            "opx_output_I": ("con1", 1),
+            "opx_output_Q": ("con1", 2),
+            "opx_input_I": ("con1", 1),
+            "opx_input_Q": ("con1", 2),
+        },
+    }
+
+    for idx in range(num_qubits):
+        # Create qubit components
+        transmon = Transmon(id=idx)
+        machine.qubits[transmon.name] = transmon
+
+        transmon.xy = IQChannel(
+            opx_output_I=f"#/wiring/qubits/q{idx}/port_I",
+            opx_output_Q=f"#/wiring/qubits/q{idx}/port_Q",
+            frequency_converter_up=FrequencyConverter(
+                mixer=Mixer(),
+                local_oscillator=LocalOscillator(power=10, frequency=6e9),
+            ),
+            intermediate_frequency=100e6,
+        )
+
+        transmon.z = SingleChannel(opx_output=f"#/wiring/qubits/q{idx}/port_Z")
+
+        transmon.resonator = InOutIQChannel(
+            id=idx,
+            opx_output_I="#/wiring/feedline/opx_output_I",
+            opx_output_Q="#/wiring/feedline/opx_output_Q",
+            opx_input_I="#/wiring/feedline/opx_input_I",
+            opx_input_Q="#/wiring/feedline/opx_input_Q",
+            frequency_converter_up=FrequencyConverter(
+                mixer=Mixer(), local_oscillator=LocalOscillator(power=10, frequency=6e9)
+            )
+        )
+    return machine
+
+
+
+ +
+ + + +
+ +
+ +
+ + + + + + + + + + + + + +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API_references/index.html b/API_references/index.html new file mode 100644 index 00000000..774f40a9 --- /dev/null +++ b/API_references/index.html @@ -0,0 +1,966 @@ + + + + + + + + + + + + + + + + + + + + + + + + + QuAM API Reference - The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ + + + +

QuAM API Reference

+

Welcome to the API Reference section of the Quantum Abstract Machine (QuAM) documentation. Here, you'll find comprehensive details on all components, classes, and methods that make up the QuAM framework. This documentation is designed to help developers understand and effectively utilize the powerful capabilities of QuAM for quantum computing applications.

+ + + + + + + + + + + + + + + +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API_references/serialisation/base/index.html b/API_references/serialisation/base/index.html new file mode 100644 index 00000000..db0dde1f --- /dev/null +++ b/API_references/serialisation/base/index.html @@ -0,0 +1,979 @@ + + + + + + + + + + + + + + + + + + + + + Base - The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ + + + +

Base

+ +
+ + + + +
+ + + +
+ + + + + + + + +
+ + + +

+ AbstractSerialiser + + +

+ + +
+ + +

Base class for serialisers.

+ +
+ Source code in quam/serialisation/base.py + 
 9
+10
+11
+12
+13
+14
+15
+16
+17
+18
+19
+20
+21
+22
+23
class AbstractSerialiser:
+    """Base class for serialisers."""
+    def save(
+        self,
+        path: Union[Path, str],
+        quam_obj: Union[QuamRoot, QuamComponent],
+        content_mapping: Dict[str, str] = None,
+    ):
+        raise NotImplementedError
+
+    def load(
+        self,
+        path: Union[Path, str] = None,
+    ):
+        raise NotImplementedError
+
+
+ + + +
+ + + + + + + + + + + +
+ +
+ +
+ + + + +
+ +
+ +
+ + + + + + + + + + + + + +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API_references/serialisation/json/index.html b/API_references/serialisation/json/index.html new file mode 100644 index 00000000..ff3c7da3 --- /dev/null +++ b/API_references/serialisation/json/index.html @@ -0,0 +1,1725 @@ + + + + + + + + + + + + + + + + + + + + + Json - The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ + + + +

Json

+ +
+ + + + +
+ + + +
+ + + + + + + + +
+ + + +

+ JSONSerialiser + + +

+ + +
+

+ Bases: AbstractSerialiser

+ + +

Serialiser for QuAM objects to JSON files.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
default_filename + +
+

The default filename to save to when no filename is provided.

+
+ 		+ required +
default_foldername + +
+

The default foldername to save to when no folder is +provided. Only used when saving components to separate files, i.e. when +component_mapping is provided.

+
+ 		+ required +
content_mapping + +
+

A dictionary mapping filenames to the keys of the contents +to be saved to that file. If not provided, all contents are saved to the +default file, otherwise a folder is created and the default file is saved +to that folder, and the contents are saved to the files specified in the +mapping.

+
+ 		+ required +
+ +
+ Source code in quam/serialisation/json.py + 
 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
+182
+183
+184
+185
class JSONSerialiser(AbstractSerialiser):
+    """Serialiser for QuAM objects to JSON files.
+
+    Args:
+        default_filename: The default filename to save to when no filename is provided.
+        default_foldername: The default foldername to save to when no folder is
+            provided. Only used when saving components to separate files, i.e. when
+            `component_mapping` is provided.
+        content_mapping: A dictionary mapping filenames to the keys of the contents
+            to be saved to that file. If not provided, all contents are saved to the
+            default file, otherwise a folder is created and the default file is saved
+            to that folder, and the contents are saved to the files specified in the
+            mapping.
+    """
+
+    default_filename = "state.json"
+    default_foldername = "quam"
+    content_mapping = {}
+
+    def _save_dict_to_json(self, contents: Dict[str, Any], path: Path):
+        """Save a dictionary to a JSON file.
+
+        Args:
+            contents: The dictionary to save.
+            path: The path to save to.
+        """
+        with open(path, "w") as f:
+            json.dump(contents, f, indent=4)
+
+    def _parse_path(
+        self,
+        path: Union[Path, str],
+        content_mapping: Dict[Union[Path, str], Sequence[str]] = None,
+    ) -> (Path, str):
+        """Parse the path to determine the folder and filename to save to.
+
+        See JSONSerialiser.save for details on allowed path types.
+
+        Args:
+            path: The path to parse.
+            content_mapping: The content mapping to use.
+        """
+        if isinstance(path, str):
+            path = Path(path)
+
+        if path is None:
+            default_filename = self.default_filename
+            if not content_mapping:
+                folder = Path(".")
+            elif not all(isinstance(elem, Path) for elem in content_mapping):
+                folder = Path(".")
+            elif not all(elem.is_absolute() for elem in content_mapping):
+                folder = Path(".")
+            else:
+                folder = self.default_foldername
+        elif path.suffix == ".json":
+            default_filename = path.name
+            folder = path.parent
+        elif not path.suffix:
+            default_filename = self.default_filename
+            folder = path
+        else:
+            raise ValueError(f"Path {path} is not a valid JSON path or folder.")
+
+        return Path(folder), default_filename
+
+    def save(
+        self,
+        quam_obj: QuamRoot,
+        path: Union[Path, str] = None,
+        content_mapping: Dict[Union[Path, str], Sequence[str]] = None,
+        include_defaults: bool = False,
+        ignore: Sequence[str] = None,
+    ):
+        """Save a QuamRoot object to a JSON file.
+
+        The save location depends on the path provided and the content_mapping.
+            No path, no component mapping -> save to default file
+            No path, component mapping -> Create folder, save to default file,
+                save components separately
+            JSON Path, no component mapping -> Save to json file
+            JSON Path, component mapping -> Save to json file, save components
+                separately
+            Folder Path, no component mapping -> Create folder, save to default file
+            Folder Path, component mapping -> Create folder, save to default file,
+                save components separately
+
+            self.default_filename when content_mapping != None or no path provided
+            self.default_foldername when content_mapping != None and path is not a
+                folder
+        """
+        content_mapping = content_mapping or self.content_mapping
+        content_mapping = content_mapping.copy()
+
+        contents = quam_obj.to_dict(include_defaults=include_defaults)
+
+        # TODO This should ideally go to the QuamRoot.to_dict method
+        for key in ignore or []:
+            contents.pop(key, None)
+
+        folder, default_filename = self._parse_path(path, content_mapping)
+
+        folder.mkdir(exist_ok=True)
+
+        content_mapping = content_mapping.copy()
+        for component_file, components in content_mapping.items():
+            if isinstance(components, str):
+                components = [components]
+
+            if ignore is not None:
+                components = [elem for elem in components if elem not in ignore]
+            if not components:
+                continue
+
+            subcomponents = {}
+            for component in components:
+                subcomponents[component] = contents.pop(component)
+
+            if isinstance(component_file, Path) and component_file.is_absolute():
+                component_filepath = component_file
+            else:
+                component_filepath = folder / component_file
+            self._save_dict_to_json(subcomponents, component_filepath)
+
+        self._save_dict_to_json(contents, folder / default_filename)
+
+    def load(
+        self,
+        path: Union[Path, str] = None,
+    ) -> Dict[str, Any]:
+        """Load a dictionary representation of a QuamRoot object from a JSON file.
+
+        Args:
+            path: The path to load from. If a folder is provided, the contents from all
+                JSON files in that folder are loaded and merged into a dictionary.
+                If a JSON file is provided, the contents of that file are loaded.
+
+        Returns:
+            A dictionary representation of the QuamRoot object.
+        """
+        path = Path(path)
+        contents = {}
+        metadata = {
+            "content_mapping": {},
+            "default_filename": None,
+            "default_foldername": None,
+        }
+
+        if not path.exists():
+            raise FileNotFoundError(f"Path {path} not found, cannot load JSON.")
+
+        if path.is_file():
+            if not path.suffix == ".json":
+                raise TypeError(f"File {path} is not a JSON file.")
+
+            metadata["default_filename"] = path.name
+            with open(path, "r") as f:
+                contents = json.load(f, object_hook=convert_int_keys)
+        elif path.is_dir():
+            metadata["default_foldername"] = str(path)
+            for file in path.iterdir():
+                if not file.suffix == ".json":
+                    continue
+
+                with open(file, "r") as f:
+                    file_contents = json.load(f, object_hook=convert_int_keys)
+                contents.update(file_contents)
+
+                if file.name == self.default_filename:
+                    metadata["default_filename"] = file.name
+                else:
+                    metadata["content_mapping"][file.name] = list(file_contents.keys())
+
+        return contents, metadata
+
+
+ + + +
+ + + + + + + + + +
+ + +

+ load(path=None) + +

+ + +
+ +

Load a dictionary representation of a QuamRoot object from a JSON file.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
path + Union[Path, str] + +
+

The path to load from. If a folder is provided, the contents from all +JSON files in that folder are loaded and merged into a dictionary. +If a JSON file is provided, the contents of that file are loaded.

+
+ 		+ None +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ Dict[str, Any] + +
+

A dictionary representation of the QuamRoot object.

+
+
+ +
+ Source code in quam/serialisation/json.py + 
138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
+182
+183
+184
+185
def load(
+    self,
+    path: Union[Path, str] = None,
+) -> Dict[str, Any]:
+    """Load a dictionary representation of a QuamRoot object from a JSON file.
+
+    Args:
+        path: The path to load from. If a folder is provided, the contents from all
+            JSON files in that folder are loaded and merged into a dictionary.
+            If a JSON file is provided, the contents of that file are loaded.
+
+    Returns:
+        A dictionary representation of the QuamRoot object.
+    """
+    path = Path(path)
+    contents = {}
+    metadata = {
+        "content_mapping": {},
+        "default_filename": None,
+        "default_foldername": None,
+    }
+
+    if not path.exists():
+        raise FileNotFoundError(f"Path {path} not found, cannot load JSON.")
+
+    if path.is_file():
+        if not path.suffix == ".json":
+            raise TypeError(f"File {path} is not a JSON file.")
+
+        metadata["default_filename"] = path.name
+        with open(path, "r") as f:
+            contents = json.load(f, object_hook=convert_int_keys)
+    elif path.is_dir():
+        metadata["default_foldername"] = str(path)
+        for file in path.iterdir():
+            if not file.suffix == ".json":
+                continue
+
+            with open(file, "r") as f:
+                file_contents = json.load(f, object_hook=convert_int_keys)
+            contents.update(file_contents)
+
+            if file.name == self.default_filename:
+                metadata["default_filename"] = file.name
+            else:
+                metadata["content_mapping"][file.name] = list(file_contents.keys())
+
+    return contents, metadata
+
+
+
+ +
+ +
+ + +

+ save(quam_obj, path=None, content_mapping=None, include_defaults=False, ignore=None) + +

+ + +
+ +

Save a QuamRoot object to a JSON file.

+

The save location depends on the path provided and the content_mapping. + No path, no component mapping -> save to default file + No path, component mapping -> Create folder, save to default file, + save components separately + JSON Path, no component mapping -> Save to json file + JSON Path, component mapping -> Save to json file, save components + separately + Folder Path, no component mapping -> Create folder, save to default file + Folder Path, component mapping -> Create folder, save to default file, + save components separately

+
self.default_filename when content_mapping != None or no path provided
+self.default_foldername when content_mapping != None and path is not a
+    folder
+
+ +
+ Source code in quam/serialisation/json.py + 
 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
def save(
+    self,
+    quam_obj: QuamRoot,
+    path: Union[Path, str] = None,
+    content_mapping: Dict[Union[Path, str], Sequence[str]] = None,
+    include_defaults: bool = False,
+    ignore: Sequence[str] = None,
+):
+    """Save a QuamRoot object to a JSON file.
+
+    The save location depends on the path provided and the content_mapping.
+        No path, no component mapping -> save to default file
+        No path, component mapping -> Create folder, save to default file,
+            save components separately
+        JSON Path, no component mapping -> Save to json file
+        JSON Path, component mapping -> Save to json file, save components
+            separately
+        Folder Path, no component mapping -> Create folder, save to default file
+        Folder Path, component mapping -> Create folder, save to default file,
+            save components separately
+
+        self.default_filename when content_mapping != None or no path provided
+        self.default_foldername when content_mapping != None and path is not a
+            folder
+    """
+    content_mapping = content_mapping or self.content_mapping
+    content_mapping = content_mapping.copy()
+
+    contents = quam_obj.to_dict(include_defaults=include_defaults)
+
+    # TODO This should ideally go to the QuamRoot.to_dict method
+    for key in ignore or []:
+        contents.pop(key, None)
+
+    folder, default_filename = self._parse_path(path, content_mapping)
+
+    folder.mkdir(exist_ok=True)
+
+    content_mapping = content_mapping.copy()
+    for component_file, components in content_mapping.items():
+        if isinstance(components, str):
+            components = [components]
+
+        if ignore is not None:
+            components = [elem for elem in components if elem not in ignore]
+        if not components:
+            continue
+
+        subcomponents = {}
+        for component in components:
+            subcomponents[component] = contents.pop(component)
+
+        if isinstance(component_file, Path) and component_file.is_absolute():
+            component_filepath = component_file
+        else:
+            component_filepath = folder / component_file
+        self._save_dict_to_json(subcomponents, component_filepath)
+
+    self._save_dict_to_json(contents, folder / default_filename)
+
+
+
+ +
+ + + +
+ +
+ +
+ + +
+ + +

+ convert_int_keys(obj) + +

+ + +
+ +

Convert dictionary keys to integers if possible.

+ +
+ Source code in quam/serialisation/json.py + 
188
+189
+190
+191
+192
+193
+194
+195
+196
+197
+198
+199
def convert_int_keys(obj):
+    """Convert dictionary keys to integers if possible."""
+    if not isinstance(obj, dict):
+        return obj
+
+    new_obj = {}
+    for key, value in obj.items():
+        if key.isdigit():
+            key = int(key)
+        new_obj[key] = value
+
+    return new_obj
+
+
+
+ +
+ + + +
+ +
+ +
+ + + + + + + + + + + + + +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API_references/utils/config/index.html b/API_references/utils/config/index.html new file mode 100644 index 00000000..3c3de347 --- /dev/null +++ b/API_references/utils/config/index.html @@ -0,0 +1,1010 @@ + + + + + + + + + + + + + + + + + + + + + Config - The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ + + + +

Config

+ +
+ + + + +
+ + + +
+ + + + + + + + + +
+ + +

+ generate_config_final_actions(qua_config) + +

+ + +
+ +

Performs final actions on the generated qua config.

+

This is called at the end of QuamRoot.generate_config(). +In this case it ensures that all analog outputs and inputs have a defined offset

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
qua_config + dict + +
+

The generated qua config.

+
+ 		+ required +
+ +
+ Source code in quam/utils/config.py + 
 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
+11
+12
+13
+14
+15
+16
+17
+18
+19
+20
+21
+22
+23
+24
+25
+26
+27
+28
def generate_config_final_actions(qua_config):
+    """Performs final actions on the generated qua config.
+
+    This is called at the end of `QuamRoot.generate_config()`.
+    In this case it ensures that all analog outputs and inputs have a defined offset
+
+    Args:
+        qua_config (dict): The generated qua config.
+    """
+    # Add default dc offset 0V to all analog outputs and inputs if not set
+    for controller_cfg in qua_config["controllers"].values():
+        for fem in controller_cfg.get("fems", {}).values():
+            if fem.get("type") != "LF":
+                continue
+            for analog_output in fem.get("analog_outputs", {}).values():
+                analog_output.setdefault("offset", 0.0)
+            for analog_input in fem.get("analog_inputs", {}).values():
+                analog_input.setdefault("offset", 0.0)
+
+        if "analog_outputs" in controller_cfg:
+            for analog_output in controller_cfg["analog_outputs"].values():
+                analog_output.setdefault("offset", 0.0)
+        if "analog_inputs" in controller_cfg:
+            for analog_input in controller_cfg["analog_inputs"].values():
+                analog_input.setdefault("offset", 0.0)
+
+
+
+ +
+ + + +
+ +
+ +
+ + + + + + + + + + + + + +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API_references/utils/dataclass/index.html b/API_references/utils/dataclass/index.html new file mode 100644 index 00000000..cf33db2c --- /dev/null +++ b/API_references/utils/dataclass/index.html @@ -0,0 +1,1392 @@ + + + + + + + + + + + + + + + + + + + + + Dataclass - The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ + + + +

Dataclass

+ +
+ + + + +
+ + + +
+ + + + + + + + +
+ + + +

+ REQUIRED + + +

+ + +
+ + +

Flag used by quam_dataclass when a required dataclass arg needs a kwarg

+ +
+ Source code in quam/utils/dataclass.py + 
12
+13
+14
+15
class REQUIRED:
+    """Flag used by `quam_dataclass` when a required dataclass arg needs a kwarg"""
+
+    ...
+
+
+ +
+ +
+ + +
+ + +

+ dataclass_field_has_default(field) + +

+ + +
+ +

Check if a dataclass field has a default value

+ +
+ Source code in quam/utils/dataclass.py + 
76
+77
+78
+79
+80
+81
+82
def dataclass_field_has_default(field: dataclasses.field) -> bool:
+    """Check if a dataclass field has a default value"""
+    if field.default is not dataclasses.MISSING:
+        return True
+    elif field.default_factory is not dataclasses.MISSING:
+        return True
+    return False
+
+
+
+ +
+ +
+ + +

+ get_dataclass_attr_annotations(cls_or_obj) + +

+ + +
+ +

Get the attributes and annotations of a dataclass

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
cls + +
+

The dataclass to get the attributes of.

+
+ 		+ required +
+ + +

Returns:

+ + + + + + + + + + + + + + + + + + + + + +
TypeDescription
+ Dict[str, Dict[str, type]] + +
+

A dictionary where the keys are "required", "optional" and "allowed". +- "required": Required attributes of the class. +- "optional": Optional attributes of the class, i.e. with a default value. +- "allowed": allowed attributes of the class := "required" + "optional".

+
+
+ Dict[str, Dict[str, type]] + +
+

For each key, the values are dictionaries with the attribute names as keys

+
+
+ Dict[str, Dict[str, type]] + +
+

and the attribute types as values.

+
+
+ +
+ Source code in quam/utils/dataclass.py + 
18
+19
+20
+21
+22
+23
+24
+25
+26
+27
+28
+29
+30
+31
+32
+33
+34
+35
+36
+37
+38
+39
+40
+41
+42
+43
+44
+45
+46
+47
+48
+49
+50
+51
+52
+53
+54
+55
+56
+57
+58
+59
+60
+61
+62
+63
+64
+65
+66
+67
+68
+69
+70
+71
+72
+73
def get_dataclass_attr_annotations(
+    cls_or_obj: Union[type, object],
+) -> Dict[str, Dict[str, type]]:
+    """Get the attributes and annotations of a dataclass
+
+    Args:
+        cls: The dataclass to get the attributes of.
+
+    Returns:
+        A dictionary where the keys are "required", "optional" and "allowed".
+            - "required": Required attributes of the class.
+            - "optional": Optional attributes of the class, i.e. with a default value.
+            - "allowed": allowed attributes of the class := "required" + "optional".
+        For each key, the values are dictionaries with the attribute names as keys
+        and the attribute types as values.
+    """
+
+    annotated_attrs = get_type_hints(cls_or_obj)
+
+    annotated_attrs.pop("_root", None)
+    annotated_attrs.pop("_references", None)
+    annotated_attrs.pop("_skip_attrs", None)
+    annotated_attrs.pop("parent", None)
+    annotated_attrs.pop("config_settings", None)
+    annotated_attrs.pop("_value_annotation", None)
+    annotated_attrs.pop("_initialized", None)
+
+    attr_annotations = {"required": {}, "optional": {}}
+    for attr, attr_type in annotated_attrs.items():
+        if getattr(attr_type, "__origin__", None) == ClassVar:
+            continue
+        # TODO Try to combine with third elif statement
+        if getattr(cls_or_obj, attr, None) is REQUIRED:  # See "patch_dataclass()"
+            if attr not in getattr(cls_or_obj, "__dataclass_fields__", {}):
+                attr_annotations["required"][attr] = attr_type
+            else:
+                field_attr = cls_or_obj.__dataclass_fields__[attr]
+                if field_attr.default_factory is not dataclasses.MISSING:
+                    attr_annotations["optional"][attr] = attr_type
+                else:
+                    attr_annotations["required"][attr] = attr_type
+        elif hasattr(cls_or_obj, attr):
+            attr_annotations["optional"][attr] = attr_type
+        elif attr in getattr(cls_or_obj, "__dataclass_fields__", {}):
+            data_field = cls_or_obj.__dataclass_fields__[attr]
+            if data_field.default_factory is not dataclasses.MISSING:
+                attr_annotations["optional"][attr] = attr_type
+            else:
+                attr_annotations["required"][attr] = attr_type
+        else:
+            attr_annotations["required"][attr] = attr_type
+    attr_annotations["allowed"] = {
+        **attr_annotations["required"],
+        **attr_annotations["optional"],
+    }
+    return attr_annotations
+
+
+
+ +
+ +
+ + +

+ handle_inherited_required_fields(cls) + +

+ + +
+ +

Adds a default REQUIRED flag for dataclass fields when necessary

+

see quam_dataclass docs for details

+ +
+ Source code in quam/utils/dataclass.py + 
 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
def handle_inherited_required_fields(cls):
+    """Adds a default REQUIRED flag for dataclass fields when necessary
+
+    see quam_dataclass docs for details
+    """
+    if not is_dataclass(cls):
+        return
+
+    # Check if dataclass has fields with default value
+    optional_fields = [
+        field.name
+        for field in dataclasses.fields(cls)
+        if dataclass_field_has_default(field)
+    ]
+    if not optional_fields:
+        # All fields of the dataclass are required, we don't have to handle situations
+        # where the parent class has fields with default values and the subclass has
+        # required fields.
+        return
+
+    # Check if class (not parents) has required fields
+    for attr, attr_type in cls.__annotations__.items():
+        if attr in cls.__dict__:
+            continue
+        if attr in optional_fields:
+            continue
+        if getattr(attr_type, "__origin__", None) is ClassVar:
+            continue
+        setattr(cls, attr, REQUIRED)
+
+
+
+ +
+ +
+ + +

+ patch_dataclass(module_name) + +

+ + +
+ +

Patch Python dataclass within a file to allow subclasses have args

+ + +
+ Note +

Patch is only applied when Python < 3.10.

+
+ +
+ Note +

This function should be called at the top of a file, before dataclasses are +defined: +

patch_dataclass(__name__)  # Ensure dataclass "kw_only" also works with python < 3.10
+

+

Prior to Python 3.10, it was not possible for a dataclass to be a subclass of +another dataclass when +- the parent dataclass has an arg with default +- the child dataclass has a required arg

+

From Python 3.10, this was fixed by including the flag @dataclass(kw_only=True). +To ensure QuAM remains compatible with Python <3.10, we include a method to patch +the dataclass such that it still works in the case described above.

+

We achieve this by first checking if the above condition is met. If so, all the +args without a default value receive a default REQUIRED flag. The post_init method +is then overridden such that an error is raised whenever an attribute still has +the REQUIRED flag after instantiation.

+ + +
+ Note +

The python dataclass is patched in a non-standard way by calling setattr +on the module. This is done to ensure that the patch is not recognized by any +static analysis tools, such as mypy. This is necessary as mypy otherwise will +no longer recognize the dataclass as a dataclass.

+
+
+ Source code in quam/utils/dataclass.py + 
168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
+182
+183
+184
+185
+186
+187
+188
+189
+190
+191
+192
+193
+194
+195
+196
+197
+198
+199
+200
+201
+202
+203
+204
+205
+206
+207
def patch_dataclass(module_name):
+    """Patch Python dataclass within a file to allow subclasses have args
+
+    Note:
+        Patch is only applied when Python < 3.10.
+
+    Note:
+        This function should be called at the top of a file, before dataclasses are
+        defined:
+        ```
+        patch_dataclass(__name__)  # Ensure dataclass "kw_only" also works with python < 3.10
+        ```
+
+    Prior to Python 3.10, it was not possible for a dataclass to be a subclass of
+    another dataclass when
+    - the parent dataclass has an arg with default
+    - the child dataclass has a required arg
+
+    From Python 3.10, this was fixed by including the flag @dataclass(kw_only=True).
+    To ensure QuAM remains compatible with Python <3.10, we include a method to patch
+    the dataclass such that it still works in the case described above.
+
+    We achieve this by first checking if the above condition is met. If so, all the
+    args without a default value receive a default REQUIRED flag. The post_init method
+    is then overridden such that an error is raised whenever an attribute still has
+    the REQUIRED flag after instantiation.
+
+    Note:
+        The python dataclass is patched in a non-standard way by calling `setattr`
+        on the module. This is done to ensure that the patch is not recognized by any
+        static analysis tools, such as mypy. This is necessary as mypy otherwise will
+        no longer recognize the dataclass as a dataclass.
+    """
+    DeprecationWarning(
+        "patch_dataclass is deprecated and will be removed in QuAM v1.0. "
+        "Please use 'from quam.core import quam_dataclass' as a decorator instead of "
+        "the regular Python dataclass."
+    )
+    if sys.version_info.minor < 10:
+        setattr(sys.modules[module_name], "dataclass", _quam_patched_dataclass)
+
+
+
+ +
+ + + +
+ +
+ +
+ + + + + + + + + + + + + +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API_references/utils/general/index.html b/API_references/utils/general/index.html new file mode 100644 index 00000000..d31308af --- /dev/null +++ b/API_references/utils/general/index.html @@ -0,0 +1,1389 @@ + + + + + + + + + + + + + + + + + + + + + General - The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ + + + +

General

+ +
+ + + + +
+ + + +
+ + + + + + + + + +
+ + +

+ get_class_from_path(class_str) + +

+ + +
+ +

Extract the class from a class path.

+ + +
+ Example + 
from quam.components import Mixer
+assert get_class_from_path("quam.components.hardware.Mixer") == Mixer
+
+
+ +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
class_str + +
+

The class path, e.g. "quam.components.hardware.Mixer"

+
+ 		+ required +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ type + +
+

Class object corresponding to the class path.

+
+
+ +
+ Source code in quam/utils/general.py + 
 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
def get_class_from_path(class_str) -> type:
+    """Extract the class from a class path.
+
+    Example:
+        ```
+        from quam.components import Mixer
+        assert get_class_from_path("quam.components.hardware.Mixer") == Mixer
+        ```
+
+    Args:
+        class_str: The class path, e.g. "quam.components.hardware.Mixer"
+
+    Returns:
+        Class object corresponding to the class path.
+    """
+    try:
+        module_path, class_name = class_str.rsplit(".", 1)
+    except ValueError as e:
+        raise ValueError(
+            "Could not extract module and class name from class path, be sure that the "
+            "class path is of the form '{module_name}.{class_name}'. "
+            f"class_str: '{class_str}'"
+        ) from e
+    module = importlib.import_module(module_path)
+    quam_class = getattr(module, class_name)
+    return quam_class
+
+
+
+ +
+ +
+ + +

+ get_full_class_path(cls_or_obj) + +

+ + +
+ +

Returns the full path of a class or object, including the module name.

+

Example: +

from quam.components import Mixer
+assert get_full_class_path(Mixer) == "quam.components.hardware.Mixer"
+

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
cls_or_obj + Union[type, object] + +
+

The class or object to get the path of.

+
+ 		+ required +
+ + +

Returns:

+ + + + + + + + + + + + + + + + + +
TypeDescription
+ str + +
+

The full path of the class or object. Generally this is of the form

+
+
+ str + +
+

"module_name.class_name".

+
+
+ +
+ Source code in quam/utils/general.py + 
13
+14
+15
+16
+17
+18
+19
+20
+21
+22
+23
+24
+25
+26
+27
+28
+29
+30
+31
+32
+33
+34
+35
+36
+37
+38
+39
+40
+41
+42
+43
+44
+45
+46
def get_full_class_path(cls_or_obj: Union[type, object]) -> str:
+    """Returns the full path of a class or object, including the module name.
+
+    Example:
+    ```
+    from quam.components import Mixer
+    assert get_full_class_path(Mixer) == "quam.components.hardware.Mixer"
+    ```
+
+    Args:
+        cls_or_obj: The class or object to get the path of.
+
+    Returns:
+        The full path of the class or object. Generally this is of the form
+        "module_name.class_name".
+
+    Warnings:
+        If the module name cannot be determined, a warning is raised.
+    """
+    if isclass(cls_or_obj):
+        class_name = cls_or_obj.__qualname__
+    else:
+        class_name = cls_or_obj.__class__.__qualname__
+
+    module_name = cls_or_obj.__module__
+    if module_name == "__main__" or module_name is None:
+        warnings.warn(
+            f"Could not determine the module of {class_name}, this may cause issues"
+            " when trying to load QuAM from a file. Please ensure that all QuAM"
+            " classes are defined in a Python module"
+        )
+        return class_name
+    else:
+        return f"{module_name}.{class_name}"
+
+
+
+ +
+ +
+ + +

+ validate_obj_type(elem, required_type, allow_none=True, str_repr='') + +

+ + +
+ +

Validate whether the object is an instance of the correct type

+

References (strings starting with "#") are not checked. +None is always allowed.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
elem + Any + +
+

The object to validate the type of.

+
+ 		+ required +
required_type + type + +
+

The required type of the object.

+
+ 		+ required +
allow_none + bool + +
+

Whether None is allowed as a value even if it's the wrong type.

+
+ 		+ True +
str_repr + str + +
+

A string representation of the object, used for error messages.

+
+ 		+ '' +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ None + +
+

None

+
+
+ +
+ Source code in quam/utils/general.py + 
49
+50
+51
+52
+53
+54
+55
+56
+57
+58
+59
+60
+61
+62
+63
+64
+65
+66
+67
+68
+69
+70
+71
+72
+73
+74
+75
+76
+77
+78
+79
+80
+81
+82
+83
+84
+85
+86
+87
+88
def validate_obj_type(
+    elem: Any, required_type: type, allow_none: bool = True, str_repr: str = ""
+) -> None:
+    """Validate whether the object is an instance of the correct type
+
+    References (strings starting with "#") are not checked.
+    None is always allowed.
+
+    Args:
+        elem: The object to validate the type of.
+        required_type: The required type of the object.
+        allow_none: Whether None is allowed as a value even if it's the wrong type.
+        str_repr: A string representation of the object, used for error messages.
+
+    Returns:
+        None
+
+    Raises:
+        TypeError if the type of the attribute is not the required type
+    """
+    # Do not check type if the value is a reference
+    if string_reference.is_reference(elem):
+        return
+    if elem is None and allow_none:
+        return
+    try:
+        check_type(elem, required_type)
+    except TypeCheckError as e:
+        if elem is None:
+            raise TypeError(
+                f"None is not allowed for required attribute {str_repr}"
+            ) from e
+        else:
+            raise TypeError(
+                "Wrong object type found during validation.\n"
+                f"Path: {str_repr}\n"
+                f"Required type: {required_type}\n"
+                f"Actual type: {type(elem)}\n"
+                f"value of actual type: {elem}"
+            ) from e
+
+
+
+ +
+ + + +
+ +
+ +
+ + + + + + + + + + + + + +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API_references/utils/pulse/index.html b/API_references/utils/pulse/index.html new file mode 100644 index 00000000..06533759 --- /dev/null +++ b/API_references/utils/pulse/index.html @@ -0,0 +1,1064 @@ + + + + + + + + + + + + + + + + + + + + + Pulse - The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ + + + +

Pulse

+ +
+ + + + +
+ + + +
+ + + + + + + + + +
+ + +

+ pulse_str_to_axis_axis_angle(pulse_str) + +

+ + +
+ +

Converts a pulse string to a tuple of axis and angle.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
pulse_str + str + +
+

A pulse string, e.g. 'X90'.

+
+ 		+ required +
+ + +

Returns:

+ + + + + + + + + + + + + + + + + +
Name TypeDescription
axis + str + +
+

The axis, one of "X", "Y" or "Z".

+
+
angle + int + +
+

The rotation angle in degrees.

+
+
+ + +

Raises:

+ + + + + + + + + + + + + +
TypeDescription
+ ValueError + +
+

If the pulse string is incorrect

+
+
+ +
+ Source code in quam/utils/pulse.py + 
 7
+ 8
+ 9
+10
+11
+12
+13
+14
+15
+16
+17
+18
+19
+20
+21
+22
+23
+24
+25
+26
+27
+28
+29
+30
+31
def pulse_str_to_axis_axis_angle(pulse_str: str) -> Tuple[str, int]:
+    """Converts a pulse string to a tuple of axis and angle.
+
+    Args:
+        pulse_str: A pulse string, e.g. 'X90'.
+
+    Returns:
+        axis (str): The axis, one of "X", "Y" or "Z".
+        angle (int): The rotation angle in degrees.
+
+    Raises:
+        ValueError: If the pulse string is incorrect
+    """
+    if pulse_str[0] not in "XYZ":
+        raise ValueError(f"Invalid pulse string: {pulse_str}")
+
+    axis = pulse_str[0]
+    angle_str = pulse_str[1:]
+
+    if angle_str[0] == "m":
+        angle_str = f"-{angle_str[1:]}"
+
+    angle = int(angle_str)
+
+    return axis, angle
+
+
+
+ +
+ + + +
+ +
+ +
+ + + + + + + + + + + + + +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API_references/utils/reference_class/index.html b/API_references/utils/reference_class/index.html new file mode 100644 index 00000000..e03d9b0c --- /dev/null +++ b/API_references/utils/reference_class/index.html @@ -0,0 +1,1199 @@ + + + + + + + + + + + + + + + + + + + + + Reference class - The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ + + + +

Reference class

+ +
+ + + + +
+ + + +
+ + + + + + + + +
+ + + +

+ ReferenceClass + + +

+ + +
+ + +

Class whose attributes can by references to other attributes

+ +
+ Source code in quam/utils/reference_class.py + 
  7
+  8
+  9
+ 10
+ 11
+ 12
+ 13
+ 14
+ 15
+ 16
+ 17
+ 18
+ 19
+ 20
+ 21
+ 22
+ 23
+ 24
+ 25
+ 26
+ 27
+ 28
+ 29
+ 30
+ 31
+ 32
+ 33
+ 34
+ 35
+ 36
+ 37
+ 38
+ 39
+ 40
+ 41
+ 42
+ 43
+ 44
+ 45
+ 46
+ 47
+ 48
+ 49
+ 50
+ 51
+ 52
+ 53
+ 54
+ 55
+ 56
+ 57
+ 58
+ 59
+ 60
+ 61
+ 62
+ 63
+ 64
+ 65
+ 66
+ 67
+ 68
+ 69
+ 70
+ 71
+ 72
+ 73
+ 74
+ 75
+ 76
+ 77
+ 78
+ 79
+ 80
+ 81
+ 82
+ 83
+ 84
+ 85
+ 86
+ 87
+ 88
+ 89
+ 90
+ 91
+ 92
+ 93
+ 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
class ReferenceClass:
+    """Class whose attributes can by references to other attributes"""
+
+    _initialized: ClassVar[bool] = False
+
+    def __post_init__(self) -> None:
+        """Post init function"""
+        self._initialized = True
+
+    def _get_referenced_value(self, attr: str) -> Any:
+        """Get the value of an attribute by reference
+
+        This function should generally be overwritten by subclasses
+        """
+        raise NotImplementedError
+
+    def _is_reference(self, attr: str) -> bool:
+        """Check if an attribute is a reference
+
+        This function should generally be overwritten by subclasses
+        """
+        raise NotImplementedError
+
+    def get_unreferenced_value(self, attr: str) -> bool:
+        """Check if an attribute is a reference"""
+        return super().__getattribute__(attr)
+
+    def __getattribute__(self, attr: str) -> Any:
+        attr_val = super().__getattribute__(attr)
+
+        if attr in ["_is_reference", "_get_referenced_value", "__post_init__"]:
+            return attr_val
+
+        try:
+            if self._is_reference(attr_val):
+                return self._get_referenced_value(attr_val)
+            return attr_val
+        except Exception:
+            return attr_val
+
+    def _is_valid_setattr(
+        self, attr: str, value: Any, error_on_False: bool = False
+    ) -> bool:
+        """Check if an attribute can be set to a value
+
+        This will be called by __setattr__ to check if the attribute can be set to the
+        given value.
+
+        Args:
+            attr: The attribute to set
+            value: The value to set the attribute to
+            error_on_False: If True, raise an error if the attribute cannot be set to
+                the value. If False, return False if the attribute cannot be set to the
+                value.
+
+        Returns:
+            True if
+            - The new value is None
+            - The attribute does not exist yet
+            - The attribute's previous value is not a reference
+            - The new value is a reference
+            False otherwise, in particular if the previous value is a reference and the
+            new value is not and is also not None.
+
+        Raises:
+            ValueError: If error_on_False is True and the attribute cannot be set to
+                the value.
+        """
+        if value is None:
+            return True
+
+        try:
+            original_value = self.get_unreferenced_value(attr)
+        except AttributeError:
+            return True
+
+        if not self._initialized:
+            return True
+
+        if self._is_reference(original_value):
+            if self._is_reference(value):
+                return True
+
+            if not error_on_False:
+                return False
+
+            raise ValueError(
+                f"Cannot set attribute {attr} to {value} because it is a reference. "
+                "To overwrite the reference, set the attribute to None first.\n"
+                f"Object: {self}\n"
+                f"Original value: {original_value}"
+            )
+
+        return True
+
+    def __setattr__(self, attr: str, value: Any) -> None:
+        self._is_valid_setattr(attr, value, error_on_False=True)
+
+        super().__setattr__(attr, value)
+
+
+ + + +
+ + + + + + + + + +
+ + +

+ __post_init__() + +

+ + +
+ +

Post init function

+ +
+ Source code in quam/utils/reference_class.py + 
12
+13
+14
def __post_init__(self) -> None:
+    """Post init function"""
+    self._initialized = True
+
+
+
+ +
+ +
+ + +

+ get_unreferenced_value(attr) + +

+ + +
+ +

Check if an attribute is a reference

+ +
+ Source code in quam/utils/reference_class.py + 
30
+31
+32
def get_unreferenced_value(self, attr: str) -> bool:
+    """Check if an attribute is a reference"""
+    return super().__getattribute__(attr)
+
+
+
+ +
+ + + +
+ +
+ +
+ + + + +
+ +
+ +
+ + + + + + + + + + + + + +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API_references/utils/string_reference/index.html b/API_references/utils/string_reference/index.html new file mode 100644 index 00000000..845196c4 --- /dev/null +++ b/API_references/utils/string_reference/index.html @@ -0,0 +1,1436 @@ + + + + + + + + + + + + + + + + + + + + + String reference - The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ + + + +

String reference

+ +
+ + + + +
+ + + +
+ + + + + + + + + +
+ + +

+ get_referenced_value(obj, string, root=None) + +

+ + +
+ +

Get the value of a reference string

+

A string reference is a string that starts with "#/", "#./" or "#../". +See documentation for details.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
string + str + +
+

The reference string

+
+ 		+ required +
root + +
+

The root object to start the search from (default: None) +Only relevant if the string is an absolute reference.

+
+ 		+ None +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ Any + +
+

The value that the reference string points to

+
+
+ + +

Raises:

+ + + + + + + + + + + + + +
TypeDescription
+ ValueError + +
+

If the string is not a valid reference

+
+
+ +
+ Source code in quam/utils/string_reference.py + 
 94
+ 95
+ 96
+ 97
+ 98
+ 99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
def get_referenced_value(obj, string: str, root=None) -> Any:
+    """Get the value of a reference string
+
+    A string reference is a string that starts with "#/", "#./" or "#../".
+    See documentation for details.
+
+    Args:
+        string: The reference string
+        root: The root object to start the search from (default: None)
+            Only relevant if the string is an absolute reference.
+
+    Returns:
+        The value that the reference string points to
+
+    Raises:
+        ValueError: If the string is not a valid reference
+    """
+    if not is_reference(string):
+        raise ValueError(f"String {string} is not a reference")
+
+    if is_absolute_reference(string):
+        obj = root
+
+    try:
+        return get_relative_reference_value(obj, string)
+    except (AttributeError, KeyError) as e:
+        raise ValueError(f"String {string} is not a valid reference, Error: {e}") from e
+
+
+
+ +
+ +
+ + +

+ get_relative_reference_value(obj, string) + +

+ + +
+ +

Get the value of a reference string relative to an object

+

Performs recursive calls to get the value of nested references

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
string + str + +
+

The reference string

+
+ 		+ required +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ Any + +
+

The value of the reference string relative to the object

+
+
+ + +

Raises:

+ + + + + + + + + + + + + +
TypeDescription
+ AttributeError + +
+

If the object does not have the attribute

+
+
+ +
+ Source code in quam/utils/string_reference.py + 
51
+52
+53
+54
+55
+56
+57
+58
+59
+60
+61
+62
+63
+64
+65
+66
+67
+68
+69
+70
+71
+72
+73
+74
+75
+76
+77
+78
+79
+80
+81
+82
+83
+84
+85
+86
+87
+88
+89
+90
+91
def get_relative_reference_value(obj, string: str) -> Any:
+    """Get the value of a reference string relative to an object
+
+    Performs recursive calls to get the value of nested references
+
+    Args:
+        string: The reference string
+
+    Returns:
+        The value of the reference string relative to the object
+
+    Raises:
+        AttributeError: If the object does not have the attribute
+    """
+    string = string.lstrip("#/")
+
+    if not string:
+        return obj
+    if string.startswith("../"):
+        return get_relative_reference_value(obj.parent, string[3:])
+    elif string.startswith("./"):
+        return get_relative_reference_value(obj, string[2:])
+
+    next_attr, remaining_string = split_next_attribute(string)
+
+    if next_attr.isdigit() and isinstance(obj, (list, UserList)):
+        try:
+            obj_attr = obj[int(next_attr)]
+        except KeyError as e:
+            raise AttributeError(f"Object {obj} has no attribute {next_attr}") from e
+    elif isinstance(obj, (dict, UserDict)):
+        if next_attr in obj:
+            obj_attr = obj[next_attr]
+        elif next_attr.isdigit() and int(next_attr) in obj:
+            obj_attr = obj[int(next_attr)]
+        else:
+            raise AttributeError(f"Object {obj} has no attribute {next_attr}")
+    else:
+        obj_attr = getattr(obj, next_attr)
+
+    return get_relative_reference_value(obj_attr, remaining_string)
+
+
+
+ +
+ +
+ + +

+ is_absolute_reference(string) + +

+ + +
+ +

Check if a string is an absolute reference

+

A relative reference starts with "#./" or "#../" +An absolute reference starts with ":" but is not followed by "./" or "../"

+ +
+ Source code in quam/utils/string_reference.py + 
18
+19
+20
+21
+22
+23
+24
+25
+26
def is_absolute_reference(string: str) -> bool:
+    """Check if a string is an absolute reference
+
+    A relative reference starts with "#./" or "#../"
+    An absolute reference starts with ":" but is not followed by "./" or "../"
+    """
+    if not is_reference(string):
+        return False
+    return string.startswith("#/")
+
+
+
+ +
+ +
+ + +

+ is_reference(string) + +

+ + +
+ +

Check if a string is a reference,

+

A reference should be a string that starts with "#/", "#./" or "#../"

+ +
+ Source code in quam/utils/string_reference.py + 
 8
+ 9
+10
+11
+12
+13
+14
+15
def is_reference(string: str) -> bool:
+    """Check if a string is a reference,
+
+    A reference should be a string that starts with "#/", "#./" or "#../"
+    """
+    if not isinstance(string, str):
+        return False
+    return string.startswith(("#/", "#./", "#../"))
+
+
+
+ +
+ +
+ + +

+ split_next_attribute(string, splitter='/') + +

+ + +
+ +

Get the next attribute of a reference string, i.e. until a splitter (default: /)

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
string + str + +
+

string to split

+
+ 		+ required +
splitter + str + +
+

splitter to split the string at (default: "/")

+
+ 		+ '/' +
+

Returns: + A tuple consisting of: + - A string of the next attribute, i.e. until the first splitter + - The remaining string from the first splitter

+ +
+ Source code in quam/utils/string_reference.py + 
29
+30
+31
+32
+33
+34
+35
+36
+37
+38
+39
+40
+41
+42
+43
+44
+45
+46
+47
+48
def split_next_attribute(string: str, splitter: str = "/") -> Tuple[str, str]:
+    """Get the next attribute of a reference string, i.e. until a splitter (default: /)
+
+    Args:
+        string: string to split
+        splitter:  splitter to split the string at (default: "/")
+    Returns:
+        A tuple consisting of:
+        - A string of the next attribute, i.e. until the first splitter
+        - The remaining string from the first splitter
+    """
+    string = string.lstrip("#/")
+
+    if not len(string):
+        return "", ""
+
+    if splitter in string:
+        return tuple(string.split(splitter, 1))
+
+    return string, ""
+
+
+
+ +
+ + + +
+ +
+ +
+ + + + + + + + + + + + + +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/API_references/utils/type_checking/index.html b/API_references/utils/type_checking/index.html new file mode 100644 index 00000000..9505f6f1 --- /dev/null +++ b/API_references/utils/type_checking/index.html @@ -0,0 +1,1036 @@ + + + + + + + + + + + + + + + + + + + + + Type checking - The Quantum Abstract Machine - QuAM Documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + Skip to content + + +
+
+ +
+ + + + + + +
+ + +
+ +
+ + + + + + +
+
+ + + +
+
+
+ + + + + + + +
+
+
+ + + + +
+
+ + + + +

Type checking

+ +
+ + + + +
+ + + +
+ + + + + + + + + +
+ + +

+ type_is_optional(type_) + +

+ + +
+ +

Check if a type is Optional[T] for some type T.

+ + +

Parameters:

+ + + + + + + + + + + + + + + + + +
NameTypeDescriptionDefault
type_ + +
+

The type to check.

+
+ 		+ required +
+ + +

Returns:

+ + + + + + + + + + + + + +
TypeDescription
+ bool + +
+

True if the type is Optional[T] for some type T, False otherwise.

+
+
+ + +
+ Notes +

This function does not check if the type is a Union of None and some other +type, only if it is a Union of exactly two types, one of which is None. +So Optional[Union[str, int]] will return False, but Optional[str] will return +True.

+
+
+ Source code in quam/utils/type_checking.py + 
 6
+ 7
+ 8
+ 9
+10
+11
+12
+13
+14
+15
+16
+17
+18
+19
+20
+21
+22
+23
+24
+25
+26
+27
+28
+29
def type_is_optional(type_) -> bool:
+    """Check if a type is Optional[T] for some type T.
+
+    Args:
+        type_: The type to check.
+
+    Returns:
+        True if the type is Optional[T] for some type T, False otherwise.
+
+    Notes:
+        This function does not check if the type is a Union of None and some other
+        type, only if it is a Union of exactly two types, one of which is None.
+        So Optional[Union[str, int]] will return False, but Optional[str] will return
+        True.
+    """
+    if not hasattr(type_, "__origin__"):
+        return False
+    if type_.__origin__ is not Union:
+        return False
+    if len(type_.__args__) != 2:
+        return False
+    if type_.__args__[1] is not type(None):
+        return False
+    return True
+
+
+
+ +
+ + + +
+ +
+ +
+ + + + + + + + + + + + + +
+
+ + + + + +
+ + + +
+ + + +
+
+
+
+ + + + + + + + + + \ No newline at end of file diff --git a/assets/_mkdocstrings.css b/assets/_mkdocstrings.css new file mode 100644 index 00000000..85449ec7 --- /dev/null +++ b/assets/_mkdocstrings.css @@ -0,0 +1,119 @@ + +/* Avoid breaking parameter names, etc. in table cells. */ +.doc-contents td code { + word-break: normal !important; +} + +/* No line break before first paragraph of descriptions. */ +.doc-md-description, +.doc-md-description>p:first-child { + display: inline; +} + +/* Max width for docstring sections tables. */ +.doc .md-typeset__table, +.doc .md-typeset__table table { + display: table !important; + width: 100%; +} + +.doc .md-typeset__table tr { + display: table-row; +} + +/* Defaults in Spacy table style. */ +.doc-param-default { + float: right; +} + +/* Backward-compatibility: docstring section titles in bold. */ +.doc-section-title { + font-weight: bold; +} + +/* Symbols in Navigation and ToC. */ +:root, +[data-md-color-scheme="default"] { + --doc-symbol-attribute-fg-color: #953800; + --doc-symbol-function-fg-color: #8250df; + --doc-symbol-method-fg-color: #8250df; + --doc-symbol-class-fg-color: #0550ae; + --doc-symbol-module-fg-color: #5cad0f; + + --doc-symbol-attribute-bg-color: #9538001a; + --doc-symbol-function-bg-color: #8250df1a; + --doc-symbol-method-bg-color: #8250df1a; + --doc-symbol-class-bg-color: #0550ae1a; + --doc-symbol-module-bg-color: #5cad0f1a; +} + +[data-md-color-scheme="slate"] { + --doc-symbol-attribute-fg-color: #ffa657; + --doc-symbol-function-fg-color: #d2a8ff; + --doc-symbol-method-fg-color: #d2a8ff; + --doc-symbol-class-fg-color: #79c0ff; + --doc-symbol-module-fg-color: #baff79; + + --doc-symbol-attribute-bg-color: #ffa6571a; + --doc-symbol-function-bg-color: #d2a8ff1a; + --doc-symbol-method-bg-color: #d2a8ff1a; + --doc-symbol-class-bg-color: #79c0ff1a; + --doc-symbol-module-bg-color: #baff791a; +} + +code.doc-symbol { + border-radius: .1rem; + font-size: .85em; + padding: 0 .3em; + font-weight: bold; +} + +code.doc-symbol-attribute { + color: var(--doc-symbol-attribute-fg-color); + background-color: var(--doc-symbol-attribute-bg-color); +} + +code.doc-symbol-attribute::after { + content: "attr"; +} + +code.doc-symbol-function { + color: var(--doc-symbol-function-fg-color); + background-color: var(--doc-symbol-function-bg-color); +} + +code.doc-symbol-function::after { + content: "func"; +} + +code.doc-symbol-method { + color: var(--doc-symbol-method-fg-color); + background-color: var(--doc-symbol-method-bg-color); +} + +code.doc-symbol-method::after { + content: "meth"; +} + +code.doc-symbol-class { + color: var(--doc-symbol-class-fg-color); + background-color: var(--doc-symbol-class-bg-color); +} + +code.doc-symbol-class::after { + content: "class"; +} + +code.doc-symbol-module { + color: var(--doc-symbol-module-fg-color); + background-color: var(--doc-symbol-module-bg-color); +} + +code.doc-symbol-module::after { + content: "mod"; +} + +.doc-signature .autorefs { + color: inherit; + border-bottom: 1px dotted currentcolor; +} diff --git a/assets/images/favicon.png b/assets/images/favicon.png new file mode 100644 index 00000000..1cf13b9f Binary files /dev/null and b/assets/images/favicon.png differ diff --git a/assets/javascripts/bundle.fe8b6f2b.min.js b/assets/javascripts/bundle.fe8b6f2b.min.js new file mode 100644 index 00000000..cf778d42 --- /dev/null +++ b/assets/javascripts/bundle.fe8b6f2b.min.js @@ -0,0 +1,29 @@ +"use strict";(()=>{var Fi=Object.create;var gr=Object.defineProperty;var ji=Object.getOwnPropertyDescriptor;var Wi=Object.getOwnPropertyNames,Dt=Object.getOwnPropertySymbols,Ui=Object.getPrototypeOf,xr=Object.prototype.hasOwnProperty,no=Object.prototype.propertyIsEnumerable;var oo=(e,t,r)=>t in e?gr(e,t,{enumerable:!0,configurable:!0,writable:!0,value:r}):e[t]=r,R=(e,t)=>{for(var r in t||(t={}))xr.call(t,r)&&oo(e,r,t[r]);if(Dt)for(var r of Dt(t))no.call(t,r)&&oo(e,r,t[r]);return e};var io=(e,t)=>{var r={};for(var o in e)xr.call(e,o)&&t.indexOf(o)<0&&(r[o]=e[o]);if(e!=null&&Dt)for(var o of Dt(e))t.indexOf(o)<0&&no.call(e,o)&&(r[o]=e[o]);return r};var yr=(e,t)=>()=>(t||e((t={exports:{}}).exports,t),t.exports);var Di=(e,t,r,o)=>{if(t&&typeof t=="object"||typeof t=="function")for(let n of Wi(t))!xr.call(e,n)&&n!==r&&gr(e,n,{get:()=>t[n],enumerable:!(o=ji(t,n))||o.enumerable});return e};var Vt=(e,t,r)=>(r=e!=null?Fi(Ui(e)):{},Di(t||!e||!e.__esModule?gr(r,"default",{value:e,enumerable:!0}):r,e));var ao=(e,t,r)=>new Promise((o,n)=>{var i=p=>{try{s(r.next(p))}catch(c){n(c)}},a=p=>{try{s(r.throw(p))}catch(c){n(c)}},s=p=>p.done?o(p.value):Promise.resolve(p.value).then(i,a);s((r=r.apply(e,t)).next())});var co=yr((Er,so)=>{(function(e,t){typeof Er=="object"&&typeof so!="undefined"?t():typeof define=="function"&&define.amd?define(t):t()})(Er,function(){"use strict";function e(r){var o=!0,n=!1,i=null,a={text:!0,search:!0,url:!0,tel:!0,email:!0,password:!0,number:!0,date:!0,month:!0,week:!0,time:!0,datetime:!0,"datetime-local":!0};function s(H){return!!(H&&H!==document&&H.nodeName!=="HTML"&&H.nodeName!=="BODY"&&"classList"in H&&"contains"in H.classList)}function p(H){var mt=H.type,ze=H.tagName;return!!(ze==="INPUT"&&a[mt]&&!H.readOnly||ze==="TEXTAREA"&&!H.readOnly||H.isContentEditable)}function c(H){H.classList.contains("focus-visible")||(H.classList.add("focus-visible"),H.setAttribute("data-focus-visible-added",""))}function l(H){H.hasAttribute("data-focus-visible-added")&&(H.classList.remove("focus-visible"),H.removeAttribute("data-focus-visible-added"))}function f(H){H.metaKey||H.altKey||H.ctrlKey||(s(r.activeElement)&&c(r.activeElement),o=!0)}function u(H){o=!1}function h(H){s(H.target)&&(o||p(H.target))&&c(H.target)}function w(H){s(H.target)&&(H.target.classList.contains("focus-visible")||H.target.hasAttribute("data-focus-visible-added"))&&(n=!0,window.clearTimeout(i),i=window.setTimeout(function(){n=!1},100),l(H.target))}function A(H){document.visibilityState==="hidden"&&(n&&(o=!0),te())}function te(){document.addEventListener("mousemove",J),document.addEventListener("mousedown",J),document.addEventListener("mouseup",J),document.addEventListener("pointermove",J),document.addEventListener("pointerdown",J),document.addEventListener("pointerup",J),document.addEventListener("touchmove",J),document.addEventListener("touchstart",J),document.addEventListener("touchend",J)}function ie(){document.removeEventListener("mousemove",J),document.removeEventListener("mousedown",J),document.removeEventListener("mouseup",J),document.removeEventListener("pointermove",J),document.removeEventListener("pointerdown",J),document.removeEventListener("pointerup",J),document.removeEventListener("touchmove",J),document.removeEventListener("touchstart",J),document.removeEventListener("touchend",J)}function J(H){H.target.nodeName&&H.target.nodeName.toLowerCase()==="html"||(o=!1,ie())}document.addEventListener("keydown",f,!0),document.addEventListener("mousedown",u,!0),document.addEventListener("pointerdown",u,!0),document.addEventListener("touchstart",u,!0),document.addEventListener("visibilitychange",A,!0),te(),r.addEventListener("focus",h,!0),r.addEventListener("blur",w,!0),r.nodeType===Node.DOCUMENT_FRAGMENT_NODE&&r.host?r.host.setAttribute("data-js-focus-visible",""):r.nodeType===Node.DOCUMENT_NODE&&(document.documentElement.classList.add("js-focus-visible"),document.documentElement.setAttribute("data-js-focus-visible",""))}if(typeof window!="undefined"&&typeof document!="undefined"){window.applyFocusVisiblePolyfill=e;var t;try{t=new CustomEvent("focus-visible-polyfill-ready")}catch(r){t=document.createEvent("CustomEvent"),t.initCustomEvent("focus-visible-polyfill-ready",!1,!1,{})}window.dispatchEvent(t)}typeof document!="undefined"&&e(document)})});var Yr=yr((Rt,Kr)=>{/*! + * clipboard.js v2.0.11 + * https://clipboardjs.com/ + * + * Licensed MIT © Zeno Rocha + */(function(t,r){typeof Rt=="object"&&typeof Kr=="object"?Kr.exports=r():typeof define=="function"&&define.amd?define([],r):typeof Rt=="object"?Rt.ClipboardJS=r():t.ClipboardJS=r()})(Rt,function(){return function(){var e={686:function(o,n,i){"use strict";i.d(n,{default:function(){return Ii}});var a=i(279),s=i.n(a),p=i(370),c=i.n(p),l=i(817),f=i.n(l);function u(V){try{return document.execCommand(V)}catch(_){return!1}}var h=function(_){var M=f()(_);return u("cut"),M},w=h;function A(V){var _=document.documentElement.getAttribute("dir")==="rtl",M=document.createElement("textarea");M.style.fontSize="12pt",M.style.border="0",M.style.padding="0",M.style.margin="0",M.style.position="absolute",M.style[_?"right":"left"]="-9999px";var j=window.pageYOffset||document.documentElement.scrollTop;return M.style.top="".concat(j,"px"),M.setAttribute("readonly",""),M.value=V,M}var te=function(_,M){var j=A(_);M.container.appendChild(j);var D=f()(j);return u("copy"),j.remove(),D},ie=function(_){var M=arguments.length>1&&arguments[1]!==void 0?arguments[1]:{container:document.body},j="";return typeof _=="string"?j=te(_,M):_ instanceof HTMLInputElement&&!["text","search","url","tel","password"].includes(_==null?void 0:_.type)?j=te(_.value,M):(j=f()(_),u("copy")),j},J=ie;function H(V){"@babel/helpers - typeof";return typeof Symbol=="function"&&typeof Symbol.iterator=="symbol"?H=function(M){return typeof M}:H=function(M){return M&&typeof Symbol=="function"&&M.constructor===Symbol&&M!==Symbol.prototype?"symbol":typeof M},H(V)}var mt=function(){var _=arguments.length>0&&arguments[0]!==void 0?arguments[0]:{},M=_.action,j=M===void 0?"copy":M,D=_.container,Y=_.target,ke=_.text;if(j!=="copy"&&j!=="cut")throw new Error('Invalid "action" value, use either "copy" or "cut"');if(Y!==void 0)if(Y&&H(Y)==="object"&&Y.nodeType===1){if(j==="copy"&&Y.hasAttribute("disabled"))throw new Error('Invalid "target" attribute. Please use "readonly" instead of "disabled" attribute');if(j==="cut"&&(Y.hasAttribute("readonly")||Y.hasAttribute("disabled")))throw new Error(`Invalid "target" attribute. You can't cut text from elements with "readonly" or "disabled" attributes`)}else throw new Error('Invalid "target" value, use a valid Element');if(ke)return J(ke,{container:D});if(Y)return j==="cut"?w(Y):J(Y,{container:D})},ze=mt;function Ie(V){"@babel/helpers - typeof";return typeof Symbol=="function"&&typeof Symbol.iterator=="symbol"?Ie=function(M){return typeof M}:Ie=function(M){return M&&typeof Symbol=="function"&&M.constructor===Symbol&&M!==Symbol.prototype?"symbol":typeof M},Ie(V)}function _i(V,_){if(!(V instanceof _))throw new TypeError("Cannot call a class as a function")}function ro(V,_){for(var M=0;M<_.length;M++){var j=_[M];j.enumerable=j.enumerable||!1,j.configurable=!0,"value"in j&&(j.writable=!0),Object.defineProperty(V,j.key,j)}}function Ai(V,_,M){return _&&ro(V.prototype,_),M&&ro(V,M),V}function Ci(V,_){if(typeof _!="function"&&_!==null)throw new TypeError("Super expression must either be null or a function");V.prototype=Object.create(_&&_.prototype,{constructor:{value:V,writable:!0,configurable:!0}}),_&&br(V,_)}function br(V,_){return br=Object.setPrototypeOf||function(j,D){return j.__proto__=D,j},br(V,_)}function Hi(V){var _=Pi();return function(){var j=Wt(V),D;if(_){var Y=Wt(this).constructor;D=Reflect.construct(j,arguments,Y)}else D=j.apply(this,arguments);return ki(this,D)}}function ki(V,_){return _&&(Ie(_)==="object"||typeof _=="function")?_:$i(V)}function $i(V){if(V===void 0)throw new ReferenceError("this hasn't been initialised - super() hasn't been called");return V}function Pi(){if(typeof Reflect=="undefined"||!Reflect.construct||Reflect.construct.sham)return!1;if(typeof Proxy=="function")return!0;try{return Date.prototype.toString.call(Reflect.construct(Date,[],function(){})),!0}catch(V){return!1}}function Wt(V){return Wt=Object.setPrototypeOf?Object.getPrototypeOf:function(M){return M.__proto__||Object.getPrototypeOf(M)},Wt(V)}function vr(V,_){var M="data-clipboard-".concat(V);if(_.hasAttribute(M))return _.getAttribute(M)}var Ri=function(V){Ci(M,V);var _=Hi(M);function M(j,D){var Y;return _i(this,M),Y=_.call(this),Y.resolveOptions(D),Y.listenClick(j),Y}return Ai(M,[{key:"resolveOptions",value:function(){var D=arguments.length>0&&arguments[0]!==void 0?arguments[0]:{};this.action=typeof D.action=="function"?D.action:this.defaultAction,this.target=typeof D.target=="function"?D.target:this.defaultTarget,this.text=typeof D.text=="function"?D.text:this.defaultText,this.container=Ie(D.container)==="object"?D.container:document.body}},{key:"listenClick",value:function(D){var Y=this;this.listener=c()(D,"click",function(ke){return Y.onClick(ke)})}},{key:"onClick",value:function(D){var Y=D.delegateTarget||D.currentTarget,ke=this.action(Y)||"copy",Ut=ze({action:ke,container:this.container,target:this.target(Y),text:this.text(Y)});this.emit(Ut?"success":"error",{action:ke,text:Ut,trigger:Y,clearSelection:function(){Y&&Y.focus(),window.getSelection().removeAllRanges()}})}},{key:"defaultAction",value:function(D){return vr("action",D)}},{key:"defaultTarget",value:function(D){var Y=vr("target",D);if(Y)return document.querySelector(Y)}},{key:"defaultText",value:function(D){return vr("text",D)}},{key:"destroy",value:function(){this.listener.destroy()}}],[{key:"copy",value:function(D){var Y=arguments.length>1&&arguments[1]!==void 0?arguments[1]:{container:document.body};return J(D,Y)}},{key:"cut",value:function(D){return w(D)}},{key:"isSupported",value:function(){var D=arguments.length>0&&arguments[0]!==void 0?arguments[0]:["copy","cut"],Y=typeof D=="string"?[D]:D,ke=!!document.queryCommandSupported;return Y.forEach(function(Ut){ke=ke&&!!document.queryCommandSupported(Ut)}),ke}}]),M}(s()),Ii=Ri},828:function(o){var n=9;if(typeof Element!="undefined"&&!Element.prototype.matches){var i=Element.prototype;i.matches=i.matchesSelector||i.mozMatchesSelector||i.msMatchesSelector||i.oMatchesSelector||i.webkitMatchesSelector}function a(s,p){for(;s&&s.nodeType!==n;){if(typeof s.matches=="function"&&s.matches(p))return s;s=s.parentNode}}o.exports=a},438:function(o,n,i){var a=i(828);function s(l,f,u,h,w){var A=c.apply(this,arguments);return l.addEventListener(u,A,w),{destroy:function(){l.removeEventListener(u,A,w)}}}function p(l,f,u,h,w){return typeof l.addEventListener=="function"?s.apply(null,arguments):typeof u=="function"?s.bind(null,document).apply(null,arguments):(typeof l=="string"&&(l=document.querySelectorAll(l)),Array.prototype.map.call(l,function(A){return s(A,f,u,h,w)}))}function c(l,f,u,h){return function(w){w.delegateTarget=a(w.target,f),w.delegateTarget&&h.call(l,w)}}o.exports=p},879:function(o,n){n.node=function(i){return i!==void 0&&i instanceof HTMLElement&&i.nodeType===1},n.nodeList=function(i){var a=Object.prototype.toString.call(i);return i!==void 0&&(a==="[object NodeList]"||a==="[object HTMLCollection]")&&"length"in i&&(i.length===0||n.node(i[0]))},n.string=function(i){return typeof i=="string"||i instanceof String},n.fn=function(i){var a=Object.prototype.toString.call(i);return a==="[object Function]"}},370:function(o,n,i){var a=i(879),s=i(438);function p(u,h,w){if(!u&&!h&&!w)throw new Error("Missing required arguments");if(!a.string(h))throw new TypeError("Second argument must be a String");if(!a.fn(w))throw new TypeError("Third argument must be a Function");if(a.node(u))return c(u,h,w);if(a.nodeList(u))return l(u,h,w);if(a.string(u))return f(u,h,w);throw new TypeError("First argument must be a String, HTMLElement, HTMLCollection, or NodeList")}function c(u,h,w){return u.addEventListener(h,w),{destroy:function(){u.removeEventListener(h,w)}}}function l(u,h,w){return Array.prototype.forEach.call(u,function(A){A.addEventListener(h,w)}),{destroy:function(){Array.prototype.forEach.call(u,function(A){A.removeEventListener(h,w)})}}}function f(u,h,w){return s(document.body,u,h,w)}o.exports=p},817:function(o){function n(i){var a;if(i.nodeName==="SELECT")i.focus(),a=i.value;else if(i.nodeName==="INPUT"||i.nodeName==="TEXTAREA"){var s=i.hasAttribute("readonly");s||i.setAttribute("readonly",""),i.select(),i.setSelectionRange(0,i.value.length),s||i.removeAttribute("readonly"),a=i.value}else{i.hasAttribute("contenteditable")&&i.focus();var p=window.getSelection(),c=document.createRange();c.selectNodeContents(i),p.removeAllRanges(),p.addRange(c),a=p.toString()}return a}o.exports=n},279:function(o){function n(){}n.prototype={on:function(i,a,s){var p=this.e||(this.e={});return(p[i]||(p[i]=[])).push({fn:a,ctx:s}),this},once:function(i,a,s){var p=this;function c(){p.off(i,c),a.apply(s,arguments)}return c._=a,this.on(i,c,s)},emit:function(i){var a=[].slice.call(arguments,1),s=((this.e||(this.e={}))[i]||[]).slice(),p=0,c=s.length;for(p;p{"use strict";/*! + * escape-html + * Copyright(c) 2012-2013 TJ Holowaychuk + * Copyright(c) 2015 Andreas Lubbe + * Copyright(c) 2015 Tiancheng "Timothy" Gu + * MIT Licensed + */var ts=/["'&<>]/;ei.exports=rs;function rs(e){var t=""+e,r=ts.exec(t);if(!r)return t;var o,n="",i=0,a=0;for(i=r.index;i0&&i[i.length-1])&&(c[0]===6||c[0]===2)){r=0;continue}if(c[0]===3&&(!i||c[1]>i[0]&&c[1]=e.length&&(e=void 0),{value:e&&e[o++],done:!e}}};throw new TypeError(t?"Object is not iterable.":"Symbol.iterator is not defined.")}function N(e,t){var r=typeof Symbol=="function"&&e[Symbol.iterator];if(!r)return e;var o=r.call(e),n,i=[],a;try{for(;(t===void 0||t-- >0)&&!(n=o.next()).done;)i.push(n.value)}catch(s){a={error:s}}finally{try{n&&!n.done&&(r=o.return)&&r.call(o)}finally{if(a)throw a.error}}return i}function q(e,t,r){if(r||arguments.length===2)for(var o=0,n=t.length,i;o1||s(u,h)})})}function s(u,h){try{p(o[u](h))}catch(w){f(i[0][3],w)}}function p(u){u.value instanceof nt?Promise.resolve(u.value.v).then(c,l):f(i[0][2],u)}function c(u){s("next",u)}function l(u){s("throw",u)}function f(u,h){u(h),i.shift(),i.length&&s(i[0][0],i[0][1])}}function mo(e){if(!Symbol.asyncIterator)throw new TypeError("Symbol.asyncIterator is not defined.");var t=e[Symbol.asyncIterator],r;return t?t.call(e):(e=typeof de=="function"?de(e):e[Symbol.iterator](),r={},o("next"),o("throw"),o("return"),r[Symbol.asyncIterator]=function(){return this},r);function o(i){r[i]=e[i]&&function(a){return new Promise(function(s,p){a=e[i](a),n(s,p,a.done,a.value)})}}function n(i,a,s,p){Promise.resolve(p).then(function(c){i({value:c,done:s})},a)}}function k(e){return typeof e=="function"}function ft(e){var t=function(o){Error.call(o),o.stack=new Error().stack},r=e(t);return r.prototype=Object.create(Error.prototype),r.prototype.constructor=r,r}var zt=ft(function(e){return function(r){e(this),this.message=r?r.length+` errors occurred during unsubscription: +`+r.map(function(o,n){return n+1+") "+o.toString()}).join(` + `):"",this.name="UnsubscriptionError",this.errors=r}});function qe(e,t){if(e){var r=e.indexOf(t);0<=r&&e.splice(r,1)}}var Fe=function(){function e(t){this.initialTeardown=t,this.closed=!1,this._parentage=null,this._finalizers=null}return e.prototype.unsubscribe=function(){var t,r,o,n,i;if(!this.closed){this.closed=!0;var a=this._parentage;if(a)if(this._parentage=null,Array.isArray(a))try{for(var s=de(a),p=s.next();!p.done;p=s.next()){var c=p.value;c.remove(this)}}catch(A){t={error:A}}finally{try{p&&!p.done&&(r=s.return)&&r.call(s)}finally{if(t)throw t.error}}else a.remove(this);var l=this.initialTeardown;if(k(l))try{l()}catch(A){i=A instanceof zt?A.errors:[A]}var f=this._finalizers;if(f){this._finalizers=null;try{for(var u=de(f),h=u.next();!h.done;h=u.next()){var w=h.value;try{fo(w)}catch(A){i=i!=null?i:[],A instanceof zt?i=q(q([],N(i)),N(A.errors)):i.push(A)}}}catch(A){o={error:A}}finally{try{h&&!h.done&&(n=u.return)&&n.call(u)}finally{if(o)throw o.error}}}if(i)throw new zt(i)}},e.prototype.add=function(t){var r;if(t&&t!==this)if(this.closed)fo(t);else{if(t instanceof e){if(t.closed||t._hasParent(this))return;t._addParent(this)}(this._finalizers=(r=this._finalizers)!==null&&r!==void 0?r:[]).push(t)}},e.prototype._hasParent=function(t){var r=this._parentage;return r===t||Array.isArray(r)&&r.includes(t)},e.prototype._addParent=function(t){var r=this._parentage;this._parentage=Array.isArray(r)?(r.push(t),r):r?[r,t]:t},e.prototype._removeParent=function(t){var r=this._parentage;r===t?this._parentage=null:Array.isArray(r)&&qe(r,t)},e.prototype.remove=function(t){var r=this._finalizers;r&&qe(r,t),t instanceof e&&t._removeParent(this)},e.EMPTY=function(){var t=new e;return t.closed=!0,t}(),e}();var Tr=Fe.EMPTY;function qt(e){return e instanceof Fe||e&&"closed"in e&&k(e.remove)&&k(e.add)&&k(e.unsubscribe)}function fo(e){k(e)?e():e.unsubscribe()}var $e={onUnhandledError:null,onStoppedNotification:null,Promise:void 0,useDeprecatedSynchronousErrorHandling:!1,useDeprecatedNextContext:!1};var ut={setTimeout:function(e,t){for(var r=[],o=2;o0},enumerable:!1,configurable:!0}),t.prototype._trySubscribe=function(r){return this._throwIfClosed(),e.prototype._trySubscribe.call(this,r)},t.prototype._subscribe=function(r){return this._throwIfClosed(),this._checkFinalizedStatuses(r),this._innerSubscribe(r)},t.prototype._innerSubscribe=function(r){var o=this,n=this,i=n.hasError,a=n.isStopped,s=n.observers;return i||a?Tr:(this.currentObservers=null,s.push(r),new Fe(function(){o.currentObservers=null,qe(s,r)}))},t.prototype._checkFinalizedStatuses=function(r){var o=this,n=o.hasError,i=o.thrownError,a=o.isStopped;n?r.error(i):a&&r.complete()},t.prototype.asObservable=function(){var r=new F;return r.source=this,r},t.create=function(r,o){return new Eo(r,o)},t}(F);var Eo=function(e){re(t,e);function t(r,o){var n=e.call(this)||this;return n.destination=r,n.source=o,n}return t.prototype.next=function(r){var o,n;(n=(o=this.destination)===null||o===void 0?void 0:o.next)===null||n===void 0||n.call(o,r)},t.prototype.error=function(r){var o,n;(n=(o=this.destination)===null||o===void 0?void 0:o.error)===null||n===void 0||n.call(o,r)},t.prototype.complete=function(){var r,o;(o=(r=this.destination)===null||r===void 0?void 0:r.complete)===null||o===void 0||o.call(r)},t.prototype._subscribe=function(r){var o,n;return(n=(o=this.source)===null||o===void 0?void 0:o.subscribe(r))!==null&&n!==void 0?n:Tr},t}(g);var _r=function(e){re(t,e);function t(r){var o=e.call(this)||this;return o._value=r,o}return Object.defineProperty(t.prototype,"value",{get:function(){return this.getValue()},enumerable:!1,configurable:!0}),t.prototype._subscribe=function(r){var o=e.prototype._subscribe.call(this,r);return!o.closed&&r.next(this._value),o},t.prototype.getValue=function(){var r=this,o=r.hasError,n=r.thrownError,i=r._value;if(o)throw n;return this._throwIfClosed(),i},t.prototype.next=function(r){e.prototype.next.call(this,this._value=r)},t}(g);var Lt={now:function(){return(Lt.delegate||Date).now()},delegate:void 0};var _t=function(e){re(t,e);function t(r,o,n){r===void 0&&(r=1/0),o===void 0&&(o=1/0),n===void 0&&(n=Lt);var i=e.call(this)||this;return i._bufferSize=r,i._windowTime=o,i._timestampProvider=n,i._buffer=[],i._infiniteTimeWindow=!0,i._infiniteTimeWindow=o===1/0,i._bufferSize=Math.max(1,r),i._windowTime=Math.max(1,o),i}return t.prototype.next=function(r){var o=this,n=o.isStopped,i=o._buffer,a=o._infiniteTimeWindow,s=o._timestampProvider,p=o._windowTime;n||(i.push(r),!a&&i.push(s.now()+p)),this._trimBuffer(),e.prototype.next.call(this,r)},t.prototype._subscribe=function(r){this._throwIfClosed(),this._trimBuffer();for(var o=this._innerSubscribe(r),n=this,i=n._infiniteTimeWindow,a=n._buffer,s=a.slice(),p=0;p0?e.prototype.schedule.call(this,r,o):(this.delay=o,this.state=r,this.scheduler.flush(this),this)},t.prototype.execute=function(r,o){return o>0||this.closed?e.prototype.execute.call(this,r,o):this._execute(r,o)},t.prototype.requestAsyncId=function(r,o,n){return n===void 0&&(n=0),n!=null&&n>0||n==null&&this.delay>0?e.prototype.requestAsyncId.call(this,r,o,n):(r.flush(this),0)},t}(vt);var So=function(e){re(t,e);function t(){return e!==null&&e.apply(this,arguments)||this}return t}(gt);var Hr=new So(To);var Oo=function(e){re(t,e);function t(r,o){var n=e.call(this,r,o)||this;return n.scheduler=r,n.work=o,n}return t.prototype.requestAsyncId=function(r,o,n){return n===void 0&&(n=0),n!==null&&n>0?e.prototype.requestAsyncId.call(this,r,o,n):(r.actions.push(this),r._scheduled||(r._scheduled=bt.requestAnimationFrame(function(){return r.flush(void 0)})))},t.prototype.recycleAsyncId=function(r,o,n){var i;if(n===void 0&&(n=0),n!=null?n>0:this.delay>0)return e.prototype.recycleAsyncId.call(this,r,o,n);var a=r.actions;o!=null&&((i=a[a.length-1])===null||i===void 0?void 0:i.id)!==o&&(bt.cancelAnimationFrame(o),r._scheduled=void 0)},t}(vt);var Mo=function(e){re(t,e);function t(){return e!==null&&e.apply(this,arguments)||this}return t.prototype.flush=function(r){this._active=!0;var o=this._scheduled;this._scheduled=void 0;var n=this.actions,i;r=r||n.shift();do if(i=r.execute(r.state,r.delay))break;while((r=n[0])&&r.id===o&&n.shift());if(this._active=!1,i){for(;(r=n[0])&&r.id===o&&n.shift();)r.unsubscribe();throw i}},t}(gt);var me=new Mo(Oo);var O=new F(function(e){return e.complete()});function Yt(e){return e&&k(e.schedule)}function kr(e){return e[e.length-1]}function Xe(e){return k(kr(e))?e.pop():void 0}function He(e){return Yt(kr(e))?e.pop():void 0}function Bt(e,t){return typeof kr(e)=="number"?e.pop():t}var xt=function(e){return e&&typeof e.length=="number"&&typeof e!="function"};function Gt(e){return k(e==null?void 0:e.then)}function Jt(e){return k(e[ht])}function Xt(e){return Symbol.asyncIterator&&k(e==null?void 0:e[Symbol.asyncIterator])}function Zt(e){return new TypeError("You provided "+(e!==null&&typeof e=="object"?"an invalid object":"'"+e+"'")+" where a stream was expected. You can provide an Observable, Promise, ReadableStream, Array, AsyncIterable, or Iterable.")}function Gi(){return typeof Symbol!="function"||!Symbol.iterator?"@@iterator":Symbol.iterator}var er=Gi();function tr(e){return k(e==null?void 0:e[er])}function rr(e){return lo(this,arguments,function(){var r,o,n,i;return Nt(this,function(a){switch(a.label){case 0:r=e.getReader(),a.label=1;case 1:a.trys.push([1,,9,10]),a.label=2;case 2:return[4,nt(r.read())];case 3:return o=a.sent(),n=o.value,i=o.done,i?[4,nt(void 0)]:[3,5];case 4:return[2,a.sent()];case 5:return[4,nt(n)];case 6:return[4,a.sent()];case 7:return a.sent(),[3,2];case 8:return[3,10];case 9:return r.releaseLock(),[7];case 10:return[2]}})})}function or(e){return k(e==null?void 0:e.getReader)}function W(e){if(e instanceof F)return e;if(e!=null){if(Jt(e))return Ji(e);if(xt(e))return Xi(e);if(Gt(e))return Zi(e);if(Xt(e))return Lo(e);if(tr(e))return ea(e);if(or(e))return ta(e)}throw Zt(e)}function Ji(e){return new F(function(t){var r=e[ht]();if(k(r.subscribe))return r.subscribe(t);throw new TypeError("Provided object does not correctly implement Symbol.observable")})}function Xi(e){return new F(function(t){for(var r=0;r=2;return function(o){return o.pipe(e?b(function(n,i){return e(n,i,o)}):le,Te(1),r?Be(t):zo(function(){return new ir}))}}function Fr(e){return e<=0?function(){return O}:y(function(t,r){var o=[];t.subscribe(T(r,function(n){o.push(n),e=2,!0))}function pe(e){e===void 0&&(e={});var t=e.connector,r=t===void 0?function(){return new g}:t,o=e.resetOnError,n=o===void 0?!0:o,i=e.resetOnComplete,a=i===void 0?!0:i,s=e.resetOnRefCountZero,p=s===void 0?!0:s;return function(c){var l,f,u,h=0,w=!1,A=!1,te=function(){f==null||f.unsubscribe(),f=void 0},ie=function(){te(),l=u=void 0,w=A=!1},J=function(){var H=l;ie(),H==null||H.unsubscribe()};return y(function(H,mt){h++,!A&&!w&&te();var ze=u=u!=null?u:r();mt.add(function(){h--,h===0&&!A&&!w&&(f=Wr(J,p))}),ze.subscribe(mt),!l&&h>0&&(l=new at({next:function(Ie){return ze.next(Ie)},error:function(Ie){A=!0,te(),f=Wr(ie,n,Ie),ze.error(Ie)},complete:function(){w=!0,te(),f=Wr(ie,a),ze.complete()}}),W(H).subscribe(l))})(c)}}function Wr(e,t){for(var r=[],o=2;oe.next(document)),e}function $(e,t=document){return Array.from(t.querySelectorAll(e))}function P(e,t=document){let r=fe(e,t);if(typeof r=="undefined")throw new ReferenceError(`Missing element: expected "${e}" to be present`);return r}function fe(e,t=document){return t.querySelector(e)||void 0}function Re(){var e,t,r,o;return(o=(r=(t=(e=document.activeElement)==null?void 0:e.shadowRoot)==null?void 0:t.activeElement)!=null?r:document.activeElement)!=null?o:void 0}var xa=S(d(document.body,"focusin"),d(document.body,"focusout")).pipe(_e(1),Q(void 0),m(()=>Re()||document.body),G(1));function et(e){return xa.pipe(m(t=>e.contains(t)),K())}function kt(e,t){return C(()=>S(d(e,"mouseenter").pipe(m(()=>!0)),d(e,"mouseleave").pipe(m(()=>!1))).pipe(t?Ht(r=>Me(+!r*t)):le,Q(e.matches(":hover"))))}function Bo(e,t){if(typeof t=="string"||typeof t=="number")e.innerHTML+=t.toString();else if(t instanceof Node)e.appendChild(t);else if(Array.isArray(t))for(let r of t)Bo(e,r)}function x(e,t,...r){let o=document.createElement(e);if(t)for(let n of Object.keys(t))typeof t[n]!="undefined"&&(typeof t[n]!="boolean"?o.setAttribute(n,t[n]):o.setAttribute(n,""));for(let n of r)Bo(o,n);return o}function sr(e){if(e>999){let t=+((e-950)%1e3>99);return`${((e+1e-6)/1e3).toFixed(t)}k`}else return e.toString()}function wt(e){let t=x("script",{src:e});return C(()=>(document.head.appendChild(t),S(d(t,"load"),d(t,"error").pipe(v(()=>$r(()=>new ReferenceError(`Invalid script: ${e}`))))).pipe(m(()=>{}),L(()=>document.head.removeChild(t)),Te(1))))}var Go=new g,ya=C(()=>typeof ResizeObserver=="undefined"?wt("https://unpkg.com/resize-observer-polyfill"):I(void 0)).pipe(m(()=>new ResizeObserver(e=>e.forEach(t=>Go.next(t)))),v(e=>S(Ke,I(e)).pipe(L(()=>e.disconnect()))),G(1));function ce(e){return{width:e.offsetWidth,height:e.offsetHeight}}function ge(e){let t=e;for(;t.clientWidth===0&&t.parentElement;)t=t.parentElement;return ya.pipe(E(r=>r.observe(t)),v(r=>Go.pipe(b(o=>o.target===t),L(()=>r.unobserve(t)))),m(()=>ce(e)),Q(ce(e)))}function Tt(e){return{width:e.scrollWidth,height:e.scrollHeight}}function cr(e){let t=e.parentElement;for(;t&&(e.scrollWidth<=t.scrollWidth&&e.scrollHeight<=t.scrollHeight);)t=(e=t).parentElement;return t?e:void 0}function Jo(e){let t=[],r=e.parentElement;for(;r;)(e.clientWidth>r.clientWidth||e.clientHeight>r.clientHeight)&&t.push(r),r=(e=r).parentElement;return t.length===0&&t.push(document.documentElement),t}function Ue(e){return{x:e.offsetLeft,y:e.offsetTop}}function Xo(e){let t=e.getBoundingClientRect();return{x:t.x+window.scrollX,y:t.y+window.scrollY}}function Zo(e){return S(d(window,"load"),d(window,"resize")).pipe(Le(0,me),m(()=>Ue(e)),Q(Ue(e)))}function pr(e){return{x:e.scrollLeft,y:e.scrollTop}}function De(e){return S(d(e,"scroll"),d(window,"scroll"),d(window,"resize")).pipe(Le(0,me),m(()=>pr(e)),Q(pr(e)))}var en=new g,Ea=C(()=>I(new IntersectionObserver(e=>{for(let t of e)en.next(t)},{threshold:0}))).pipe(v(e=>S(Ke,I(e)).pipe(L(()=>e.disconnect()))),G(1));function tt(e){return Ea.pipe(E(t=>t.observe(e)),v(t=>en.pipe(b(({target:r})=>r===e),L(()=>t.unobserve(e)),m(({isIntersecting:r})=>r))))}function tn(e,t=16){return De(e).pipe(m(({y:r})=>{let o=ce(e),n=Tt(e);return r>=n.height-o.height-t}),K())}var lr={drawer:P("[data-md-toggle=drawer]"),search:P("[data-md-toggle=search]")};function rn(e){return lr[e].checked}function Je(e,t){lr[e].checked!==t&&lr[e].click()}function Ve(e){let t=lr[e];return d(t,"change").pipe(m(()=>t.checked),Q(t.checked))}function wa(e,t){switch(e.constructor){case HTMLInputElement:return e.type==="radio"?/^Arrow/.test(t):!0;case HTMLSelectElement:case HTMLTextAreaElement:return!0;default:return e.isContentEditable}}function Ta(){return S(d(window,"compositionstart").pipe(m(()=>!0)),d(window,"compositionend").pipe(m(()=>!1))).pipe(Q(!1))}function on(){let e=d(window,"keydown").pipe(b(t=>!(t.metaKey||t.ctrlKey)),m(t=>({mode:rn("search")?"search":"global",type:t.key,claim(){t.preventDefault(),t.stopPropagation()}})),b(({mode:t,type:r})=>{if(t==="global"){let o=Re();if(typeof o!="undefined")return!wa(o,r)}return!0}),pe());return Ta().pipe(v(t=>t?O:e))}function xe(){return new URL(location.href)}function pt(e,t=!1){if(B("navigation.instant")&&!t){let r=x("a",{href:e.href});document.body.appendChild(r),r.click(),r.remove()}else location.href=e.href}function nn(){return new g}function an(){return location.hash.slice(1)}function sn(e){let t=x("a",{href:e});t.addEventListener("click",r=>r.stopPropagation()),t.click()}function Sa(e){return S(d(window,"hashchange"),e).pipe(m(an),Q(an()),b(t=>t.length>0),G(1))}function cn(e){return Sa(e).pipe(m(t=>fe(`[id="${t}"]`)),b(t=>typeof t!="undefined"))}function $t(e){let t=matchMedia(e);return ar(r=>t.addListener(()=>r(t.matches))).pipe(Q(t.matches))}function pn(){let e=matchMedia("print");return S(d(window,"beforeprint").pipe(m(()=>!0)),d(window,"afterprint").pipe(m(()=>!1))).pipe(Q(e.matches))}function Nr(e,t){return e.pipe(v(r=>r?t():O))}function zr(e,t){return new F(r=>{let o=new XMLHttpRequest;return o.open("GET",`${e}`),o.responseType="blob",o.addEventListener("load",()=>{o.status>=200&&o.status<300?(r.next(o.response),r.complete()):r.error(new Error(o.statusText))}),o.addEventListener("error",()=>{r.error(new Error("Network error"))}),o.addEventListener("abort",()=>{r.complete()}),typeof(t==null?void 0:t.progress$)!="undefined"&&(o.addEventListener("progress",n=>{var i;if(n.lengthComputable)t.progress$.next(n.loaded/n.total*100);else{let a=(i=o.getResponseHeader("Content-Length"))!=null?i:0;t.progress$.next(n.loaded/+a*100)}}),t.progress$.next(5)),o.send(),()=>o.abort()})}function Ne(e,t){return zr(e,t).pipe(v(r=>r.text()),m(r=>JSON.parse(r)),G(1))}function ln(e,t){let r=new DOMParser;return zr(e,t).pipe(v(o=>o.text()),m(o=>r.parseFromString(o,"text/html")),G(1))}function mn(e,t){let r=new DOMParser;return zr(e,t).pipe(v(o=>o.text()),m(o=>r.parseFromString(o,"text/xml")),G(1))}function fn(){return{x:Math.max(0,scrollX),y:Math.max(0,scrollY)}}function un(){return S(d(window,"scroll",{passive:!0}),d(window,"resize",{passive:!0})).pipe(m(fn),Q(fn()))}function dn(){return{width:innerWidth,height:innerHeight}}function hn(){return d(window,"resize",{passive:!0}).pipe(m(dn),Q(dn()))}function bn(){return z([un(),hn()]).pipe(m(([e,t])=>({offset:e,size:t})),G(1))}function mr(e,{viewport$:t,header$:r}){let o=t.pipe(Z("size")),n=z([o,r]).pipe(m(()=>Ue(e)));return z([r,t,n]).pipe(m(([{height:i},{offset:a,size:s},{x:p,y:c}])=>({offset:{x:a.x-p,y:a.y-c+i},size:s})))}function Oa(e){return d(e,"message",t=>t.data)}function Ma(e){let t=new g;return t.subscribe(r=>e.postMessage(r)),t}function vn(e,t=new Worker(e)){let r=Oa(t),o=Ma(t),n=new g;n.subscribe(o);let i=o.pipe(X(),ne(!0));return n.pipe(X(),Pe(r.pipe(U(i))),pe())}var La=P("#__config"),St=JSON.parse(La.textContent);St.base=`${new URL(St.base,xe())}`;function ye(){return St}function B(e){return St.features.includes(e)}function Ee(e,t){return typeof t!="undefined"?St.translations[e].replace("#",t.toString()):St.translations[e]}function Se(e,t=document){return P(`[data-md-component=${e}]`,t)}function ae(e,t=document){return $(`[data-md-component=${e}]`,t)}function _a(e){let t=P(".md-typeset > :first-child",e);return d(t,"click",{once:!0}).pipe(m(()=>P(".md-typeset",e)),m(r=>({hash:__md_hash(r.innerHTML)})))}function gn(e){if(!B("announce.dismiss")||!e.childElementCount)return O;if(!e.hidden){let t=P(".md-typeset",e);__md_hash(t.innerHTML)===__md_get("__announce")&&(e.hidden=!0)}return C(()=>{let t=new g;return t.subscribe(({hash:r})=>{e.hidden=!0,__md_set("__announce",r)}),_a(e).pipe(E(r=>t.next(r)),L(()=>t.complete()),m(r=>R({ref:e},r)))})}function Aa(e,{target$:t}){return t.pipe(m(r=>({hidden:r!==e})))}function xn(e,t){let r=new g;return r.subscribe(({hidden:o})=>{e.hidden=o}),Aa(e,t).pipe(E(o=>r.next(o)),L(()=>r.complete()),m(o=>R({ref:e},o)))}function Pt(e,t){return t==="inline"?x("div",{class:"md-tooltip md-tooltip--inline",id:e,role:"tooltip"},x("div",{class:"md-tooltip__inner md-typeset"})):x("div",{class:"md-tooltip",id:e,role:"tooltip"},x("div",{class:"md-tooltip__inner md-typeset"}))}function yn(...e){return x("div",{class:"md-tooltip2",role:"tooltip"},x("div",{class:"md-tooltip2__inner md-typeset"},e))}function En(e,t){if(t=t?`${t}_annotation_${e}`:void 0,t){let r=t?`#${t}`:void 0;return x("aside",{class:"md-annotation",tabIndex:0},Pt(t),x("a",{href:r,class:"md-annotation__index",tabIndex:-1},x("span",{"data-md-annotation-id":e})))}else return x("aside",{class:"md-annotation",tabIndex:0},Pt(t),x("span",{class:"md-annotation__index",tabIndex:-1},x("span",{"data-md-annotation-id":e})))}function wn(e){return x("button",{class:"md-clipboard md-icon",title:Ee("clipboard.copy"),"data-clipboard-target":`#${e} > code`})}function qr(e,t){let r=t&2,o=t&1,n=Object.keys(e.terms).filter(p=>!e.terms[p]).reduce((p,c)=>[...p,x("del",null,c)," "],[]).slice(0,-1),i=ye(),a=new URL(e.location,i.base);B("search.highlight")&&a.searchParams.set("h",Object.entries(e.terms).filter(([,p])=>p).reduce((p,[c])=>`${p} ${c}`.trim(),""));let{tags:s}=ye();return x("a",{href:`${a}`,class:"md-search-result__link",tabIndex:-1},x("article",{class:"md-search-result__article md-typeset","data-md-score":e.score.toFixed(2)},r>0&&x("div",{class:"md-search-result__icon md-icon"}),r>0&&x("h1",null,e.title),r<=0&&x("h2",null,e.title),o>0&&e.text.length>0&&e.text,e.tags&&e.tags.map(p=>{let c=s?p in s?`md-tag-icon md-tag--${s[p]}`:"md-tag-icon":"";return x("span",{class:`md-tag ${c}`},p)}),o>0&&n.length>0&&x("p",{class:"md-search-result__terms"},Ee("search.result.term.missing"),": ",...n)))}function Tn(e){let t=e[0].score,r=[...e],o=ye(),n=r.findIndex(l=>!`${new URL(l.location,o.base)}`.includes("#")),[i]=r.splice(n,1),a=r.findIndex(l=>l.scoreqr(l,1)),...p.length?[x("details",{class:"md-search-result__more"},x("summary",{tabIndex:-1},x("div",null,p.length>0&&p.length===1?Ee("search.result.more.one"):Ee("search.result.more.other",p.length))),...p.map(l=>qr(l,1)))]:[]];return x("li",{class:"md-search-result__item"},c)}function Sn(e){return x("ul",{class:"md-source__facts"},Object.entries(e).map(([t,r])=>x("li",{class:`md-source__fact md-source__fact--${t}`},typeof r=="number"?sr(r):r)))}function Qr(e){let t=`tabbed-control tabbed-control--${e}`;return x("div",{class:t,hidden:!0},x("button",{class:"tabbed-button",tabIndex:-1,"aria-hidden":"true"}))}function On(e){return x("div",{class:"md-typeset__scrollwrap"},x("div",{class:"md-typeset__table"},e))}function Ca(e){var o;let t=ye(),r=new URL(`../${e.version}/`,t.base);return x("li",{class:"md-version__item"},x("a",{href:`${r}`,class:"md-version__link"},e.title,((o=t.version)==null?void 0:o.alias)&&e.aliases.length>0&&x("span",{class:"md-version__alias"},e.aliases[0])))}function Mn(e,t){var o;let r=ye();return e=e.filter(n=>{var i;return!((i=n.properties)!=null&&i.hidden)}),x("div",{class:"md-version"},x("button",{class:"md-version__current","aria-label":Ee("select.version")},t.title,((o=r.version)==null?void 0:o.alias)&&t.aliases.length>0&&x("span",{class:"md-version__alias"},t.aliases[0])),x("ul",{class:"md-version__list"},e.map(Ca)))}var Ha=0;function ka(e){let t=z([et(e),kt(e)]).pipe(m(([o,n])=>o||n),K()),r=C(()=>Jo(e)).pipe(oe(De),ct(1),m(()=>Xo(e)));return t.pipe(Ae(o=>o),v(()=>z([t,r])),m(([o,n])=>({active:o,offset:n})),pe())}function $a(e,t){let{content$:r,viewport$:o}=t,n=`__tooltip2_${Ha++}`;return C(()=>{let i=new g,a=new _r(!1);i.pipe(X(),ne(!1)).subscribe(a);let s=a.pipe(Ht(c=>Me(+!c*250,Hr)),K(),v(c=>c?r:O),E(c=>c.id=n),pe());z([i.pipe(m(({active:c})=>c)),s.pipe(v(c=>kt(c,250)),Q(!1))]).pipe(m(c=>c.some(l=>l))).subscribe(a);let p=a.pipe(b(c=>c),ee(s,o),m(([c,l,{size:f}])=>{let u=e.getBoundingClientRect(),h=u.width/2;if(l.role==="tooltip")return{x:h,y:8+u.height};if(u.y>=f.height/2){let{height:w}=ce(l);return{x:h,y:-16-w}}else return{x:h,y:16+u.height}}));return z([s,i,p]).subscribe(([c,{offset:l},f])=>{c.style.setProperty("--md-tooltip-host-x",`${l.x}px`),c.style.setProperty("--md-tooltip-host-y",`${l.y}px`),c.style.setProperty("--md-tooltip-x",`${f.x}px`),c.style.setProperty("--md-tooltip-y",`${f.y}px`),c.classList.toggle("md-tooltip2--top",f.y<0),c.classList.toggle("md-tooltip2--bottom",f.y>=0)}),a.pipe(b(c=>c),ee(s,(c,l)=>l),b(c=>c.role==="tooltip")).subscribe(c=>{let l=ce(P(":scope > *",c));c.style.setProperty("--md-tooltip-width",`${l.width}px`),c.style.setProperty("--md-tooltip-tail","0px")}),a.pipe(K(),be(me),ee(s)).subscribe(([c,l])=>{l.classList.toggle("md-tooltip2--active",c)}),z([a.pipe(b(c=>c)),s]).subscribe(([c,l])=>{l.role==="dialog"?(e.setAttribute("aria-controls",n),e.setAttribute("aria-haspopup","dialog")):e.setAttribute("aria-describedby",n)}),a.pipe(b(c=>!c)).subscribe(()=>{e.removeAttribute("aria-controls"),e.removeAttribute("aria-describedby"),e.removeAttribute("aria-haspopup")}),ka(e).pipe(E(c=>i.next(c)),L(()=>i.complete()),m(c=>R({ref:e},c)))})}function lt(e,{viewport$:t},r=document.body){return $a(e,{content$:new F(o=>{let n=e.title,i=yn(n);return o.next(i),e.removeAttribute("title"),r.append(i),()=>{i.remove(),e.setAttribute("title",n)}}),viewport$:t})}function Pa(e,t){let r=C(()=>z([Zo(e),De(t)])).pipe(m(([{x:o,y:n},i])=>{let{width:a,height:s}=ce(e);return{x:o-i.x+a/2,y:n-i.y+s/2}}));return et(e).pipe(v(o=>r.pipe(m(n=>({active:o,offset:n})),Te(+!o||1/0))))}function Ln(e,t,{target$:r}){let[o,n]=Array.from(e.children);return C(()=>{let i=new g,a=i.pipe(X(),ne(!0));return i.subscribe({next({offset:s}){e.style.setProperty("--md-tooltip-x",`${s.x}px`),e.style.setProperty("--md-tooltip-y",`${s.y}px`)},complete(){e.style.removeProperty("--md-tooltip-x"),e.style.removeProperty("--md-tooltip-y")}}),tt(e).pipe(U(a)).subscribe(s=>{e.toggleAttribute("data-md-visible",s)}),S(i.pipe(b(({active:s})=>s)),i.pipe(_e(250),b(({active:s})=>!s))).subscribe({next({active:s}){s?e.prepend(o):o.remove()},complete(){e.prepend(o)}}),i.pipe(Le(16,me)).subscribe(({active:s})=>{o.classList.toggle("md-tooltip--active",s)}),i.pipe(ct(125,me),b(()=>!!e.offsetParent),m(()=>e.offsetParent.getBoundingClientRect()),m(({x:s})=>s)).subscribe({next(s){s?e.style.setProperty("--md-tooltip-0",`${-s}px`):e.style.removeProperty("--md-tooltip-0")},complete(){e.style.removeProperty("--md-tooltip-0")}}),d(n,"click").pipe(U(a),b(s=>!(s.metaKey||s.ctrlKey))).subscribe(s=>{s.stopPropagation(),s.preventDefault()}),d(n,"mousedown").pipe(U(a),ee(i)).subscribe(([s,{active:p}])=>{var c;if(s.button!==0||s.metaKey||s.ctrlKey)s.preventDefault();else if(p){s.preventDefault();let l=e.parentElement.closest(".md-annotation");l instanceof HTMLElement?l.focus():(c=Re())==null||c.blur()}}),r.pipe(U(a),b(s=>s===o),Ge(125)).subscribe(()=>e.focus()),Pa(e,t).pipe(E(s=>i.next(s)),L(()=>i.complete()),m(s=>R({ref:e},s)))})}function Ra(e){return e.tagName==="CODE"?$(".c, .c1, .cm",e):[e]}function Ia(e){let t=[];for(let r of Ra(e)){let o=[],n=document.createNodeIterator(r,NodeFilter.SHOW_TEXT);for(let i=n.nextNode();i;i=n.nextNode())o.push(i);for(let i of o){let a;for(;a=/(\(\d+\))(!)?/.exec(i.textContent);){let[,s,p]=a;if(typeof p=="undefined"){let c=i.splitText(a.index);i=c.splitText(s.length),t.push(c)}else{i.textContent=s,t.push(i);break}}}}return t}function _n(e,t){t.append(...Array.from(e.childNodes))}function fr(e,t,{target$:r,print$:o}){let n=t.closest("[id]"),i=n==null?void 0:n.id,a=new Map;for(let s of Ia(t)){let[,p]=s.textContent.match(/\((\d+)\)/);fe(`:scope > li:nth-child(${p})`,e)&&(a.set(p,En(p,i)),s.replaceWith(a.get(p)))}return a.size===0?O:C(()=>{let s=new g,p=s.pipe(X(),ne(!0)),c=[];for(let[l,f]of a)c.push([P(".md-typeset",f),P(`:scope > li:nth-child(${l})`,e)]);return o.pipe(U(p)).subscribe(l=>{e.hidden=!l,e.classList.toggle("md-annotation-list",l);for(let[f,u]of c)l?_n(f,u):_n(u,f)}),S(...[...a].map(([,l])=>Ln(l,t,{target$:r}))).pipe(L(()=>s.complete()),pe())})}function An(e){if(e.nextElementSibling){let t=e.nextElementSibling;if(t.tagName==="OL")return t;if(t.tagName==="P"&&!t.children.length)return An(t)}}function Cn(e,t){return C(()=>{let r=An(e);return typeof r!="undefined"?fr(r,e,t):O})}var Hn=Vt(Yr());var Fa=0;function kn(e){if(e.nextElementSibling){let t=e.nextElementSibling;if(t.tagName==="OL")return t;if(t.tagName==="P"&&!t.children.length)return kn(t)}}function ja(e){return ge(e).pipe(m(({width:t})=>({scrollable:Tt(e).width>t})),Z("scrollable"))}function $n(e,t){let{matches:r}=matchMedia("(hover)"),o=C(()=>{let n=new g,i=n.pipe(Fr(1));n.subscribe(({scrollable:c})=>{c&&r?e.setAttribute("tabindex","0"):e.removeAttribute("tabindex")});let a=[];if(Hn.default.isSupported()&&(e.closest(".copy")||B("content.code.copy")&&!e.closest(".no-copy"))){let c=e.closest("pre");c.id=`__code_${Fa++}`;let l=wn(c.id);c.insertBefore(l,e),B("content.tooltips")&&a.push(lt(l,{viewport$}))}let s=e.closest(".highlight");if(s instanceof HTMLElement){let c=kn(s);if(typeof c!="undefined"&&(s.classList.contains("annotate")||B("content.code.annotate"))){let l=fr(c,e,t);a.push(ge(s).pipe(U(i),m(({width:f,height:u})=>f&&u),K(),v(f=>f?l:O)))}}return $(":scope > span[id]",e).length&&e.classList.add("md-code__content"),ja(e).pipe(E(c=>n.next(c)),L(()=>n.complete()),m(c=>R({ref:e},c)),Pe(...a))});return B("content.lazy")?tt(e).pipe(b(n=>n),Te(1),v(()=>o)):o}function Wa(e,{target$:t,print$:r}){let o=!0;return S(t.pipe(m(n=>n.closest("details:not([open])")),b(n=>e===n),m(()=>({action:"open",reveal:!0}))),r.pipe(b(n=>n||!o),E(()=>o=e.open),m(n=>({action:n?"open":"close"}))))}function Pn(e,t){return C(()=>{let r=new g;return r.subscribe(({action:o,reveal:n})=>{e.toggleAttribute("open",o==="open"),n&&e.scrollIntoView()}),Wa(e,t).pipe(E(o=>r.next(o)),L(()=>r.complete()),m(o=>R({ref:e},o)))})}var Rn=".node circle,.node ellipse,.node path,.node polygon,.node rect{fill:var(--md-mermaid-node-bg-color);stroke:var(--md-mermaid-node-fg-color)}marker{fill:var(--md-mermaid-edge-color)!important}.edgeLabel .label rect{fill:#0000}.label{color:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}.label foreignObject{line-height:normal;overflow:visible}.label div .edgeLabel{color:var(--md-mermaid-label-fg-color)}.edgeLabel,.edgeLabel rect,.label div .edgeLabel{background-color:var(--md-mermaid-label-bg-color)}.edgeLabel,.edgeLabel rect{fill:var(--md-mermaid-label-bg-color);color:var(--md-mermaid-edge-color)}.edgePath .path,.flowchart-link{stroke:var(--md-mermaid-edge-color);stroke-width:.05rem}.edgePath .arrowheadPath{fill:var(--md-mermaid-edge-color);stroke:none}.cluster rect{fill:var(--md-default-fg-color--lightest);stroke:var(--md-default-fg-color--lighter)}.cluster span{color:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}g #flowchart-circleEnd,g #flowchart-circleStart,g #flowchart-crossEnd,g #flowchart-crossStart,g #flowchart-pointEnd,g #flowchart-pointStart{stroke:none}g.classGroup line,g.classGroup rect{fill:var(--md-mermaid-node-bg-color);stroke:var(--md-mermaid-node-fg-color)}g.classGroup text{fill:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}.classLabel .box{fill:var(--md-mermaid-label-bg-color);background-color:var(--md-mermaid-label-bg-color);opacity:1}.classLabel .label{fill:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}.node .divider{stroke:var(--md-mermaid-node-fg-color)}.relation{stroke:var(--md-mermaid-edge-color)}.cardinality{fill:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}.cardinality text{fill:inherit!important}defs #classDiagram-compositionEnd,defs #classDiagram-compositionStart,defs #classDiagram-dependencyEnd,defs #classDiagram-dependencyStart,defs #classDiagram-extensionEnd,defs #classDiagram-extensionStart{fill:var(--md-mermaid-edge-color)!important;stroke:var(--md-mermaid-edge-color)!important}defs #classDiagram-aggregationEnd,defs #classDiagram-aggregationStart{fill:var(--md-mermaid-label-bg-color)!important;stroke:var(--md-mermaid-edge-color)!important}g.stateGroup rect{fill:var(--md-mermaid-node-bg-color);stroke:var(--md-mermaid-node-fg-color)}g.stateGroup .state-title{fill:var(--md-mermaid-label-fg-color)!important;font-family:var(--md-mermaid-font-family)}g.stateGroup .composit{fill:var(--md-mermaid-label-bg-color)}.nodeLabel,.nodeLabel p{color:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}a .nodeLabel{text-decoration:underline}.node circle.state-end,.node circle.state-start,.start-state{fill:var(--md-mermaid-edge-color);stroke:none}.end-state-inner,.end-state-outer{fill:var(--md-mermaid-edge-color)}.end-state-inner,.node circle.state-end{stroke:var(--md-mermaid-label-bg-color)}.transition{stroke:var(--md-mermaid-edge-color)}[id^=state-fork] rect,[id^=state-join] rect{fill:var(--md-mermaid-edge-color)!important;stroke:none!important}.statediagram-cluster.statediagram-cluster .inner{fill:var(--md-default-bg-color)}.statediagram-cluster rect{fill:var(--md-mermaid-node-bg-color);stroke:var(--md-mermaid-node-fg-color)}.statediagram-state rect.divider{fill:var(--md-default-fg-color--lightest);stroke:var(--md-default-fg-color--lighter)}defs #statediagram-barbEnd{stroke:var(--md-mermaid-edge-color)}.attributeBoxEven,.attributeBoxOdd{fill:var(--md-mermaid-node-bg-color);stroke:var(--md-mermaid-node-fg-color)}.entityBox{fill:var(--md-mermaid-label-bg-color);stroke:var(--md-mermaid-node-fg-color)}.entityLabel{fill:var(--md-mermaid-label-fg-color);font-family:var(--md-mermaid-font-family)}.relationshipLabelBox{fill:var(--md-mermaid-label-bg-color);fill-opacity:1;background-color:var(--md-mermaid-label-bg-color);opacity:1}.relationshipLabel{fill:var(--md-mermaid-label-fg-color)}.relationshipLine{stroke:var(--md-mermaid-edge-color)}defs #ONE_OR_MORE_END *,defs #ONE_OR_MORE_START *,defs #ONLY_ONE_END *,defs #ONLY_ONE_START *,defs #ZERO_OR_MORE_END *,defs #ZERO_OR_MORE_START *,defs #ZERO_OR_ONE_END *,defs #ZERO_OR_ONE_START *{stroke:var(--md-mermaid-edge-color)!important}defs #ZERO_OR_MORE_END circle,defs #ZERO_OR_MORE_START circle{fill:var(--md-mermaid-label-bg-color)}.actor{fill:var(--md-mermaid-sequence-actor-bg-color);stroke:var(--md-mermaid-sequence-actor-border-color)}text.actor>tspan{fill:var(--md-mermaid-sequence-actor-fg-color);font-family:var(--md-mermaid-font-family)}line{stroke:var(--md-mermaid-sequence-actor-line-color)}.actor-man circle,.actor-man line{fill:var(--md-mermaid-sequence-actorman-bg-color);stroke:var(--md-mermaid-sequence-actorman-line-color)}.messageLine0,.messageLine1{stroke:var(--md-mermaid-sequence-message-line-color)}.note{fill:var(--md-mermaid-sequence-note-bg-color);stroke:var(--md-mermaid-sequence-note-border-color)}.loopText,.loopText>tspan,.messageText,.noteText>tspan{stroke:none;font-family:var(--md-mermaid-font-family)!important}.messageText{fill:var(--md-mermaid-sequence-message-fg-color)}.loopText,.loopText>tspan{fill:var(--md-mermaid-sequence-loop-fg-color)}.noteText>tspan{fill:var(--md-mermaid-sequence-note-fg-color)}#arrowhead path{fill:var(--md-mermaid-sequence-message-line-color);stroke:none}.loopLine{fill:var(--md-mermaid-sequence-loop-bg-color);stroke:var(--md-mermaid-sequence-loop-border-color)}.labelBox{fill:var(--md-mermaid-sequence-label-bg-color);stroke:none}.labelText,.labelText>span{fill:var(--md-mermaid-sequence-label-fg-color);font-family:var(--md-mermaid-font-family)}.sequenceNumber{fill:var(--md-mermaid-sequence-number-fg-color)}rect.rect{fill:var(--md-mermaid-sequence-box-bg-color);stroke:none}rect.rect+text.text{fill:var(--md-mermaid-sequence-box-fg-color)}defs #sequencenumber{fill:var(--md-mermaid-sequence-number-bg-color)!important}";var Br,Da=0;function Va(){return typeof mermaid=="undefined"||mermaid instanceof Element?wt("https://unpkg.com/mermaid@10/dist/mermaid.min.js"):I(void 0)}function In(e){return e.classList.remove("mermaid"),Br||(Br=Va().pipe(E(()=>mermaid.initialize({startOnLoad:!1,themeCSS:Rn,sequence:{actorFontSize:"16px",messageFontSize:"16px",noteFontSize:"16px"}})),m(()=>{}),G(1))),Br.subscribe(()=>ao(this,null,function*(){e.classList.add("mermaid");let t=`__mermaid_${Da++}`,r=x("div",{class:"mermaid"}),o=e.textContent,{svg:n,fn:i}=yield mermaid.render(t,o),a=r.attachShadow({mode:"closed"});a.innerHTML=n,e.replaceWith(r),i==null||i(a)})),Br.pipe(m(()=>({ref:e})))}var Fn=x("table");function jn(e){return e.replaceWith(Fn),Fn.replaceWith(On(e)),I({ref:e})}function Na(e){let t=e.find(r=>r.checked)||e[0];return S(...e.map(r=>d(r,"change").pipe(m(()=>P(`label[for="${r.id}"]`))))).pipe(Q(P(`label[for="${t.id}"]`)),m(r=>({active:r})))}function Wn(e,{viewport$:t,target$:r}){let o=P(".tabbed-labels",e),n=$(":scope > input",e),i=Qr("prev");e.append(i);let a=Qr("next");return e.append(a),C(()=>{let s=new g,p=s.pipe(X(),ne(!0));z([s,ge(e),tt(e)]).pipe(U(p),Le(1,me)).subscribe({next([{active:c},l]){let f=Ue(c),{width:u}=ce(c);e.style.setProperty("--md-indicator-x",`${f.x}px`),e.style.setProperty("--md-indicator-width",`${u}px`);let h=pr(o);(f.xh.x+l.width)&&o.scrollTo({left:Math.max(0,f.x-16),behavior:"smooth"})},complete(){e.style.removeProperty("--md-indicator-x"),e.style.removeProperty("--md-indicator-width")}}),z([De(o),ge(o)]).pipe(U(p)).subscribe(([c,l])=>{let f=Tt(o);i.hidden=c.x<16,a.hidden=c.x>f.width-l.width-16}),S(d(i,"click").pipe(m(()=>-1)),d(a,"click").pipe(m(()=>1))).pipe(U(p)).subscribe(c=>{let{width:l}=ce(o);o.scrollBy({left:l*c,behavior:"smooth"})}),r.pipe(U(p),b(c=>n.includes(c))).subscribe(c=>c.click()),o.classList.add("tabbed-labels--linked");for(let c of n){let l=P(`label[for="${c.id}"]`);l.replaceChildren(x("a",{href:`#${l.htmlFor}`,tabIndex:-1},...Array.from(l.childNodes))),d(l.firstElementChild,"click").pipe(U(p),b(f=>!(f.metaKey||f.ctrlKey)),E(f=>{f.preventDefault(),f.stopPropagation()})).subscribe(()=>{history.replaceState({},"",`#${l.htmlFor}`),l.click()})}return B("content.tabs.link")&&s.pipe(Ce(1),ee(t)).subscribe(([{active:c},{offset:l}])=>{let f=c.innerText.trim();if(c.hasAttribute("data-md-switching"))c.removeAttribute("data-md-switching");else{let u=e.offsetTop-l.y;for(let w of $("[data-tabs]"))for(let A of $(":scope > input",w)){let te=P(`label[for="${A.id}"]`);if(te!==c&&te.innerText.trim()===f){te.setAttribute("data-md-switching",""),A.click();break}}window.scrollTo({top:e.offsetTop-u});let h=__md_get("__tabs")||[];__md_set("__tabs",[...new Set([f,...h])])}}),s.pipe(U(p)).subscribe(()=>{for(let c of $("audio, video",e))c.pause()}),Na(n).pipe(E(c=>s.next(c)),L(()=>s.complete()),m(c=>R({ref:e},c)))}).pipe(Qe(se))}function Un(e,{viewport$:t,target$:r,print$:o}){return S(...$(".annotate:not(.highlight)",e).map(n=>Cn(n,{target$:r,print$:o})),...$("pre:not(.mermaid) > code",e).map(n=>$n(n,{target$:r,print$:o})),...$("pre.mermaid",e).map(n=>In(n)),...$("table:not([class])",e).map(n=>jn(n)),...$("details",e).map(n=>Pn(n,{target$:r,print$:o})),...$("[data-tabs]",e).map(n=>Wn(n,{viewport$:t,target$:r})),...$("[title]",e).filter(()=>B("content.tooltips")).map(n=>lt(n,{viewport$:t})))}function za(e,{alert$:t}){return t.pipe(v(r=>S(I(!0),I(!1).pipe(Ge(2e3))).pipe(m(o=>({message:r,active:o})))))}function Dn(e,t){let r=P(".md-typeset",e);return C(()=>{let o=new g;return o.subscribe(({message:n,active:i})=>{e.classList.toggle("md-dialog--active",i),r.textContent=n}),za(e,t).pipe(E(n=>o.next(n)),L(()=>o.complete()),m(n=>R({ref:e},n)))})}var qa=0;function Qa(e,t){document.body.append(e);let{width:r}=ce(e);e.style.setProperty("--md-tooltip-width",`${r}px`),e.remove();let o=cr(t),n=typeof o!="undefined"?De(o):I({x:0,y:0}),i=S(et(t),kt(t)).pipe(K());return z([i,n]).pipe(m(([a,s])=>{let{x:p,y:c}=Ue(t),l=ce(t),f=t.closest("table");return f&&t.parentElement&&(p+=f.offsetLeft+t.parentElement.offsetLeft,c+=f.offsetTop+t.parentElement.offsetTop),{active:a,offset:{x:p-s.x+l.width/2-r/2,y:c-s.y+l.height+8}}}))}function Vn(e){let t=e.title;if(!t.length)return O;let r=`__tooltip_${qa++}`,o=Pt(r,"inline"),n=P(".md-typeset",o);return n.innerHTML=t,C(()=>{let i=new g;return i.subscribe({next({offset:a}){o.style.setProperty("--md-tooltip-x",`${a.x}px`),o.style.setProperty("--md-tooltip-y",`${a.y}px`)},complete(){o.style.removeProperty("--md-tooltip-x"),o.style.removeProperty("--md-tooltip-y")}}),S(i.pipe(b(({active:a})=>a)),i.pipe(_e(250),b(({active:a})=>!a))).subscribe({next({active:a}){a?(e.insertAdjacentElement("afterend",o),e.setAttribute("aria-describedby",r),e.removeAttribute("title")):(o.remove(),e.removeAttribute("aria-describedby"),e.setAttribute("title",t))},complete(){o.remove(),e.removeAttribute("aria-describedby"),e.setAttribute("title",t)}}),i.pipe(Le(16,me)).subscribe(({active:a})=>{o.classList.toggle("md-tooltip--active",a)}),i.pipe(ct(125,me),b(()=>!!e.offsetParent),m(()=>e.offsetParent.getBoundingClientRect()),m(({x:a})=>a)).subscribe({next(a){a?o.style.setProperty("--md-tooltip-0",`${-a}px`):o.style.removeProperty("--md-tooltip-0")},complete(){o.style.removeProperty("--md-tooltip-0")}}),Qa(o,e).pipe(E(a=>i.next(a)),L(()=>i.complete()),m(a=>R({ref:e},a)))}).pipe(Qe(se))}function Ka({viewport$:e}){if(!B("header.autohide"))return I(!1);let t=e.pipe(m(({offset:{y:n}})=>n),Ye(2,1),m(([n,i])=>[nMath.abs(i-n.y)>100),m(([,[n]])=>n),K()),o=Ve("search");return z([e,o]).pipe(m(([{offset:n},i])=>n.y>400&&!i),K(),v(n=>n?r:I(!1)),Q(!1))}function Nn(e,t){return C(()=>z([ge(e),Ka(t)])).pipe(m(([{height:r},o])=>({height:r,hidden:o})),K((r,o)=>r.height===o.height&&r.hidden===o.hidden),G(1))}function zn(e,{header$:t,main$:r}){return C(()=>{let o=new g,n=o.pipe(X(),ne(!0));o.pipe(Z("active"),We(t)).subscribe(([{active:a},{hidden:s}])=>{e.classList.toggle("md-header--shadow",a&&!s),e.hidden=s});let i=ue($("[title]",e)).pipe(b(()=>B("content.tooltips")),oe(a=>Vn(a)));return r.subscribe(o),t.pipe(U(n),m(a=>R({ref:e},a)),Pe(i.pipe(U(n))))})}function Ya(e,{viewport$:t,header$:r}){return mr(e,{viewport$:t,header$:r}).pipe(m(({offset:{y:o}})=>{let{height:n}=ce(e);return{active:o>=n}}),Z("active"))}function qn(e,t){return C(()=>{let r=new g;r.subscribe({next({active:n}){e.classList.toggle("md-header__title--active",n)},complete(){e.classList.remove("md-header__title--active")}});let o=fe(".md-content h1");return typeof o=="undefined"?O:Ya(o,t).pipe(E(n=>r.next(n)),L(()=>r.complete()),m(n=>R({ref:e},n)))})}function Qn(e,{viewport$:t,header$:r}){let o=r.pipe(m(({height:i})=>i),K()),n=o.pipe(v(()=>ge(e).pipe(m(({height:i})=>({top:e.offsetTop,bottom:e.offsetTop+i})),Z("bottom"))));return z([o,n,t]).pipe(m(([i,{top:a,bottom:s},{offset:{y:p},size:{height:c}}])=>(c=Math.max(0,c-Math.max(0,a-p,i)-Math.max(0,c+p-s)),{offset:a-i,height:c,active:a-i<=p})),K((i,a)=>i.offset===a.offset&&i.height===a.height&&i.active===a.active))}function Ba(e){let t=__md_get("__palette")||{index:e.findIndex(o=>matchMedia(o.getAttribute("data-md-color-media")).matches)},r=Math.max(0,Math.min(t.index,e.length-1));return I(...e).pipe(oe(o=>d(o,"change").pipe(m(()=>o))),Q(e[r]),m(o=>({index:e.indexOf(o),color:{media:o.getAttribute("data-md-color-media"),scheme:o.getAttribute("data-md-color-scheme"),primary:o.getAttribute("data-md-color-primary"),accent:o.getAttribute("data-md-color-accent")}})),G(1))}function Kn(e){let t=$("input",e),r=x("meta",{name:"theme-color"});document.head.appendChild(r);let o=x("meta",{name:"color-scheme"});document.head.appendChild(o);let n=$t("(prefers-color-scheme: light)");return C(()=>{let i=new g;return i.subscribe(a=>{if(document.body.setAttribute("data-md-color-switching",""),a.color.media==="(prefers-color-scheme)"){let s=matchMedia("(prefers-color-scheme: light)"),p=document.querySelector(s.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");a.color.scheme=p.getAttribute("data-md-color-scheme"),a.color.primary=p.getAttribute("data-md-color-primary"),a.color.accent=p.getAttribute("data-md-color-accent")}for(let[s,p]of Object.entries(a.color))document.body.setAttribute(`data-md-color-${s}`,p);for(let s=0;sa.key==="Enter"),ee(i,(a,s)=>s)).subscribe(({index:a})=>{a=(a+1)%t.length,t[a].click(),t[a].focus()}),i.pipe(m(()=>{let a=Se("header"),s=window.getComputedStyle(a);return o.content=s.colorScheme,s.backgroundColor.match(/\d+/g).map(p=>(+p).toString(16).padStart(2,"0")).join("")})).subscribe(a=>r.content=`#${a}`),i.pipe(be(se)).subscribe(()=>{document.body.removeAttribute("data-md-color-switching")}),Ba(t).pipe(U(n.pipe(Ce(1))),st(),E(a=>i.next(a)),L(()=>i.complete()),m(a=>R({ref:e},a)))})}function Yn(e,{progress$:t}){return C(()=>{let r=new g;return r.subscribe(({value:o})=>{e.style.setProperty("--md-progress-value",`${o}`)}),t.pipe(E(o=>r.next({value:o})),L(()=>r.complete()),m(o=>({ref:e,value:o})))})}var Gr=Vt(Yr());function Ga(e){e.setAttribute("data-md-copying","");let t=e.closest("[data-copy]"),r=t?t.getAttribute("data-copy"):e.innerText;return e.removeAttribute("data-md-copying"),r.trimEnd()}function Bn({alert$:e}){Gr.default.isSupported()&&new F(t=>{new Gr.default("[data-clipboard-target], [data-clipboard-text]",{text:r=>r.getAttribute("data-clipboard-text")||Ga(P(r.getAttribute("data-clipboard-target")))}).on("success",r=>t.next(r))}).pipe(E(t=>{t.trigger.focus()}),m(()=>Ee("clipboard.copied"))).subscribe(e)}function Gn(e,t){return e.protocol=t.protocol,e.hostname=t.hostname,e}function Ja(e,t){let r=new Map;for(let o of $("url",e)){let n=P("loc",o),i=[Gn(new URL(n.textContent),t)];r.set(`${i[0]}`,i);for(let a of $("[rel=alternate]",o)){let s=a.getAttribute("href");s!=null&&i.push(Gn(new URL(s),t))}}return r}function ur(e){return mn(new URL("sitemap.xml",e)).pipe(m(t=>Ja(t,new URL(e))),ve(()=>I(new Map)))}function Xa(e,t){if(!(e.target instanceof Element))return O;let r=e.target.closest("a");if(r===null)return O;if(r.target||e.metaKey||e.ctrlKey)return O;let o=new URL(r.href);return o.search=o.hash="",t.has(`${o}`)?(e.preventDefault(),I(new URL(r.href))):O}function Jn(e){let t=new Map;for(let r of $(":scope > *",e.head))t.set(r.outerHTML,r);return t}function Xn(e){for(let t of $("[href], [src]",e))for(let r of["href","src"]){let o=t.getAttribute(r);if(o&&!/^(?:[a-z]+:)?\/\//i.test(o)){t[r]=t[r];break}}return I(e)}function Za(e){for(let o of["[data-md-component=announce]","[data-md-component=container]","[data-md-component=header-topic]","[data-md-component=outdated]","[data-md-component=logo]","[data-md-component=skip]",...B("navigation.tabs.sticky")?["[data-md-component=tabs]"]:[]]){let n=fe(o),i=fe(o,e);typeof n!="undefined"&&typeof i!="undefined"&&n.replaceWith(i)}let t=Jn(document);for(let[o,n]of Jn(e))t.has(o)?t.delete(o):document.head.appendChild(n);for(let o of t.values()){let n=o.getAttribute("name");n!=="theme-color"&&n!=="color-scheme"&&o.remove()}let r=Se("container");return je($("script",r)).pipe(v(o=>{let n=e.createElement("script");if(o.src){for(let i of o.getAttributeNames())n.setAttribute(i,o.getAttribute(i));return o.replaceWith(n),new F(i=>{n.onload=()=>i.complete()})}else return n.textContent=o.textContent,o.replaceWith(n),O}),X(),ne(document))}function Zn({location$:e,viewport$:t,progress$:r}){let o=ye();if(location.protocol==="file:")return O;let n=ur(o.base);I(document).subscribe(Xn);let i=d(document.body,"click").pipe(We(n),v(([p,c])=>Xa(p,c)),pe()),a=d(window,"popstate").pipe(m(xe),pe());i.pipe(ee(t)).subscribe(([p,{offset:c}])=>{history.replaceState(c,""),history.pushState(null,"",p)}),S(i,a).subscribe(e);let s=e.pipe(Z("pathname"),v(p=>ln(p,{progress$:r}).pipe(ve(()=>(pt(p,!0),O)))),v(Xn),v(Za),pe());return S(s.pipe(ee(e,(p,c)=>c)),s.pipe(v(()=>e),Z("pathname"),v(()=>e),Z("hash")),e.pipe(K((p,c)=>p.pathname===c.pathname&&p.hash===c.hash),v(()=>i),E(()=>history.back()))).subscribe(p=>{var c,l;history.state!==null||!p.hash?window.scrollTo(0,(l=(c=history.state)==null?void 0:c.y)!=null?l:0):(history.scrollRestoration="auto",sn(p.hash),history.scrollRestoration="manual")}),e.subscribe(()=>{history.scrollRestoration="manual"}),d(window,"beforeunload").subscribe(()=>{history.scrollRestoration="auto"}),t.pipe(Z("offset"),_e(100)).subscribe(({offset:p})=>{history.replaceState(p,"")}),s}var ri=Vt(ti());function oi(e){let t=e.separator.split("|").map(n=>n.replace(/(\(\?[!=<][^)]+\))/g,"").length===0?"\uFFFD":n).join("|"),r=new RegExp(t,"img"),o=(n,i,a)=>`${i}${a}`;return n=>{n=n.replace(/[\s*+\-:~^]+/g," ").trim();let i=new RegExp(`(^|${e.separator}|)(${n.replace(/[|\\{}()[\]^$+*?.-]/g,"\\$&").replace(r,"|")})`,"img");return a=>(0,ri.default)(a).replace(i,o).replace(/<\/mark>(\s+)]*>/img,"$1")}}function It(e){return e.type===1}function dr(e){return e.type===3}function ni(e,t){let r=vn(e);return S(I(location.protocol!=="file:"),Ve("search")).pipe(Ae(o=>o),v(()=>t)).subscribe(({config:o,docs:n})=>r.next({type:0,data:{config:o,docs:n,options:{suggest:B("search.suggest")}}})),r}function ii({document$:e}){let t=ye(),r=Ne(new URL("../versions.json",t.base)).pipe(ve(()=>O)),o=r.pipe(m(n=>{let[,i]=t.base.match(/([^/]+)\/?$/);return n.find(({version:a,aliases:s})=>a===i||s.includes(i))||n[0]}));r.pipe(m(n=>new Map(n.map(i=>[`${new URL(`../${i.version}/`,t.base)}`,i]))),v(n=>d(document.body,"click").pipe(b(i=>!i.metaKey&&!i.ctrlKey),ee(o),v(([i,a])=>{if(i.target instanceof Element){let s=i.target.closest("a");if(s&&!s.target&&n.has(s.href)){let p=s.href;return!i.target.closest(".md-version")&&n.get(p)===a?O:(i.preventDefault(),I(p))}}return O}),v(i=>ur(new URL(i)).pipe(m(a=>{let p=xe().href.replace(t.base,i);return a.has(p.split("#")[0])?new URL(p):new URL(i)})))))).subscribe(n=>pt(n,!0)),z([r,o]).subscribe(([n,i])=>{P(".md-header__topic").appendChild(Mn(n,i))}),e.pipe(v(()=>o)).subscribe(n=>{var a;let i=__md_get("__outdated",sessionStorage);if(i===null){i=!0;let s=((a=t.version)==null?void 0:a.default)||"latest";Array.isArray(s)||(s=[s]);e:for(let p of s)for(let c of n.aliases.concat(n.version))if(new RegExp(p,"i").test(c)){i=!1;break e}__md_set("__outdated",i,sessionStorage)}if(i)for(let s of ae("outdated"))s.hidden=!1})}function ns(e,{worker$:t}){let{searchParams:r}=xe();r.has("q")&&(Je("search",!0),e.value=r.get("q"),e.focus(),Ve("search").pipe(Ae(i=>!i)).subscribe(()=>{let i=xe();i.searchParams.delete("q"),history.replaceState({},"",`${i}`)}));let o=et(e),n=S(t.pipe(Ae(It)),d(e,"keyup"),o).pipe(m(()=>e.value),K());return z([n,o]).pipe(m(([i,a])=>({value:i,focus:a})),G(1))}function ai(e,{worker$:t}){let r=new g,o=r.pipe(X(),ne(!0));z([t.pipe(Ae(It)),r],(i,a)=>a).pipe(Z("value")).subscribe(({value:i})=>t.next({type:2,data:i})),r.pipe(Z("focus")).subscribe(({focus:i})=>{i&&Je("search",i)}),d(e.form,"reset").pipe(U(o)).subscribe(()=>e.focus());let n=P("header [for=__search]");return d(n,"click").subscribe(()=>e.focus()),ns(e,{worker$:t}).pipe(E(i=>r.next(i)),L(()=>r.complete()),m(i=>R({ref:e},i)),G(1))}function si(e,{worker$:t,query$:r}){let o=new g,n=tn(e.parentElement).pipe(b(Boolean)),i=e.parentElement,a=P(":scope > :first-child",e),s=P(":scope > :last-child",e);Ve("search").subscribe(l=>s.setAttribute("role",l?"list":"presentation")),o.pipe(ee(r),Ur(t.pipe(Ae(It)))).subscribe(([{items:l},{value:f}])=>{switch(l.length){case 0:a.textContent=f.length?Ee("search.result.none"):Ee("search.result.placeholder");break;case 1:a.textContent=Ee("search.result.one");break;default:let u=sr(l.length);a.textContent=Ee("search.result.other",u)}});let p=o.pipe(E(()=>s.innerHTML=""),v(({items:l})=>S(I(...l.slice(0,10)),I(...l.slice(10)).pipe(Ye(4),Vr(n),v(([f])=>f)))),m(Tn),pe());return p.subscribe(l=>s.appendChild(l)),p.pipe(oe(l=>{let f=fe("details",l);return typeof f=="undefined"?O:d(f,"toggle").pipe(U(o),m(()=>f))})).subscribe(l=>{l.open===!1&&l.offsetTop<=i.scrollTop&&i.scrollTo({top:l.offsetTop})}),t.pipe(b(dr),m(({data:l})=>l)).pipe(E(l=>o.next(l)),L(()=>o.complete()),m(l=>R({ref:e},l)))}function is(e,{query$:t}){return t.pipe(m(({value:r})=>{let o=xe();return o.hash="",r=r.replace(/\s+/g,"+").replace(/&/g,"%26").replace(/=/g,"%3D"),o.search=`q=${r}`,{url:o}}))}function ci(e,t){let r=new g,o=r.pipe(X(),ne(!0));return r.subscribe(({url:n})=>{e.setAttribute("data-clipboard-text",e.href),e.href=`${n}`}),d(e,"click").pipe(U(o)).subscribe(n=>n.preventDefault()),is(e,t).pipe(E(n=>r.next(n)),L(()=>r.complete()),m(n=>R({ref:e},n)))}function pi(e,{worker$:t,keyboard$:r}){let o=new g,n=Se("search-query"),i=S(d(n,"keydown"),d(n,"focus")).pipe(be(se),m(()=>n.value),K());return o.pipe(We(i),m(([{suggest:s},p])=>{let c=p.split(/([\s-]+)/);if(s!=null&&s.length&&c[c.length-1]){let l=s[s.length-1];l.startsWith(c[c.length-1])&&(c[c.length-1]=l)}else c.length=0;return c})).subscribe(s=>e.innerHTML=s.join("").replace(/\s/g," ")),r.pipe(b(({mode:s})=>s==="search")).subscribe(s=>{switch(s.type){case"ArrowRight":e.innerText.length&&n.selectionStart===n.value.length&&(n.value=e.innerText);break}}),t.pipe(b(dr),m(({data:s})=>s)).pipe(E(s=>o.next(s)),L(()=>o.complete()),m(()=>({ref:e})))}function li(e,{index$:t,keyboard$:r}){let o=ye();try{let n=ni(o.search,t),i=Se("search-query",e),a=Se("search-result",e);d(e,"click").pipe(b(({target:p})=>p instanceof Element&&!!p.closest("a"))).subscribe(()=>Je("search",!1)),r.pipe(b(({mode:p})=>p==="search")).subscribe(p=>{let c=Re();switch(p.type){case"Enter":if(c===i){let l=new Map;for(let f of $(":first-child [href]",a)){let u=f.firstElementChild;l.set(f,parseFloat(u.getAttribute("data-md-score")))}if(l.size){let[[f]]=[...l].sort(([,u],[,h])=>h-u);f.click()}p.claim()}break;case"Escape":case"Tab":Je("search",!1),i.blur();break;case"ArrowUp":case"ArrowDown":if(typeof c=="undefined")i.focus();else{let l=[i,...$(":not(details) > [href], summary, details[open] [href]",a)],f=Math.max(0,(Math.max(0,l.indexOf(c))+l.length+(p.type==="ArrowUp"?-1:1))%l.length);l[f].focus()}p.claim();break;default:i!==Re()&&i.focus()}}),r.pipe(b(({mode:p})=>p==="global")).subscribe(p=>{switch(p.type){case"f":case"s":case"/":i.focus(),i.select(),p.claim();break}});let s=ai(i,{worker$:n});return S(s,si(a,{worker$:n,query$:s})).pipe(Pe(...ae("search-share",e).map(p=>ci(p,{query$:s})),...ae("search-suggest",e).map(p=>pi(p,{worker$:n,keyboard$:r}))))}catch(n){return e.hidden=!0,Ke}}function mi(e,{index$:t,location$:r}){return z([t,r.pipe(Q(xe()),b(o=>!!o.searchParams.get("h")))]).pipe(m(([o,n])=>oi(o.config)(n.searchParams.get("h"))),m(o=>{var a;let n=new Map,i=document.createNodeIterator(e,NodeFilter.SHOW_TEXT);for(let s=i.nextNode();s;s=i.nextNode())if((a=s.parentElement)!=null&&a.offsetHeight){let p=s.textContent,c=o(p);c.length>p.length&&n.set(s,c)}for(let[s,p]of n){let{childNodes:c}=x("span",null,p);s.replaceWith(...Array.from(c))}return{ref:e,nodes:n}}))}function as(e,{viewport$:t,main$:r}){let o=e.closest(".md-grid"),n=o.offsetTop-o.parentElement.offsetTop;return z([r,t]).pipe(m(([{offset:i,height:a},{offset:{y:s}}])=>(a=a+Math.min(n,Math.max(0,s-i))-n,{height:a,locked:s>=i+n})),K((i,a)=>i.height===a.height&&i.locked===a.locked))}function Jr(e,o){var n=o,{header$:t}=n,r=io(n,["header$"]);let i=P(".md-sidebar__scrollwrap",e),{y:a}=Ue(i);return C(()=>{let s=new g,p=s.pipe(X(),ne(!0)),c=s.pipe(Le(0,me));return c.pipe(ee(t)).subscribe({next([{height:l},{height:f}]){i.style.height=`${l-2*a}px`,e.style.top=`${f}px`},complete(){i.style.height="",e.style.top=""}}),c.pipe(Ae()).subscribe(()=>{for(let l of $(".md-nav__link--active[href]",e)){if(!l.clientHeight)continue;let f=l.closest(".md-sidebar__scrollwrap");if(typeof f!="undefined"){let u=l.offsetTop-f.offsetTop,{height:h}=ce(f);f.scrollTo({top:u-h/2})}}}),ue($("label[tabindex]",e)).pipe(oe(l=>d(l,"click").pipe(be(se),m(()=>l),U(p)))).subscribe(l=>{let f=P(`[id="${l.htmlFor}"]`);P(`[aria-labelledby="${l.id}"]`).setAttribute("aria-expanded",`${f.checked}`)}),as(e,r).pipe(E(l=>s.next(l)),L(()=>s.complete()),m(l=>R({ref:e},l)))})}function fi(e,t){if(typeof t!="undefined"){let r=`https://api.github.com/repos/${e}/${t}`;return Ct(Ne(`${r}/releases/latest`).pipe(ve(()=>O),m(o=>({version:o.tag_name})),Be({})),Ne(r).pipe(ve(()=>O),m(o=>({stars:o.stargazers_count,forks:o.forks_count})),Be({}))).pipe(m(([o,n])=>R(R({},o),n)))}else{let r=`https://api.github.com/users/${e}`;return Ne(r).pipe(m(o=>({repositories:o.public_repos})),Be({}))}}function ui(e,t){let r=`https://${e}/api/v4/projects/${encodeURIComponent(t)}`;return Ne(r).pipe(ve(()=>O),m(({star_count:o,forks_count:n})=>({stars:o,forks:n})),Be({}))}function di(e){let t=e.match(/^.+github\.com\/([^/]+)\/?([^/]+)?/i);if(t){let[,r,o]=t;return fi(r,o)}if(t=e.match(/^.+?([^/]*gitlab[^/]+)\/(.+?)\/?$/i),t){let[,r,o]=t;return ui(r,o)}return O}var ss;function cs(e){return ss||(ss=C(()=>{let t=__md_get("__source",sessionStorage);if(t)return I(t);if(ae("consent").length){let o=__md_get("__consent");if(!(o&&o.github))return O}return di(e.href).pipe(E(o=>__md_set("__source",o,sessionStorage)))}).pipe(ve(()=>O),b(t=>Object.keys(t).length>0),m(t=>({facts:t})),G(1)))}function hi(e){let t=P(":scope > :last-child",e);return C(()=>{let r=new g;return r.subscribe(({facts:o})=>{t.appendChild(Sn(o)),t.classList.add("md-source__repository--active")}),cs(e).pipe(E(o=>r.next(o)),L(()=>r.complete()),m(o=>R({ref:e},o)))})}function ps(e,{viewport$:t,header$:r}){return ge(document.body).pipe(v(()=>mr(e,{header$:r,viewport$:t})),m(({offset:{y:o}})=>({hidden:o>=10})),Z("hidden"))}function bi(e,t){return C(()=>{let r=new g;return r.subscribe({next({hidden:o}){e.hidden=o},complete(){e.hidden=!1}}),(B("navigation.tabs.sticky")?I({hidden:!1}):ps(e,t)).pipe(E(o=>r.next(o)),L(()=>r.complete()),m(o=>R({ref:e},o)))})}function ls(e,{viewport$:t,header$:r}){let o=new Map,n=$(".md-nav__link",e);for(let s of n){let p=decodeURIComponent(s.hash.substring(1)),c=fe(`[id="${p}"]`);typeof c!="undefined"&&o.set(s,c)}let i=r.pipe(Z("height"),m(({height:s})=>{let p=Se("main"),c=P(":scope > :first-child",p);return s+.8*(c.offsetTop-p.offsetTop)}),pe());return ge(document.body).pipe(Z("height"),v(s=>C(()=>{let p=[];return I([...o].reduce((c,[l,f])=>{for(;p.length&&o.get(p[p.length-1]).tagName>=f.tagName;)p.pop();let u=f.offsetTop;for(;!u&&f.parentElement;)f=f.parentElement,u=f.offsetTop;let h=f.offsetParent;for(;h;h=h.offsetParent)u+=h.offsetTop;return c.set([...p=[...p,l]].reverse(),u)},new Map))}).pipe(m(p=>new Map([...p].sort(([,c],[,l])=>c-l))),We(i),v(([p,c])=>t.pipe(jr(([l,f],{offset:{y:u},size:h})=>{let w=u+h.height>=Math.floor(s.height);for(;f.length;){let[,A]=f[0];if(A-c=u&&!w)f=[l.pop(),...f];else break}return[l,f]},[[],[...p]]),K((l,f)=>l[0]===f[0]&&l[1]===f[1])))))).pipe(m(([s,p])=>({prev:s.map(([c])=>c),next:p.map(([c])=>c)})),Q({prev:[],next:[]}),Ye(2,1),m(([s,p])=>s.prev.length{let i=new g,a=i.pipe(X(),ne(!0));if(i.subscribe(({prev:s,next:p})=>{for(let[c]of p)c.classList.remove("md-nav__link--passed"),c.classList.remove("md-nav__link--active");for(let[c,[l]]of s.entries())l.classList.add("md-nav__link--passed"),l.classList.toggle("md-nav__link--active",c===s.length-1)}),B("toc.follow")){let s=S(t.pipe(_e(1),m(()=>{})),t.pipe(_e(250),m(()=>"smooth")));i.pipe(b(({prev:p})=>p.length>0),We(o.pipe(be(se))),ee(s)).subscribe(([[{prev:p}],c])=>{let[l]=p[p.length-1];if(l.offsetHeight){let f=cr(l);if(typeof f!="undefined"){let u=l.offsetTop-f.offsetTop,{height:h}=ce(f);f.scrollTo({top:u-h/2,behavior:c})}}})}return B("navigation.tracking")&&t.pipe(U(a),Z("offset"),_e(250),Ce(1),U(n.pipe(Ce(1))),st({delay:250}),ee(i)).subscribe(([,{prev:s}])=>{let p=xe(),c=s[s.length-1];if(c&&c.length){let[l]=c,{hash:f}=new URL(l.href);p.hash!==f&&(p.hash=f,history.replaceState({},"",`${p}`))}else p.hash="",history.replaceState({},"",`${p}`)}),ls(e,{viewport$:t,header$:r}).pipe(E(s=>i.next(s)),L(()=>i.complete()),m(s=>R({ref:e},s)))})}function ms(e,{viewport$:t,main$:r,target$:o}){let n=t.pipe(m(({offset:{y:a}})=>a),Ye(2,1),m(([a,s])=>a>s&&s>0),K()),i=r.pipe(m(({active:a})=>a));return z([i,n]).pipe(m(([a,s])=>!(a&&s)),K(),U(o.pipe(Ce(1))),ne(!0),st({delay:250}),m(a=>({hidden:a})))}function gi(e,{viewport$:t,header$:r,main$:o,target$:n}){let i=new g,a=i.pipe(X(),ne(!0));return i.subscribe({next({hidden:s}){e.hidden=s,s?(e.setAttribute("tabindex","-1"),e.blur()):e.removeAttribute("tabindex")},complete(){e.style.top="",e.hidden=!0,e.removeAttribute("tabindex")}}),r.pipe(U(a),Z("height")).subscribe(({height:s})=>{e.style.top=`${s+16}px`}),d(e,"click").subscribe(s=>{s.preventDefault(),window.scrollTo({top:0})}),ms(e,{viewport$:t,main$:o,target$:n}).pipe(E(s=>i.next(s)),L(()=>i.complete()),m(s=>R({ref:e},s)))}function xi({document$:e,viewport$:t}){e.pipe(v(()=>$(".md-ellipsis")),oe(r=>tt(r).pipe(U(e.pipe(Ce(1))),b(o=>o),m(()=>r),Te(1))),b(r=>r.offsetWidth{let o=r.innerText,n=r.closest("a")||r;return n.title=o,B("content.tooltips")?lt(n,{viewport$:t}).pipe(U(e.pipe(Ce(1))),L(()=>n.removeAttribute("title"))):O})).subscribe(),B("content.tooltips")&&e.pipe(v(()=>$(".md-status")),oe(r=>lt(r,{viewport$:t}))).subscribe()}function yi({document$:e,tablet$:t}){e.pipe(v(()=>$(".md-toggle--indeterminate")),E(r=>{r.indeterminate=!0,r.checked=!1}),oe(r=>d(r,"change").pipe(Dr(()=>r.classList.contains("md-toggle--indeterminate")),m(()=>r))),ee(t)).subscribe(([r,o])=>{r.classList.remove("md-toggle--indeterminate"),o&&(r.checked=!1)})}function fs(){return/(iPad|iPhone|iPod)/.test(navigator.userAgent)}function Ei({document$:e}){e.pipe(v(()=>$("[data-md-scrollfix]")),E(t=>t.removeAttribute("data-md-scrollfix")),b(fs),oe(t=>d(t,"touchstart").pipe(m(()=>t)))).subscribe(t=>{let r=t.scrollTop;r===0?t.scrollTop=1:r+t.offsetHeight===t.scrollHeight&&(t.scrollTop=r-1)})}function wi({viewport$:e,tablet$:t}){z([Ve("search"),t]).pipe(m(([r,o])=>r&&!o),v(r=>I(r).pipe(Ge(r?400:100))),ee(e)).subscribe(([r,{offset:{y:o}}])=>{if(r)document.body.setAttribute("data-md-scrolllock",""),document.body.style.top=`-${o}px`;else{let n=-1*parseInt(document.body.style.top,10);document.body.removeAttribute("data-md-scrolllock"),document.body.style.top="",n&&window.scrollTo(0,n)}})}Object.entries||(Object.entries=function(e){let t=[];for(let r of Object.keys(e))t.push([r,e[r]]);return t});Object.values||(Object.values=function(e){let t=[];for(let r of Object.keys(e))t.push(e[r]);return t});typeof Element!="undefined"&&(Element.prototype.scrollTo||(Element.prototype.scrollTo=function(e,t){typeof e=="object"?(this.scrollLeft=e.left,this.scrollTop=e.top):(this.scrollLeft=e,this.scrollTop=t)}),Element.prototype.replaceWith||(Element.prototype.replaceWith=function(...e){let t=this.parentNode;if(t){e.length===0&&t.removeChild(this);for(let r=e.length-1;r>=0;r--){let o=e[r];typeof o=="string"?o=document.createTextNode(o):o.parentNode&&o.parentNode.removeChild(o),r?t.insertBefore(this.previousSibling,o):t.replaceChild(o,this)}}}));function us(){return location.protocol==="file:"?wt(`${new URL("search/search_index.js",Xr.base)}`).pipe(m(()=>__index),G(1)):Ne(new URL("search/search_index.json",Xr.base))}document.documentElement.classList.remove("no-js");document.documentElement.classList.add("js");var ot=Yo(),jt=nn(),Ot=cn(jt),Zr=on(),Oe=bn(),hr=$t("(min-width: 960px)"),Si=$t("(min-width: 1220px)"),Oi=pn(),Xr=ye(),Mi=document.forms.namedItem("search")?us():Ke,eo=new g;Bn({alert$:eo});var to=new g;B("navigation.instant")&&Zn({location$:jt,viewport$:Oe,progress$:to}).subscribe(ot);var Ti;((Ti=Xr.version)==null?void 0:Ti.provider)==="mike"&&ii({document$:ot});S(jt,Ot).pipe(Ge(125)).subscribe(()=>{Je("drawer",!1),Je("search",!1)});Zr.pipe(b(({mode:e})=>e==="global")).subscribe(e=>{switch(e.type){case"p":case",":let t=fe("link[rel=prev]");typeof t!="undefined"&&pt(t);break;case"n":case".":let r=fe("link[rel=next]");typeof r!="undefined"&&pt(r);break;case"Enter":let o=Re();o instanceof HTMLLabelElement&&o.click()}});xi({viewport$:Oe,document$:ot});yi({document$:ot,tablet$:hr});Ei({document$:ot});wi({viewport$:Oe,tablet$:hr});var rt=Nn(Se("header"),{viewport$:Oe}),Ft=ot.pipe(m(()=>Se("main")),v(e=>Qn(e,{viewport$:Oe,header$:rt})),G(1)),ds=S(...ae("consent").map(e=>xn(e,{target$:Ot})),...ae("dialog").map(e=>Dn(e,{alert$:eo})),...ae("header").map(e=>zn(e,{viewport$:Oe,header$:rt,main$:Ft})),...ae("palette").map(e=>Kn(e)),...ae("progress").map(e=>Yn(e,{progress$:to})),...ae("search").map(e=>li(e,{index$:Mi,keyboard$:Zr})),...ae("source").map(e=>hi(e))),hs=C(()=>S(...ae("announce").map(e=>gn(e)),...ae("content").map(e=>Un(e,{viewport$:Oe,target$:Ot,print$:Oi})),...ae("content").map(e=>B("search.highlight")?mi(e,{index$:Mi,location$:jt}):O),...ae("header-title").map(e=>qn(e,{viewport$:Oe,header$:rt})),...ae("sidebar").map(e=>e.getAttribute("data-md-type")==="navigation"?Nr(Si,()=>Jr(e,{viewport$:Oe,header$:rt,main$:Ft})):Nr(hr,()=>Jr(e,{viewport$:Oe,header$:rt,main$:Ft}))),...ae("tabs").map(e=>bi(e,{viewport$:Oe,header$:rt})),...ae("toc").map(e=>vi(e,{viewport$:Oe,header$:rt,main$:Ft,target$:Ot})),...ae("top").map(e=>gi(e,{viewport$:Oe,header$:rt,main$:Ft,target$:Ot})))),Li=ot.pipe(v(()=>hs),Pe(ds),G(1));Li.subscribe();window.document$=ot;window.location$=jt;window.target$=Ot;window.keyboard$=Zr;window.viewport$=Oe;window.tablet$=hr;window.screen$=Si;window.print$=Oi;window.alert$=eo;window.progress$=to;window.component$=Li;})(); +//# sourceMappingURL=bundle.fe8b6f2b.min.js.map + diff --git a/assets/javascripts/bundle.fe8b6f2b.min.js.map b/assets/javascripts/bundle.fe8b6f2b.min.js.map new file mode 100644 index 00000000..82635852 --- /dev/null +++ b/assets/javascripts/bundle.fe8b6f2b.min.js.map @@ -0,0 +1,7 @@ +{ + "version": 3, + "sources": ["node_modules/focus-visible/dist/focus-visible.js", "node_modules/clipboard/dist/clipboard.js", "node_modules/escape-html/index.js", "src/templates/assets/javascripts/bundle.ts", "node_modules/rxjs/node_modules/tslib/tslib.es6.js", "node_modules/rxjs/src/internal/util/isFunction.ts", "node_modules/rxjs/src/internal/util/createErrorClass.ts", "node_modules/rxjs/src/internal/util/UnsubscriptionError.ts", "node_modules/rxjs/src/internal/util/arrRemove.ts", "node_modules/rxjs/src/internal/Subscription.ts", "node_modules/rxjs/src/internal/config.ts", "node_modules/rxjs/src/internal/scheduler/timeoutProvider.ts", "node_modules/rxjs/src/internal/util/reportUnhandledError.ts", "node_modules/rxjs/src/internal/util/noop.ts", "node_modules/rxjs/src/internal/NotificationFactories.ts", "node_modules/rxjs/src/internal/util/errorContext.ts", "node_modules/rxjs/src/internal/Subscriber.ts", "node_modules/rxjs/src/internal/symbol/observable.ts", "node_modules/rxjs/src/internal/util/identity.ts", "node_modules/rxjs/src/internal/util/pipe.ts", "node_modules/rxjs/src/internal/Observable.ts", "node_modules/rxjs/src/internal/util/lift.ts", "node_modules/rxjs/src/internal/operators/OperatorSubscriber.ts", "node_modules/rxjs/src/internal/scheduler/animationFrameProvider.ts", "node_modules/rxjs/src/internal/util/ObjectUnsubscribedError.ts", "node_modules/rxjs/src/internal/Subject.ts", "node_modules/rxjs/src/internal/BehaviorSubject.ts", "node_modules/rxjs/src/internal/scheduler/dateTimestampProvider.ts", "node_modules/rxjs/src/internal/ReplaySubject.ts", "node_modules/rxjs/src/internal/scheduler/Action.ts", "node_modules/rxjs/src/internal/scheduler/intervalProvider.ts", "node_modules/rxjs/src/internal/scheduler/AsyncAction.ts", "node_modules/rxjs/src/internal/Scheduler.ts", "node_modules/rxjs/src/internal/scheduler/AsyncScheduler.ts", "node_modules/rxjs/src/internal/scheduler/async.ts", "node_modules/rxjs/src/internal/scheduler/QueueAction.ts", "node_modules/rxjs/src/internal/scheduler/QueueScheduler.ts", "node_modules/rxjs/src/internal/scheduler/queue.ts", "node_modules/rxjs/src/internal/scheduler/AnimationFrameAction.ts", "node_modules/rxjs/src/internal/scheduler/AnimationFrameScheduler.ts", "node_modules/rxjs/src/internal/scheduler/animationFrame.ts", "node_modules/rxjs/src/internal/observable/empty.ts", "node_modules/rxjs/src/internal/util/isScheduler.ts", "node_modules/rxjs/src/internal/util/args.ts", "node_modules/rxjs/src/internal/util/isArrayLike.ts", "node_modules/rxjs/src/internal/util/isPromise.ts", "node_modules/rxjs/src/internal/util/isInteropObservable.ts", "node_modules/rxjs/src/internal/util/isAsyncIterable.ts", "node_modules/rxjs/src/internal/util/throwUnobservableError.ts", "node_modules/rxjs/src/internal/symbol/iterator.ts", "node_modules/rxjs/src/internal/util/isIterable.ts", "node_modules/rxjs/src/internal/util/isReadableStreamLike.ts", "node_modules/rxjs/src/internal/observable/innerFrom.ts", "node_modules/rxjs/src/internal/util/executeSchedule.ts", "node_modules/rxjs/src/internal/operators/observeOn.ts", "node_modules/rxjs/src/internal/operators/subscribeOn.ts", "node_modules/rxjs/src/internal/scheduled/scheduleObservable.ts", "node_modules/rxjs/src/internal/scheduled/schedulePromise.ts", "node_modules/rxjs/src/internal/scheduled/scheduleArray.ts", "node_modules/rxjs/src/internal/scheduled/scheduleIterable.ts", "node_modules/rxjs/src/internal/scheduled/scheduleAsyncIterable.ts", "node_modules/rxjs/src/internal/scheduled/scheduleReadableStreamLike.ts", "node_modules/rxjs/src/internal/scheduled/scheduled.ts", "node_modules/rxjs/src/internal/observable/from.ts", "node_modules/rxjs/src/internal/observable/of.ts", "node_modules/rxjs/src/internal/observable/throwError.ts", "node_modules/rxjs/src/internal/util/EmptyError.ts", "node_modules/rxjs/src/internal/util/isDate.ts", "node_modules/rxjs/src/internal/operators/map.ts", "node_modules/rxjs/src/internal/util/mapOneOrManyArgs.ts", "node_modules/rxjs/src/internal/util/argsArgArrayOrObject.ts", "node_modules/rxjs/src/internal/util/createObject.ts", "node_modules/rxjs/src/internal/observable/combineLatest.ts", "node_modules/rxjs/src/internal/operators/mergeInternals.ts", "node_modules/rxjs/src/internal/operators/mergeMap.ts", "node_modules/rxjs/src/internal/operators/mergeAll.ts", "node_modules/rxjs/src/internal/operators/concatAll.ts", "node_modules/rxjs/src/internal/observable/concat.ts", "node_modules/rxjs/src/internal/observable/defer.ts", "node_modules/rxjs/src/internal/observable/fromEvent.ts", "node_modules/rxjs/src/internal/observable/fromEventPattern.ts", "node_modules/rxjs/src/internal/observable/timer.ts", "node_modules/rxjs/src/internal/observable/merge.ts", "node_modules/rxjs/src/internal/observable/never.ts", "node_modules/rxjs/src/internal/util/argsOrArgArray.ts", "node_modules/rxjs/src/internal/operators/filter.ts", "node_modules/rxjs/src/internal/observable/zip.ts", "node_modules/rxjs/src/internal/operators/audit.ts", "node_modules/rxjs/src/internal/operators/auditTime.ts", "node_modules/rxjs/src/internal/operators/bufferCount.ts", "node_modules/rxjs/src/internal/operators/catchError.ts", "node_modules/rxjs/src/internal/operators/scanInternals.ts", "node_modules/rxjs/src/internal/operators/combineLatest.ts", "node_modules/rxjs/src/internal/operators/combineLatestWith.ts", "node_modules/rxjs/src/internal/operators/debounce.ts", "node_modules/rxjs/src/internal/operators/debounceTime.ts", "node_modules/rxjs/src/internal/operators/defaultIfEmpty.ts", "node_modules/rxjs/src/internal/operators/take.ts", "node_modules/rxjs/src/internal/operators/ignoreElements.ts", "node_modules/rxjs/src/internal/operators/mapTo.ts", "node_modules/rxjs/src/internal/operators/delayWhen.ts", "node_modules/rxjs/src/internal/operators/delay.ts", "node_modules/rxjs/src/internal/operators/distinctUntilChanged.ts", "node_modules/rxjs/src/internal/operators/distinctUntilKeyChanged.ts", "node_modules/rxjs/src/internal/operators/throwIfEmpty.ts", "node_modules/rxjs/src/internal/operators/endWith.ts", "node_modules/rxjs/src/internal/operators/finalize.ts", "node_modules/rxjs/src/internal/operators/first.ts", "node_modules/rxjs/src/internal/operators/takeLast.ts", "node_modules/rxjs/src/internal/operators/merge.ts", "node_modules/rxjs/src/internal/operators/mergeWith.ts", "node_modules/rxjs/src/internal/operators/repeat.ts", "node_modules/rxjs/src/internal/operators/scan.ts", "node_modules/rxjs/src/internal/operators/share.ts", "node_modules/rxjs/src/internal/operators/shareReplay.ts", "node_modules/rxjs/src/internal/operators/skip.ts", "node_modules/rxjs/src/internal/operators/skipUntil.ts", "node_modules/rxjs/src/internal/operators/startWith.ts", "node_modules/rxjs/src/internal/operators/switchMap.ts", "node_modules/rxjs/src/internal/operators/takeUntil.ts", "node_modules/rxjs/src/internal/operators/takeWhile.ts", "node_modules/rxjs/src/internal/operators/tap.ts", "node_modules/rxjs/src/internal/operators/throttle.ts", "node_modules/rxjs/src/internal/operators/throttleTime.ts", "node_modules/rxjs/src/internal/operators/withLatestFrom.ts", "node_modules/rxjs/src/internal/operators/zip.ts", "node_modules/rxjs/src/internal/operators/zipWith.ts", "src/templates/assets/javascripts/browser/document/index.ts", "src/templates/assets/javascripts/browser/element/_/index.ts", "src/templates/assets/javascripts/browser/element/focus/index.ts", "src/templates/assets/javascripts/browser/element/hover/index.ts", "src/templates/assets/javascripts/utilities/h/index.ts", "src/templates/assets/javascripts/utilities/round/index.ts", "src/templates/assets/javascripts/browser/script/index.ts", "src/templates/assets/javascripts/browser/element/size/_/index.ts", "src/templates/assets/javascripts/browser/element/size/content/index.ts", "src/templates/assets/javascripts/browser/element/offset/_/index.ts", "src/templates/assets/javascripts/browser/element/offset/content/index.ts", "src/templates/assets/javascripts/browser/element/visibility/index.ts", "src/templates/assets/javascripts/browser/toggle/index.ts", "src/templates/assets/javascripts/browser/keyboard/index.ts", "src/templates/assets/javascripts/browser/location/_/index.ts", "src/templates/assets/javascripts/browser/location/hash/index.ts", "src/templates/assets/javascripts/browser/media/index.ts", "src/templates/assets/javascripts/browser/request/index.ts", "src/templates/assets/javascripts/browser/viewport/offset/index.ts", "src/templates/assets/javascripts/browser/viewport/size/index.ts", "src/templates/assets/javascripts/browser/viewport/_/index.ts", "src/templates/assets/javascripts/browser/viewport/at/index.ts", "src/templates/assets/javascripts/browser/worker/index.ts", "src/templates/assets/javascripts/_/index.ts", "src/templates/assets/javascripts/components/_/index.ts", "src/templates/assets/javascripts/components/announce/index.ts", "src/templates/assets/javascripts/components/consent/index.ts", "src/templates/assets/javascripts/templates/tooltip/index.tsx", "src/templates/assets/javascripts/templates/annotation/index.tsx", "src/templates/assets/javascripts/templates/clipboard/index.tsx", "src/templates/assets/javascripts/templates/search/index.tsx", "src/templates/assets/javascripts/templates/source/index.tsx", "src/templates/assets/javascripts/templates/tabbed/index.tsx", "src/templates/assets/javascripts/templates/table/index.tsx", "src/templates/assets/javascripts/templates/version/index.tsx", "src/templates/assets/javascripts/components/tooltip2/index.ts", "src/templates/assets/javascripts/components/content/annotation/_/index.ts", "src/templates/assets/javascripts/components/content/annotation/list/index.ts", "src/templates/assets/javascripts/components/content/annotation/block/index.ts", "src/templates/assets/javascripts/components/content/code/_/index.ts", "src/templates/assets/javascripts/components/content/details/index.ts", "src/templates/assets/javascripts/components/content/mermaid/index.css", "src/templates/assets/javascripts/components/content/mermaid/index.ts", "src/templates/assets/javascripts/components/content/table/index.ts", "src/templates/assets/javascripts/components/content/tabs/index.ts", "src/templates/assets/javascripts/components/content/_/index.ts", "src/templates/assets/javascripts/components/dialog/index.ts", "src/templates/assets/javascripts/components/tooltip/index.ts", "src/templates/assets/javascripts/components/header/_/index.ts", "src/templates/assets/javascripts/components/header/title/index.ts", "src/templates/assets/javascripts/components/main/index.ts", "src/templates/assets/javascripts/components/palette/index.ts", "src/templates/assets/javascripts/components/progress/index.ts", "src/templates/assets/javascripts/integrations/clipboard/index.ts", "src/templates/assets/javascripts/integrations/sitemap/index.ts", "src/templates/assets/javascripts/integrations/instant/index.ts", "src/templates/assets/javascripts/integrations/search/highlighter/index.ts", "src/templates/assets/javascripts/integrations/search/worker/message/index.ts", "src/templates/assets/javascripts/integrations/search/worker/_/index.ts", "src/templates/assets/javascripts/integrations/version/index.ts", "src/templates/assets/javascripts/components/search/query/index.ts", "src/templates/assets/javascripts/components/search/result/index.ts", "src/templates/assets/javascripts/components/search/share/index.ts", "src/templates/assets/javascripts/components/search/suggest/index.ts", "src/templates/assets/javascripts/components/search/_/index.ts", "src/templates/assets/javascripts/components/search/highlight/index.ts", "src/templates/assets/javascripts/components/sidebar/index.ts", "src/templates/assets/javascripts/components/source/facts/github/index.ts", "src/templates/assets/javascripts/components/source/facts/gitlab/index.ts", "src/templates/assets/javascripts/components/source/facts/_/index.ts", "src/templates/assets/javascripts/components/source/_/index.ts", "src/templates/assets/javascripts/components/tabs/index.ts", "src/templates/assets/javascripts/components/toc/index.ts", "src/templates/assets/javascripts/components/top/index.ts", "src/templates/assets/javascripts/patches/ellipsis/index.ts", "src/templates/assets/javascripts/patches/indeterminate/index.ts", "src/templates/assets/javascripts/patches/scrollfix/index.ts", "src/templates/assets/javascripts/patches/scrolllock/index.ts", "src/templates/assets/javascripts/polyfills/index.ts"], + "sourcesContent": ["(function (global, factory) {\n typeof exports === 'object' && typeof module !== 'undefined' ? factory() :\n typeof define === 'function' && define.amd ? define(factory) :\n (factory());\n}(this, (function () { 'use strict';\n\n /**\n * Applies the :focus-visible polyfill at the given scope.\n * A scope in this case is either the top-level Document or a Shadow Root.\n *\n * @param {(Document|ShadowRoot)} scope\n * @see https://github.com/WICG/focus-visible\n */\n function applyFocusVisiblePolyfill(scope) {\n var hadKeyboardEvent = true;\n var hadFocusVisibleRecently = false;\n var hadFocusVisibleRecentlyTimeout = null;\n\n var inputTypesAllowlist = {\n text: true,\n search: true,\n url: true,\n tel: true,\n email: true,\n password: true,\n number: true,\n date: true,\n month: true,\n week: true,\n time: true,\n datetime: true,\n 'datetime-local': true\n };\n\n /**\n * Helper function for legacy browsers and iframes which sometimes focus\n * elements like document, body, and non-interactive SVG.\n * @param {Element} el\n */\n function isValidFocusTarget(el) {\n if (\n el &&\n el !== document &&\n el.nodeName !== 'HTML' &&\n el.nodeName !== 'BODY' &&\n 'classList' in el &&\n 'contains' in el.classList\n ) {\n return true;\n }\n return false;\n }\n\n /**\n * Computes whether the given element should automatically trigger the\n * `focus-visible` class being added, i.e. whether it should always match\n * `:focus-visible` when focused.\n * @param {Element} el\n * @return {boolean}\n */\n function focusTriggersKeyboardModality(el) {\n var type = el.type;\n var tagName = el.tagName;\n\n if (tagName === 'INPUT' && inputTypesAllowlist[type] && !el.readOnly) {\n return true;\n }\n\n if (tagName === 'TEXTAREA' && !el.readOnly) {\n return true;\n }\n\n if (el.isContentEditable) {\n return true;\n }\n\n return false;\n }\n\n /**\n * Add the `focus-visible` class to the given element if it was not added by\n * the author.\n * @param {Element} el\n */\n function addFocusVisibleClass(el) {\n if (el.classList.contains('focus-visible')) {\n return;\n }\n el.classList.add('focus-visible');\n el.setAttribute('data-focus-visible-added', '');\n }\n\n /**\n * Remove the `focus-visible` class from the given element if it was not\n * originally added by the author.\n * @param {Element} el\n */\n function removeFocusVisibleClass(el) {\n if (!el.hasAttribute('data-focus-visible-added')) {\n return;\n }\n el.classList.remove('focus-visible');\n el.removeAttribute('data-focus-visible-added');\n }\n\n /**\n * If the most recent user interaction was via the keyboard;\n * and the key press did not include a meta, alt/option, or control key;\n * then the modality is keyboard. Otherwise, the modality is not keyboard.\n * Apply `focus-visible` to any current active element and keep track\n * of our keyboard modality state with `hadKeyboardEvent`.\n * @param {KeyboardEvent} e\n */\n function onKeyDown(e) {\n if (e.metaKey || e.altKey || e.ctrlKey) {\n return;\n }\n\n if (isValidFocusTarget(scope.activeElement)) {\n addFocusVisibleClass(scope.activeElement);\n }\n\n hadKeyboardEvent = true;\n }\n\n /**\n * If at any point a user clicks with a pointing device, ensure that we change\n * the modality away from keyboard.\n * This avoids the situation where a user presses a key on an already focused\n * element, and then clicks on a different element, focusing it with a\n * pointing device, while we still think we're in keyboard modality.\n * @param {Event} e\n */\n function onPointerDown(e) {\n hadKeyboardEvent = false;\n }\n\n /**\n * On `focus`, add the `focus-visible` class to the target if:\n * - the target received focus as a result of keyboard navigation, or\n * - the event target is an element that will likely require interaction\n * via the keyboard (e.g. a text box)\n * @param {Event} e\n */\n function onFocus(e) {\n // Prevent IE from focusing the document or HTML element.\n if (!isValidFocusTarget(e.target)) {\n return;\n }\n\n if (hadKeyboardEvent || focusTriggersKeyboardModality(e.target)) {\n addFocusVisibleClass(e.target);\n }\n }\n\n /**\n * On `blur`, remove the `focus-visible` class from the target.\n * @param {Event} e\n */\n function onBlur(e) {\n if (!isValidFocusTarget(e.target)) {\n return;\n }\n\n if (\n e.target.classList.contains('focus-visible') ||\n e.target.hasAttribute('data-focus-visible-added')\n ) {\n // To detect a tab/window switch, we look for a blur event followed\n // rapidly by a visibility change.\n // If we don't see a visibility change within 100ms, it's probably a\n // regular focus change.\n hadFocusVisibleRecently = true;\n window.clearTimeout(hadFocusVisibleRecentlyTimeout);\n hadFocusVisibleRecentlyTimeout = window.setTimeout(function() {\n hadFocusVisibleRecently = false;\n }, 100);\n removeFocusVisibleClass(e.target);\n }\n }\n\n /**\n * If the user changes tabs, keep track of whether or not the previously\n * focused element had .focus-visible.\n * @param {Event} e\n */\n function onVisibilityChange(e) {\n if (document.visibilityState === 'hidden') {\n // If the tab becomes active again, the browser will handle calling focus\n // on the element (Safari actually calls it twice).\n // If this tab change caused a blur on an element with focus-visible,\n // re-apply the class when the user switches back to the tab.\n if (hadFocusVisibleRecently) {\n hadKeyboardEvent = true;\n }\n addInitialPointerMoveListeners();\n }\n }\n\n /**\n * Add a group of listeners to detect usage of any pointing devices.\n * These listeners will be added when the polyfill first loads, and anytime\n * the window is blurred, so that they are active when the window regains\n * focus.\n */\n function addInitialPointerMoveListeners() {\n document.addEventListener('mousemove', onInitialPointerMove);\n document.addEventListener('mousedown', onInitialPointerMove);\n document.addEventListener('mouseup', onInitialPointerMove);\n document.addEventListener('pointermove', onInitialPointerMove);\n document.addEventListener('pointerdown', onInitialPointerMove);\n document.addEventListener('pointerup', onInitialPointerMove);\n document.addEventListener('touchmove', onInitialPointerMove);\n document.addEventListener('touchstart', onInitialPointerMove);\n document.addEventListener('touchend', onInitialPointerMove);\n }\n\n function removeInitialPointerMoveListeners() {\n document.removeEventListener('mousemove', onInitialPointerMove);\n document.removeEventListener('mousedown', onInitialPointerMove);\n document.removeEventListener('mouseup', onInitialPointerMove);\n document.removeEventListener('pointermove', onInitialPointerMove);\n document.removeEventListener('pointerdown', onInitialPointerMove);\n document.removeEventListener('pointerup', onInitialPointerMove);\n document.removeEventListener('touchmove', onInitialPointerMove);\n document.removeEventListener('touchstart', onInitialPointerMove);\n document.removeEventListener('touchend', onInitialPointerMove);\n }\n\n /**\n * When the polfyill first loads, assume the user is in keyboard modality.\n * If any event is received from a pointing device (e.g. mouse, pointer,\n * touch), turn off keyboard modality.\n * This accounts for situations where focus enters the page from the URL bar.\n * @param {Event} e\n */\n function onInitialPointerMove(e) {\n // Work around a Safari quirk that fires a mousemove on whenever the\n // window blurs, even if you're tabbing out of the page. \u00AF\\_(\u30C4)_/\u00AF\n if (e.target.nodeName && e.target.nodeName.toLowerCase() === 'html') {\n return;\n }\n\n hadKeyboardEvent = false;\n removeInitialPointerMoveListeners();\n }\n\n // For some kinds of state, we are interested in changes at the global scope\n // only. For example, global pointer input, global key presses and global\n // visibility change should affect the state at every scope:\n document.addEventListener('keydown', onKeyDown, true);\n document.addEventListener('mousedown', onPointerDown, true);\n document.addEventListener('pointerdown', onPointerDown, true);\n document.addEventListener('touchstart', onPointerDown, true);\n document.addEventListener('visibilitychange', onVisibilityChange, true);\n\n addInitialPointerMoveListeners();\n\n // For focus and blur, we specifically care about state changes in the local\n // scope. This is because focus / blur events that originate from within a\n // shadow root are not re-dispatched from the host element if it was already\n // the active element in its own scope:\n scope.addEventListener('focus', onFocus, true);\n scope.addEventListener('blur', onBlur, true);\n\n // We detect that a node is a ShadowRoot by ensuring that it is a\n // DocumentFragment and also has a host property. This check covers native\n // implementation and polyfill implementation transparently. If we only cared\n // about the native implementation, we could just check if the scope was\n // an instance of a ShadowRoot.\n if (scope.nodeType === Node.DOCUMENT_FRAGMENT_NODE && scope.host) {\n // Since a ShadowRoot is a special kind of DocumentFragment, it does not\n // have a root element to add a class to. So, we add this attribute to the\n // host element instead:\n scope.host.setAttribute('data-js-focus-visible', '');\n } else if (scope.nodeType === Node.DOCUMENT_NODE) {\n document.documentElement.classList.add('js-focus-visible');\n document.documentElement.setAttribute('data-js-focus-visible', '');\n }\n }\n\n // It is important to wrap all references to global window and document in\n // these checks to support server-side rendering use cases\n // @see https://github.com/WICG/focus-visible/issues/199\n if (typeof window !== 'undefined' && typeof document !== 'undefined') {\n // Make the polyfill helper globally available. This can be used as a signal\n // to interested libraries that wish to coordinate with the polyfill for e.g.,\n // applying the polyfill to a shadow root:\n window.applyFocusVisiblePolyfill = applyFocusVisiblePolyfill;\n\n // Notify interested libraries of the polyfill's presence, in case the\n // polyfill was loaded lazily:\n var event;\n\n try {\n event = new CustomEvent('focus-visible-polyfill-ready');\n } catch (error) {\n // IE11 does not support using CustomEvent as a constructor directly:\n event = document.createEvent('CustomEvent');\n event.initCustomEvent('focus-visible-polyfill-ready', false, false, {});\n }\n\n window.dispatchEvent(event);\n }\n\n if (typeof document !== 'undefined') {\n // Apply the polyfill to the global document, so that no JavaScript\n // coordination is required to use the polyfill in the top-level document:\n applyFocusVisiblePolyfill(document);\n }\n\n})));\n", "/*!\n * clipboard.js v2.0.11\n * https://clipboardjs.com/\n *\n * Licensed MIT \u00A9 Zeno Rocha\n */\n(function webpackUniversalModuleDefinition(root, factory) {\n\tif(typeof exports === 'object' && typeof module === 'object')\n\t\tmodule.exports = factory();\n\telse if(typeof define === 'function' && define.amd)\n\t\tdefine([], factory);\n\telse if(typeof exports === 'object')\n\t\texports[\"ClipboardJS\"] = factory();\n\telse\n\t\troot[\"ClipboardJS\"] = factory();\n})(this, function() {\nreturn /******/ (function() { // webpackBootstrap\n/******/ \tvar __webpack_modules__ = ({\n\n/***/ 686:\n/***/ (function(__unused_webpack_module, __webpack_exports__, __webpack_require__) {\n\n\"use strict\";\n\n// EXPORTS\n__webpack_require__.d(__webpack_exports__, {\n \"default\": function() { return /* binding */ clipboard; }\n});\n\n// EXTERNAL MODULE: ./node_modules/tiny-emitter/index.js\nvar tiny_emitter = __webpack_require__(279);\nvar tiny_emitter_default = /*#__PURE__*/__webpack_require__.n(tiny_emitter);\n// EXTERNAL MODULE: ./node_modules/good-listener/src/listen.js\nvar listen = __webpack_require__(370);\nvar listen_default = /*#__PURE__*/__webpack_require__.n(listen);\n// EXTERNAL MODULE: ./node_modules/select/src/select.js\nvar src_select = __webpack_require__(817);\nvar select_default = /*#__PURE__*/__webpack_require__.n(src_select);\n;// CONCATENATED MODULE: ./src/common/command.js\n/**\n * Executes a given operation type.\n * @param {String} type\n * @return {Boolean}\n */\nfunction command(type) {\n try {\n return document.execCommand(type);\n } catch (err) {\n return false;\n }\n}\n;// CONCATENATED MODULE: ./src/actions/cut.js\n\n\n/**\n * Cut action wrapper.\n * @param {String|HTMLElement} target\n * @return {String}\n */\n\nvar ClipboardActionCut = function ClipboardActionCut(target) {\n var selectedText = select_default()(target);\n command('cut');\n return selectedText;\n};\n\n/* harmony default export */ var actions_cut = (ClipboardActionCut);\n;// CONCATENATED MODULE: ./src/common/create-fake-element.js\n/**\n * Creates a fake textarea element with a value.\n * @param {String} value\n * @return {HTMLElement}\n */\nfunction createFakeElement(value) {\n var isRTL = document.documentElement.getAttribute('dir') === 'rtl';\n var fakeElement = document.createElement('textarea'); // Prevent zooming on iOS\n\n fakeElement.style.fontSize = '12pt'; // Reset box model\n\n fakeElement.style.border = '0';\n fakeElement.style.padding = '0';\n fakeElement.style.margin = '0'; // Move element out of screen horizontally\n\n fakeElement.style.position = 'absolute';\n fakeElement.style[isRTL ? 'right' : 'left'] = '-9999px'; // Move element to the same position vertically\n\n var yPosition = window.pageYOffset || document.documentElement.scrollTop;\n fakeElement.style.top = \"\".concat(yPosition, \"px\");\n fakeElement.setAttribute('readonly', '');\n fakeElement.value = value;\n return fakeElement;\n}\n;// CONCATENATED MODULE: ./src/actions/copy.js\n\n\n\n/**\n * Create fake copy action wrapper using a fake element.\n * @param {String} target\n * @param {Object} options\n * @return {String}\n */\n\nvar fakeCopyAction = function fakeCopyAction(value, options) {\n var fakeElement = createFakeElement(value);\n options.container.appendChild(fakeElement);\n var selectedText = select_default()(fakeElement);\n command('copy');\n fakeElement.remove();\n return selectedText;\n};\n/**\n * Copy action wrapper.\n * @param {String|HTMLElement} target\n * @param {Object} options\n * @return {String}\n */\n\n\nvar ClipboardActionCopy = function ClipboardActionCopy(target) {\n var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {\n container: document.body\n };\n var selectedText = '';\n\n if (typeof target === 'string') {\n selectedText = fakeCopyAction(target, options);\n } else if (target instanceof HTMLInputElement && !['text', 'search', 'url', 'tel', 'password'].includes(target === null || target === void 0 ? void 0 : target.type)) {\n // If input type doesn't support `setSelectionRange`. Simulate it. https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setSelectionRange\n selectedText = fakeCopyAction(target.value, options);\n } else {\n selectedText = select_default()(target);\n command('copy');\n }\n\n return selectedText;\n};\n\n/* harmony default export */ var actions_copy = (ClipboardActionCopy);\n;// CONCATENATED MODULE: ./src/actions/default.js\nfunction _typeof(obj) { \"@babel/helpers - typeof\"; if (typeof Symbol === \"function\" && typeof Symbol.iterator === \"symbol\") { _typeof = function _typeof(obj) { return typeof obj; }; } else { _typeof = function _typeof(obj) { return obj && typeof Symbol === \"function\" && obj.constructor === Symbol && obj !== Symbol.prototype ? \"symbol\" : typeof obj; }; } return _typeof(obj); }\n\n\n\n/**\n * Inner function which performs selection from either `text` or `target`\n * properties and then executes copy or cut operations.\n * @param {Object} options\n */\n\nvar ClipboardActionDefault = function ClipboardActionDefault() {\n var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};\n // Defines base properties passed from constructor.\n var _options$action = options.action,\n action = _options$action === void 0 ? 'copy' : _options$action,\n container = options.container,\n target = options.target,\n text = options.text; // Sets the `action` to be performed which can be either 'copy' or 'cut'.\n\n if (action !== 'copy' && action !== 'cut') {\n throw new Error('Invalid \"action\" value, use either \"copy\" or \"cut\"');\n } // Sets the `target` property using an element that will be have its content copied.\n\n\n if (target !== undefined) {\n if (target && _typeof(target) === 'object' && target.nodeType === 1) {\n if (action === 'copy' && target.hasAttribute('disabled')) {\n throw new Error('Invalid \"target\" attribute. Please use \"readonly\" instead of \"disabled\" attribute');\n }\n\n if (action === 'cut' && (target.hasAttribute('readonly') || target.hasAttribute('disabled'))) {\n throw new Error('Invalid \"target\" attribute. You can\\'t cut text from elements with \"readonly\" or \"disabled\" attributes');\n }\n } else {\n throw new Error('Invalid \"target\" value, use a valid Element');\n }\n } // Define selection strategy based on `text` property.\n\n\n if (text) {\n return actions_copy(text, {\n container: container\n });\n } // Defines which selection strategy based on `target` property.\n\n\n if (target) {\n return action === 'cut' ? actions_cut(target) : actions_copy(target, {\n container: container\n });\n }\n};\n\n/* harmony default export */ var actions_default = (ClipboardActionDefault);\n;// CONCATENATED MODULE: ./src/clipboard.js\nfunction clipboard_typeof(obj) { \"@babel/helpers - typeof\"; if (typeof Symbol === \"function\" && typeof Symbol.iterator === \"symbol\") { clipboard_typeof = function _typeof(obj) { return typeof obj; }; } else { clipboard_typeof = function _typeof(obj) { return obj && typeof Symbol === \"function\" && obj.constructor === Symbol && obj !== Symbol.prototype ? \"symbol\" : typeof obj; }; } return clipboard_typeof(obj); }\n\nfunction _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError(\"Cannot call a class as a function\"); } }\n\nfunction _defineProperties(target, props) { for (var i = 0; i < props.length; i++) { var descriptor = props[i]; descriptor.enumerable = descriptor.enumerable || false; descriptor.configurable = true; if (\"value\" in descriptor) descriptor.writable = true; Object.defineProperty(target, descriptor.key, descriptor); } }\n\nfunction _createClass(Constructor, protoProps, staticProps) { if (protoProps) _defineProperties(Constructor.prototype, protoProps); if (staticProps) _defineProperties(Constructor, staticProps); return Constructor; }\n\nfunction _inherits(subClass, superClass) { if (typeof superClass !== \"function\" && superClass !== null) { throw new TypeError(\"Super expression must either be null or a function\"); } subClass.prototype = Object.create(superClass && superClass.prototype, { constructor: { value: subClass, writable: true, configurable: true } }); if (superClass) _setPrototypeOf(subClass, superClass); }\n\nfunction _setPrototypeOf(o, p) { _setPrototypeOf = Object.setPrototypeOf || function _setPrototypeOf(o, p) { o.__proto__ = p; return o; }; return _setPrototypeOf(o, p); }\n\nfunction _createSuper(Derived) { var hasNativeReflectConstruct = _isNativeReflectConstruct(); return function _createSuperInternal() { var Super = _getPrototypeOf(Derived), result; if (hasNativeReflectConstruct) { var NewTarget = _getPrototypeOf(this).constructor; result = Reflect.construct(Super, arguments, NewTarget); } else { result = Super.apply(this, arguments); } return _possibleConstructorReturn(this, result); }; }\n\nfunction _possibleConstructorReturn(self, call) { if (call && (clipboard_typeof(call) === \"object\" || typeof call === \"function\")) { return call; } return _assertThisInitialized(self); }\n\nfunction _assertThisInitialized(self) { if (self === void 0) { throw new ReferenceError(\"this hasn't been initialised - super() hasn't been called\"); } return self; }\n\nfunction _isNativeReflectConstruct() { if (typeof Reflect === \"undefined\" || !Reflect.construct) return false; if (Reflect.construct.sham) return false; if (typeof Proxy === \"function\") return true; try { Date.prototype.toString.call(Reflect.construct(Date, [], function () {})); return true; } catch (e) { return false; } }\n\nfunction _getPrototypeOf(o) { _getPrototypeOf = Object.setPrototypeOf ? Object.getPrototypeOf : function _getPrototypeOf(o) { return o.__proto__ || Object.getPrototypeOf(o); }; return _getPrototypeOf(o); }\n\n\n\n\n\n\n/**\n * Helper function to retrieve attribute value.\n * @param {String} suffix\n * @param {Element} element\n */\n\nfunction getAttributeValue(suffix, element) {\n var attribute = \"data-clipboard-\".concat(suffix);\n\n if (!element.hasAttribute(attribute)) {\n return;\n }\n\n return element.getAttribute(attribute);\n}\n/**\n * Base class which takes one or more elements, adds event listeners to them,\n * and instantiates a new `ClipboardAction` on each click.\n */\n\n\nvar Clipboard = /*#__PURE__*/function (_Emitter) {\n _inherits(Clipboard, _Emitter);\n\n var _super = _createSuper(Clipboard);\n\n /**\n * @param {String|HTMLElement|HTMLCollection|NodeList} trigger\n * @param {Object} options\n */\n function Clipboard(trigger, options) {\n var _this;\n\n _classCallCheck(this, Clipboard);\n\n _this = _super.call(this);\n\n _this.resolveOptions(options);\n\n _this.listenClick(trigger);\n\n return _this;\n }\n /**\n * Defines if attributes would be resolved using internal setter functions\n * or custom functions that were passed in the constructor.\n * @param {Object} options\n */\n\n\n _createClass(Clipboard, [{\n key: \"resolveOptions\",\n value: function resolveOptions() {\n var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};\n this.action = typeof options.action === 'function' ? options.action : this.defaultAction;\n this.target = typeof options.target === 'function' ? options.target : this.defaultTarget;\n this.text = typeof options.text === 'function' ? options.text : this.defaultText;\n this.container = clipboard_typeof(options.container) === 'object' ? options.container : document.body;\n }\n /**\n * Adds a click event listener to the passed trigger.\n * @param {String|HTMLElement|HTMLCollection|NodeList} trigger\n */\n\n }, {\n key: \"listenClick\",\n value: function listenClick(trigger) {\n var _this2 = this;\n\n this.listener = listen_default()(trigger, 'click', function (e) {\n return _this2.onClick(e);\n });\n }\n /**\n * Defines a new `ClipboardAction` on each click event.\n * @param {Event} e\n */\n\n }, {\n key: \"onClick\",\n value: function onClick(e) {\n var trigger = e.delegateTarget || e.currentTarget;\n var action = this.action(trigger) || 'copy';\n var text = actions_default({\n action: action,\n container: this.container,\n target: this.target(trigger),\n text: this.text(trigger)\n }); // Fires an event based on the copy operation result.\n\n this.emit(text ? 'success' : 'error', {\n action: action,\n text: text,\n trigger: trigger,\n clearSelection: function clearSelection() {\n if (trigger) {\n trigger.focus();\n }\n\n window.getSelection().removeAllRanges();\n }\n });\n }\n /**\n * Default `action` lookup function.\n * @param {Element} trigger\n */\n\n }, {\n key: \"defaultAction\",\n value: function defaultAction(trigger) {\n return getAttributeValue('action', trigger);\n }\n /**\n * Default `target` lookup function.\n * @param {Element} trigger\n */\n\n }, {\n key: \"defaultTarget\",\n value: function defaultTarget(trigger) {\n var selector = getAttributeValue('target', trigger);\n\n if (selector) {\n return document.querySelector(selector);\n }\n }\n /**\n * Allow fire programmatically a copy action\n * @param {String|HTMLElement} target\n * @param {Object} options\n * @returns Text copied.\n */\n\n }, {\n key: \"defaultText\",\n\n /**\n * Default `text` lookup function.\n * @param {Element} trigger\n */\n value: function defaultText(trigger) {\n return getAttributeValue('text', trigger);\n }\n /**\n * Destroy lifecycle.\n */\n\n }, {\n key: \"destroy\",\n value: function destroy() {\n this.listener.destroy();\n }\n }], [{\n key: \"copy\",\n value: function copy(target) {\n var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {\n container: document.body\n };\n return actions_copy(target, options);\n }\n /**\n * Allow fire programmatically a cut action\n * @param {String|HTMLElement} target\n * @returns Text cutted.\n */\n\n }, {\n key: \"cut\",\n value: function cut(target) {\n return actions_cut(target);\n }\n /**\n * Returns the support of the given action, or all actions if no action is\n * given.\n * @param {String} [action]\n */\n\n }, {\n key: \"isSupported\",\n value: function isSupported() {\n var action = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : ['copy', 'cut'];\n var actions = typeof action === 'string' ? [action] : action;\n var support = !!document.queryCommandSupported;\n actions.forEach(function (action) {\n support = support && !!document.queryCommandSupported(action);\n });\n return support;\n }\n }]);\n\n return Clipboard;\n}((tiny_emitter_default()));\n\n/* harmony default export */ var clipboard = (Clipboard);\n\n/***/ }),\n\n/***/ 828:\n/***/ (function(module) {\n\nvar DOCUMENT_NODE_TYPE = 9;\n\n/**\n * A polyfill for Element.matches()\n */\nif (typeof Element !== 'undefined' && !Element.prototype.matches) {\n var proto = Element.prototype;\n\n proto.matches = proto.matchesSelector ||\n proto.mozMatchesSelector ||\n proto.msMatchesSelector ||\n proto.oMatchesSelector ||\n proto.webkitMatchesSelector;\n}\n\n/**\n * Finds the closest parent that matches a selector.\n *\n * @param {Element} element\n * @param {String} selector\n * @return {Function}\n */\nfunction closest (element, selector) {\n while (element && element.nodeType !== DOCUMENT_NODE_TYPE) {\n if (typeof element.matches === 'function' &&\n element.matches(selector)) {\n return element;\n }\n element = element.parentNode;\n }\n}\n\nmodule.exports = closest;\n\n\n/***/ }),\n\n/***/ 438:\n/***/ (function(module, __unused_webpack_exports, __webpack_require__) {\n\nvar closest = __webpack_require__(828);\n\n/**\n * Delegates event to a selector.\n *\n * @param {Element} element\n * @param {String} selector\n * @param {String} type\n * @param {Function} callback\n * @param {Boolean} useCapture\n * @return {Object}\n */\nfunction _delegate(element, selector, type, callback, useCapture) {\n var listenerFn = listener.apply(this, arguments);\n\n element.addEventListener(type, listenerFn, useCapture);\n\n return {\n destroy: function() {\n element.removeEventListener(type, listenerFn, useCapture);\n }\n }\n}\n\n/**\n * Delegates event to a selector.\n *\n * @param {Element|String|Array} [elements]\n * @param {String} selector\n * @param {String} type\n * @param {Function} callback\n * @param {Boolean} useCapture\n * @return {Object}\n */\nfunction delegate(elements, selector, type, callback, useCapture) {\n // Handle the regular Element usage\n if (typeof elements.addEventListener === 'function') {\n return _delegate.apply(null, arguments);\n }\n\n // Handle Element-less usage, it defaults to global delegation\n if (typeof type === 'function') {\n // Use `document` as the first parameter, then apply arguments\n // This is a short way to .unshift `arguments` without running into deoptimizations\n return _delegate.bind(null, document).apply(null, arguments);\n }\n\n // Handle Selector-based usage\n if (typeof elements === 'string') {\n elements = document.querySelectorAll(elements);\n }\n\n // Handle Array-like based usage\n return Array.prototype.map.call(elements, function (element) {\n return _delegate(element, selector, type, callback, useCapture);\n });\n}\n\n/**\n * Finds closest match and invokes callback.\n *\n * @param {Element} element\n * @param {String} selector\n * @param {String} type\n * @param {Function} callback\n * @return {Function}\n */\nfunction listener(element, selector, type, callback) {\n return function(e) {\n e.delegateTarget = closest(e.target, selector);\n\n if (e.delegateTarget) {\n callback.call(element, e);\n }\n }\n}\n\nmodule.exports = delegate;\n\n\n/***/ }),\n\n/***/ 879:\n/***/ (function(__unused_webpack_module, exports) {\n\n/**\n * Check if argument is a HTML element.\n *\n * @param {Object} value\n * @return {Boolean}\n */\nexports.node = function(value) {\n return value !== undefined\n && value instanceof HTMLElement\n && value.nodeType === 1;\n};\n\n/**\n * Check if argument is a list of HTML elements.\n *\n * @param {Object} value\n * @return {Boolean}\n */\nexports.nodeList = function(value) {\n var type = Object.prototype.toString.call(value);\n\n return value !== undefined\n && (type === '[object NodeList]' || type === '[object HTMLCollection]')\n && ('length' in value)\n && (value.length === 0 || exports.node(value[0]));\n};\n\n/**\n * Check if argument is a string.\n *\n * @param {Object} value\n * @return {Boolean}\n */\nexports.string = function(value) {\n return typeof value === 'string'\n || value instanceof String;\n};\n\n/**\n * Check if argument is a function.\n *\n * @param {Object} value\n * @return {Boolean}\n */\nexports.fn = function(value) {\n var type = Object.prototype.toString.call(value);\n\n return type === '[object Function]';\n};\n\n\n/***/ }),\n\n/***/ 370:\n/***/ (function(module, __unused_webpack_exports, __webpack_require__) {\n\nvar is = __webpack_require__(879);\nvar delegate = __webpack_require__(438);\n\n/**\n * Validates all params and calls the right\n * listener function based on its target type.\n *\n * @param {String|HTMLElement|HTMLCollection|NodeList} target\n * @param {String} type\n * @param {Function} callback\n * @return {Object}\n */\nfunction listen(target, type, callback) {\n if (!target && !type && !callback) {\n throw new Error('Missing required arguments');\n }\n\n if (!is.string(type)) {\n throw new TypeError('Second argument must be a String');\n }\n\n if (!is.fn(callback)) {\n throw new TypeError('Third argument must be a Function');\n }\n\n if (is.node(target)) {\n return listenNode(target, type, callback);\n }\n else if (is.nodeList(target)) {\n return listenNodeList(target, type, callback);\n }\n else if (is.string(target)) {\n return listenSelector(target, type, callback);\n }\n else {\n throw new TypeError('First argument must be a String, HTMLElement, HTMLCollection, or NodeList');\n }\n}\n\n/**\n * Adds an event listener to a HTML element\n * and returns a remove listener function.\n *\n * @param {HTMLElement} node\n * @param {String} type\n * @param {Function} callback\n * @return {Object}\n */\nfunction listenNode(node, type, callback) {\n node.addEventListener(type, callback);\n\n return {\n destroy: function() {\n node.removeEventListener(type, callback);\n }\n }\n}\n\n/**\n * Add an event listener to a list of HTML elements\n * and returns a remove listener function.\n *\n * @param {NodeList|HTMLCollection} nodeList\n * @param {String} type\n * @param {Function} callback\n * @return {Object}\n */\nfunction listenNodeList(nodeList, type, callback) {\n Array.prototype.forEach.call(nodeList, function(node) {\n node.addEventListener(type, callback);\n });\n\n return {\n destroy: function() {\n Array.prototype.forEach.call(nodeList, function(node) {\n node.removeEventListener(type, callback);\n });\n }\n }\n}\n\n/**\n * Add an event listener to a selector\n * and returns a remove listener function.\n *\n * @param {String} selector\n * @param {String} type\n * @param {Function} callback\n * @return {Object}\n */\nfunction listenSelector(selector, type, callback) {\n return delegate(document.body, selector, type, callback);\n}\n\nmodule.exports = listen;\n\n\n/***/ }),\n\n/***/ 817:\n/***/ (function(module) {\n\nfunction select(element) {\n var selectedText;\n\n if (element.nodeName === 'SELECT') {\n element.focus();\n\n selectedText = element.value;\n }\n else if (element.nodeName === 'INPUT' || element.nodeName === 'TEXTAREA') {\n var isReadOnly = element.hasAttribute('readonly');\n\n if (!isReadOnly) {\n element.setAttribute('readonly', '');\n }\n\n element.select();\n element.setSelectionRange(0, element.value.length);\n\n if (!isReadOnly) {\n element.removeAttribute('readonly');\n }\n\n selectedText = element.value;\n }\n else {\n if (element.hasAttribute('contenteditable')) {\n element.focus();\n }\n\n var selection = window.getSelection();\n var range = document.createRange();\n\n range.selectNodeContents(element);\n selection.removeAllRanges();\n selection.addRange(range);\n\n selectedText = selection.toString();\n }\n\n return selectedText;\n}\n\nmodule.exports = select;\n\n\n/***/ }),\n\n/***/ 279:\n/***/ (function(module) {\n\nfunction E () {\n // Keep this empty so it's easier to inherit from\n // (via https://github.com/lipsmack from https://github.com/scottcorgan/tiny-emitter/issues/3)\n}\n\nE.prototype = {\n on: function (name, callback, ctx) {\n var e = this.e || (this.e = {});\n\n (e[name] || (e[name] = [])).push({\n fn: callback,\n ctx: ctx\n });\n\n return this;\n },\n\n once: function (name, callback, ctx) {\n var self = this;\n function listener () {\n self.off(name, listener);\n callback.apply(ctx, arguments);\n };\n\n listener._ = callback\n return this.on(name, listener, ctx);\n },\n\n emit: function (name) {\n var data = [].slice.call(arguments, 1);\n var evtArr = ((this.e || (this.e = {}))[name] || []).slice();\n var i = 0;\n var len = evtArr.length;\n\n for (i; i < len; i++) {\n evtArr[i].fn.apply(evtArr[i].ctx, data);\n }\n\n return this;\n },\n\n off: function (name, callback) {\n var e = this.e || (this.e = {});\n var evts = e[name];\n var liveEvents = [];\n\n if (evts && callback) {\n for (var i = 0, len = evts.length; i < len; i++) {\n if (evts[i].fn !== callback && evts[i].fn._ !== callback)\n liveEvents.push(evts[i]);\n }\n }\n\n // Remove event from queue to prevent memory leak\n // Suggested by https://github.com/lazd\n // Ref: https://github.com/scottcorgan/tiny-emitter/commit/c6ebfaa9bc973b33d110a84a307742b7cf94c953#commitcomment-5024910\n\n (liveEvents.length)\n ? e[name] = liveEvents\n : delete e[name];\n\n return this;\n }\n};\n\nmodule.exports = E;\nmodule.exports.TinyEmitter = E;\n\n\n/***/ })\n\n/******/ \t});\n/************************************************************************/\n/******/ \t// The module cache\n/******/ \tvar __webpack_module_cache__ = {};\n/******/ \t\n/******/ \t// The require function\n/******/ \tfunction __webpack_require__(moduleId) {\n/******/ \t\t// Check if module is in cache\n/******/ \t\tif(__webpack_module_cache__[moduleId]) {\n/******/ \t\t\treturn __webpack_module_cache__[moduleId].exports;\n/******/ \t\t}\n/******/ \t\t// Create a new module (and put it into the cache)\n/******/ \t\tvar module = __webpack_module_cache__[moduleId] = {\n/******/ \t\t\t// no module.id needed\n/******/ \t\t\t// no module.loaded needed\n/******/ \t\t\texports: {}\n/******/ \t\t};\n/******/ \t\n/******/ \t\t// Execute the module function\n/******/ \t\t__webpack_modules__[moduleId](module, module.exports, __webpack_require__);\n/******/ \t\n/******/ \t\t// Return the exports of the module\n/******/ \t\treturn module.exports;\n/******/ \t}\n/******/ \t\n/************************************************************************/\n/******/ \t/* webpack/runtime/compat get default export */\n/******/ \t!function() {\n/******/ \t\t// getDefaultExport function for compatibility with non-harmony modules\n/******/ \t\t__webpack_require__.n = function(module) {\n/******/ \t\t\tvar getter = module && module.__esModule ?\n/******/ \t\t\t\tfunction() { return module['default']; } :\n/******/ \t\t\t\tfunction() { return module; };\n/******/ \t\t\t__webpack_require__.d(getter, { a: getter });\n/******/ \t\t\treturn getter;\n/******/ \t\t};\n/******/ \t}();\n/******/ \t\n/******/ \t/* webpack/runtime/define property getters */\n/******/ \t!function() {\n/******/ \t\t// define getter functions for harmony exports\n/******/ \t\t__webpack_require__.d = function(exports, definition) {\n/******/ \t\t\tfor(var key in definition) {\n/******/ \t\t\t\tif(__webpack_require__.o(definition, key) && !__webpack_require__.o(exports, key)) {\n/******/ \t\t\t\t\tObject.defineProperty(exports, key, { enumerable: true, get: definition[key] });\n/******/ \t\t\t\t}\n/******/ \t\t\t}\n/******/ \t\t};\n/******/ \t}();\n/******/ \t\n/******/ \t/* webpack/runtime/hasOwnProperty shorthand */\n/******/ \t!function() {\n/******/ \t\t__webpack_require__.o = function(obj, prop) { return Object.prototype.hasOwnProperty.call(obj, prop); }\n/******/ \t}();\n/******/ \t\n/************************************************************************/\n/******/ \t// module exports must be returned from runtime so entry inlining is disabled\n/******/ \t// startup\n/******/ \t// Load entry module and return exports\n/******/ \treturn __webpack_require__(686);\n/******/ })()\n.default;\n});", "/*!\n * escape-html\n * Copyright(c) 2012-2013 TJ Holowaychuk\n * Copyright(c) 2015 Andreas Lubbe\n * Copyright(c) 2015 Tiancheng \"Timothy\" Gu\n * MIT Licensed\n */\n\n'use strict';\n\n/**\n * Module variables.\n * @private\n */\n\nvar matchHtmlRegExp = /[\"'&<>]/;\n\n/**\n * Module exports.\n * @public\n */\n\nmodule.exports = escapeHtml;\n\n/**\n * Escape special characters in the given string of html.\n *\n * @param {string} string The string to escape for inserting into HTML\n * @return {string}\n * @public\n */\n\nfunction escapeHtml(string) {\n var str = '' + string;\n var match = matchHtmlRegExp.exec(str);\n\n if (!match) {\n return str;\n }\n\n var escape;\n var html = '';\n var index = 0;\n var lastIndex = 0;\n\n for (index = match.index; index < str.length; index++) {\n switch (str.charCodeAt(index)) {\n case 34: // \"\n escape = '"';\n break;\n case 38: // &\n escape = '&';\n break;\n case 39: // '\n escape = ''';\n break;\n case 60: // <\n escape = '<';\n break;\n case 62: // >\n escape = '>';\n break;\n default:\n continue;\n }\n\n if (lastIndex !== index) {\n html += str.substring(lastIndex, index);\n }\n\n lastIndex = index + 1;\n html += escape;\n }\n\n return lastIndex !== index\n ? html + str.substring(lastIndex, index)\n : html;\n}\n", "/*\n * Copyright (c) 2016-2024 Martin Donath \n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to\n * deal in the Software without restriction, including without limitation the\n * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or\n * sell copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in\n * all copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\n * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS\n * IN THE SOFTWARE.\n */\n\nimport \"focus-visible\"\n\nimport {\n EMPTY,\n NEVER,\n Observable,\n Subject,\n defer,\n delay,\n filter,\n map,\n merge,\n mergeWith,\n shareReplay,\n switchMap\n} from \"rxjs\"\n\nimport { configuration, feature } from \"./_\"\nimport {\n at,\n getActiveElement,\n getOptionalElement,\n requestJSON,\n setLocation,\n setToggle,\n watchDocument,\n watchKeyboard,\n watchLocation,\n watchLocationTarget,\n watchMedia,\n watchPrint,\n watchScript,\n watchViewport\n} from \"./browser\"\nimport {\n getComponentElement,\n getComponentElements,\n mountAnnounce,\n mountBackToTop,\n mountConsent,\n mountContent,\n mountDialog,\n mountHeader,\n mountHeaderTitle,\n mountPalette,\n mountProgress,\n mountSearch,\n mountSearchHiglight,\n mountSidebar,\n mountSource,\n mountTableOfContents,\n mountTabs,\n watchHeader,\n watchMain\n} from \"./components\"\nimport {\n SearchIndex,\n setupClipboardJS,\n setupInstantNavigation,\n setupVersionSelector\n} from \"./integrations\"\nimport {\n patchEllipsis,\n patchIndeterminate,\n patchScrollfix,\n patchScrolllock\n} from \"./patches\"\nimport \"./polyfills\"\n\n/* ----------------------------------------------------------------------------\n * Functions - @todo refactor\n * ------------------------------------------------------------------------- */\n\n/**\n * Fetch search index\n *\n * @returns Search index observable\n */\nfunction fetchSearchIndex(): Observable {\n if (location.protocol === \"file:\") {\n return watchScript(\n `${new URL(\"search/search_index.js\", config.base)}`\n )\n .pipe(\n // @ts-ignore - @todo fix typings\n map(() => __index),\n shareReplay(1)\n )\n } else {\n return requestJSON(\n new URL(\"search/search_index.json\", config.base)\n )\n }\n}\n\n/* ----------------------------------------------------------------------------\n * Application\n * ------------------------------------------------------------------------- */\n\n/* Yay, JavaScript is available */\ndocument.documentElement.classList.remove(\"no-js\")\ndocument.documentElement.classList.add(\"js\")\n\n/* Set up navigation observables and subjects */\nconst document$ = watchDocument()\nconst location$ = watchLocation()\nconst target$ = watchLocationTarget(location$)\nconst keyboard$ = watchKeyboard()\n\n/* Set up media observables */\nconst viewport$ = watchViewport()\nconst tablet$ = watchMedia(\"(min-width: 960px)\")\nconst screen$ = watchMedia(\"(min-width: 1220px)\")\nconst print$ = watchPrint()\n\n/* Retrieve search index, if search is enabled */\nconst config = configuration()\nconst index$ = document.forms.namedItem(\"search\")\n ? fetchSearchIndex()\n : NEVER\n\n/* Set up Clipboard.js integration */\nconst alert$ = new Subject()\nsetupClipboardJS({ alert$ })\n\n/* Set up progress indicator */\nconst progress$ = new Subject()\n\n/* Set up instant navigation, if enabled */\nif (feature(\"navigation.instant\"))\n setupInstantNavigation({ location$, viewport$, progress$ })\n .subscribe(document$)\n\n/* Set up version selector */\nif (config.version?.provider === \"mike\")\n setupVersionSelector({ document$ })\n\n/* Always close drawer and search on navigation */\nmerge(location$, target$)\n .pipe(\n delay(125)\n )\n .subscribe(() => {\n setToggle(\"drawer\", false)\n setToggle(\"search\", false)\n })\n\n/* Set up global keyboard handlers */\nkeyboard$\n .pipe(\n filter(({ mode }) => mode === \"global\")\n )\n .subscribe(key => {\n switch (key.type) {\n\n /* Go to previous page */\n case \"p\":\n case \",\":\n const prev = getOptionalElement(\"link[rel=prev]\")\n if (typeof prev !== \"undefined\")\n setLocation(prev)\n break\n\n /* Go to next page */\n case \"n\":\n case \".\":\n const next = getOptionalElement(\"link[rel=next]\")\n if (typeof next !== \"undefined\")\n setLocation(next)\n break\n\n /* Expand navigation, see https://bit.ly/3ZjG5io */\n case \"Enter\":\n const active = getActiveElement()\n if (active instanceof HTMLLabelElement)\n active.click()\n }\n })\n\n/* Set up patches */\npatchEllipsis({ viewport$, document$ })\npatchIndeterminate({ document$, tablet$ })\npatchScrollfix({ document$ })\npatchScrolllock({ viewport$, tablet$ })\n\n/* Set up header and main area observable */\nconst header$ = watchHeader(getComponentElement(\"header\"), { viewport$ })\nconst main$ = document$\n .pipe(\n map(() => getComponentElement(\"main\")),\n switchMap(el => watchMain(el, { viewport$, header$ })),\n shareReplay(1)\n )\n\n/* Set up control component observables */\nconst control$ = merge(\n\n /* Consent */\n ...getComponentElements(\"consent\")\n .map(el => mountConsent(el, { target$ })),\n\n /* Dialog */\n ...getComponentElements(\"dialog\")\n .map(el => mountDialog(el, { alert$ })),\n\n /* Header */\n ...getComponentElements(\"header\")\n .map(el => mountHeader(el, { viewport$, header$, main$ })),\n\n /* Color palette */\n ...getComponentElements(\"palette\")\n .map(el => mountPalette(el)),\n\n /* Progress bar */\n ...getComponentElements(\"progress\")\n .map(el => mountProgress(el, { progress$ })),\n\n /* Search */\n ...getComponentElements(\"search\")\n .map(el => mountSearch(el, { index$, keyboard$ })),\n\n /* Repository information */\n ...getComponentElements(\"source\")\n .map(el => mountSource(el))\n)\n\n/* Set up content component observables */\nconst content$ = defer(() => merge(\n\n /* Announcement bar */\n ...getComponentElements(\"announce\")\n .map(el => mountAnnounce(el)),\n\n /* Content */\n ...getComponentElements(\"content\")\n .map(el => mountContent(el, { viewport$, target$, print$ })),\n\n /* Search highlighting */\n ...getComponentElements(\"content\")\n .map(el => feature(\"search.highlight\")\n ? mountSearchHiglight(el, { index$, location$ })\n : EMPTY\n ),\n\n /* Header title */\n ...getComponentElements(\"header-title\")\n .map(el => mountHeaderTitle(el, { viewport$, header$ })),\n\n /* Sidebar */\n ...getComponentElements(\"sidebar\")\n .map(el => el.getAttribute(\"data-md-type\") === \"navigation\"\n ? at(screen$, () => mountSidebar(el, { viewport$, header$, main$ }))\n : at(tablet$, () => mountSidebar(el, { viewport$, header$, main$ }))\n ),\n\n /* Navigation tabs */\n ...getComponentElements(\"tabs\")\n .map(el => mountTabs(el, { viewport$, header$ })),\n\n /* Table of contents */\n ...getComponentElements(\"toc\")\n .map(el => mountTableOfContents(el, {\n viewport$, header$, main$, target$\n })),\n\n /* Back-to-top button */\n ...getComponentElements(\"top\")\n .map(el => mountBackToTop(el, { viewport$, header$, main$, target$ }))\n))\n\n/* Set up component observables */\nconst component$ = document$\n .pipe(\n switchMap(() => content$),\n mergeWith(control$),\n shareReplay(1)\n )\n\n/* Subscribe to all components */\ncomponent$.subscribe()\n\n/* ----------------------------------------------------------------------------\n * Exports\n * ------------------------------------------------------------------------- */\n\nwindow.document$ = document$ /* Document observable */\nwindow.location$ = location$ /* Location subject */\nwindow.target$ = target$ /* Location target observable */\nwindow.keyboard$ = keyboard$ /* Keyboard observable */\nwindow.viewport$ = viewport$ /* Viewport observable */\nwindow.tablet$ = tablet$ /* Media tablet observable */\nwindow.screen$ = screen$ /* Media screen observable */\nwindow.print$ = print$ /* Media print observable */\nwindow.alert$ = alert$ /* Alert subject */\nwindow.progress$ = progress$ /* Progress indicator subject */\nwindow.component$ = component$ /* Component observable */\n", "/*! *****************************************************************************\r\nCopyright (c) Microsoft Corporation.\r\n\r\nPermission to use, copy, modify, and/or distribute this software for any\r\npurpose with or without fee is hereby granted.\r\n\r\nTHE SOFTWARE IS PROVIDED \"AS IS\" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH\r\nREGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY\r\nAND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,\r\nINDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM\r\nLOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR\r\nOTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR\r\nPERFORMANCE OF THIS SOFTWARE.\r\n***************************************************************************** */\r\n/* global Reflect, Promise */\r\n\r\nvar extendStatics = function(d, b) {\r\n extendStatics = Object.setPrototypeOf ||\r\n ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||\r\n function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };\r\n return extendStatics(d, b);\r\n};\r\n\r\nexport function __extends(d, b) {\r\n if (typeof b !== \"function\" && b !== null)\r\n throw new TypeError(\"Class extends value \" + String(b) + \" is not a constructor or null\");\r\n extendStatics(d, b);\r\n function __() { this.constructor = d; }\r\n d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());\r\n}\r\n\r\nexport var __assign = function() {\r\n __assign = Object.assign || function __assign(t) {\r\n for (var s, i = 1, n = arguments.length; i < n; i++) {\r\n s = arguments[i];\r\n for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p)) t[p] = s[p];\r\n }\r\n return t;\r\n }\r\n return __assign.apply(this, arguments);\r\n}\r\n\r\nexport function __rest(s, e) {\r\n var t = {};\r\n for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)\r\n t[p] = s[p];\r\n if (s != null && typeof Object.getOwnPropertySymbols === \"function\")\r\n for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {\r\n if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))\r\n t[p[i]] = s[p[i]];\r\n }\r\n return t;\r\n}\r\n\r\nexport function __decorate(decorators, target, key, desc) {\r\n var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;\r\n if (typeof Reflect === \"object\" && typeof Reflect.decorate === \"function\") r = Reflect.decorate(decorators, target, key, desc);\r\n else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;\r\n return c > 3 && r && Object.defineProperty(target, key, r), r;\r\n}\r\n\r\nexport function __param(paramIndex, decorator) {\r\n return function (target, key) { decorator(target, key, paramIndex); }\r\n}\r\n\r\nexport function __metadata(metadataKey, metadataValue) {\r\n if (typeof Reflect === \"object\" && typeof Reflect.metadata === \"function\") return Reflect.metadata(metadataKey, metadataValue);\r\n}\r\n\r\nexport function __awaiter(thisArg, _arguments, P, generator) {\r\n function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }\r\n return new (P || (P = Promise))(function (resolve, reject) {\r\n function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }\r\n function rejected(value) { try { step(generator[\"throw\"](value)); } catch (e) { reject(e); } }\r\n function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }\r\n step((generator = generator.apply(thisArg, _arguments || [])).next());\r\n });\r\n}\r\n\r\nexport function __generator(thisArg, body) {\r\n var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;\r\n return g = { next: verb(0), \"throw\": verb(1), \"return\": verb(2) }, typeof Symbol === \"function\" && (g[Symbol.iterator] = function() { return this; }), g;\r\n function verb(n) { return function (v) { return step([n, v]); }; }\r\n function step(op) {\r\n if (f) throw new TypeError(\"Generator is already executing.\");\r\n while (_) try {\r\n if (f = 1, y && (t = op[0] & 2 ? y[\"return\"] : op[0] ? y[\"throw\"] || ((t = y[\"return\"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;\r\n if (y = 0, t) op = [op[0] & 2, t.value];\r\n switch (op[0]) {\r\n case 0: case 1: t = op; break;\r\n case 4: _.label++; return { value: op[1], done: false };\r\n case 5: _.label++; y = op[1]; op = [0]; continue;\r\n case 7: op = _.ops.pop(); _.trys.pop(); continue;\r\n default:\r\n if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }\r\n if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }\r\n if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }\r\n if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }\r\n if (t[2]) _.ops.pop();\r\n _.trys.pop(); continue;\r\n }\r\n op = body.call(thisArg, _);\r\n } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }\r\n if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };\r\n }\r\n}\r\n\r\nexport var __createBinding = Object.create ? (function(o, m, k, k2) {\r\n if (k2 === undefined) k2 = k;\r\n Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });\r\n}) : (function(o, m, k, k2) {\r\n if (k2 === undefined) k2 = k;\r\n o[k2] = m[k];\r\n});\r\n\r\nexport function __exportStar(m, o) {\r\n for (var p in m) if (p !== \"default\" && !Object.prototype.hasOwnProperty.call(o, p)) __createBinding(o, m, p);\r\n}\r\n\r\nexport function __values(o) {\r\n var s = typeof Symbol === \"function\" && Symbol.iterator, m = s && o[s], i = 0;\r\n if (m) return m.call(o);\r\n if (o && typeof o.length === \"number\") return {\r\n next: function () {\r\n if (o && i >= o.length) o = void 0;\r\n return { value: o && o[i++], done: !o };\r\n }\r\n };\r\n throw new TypeError(s ? \"Object is not iterable.\" : \"Symbol.iterator is not defined.\");\r\n}\r\n\r\nexport function __read(o, n) {\r\n var m = typeof Symbol === \"function\" && o[Symbol.iterator];\r\n if (!m) return o;\r\n var i = m.call(o), r, ar = [], e;\r\n try {\r\n while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);\r\n }\r\n catch (error) { e = { error: error }; }\r\n finally {\r\n try {\r\n if (r && !r.done && (m = i[\"return\"])) m.call(i);\r\n }\r\n finally { if (e) throw e.error; }\r\n }\r\n return ar;\r\n}\r\n\r\n/** @deprecated */\r\nexport function __spread() {\r\n for (var ar = [], i = 0; i < arguments.length; i++)\r\n ar = ar.concat(__read(arguments[i]));\r\n return ar;\r\n}\r\n\r\n/** @deprecated */\r\nexport function __spreadArrays() {\r\n for (var s = 0, i = 0, il = arguments.length; i < il; i++) s += arguments[i].length;\r\n for (var r = Array(s), k = 0, i = 0; i < il; i++)\r\n for (var a = arguments[i], j = 0, jl = a.length; j < jl; j++, k++)\r\n r[k] = a[j];\r\n return r;\r\n}\r\n\r\nexport function __spreadArray(to, from, pack) {\r\n if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {\r\n if (ar || !(i in from)) {\r\n if (!ar) ar = Array.prototype.slice.call(from, 0, i);\r\n ar[i] = from[i];\r\n }\r\n }\r\n return to.concat(ar || Array.prototype.slice.call(from));\r\n}\r\n\r\nexport function __await(v) {\r\n return this instanceof __await ? (this.v = v, this) : new __await(v);\r\n}\r\n\r\nexport function __asyncGenerator(thisArg, _arguments, generator) {\r\n if (!Symbol.asyncIterator) throw new TypeError(\"Symbol.asyncIterator is not defined.\");\r\n var g = generator.apply(thisArg, _arguments || []), i, q = [];\r\n return i = {}, verb(\"next\"), verb(\"throw\"), verb(\"return\"), i[Symbol.asyncIterator] = function () { return this; }, i;\r\n function verb(n) { if (g[n]) i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; }\r\n function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }\r\n function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }\r\n function fulfill(value) { resume(\"next\", value); }\r\n function reject(value) { resume(\"throw\", value); }\r\n function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }\r\n}\r\n\r\nexport function __asyncDelegator(o) {\r\n var i, p;\r\n return i = {}, verb(\"next\"), verb(\"throw\", function (e) { throw e; }), verb(\"return\"), i[Symbol.iterator] = function () { return this; }, i;\r\n function verb(n, f) { i[n] = o[n] ? function (v) { return (p = !p) ? { value: __await(o[n](v)), done: n === \"return\" } : f ? f(v) : v; } : f; }\r\n}\r\n\r\nexport function __asyncValues(o) {\r\n if (!Symbol.asyncIterator) throw new TypeError(\"Symbol.asyncIterator is not defined.\");\r\n var m = o[Symbol.asyncIterator], i;\r\n return m ? m.call(o) : (o = typeof __values === \"function\" ? __values(o) : o[Symbol.iterator](), i = {}, verb(\"next\"), verb(\"throw\"), verb(\"return\"), i[Symbol.asyncIterator] = function () { return this; }, i);\r\n function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }\r\n function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }\r\n}\r\n\r\nexport function __makeTemplateObject(cooked, raw) {\r\n if (Object.defineProperty) { Object.defineProperty(cooked, \"raw\", { value: raw }); } else { cooked.raw = raw; }\r\n return cooked;\r\n};\r\n\r\nvar __setModuleDefault = Object.create ? (function(o, v) {\r\n Object.defineProperty(o, \"default\", { enumerable: true, value: v });\r\n}) : function(o, v) {\r\n o[\"default\"] = v;\r\n};\r\n\r\nexport function __importStar(mod) {\r\n if (mod && mod.__esModule) return mod;\r\n var result = {};\r\n if (mod != null) for (var k in mod) if (k !== \"default\" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);\r\n __setModuleDefault(result, mod);\r\n return result;\r\n}\r\n\r\nexport function __importDefault(mod) {\r\n return (mod && mod.__esModule) ? mod : { default: mod };\r\n}\r\n\r\nexport function __classPrivateFieldGet(receiver, state, kind, f) {\r\n if (kind === \"a\" && !f) throw new TypeError(\"Private accessor was defined without a getter\");\r\n if (typeof state === \"function\" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError(\"Cannot read private member from an object whose class did not declare it\");\r\n return kind === \"m\" ? f : kind === \"a\" ? f.call(receiver) : f ? f.value : state.get(receiver);\r\n}\r\n\r\nexport function __classPrivateFieldSet(receiver, state, value, kind, f) {\r\n if (kind === \"m\") throw new TypeError(\"Private method is not writable\");\r\n if (kind === \"a\" && !f) throw new TypeError(\"Private accessor was defined without a setter\");\r\n if (typeof state === \"function\" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError(\"Cannot write private member to an object whose class did not declare it\");\r\n return (kind === \"a\" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;\r\n}\r\n", "/**\n * Returns true if the object is a function.\n * @param value The value to check\n */\nexport function isFunction(value: any): value is (...args: any[]) => any {\n return typeof value === 'function';\n}\n", "/**\n * Used to create Error subclasses until the community moves away from ES5.\n *\n * This is because compiling from TypeScript down to ES5 has issues with subclassing Errors\n * as well as other built-in types: https://github.com/Microsoft/TypeScript/issues/12123\n *\n * @param createImpl A factory function to create the actual constructor implementation. The returned\n * function should be a named function that calls `_super` internally.\n */\nexport function createErrorClass(createImpl: (_super: any) => any): T {\n const _super = (instance: any) => {\n Error.call(instance);\n instance.stack = new Error().stack;\n };\n\n const ctorFunc = createImpl(_super);\n ctorFunc.prototype = Object.create(Error.prototype);\n ctorFunc.prototype.constructor = ctorFunc;\n return ctorFunc;\n}\n", "import { createErrorClass } from './createErrorClass';\n\nexport interface UnsubscriptionError extends Error {\n readonly errors: any[];\n}\n\nexport interface UnsubscriptionErrorCtor {\n /**\n * @deprecated Internal implementation detail. Do not construct error instances.\n * Cannot be tagged as internal: https://github.com/ReactiveX/rxjs/issues/6269\n */\n new (errors: any[]): UnsubscriptionError;\n}\n\n/**\n * An error thrown when one or more errors have occurred during the\n * `unsubscribe` of a {@link Subscription}.\n */\nexport const UnsubscriptionError: UnsubscriptionErrorCtor = createErrorClass(\n (_super) =>\n function UnsubscriptionErrorImpl(this: any, errors: (Error | string)[]) {\n _super(this);\n this.message = errors\n ? `${errors.length} errors occurred during unsubscription:\n${errors.map((err, i) => `${i + 1}) ${err.toString()}`).join('\\n ')}`\n : '';\n this.name = 'UnsubscriptionError';\n this.errors = errors;\n }\n);\n", "/**\n * Removes an item from an array, mutating it.\n * @param arr The array to remove the item from\n * @param item The item to remove\n */\nexport function arrRemove(arr: T[] | undefined | null, item: T) {\n if (arr) {\n const index = arr.indexOf(item);\n 0 <= index && arr.splice(index, 1);\n }\n}\n", "import { isFunction } from './util/isFunction';\nimport { UnsubscriptionError } from './util/UnsubscriptionError';\nimport { SubscriptionLike, TeardownLogic, Unsubscribable } from './types';\nimport { arrRemove } from './util/arrRemove';\n\n/**\n * Represents a disposable resource, such as the execution of an Observable. A\n * Subscription has one important method, `unsubscribe`, that takes no argument\n * and just disposes the resource held by the subscription.\n *\n * Additionally, subscriptions may be grouped together through the `add()`\n * method, which will attach a child Subscription to the current Subscription.\n * When a Subscription is unsubscribed, all its children (and its grandchildren)\n * will be unsubscribed as well.\n *\n * @class Subscription\n */\nexport class Subscription implements SubscriptionLike {\n /** @nocollapse */\n public static EMPTY = (() => {\n const empty = new Subscription();\n empty.closed = true;\n return empty;\n })();\n\n /**\n * A flag to indicate whether this Subscription has already been unsubscribed.\n */\n public closed = false;\n\n private _parentage: Subscription[] | Subscription | null = null;\n\n /**\n * The list of registered finalizers to execute upon unsubscription. Adding and removing from this\n * list occurs in the {@link #add} and {@link #remove} methods.\n */\n private _finalizers: Exclude[] | null = null;\n\n /**\n * @param initialTeardown A function executed first as part of the finalization\n * process that is kicked off when {@link #unsubscribe} is called.\n */\n constructor(private initialTeardown?: () => void) {}\n\n /**\n * Disposes the resources held by the subscription. May, for instance, cancel\n * an ongoing Observable execution or cancel any other type of work that\n * started when the Subscription was created.\n * @return {void}\n */\n unsubscribe(): void {\n let errors: any[] | undefined;\n\n if (!this.closed) {\n this.closed = true;\n\n // Remove this from it's parents.\n const { _parentage } = this;\n if (_parentage) {\n this._parentage = null;\n if (Array.isArray(_parentage)) {\n for (const parent of _parentage) {\n parent.remove(this);\n }\n } else {\n _parentage.remove(this);\n }\n }\n\n const { initialTeardown: initialFinalizer } = this;\n if (isFunction(initialFinalizer)) {\n try {\n initialFinalizer();\n } catch (e) {\n errors = e instanceof UnsubscriptionError ? e.errors : [e];\n }\n }\n\n const { _finalizers } = this;\n if (_finalizers) {\n this._finalizers = null;\n for (const finalizer of _finalizers) {\n try {\n execFinalizer(finalizer);\n } catch (err) {\n errors = errors ?? [];\n if (err instanceof UnsubscriptionError) {\n errors = [...errors, ...err.errors];\n } else {\n errors.push(err);\n }\n }\n }\n }\n\n if (errors) {\n throw new UnsubscriptionError(errors);\n }\n }\n }\n\n /**\n * Adds a finalizer to this subscription, so that finalization will be unsubscribed/called\n * when this subscription is unsubscribed. If this subscription is already {@link #closed},\n * because it has already been unsubscribed, then whatever finalizer is passed to it\n * will automatically be executed (unless the finalizer itself is also a closed subscription).\n *\n * Closed Subscriptions cannot be added as finalizers to any subscription. Adding a closed\n * subscription to a any subscription will result in no operation. (A noop).\n *\n * Adding a subscription to itself, or adding `null` or `undefined` will not perform any\n * operation at all. (A noop).\n *\n * `Subscription` instances that are added to this instance will automatically remove themselves\n * if they are unsubscribed. Functions and {@link Unsubscribable} objects that you wish to remove\n * will need to be removed manually with {@link #remove}\n *\n * @param teardown The finalization logic to add to this subscription.\n */\n add(teardown: TeardownLogic): void {\n // Only add the finalizer if it's not undefined\n // and don't add a subscription to itself.\n if (teardown && teardown !== this) {\n if (this.closed) {\n // If this subscription is already closed,\n // execute whatever finalizer is handed to it automatically.\n execFinalizer(teardown);\n } else {\n if (teardown instanceof Subscription) {\n // We don't add closed subscriptions, and we don't add the same subscription\n // twice. Subscription unsubscribe is idempotent.\n if (teardown.closed || teardown._hasParent(this)) {\n return;\n }\n teardown._addParent(this);\n }\n (this._finalizers = this._finalizers ?? []).push(teardown);\n }\n }\n }\n\n /**\n * Checks to see if a this subscription already has a particular parent.\n * This will signal that this subscription has already been added to the parent in question.\n * @param parent the parent to check for\n */\n private _hasParent(parent: Subscription) {\n const { _parentage } = this;\n return _parentage === parent || (Array.isArray(_parentage) && _parentage.includes(parent));\n }\n\n /**\n * Adds a parent to this subscription so it can be removed from the parent if it\n * unsubscribes on it's own.\n *\n * NOTE: THIS ASSUMES THAT {@link _hasParent} HAS ALREADY BEEN CHECKED.\n * @param parent The parent subscription to add\n */\n private _addParent(parent: Subscription) {\n const { _parentage } = this;\n this._parentage = Array.isArray(_parentage) ? (_parentage.push(parent), _parentage) : _parentage ? [_parentage, parent] : parent;\n }\n\n /**\n * Called on a child when it is removed via {@link #remove}.\n * @param parent The parent to remove\n */\n private _removeParent(parent: Subscription) {\n const { _parentage } = this;\n if (_parentage === parent) {\n this._parentage = null;\n } else if (Array.isArray(_parentage)) {\n arrRemove(_parentage, parent);\n }\n }\n\n /**\n * Removes a finalizer from this subscription that was previously added with the {@link #add} method.\n *\n * Note that `Subscription` instances, when unsubscribed, will automatically remove themselves\n * from every other `Subscription` they have been added to. This means that using the `remove` method\n * is not a common thing and should be used thoughtfully.\n *\n * If you add the same finalizer instance of a function or an unsubscribable object to a `Subscription` instance\n * more than once, you will need to call `remove` the same number of times to remove all instances.\n *\n * All finalizer instances are removed to free up memory upon unsubscription.\n *\n * @param teardown The finalizer to remove from this subscription\n */\n remove(teardown: Exclude): void {\n const { _finalizers } = this;\n _finalizers && arrRemove(_finalizers, teardown);\n\n if (teardown instanceof Subscription) {\n teardown._removeParent(this);\n }\n }\n}\n\nexport const EMPTY_SUBSCRIPTION = Subscription.EMPTY;\n\nexport function isSubscription(value: any): value is Subscription {\n return (\n value instanceof Subscription ||\n (value && 'closed' in value && isFunction(value.remove) && isFunction(value.add) && isFunction(value.unsubscribe))\n );\n}\n\nfunction execFinalizer(finalizer: Unsubscribable | (() => void)) {\n if (isFunction(finalizer)) {\n finalizer();\n } else {\n finalizer.unsubscribe();\n }\n}\n", "import { Subscriber } from './Subscriber';\nimport { ObservableNotification } from './types';\n\n/**\n * The {@link GlobalConfig} object for RxJS. It is used to configure things\n * like how to react on unhandled errors.\n */\nexport const config: GlobalConfig = {\n onUnhandledError: null,\n onStoppedNotification: null,\n Promise: undefined,\n useDeprecatedSynchronousErrorHandling: false,\n useDeprecatedNextContext: false,\n};\n\n/**\n * The global configuration object for RxJS, used to configure things\n * like how to react on unhandled errors. Accessible via {@link config}\n * object.\n */\nexport interface GlobalConfig {\n /**\n * A registration point for unhandled errors from RxJS. These are errors that\n * cannot were not handled by consuming code in the usual subscription path. For\n * example, if you have this configured, and you subscribe to an observable without\n * providing an error handler, errors from that subscription will end up here. This\n * will _always_ be called asynchronously on another job in the runtime. This is because\n * we do not want errors thrown in this user-configured handler to interfere with the\n * behavior of the library.\n */\n onUnhandledError: ((err: any) => void) | null;\n\n /**\n * A registration point for notifications that cannot be sent to subscribers because they\n * have completed, errored or have been explicitly unsubscribed. By default, next, complete\n * and error notifications sent to stopped subscribers are noops. However, sometimes callers\n * might want a different behavior. For example, with sources that attempt to report errors\n * to stopped subscribers, a caller can configure RxJS to throw an unhandled error instead.\n * This will _always_ be called asynchronously on another job in the runtime. This is because\n * we do not want errors thrown in this user-configured handler to interfere with the\n * behavior of the library.\n */\n onStoppedNotification: ((notification: ObservableNotification, subscriber: Subscriber) => void) | null;\n\n /**\n * The promise constructor used by default for {@link Observable#toPromise toPromise} and {@link Observable#forEach forEach}\n * methods.\n *\n * @deprecated As of version 8, RxJS will no longer support this sort of injection of a\n * Promise constructor. If you need a Promise implementation other than native promises,\n * please polyfill/patch Promise as you see appropriate. Will be removed in v8.\n */\n Promise?: PromiseConstructorLike;\n\n /**\n * If true, turns on synchronous error rethrowing, which is a deprecated behavior\n * in v6 and higher. This behavior enables bad patterns like wrapping a subscribe\n * call in a try/catch block. It also enables producer interference, a nasty bug\n * where a multicast can be broken for all observers by a downstream consumer with\n * an unhandled error. DO NOT USE THIS FLAG UNLESS IT'S NEEDED TO BUY TIME\n * FOR MIGRATION REASONS.\n *\n * @deprecated As of version 8, RxJS will no longer support synchronous throwing\n * of unhandled errors. All errors will be thrown on a separate call stack to prevent bad\n * behaviors described above. Will be removed in v8.\n */\n useDeprecatedSynchronousErrorHandling: boolean;\n\n /**\n * If true, enables an as-of-yet undocumented feature from v5: The ability to access\n * `unsubscribe()` via `this` context in `next` functions created in observers passed\n * to `subscribe`.\n *\n * This is being removed because the performance was severely problematic, and it could also cause\n * issues when types other than POJOs are passed to subscribe as subscribers, as they will likely have\n * their `this` context overwritten.\n *\n * @deprecated As of version 8, RxJS will no longer support altering the\n * context of next functions provided as part of an observer to Subscribe. Instead,\n * you will have access to a subscription or a signal or token that will allow you to do things like\n * unsubscribe and test closed status. Will be removed in v8.\n */\n useDeprecatedNextContext: boolean;\n}\n", "import type { TimerHandle } from './timerHandle';\ntype SetTimeoutFunction = (handler: () => void, timeout?: number, ...args: any[]) => TimerHandle;\ntype ClearTimeoutFunction = (handle: TimerHandle) => void;\n\ninterface TimeoutProvider {\n setTimeout: SetTimeoutFunction;\n clearTimeout: ClearTimeoutFunction;\n delegate:\n | {\n setTimeout: SetTimeoutFunction;\n clearTimeout: ClearTimeoutFunction;\n }\n | undefined;\n}\n\nexport const timeoutProvider: TimeoutProvider = {\n // When accessing the delegate, use the variable rather than `this` so that\n // the functions can be called without being bound to the provider.\n setTimeout(handler: () => void, timeout?: number, ...args) {\n const { delegate } = timeoutProvider;\n if (delegate?.setTimeout) {\n return delegate.setTimeout(handler, timeout, ...args);\n }\n return setTimeout(handler, timeout, ...args);\n },\n clearTimeout(handle) {\n const { delegate } = timeoutProvider;\n return (delegate?.clearTimeout || clearTimeout)(handle as any);\n },\n delegate: undefined,\n};\n", "import { config } from '../config';\nimport { timeoutProvider } from '../scheduler/timeoutProvider';\n\n/**\n * Handles an error on another job either with the user-configured {@link onUnhandledError},\n * or by throwing it on that new job so it can be picked up by `window.onerror`, `process.on('error')`, etc.\n *\n * This should be called whenever there is an error that is out-of-band with the subscription\n * or when an error hits a terminal boundary of the subscription and no error handler was provided.\n *\n * @param err the error to report\n */\nexport function reportUnhandledError(err: any) {\n timeoutProvider.setTimeout(() => {\n const { onUnhandledError } = config;\n if (onUnhandledError) {\n // Execute the user-configured error handler.\n onUnhandledError(err);\n } else {\n // Throw so it is picked up by the runtime's uncaught error mechanism.\n throw err;\n }\n });\n}\n", "/* tslint:disable:no-empty */\nexport function noop() { }\n", "import { CompleteNotification, NextNotification, ErrorNotification } from './types';\n\n/**\n * A completion object optimized for memory use and created to be the\n * same \"shape\" as other notifications in v8.\n * @internal\n */\nexport const COMPLETE_NOTIFICATION = (() => createNotification('C', undefined, undefined) as CompleteNotification)();\n\n/**\n * Internal use only. Creates an optimized error notification that is the same \"shape\"\n * as other notifications.\n * @internal\n */\nexport function errorNotification(error: any): ErrorNotification {\n return createNotification('E', undefined, error) as any;\n}\n\n/**\n * Internal use only. Creates an optimized next notification that is the same \"shape\"\n * as other notifications.\n * @internal\n */\nexport function nextNotification(value: T) {\n return createNotification('N', value, undefined) as NextNotification;\n}\n\n/**\n * Ensures that all notifications created internally have the same \"shape\" in v8.\n *\n * TODO: This is only exported to support a crazy legacy test in `groupBy`.\n * @internal\n */\nexport function createNotification(kind: 'N' | 'E' | 'C', value: any, error: any) {\n return {\n kind,\n value,\n error,\n };\n}\n", "import { config } from '../config';\n\nlet context: { errorThrown: boolean; error: any } | null = null;\n\n/**\n * Handles dealing with errors for super-gross mode. Creates a context, in which\n * any synchronously thrown errors will be passed to {@link captureError}. Which\n * will record the error such that it will be rethrown after the call back is complete.\n * TODO: Remove in v8\n * @param cb An immediately executed function.\n */\nexport function errorContext(cb: () => void) {\n if (config.useDeprecatedSynchronousErrorHandling) {\n const isRoot = !context;\n if (isRoot) {\n context = { errorThrown: false, error: null };\n }\n cb();\n if (isRoot) {\n const { errorThrown, error } = context!;\n context = null;\n if (errorThrown) {\n throw error;\n }\n }\n } else {\n // This is the general non-deprecated path for everyone that\n // isn't crazy enough to use super-gross mode (useDeprecatedSynchronousErrorHandling)\n cb();\n }\n}\n\n/**\n * Captures errors only in super-gross mode.\n * @param err the error to capture\n */\nexport function captureError(err: any) {\n if (config.useDeprecatedSynchronousErrorHandling && context) {\n context.errorThrown = true;\n context.error = err;\n }\n}\n", "import { isFunction } from './util/isFunction';\nimport { Observer, ObservableNotification } from './types';\nimport { isSubscription, Subscription } from './Subscription';\nimport { config } from './config';\nimport { reportUnhandledError } from './util/reportUnhandledError';\nimport { noop } from './util/noop';\nimport { nextNotification, errorNotification, COMPLETE_NOTIFICATION } from './NotificationFactories';\nimport { timeoutProvider } from './scheduler/timeoutProvider';\nimport { captureError } from './util/errorContext';\n\n/**\n * Implements the {@link Observer} interface and extends the\n * {@link Subscription} class. While the {@link Observer} is the public API for\n * consuming the values of an {@link Observable}, all Observers get converted to\n * a Subscriber, in order to provide Subscription-like capabilities such as\n * `unsubscribe`. Subscriber is a common type in RxJS, and crucial for\n * implementing operators, but it is rarely used as a public API.\n *\n * @class Subscriber\n */\nexport class Subscriber extends Subscription implements Observer {\n /**\n * A static factory for a Subscriber, given a (potentially partial) definition\n * of an Observer.\n * @param next The `next` callback of an Observer.\n * @param error The `error` callback of an\n * Observer.\n * @param complete The `complete` callback of an\n * Observer.\n * @return A Subscriber wrapping the (partially defined)\n * Observer represented by the given arguments.\n * @nocollapse\n * @deprecated Do not use. Will be removed in v8. There is no replacement for this\n * method, and there is no reason to be creating instances of `Subscriber` directly.\n * If you have a specific use case, please file an issue.\n */\n static create(next?: (x?: T) => void, error?: (e?: any) => void, complete?: () => void): Subscriber {\n return new SafeSubscriber(next, error, complete);\n }\n\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n protected isStopped: boolean = false;\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n protected destination: Subscriber | Observer; // this `any` is the escape hatch to erase extra type param (e.g. R)\n\n /**\n * @deprecated Internal implementation detail, do not use directly. Will be made internal in v8.\n * There is no reason to directly create an instance of Subscriber. This type is exported for typings reasons.\n */\n constructor(destination?: Subscriber | Observer) {\n super();\n if (destination) {\n this.destination = destination;\n // Automatically chain subscriptions together here.\n // if destination is a Subscription, then it is a Subscriber.\n if (isSubscription(destination)) {\n destination.add(this);\n }\n } else {\n this.destination = EMPTY_OBSERVER;\n }\n }\n\n /**\n * The {@link Observer} callback to receive notifications of type `next` from\n * the Observable, with a value. The Observable may call this method 0 or more\n * times.\n * @param {T} [value] The `next` value.\n * @return {void}\n */\n next(value?: T): void {\n if (this.isStopped) {\n handleStoppedNotification(nextNotification(value), this);\n } else {\n this._next(value!);\n }\n }\n\n /**\n * The {@link Observer} callback to receive notifications of type `error` from\n * the Observable, with an attached `Error`. Notifies the Observer that\n * the Observable has experienced an error condition.\n * @param {any} [err] The `error` exception.\n * @return {void}\n */\n error(err?: any): void {\n if (this.isStopped) {\n handleStoppedNotification(errorNotification(err), this);\n } else {\n this.isStopped = true;\n this._error(err);\n }\n }\n\n /**\n * The {@link Observer} callback to receive a valueless notification of type\n * `complete` from the Observable. Notifies the Observer that the Observable\n * has finished sending push-based notifications.\n * @return {void}\n */\n complete(): void {\n if (this.isStopped) {\n handleStoppedNotification(COMPLETE_NOTIFICATION, this);\n } else {\n this.isStopped = true;\n this._complete();\n }\n }\n\n unsubscribe(): void {\n if (!this.closed) {\n this.isStopped = true;\n super.unsubscribe();\n this.destination = null!;\n }\n }\n\n protected _next(value: T): void {\n this.destination.next(value);\n }\n\n protected _error(err: any): void {\n try {\n this.destination.error(err);\n } finally {\n this.unsubscribe();\n }\n }\n\n protected _complete(): void {\n try {\n this.destination.complete();\n } finally {\n this.unsubscribe();\n }\n }\n}\n\n/**\n * This bind is captured here because we want to be able to have\n * compatibility with monoid libraries that tend to use a method named\n * `bind`. In particular, a library called Monio requires this.\n */\nconst _bind = Function.prototype.bind;\n\nfunction bind any>(fn: Fn, thisArg: any): Fn {\n return _bind.call(fn, thisArg);\n}\n\n/**\n * Internal optimization only, DO NOT EXPOSE.\n * @internal\n */\nclass ConsumerObserver implements Observer {\n constructor(private partialObserver: Partial>) {}\n\n next(value: T): void {\n const { partialObserver } = this;\n if (partialObserver.next) {\n try {\n partialObserver.next(value);\n } catch (error) {\n handleUnhandledError(error);\n }\n }\n }\n\n error(err: any): void {\n const { partialObserver } = this;\n if (partialObserver.error) {\n try {\n partialObserver.error(err);\n } catch (error) {\n handleUnhandledError(error);\n }\n } else {\n handleUnhandledError(err);\n }\n }\n\n complete(): void {\n const { partialObserver } = this;\n if (partialObserver.complete) {\n try {\n partialObserver.complete();\n } catch (error) {\n handleUnhandledError(error);\n }\n }\n }\n}\n\nexport class SafeSubscriber extends Subscriber {\n constructor(\n observerOrNext?: Partial> | ((value: T) => void) | null,\n error?: ((e?: any) => void) | null,\n complete?: (() => void) | null\n ) {\n super();\n\n let partialObserver: Partial>;\n if (isFunction(observerOrNext) || !observerOrNext) {\n // The first argument is a function, not an observer. The next\n // two arguments *could* be observers, or they could be empty.\n partialObserver = {\n next: (observerOrNext ?? undefined) as (((value: T) => void) | undefined),\n error: error ?? undefined,\n complete: complete ?? undefined,\n };\n } else {\n // The first argument is a partial observer.\n let context: any;\n if (this && config.useDeprecatedNextContext) {\n // This is a deprecated path that made `this.unsubscribe()` available in\n // next handler functions passed to subscribe. This only exists behind a flag\n // now, as it is *very* slow.\n context = Object.create(observerOrNext);\n context.unsubscribe = () => this.unsubscribe();\n partialObserver = {\n next: observerOrNext.next && bind(observerOrNext.next, context),\n error: observerOrNext.error && bind(observerOrNext.error, context),\n complete: observerOrNext.complete && bind(observerOrNext.complete, context),\n };\n } else {\n // The \"normal\" path. Just use the partial observer directly.\n partialObserver = observerOrNext;\n }\n }\n\n // Wrap the partial observer to ensure it's a full observer, and\n // make sure proper error handling is accounted for.\n this.destination = new ConsumerObserver(partialObserver);\n }\n}\n\nfunction handleUnhandledError(error: any) {\n if (config.useDeprecatedSynchronousErrorHandling) {\n captureError(error);\n } else {\n // Ideal path, we report this as an unhandled error,\n // which is thrown on a new call stack.\n reportUnhandledError(error);\n }\n}\n\n/**\n * An error handler used when no error handler was supplied\n * to the SafeSubscriber -- meaning no error handler was supplied\n * do the `subscribe` call on our observable.\n * @param err The error to handle\n */\nfunction defaultErrorHandler(err: any) {\n throw err;\n}\n\n/**\n * A handler for notifications that cannot be sent to a stopped subscriber.\n * @param notification The notification being sent\n * @param subscriber The stopped subscriber\n */\nfunction handleStoppedNotification(notification: ObservableNotification, subscriber: Subscriber) {\n const { onStoppedNotification } = config;\n onStoppedNotification && timeoutProvider.setTimeout(() => onStoppedNotification(notification, subscriber));\n}\n\n/**\n * The observer used as a stub for subscriptions where the user did not\n * pass any arguments to `subscribe`. Comes with the default error handling\n * behavior.\n */\nexport const EMPTY_OBSERVER: Readonly> & { closed: true } = {\n closed: true,\n next: noop,\n error: defaultErrorHandler,\n complete: noop,\n};\n", "/**\n * Symbol.observable or a string \"@@observable\". Used for interop\n *\n * @deprecated We will no longer be exporting this symbol in upcoming versions of RxJS.\n * Instead polyfill and use Symbol.observable directly *or* use https://www.npmjs.com/package/symbol-observable\n */\nexport const observable: string | symbol = (() => (typeof Symbol === 'function' && Symbol.observable) || '@@observable')();\n", "/**\n * This function takes one parameter and just returns it. Simply put,\n * this is like `(x: T): T => x`.\n *\n * ## Examples\n *\n * This is useful in some cases when using things like `mergeMap`\n *\n * ```ts\n * import { interval, take, map, range, mergeMap, identity } from 'rxjs';\n *\n * const source$ = interval(1000).pipe(take(5));\n *\n * const result$ = source$.pipe(\n * map(i => range(i)),\n * mergeMap(identity) // same as mergeMap(x => x)\n * );\n *\n * result$.subscribe({\n * next: console.log\n * });\n * ```\n *\n * Or when you want to selectively apply an operator\n *\n * ```ts\n * import { interval, take, identity } from 'rxjs';\n *\n * const shouldLimit = () => Math.random() < 0.5;\n *\n * const source$ = interval(1000);\n *\n * const result$ = source$.pipe(shouldLimit() ? take(5) : identity);\n *\n * result$.subscribe({\n * next: console.log\n * });\n * ```\n *\n * @param x Any value that is returned by this function\n * @returns The value passed as the first parameter to this function\n */\nexport function identity(x: T): T {\n return x;\n}\n", "import { identity } from './identity';\nimport { UnaryFunction } from '../types';\n\nexport function pipe(): typeof identity;\nexport function pipe(fn1: UnaryFunction): UnaryFunction;\nexport function pipe(fn1: UnaryFunction, fn2: UnaryFunction): UnaryFunction;\nexport function pipe(fn1: UnaryFunction, fn2: UnaryFunction, fn3: UnaryFunction): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction\n): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction,\n fn5: UnaryFunction\n): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction,\n fn5: UnaryFunction,\n fn6: UnaryFunction\n): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction,\n fn5: UnaryFunction,\n fn6: UnaryFunction,\n fn7: UnaryFunction\n): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction,\n fn5: UnaryFunction,\n fn6: UnaryFunction,\n fn7: UnaryFunction,\n fn8: UnaryFunction\n): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction,\n fn5: UnaryFunction,\n fn6: UnaryFunction,\n fn7: UnaryFunction,\n fn8: UnaryFunction,\n fn9: UnaryFunction\n): UnaryFunction;\nexport function pipe(\n fn1: UnaryFunction,\n fn2: UnaryFunction,\n fn3: UnaryFunction,\n fn4: UnaryFunction,\n fn5: UnaryFunction,\n fn6: UnaryFunction,\n fn7: UnaryFunction,\n fn8: UnaryFunction,\n fn9: UnaryFunction,\n ...fns: UnaryFunction[]\n): UnaryFunction;\n\n/**\n * pipe() can be called on one or more functions, each of which can take one argument (\"UnaryFunction\")\n * and uses it to return a value.\n * It returns a function that takes one argument, passes it to the first UnaryFunction, and then\n * passes the result to the next one, passes that result to the next one, and so on. \n */\nexport function pipe(...fns: Array>): UnaryFunction {\n return pipeFromArray(fns);\n}\n\n/** @internal */\nexport function pipeFromArray(fns: Array>): UnaryFunction {\n if (fns.length === 0) {\n return identity as UnaryFunction;\n }\n\n if (fns.length === 1) {\n return fns[0];\n }\n\n return function piped(input: T): R {\n return fns.reduce((prev: any, fn: UnaryFunction) => fn(prev), input as any);\n };\n}\n", "import { Operator } from './Operator';\nimport { SafeSubscriber, Subscriber } from './Subscriber';\nimport { isSubscription, Subscription } from './Subscription';\nimport { TeardownLogic, OperatorFunction, Subscribable, Observer } from './types';\nimport { observable as Symbol_observable } from './symbol/observable';\nimport { pipeFromArray } from './util/pipe';\nimport { config } from './config';\nimport { isFunction } from './util/isFunction';\nimport { errorContext } from './util/errorContext';\n\n/**\n * A representation of any set of values over any amount of time. This is the most basic building block\n * of RxJS.\n *\n * @class Observable\n */\nexport class Observable implements Subscribable {\n /**\n * @deprecated Internal implementation detail, do not use directly. Will be made internal in v8.\n */\n source: Observable | undefined;\n\n /**\n * @deprecated Internal implementation detail, do not use directly. Will be made internal in v8.\n */\n operator: Operator | undefined;\n\n /**\n * @constructor\n * @param {Function} subscribe the function that is called when the Observable is\n * initially subscribed to. This function is given a Subscriber, to which new values\n * can be `next`ed, or an `error` method can be called to raise an error, or\n * `complete` can be called to notify of a successful completion.\n */\n constructor(subscribe?: (this: Observable, subscriber: Subscriber) => TeardownLogic) {\n if (subscribe) {\n this._subscribe = subscribe;\n }\n }\n\n // HACK: Since TypeScript inherits static properties too, we have to\n // fight against TypeScript here so Subject can have a different static create signature\n /**\n * Creates a new Observable by calling the Observable constructor\n * @owner Observable\n * @method create\n * @param {Function} subscribe? the subscriber function to be passed to the Observable constructor\n * @return {Observable} a new observable\n * @nocollapse\n * @deprecated Use `new Observable()` instead. Will be removed in v8.\n */\n static create: (...args: any[]) => any = (subscribe?: (subscriber: Subscriber) => TeardownLogic) => {\n return new Observable(subscribe);\n };\n\n /**\n * Creates a new Observable, with this Observable instance as the source, and the passed\n * operator defined as the new observable's operator.\n * @method lift\n * @param operator the operator defining the operation to take on the observable\n * @return a new observable with the Operator applied\n * @deprecated Internal implementation detail, do not use directly. Will be made internal in v8.\n * If you have implemented an operator using `lift`, it is recommended that you create an\n * operator by simply returning `new Observable()` directly. See \"Creating new operators from\n * scratch\" section here: https://rxjs.dev/guide/operators\n */\n lift(operator?: Operator): Observable {\n const observable = new Observable();\n observable.source = this;\n observable.operator = operator;\n return observable;\n }\n\n subscribe(observerOrNext?: Partial> | ((value: T) => void)): Subscription;\n /** @deprecated Instead of passing separate callback arguments, use an observer argument. Signatures taking separate callback arguments will be removed in v8. Details: https://rxjs.dev/deprecations/subscribe-arguments */\n subscribe(next?: ((value: T) => void) | null, error?: ((error: any) => void) | null, complete?: (() => void) | null): Subscription;\n /**\n * Invokes an execution of an Observable and registers Observer handlers for notifications it will emit.\n *\n * Use it when you have all these Observables, but still nothing is happening.\n *\n * `subscribe` is not a regular operator, but a method that calls Observable's internal `subscribe` function. It\n * might be for example a function that you passed to Observable's constructor, but most of the time it is\n * a library implementation, which defines what will be emitted by an Observable, and when it be will emitted. This means\n * that calling `subscribe` is actually the moment when Observable starts its work, not when it is created, as it is often\n * the thought.\n *\n * Apart from starting the execution of an Observable, this method allows you to listen for values\n * that an Observable emits, as well as for when it completes or errors. You can achieve this in two\n * of the following ways.\n *\n * The first way is creating an object that implements {@link Observer} interface. It should have methods\n * defined by that interface, but note that it should be just a regular JavaScript object, which you can create\n * yourself in any way you want (ES6 class, classic function constructor, object literal etc.). In particular, do\n * not attempt to use any RxJS implementation details to create Observers - you don't need them. Remember also\n * that your object does not have to implement all methods. If you find yourself creating a method that doesn't\n * do anything, you can simply omit it. Note however, if the `error` method is not provided and an error happens,\n * it will be thrown asynchronously. Errors thrown asynchronously cannot be caught using `try`/`catch`. Instead,\n * use the {@link onUnhandledError} configuration option or use a runtime handler (like `window.onerror` or\n * `process.on('error)`) to be notified of unhandled errors. Because of this, it's recommended that you provide\n * an `error` method to avoid missing thrown errors.\n *\n * The second way is to give up on Observer object altogether and simply provide callback functions in place of its methods.\n * This means you can provide three functions as arguments to `subscribe`, where the first function is equivalent\n * of a `next` method, the second of an `error` method and the third of a `complete` method. Just as in case of an Observer,\n * if you do not need to listen for something, you can omit a function by passing `undefined` or `null`,\n * since `subscribe` recognizes these functions by where they were placed in function call. When it comes\n * to the `error` function, as with an Observer, if not provided, errors emitted by an Observable will be thrown asynchronously.\n *\n * You can, however, subscribe with no parameters at all. This may be the case where you're not interested in terminal events\n * and you also handled emissions internally by using operators (e.g. using `tap`).\n *\n * Whichever style of calling `subscribe` you use, in both cases it returns a Subscription object.\n * This object allows you to call `unsubscribe` on it, which in turn will stop the work that an Observable does and will clean\n * up all resources that an Observable used. Note that cancelling a subscription will not call `complete` callback\n * provided to `subscribe` function, which is reserved for a regular completion signal that comes from an Observable.\n *\n * Remember that callbacks provided to `subscribe` are not guaranteed to be called asynchronously.\n * It is an Observable itself that decides when these functions will be called. For example {@link of}\n * by default emits all its values synchronously. Always check documentation for how given Observable\n * will behave when subscribed and if its default behavior can be modified with a `scheduler`.\n *\n * #### Examples\n *\n * Subscribe with an {@link guide/observer Observer}\n *\n * ```ts\n * import { of } from 'rxjs';\n *\n * const sumObserver = {\n * sum: 0,\n * next(value) {\n * console.log('Adding: ' + value);\n * this.sum = this.sum + value;\n * },\n * error() {\n * // We actually could just remove this method,\n * // since we do not really care about errors right now.\n * },\n * complete() {\n * console.log('Sum equals: ' + this.sum);\n * }\n * };\n *\n * of(1, 2, 3) // Synchronously emits 1, 2, 3 and then completes.\n * .subscribe(sumObserver);\n *\n * // Logs:\n * // 'Adding: 1'\n * // 'Adding: 2'\n * // 'Adding: 3'\n * // 'Sum equals: 6'\n * ```\n *\n * Subscribe with functions ({@link deprecations/subscribe-arguments deprecated})\n *\n * ```ts\n * import { of } from 'rxjs'\n *\n * let sum = 0;\n *\n * of(1, 2, 3).subscribe(\n * value => {\n * console.log('Adding: ' + value);\n * sum = sum + value;\n * },\n * undefined,\n * () => console.log('Sum equals: ' + sum)\n * );\n *\n * // Logs:\n * // 'Adding: 1'\n * // 'Adding: 2'\n * // 'Adding: 3'\n * // 'Sum equals: 6'\n * ```\n *\n * Cancel a subscription\n *\n * ```ts\n * import { interval } from 'rxjs';\n *\n * const subscription = interval(1000).subscribe({\n * next(num) {\n * console.log(num)\n * },\n * complete() {\n * // Will not be called, even when cancelling subscription.\n * console.log('completed!');\n * }\n * });\n *\n * setTimeout(() => {\n * subscription.unsubscribe();\n * console.log('unsubscribed!');\n * }, 2500);\n *\n * // Logs:\n * // 0 after 1s\n * // 1 after 2s\n * // 'unsubscribed!' after 2.5s\n * ```\n *\n * @param {Observer|Function} observerOrNext (optional) Either an observer with methods to be called,\n * or the first of three possible handlers, which is the handler for each value emitted from the subscribed\n * Observable.\n * @param {Function} error (optional) A handler for a terminal event resulting from an error. If no error handler is provided,\n * the error will be thrown asynchronously as unhandled.\n * @param {Function} complete (optional) A handler for a terminal event resulting from successful completion.\n * @return {Subscription} a subscription reference to the registered handlers\n * @method subscribe\n */\n subscribe(\n observerOrNext?: Partial> | ((value: T) => void) | null,\n error?: ((error: any) => void) | null,\n complete?: (() => void) | null\n ): Subscription {\n const subscriber = isSubscriber(observerOrNext) ? observerOrNext : new SafeSubscriber(observerOrNext, error, complete);\n\n errorContext(() => {\n const { operator, source } = this;\n subscriber.add(\n operator\n ? // We're dealing with a subscription in the\n // operator chain to one of our lifted operators.\n operator.call(subscriber, source)\n : source\n ? // If `source` has a value, but `operator` does not, something that\n // had intimate knowledge of our API, like our `Subject`, must have\n // set it. We're going to just call `_subscribe` directly.\n this._subscribe(subscriber)\n : // In all other cases, we're likely wrapping a user-provided initializer\n // function, so we need to catch errors and handle them appropriately.\n this._trySubscribe(subscriber)\n );\n });\n\n return subscriber;\n }\n\n /** @internal */\n protected _trySubscribe(sink: Subscriber): TeardownLogic {\n try {\n return this._subscribe(sink);\n } catch (err) {\n // We don't need to return anything in this case,\n // because it's just going to try to `add()` to a subscription\n // above.\n sink.error(err);\n }\n }\n\n /**\n * Used as a NON-CANCELLABLE means of subscribing to an observable, for use with\n * APIs that expect promises, like `async/await`. You cannot unsubscribe from this.\n *\n * **WARNING**: Only use this with observables you *know* will complete. If the source\n * observable does not complete, you will end up with a promise that is hung up, and\n * potentially all of the state of an async function hanging out in memory. To avoid\n * this situation, look into adding something like {@link timeout}, {@link take},\n * {@link takeWhile}, or {@link takeUntil} amongst others.\n *\n * #### Example\n *\n * ```ts\n * import { interval, take } from 'rxjs';\n *\n * const source$ = interval(1000).pipe(take(4));\n *\n * async function getTotal() {\n * let total = 0;\n *\n * await source$.forEach(value => {\n * total += value;\n * console.log('observable -> ' + value);\n * });\n *\n * return total;\n * }\n *\n * getTotal().then(\n * total => console.log('Total: ' + total)\n * );\n *\n * // Expected:\n * // 'observable -> 0'\n * // 'observable -> 1'\n * // 'observable -> 2'\n * // 'observable -> 3'\n * // 'Total: 6'\n * ```\n *\n * @param next a handler for each value emitted by the observable\n * @return a promise that either resolves on observable completion or\n * rejects with the handled error\n */\n forEach(next: (value: T) => void): Promise;\n\n /**\n * @param next a handler for each value emitted by the observable\n * @param promiseCtor a constructor function used to instantiate the Promise\n * @return a promise that either resolves on observable completion or\n * rejects with the handled error\n * @deprecated Passing a Promise constructor will no longer be available\n * in upcoming versions of RxJS. This is because it adds weight to the library, for very\n * little benefit. If you need this functionality, it is recommended that you either\n * polyfill Promise, or you create an adapter to convert the returned native promise\n * to whatever promise implementation you wanted. Will be removed in v8.\n */\n forEach(next: (value: T) => void, promiseCtor: PromiseConstructorLike): Promise;\n\n forEach(next: (value: T) => void, promiseCtor?: PromiseConstructorLike): Promise {\n promiseCtor = getPromiseCtor(promiseCtor);\n\n return new promiseCtor((resolve, reject) => {\n const subscriber = new SafeSubscriber({\n next: (value) => {\n try {\n next(value);\n } catch (err) {\n reject(err);\n subscriber.unsubscribe();\n }\n },\n error: reject,\n complete: resolve,\n });\n this.subscribe(subscriber);\n }) as Promise;\n }\n\n /** @internal */\n protected _subscribe(subscriber: Subscriber): TeardownLogic {\n return this.source?.subscribe(subscriber);\n }\n\n /**\n * An interop point defined by the es7-observable spec https://github.com/zenparsing/es-observable\n * @method Symbol.observable\n * @return {Observable} this instance of the observable\n */\n [Symbol_observable]() {\n return this;\n }\n\n /* tslint:disable:max-line-length */\n pipe(): Observable;\n pipe(op1: OperatorFunction): Observable;\n pipe(op1: OperatorFunction, op2: OperatorFunction): Observable;\n pipe(op1: OperatorFunction, op2: OperatorFunction, op3: OperatorFunction): Observable;\n pipe(\n op1: OperatorFunction,\n op2: OperatorFunction,\n op3: OperatorFunction,\n op4: OperatorFunction\n ): Observable;\n pipe(\n op1: OperatorFunction,\n op2: OperatorFunction,\n op3: OperatorFunction,\n op4: OperatorFunction,\n op5: OperatorFunction\n ): Observable;\n pipe(\n op1: OperatorFunction,\n op2: OperatorFunction,\n op3: OperatorFunction,\n op4: OperatorFunction,\n op5: OperatorFunction,\n op6: OperatorFunction\n ): Observable;\n pipe(\n op1: OperatorFunction,\n op2: OperatorFunction,\n op3: OperatorFunction,\n op4: OperatorFunction,\n op5: OperatorFunction,\n op6: OperatorFunction,\n op7: OperatorFunction\n ): Observable;\n pipe(\n op1: OperatorFunction,\n op2: OperatorFunction,\n op3: OperatorFunction,\n op4: OperatorFunction,\n op5: OperatorFunction,\n op6: OperatorFunction,\n op7: OperatorFunction,\n op8: OperatorFunction\n ): Observable;\n pipe(\n op1: OperatorFunction,\n op2: OperatorFunction,\n op3: OperatorFunction,\n op4: OperatorFunction,\n op5: OperatorFunction,\n op6: OperatorFunction,\n op7: OperatorFunction,\n op8: OperatorFunction,\n op9: OperatorFunction\n ): Observable;\n pipe(\n op1: OperatorFunction,\n op2: OperatorFunction,\n op3: OperatorFunction,\n op4: OperatorFunction,\n op5: OperatorFunction,\n op6: OperatorFunction,\n op7: OperatorFunction,\n op8: OperatorFunction,\n op9: OperatorFunction,\n ...operations: OperatorFunction[]\n ): Observable;\n /* tslint:enable:max-line-length */\n\n /**\n * Used to stitch together functional operators into a chain.\n * @method pipe\n * @return {Observable} the Observable result of all of the operators having\n * been called in the order they were passed in.\n *\n * ## Example\n *\n * ```ts\n * import { interval, filter, map, scan } from 'rxjs';\n *\n * interval(1000)\n * .pipe(\n * filter(x => x % 2 === 0),\n * map(x => x + x),\n * scan((acc, x) => acc + x)\n * )\n * .subscribe(x => console.log(x));\n * ```\n */\n pipe(...operations: OperatorFunction[]): Observable {\n return pipeFromArray(operations)(this);\n }\n\n /* tslint:disable:max-line-length */\n /** @deprecated Replaced with {@link firstValueFrom} and {@link lastValueFrom}. Will be removed in v8. Details: https://rxjs.dev/deprecations/to-promise */\n toPromise(): Promise;\n /** @deprecated Replaced with {@link firstValueFrom} and {@link lastValueFrom}. Will be removed in v8. Details: https://rxjs.dev/deprecations/to-promise */\n toPromise(PromiseCtor: typeof Promise): Promise;\n /** @deprecated Replaced with {@link firstValueFrom} and {@link lastValueFrom}. Will be removed in v8. Details: https://rxjs.dev/deprecations/to-promise */\n toPromise(PromiseCtor: PromiseConstructorLike): Promise;\n /* tslint:enable:max-line-length */\n\n /**\n * Subscribe to this Observable and get a Promise resolving on\n * `complete` with the last emission (if any).\n *\n * **WARNING**: Only use this with observables you *know* will complete. If the source\n * observable does not complete, you will end up with a promise that is hung up, and\n * potentially all of the state of an async function hanging out in memory. To avoid\n * this situation, look into adding something like {@link timeout}, {@link take},\n * {@link takeWhile}, or {@link takeUntil} amongst others.\n *\n * @method toPromise\n * @param [promiseCtor] a constructor function used to instantiate\n * the Promise\n * @return A Promise that resolves with the last value emit, or\n * rejects on an error. If there were no emissions, Promise\n * resolves with undefined.\n * @deprecated Replaced with {@link firstValueFrom} and {@link lastValueFrom}. Will be removed in v8. Details: https://rxjs.dev/deprecations/to-promise\n */\n toPromise(promiseCtor?: PromiseConstructorLike): Promise {\n promiseCtor = getPromiseCtor(promiseCtor);\n\n return new promiseCtor((resolve, reject) => {\n let value: T | undefined;\n this.subscribe(\n (x: T) => (value = x),\n (err: any) => reject(err),\n () => resolve(value)\n );\n }) as Promise;\n }\n}\n\n/**\n * Decides between a passed promise constructor from consuming code,\n * A default configured promise constructor, and the native promise\n * constructor and returns it. If nothing can be found, it will throw\n * an error.\n * @param promiseCtor The optional promise constructor to passed by consuming code\n */\nfunction getPromiseCtor(promiseCtor: PromiseConstructorLike | undefined) {\n return promiseCtor ?? config.Promise ?? Promise;\n}\n\nfunction isObserver(value: any): value is Observer {\n return value && isFunction(value.next) && isFunction(value.error) && isFunction(value.complete);\n}\n\nfunction isSubscriber(value: any): value is Subscriber {\n return (value && value instanceof Subscriber) || (isObserver(value) && isSubscription(value));\n}\n", "import { Observable } from '../Observable';\nimport { Subscriber } from '../Subscriber';\nimport { OperatorFunction } from '../types';\nimport { isFunction } from './isFunction';\n\n/**\n * Used to determine if an object is an Observable with a lift function.\n */\nexport function hasLift(source: any): source is { lift: InstanceType['lift'] } {\n return isFunction(source?.lift);\n}\n\n/**\n * Creates an `OperatorFunction`. Used to define operators throughout the library in a concise way.\n * @param init The logic to connect the liftedSource to the subscriber at the moment of subscription.\n */\nexport function operate(\n init: (liftedSource: Observable, subscriber: Subscriber) => (() => void) | void\n): OperatorFunction {\n return (source: Observable) => {\n if (hasLift(source)) {\n return source.lift(function (this: Subscriber, liftedSource: Observable) {\n try {\n return init(liftedSource, this);\n } catch (err) {\n this.error(err);\n }\n });\n }\n throw new TypeError('Unable to lift unknown Observable type');\n };\n}\n", "import { Subscriber } from '../Subscriber';\n\n/**\n * Creates an instance of an `OperatorSubscriber`.\n * @param destination The downstream subscriber.\n * @param onNext Handles next values, only called if this subscriber is not stopped or closed. Any\n * error that occurs in this function is caught and sent to the `error` method of this subscriber.\n * @param onError Handles errors from the subscription, any errors that occur in this handler are caught\n * and send to the `destination` error handler.\n * @param onComplete Handles completion notification from the subscription. Any errors that occur in\n * this handler are sent to the `destination` error handler.\n * @param onFinalize Additional teardown logic here. This will only be called on teardown if the\n * subscriber itself is not already closed. This is called after all other teardown logic is executed.\n */\nexport function createOperatorSubscriber(\n destination: Subscriber,\n onNext?: (value: T) => void,\n onComplete?: () => void,\n onError?: (err: any) => void,\n onFinalize?: () => void\n): Subscriber {\n return new OperatorSubscriber(destination, onNext, onComplete, onError, onFinalize);\n}\n\n/**\n * A generic helper for allowing operators to be created with a Subscriber and\n * use closures to capture necessary state from the operator function itself.\n */\nexport class OperatorSubscriber extends Subscriber {\n /**\n * Creates an instance of an `OperatorSubscriber`.\n * @param destination The downstream subscriber.\n * @param onNext Handles next values, only called if this subscriber is not stopped or closed. Any\n * error that occurs in this function is caught and sent to the `error` method of this subscriber.\n * @param onError Handles errors from the subscription, any errors that occur in this handler are caught\n * and send to the `destination` error handler.\n * @param onComplete Handles completion notification from the subscription. Any errors that occur in\n * this handler are sent to the `destination` error handler.\n * @param onFinalize Additional finalization logic here. This will only be called on finalization if the\n * subscriber itself is not already closed. This is called after all other finalization logic is executed.\n * @param shouldUnsubscribe An optional check to see if an unsubscribe call should truly unsubscribe.\n * NOTE: This currently **ONLY** exists to support the strange behavior of {@link groupBy}, where unsubscription\n * to the resulting observable does not actually disconnect from the source if there are active subscriptions\n * to any grouped observable. (DO NOT EXPOSE OR USE EXTERNALLY!!!)\n */\n constructor(\n destination: Subscriber,\n onNext?: (value: T) => void,\n onComplete?: () => void,\n onError?: (err: any) => void,\n private onFinalize?: () => void,\n private shouldUnsubscribe?: () => boolean\n ) {\n // It's important - for performance reasons - that all of this class's\n // members are initialized and that they are always initialized in the same\n // order. This will ensure that all OperatorSubscriber instances have the\n // same hidden class in V8. This, in turn, will help keep the number of\n // hidden classes involved in property accesses within the base class as\n // low as possible. If the number of hidden classes involved exceeds four,\n // the property accesses will become megamorphic and performance penalties\n // will be incurred - i.e. inline caches won't be used.\n //\n // The reasons for ensuring all instances have the same hidden class are\n // further discussed in this blog post from Benedikt Meurer:\n // https://benediktmeurer.de/2018/03/23/impact-of-polymorphism-on-component-based-frameworks-like-react/\n super(destination);\n this._next = onNext\n ? function (this: OperatorSubscriber, value: T) {\n try {\n onNext(value);\n } catch (err) {\n destination.error(err);\n }\n }\n : super._next;\n this._error = onError\n ? function (this: OperatorSubscriber, err: any) {\n try {\n onError(err);\n } catch (err) {\n // Send any errors that occur down stream.\n destination.error(err);\n } finally {\n // Ensure finalization.\n this.unsubscribe();\n }\n }\n : super._error;\n this._complete = onComplete\n ? function (this: OperatorSubscriber) {\n try {\n onComplete();\n } catch (err) {\n // Send any errors that occur down stream.\n destination.error(err);\n } finally {\n // Ensure finalization.\n this.unsubscribe();\n }\n }\n : super._complete;\n }\n\n unsubscribe() {\n if (!this.shouldUnsubscribe || this.shouldUnsubscribe()) {\n const { closed } = this;\n super.unsubscribe();\n // Execute additional teardown if we have any and we didn't already do so.\n !closed && this.onFinalize?.();\n }\n }\n}\n", "import { Subscription } from '../Subscription';\n\ninterface AnimationFrameProvider {\n schedule(callback: FrameRequestCallback): Subscription;\n requestAnimationFrame: typeof requestAnimationFrame;\n cancelAnimationFrame: typeof cancelAnimationFrame;\n delegate:\n | {\n requestAnimationFrame: typeof requestAnimationFrame;\n cancelAnimationFrame: typeof cancelAnimationFrame;\n }\n | undefined;\n}\n\nexport const animationFrameProvider: AnimationFrameProvider = {\n // When accessing the delegate, use the variable rather than `this` so that\n // the functions can be called without being bound to the provider.\n schedule(callback) {\n let request = requestAnimationFrame;\n let cancel: typeof cancelAnimationFrame | undefined = cancelAnimationFrame;\n const { delegate } = animationFrameProvider;\n if (delegate) {\n request = delegate.requestAnimationFrame;\n cancel = delegate.cancelAnimationFrame;\n }\n const handle = request((timestamp) => {\n // Clear the cancel function. The request has been fulfilled, so\n // attempting to cancel the request upon unsubscription would be\n // pointless.\n cancel = undefined;\n callback(timestamp);\n });\n return new Subscription(() => cancel?.(handle));\n },\n requestAnimationFrame(...args) {\n const { delegate } = animationFrameProvider;\n return (delegate?.requestAnimationFrame || requestAnimationFrame)(...args);\n },\n cancelAnimationFrame(...args) {\n const { delegate } = animationFrameProvider;\n return (delegate?.cancelAnimationFrame || cancelAnimationFrame)(...args);\n },\n delegate: undefined,\n};\n", "import { createErrorClass } from './createErrorClass';\n\nexport interface ObjectUnsubscribedError extends Error {}\n\nexport interface ObjectUnsubscribedErrorCtor {\n /**\n * @deprecated Internal implementation detail. Do not construct error instances.\n * Cannot be tagged as internal: https://github.com/ReactiveX/rxjs/issues/6269\n */\n new (): ObjectUnsubscribedError;\n}\n\n/**\n * An error thrown when an action is invalid because the object has been\n * unsubscribed.\n *\n * @see {@link Subject}\n * @see {@link BehaviorSubject}\n *\n * @class ObjectUnsubscribedError\n */\nexport const ObjectUnsubscribedError: ObjectUnsubscribedErrorCtor = createErrorClass(\n (_super) =>\n function ObjectUnsubscribedErrorImpl(this: any) {\n _super(this);\n this.name = 'ObjectUnsubscribedError';\n this.message = 'object unsubscribed';\n }\n);\n", "import { Operator } from './Operator';\nimport { Observable } from './Observable';\nimport { Subscriber } from './Subscriber';\nimport { Subscription, EMPTY_SUBSCRIPTION } from './Subscription';\nimport { Observer, SubscriptionLike, TeardownLogic } from './types';\nimport { ObjectUnsubscribedError } from './util/ObjectUnsubscribedError';\nimport { arrRemove } from './util/arrRemove';\nimport { errorContext } from './util/errorContext';\n\n/**\n * A Subject is a special type of Observable that allows values to be\n * multicasted to many Observers. Subjects are like EventEmitters.\n *\n * Every Subject is an Observable and an Observer. You can subscribe to a\n * Subject, and you can call next to feed values as well as error and complete.\n */\nexport class Subject extends Observable implements SubscriptionLike {\n closed = false;\n\n private currentObservers: Observer[] | null = null;\n\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n observers: Observer[] = [];\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n isStopped = false;\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n hasError = false;\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n thrownError: any = null;\n\n /**\n * Creates a \"subject\" by basically gluing an observer to an observable.\n *\n * @nocollapse\n * @deprecated Recommended you do not use. Will be removed at some point in the future. Plans for replacement still under discussion.\n */\n static create: (...args: any[]) => any = (destination: Observer, source: Observable): AnonymousSubject => {\n return new AnonymousSubject(destination, source);\n };\n\n constructor() {\n // NOTE: This must be here to obscure Observable's constructor.\n super();\n }\n\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n lift(operator: Operator): Observable {\n const subject = new AnonymousSubject(this, this);\n subject.operator = operator as any;\n return subject as any;\n }\n\n /** @internal */\n protected _throwIfClosed() {\n if (this.closed) {\n throw new ObjectUnsubscribedError();\n }\n }\n\n next(value: T) {\n errorContext(() => {\n this._throwIfClosed();\n if (!this.isStopped) {\n if (!this.currentObservers) {\n this.currentObservers = Array.from(this.observers);\n }\n for (const observer of this.currentObservers) {\n observer.next(value);\n }\n }\n });\n }\n\n error(err: any) {\n errorContext(() => {\n this._throwIfClosed();\n if (!this.isStopped) {\n this.hasError = this.isStopped = true;\n this.thrownError = err;\n const { observers } = this;\n while (observers.length) {\n observers.shift()!.error(err);\n }\n }\n });\n }\n\n complete() {\n errorContext(() => {\n this._throwIfClosed();\n if (!this.isStopped) {\n this.isStopped = true;\n const { observers } = this;\n while (observers.length) {\n observers.shift()!.complete();\n }\n }\n });\n }\n\n unsubscribe() {\n this.isStopped = this.closed = true;\n this.observers = this.currentObservers = null!;\n }\n\n get observed() {\n return this.observers?.length > 0;\n }\n\n /** @internal */\n protected _trySubscribe(subscriber: Subscriber): TeardownLogic {\n this._throwIfClosed();\n return super._trySubscribe(subscriber);\n }\n\n /** @internal */\n protected _subscribe(subscriber: Subscriber): Subscription {\n this._throwIfClosed();\n this._checkFinalizedStatuses(subscriber);\n return this._innerSubscribe(subscriber);\n }\n\n /** @internal */\n protected _innerSubscribe(subscriber: Subscriber) {\n const { hasError, isStopped, observers } = this;\n if (hasError || isStopped) {\n return EMPTY_SUBSCRIPTION;\n }\n this.currentObservers = null;\n observers.push(subscriber);\n return new Subscription(() => {\n this.currentObservers = null;\n arrRemove(observers, subscriber);\n });\n }\n\n /** @internal */\n protected _checkFinalizedStatuses(subscriber: Subscriber) {\n const { hasError, thrownError, isStopped } = this;\n if (hasError) {\n subscriber.error(thrownError);\n } else if (isStopped) {\n subscriber.complete();\n }\n }\n\n /**\n * Creates a new Observable with this Subject as the source. You can do this\n * to create custom Observer-side logic of the Subject and conceal it from\n * code that uses the Observable.\n * @return {Observable} Observable that the Subject casts to\n */\n asObservable(): Observable {\n const observable: any = new Observable();\n observable.source = this;\n return observable;\n }\n}\n\n/**\n * @class AnonymousSubject\n */\nexport class AnonymousSubject extends Subject {\n constructor(\n /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */\n public destination?: Observer,\n source?: Observable\n ) {\n super();\n this.source = source;\n }\n\n next(value: T) {\n this.destination?.next?.(value);\n }\n\n error(err: any) {\n this.destination?.error?.(err);\n }\n\n complete() {\n this.destination?.complete?.();\n }\n\n /** @internal */\n protected _subscribe(subscriber: Subscriber): Subscription {\n return this.source?.subscribe(subscriber) ?? EMPTY_SUBSCRIPTION;\n }\n}\n", "import { Subject } from './Subject';\nimport { Subscriber } from './Subscriber';\nimport { Subscription } from './Subscription';\n\n/**\n * A variant of Subject that requires an initial value and emits its current\n * value whenever it is subscribed to.\n *\n * @class BehaviorSubject\n */\nexport class BehaviorSubject extends Subject {\n constructor(private _value: T) {\n super();\n }\n\n get value(): T {\n return this.getValue();\n }\n\n /** @internal */\n protected _subscribe(subscriber: Subscriber): Subscription {\n const subscription = super._subscribe(subscriber);\n !subscription.closed && subscriber.next(this._value);\n return subscription;\n }\n\n getValue(): T {\n const { hasError, thrownError, _value } = this;\n if (hasError) {\n throw thrownError;\n }\n this._throwIfClosed();\n return _value;\n }\n\n next(value: T): void {\n super.next((this._value = value));\n }\n}\n", "import { TimestampProvider } from '../types';\n\ninterface DateTimestampProvider extends TimestampProvider {\n delegate: TimestampProvider | undefined;\n}\n\nexport const dateTimestampProvider: DateTimestampProvider = {\n now() {\n // Use the variable rather than `this` so that the function can be called\n // without being bound to the provider.\n return (dateTimestampProvider.delegate || Date).now();\n },\n delegate: undefined,\n};\n", "import { Subject } from './Subject';\nimport { TimestampProvider } from './types';\nimport { Subscriber } from './Subscriber';\nimport { Subscription } from './Subscription';\nimport { dateTimestampProvider } from './scheduler/dateTimestampProvider';\n\n/**\n * A variant of {@link Subject} that \"replays\" old values to new subscribers by emitting them when they first subscribe.\n *\n * `ReplaySubject` has an internal buffer that will store a specified number of values that it has observed. Like `Subject`,\n * `ReplaySubject` \"observes\" values by having them passed to its `next` method. When it observes a value, it will store that\n * value for a time determined by the configuration of the `ReplaySubject`, as passed to its constructor.\n *\n * When a new subscriber subscribes to the `ReplaySubject` instance, it will synchronously emit all values in its buffer in\n * a First-In-First-Out (FIFO) manner. The `ReplaySubject` will also complete, if it has observed completion; and it will\n * error if it has observed an error.\n *\n * There are two main configuration items to be concerned with:\n *\n * 1. `bufferSize` - This will determine how many items are stored in the buffer, defaults to infinite.\n * 2. `windowTime` - The amount of time to hold a value in the buffer before removing it from the buffer.\n *\n * Both configurations may exist simultaneously. So if you would like to buffer a maximum of 3 values, as long as the values\n * are less than 2 seconds old, you could do so with a `new ReplaySubject(3, 2000)`.\n *\n * ### Differences with BehaviorSubject\n *\n * `BehaviorSubject` is similar to `new ReplaySubject(1)`, with a couple of exceptions:\n *\n * 1. `BehaviorSubject` comes \"primed\" with a single value upon construction.\n * 2. `ReplaySubject` will replay values, even after observing an error, where `BehaviorSubject` will not.\n *\n * @see {@link Subject}\n * @see {@link BehaviorSubject}\n * @see {@link shareReplay}\n */\nexport class ReplaySubject extends Subject {\n private _buffer: (T | number)[] = [];\n private _infiniteTimeWindow = true;\n\n /**\n * @param bufferSize The size of the buffer to replay on subscription\n * @param windowTime The amount of time the buffered items will stay buffered\n * @param timestampProvider An object with a `now()` method that provides the current timestamp. This is used to\n * calculate the amount of time something has been buffered.\n */\n constructor(\n private _bufferSize = Infinity,\n private _windowTime = Infinity,\n private _timestampProvider: TimestampProvider = dateTimestampProvider\n ) {\n super();\n this._infiniteTimeWindow = _windowTime === Infinity;\n this._bufferSize = Math.max(1, _bufferSize);\n this._windowTime = Math.max(1, _windowTime);\n }\n\n next(value: T): void {\n const { isStopped, _buffer, _infiniteTimeWindow, _timestampProvider, _windowTime } = this;\n if (!isStopped) {\n _buffer.push(value);\n !_infiniteTimeWindow && _buffer.push(_timestampProvider.now() + _windowTime);\n }\n this._trimBuffer();\n super.next(value);\n }\n\n /** @internal */\n protected _subscribe(subscriber: Subscriber): Subscription {\n this._throwIfClosed();\n this._trimBuffer();\n\n const subscription = this._innerSubscribe(subscriber);\n\n const { _infiniteTimeWindow, _buffer } = this;\n // We use a copy here, so reentrant code does not mutate our array while we're\n // emitting it to a new subscriber.\n const copy = _buffer.slice();\n for (let i = 0; i < copy.length && !subscriber.closed; i += _infiniteTimeWindow ? 1 : 2) {\n subscriber.next(copy[i] as T);\n }\n\n this._checkFinalizedStatuses(subscriber);\n\n return subscription;\n }\n\n private _trimBuffer() {\n const { _bufferSize, _timestampProvider, _buffer, _infiniteTimeWindow } = this;\n // If we don't have an infinite buffer size, and we're over the length,\n // use splice to truncate the old buffer values off. Note that we have to\n // double the size for instances where we're not using an infinite time window\n // because we're storing the values and the timestamps in the same array.\n const adjustedBufferSize = (_infiniteTimeWindow ? 1 : 2) * _bufferSize;\n _bufferSize < Infinity && adjustedBufferSize < _buffer.length && _buffer.splice(0, _buffer.length - adjustedBufferSize);\n\n // Now, if we're not in an infinite time window, remove all values where the time is\n // older than what is allowed.\n if (!_infiniteTimeWindow) {\n const now = _timestampProvider.now();\n let last = 0;\n // Search the array for the first timestamp that isn't expired and\n // truncate the buffer up to that point.\n for (let i = 1; i < _buffer.length && (_buffer[i] as number) <= now; i += 2) {\n last = i;\n }\n last && _buffer.splice(0, last + 1);\n }\n }\n}\n", "import { Scheduler } from '../Scheduler';\nimport { Subscription } from '../Subscription';\nimport { SchedulerAction } from '../types';\n\n/**\n * A unit of work to be executed in a `scheduler`. An action is typically\n * created from within a {@link SchedulerLike} and an RxJS user does not need to concern\n * themselves about creating and manipulating an Action.\n *\n * ```ts\n * class Action extends Subscription {\n * new (scheduler: Scheduler, work: (state?: T) => void);\n * schedule(state?: T, delay: number = 0): Subscription;\n * }\n * ```\n *\n * @class Action\n */\nexport class Action extends Subscription {\n constructor(scheduler: Scheduler, work: (this: SchedulerAction, state?: T) => void) {\n super();\n }\n /**\n * Schedules this action on its parent {@link SchedulerLike} for execution. May be passed\n * some context object, `state`. May happen at some point in the future,\n * according to the `delay` parameter, if specified.\n * @param {T} [state] Some contextual data that the `work` function uses when\n * called by the Scheduler.\n * @param {number} [delay] Time to wait before executing the work, where the\n * time unit is implicit and defined by the Scheduler.\n * @return {void}\n */\n public schedule(state?: T, delay: number = 0): Subscription {\n return this;\n }\n}\n", "import type { TimerHandle } from './timerHandle';\ntype SetIntervalFunction = (handler: () => void, timeout?: number, ...args: any[]) => TimerHandle;\ntype ClearIntervalFunction = (handle: TimerHandle) => void;\n\ninterface IntervalProvider {\n setInterval: SetIntervalFunction;\n clearInterval: ClearIntervalFunction;\n delegate:\n | {\n setInterval: SetIntervalFunction;\n clearInterval: ClearIntervalFunction;\n }\n | undefined;\n}\n\nexport const intervalProvider: IntervalProvider = {\n // When accessing the delegate, use the variable rather than `this` so that\n // the functions can be called without being bound to the provider.\n setInterval(handler: () => void, timeout?: number, ...args) {\n const { delegate } = intervalProvider;\n if (delegate?.setInterval) {\n return delegate.setInterval(handler, timeout, ...args);\n }\n return setInterval(handler, timeout, ...args);\n },\n clearInterval(handle) {\n const { delegate } = intervalProvider;\n return (delegate?.clearInterval || clearInterval)(handle as any);\n },\n delegate: undefined,\n};\n", "import { Action } from './Action';\nimport { SchedulerAction } from '../types';\nimport { Subscription } from '../Subscription';\nimport { AsyncScheduler } from './AsyncScheduler';\nimport { intervalProvider } from './intervalProvider';\nimport { arrRemove } from '../util/arrRemove';\nimport { TimerHandle } from './timerHandle';\n\nexport class AsyncAction extends Action {\n public id: TimerHandle | undefined;\n public state?: T;\n // @ts-ignore: Property has no initializer and is not definitely assigned\n public delay: number;\n protected pending: boolean = false;\n\n constructor(protected scheduler: AsyncScheduler, protected work: (this: SchedulerAction, state?: T) => void) {\n super(scheduler, work);\n }\n\n public schedule(state?: T, delay: number = 0): Subscription {\n if (this.closed) {\n return this;\n }\n\n // Always replace the current state with the new state.\n this.state = state;\n\n const id = this.id;\n const scheduler = this.scheduler;\n\n //\n // Important implementation note:\n //\n // Actions only execute once by default, unless rescheduled from within the\n // scheduled callback. This allows us to implement single and repeat\n // actions via the same code path, without adding API surface area, as well\n // as mimic traditional recursion but across asynchronous boundaries.\n //\n // However, JS runtimes and timers distinguish between intervals achieved by\n // serial `setTimeout` calls vs. a single `setInterval` call. An interval of\n // serial `setTimeout` calls can be individually delayed, which delays\n // scheduling the next `setTimeout`, and so on. `setInterval` attempts to\n // guarantee the interval callback will be invoked more precisely to the\n // interval period, regardless of load.\n //\n // Therefore, we use `setInterval` to schedule single and repeat actions.\n // If the action reschedules itself with the same delay, the interval is not\n // canceled. If the action doesn't reschedule, or reschedules with a\n // different delay, the interval will be canceled after scheduled callback\n // execution.\n //\n if (id != null) {\n this.id = this.recycleAsyncId(scheduler, id, delay);\n }\n\n // Set the pending flag indicating that this action has been scheduled, or\n // has recursively rescheduled itself.\n this.pending = true;\n\n this.delay = delay;\n // If this action has already an async Id, don't request a new one.\n this.id = this.id ?? this.requestAsyncId(scheduler, this.id, delay);\n\n return this;\n }\n\n protected requestAsyncId(scheduler: AsyncScheduler, _id?: TimerHandle, delay: number = 0): TimerHandle {\n return intervalProvider.setInterval(scheduler.flush.bind(scheduler, this), delay);\n }\n\n protected recycleAsyncId(_scheduler: AsyncScheduler, id?: TimerHandle, delay: number | null = 0): TimerHandle | undefined {\n // If this action is rescheduled with the same delay time, don't clear the interval id.\n if (delay != null && this.delay === delay && this.pending === false) {\n return id;\n }\n // Otherwise, if the action's delay time is different from the current delay,\n // or the action has been rescheduled before it's executed, clear the interval id\n if (id != null) {\n intervalProvider.clearInterval(id);\n }\n\n return undefined;\n }\n\n /**\n * Immediately executes this action and the `work` it contains.\n * @return {any}\n */\n public execute(state: T, delay: number): any {\n if (this.closed) {\n return new Error('executing a cancelled action');\n }\n\n this.pending = false;\n const error = this._execute(state, delay);\n if (error) {\n return error;\n } else if (this.pending === false && this.id != null) {\n // Dequeue if the action didn't reschedule itself. Don't call\n // unsubscribe(), because the action could reschedule later.\n // For example:\n // ```\n // scheduler.schedule(function doWork(counter) {\n // /* ... I'm a busy worker bee ... */\n // var originalAction = this;\n // /* wait 100ms before rescheduling the action */\n // setTimeout(function () {\n // originalAction.schedule(counter + 1);\n // }, 100);\n // }, 1000);\n // ```\n this.id = this.recycleAsyncId(this.scheduler, this.id, null);\n }\n }\n\n protected _execute(state: T, _delay: number): any {\n let errored: boolean = false;\n let errorValue: any;\n try {\n this.work(state);\n } catch (e) {\n errored = true;\n // HACK: Since code elsewhere is relying on the \"truthiness\" of the\n // return here, we can't have it return \"\" or 0 or false.\n // TODO: Clean this up when we refactor schedulers mid-version-8 or so.\n errorValue = e ? e : new Error('Scheduled action threw falsy error');\n }\n if (errored) {\n this.unsubscribe();\n return errorValue;\n }\n }\n\n unsubscribe() {\n if (!this.closed) {\n const { id, scheduler } = this;\n const { actions } = scheduler;\n\n this.work = this.state = this.scheduler = null!;\n this.pending = false;\n\n arrRemove(actions, this);\n if (id != null) {\n this.id = this.recycleAsyncId(scheduler, id, null);\n }\n\n this.delay = null!;\n super.unsubscribe();\n }\n }\n}\n", "import { Action } from './scheduler/Action';\nimport { Subscription } from './Subscription';\nimport { SchedulerLike, SchedulerAction } from './types';\nimport { dateTimestampProvider } from './scheduler/dateTimestampProvider';\n\n/**\n * An execution context and a data structure to order tasks and schedule their\n * execution. Provides a notion of (potentially virtual) time, through the\n * `now()` getter method.\n *\n * Each unit of work in a Scheduler is called an `Action`.\n *\n * ```ts\n * class Scheduler {\n * now(): number;\n * schedule(work, delay?, state?): Subscription;\n * }\n * ```\n *\n * @class Scheduler\n * @deprecated Scheduler is an internal implementation detail of RxJS, and\n * should not be used directly. Rather, create your own class and implement\n * {@link SchedulerLike}. Will be made internal in v8.\n */\nexport class Scheduler implements SchedulerLike {\n public static now: () => number = dateTimestampProvider.now;\n\n constructor(private schedulerActionCtor: typeof Action, now: () => number = Scheduler.now) {\n this.now = now;\n }\n\n /**\n * A getter method that returns a number representing the current time\n * (at the time this function was called) according to the scheduler's own\n * internal clock.\n * @return {number} A number that represents the current time. May or may not\n * have a relation to wall-clock time. May or may not refer to a time unit\n * (e.g. milliseconds).\n */\n public now: () => number;\n\n /**\n * Schedules a function, `work`, for execution. May happen at some point in\n * the future, according to the `delay` parameter, if specified. May be passed\n * some context object, `state`, which will be passed to the `work` function.\n *\n * The given arguments will be processed an stored as an Action object in a\n * queue of actions.\n *\n * @param {function(state: ?T): ?Subscription} work A function representing a\n * task, or some unit of work to be executed by the Scheduler.\n * @param {number} [delay] Time to wait before executing the work, where the\n * time unit is implicit and defined by the Scheduler itself.\n * @param {T} [state] Some contextual data that the `work` function uses when\n * called by the Scheduler.\n * @return {Subscription} A subscription in order to be able to unsubscribe\n * the scheduled work.\n */\n public schedule(work: (this: SchedulerAction, state?: T) => void, delay: number = 0, state?: T): Subscription {\n return new this.schedulerActionCtor(this, work).schedule(state, delay);\n }\n}\n", "import { Scheduler } from '../Scheduler';\nimport { Action } from './Action';\nimport { AsyncAction } from './AsyncAction';\nimport { TimerHandle } from './timerHandle';\n\nexport class AsyncScheduler extends Scheduler {\n public actions: Array> = [];\n /**\n * A flag to indicate whether the Scheduler is currently executing a batch of\n * queued actions.\n * @type {boolean}\n * @internal\n */\n public _active: boolean = false;\n /**\n * An internal ID used to track the latest asynchronous task such as those\n * coming from `setTimeout`, `setInterval`, `requestAnimationFrame`, and\n * others.\n * @type {any}\n * @internal\n */\n public _scheduled: TimerHandle | undefined;\n\n constructor(SchedulerAction: typeof Action, now: () => number = Scheduler.now) {\n super(SchedulerAction, now);\n }\n\n public flush(action: AsyncAction): void {\n const { actions } = this;\n\n if (this._active) {\n actions.push(action);\n return;\n }\n\n let error: any;\n this._active = true;\n\n do {\n if ((error = action.execute(action.state, action.delay))) {\n break;\n }\n } while ((action = actions.shift()!)); // exhaust the scheduler queue\n\n this._active = false;\n\n if (error) {\n while ((action = actions.shift()!)) {\n action.unsubscribe();\n }\n throw error;\n }\n }\n}\n", "import { AsyncAction } from './AsyncAction';\nimport { AsyncScheduler } from './AsyncScheduler';\n\n/**\n *\n * Async Scheduler\n *\n * Schedule task as if you used setTimeout(task, duration)\n *\n * `async` scheduler schedules tasks asynchronously, by putting them on the JavaScript\n * event loop queue. It is best used to delay tasks in time or to schedule tasks repeating\n * in intervals.\n *\n * If you just want to \"defer\" task, that is to perform it right after currently\n * executing synchronous code ends (commonly achieved by `setTimeout(deferredTask, 0)`),\n * better choice will be the {@link asapScheduler} scheduler.\n *\n * ## Examples\n * Use async scheduler to delay task\n * ```ts\n * import { asyncScheduler } from 'rxjs';\n *\n * const task = () => console.log('it works!');\n *\n * asyncScheduler.schedule(task, 2000);\n *\n * // After 2 seconds logs:\n * // \"it works!\"\n * ```\n *\n * Use async scheduler to repeat task in intervals\n * ```ts\n * import { asyncScheduler } from 'rxjs';\n *\n * function task(state) {\n * console.log(state);\n * this.schedule(state + 1, 1000); // `this` references currently executing Action,\n * // which we reschedule with new state and delay\n * }\n *\n * asyncScheduler.schedule(task, 3000, 0);\n *\n * // Logs:\n * // 0 after 3s\n * // 1 after 4s\n * // 2 after 5s\n * // 3 after 6s\n * ```\n */\n\nexport const asyncScheduler = new AsyncScheduler(AsyncAction);\n\n/**\n * @deprecated Renamed to {@link asyncScheduler}. Will be removed in v8.\n */\nexport const async = asyncScheduler;\n", "import { AsyncAction } from './AsyncAction';\nimport { Subscription } from '../Subscription';\nimport { QueueScheduler } from './QueueScheduler';\nimport { SchedulerAction } from '../types';\nimport { TimerHandle } from './timerHandle';\n\nexport class QueueAction extends AsyncAction {\n constructor(protected scheduler: QueueScheduler, protected work: (this: SchedulerAction, state?: T) => void) {\n super(scheduler, work);\n }\n\n public schedule(state?: T, delay: number = 0): Subscription {\n if (delay > 0) {\n return super.schedule(state, delay);\n }\n this.delay = delay;\n this.state = state;\n this.scheduler.flush(this);\n return this;\n }\n\n public execute(state: T, delay: number): any {\n return delay > 0 || this.closed ? super.execute(state, delay) : this._execute(state, delay);\n }\n\n protected requestAsyncId(scheduler: QueueScheduler, id?: TimerHandle, delay: number = 0): TimerHandle {\n // If delay exists and is greater than 0, or if the delay is null (the\n // action wasn't rescheduled) but was originally scheduled as an async\n // action, then recycle as an async action.\n\n if ((delay != null && delay > 0) || (delay == null && this.delay > 0)) {\n return super.requestAsyncId(scheduler, id, delay);\n }\n\n // Otherwise flush the scheduler starting with this action.\n scheduler.flush(this);\n\n // HACK: In the past, this was returning `void`. However, `void` isn't a valid\n // `TimerHandle`, and generally the return value here isn't really used. So the\n // compromise is to return `0` which is both \"falsy\" and a valid `TimerHandle`,\n // as opposed to refactoring every other instanceo of `requestAsyncId`.\n return 0;\n }\n}\n", "import { AsyncScheduler } from './AsyncScheduler';\n\nexport class QueueScheduler extends AsyncScheduler {\n}\n", "import { QueueAction } from './QueueAction';\nimport { QueueScheduler } from './QueueScheduler';\n\n/**\n *\n * Queue Scheduler\n *\n * Put every next task on a queue, instead of executing it immediately\n *\n * `queue` scheduler, when used with delay, behaves the same as {@link asyncScheduler} scheduler.\n *\n * When used without delay, it schedules given task synchronously - executes it right when\n * it is scheduled. However when called recursively, that is when inside the scheduled task,\n * another task is scheduled with queue scheduler, instead of executing immediately as well,\n * that task will be put on a queue and wait for current one to finish.\n *\n * This means that when you execute task with `queue` scheduler, you are sure it will end\n * before any other task scheduled with that scheduler will start.\n *\n * ## Examples\n * Schedule recursively first, then do something\n * ```ts\n * import { queueScheduler } from 'rxjs';\n *\n * queueScheduler.schedule(() => {\n * queueScheduler.schedule(() => console.log('second')); // will not happen now, but will be put on a queue\n *\n * console.log('first');\n * });\n *\n * // Logs:\n * // \"first\"\n * // \"second\"\n * ```\n *\n * Reschedule itself recursively\n * ```ts\n * import { queueScheduler } from 'rxjs';\n *\n * queueScheduler.schedule(function(state) {\n * if (state !== 0) {\n * console.log('before', state);\n * this.schedule(state - 1); // `this` references currently executing Action,\n * // which we reschedule with new state\n * console.log('after', state);\n * }\n * }, 0, 3);\n *\n * // In scheduler that runs recursively, you would expect:\n * // \"before\", 3\n * // \"before\", 2\n * // \"before\", 1\n * // \"after\", 1\n * // \"after\", 2\n * // \"after\", 3\n *\n * // But with queue it logs:\n * // \"before\", 3\n * // \"after\", 3\n * // \"before\", 2\n * // \"after\", 2\n * // \"before\", 1\n * // \"after\", 1\n * ```\n */\n\nexport const queueScheduler = new QueueScheduler(QueueAction);\n\n/**\n * @deprecated Renamed to {@link queueScheduler}. Will be removed in v8.\n */\nexport const queue = queueScheduler;\n", "import { AsyncAction } from './AsyncAction';\nimport { AnimationFrameScheduler } from './AnimationFrameScheduler';\nimport { SchedulerAction } from '../types';\nimport { animationFrameProvider } from './animationFrameProvider';\nimport { TimerHandle } from './timerHandle';\n\nexport class AnimationFrameAction extends AsyncAction {\n constructor(protected scheduler: AnimationFrameScheduler, protected work: (this: SchedulerAction, state?: T) => void) {\n super(scheduler, work);\n }\n\n protected requestAsyncId(scheduler: AnimationFrameScheduler, id?: TimerHandle, delay: number = 0): TimerHandle {\n // If delay is greater than 0, request as an async action.\n if (delay !== null && delay > 0) {\n return super.requestAsyncId(scheduler, id, delay);\n }\n // Push the action to the end of the scheduler queue.\n scheduler.actions.push(this);\n // If an animation frame has already been requested, don't request another\n // one. If an animation frame hasn't been requested yet, request one. Return\n // the current animation frame request id.\n return scheduler._scheduled || (scheduler._scheduled = animationFrameProvider.requestAnimationFrame(() => scheduler.flush(undefined)));\n }\n\n protected recycleAsyncId(scheduler: AnimationFrameScheduler, id?: TimerHandle, delay: number = 0): TimerHandle | undefined {\n // If delay exists and is greater than 0, or if the delay is null (the\n // action wasn't rescheduled) but was originally scheduled as an async\n // action, then recycle as an async action.\n if (delay != null ? delay > 0 : this.delay > 0) {\n return super.recycleAsyncId(scheduler, id, delay);\n }\n // If the scheduler queue has no remaining actions with the same async id,\n // cancel the requested animation frame and set the scheduled flag to\n // undefined so the next AnimationFrameAction will request its own.\n const { actions } = scheduler;\n if (id != null && actions[actions.length - 1]?.id !== id) {\n animationFrameProvider.cancelAnimationFrame(id as number);\n scheduler._scheduled = undefined;\n }\n // Return undefined so the action knows to request a new async id if it's rescheduled.\n return undefined;\n }\n}\n", "import { AsyncAction } from './AsyncAction';\nimport { AsyncScheduler } from './AsyncScheduler';\n\nexport class AnimationFrameScheduler extends AsyncScheduler {\n public flush(action?: AsyncAction): void {\n this._active = true;\n // The async id that effects a call to flush is stored in _scheduled.\n // Before executing an action, it's necessary to check the action's async\n // id to determine whether it's supposed to be executed in the current\n // flush.\n // Previous implementations of this method used a count to determine this,\n // but that was unsound, as actions that are unsubscribed - i.e. cancelled -\n // are removed from the actions array and that can shift actions that are\n // scheduled to be executed in a subsequent flush into positions at which\n // they are executed within the current flush.\n const flushId = this._scheduled;\n this._scheduled = undefined;\n\n const { actions } = this;\n let error: any;\n action = action || actions.shift()!;\n\n do {\n if ((error = action.execute(action.state, action.delay))) {\n break;\n }\n } while ((action = actions[0]) && action.id === flushId && actions.shift());\n\n this._active = false;\n\n if (error) {\n while ((action = actions[0]) && action.id === flushId && actions.shift()) {\n action.unsubscribe();\n }\n throw error;\n }\n }\n}\n", "import { AnimationFrameAction } from './AnimationFrameAction';\nimport { AnimationFrameScheduler } from './AnimationFrameScheduler';\n\n/**\n *\n * Animation Frame Scheduler\n *\n * Perform task when `window.requestAnimationFrame` would fire\n *\n * When `animationFrame` scheduler is used with delay, it will fall back to {@link asyncScheduler} scheduler\n * behaviour.\n *\n * Without delay, `animationFrame` scheduler can be used to create smooth browser animations.\n * It makes sure scheduled task will happen just before next browser content repaint,\n * thus performing animations as efficiently as possible.\n *\n * ## Example\n * Schedule div height animation\n * ```ts\n * // html:
\n * import { animationFrameScheduler } from 'rxjs';\n *\n * const div = document.querySelector('div');\n *\n * animationFrameScheduler.schedule(function(height) {\n * div.style.height = height + \"px\";\n *\n * this.schedule(height + 1); // `this` references currently executing Action,\n * // which we reschedule with new state\n * }, 0, 0);\n *\n * // You will see a div element growing in height\n * ```\n */\n\nexport const animationFrameScheduler = new AnimationFrameScheduler(AnimationFrameAction);\n\n/**\n * @deprecated Renamed to {@link animationFrameScheduler}. Will be removed in v8.\n */\nexport const animationFrame = animationFrameScheduler;\n", "import { Observable } from '../Observable';\nimport { SchedulerLike } from '../types';\n\n/**\n * A simple Observable that emits no items to the Observer and immediately\n * emits a complete notification.\n *\n * Just emits 'complete', and nothing else.\n *\n * ![](empty.png)\n *\n * A simple Observable that only emits the complete notification. It can be used\n * for composing with other Observables, such as in a {@link mergeMap}.\n *\n * ## Examples\n *\n * Log complete notification\n *\n * ```ts\n * import { EMPTY } from 'rxjs';\n *\n * EMPTY.subscribe({\n * next: () => console.log('Next'),\n * complete: () => console.log('Complete!')\n * });\n *\n * // Outputs\n * // Complete!\n * ```\n *\n * Emit the number 7, then complete\n *\n * ```ts\n * import { EMPTY, startWith } from 'rxjs';\n *\n * const result = EMPTY.pipe(startWith(7));\n * result.subscribe(x => console.log(x));\n *\n * // Outputs\n * // 7\n * ```\n *\n * Map and flatten only odd numbers to the sequence `'a'`, `'b'`, `'c'`\n *\n * ```ts\n * import { interval, mergeMap, of, EMPTY } from 'rxjs';\n *\n * const interval$ = interval(1000);\n * const result = interval$.pipe(\n * mergeMap(x => x % 2 === 1 ? of('a', 'b', 'c') : EMPTY),\n * );\n * result.subscribe(x => console.log(x));\n *\n * // Results in the following to the console:\n * // x is equal to the count on the interval, e.g. (0, 1, 2, 3, ...)\n * // x will occur every 1000ms\n * // if x % 2 is equal to 1, print a, b, c (each on its own)\n * // if x % 2 is not equal to 1, nothing will be output\n * ```\n *\n * @see {@link Observable}\n * @see {@link NEVER}\n * @see {@link of}\n * @see {@link throwError}\n */\nexport const EMPTY = new Observable((subscriber) => subscriber.complete());\n\n/**\n * @param scheduler A {@link SchedulerLike} to use for scheduling\n * the emission of the complete notification.\n * @deprecated Replaced with the {@link EMPTY} constant or {@link scheduled} (e.g. `scheduled([], scheduler)`). Will be removed in v8.\n */\nexport function empty(scheduler?: SchedulerLike) {\n return scheduler ? emptyScheduled(scheduler) : EMPTY;\n}\n\nfunction emptyScheduled(scheduler: SchedulerLike) {\n return new Observable((subscriber) => scheduler.schedule(() => subscriber.complete()));\n}\n", "import { SchedulerLike } from '../types';\nimport { isFunction } from './isFunction';\n\nexport function isScheduler(value: any): value is SchedulerLike {\n return value && isFunction(value.schedule);\n}\n", "import { SchedulerLike } from '../types';\nimport { isFunction } from './isFunction';\nimport { isScheduler } from './isScheduler';\n\nfunction last(arr: T[]): T | undefined {\n return arr[arr.length - 1];\n}\n\nexport function popResultSelector(args: any[]): ((...args: unknown[]) => unknown) | undefined {\n return isFunction(last(args)) ? args.pop() : undefined;\n}\n\nexport function popScheduler(args: any[]): SchedulerLike | undefined {\n return isScheduler(last(args)) ? args.pop() : undefined;\n}\n\nexport function popNumber(args: any[], defaultValue: number): number {\n return typeof last(args) === 'number' ? args.pop()! : defaultValue;\n}\n", "export const isArrayLike = ((x: any): x is ArrayLike => x && typeof x.length === 'number' && typeof x !== 'function');", "import { isFunction } from \"./isFunction\";\n\n/**\n * Tests to see if the object is \"thennable\".\n * @param value the object to test\n */\nexport function isPromise(value: any): value is PromiseLike {\n return isFunction(value?.then);\n}\n", "import { InteropObservable } from '../types';\nimport { observable as Symbol_observable } from '../symbol/observable';\nimport { isFunction } from './isFunction';\n\n/** Identifies an input as being Observable (but not necessary an Rx Observable) */\nexport function isInteropObservable(input: any): input is InteropObservable {\n return isFunction(input[Symbol_observable]);\n}\n", "import { isFunction } from './isFunction';\n\nexport function isAsyncIterable(obj: any): obj is AsyncIterable {\n return Symbol.asyncIterator && isFunction(obj?.[Symbol.asyncIterator]);\n}\n", "/**\n * Creates the TypeError to throw if an invalid object is passed to `from` or `scheduled`.\n * @param input The object that was passed.\n */\nexport function createInvalidObservableTypeError(input: any) {\n // TODO: We should create error codes that can be looked up, so this can be less verbose.\n return new TypeError(\n `You provided ${\n input !== null && typeof input === 'object' ? 'an invalid object' : `'${input}'`\n } where a stream was expected. You can provide an Observable, Promise, ReadableStream, Array, AsyncIterable, or Iterable.`\n );\n}\n", "export function getSymbolIterator(): symbol {\n if (typeof Symbol !== 'function' || !Symbol.iterator) {\n return '@@iterator' as any;\n }\n\n return Symbol.iterator;\n}\n\nexport const iterator = getSymbolIterator();\n", "import { iterator as Symbol_iterator } from '../symbol/iterator';\nimport { isFunction } from './isFunction';\n\n/** Identifies an input as being an Iterable */\nexport function isIterable(input: any): input is Iterable {\n return isFunction(input?.[Symbol_iterator]);\n}\n", "import { ReadableStreamLike } from '../types';\nimport { isFunction } from './isFunction';\n\nexport async function* readableStreamLikeToAsyncGenerator(readableStream: ReadableStreamLike): AsyncGenerator {\n const reader = readableStream.getReader();\n try {\n while (true) {\n const { value, done } = await reader.read();\n if (done) {\n return;\n }\n yield value!;\n }\n } finally {\n reader.releaseLock();\n }\n}\n\nexport function isReadableStreamLike(obj: any): obj is ReadableStreamLike {\n // We don't want to use instanceof checks because they would return\n // false for instances from another Realm, like an