Serialization API¶

Program¶

The object returned by the program context manager. It can be serialized to and from a protobuf binary for storage or transfer.

Program ¶

Program(program: Optional[QuaProgram] = None)

The Program class encapsulates a QuaProgram protobuf object along with additional metadata. It provides properties to access the program's state, including the capabilities used and whether it is currently being edited (is_in_scope). Additionally, it includes methods to serialize and deserialize the QuaProgram to and from various formats.

This class is used internally during construction (within ProgramScope) and externally as a read-only API for users. Protected methods (prefixed with _) are intended only for internal use during the building phase.

from_file `classmethod` ¶

from_file(path: Union[str, Path]) -> Program

Deserialize the program from a protobuf binary file.

PARAMETER	DESCRIPTION
`path`	The file path to read the serialized program from. TYPE: `Union[str, Path]`

RETURNS	DESCRIPTION
`Program`	The deserialized program.

from_protobuf `classmethod` ¶

from_protobuf(binary: bytes) -> Program

Deserialize the program from a protobuf binary.

PARAMETER	DESCRIPTION
`binary`	The protobuf binary to deserialize. TYPE: `bytes`

RETURNS	DESCRIPTION
`Program`	The deserialized program.

to_file ¶

to_file(
    path: Union[str, Path], config: FullQuaConfig
) -> None

Serialize the program to a protobuf binary and write it to a file.

PARAMETER	DESCRIPTION
`path`	The file path to write the serialized program to. TYPE: `Union[str, Path]`
`config`	The QUA configuration to embed in the serialized program. TYPE: `FullQuaConfig`

to_protobuf ¶

to_protobuf(config: FullQuaConfig) -> bytes

Serialize the program to a protobuf binary.

PARAMETER	DESCRIPTION
`config`	The QUA configuration to embed in the serialized program. TYPE: `FullQuaConfig`

RETURNS	DESCRIPTION
`bytes`	The serialized program as a protobuf binary.

Script Generation and Comparison¶

Functions for turning a Program into a standalone Python script, and for comparing two programs for structural equality.

generate_qua_script ¶

generate_qua_script(
    prog: Program, config: Optional[FullQuaConfig] = None
) -> str

Serializes a QUA program into a runnable QUA Python script.

The returned string is standalone Python source that reconstructs the given program, useful for debugging, sharing, or archiving a program.

Note

This function must be called outside of a program() scope.

Note

In some cases the serialization may be incomplete. When that happens, the generated script silently contains a SERIALIZATION WAS NOT COMPLETE comment block with the raw protobuf representation of the program. This indicates a problem in the serialization itself and should be reported to Quantum Machines.

PARAMETER	DESCRIPTION
`prog`	The QUA `program()` object to serialize. TYPE: `Program`
`config`	A QUA configuration to embed in the generated script. When omitted, the script is generated without a configuration. TYPE: `Optional[FullQuaConfig]` DEFAULT: `None`

RETURNS	DESCRIPTION
`str`	The generated QUA Python script as a string.

RAISES	DESCRIPTION
`RuntimeError`	If called inside a QUA program scope, or if the given config is invalid.

assert_programs_are_equal ¶

assert_programs_are_equal(
    prog1: QuaProgram, prog2: QuaProgram
) -> None

Asserts that two QUA programs are structurally equivalent.

Both programs are first normalized with standardize_program_for_comparison, so that differences that do not affect runtime behavior (source locations, variable and stream names, result-analysis ordering) are ignored.

PARAMETER	DESCRIPTION
`prog1`	The first program to compare. TYPE: `QuaProgram`
`prog2`	The second program to compare. TYPE: `QuaProgram`

RAISES	DESCRIPTION
`AssertionError`	If the two programs are not structurally equivalent.