See also

A Jupyter notebook version of this tutorial can be downloaded here.

Serialization & Deserialization

Qblox scheduler allows for serialization and deserialization of {class}~qblox_scheduler.QuantumDevice, {class}~qblox_scheduler.DeviceElement (e.g. {class}~qblox_scheduler.BasicTransmonElement) to and from JSON or YAML, either as strings or files. All subclasses also inherit this functionality.

Each class provides the following methods:

Serialization

• to_dict: Converts the object into a dictionary.

• to_yaml: Converts the object into a YAML string.

• to_yaml_file: Saves the YAML string to a file.

• to_json: Converts the object into a JSON string.

• to_json_file: Saves the JSON string to a file.

Deserialization

• from_dict: Creates a Python object from a dictionary.

• from_yaml: Creates a Python object from a YAML string.

• from_yaml_file: Reads a YAML file and converts it into the corresponding Python object.

• from_json: Creates a Python object from a JSON string.

• from_json_file: Reads a JSON file and converts it into the corresponding Python object.

Code examples

(De)Serializing a QuantumDevice object to YAML string

from qblox_scheduler import BasicTransmonElement, HardwareAgent, QuantumDevice

device = QuantumDevice("single_qubit_device")
q0 = BasicTransmonElement("q0")
device.add_element(q0)

device_yaml = device.to_yaml()

print(device_yaml)

!QuantumDevice
name: single_qubit_device
elements:
  q0: !BasicTransmonElement
    name: q0
    reset:
      name: reset
      duration: 0.0002
    rxy:
      name: rxy
      amp180: .nan
      beta: 0.0
      duration: 2e-08
      reference_magnitude:
        name: reference_magnitude
        dBm: .nan
        V: .nan
        A: .nan
    measure:
      name: measure
      pulse_type: SquarePulse
      pulse_amp: 0.25
      pulse_duration: 3e-07
      acq_channel: 0
      acq_delay: 0.0
      integration_time: 1e-06
      reset_clock_phase: true
      acq_weights_a: !numpy.ndarray
        dtype: float64
        shape: [0]
        data: []
      acq_weights_b: !numpy.ndarray
        dtype: float64
        shape: [0]
        data: []
      acq_weights_sampling_rate: 1000000000.0
      acq_weight_type: SSB
      acq_rotation: 0.0
      acq_threshold: 0.0
      num_points: 1
      reference_magnitude:
        name: reference_magnitude
        dBm: .nan
        V: .nan
        A: .nan
    pulse_compensation:
      name: pulse_compensation
      max_compensation_amp: .nan
      time_grid: .nan
      sampling_rate: .nan
    ports:
      name: ports
      microwave: q0:mw
      flux: q0:fl
      readout: q0:res
    clock_freqs:
      name: clock_freqs
      f01: .nan
      f12: .nan
      readout: .nan
edges: {}
cfg_sched_repetitions: 1024
keep_original_schedule: true
hardware_config:
scheduling_strategy: asap

Note

The concept is identical when working with JSON : users are free to choose whichever format they prefer. Our documentation primarily uses YAML for examples and explanations, as it offers better readability for configuration files.

To deserialize (reconstruct) an object from a YAML string, simply use the corresponding classes from_yaml method:

deserialized_device = QuantumDevice.from_yaml(device_yaml)

(De)Serializing a QuantumDevice object to a YAML file

You can optionally provide a folder path as an argument to the to_yaml_file method. Qblox scheduler will automatically create a new YAML file in that location. The add_timestamp parameter controls whether a timestamp is appended to the filename. Use it to create a new file each time, or disable it to overwrite an existing file with the same name. The following line will save the QuantumDevice to the current folder.

device.to_yaml_file(".")

'./single_qubit_device_2025-10-30_00-43-02_UTC.yaml'

and the timestamp can be omitted by setting add_timestamp=False:

device.to_yaml_file(".", add_timestamp=False)  # Saves to "single_qubit_device.yaml"

'./single_qubit_device.yaml'

You also have the option to save the file automatically to the current data directory managed by the {class}HardwareAgent, using the object itself. The default directory can be controlled via the default_output_dir parameter. For example, if you set default_output_dir=".\\temp", a temp file will be created in your local directory and saves will be done there.

hw_agent = HardwareAgent(hardware_configuration={}, quantum_device_configuration=device)
device.to_yaml_file()  # Saves to "{datadir_path}/single_qubit_device_2025-09-10_13-36-59_UTC.yaml"

'/root/qblox_data/single_qubit_device_2025-10-30_00-43-02_UTC.yaml'

Finally, loading the object from the YAML file is done using the from_yaml_file method:

deserialized_device = QuantumDevice.from_yaml_file("single_qubit_device.yaml")

As a final note, {class}~qblox_scheduler.Schedule objects support only JSON serialization and deserialization. All other points mentioned above still apply.