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

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:

Name	Type	Description	Default
parent		The parent of this object. This is automatically set when adding this object to another QuamBase 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

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.
        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()
    _last_instantiated_root: ClassVar[Optional["QuamRoot"]] = None
    config_settings: ClassVar[Dict[str, Any]] = None
    _MAX_REFERENCE_DEPTH: ClassVar[int] = 10

    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_root(self) -> Optional[QuamRoot]:
        """Get the QuamRoot object of this object.

        This function recursively searches the parent chain for a QuamRoot object.
        If no QuamRoot object is found, it will return the last instantiated QuamRoot
        if it exists, else None.

        Returns:
            The root of this object, or None if no root is found.
        """
        if self.parent is not None:
            return self.parent.get_root()

        if self._last_instantiated_root is not None:
            warnings.warn(
                f"This component is not part of any QuamRoot, using last "
                f"instantiated QuamRoot. This is not recommended as it may lead to "
                f"unexpected behaviour. Component: {self.__class__.__name__}"
            )
            return self._last_instantiated_root
        return None

    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 self.get_raw_value(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: Optional[str] = None,
        relative_path: Optional[str] = None,
        follow_chain: bool = False,
    ) -> Optional[str]:
        """Get the reference path of this object or one of its attributes.

        Args:
            attr: The optional attribute to get the reference path for.
                If None, the reference path of the object itself is returned.
            relative_path: The optional relative path to join with the reference path.
            follow_chain: If True and attr is a reference, follow the reference chain
                to return the ultimate target reference. Default is False for backward
                compatibility. Only applies when attr is specified.

        Returns:
            The reference path of this object or the specified attribute.

        Raises:
            ValueError: If both attr and relative_path are specified, or if follow_chain
                is True but attr is not a reference.

        Examples:
            We assume a QuamRoot object with a component "elem".
            - elem.get_reference() == "#/elem"
            - elem.get_reference(attr="child") == "#/elem/child"
            - elem.get_reference(relative_path="#./child") == "#/elem/child"
            - elem.get_reference(relative_path="#../child") == "#/child"
            - elem.get_reference(relative_path="#./child/grandchild") == "#/elem/child/grandchild"

            With follow_chain=True (if attr contains a reference to another reference):
            - elem.get_reference(attr="chain_ref", follow_chain=True)  # returns ultimate target
        """

        if attr is not None and relative_path is not None:
            raise ValueError(
                "Cannot specify both attr and relative_path. "
                "Please specify only one of them."
            )

        # Handle follow_chain before computing the reference path
        if follow_chain and attr is not None:
            raw_value = self.get_raw_value(attr)
            if not string_reference.is_reference(raw_value):
                raise ValueError(
                    f"Cannot follow reference chain for attr '{attr}': "
                    f"value is not a reference (value={raw_value})"
                )
            # Follow the reference chain to get the ultimate target
            try:
                target_obj, target_attr = self._follow_reference_chain(self, attr)
                # Return the reference path to the ultimate target
                return target_obj.get_reference(attr=target_attr)
            except (AttributeError, ValueError, RecursionError) as e:
                raise ValueError(
                    f"Failed to follow reference chain for attr '{attr}': {e}"
                ) from e

        if self.parent is None:
            raise AttributeError(
                "Unable to extract reference path for {self}: No parent defined"
            )

        try:
            base_reference = self.parent.get_reference()
            if base_reference == "#/":
                base_reference = "#"
        except AttributeError:
            raise AttributeError(
                f"Unable to extract reference path for {self}: Could not get "
                f"reference path for parent {self.parent}"
            )

        try:
            attr_name = self.parent.get_attr_name(self)
        except AttributeError:
            raise AttributeError(
                f"Unable to extract reference path for {self}: Could not get "
                f"attribute name from parent {self.parent}"
            )

        reference = f"{base_reference}/{attr_name}"

        if relative_path is not None:
            if not string_reference.is_reference(relative_path):
                raise ValueError(
                    f"Unable to extract reference path for {self}: "
                    f"relative_path {relative_path} is not a reference"
                )

            reference = string_reference.join_references(reference, relative_path)
        elif 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]

        # Apply skip_save metadata filter
        if is_dataclass(self):
            skip_save_attrs = [
                field.name
                for field in fields(self)
                if field.metadata.get("skip_save", False)
            ]
            attr_names = [attr for attr in attr_names if attr not in skip_save_attrs]

        if not follow_references:
            attrs = {attr: self.get_raw_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 = True
    ) -> 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.

        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,
                )
            else:
                quam_dict[attr] = val

        # Add __class__ to specify the class of the object
        quam_dict["__class__"] = get_full_class_path(self)

        return quam_dict

    def iterate_components(
        self, skip_elems: Optional[Sequence["QuamBase"]] = None
    ) -> Generator["QuamBase", None, None]:
        """Iterate over all QuamBase objects in this object, including nested objects.

        Args:
            skip_elems: A sequence 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

        root = self.get_root()
        if string_reference.is_absolute_reference(reference) and root is None:
            warnings.warn(
                f"No QuamRoot initialized, cannot retrieve absolute reference "
                f"{reference} from {self.__class__.__name__}"
            )
            return reference

        try:
            return string_reference.get_referenced_value(self, reference, root=root)
        except InvalidReferenceError as e:
            try:
                ref = f"{self.__class__.__name__}: {self.get_reference()}"
            except Exception:
                ref = self.__class__.__name__

            # Construct message using the chained exception's message
            base_error_msg = str(e)
            component_ref_str = f"component {ref}"
            msg = (
                f'Could not get reference "{reference}" from {component_ref_str}. '
                f"Error: {base_error_msg}"
            )

            try:
                cfg = get_quam_config()
                raise_error_missing_reference = cfg.raise_error_missing_reference
            except FileNotFoundError:
                # Default behavior if config file not found
                raise_error_missing_reference = False

            if not raise_error_missing_reference:
                warnings.warn(msg)
            else:
                # Re-raise with context, keeping the original exception chain
                raise InvalidReferenceError(msg) from 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.get_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}")

    def _follow_reference_chain(
        self, obj: "QuamBase", attr: str, max_depth: Optional[int] = None
    ) -> tuple["QuamBase", str]:
        """Recursively follow a reference chain to find the ultimate target.

        This method follows reference strings through nested references until
        reaching a non-reference value. It is used internally by
        set_at_reference() and get_reference() to handle chained references.

        Args:
            obj: The QuamBase object containing the attribute.
            attr: The attribute name to follow (may be a list index like "0").
            max_depth: Maximum recursion depth to prevent infinite loops
                (default: QuamBase._MAX_REFERENCE_DEPTH).

        Returns:
            A tuple of (target_object, final_attr_name) where:
            - target_object: The QuamBase object containing the ultimate value
            - final_attr_name: The final attribute name (after following all chains)

        Raises:
            AttributeError: If a reference in the chain cannot be resolved.
            RecursionError: If max_depth is exceeded (indicates circular reference).
        """
        # Normalize attr to string for consistent handling
        attr = str(attr)

        if max_depth is None:
            max_depth = self._MAX_REFERENCE_DEPTH
        if max_depth <= 0:
            raise RecursionError(
                f"Reference chain exceeded maximum depth of {self._MAX_REFERENCE_DEPTH}. "
                f"Possible circular reference starting from {obj.get_attr_path()}"
            )

        # Handle list/dict index access specially
        if attr.isdigit() and isinstance(obj, (list, UserList, QuamList)):
            # For list indices, get the raw element directly from the list
            index = int(attr)
            if isinstance(obj, QuamList):
                raw_value = obj.data[index]
            else:
                raw_value = obj[index]
        else:
            raw_value = obj.get_raw_value(attr)

        # Base case: value is not a reference
        if not string_reference.is_reference(raw_value):
            return obj, attr

        # Recursive case: follow the reference chain
        parent_reference, parent_attr = string_reference.split_reference(raw_value)
        if not parent_attr:
            raise ValueError(
                f"Invalid reference {raw_value}: must have an attribute part"
            )

        parent_obj = obj._get_referenced_value(parent_reference)
        if not isinstance(parent_obj, QuamBase):
            # This can happen when:
            # 1. Broken reference: _get_referenced_value returns the reference string
            # 2. Reference to a non-QuamBase value (e.g., primitive)
            # Raise AttributeError to match the expected contract for set_at_reference
            raise AttributeError(
                f"Cannot follow reference chain: '{parent_reference}' resolved to "
                f"{type(parent_obj).__name__}, not a QuamBase object"
            )

        # Recursively follow the chain
        return self._follow_reference_chain(parent_obj, parent_attr, max_depth - 1)

    def set_at_reference(
        self, attr: str, value: Any, allow_non_reference: bool = True
    ):
        """Follow the reference of an attribute and set the value at the reference.

        This method follows reference chains recursively. If an attribute contains
        a reference to another reference, both references are preserved while the
        ultimate target value is updated.

        Args:
            attr: The attribute to set the value at the reference of.
            value: The value to set.
            allow_non_reference: Whether to allow the attribute to be a non-reference.
                If True (default), non-reference attributes are allowed. If False,
                the attribute must be a reference or an error is raised.

        Raises:
            ValueError: If the attribute is not a reference and `allow_non_reference` is
                False.
            ValueError: If the reference is invalid, e.g. "#./" since it has no
                attribute.
        """
        raw_value = self.get_raw_value(attr)
        if not string_reference.is_reference(raw_value):
            if not allow_non_reference:
                raise ValueError(
                    f"Cannot set at reference because attr '{attr}' is not a reference. "
                    f"'{attr}' = {raw_value}"
                )
            target_obj, target_attr = self, attr
        else:
            # Follow the reference chain to get the ultimate target
            target_obj, target_attr = self._follow_reference_chain(self, attr)

        # Use __setitem__ for dict/list types, otherwise use setattr
        if isinstance(target_obj, (dict, list, UserDict, UserList, QuamDict, QuamList)):
            # Convert string index to int for list types
            if (
                isinstance(target_obj, (list, UserList, QuamList))
                and target_attr.isdigit()
            ):
                target_attr = int(target_attr)
            target_obj[target_attr] = value
        else:
            setattr(target_obj, target_attr, value)

get_attr_name(attr_val)

Get the name of an attribute that matches the value.

Parameters:

Name	Type	Description	Default
attr_val	Any	The value of the attribute.	required

Returns:

Type	Description
str	The name of the attribute.

Source code in quam/core/quam_classes.py

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 self.get_raw_value(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:

Name	Type	Description	Default
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:

Type	Description
Dict[str, Any]	A dictionary of attribute names and values.

Source code in quam/core/quam_classes.py

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]

    # Apply skip_save metadata filter
    if is_dataclass(self):
        skip_save_attrs = [
            field.name
            for field in fields(self)
            if field.metadata.get("skip_save", False)
        ]
        attr_names = [attr for attr in attr_names if attr not in skip_save_attrs]

    if not follow_references:
        attrs = {attr: self.get_raw_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, relative_path=None, follow_chain=False)

Get the reference path of this object or one of its attributes.

Parameters:

Name	Type	Description	Default
attr	Optional[str]	The optional attribute to get the reference path for. If None, the reference path of the object itself is returned.	None
relative_path	Optional[str]	The optional relative path to join with the reference path.	None
follow_chain	bool	If True and attr is a reference, follow the reference chain to return the ultimate target reference. Default is False for backward compatibility. Only applies when attr is specified.	False

Returns:

Type	Description
Optional[str]	The reference path of this object or the specified attribute.

Raises:

Type	Description
ValueError	If both attr and relative_path are specified, or if follow_chain is True but attr is not a reference.

Examples:

We assume a QuamRoot object with a component "elem". - elem.get_reference() == "#/elem" - elem.get_reference(attr="child") == "#/elem/child" - elem.get_reference(relative_path="#./child") == "#/elem/child" - elem.get_reference(relative_path="#../child") == "#/child" - elem.get_reference(relative_path="#./child/grandchild") == "#/elem/child/grandchild"

With follow_chain=True (if attr contains a reference to another reference): - elem.get_reference(attr="chain_ref", follow_chain=True) # returns ultimate target

Source code in quam/core/quam_classes.py

def get_reference(
    self,
    attr: Optional[str] = None,
    relative_path: Optional[str] = None,
    follow_chain: bool = False,
) -> Optional[str]:
    """Get the reference path of this object or one of its attributes.

    Args:
        attr: The optional attribute to get the reference path for.
            If None, the reference path of the object itself is returned.
        relative_path: The optional relative path to join with the reference path.
        follow_chain: If True and attr is a reference, follow the reference chain
            to return the ultimate target reference. Default is False for backward
            compatibility. Only applies when attr is specified.

    Returns:
        The reference path of this object or the specified attribute.

    Raises:
        ValueError: If both attr and relative_path are specified, or if follow_chain
            is True but attr is not a reference.

    Examples:
        We assume a QuamRoot object with a component "elem".
        - elem.get_reference() == "#/elem"
        - elem.get_reference(attr="child") == "#/elem/child"
        - elem.get_reference(relative_path="#./child") == "#/elem/child"
        - elem.get_reference(relative_path="#../child") == "#/child"
        - elem.get_reference(relative_path="#./child/grandchild") == "#/elem/child/grandchild"

        With follow_chain=True (if attr contains a reference to another reference):
        - elem.get_reference(attr="chain_ref", follow_chain=True)  # returns ultimate target
    """

    if attr is not None and relative_path is not None:
        raise ValueError(
            "Cannot specify both attr and relative_path. "
            "Please specify only one of them."
        )

    # Handle follow_chain before computing the reference path
    if follow_chain and attr is not None:
        raw_value = self.get_raw_value(attr)
        if not string_reference.is_reference(raw_value):
            raise ValueError(
                f"Cannot follow reference chain for attr '{attr}': "
                f"value is not a reference (value={raw_value})"
            )
        # Follow the reference chain to get the ultimate target
        try:
            target_obj, target_attr = self._follow_reference_chain(self, attr)
            # Return the reference path to the ultimate target
            return target_obj.get_reference(attr=target_attr)
        except (AttributeError, ValueError, RecursionError) as e:
            raise ValueError(
                f"Failed to follow reference chain for attr '{attr}': {e}"
            ) from e

    if self.parent is None:
        raise AttributeError(
            "Unable to extract reference path for {self}: No parent defined"
        )

    try:
        base_reference = self.parent.get_reference()
        if base_reference == "#/":
            base_reference = "#"
    except AttributeError:
        raise AttributeError(
            f"Unable to extract reference path for {self}: Could not get "
            f"reference path for parent {self.parent}"
        )

    try:
        attr_name = self.parent.get_attr_name(self)
    except AttributeError:
        raise AttributeError(
            f"Unable to extract reference path for {self}: Could not get "
            f"attribute name from parent {self.parent}"
        )

    reference = f"{base_reference}/{attr_name}"

    if relative_path is not None:
        if not string_reference.is_reference(relative_path):
            raise ValueError(
                f"Unable to extract reference path for {self}: "
                f"relative_path {relative_path} is not a reference"
            )

        reference = string_reference.join_references(reference, relative_path)
    elif attr is not None:
        reference = f"{reference}/{attr}"

    return reference

get_root()

Get the QuamRoot object of this object.

This function recursively searches the parent chain for a QuamRoot object. If no QuamRoot object is found, it will return the last instantiated QuamRoot if it exists, else None.

Returns:

Type	Description
Optional[QuamRoot]	The root of this object, or None if no root is found.

Source code in quam/core/quam_classes.py

def get_root(self) -> Optional[QuamRoot]:
    """Get the QuamRoot object of this object.

    This function recursively searches the parent chain for a QuamRoot object.
    If no QuamRoot object is found, it will return the last instantiated QuamRoot
    if it exists, else None.

    Returns:
        The root of this object, or None if no root is found.
    """
    if self.parent is not None:
        return self.parent.get_root()

    if self._last_instantiated_root is not None:
        warnings.warn(
            f"This component is not part of any QuamRoot, using last "
            f"instantiated QuamRoot. This is not recommended as it may lead to "
            f"unexpected behaviour. Component: {self.__class__.__name__}"
        )
        return self._last_instantiated_root
    return None

iterate_components(skip_elems=None)

Iterate over all QuamBase objects in this object, including nested objects.

Parameters:

Name	Type	Description	Default
skip_elems	Optional[Sequence['QuamBase']]	A sequence of QuamBase objects to skip. This is used to prevent infinite loops when iterating over nested objects.	None

Returns:

Type	Description
None	A generator of QuamBase objects.

Source code in quam/core/quam_classes.py

def iterate_components(
    self, skip_elems: Optional[Sequence["QuamBase"]] = None
) -> Generator["QuamBase", None, None]:
    """Iterate over all QuamBase objects in this object, including nested objects.

    Args:
        skip_elems: A sequence 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:

Name	Type	Description	Default
indent	int	The number of spaces to indent the summary.	0

Source code in quam/core/quam_classes.py

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.get_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}")

set_at_reference(attr, value, allow_non_reference=True)

Follow the reference of an attribute and set the value at the reference.

This method follows reference chains recursively. If an attribute contains a reference to another reference, both references are preserved while the ultimate target value is updated.

Parameters:

Name	Type	Description	Default
attr	str	The attribute to set the value at the reference of.	required
value	Any	The value to set.	required
allow_non_reference	bool	Whether to allow the attribute to be a non-reference. If True (default), non-reference attributes are allowed. If False, the attribute must be a reference or an error is raised.	True

Raises:

Type	Description
ValueError	If the attribute is not a reference and allow_non_reference is False.
ValueError	If the reference is invalid, e.g. "#./" since it has no attribute.

Source code in quam/core/quam_classes.py

def set_at_reference(
    self, attr: str, value: Any, allow_non_reference: bool = True
):
    """Follow the reference of an attribute and set the value at the reference.

    This method follows reference chains recursively. If an attribute contains
    a reference to another reference, both references are preserved while the
    ultimate target value is updated.

    Args:
        attr: The attribute to set the value at the reference of.
        value: The value to set.
        allow_non_reference: Whether to allow the attribute to be a non-reference.
            If True (default), non-reference attributes are allowed. If False,
            the attribute must be a reference or an error is raised.

    Raises:
        ValueError: If the attribute is not a reference and `allow_non_reference` is
            False.
        ValueError: If the reference is invalid, e.g. "#./" since it has no
            attribute.
    """
    raw_value = self.get_raw_value(attr)
    if not string_reference.is_reference(raw_value):
        if not allow_non_reference:
            raise ValueError(
                f"Cannot set at reference because attr '{attr}' is not a reference. "
                f"'{attr}' = {raw_value}"
            )
        target_obj, target_attr = self, attr
    else:
        # Follow the reference chain to get the ultimate target
        target_obj, target_attr = self._follow_reference_chain(self, attr)

    # Use __setitem__ for dict/list types, otherwise use setattr
    if isinstance(target_obj, (dict, list, UserDict, UserList, QuamDict, QuamList)):
        # Convert string index to int for list types
        if (
            isinstance(target_obj, (list, UserList, QuamList))
            and target_attr.isdigit()
        ):
            target_attr = int(target_attr)
        target_obj[target_attr] = value
    else:
        setattr(target_obj, target_attr, value)

to_dict(follow_references=False, include_defaults=True)

Convert this object to a dictionary.

Parameters:

Name	Type	Description	Default
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:

Type	Description
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

def to_dict(
    self, follow_references: bool = False, include_defaults: bool = True
) -> 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.

    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,
            )
        else:
            quam_dict[attr] = val

    # Add __class__ to specify the class of the object
    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

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:

Name	Type	Description	Default
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

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

@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 not string_reference.is_reference(elem):
            return elem

        try:
            target_obj, target_attr = self._follow_reference_chain(self, i)
            # Handle list/dict indices that result from following the chain
            if target_attr.isdigit() and isinstance(
                target_obj, (list, UserList, QuamList)
            ):
                return target_obj[int(target_attr)]
            elif isinstance(target_obj, (dict, UserDict, QuamDict)):
                return target_obj[target_attr]
            else:
                return target_obj.get_raw_value(target_attr)
        except (AttributeError, KeyError, ValueError):
            # Chain couldn't be followed (broken reference, missing attribute, etc.)
            # Return the reference string - _get_referenced_value handles warnings
            return self._get_referenced_value(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.get_raw_value(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_raw_value(self, attr: str) -> Any:
        """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 raw (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 sequence 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)

    def to_dict(
        self, follow_references: bool = False, include_defaults: bool = True
    ) -> dict:
        """Convert this object to a dictionary.

        Ensures all child QUAM objects are also converted to dictionaries.

        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 representation of the object.
        """
        quam_dict = super().to_dict(
            follow_references=follow_references,
            include_defaults=include_defaults,
        )

        # Remove __class__ from the dictionary as it's the default for a dict
        quam_dict.pop("__class__", None)

        return quam_dict

get_attr_name(attr_val)

Get the name of an attribute that matches the value.

Parameters:

Name	Type	Description	Default
attr_val	Any	The value of the attribute.	required

Returns:

Type	Description
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

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.get_raw_value(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_raw_value(attr)

Get the value of an attribute without following references.

Parameters:

Name	Type	Description	Default
attr	str	The name of the attribute.	required

Returns:

Type	Description
Any	The value of the attribute. If the value is a reference, it returns the
Any	reference string instead of the value it is referencing.

Source code in quam/core/quam_classes.py

def get_raw_value(self, attr: str) -> Any:
    """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 raw (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:

Name	Type	Description	Default
skip_elems	Sequence[QuamBase]	A sequence of QuamBase objects to skip. This is used to prevent infinite loops when iterating over nested objects.	None

Returns:

Type	Description
None	A generator of QuamBase objects.

Source code in quam/core/quam_classes.py

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 sequence 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)

to_dict(follow_references=False, include_defaults=True)

Convert this object to a dictionary.

Ensures all child QUAM objects are also converted to dictionaries.

Parameters:

Name	Type	Description	Default
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:

Type	Description
dict	A dictionary representation of the object.

Source code in quam/core/quam_classes.py

def to_dict(
    self, follow_references: bool = False, include_defaults: bool = True
) -> dict:
    """Convert this object to a dictionary.

    Ensures all child QUAM objects are also converted to dictionaries.

    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 representation of the object.
    """
    quam_dict = super().to_dict(
        follow_references=follow_references,
        include_defaults=include_defaults,
    )

    # Remove __class__ from the dictionary as it's the default for a dict
    quam_dict.pop("__class__", None)

    return quam_dict

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

@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):
            if isinstance(elem, QuamList):
                elem.parent = self.parent
            # This automatically gets the referenced values
            return list(elem)

        elif not string_reference.is_reference(elem):
            return elem

        try:
            target_obj, target_attr = self._follow_reference_chain(self, i)
            # Handle list/dict indices that result from following the chain
            if target_attr.isdigit() and isinstance(
                target_obj, (list, UserList, QuamList)
            ):
                return target_obj[int(target_attr)]
            elif isinstance(target_obj, (dict, UserDict, QuamDict)):
                return target_obj[target_attr]
            else:
                return target_obj.get_raw_value(target_attr)
        except (AttributeError, KeyError, ValueError):
            # Chain couldn't be followed (broken reference, missing attribute, etc.)
            # Return the reference string - _get_referenced_value handles warnings
            return self._get_referenced_value(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 = True
    ) -> 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,
                    )
                )
            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:

Name	Type	Description	Default
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:

Type	Description
None	A generator of QuamBase objects.

Source code in quam/core/quam_classes.py

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:

Name	Type	Description	Default
indent	int	The number of spaces to indent the summary.	0

Source code in quam/core/quam_classes.py

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=True)

Convert this object to a list, usually as part of a dictionary representation.

Parameters:

Name	Type	Description	Default
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:

Type	Description
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

def to_dict(
    self, follow_references: bool = False, include_defaults: bool = True
) -> 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,
                )
            )
        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.

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.

Source code in quam/core/quam_classes.py

class QuamRoot(QuamBase):
    """Base class for the root of a QUAM object.

    This class should be subclassed and made a dataclass.

    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.
    """

    def __post_init__(self):
        QuamBase._last_instantiated_root = self
        self.serialiser = self.get_serialiser()
        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

    @classmethod
    def get_serialiser(cls) -> AbstractSerialiser:
        """Get the serialiser for the QuamRoot class, which is the JSONSerialiser.

        This method can be overridden by subclasses to provide a custom serialiser.
        """
        return JSONSerialiser()

    def get_reference(
        self, attr: Optional[str] = None, relative_path: Optional[str] = None
    ) -> Optional[str]:
        if attr is not None:
            return f"#/{attr}"

        reference = "#/"
        if relative_path is not None:
            reference = string_reference.join_references(reference, relative_path)
        return reference

    def get_root(self: QuamRootType) -> QuamRootType:
        """Get the QuamRoot object of this object, i.e. the object itself.

        This QuamRoot function overrides the QuamBase function to return the object
        itself, rather than following the parent chain.

        Returns:
            The current QuamRoot object (self).
        """
        return self

    def save(
        self,
        path: Optional[Union[Path, str]] = None,
        content_mapping: Optional[Dict[str, str]] = None,
        include_defaults: Optional[bool] = None,
        ignore: Optional[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 extracted from
                the `state_path` attribute of the serialiser, which could be set by the
                quam config file or environment variable.
            content_mapping: Optional mapping of component names to filenames. 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 components to ignore.
        """
        self.serialiser.save(
            quam_obj=self,
            path=path,
            content_mapping=content_mapping,
            include_defaults=include_defaults,
            ignore=ignore,
        )

    @classmethod
    def load(
        cls: type[QuamRootType],
        filepath_or_dict: Optional[Union[str, Path, dict]] = None,
        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()`
                Can be omitted, in which case the serialiser will use the default state
                path, which is typically defined in the quam config file.
            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.get_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) -> DictQuaConfig:
        """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

generate_config()

Generate the QUA configuration from the QUAM object.

Returns:

Type	Description
DictQuaConfig	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

def generate_config(self) -> DictQuaConfig:
    """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

get_root()

Get the QuamRoot object of this object, i.e. the object itself.

This QuamRoot function overrides the QuamBase function to return the object itself, rather than following the parent chain.

Returns:

Type	Description
QuamRootType	The current QuamRoot object (self).

Source code in quam/core/quam_classes.py

def get_root(self: QuamRootType) -> QuamRootType:
    """Get the QuamRoot object of this object, i.e. the object itself.

    This QuamRoot function overrides the QuamBase function to return the object
    itself, rather than following the parent chain.

    Returns:
        The current QuamRoot object (self).
    """
    return self

get_serialiser() classmethod

Get the serialiser for the QuamRoot class, which is the JSONSerialiser.

This method can be overridden by subclasses to provide a custom serialiser.

Source code in quam/core/quam_classes.py

@classmethod
def get_serialiser(cls) -> AbstractSerialiser:
    """Get the serialiser for the QuamRoot class, which is the JSONSerialiser.

    This method can be overridden by subclasses to provide a custom serialiser.
    """
    return JSONSerialiser()

load(filepath_or_dict=None, validate_type=True, fix_attrs=True) classmethod

Load a QuamRoot object from a file.

Parameters:

Name	Type	Description	Default
filepath_or_dict	Optional[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() Can be omitted, in which case the serialiser will use the default state path, which is typically defined in the quam config file.	None
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:

Type	Description
QuamRootType	A QuamRoot object instantiated from the file/folder/dict.

Source code in quam/core/quam_classes.py

@classmethod
def load(
    cls: type[QuamRootType],
    filepath_or_dict: Optional[Union[str, Path, dict]] = None,
    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()`
            Can be omitted, in which case the serialiser will use the default state
            path, which is typically defined in the quam config file.
        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.get_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=None, ignore=None)

Save the entire QuamRoot object to a file. This includes nested objects.

Parameters:

Name	Type	Description	Default
path	Optional[Union[Path, str]]	The path to save the file to. If None, the path will be extracted from the state_path attribute of the serialiser, which could be set by the quam config file or environment variable.	None
content_mapping	Optional[Dict[str, str]]	Optional mapping of component names to filenames. This can be used to save different parts of the QuamRoot object to different files.	None
include_defaults	Optional[bool]	Whether to include attributes that have the default value.	None
ignore	Optional[Sequence[str]]	A list of components to ignore.	None

Source code in quam/core/quam_classes.py

def save(
    self,
    path: Optional[Union[Path, str]] = None,
    content_mapping: Optional[Dict[str, str]] = None,
    include_defaults: Optional[bool] = None,
    ignore: Optional[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 extracted from
            the `state_path` attribute of the serialiser, which could be set by the
            quam config file or environment variable.
        content_mapping: Optional mapping of component names to filenames. 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 components to ignore.
    """
    self.serialiser.save(
        quam_obj=self,
        path=path,
        content_mapping=content_mapping,
        include_defaults=include_defaults,
        ignore=ignore,
    )

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

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:

Name	Type	Description	Default
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:

Type	Description
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

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