quantify_scheduler.structure.model

Root models for data structures used within the package.

Module Contents

Classes

DataStructure

A parent for all data structures.

Functions

orjson_dumps(→ str)

Dump an object to a JSON string using orjson library.

deserialize_function(→ Callable[Ellipsis, Any])

Import a python function from a dotted import string (e.g.,

deserialize_class(→ type)

Import a python class from a dotted import string (e.g.,
orjson_dumps(obj: Any, *, default: Callable[[Any], Any]) → str[source]

Dump an object to a JSON string using orjson library.

Parameters

  • obj – Object to dump

  • default – A function that is called if an object can’t be serialized otherwise. It should return a JSON-encodable version of an object or raise a TypeError.

Returns

JSON-encoded string representation of an object

Return type

str

Raises

TypeError – If value can’t be serialized.

class DataStructure[source]

Bases: pydantic.BaseModel

A parent for all data structures.

Data attributes are generated from the class’ type annotations, similarly to dataclasses. If data attributes are JSON-serializable, data structure can be serialized using json() method. This string can be deserialized using parse_raw() classmethod of a correspondent child class.

If required, data fields can be validated, see examples for more information. It is also possible to define custom field types with advanced validation.

This class is a pre-configured pydantic model. See its documentation for details of usage information.

Examples

Initializing a custom data structure:

class ExampleClockResource(DataStructure):
    """An example clock resource. It has name, frequency and phase. By default phase
    is zero.

    Parameters
    ----------
    name
        Clock name
    freq
        Clock frequency [Hz]
    phase
        Clock phase, by default 0 [rad].
    """

    name: str
    freq: float
    phase: float = 0


clock = ExampleClockResource(name="q0.01", freq=7e9)
print(str(clock))
print(repr(clock))

name='q0.01' freq=7000000000.0 phase=0
ExampleClockResource(name='q0.01', freq=7000000000.0, phase=0)

This data structure can be used within other data structures:

class ExamplePulse(DataStructure):
    """..."""

    amplitude: float
    duration: float
    clock: ExampleClockResource


pulse = ExamplePulse(amplitude=0.1, duration=2e-8, clock=clock)
print(str(pulse))
print(repr(pulse))

amplitude=0.1 duration=2e-08 clock=ExampleClockResource(name='q0.01', freq=7000000000.0, phase=0)
ExamplePulse(amplitude=0.1, duration=2e-08, clock=ExampleClockResource(name='q0.01', freq=7000000000.0, phase=0))

Serialization, deserialization and comparison are provided from scratch:

pulse_json = pulse.json()
print(pulse_json)
pulse2 = ExamplePulse.parse_raw(pulse_json)
assert pulse == pulse2

{"amplitude":0.1,"duration":2e-8,"clock":{"name":"q0.01","freq":7000000000.0,"phase":0}}

User may implement custom validators:

from pydantic import validator


class ScheduledExamplePulse(DataStructure):
    """..."""

    pulse: ExamplePulse
    start: float

    @validator("start")
    def _ensure_4ns_grid(cls, value):  # pylint: disable=no-self-argument,no-self-use
        if value % 4e-9 > 1e-12:
            raise ValueError("Start must be on a 4 ns grid due to hardware limitations")

        return value


# This works fine
scheduled_pulse = ScheduledExamplePulse(pulse=pulse, start=8e-9)
# This raises a ValidationError
scheduled_pulse = ScheduledExamplePulse(pulse=pulse, start=9e-9)

---------------------------------------------------------------------------
ValidationError                           Traceback (most recent call last)
Cell In[5], line 21
     19 scheduled_pulse = ScheduledExamplePulse(pulse=pulse, start=8e-9)
     20 # This raises a ValidationError
---> 21 scheduled_pulse = ScheduledExamplePulse(pulse=pulse, start=9e-9)

File ~/.anaconda3/envs/tmp/lib/python3.9/site-packages/pydantic/main.py:341, in pydantic.main.BaseModel.__init__()

ValidationError: 1 validation error for ScheduledExamplePulse
start
  Start must be on a 4 ns grid due to hardware limitations (type=value_error)

See pydantic documentation for more usage examples.

class Config[source]
json_loads[source]
json_dumps[source]
json_encoders[source]
extra[source]
validate_assignment = True[source]
deserialize_function(fun: str) → Callable[Ellipsis, Any][source]

Import a python function from a dotted import string (e.g., “quantify_scheduler.structure.model.deserialize_function”).

Parameters

fun (str) – A dotted import path to a function (e.g., “quantify_scheduler.waveforms.square”), or a function pointer.

Return type

Callable[[Any], Any]

Raises

ValueError – Raised if the function cannot be imported from path in the string.

deserialize_class(cls: str) → type[source]

Import a python class from a dotted import string (e.g., “quantify_scheduler.structure.model.DataStructure”).

Parameters

cls (str) –

Returns

The type you are trying to import.

Raises

ValueError – Raised if the class cannot be imported from path in the string.