Synthesis

synthesize

synthesize(
    model: SerializedModel | BaseQFunc,
    auto_show: bool = False,
    constraints: Constraints | None = None,
    preferences: Preferences | None = None,
) -> QuantumProgram

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

Parameters:

Name	Type	Description	Default
`model`	`SerializedModel \| BaseQFunc`	The entry point of the Qmod model - a qfunc named 'main' (or alternatively the output of 'create_model').	required
`auto_show`	`bool`	Whether to 'show' the synthesized model (False by default).	`False`
`constraints`	`Constraints \| None`	Constraints for the synthesis of the model. See Constraints (Optional).	`None`
`preferences`	`Preferences \| None`	Preferences for the synthesis of the model. See Preferences (Optional).	`None`

Returns:

Name	Type	Description
`QuantumProgram`	`QuantumProgram`	Quantum program. (See: QuantumProgram)

show

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

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

Parameters:

Name	Type	Description	Default
`quantum_program`	`QuantumProgram`	The quantum program to be displayed.	required
`display_url`	`bool`	Whether to print the url	`True`

Links

Visualization tool

QuantumProgram

Bases: VersionedModel, CircuitCodeInterface

Methods:

Name	Description
`get_debug_info`
`raise_warnings`	Raises all warnings that were collected during synthesis.
`save_results`	Saves quantum program results as json into a file.
`to_base_program`
`to_program`

Attributes:

Name	Type	Description
`compiled_qmod`	`Model \| None`
`compressed_debug_info`	`bytes \| None`
`creation_time`	`str`
`data`	`GeneratedCircuitData`
`execution_primitives_input`	`PrimitivesInput \| None`
`hardware_data`	`SynthesisHardwareData`
`model`	`ExecutionModel`
`program_circuit`	`CircuitCodeInterface`
`program_id`	`str`
`synthesis_warnings`	`list[str] \| None`
`transpiled_circuit`	`TranspiledCircuitData \| None`

compiled_qmod

compiled_qmod: Model | None = Field(default=None)

compressed_debug_info

compressed_debug_info: bytes | None = Field(default=None)

creation_time

creation_time: str = Field(
    default_factory=_get_formatted_utc_current_time
)

data

data: GeneratedCircuitData

execution_primitives_input

execution_primitives_input: PrimitivesInput | None = Field(
    default=None
)

hardware_data

hardware_data: SynthesisHardwareData

model

model: ExecutionModel

program_circuit

program_circuit: CircuitCodeInterface

program_id

program_id: str = Field(default_factory=get_uuid_as_str)

synthesis_warnings

synthesis_warnings: list[str] | None = Field(default=None)

transpiled_circuit

transpiled_circuit: TranspiledCircuitData | None = Field(
    default=None
)

get_debug_info

get_debug_info() -> list[FunctionDebugInfoInterface] | None

raise_warnings

raise_warnings() -> None

Raises all warnings that were collected during synthesis.

save_results

save_results(filename: str | Path | None = 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(
    instruction_set: QuantumInstructionSet | None = 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`.
`optimization_level`	`OptimizationLevel)`	The optimization level used during synthesis (0-3);
`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_backend_name`
`validate_output_format`

backend_name

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

backend_preferences

backend_preferences: BackendPreferences | None

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: (
    Provider | ProviderVendor | str | None
) = 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=LIGHT,
    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: PositiveInt | None = 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: bool | None = 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: PositiveInt | None = Field(
    None,
    description="Maximum iterations for the Solovay-Kitaev algorithm (if applied).",
)

symbolic_loops

symbolic_loops: bool = Field(default=False)

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: PositiveInt | None,
    info: ValidationInfo,
) -> PositiveInt | None

validate_backend

validate_backend() -> Self

validate_backend_name

validate_backend_name(
    backend_name: str | None,
) -> str | None

validate_output_format

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

set_preferences

set_preferences(
    serialized_model: SerializedModel,
    preferences: Preferences | None = 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`	`Preferences \| None`	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: (
        ExecutionPreferences | None
    ) = 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`	`ExecutionPreferences \| None`	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: QuantumProgram,
    preferences: ExecutionPreferences,
) -> QuantumProgram

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`.
`optimization_parameter`	`OptimizationParameterType`	Determines if and how the synthesis engine should optimize the solution. Defaults to `NO_OPTIMIZATION`. See `OptimizationParameterType`

max_width

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

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: Constraints | None = 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`	`Constraints \| None`	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.

create_model

create_model(
    entry_point: QFunc | GenerativeQFunc,
    constraints: Constraints | None = None,
    execution_preferences: (
        ExecutionPreferences | None
    ) = None,
    preferences: Preferences | None = None,
    classical_execution_function: CFunc | None = None,
    out_file: str | None = None,
) -> SerializedModel

Create a serialized model from a given Qmod entry function and additional parameters.

Parameters:

Name	Type	Description	Default
`entry_point`	`QFunc \| GenerativeQFunc`	The entry point function for the model, which must be a QFunc named 'main'.	required
`constraints`	`Constraints \| None`	Constraints for the synthesis of the model. See Constraints (Optional).	`None`
`execution_preferences`	`ExecutionPreferences \| None`	Preferences for the execution of the model. See ExecutionPreferences (Optional).	`None`
`preferences`	`Preferences \| None`	Preferences for the synthesis of the model. See Preferences (Optional).	`None`
`classical_execution_function`	`CFunc \| None`	A function for the classical execution logic, which must be a CFunc (Optional).	`None`
`out_file`	`str \| None`	File path to write the Qmod model in native Qmod representation to (Optional).	`None`

Returns:

Name	Type	Description
`SerializedModel`	`SerializedModel`	A serialized model.

Raises:

Type	Description
`ClassiqError`	If the entry point function is not named 'main'.

write_qmod

Functions:

Name	Description
`prepare_write_qmod_model`
`write_qmod`	Creates a native Qmod file from a serialized model and outputs the synthesis options (Preferences and Constraints) to a file.

prepare_write_qmod_model

prepare_write_qmod_model(
    model: SerializedModel | QFunc | GenerativeQFunc,
    symbolic_only: bool,
) -> Model

write_qmod

write_qmod(
    model: SerializedModel | QFunc | GenerativeQFunc,
    name: str,
    directory: Path | None = None,
    decimal_precision: int = DEFAULT_DECIMAL_PRECISION,
    symbolic_only: bool = True,
) -> None

Creates a native Qmod file from a serialized model and outputs the synthesis options (Preferences and Constraints) to a file. The native Qmod file may be uploaded to the Classiq IDE.

Parameters:

Name	Type	Description	Default
`model`	`SerializedModel \| QFunc \| GenerativeQFunc`	The entry point of the Qmod model - a qfunc named 'main' (or alternatively the output of 'create_model').	required
`name`	`str`	The name to save the file by.	required
`directory`	`Path \| None`	The directory to save the files in. If None, the current working directory is used.	`None`
`decimal_precision`	`int`	The number of decimal places to use for numbers, set to 4 by default.	`DEFAULT_DECIMAL_PRECISION`
`symbolic_only`	`bool`	If True keep function definitions un-expanded and symbolic (note that Qmod functions with parameters of Python types are not supported in this mode)	`True`

Returns:

Type	Description
`None`	None

qasm_to_qmod

qasm_to_qmod(qasm: str, qmod_format: QmodFormat) -> str

Decompiles QASM to Native/Python Qmod.

Returns Qmod code as a string. Native Qmod can be synthesized in the Classiq IDE, while Python Qmod can be copy-pasted to a Python file (.py) and synthesized by calling synthesize(main).

Parameters:

Name	Type	Description	Default
`qasm`	`str`	QASM 2 or QASM 3 code	required
`qmod_format`	`QmodFormat`	The requested output format	required

Returns:

Type	Description
`str`	The decompiled Qmod program