Skip to content

Synthesis

synthesize

synthesize(
    serialized_model: SerializedModel,
    auto_show: bool = False,
) -> SerializedQuantumProgram

Synthesize a model with the Classiq engine to receive a quantum program. More details

Parameters:

Name Type Description Default
serialized_model SerializedModel

A model object serialized as a string.

required
auto_show bool

boolean. whether to call show on the output

False

Returns:

Name Type Description
SerializedQuantumProgram SerializedQuantumProgram

Quantum program serialized as a string. (See: QuantumProgram)

show

show(
    quantum_program: SerializedQuantumProgram,
    display_url: bool = True,
) -> None

Displays the interactive representation of the quantum program in the Classiq IDE.

Parameters:

Name Type Description Default
quantum_program SerializedQuantumProgram

The serialized quantum program to be displayed.

required
display_url bool

Whether to print the url

True

QuantumProgram

Bases: VersionedModel, CircuitCodeInterface

Methods:

Name Description
from_qprog

Creates a QuantumProgram instance from a raw quantum program string.

get_registers_initialization
save_results

Saves quantum program results as json into a file.

to_base_program
to_program

Attributes:

Name Type Description
creation_time str
data GeneratedCircuitData
debug_info Optional[list[FunctionDebugInfoInterface]]
execution_primitives_input Optional[PrimitivesInput]
hardware_data SynthesisHardwareData
initial_values Optional[InitialConditions]
model ExecutionModel
program_circuit CircuitCodeInterface
program_id str
synthesis_duration Optional[SynthesisStepDurations]
transpiled_circuit Optional[TranspiledCircuitData]

creation_time

creation_time: str = Field(
    default_factory=_get_formatted_utc_current_time
)

data

data: GeneratedCircuitData

debug_info

debug_info: Optional[list[FunctionDebugInfoInterface]] = (
    Field(default=None)
)

execution_primitives_input

execution_primitives_input: Optional[PrimitivesInput] = (
    Field(default=None)
)

hardware_data

hardware_data: SynthesisHardwareData

initial_values

initial_values: Optional[InitialConditions] = Field(
    default=None
)

model

model: ExecutionModel

program_circuit

program_circuit: CircuitCodeInterface

program_id

program_id: str = Field(default_factory=get_uuid_as_str)

synthesis_duration

synthesis_duration: Optional[SynthesisStepDurations] = (
    Field(default=None)
)

transpiled_circuit

transpiled_circuit: Optional[TranspiledCircuitData] = Field(
    default=None
)

from_qprog

from_qprog(qprog: str) -> QuantumProgram

Creates a QuantumProgram instance from a raw quantum program string.

Parameters:

Name Type Description Default
qprog str

The raw quantum program in string format.

required

Returns:

Name Type Description
QuantumProgram QuantumProgram

The QuantumProgram instance.

get_registers_initialization

get_registers_initialization(
    initial_values: InitialConditions,
) -> dict[RegisterName, RegisterInitialization]

save_results

save_results(
    filename: Optional[Union[str, Path]] = None
) -> None

Saves quantum program results as json into a file. Parameters: filename (Union[str, Path]): Optional, path + filename of file. If filename supplied add .json suffix. Returns: None

to_base_program

to_base_program() -> QuantumBaseCode

to_program

to_program(
    initial_values: Optional[InitialConditions] = None,
    instruction_set: Optional[QuantumInstructionSet] = None,
) -> QuantumCode

Preferences

Bases: BaseModel

Preferences for synthesizing a quantum circuit.

Attributes:

Name Type Description
machine_precision int

Specifies the precision used for quantum operations. Defaults to DEFAULT_MACHINE_PRECISION.

backend_service_provider str

The provider company or cloud service for the requested backend. Defaults to None.

backend_name str

The name of the requested backend or target. Defaults to None.

custom_hardware_settings CustomHardwareSettings

Defines custom hardware settings for optimization. This field is ignored if backend preferences are specified.

debug_mode bool

If True, debug information is added to the synthesized result, potentially slowing down the synthesis. Useful for executing interactive algorithms. Defaults to True.

output_format List[QuantumFormat]

Lists the output format(s) for the quantum circuit. Defaults to [QuantumFormat.QASM]. QuantumFormat Options: - QASM = "qasm" - QSHARP = "qsharp" - QIR = "qir" - IONQ = "ionq" - CIRQ_JSON = "cirq_json" - QASM_CIRQ_COMPATIBLE = "qasm_cirq_compatible"

pretty_qasm bool

If True, formats OpenQASM 2 outputs with line breaks inside gate declarations, improving readability. Defaults to True.

qasm3 Optional[bool]

If True, outputs OpenQASM 3.0 in addition to 2.0, applicable to relevant attributes in GeneratedCircuit. Defaults to None.

transpilation_option TranspilationOption

Sets the transpilation option to optimize the circuit. Defaults to AUTO_OPTIMIZE. See TranspilationOption

solovay_kitaev_max_iterations Optional[int]

Specifies the maximum number of iterations for the Solovay-Kitaev algorithm, if used. Defaults to None.

timeout_seconds int

Timeout setting for circuit synthesis in seconds. Defaults to 300.

optimization_timeout_seconds Optional[int]

Specifies the timeout for optimization in seconds, or None for no optimization timeout. This will still adhere to the overall synthesis timeout. Defaults to None.

random_seed int

Random seed for circuit synthesis.

Raises:

Type Description
ClassiqValueError
  • If the optimization timeout is greater than or equal to the synthesis timeout.
  • If the output_format contains duplicate entries.
  • If backend_name is provided without backend_service_provider or vice versa.
ValueError
  • If backend_service_provider is not valid.

Methods:

Name Description
make_output_format_list
optimization_timeout_less_than_generation_timeout
validate_backend
validate_output_format

Attributes:

Name Type Description
backend_name Optional[Union[PydanticBackendName, AllBackendsNameByVendor]]
backend_preferences Optional[BackendPreferences]

Returns the backend preferences. If the backend preferences are not provided, the function sets the backend preferences according to backend name and provider.

backend_service_provider Optional[Union[Provider, ProviderVendor, str]]
custom_hardware_settings CustomHardwareSettings
debug_mode bool
machine_precision PydanticMachinePrecision
optimization_level OptimizationLevel
optimization_timeout_seconds Optional[PositiveInt]
output_format PydanticConstrainedQuantumFormatList
pretty_qasm bool
qasm3 Optional[bool]
random_seed int
solovay_kitaev_max_iterations Optional[PositiveInt]
synthesize_all_separately bool
timeout_seconds PositiveInt
transpilation_option TranspilationOption

backend_name

backend_name: Optional[
    Union[PydanticBackendName, AllBackendsNameByVendor]
] = Field(
    default=None,
    description="Name of the requested backend or target.",
)

backend_preferences

backend_preferences: Optional[BackendPreferences]

Returns the backend preferences. If the backend preferences are not provided, the function sets the backend preferences according to backend name and provider.

backend_service_provider

backend_service_provider: Optional[
    Union[Provider, ProviderVendor, str]
] = Field(
    default=None,
    description="Provider company or cloud for the requested backend.",
)

custom_hardware_settings

custom_hardware_settings: CustomHardwareSettings = Field(
    default_factory=CustomHardwareSettings,
    description="Custom hardware settings which will be used during optimization. This field is ignored if backend preferences are given.",
)

debug_mode

debug_mode: bool = Field(
    default=True,
    description="Add debug information to the synthesized result. Setting this option to False can potentially speed up the synthesis, and is recommended for executing iterative algorithms.",
)

machine_precision

machine_precision: PydanticMachinePrecision = (
    DEFAULT_MACHINE_PRECISION
)

optimization_level

optimization_level: OptimizationLevel = Field(
    default=HIGH,
    description="The optimization level used during synthesis; determines the trade-off between synthesis speed and the quality of the results",
)

optimization_timeout_seconds

optimization_timeout_seconds: Optional[PositiveInt] = Field(
    default=None,
    description="Optimization timeout in seconds, or None for no optimization timeout (will still timeout when the generation timeout is over)",
)

output_format

output_format: PydanticConstrainedQuantumFormatList = Field(
    default=[QASM],
    description="The quantum circuit output format(s). ",
)

pretty_qasm

pretty_qasm: bool = Field(
    True,
    description="Prettify the OpenQASM2 outputs (use line breaks inside the gate declarations).",
)

qasm3

qasm3: Optional[bool] = Field(
    None,
    description="Output OpenQASM 3.0 instead of OpenQASM 2.0. Relevant only for the `qasm` and `transpiled_circuit.qasm` attributes of `GeneratedCircuit`.",
)

random_seed

random_seed: int = Field(
    default_factory=create_random_seed,
    description="The random seed used for the generation",
)

solovay_kitaev_max_iterations

solovay_kitaev_max_iterations: Optional[PositiveInt] = (
    Field(
        None,
        description="Maximum iterations for the Solovay-Kitaev algorithm (if applied).",
    )
)

synthesize_all_separately

synthesize_all_separately: bool = Field(
    default=False,
    description="If true, a heuristic is used to determine if a function should be synthesized separately",
    deprecated=True,
)

timeout_seconds

timeout_seconds: PositiveInt = Field(
    default=300, description="Generation timeout in seconds"
)

transpilation_option

transpilation_option: TranspilationOption = Field(
    default=AUTO_OPTIMIZE,
    description="If true, the returned result will contain a transpiled circuit and its depth",
)

make_output_format_list

make_output_format_list(output_format: Any) -> list

optimization_timeout_less_than_generation_timeout

optimization_timeout_less_than_generation_timeout(
    optimization_timeout_seconds: Optional[PositiveInt],
    info: ValidationInfo,
) -> Optional[PositiveInt]

validate_backend

validate_backend() -> Self

validate_output_format

validate_output_format(
    output_format: PydanticConstrainedQuantumFormatList,
    info: ValidationInfo,
) -> PydanticConstrainedQuantumFormatList

set_preferences

set_preferences(
    serialized_model: SerializedModel,
    preferences: Optional[Preferences] = None,
    **kwargs: Any
) -> SerializedModel

Overrides the preferences of a (serialized) model and returns the updated model.

Parameters:

Name Type Description Default
serialized_model SerializedModel

The model in serialized form.

required
preferences Optional[Preferences]

The new preferences to be set for the model. Can be passed as keyword arguments.

None

Returns:

Name Type Description
SerializedModel SerializedModel

The updated model with the new preferences applied.

set_execution_preferences

set_execution_preferences(
    serialized_model: SerializedModel,
    execution_preferences: Optional[
        ExecutionPreferences
    ] = None,
    **kwargs: Any
) -> SerializedModel

Overrides the execution preferences of a (serialized) model and returns the updated model.

Parameters:

Name Type Description Default
serialized_model SerializedModel

A serialization of the defined model.

required
execution_preferences Optional[ExecutionPreferences]

The new execution preferences to be set for the model. Can be passed as keyword arguments.

None

Returns: SerializedModel: The model with the attached execution preferences.

For more examples please see: set_execution_preferences

set_quantum_program_execution_preferences

set_quantum_program_execution_preferences(
    quantum_program: SerializedQuantumProgram,
    preferences: ExecutionPreferences,
) -> SerializedQuantumProgram

Constraints

Bases: BaseModel

Constraints for the quantum circuit synthesis engine.

This class is used to specify constraints such as maximum width, depth, gate count, and optimization parameters for the synthesis engine, guiding the generation of quantum circuits that satisfy these constraints.

Attributes:

Name Type Description
max_width int

Maximum number of qubits allowed in the generated quantum circuit. Defaults to None.

max_depth int

Maximum depth of the generated quantum circuit. Defaults to None.

max_gate_count Dict[TranspilerBasisGates, int]

A dictionary specifying the maximum allowed count for each type of gate in the quantum circuit. Defaults to an empty dictionary.

optimization_parameter OptimizationParameterType

Determines if and how the synthesis engine should optimize the solution. Defaults to NO_OPTIMIZATION. See OptimizationParameterType

Attributes:

Name Type Description
max_depth Optional[PositiveInt]
max_gate_count dict[TranspilerBasisGates, NonNegativeInt]
max_width Optional[PositiveInt]
model_config
optimization_parameter OptimizationParameterType

max_depth

max_depth: Optional[PositiveInt] = None

max_gate_count

max_gate_count: dict[
    TranspilerBasisGates, NonNegativeInt
] = Field(default_factory=lambda: defaultdict(int))

max_width

max_width: Optional[PositiveInt] = Field(
    default=None,
    description="Maximum number of qubits in generated quantum circuit",
)

model_config

model_config = ConfigDict(extra='forbid')

optimization_parameter

optimization_parameter: OptimizationParameterType = Field(
    default=NO_OPTIMIZATION,
    description="If set, the synthesis engine optimizes the solution according to that chosen parameter",
)

set_constraints

set_constraints(
    serialized_model: SerializedModel,
    constraints: Optional[Constraints] = None,
    **kwargs: Any
) -> SerializedModel

Overrides the constraints of a (serialized) model and returns the updated model.

Parameters:

Name Type Description Default
serialized_model SerializedModel

The model in serialized form.

required
constraints Optional[Constraints]

The new constraints to be set for the model. Can be passed as keyword arguments.

None

Returns:

Name Type Description
SerializedModel SerializedModel

The updated model with the new constraints applied.