Towards resolving "Pulse power specification"

Explanation of changes

First of three MRs closing #413 (closed).

• MR 1 implements the new API, and is mostly backwards compatible. Schedules are still compatible, but gate amplitudes will change, i.e. new calibration is required.
• MR 2 will implement backend changes, enabling to change the reference.
• MR 3 will be helper functions for QoL improvements.

New Pulse API

Pulse amplitudes will be specified with two kwargs, with the default being backwards compatible

@dataclass
class ReferenceMagnitude:
    value: float
    unit: Literal[“V“, “dBm“, (“A“)]

SquarePulse(
    amp:float,
    reference_magnitude:Optional[ReferenceMagnitude]=None,
    ...
    )
# square pulse with -20 dBm
SquarePulse(1.0, ReferenceMagnitude(-20, "dBm"))

# use reference from hardware config (current behavior)
SquarePulse(1.0)

amp is always in [-1, 1] and maps to the full DAC range. reference_magnitude is restricted to power values supported natively by the hardware. Where possible, both (V, dBm) can be used and are automatically converted.

New Gate API

DeviceElement submodules (Gates) get a new qcodes submodule, which allows the reference mangitude to be specified in one of three different units (where appropriate)

        self.add_submodule(
            name="reference_magnitude",
            submodule=ReferenceMagnitude(
                parent=self,
                name="reference_magnitude",
                dBm=kwargs.get("reference_magnitude_dBm", math.nan),
                V=kwargs.get("reference_magnitude_V", math.nan),
                A=kwargs.get("reference_magnitude_A", math.nan),
            ),
        )


q1 = BasicTransmonElement("q1")

# use HDAWG
q1.rxy.reference_magnitude.V(400e-3)

# use qcm-rf
q1.rxy.reference_magnitude.dBm(-10)

reference_magnitude(None) in the gate level will be translated to reference_magnitude = None in the pulse level API by the DeviceElement.

Motivation of changes

---

In addition to the discussion in #413 (closed), we wanted to include the unit as both V and dBm are used for different use cases. Going forward, there might also be current sources or hardware that can change values during an experiment. Qblox hardware does use attenuation, but we feel the need to specify the power somewhere. It should be understood that the reference is always an upper bound though, and not necessarily accurate. I.e. the pulse in the example might actually be -23 dBm on a scope, but should never be -19 dBm.

---

Merge checklist

See also merge request guidelines

• Merge request has been reviewed (in-depth by a knowledgeable contributor), and is approved by a project maintainer.
• New code is covered by unit tests (or N/A).
• New code is documented and docstrings use numpydoc format (or N/A).
• New functionality: considered making private instead of extending public API (or N/A).
• Public API changed: added @deprecated (or N/A).
• Tested on hardware (or N/A).
• CHANGELOG.md and AUTHORS.md have been updated (or N/A).
• Windows tests in CI pipeline pass (manually triggered by maintainers before merging).

---

For reference, the issues workflow is described in the contribution guidelines.