classiq 0.45.1__py3-none-any.whl → 0.46.1__py3-none-any.whl

classiq/interface/generator/hardware/hardware_data.py

@@ -22,6 +22,24 @@ BACKEND_VALIDATION_ERROR_MESSAGE = (
 
 
 class HardwareData(pydantic.BaseModel):
+    """
+    Hardware-specific settings used in quantum circuit synthesis,
+    including basis gates, connectivity map, and connectivity symmetry.
+
+    Attributes:
+        basis_gates (List[str]):
+            The basis gates of the hardware, used during model optimization.
+            If not provided, default values are used based on the connectivity map's symmetry.
+
+        connectivity_map(Optional[ConnectivityMap]):
+            The qubit connectivity map, defined as a list of qubit pairs [[q0, q1], [q1, q2],...].
+            If not provided, the hardware is assumed to be fully connected.
+
+        is_symmetric_connectivity(bool):
+            Indicates whether the coupling map forms an undirected graph, meaning
+            that both qubits in each pair can act as control and target. Defaults to True.
+    """
+
     basis_gates: List[str] = pydantic.Field(
         default=list(),
         description="The basis gates of the hardware. "
@@ -101,6 +119,12 @@ class HardwareData(pydantic.BaseModel):
 
 
 class CustomHardwareSettings(HardwareData):
+    """
+    Custom hardware settings for quantum circuit synthesis.
+    This class inherits from HardwareData (please see class for more details)
+
+    """
+
     _width: Optional[int] = pydantic.PrivateAttr(default=None)
 
     @pydantic.validator("basis_gates")
@@ -180,4 +204,17 @@ def _symmetrize_connectivity_map(connectivity_map: ConnectivityMap) -> Connectiv
 
 
 class SynthesisHardwareData(HardwareData):
+    """
+    Represents the synthesis-specific hardware data for a quantum circuit.
+
+    This class extends `HardwareData` and includes additional attributes that
+    pertain specifically to the hardware used during the synthesis of a quantum circuit.
+
+    Attributes:
+        backend_data (Optional[BackendPreferences]):
+            Preferences for the backend used during the synthesis process.
+            This can include specific backend configurations or settings.
+            Defaults to `None`.
+    """
+
     backend_data: Optional[BackendPreferences]

classiq/interface/generator/model/constraints.py

@@ -31,7 +31,24 @@ def optimization_parameter_type_from_string(param: str) -> OptimizationParameter
 
 class Constraints(BaseModel, extra=Extra.forbid):
     """
-    Input constraints for the generated quantum circuit.
+    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:
+        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`
     """
 
     max_width: Optional[pydantic.PositiveInt] = pydantic.Field(

classiq/interface/generator/model/preferences/preferences.py

@@ -76,6 +76,55 @@ class TranspilationOption(StrEnum):
 
 
 class Preferences(pydantic.BaseModel, extra=pydantic.Extra.forbid):
+    """
+    Preferences for synthesizing a quantum circuit.
+
+    Attributes:
+        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:
+        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.
+    """
+
     _backend_preferences: Optional[BackendPreferences] = pydantic.PrivateAttr(
         default=None
     )
@@ -140,7 +189,6 @@ class Preferences(pydantic.BaseModel, extra=pydantic.Extra.forbid):
         description="Optimization timeout in seconds, or None for no "
         "optimization timeout (will still timeout when the generation timeout is over)",
     )
-
     random_seed: int = pydantic.Field(
         default_factory=create_random_seed,
         description="The random seed used for the generation",
@@ -208,6 +256,10 @@ class Preferences(pydantic.BaseModel, extra=pydantic.Extra.forbid):
 
     @property
     def backend_preferences(self) -> 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.
+
+        """
         if self.backend_name is None or self.backend_service_provider is None:
             return None
         if self._backend_preferences is None:

classiq/interface/generator/model/quantum_register.py

@@ -80,7 +80,7 @@ class QReg:
         """Initializes a new QReg with the specified number of qubits.
 
         Args:
-            size (int): The number of qubits in the QReg.
+            size: The number of qubits in the QReg.
         """
         if size <= 0:
             raise ClassiqQRegError(f"Cannot create {size} new qubits")

classiq/interface/generator/quantum_program.py

@@ -135,11 +135,10 @@ class QuantumProgram(VersionedModel, CircuitCodeInterface):
 
     def save_results(self, filename: Optional[Union[str, Path]] = None) -> None:
         """
-        Saves quantum program results as json.
+        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
         """
@@ -151,6 +150,15 @@ class QuantumProgram(VersionedModel, CircuitCodeInterface):
 
     @classmethod
     def from_qprog(cls, qprog: str) -> "QuantumProgram":
+        """
+        Creates a `QuantumProgram` instance from a raw quantum program string.
+
+        Args:
+            qprog: The raw quantum program in string format.
+
+        Returns:
+            QuantumProgram: The `QuantumProgram` instance.
+        """
         return cls.parse_raw(qprog)
 
     @property

classiq/interface/generator/transpiler_basis_gates.py

@@ -86,6 +86,10 @@ class LowerValsEnum(StrEnum):
 if TYPE_CHECKING:
     # A subset of the gates for better type checking
     class TranspilerBasisGates(StrEnum):
+        """
+        A subset of the gates used in the transpiler.
+        """
+
         X = "x"
         CX = "cx"
         CZ = "cz"

classiq/interface/generator/types/builtin_enum_declarations.py

@@ -1,20 +1,134 @@
+# This file was generated automatically - do not edit manually
+
 from enum import IntEnum
 
-from classiq.interface.chemistry.elements import ELEMENTS
-from classiq.interface.chemistry.ground_state_problem import FermionMapping
-from classiq.interface.generator.types.enum_declaration import EnumDeclaration
 
-ELEMENT = EnumDeclaration(
-    name="Element", members={element: idx for idx, element in enumerate(ELEMENTS)}
-)
+class Element(IntEnum):
+    H = 0
+    He = 1
+    Li = 2
+    Be = 3
+    B = 4
+    C = 5
+    N = 6
+    O = 7  # noqa: E741
+    F = 8
+    Ne = 9
+    Na = 10
+    Mg = 11
+    Al = 12
+    Si = 13
+    P = 14
+    S = 15
+    Cl = 16
+    Ar = 17
+    K = 18
+    Ca = 19
+    Sc = 20
+    Ti = 21
+    V = 22
+    Cr = 23
+    Mn = 24
+    Fe = 25
+    Co = 26
+    Ni = 27
+    Cu = 28
+    Zn = 29
+    Ga = 30
+    Ge = 31
+    As = 32
+    Se = 33
+    Br = 34
+    Kr = 35
+    Rb = 36
+    Sr = 37
+    Y = 38
+    Zr = 39
+    Nb = 40
+    Mo = 41
+    Tc = 42
+    Ru = 43
+    Rh = 44
+    Pd = 45
+    Ag = 46
+    Cd = 47
+    In = 48
+    Sn = 49
+    Sb = 50
+    Te = 51
+    I = 52  # noqa: E741
+    Xe = 53
+    Cs = 54
+    Ba = 55
+    La = 56
+    Ce = 57
+    Pr = 58
+    Nd = 59
+    Pm = 60
+    Sm = 61
+    Eu = 62
+    Gd = 63
+    Tb = 64
+    Dy = 65
+    Ho = 66
+    Er = 67
+    Tm = 68
+    Yb = 69
+    Lu = 70
+    Hf = 71
+    Ta = 72
+    W = 73
+    Re = 74
+    Os = 75
+    Ir = 76
+    Pt = 77
+    Au = 78
+    Hg = 79
+    Tl = 80
+    Pb = 81
+    Bi = 82
+    Po = 83
+    At = 84
+    Rn = 85
+    Fr = 86
+    Ra = 87
+    Ac = 88
+    Th = 89
+    Pa = 90
+    U = 91
+    Np = 92
+    Pu = 93
+    Am = 94
+    Cm = 95
+    Bk = 96
+    Cf = 97
+    Es = 98
+    Fm = 99
+    Md = 100
+    No = 101
+    Lr = 102
+    Rf = 103
+    Db = 104
+    Sg = 105
+    Bh = 106
+    Hs = 107
+    Mt = 108
+    Ds = 109
+    Rg = 110
+    Cn = 111
+    Nh = 112
+    Fl = 113
+    Mc = 114
+    Lv = 115
+    Ts = 116
+    Og = 117
+
 
-FERMION_MAPPING = EnumDeclaration(
-    name="FermionMapping",
-    members={
-        mapping.name: idx  # type:ignore[attr-defined]
-        for idx, mapping in enumerate(FermionMapping)
-    },
-)
+class FermionMapping(IntEnum):
+    JORDAN_WIGNER = 0
+    PARITY = 1
+    BRAVYI_KITAEV = 2
+    FAST_BRAVYI_KITAEV = 3
 
 
 class FinanceFunctionType(IntEnum):
@@ -52,11 +166,12 @@ class QSVMFeatureMapEntanglement(IntEnum):
     PAIRWISE = 4
 
 
-for enum_decl in list(vars().values()):
-    if isinstance(enum_decl, EnumDeclaration):
-        EnumDeclaration.BUILTIN_ENUM_DECLARATIONS[enum_decl.name] = enum_decl
-    elif isinstance(enum_decl, type) and issubclass(enum_decl, IntEnum):
-        EnumDeclaration.BUILTIN_ENUM_DECLARATIONS[enum_decl.__name__] = EnumDeclaration(
-            name=enum_decl.__name__,
-            members={enum_val.name: enum_val.value for enum_val in enum_decl},
-        )
+__all__ = [
+    "Element",
+    "FermionMapping",
+    "FinanceFunctionType",
+    "LadderOperator",
+    "Optimizer",
+    "Pauli",
+    "QSVMFeatureMapEntanglement",
+]

classiq/interface/generator/types/enum_declaration.py

@@ -1,6 +1,6 @@
 from collections import Counter
 from enum import Enum, EnumMeta, IntEnum
-from typing import ClassVar, Dict
+from typing import Dict
 
 import pydantic
 
@@ -16,8 +16,6 @@ class EnumDeclaration(HashableASTNode):
         description="Dictionary of member names and their values",
     )
 
-    BUILTIN_ENUM_DECLARATIONS: ClassVar[Dict[str, "EnumDeclaration"]] = {}
-
     @pydantic.validator("members")
     def _validate_members(cls, members: Dict[str, int]) -> Dict[str, int]:
         underscore_members = [

classiq/interface/generator/types/struct_declaration.py

@@ -1,4 +1,4 @@
-from typing import Any, ClassVar, Dict, Mapping
+from typing import Any, Dict, Mapping
 
 import pydantic
 
@@ -15,8 +15,6 @@ class StructDeclaration(HashableASTNode):
         description="Dictionary of variable names and their classical types",
     )
 
-    BUILTIN_STRUCT_DECLARATIONS: ClassVar[Dict[str, "StructDeclaration"]] = {}
-
     def validate_fields(self, fields: Mapping[str, Any]) -> None:
         expected_field_names = list(self.variables.keys())
         received_field_names = list(fields.keys())

classiq/interface/hardware.py

@@ -7,6 +7,11 @@ from classiq.interface.enum_utils import StrEnum
 
 
 class Provider(StrEnum):
+    """
+    This class defines all Providers that Classiq supports.
+    This is mainly used in backend_preferences when specifying where do we want to execute the defined model.
+    """
+
     IBM_QUANTUM = "IBM Quantum"
     AZURE_QUANTUM = "Azure Quantum"
     AMAZON_BRAKET = "Amazon Braket"

classiq/interface/ide/visual_model.py

@@ -33,7 +33,7 @@ class ProgramData(pydantic.BaseModel):
 
 class OperationParameter(pydantic.BaseModel):
     label: str
-    value: Optional[float]
+    value: Optional[str]
 
 
 class OperationLink(pydantic.BaseModel):

classiq/interface/model/classical_parameter_declaration.py

@@ -2,6 +2,7 @@ from typing import Any, Dict, Literal
 
 import pydantic
 
+from classiq.interface.exceptions import ClassiqInternalError
 from classiq.interface.generator.functions.concrete_types import ConcreteClassicalType
 from classiq.interface.helpers.pydantic_model_helpers import values_with_discriminator
 from classiq.interface.model.parameter import Parameter
@@ -19,6 +20,11 @@ class AnonClassicalParameterDeclaration(Parameter):
         )
 
     def rename(self, new_name: str) -> "ClassicalParameterDeclaration":
+        if type(self) not in (
+            AnonClassicalParameterDeclaration,
+            ClassicalParameterDeclaration,
+        ):
+            raise ClassiqInternalError
         return ClassicalParameterDeclaration(**{**self.__dict__, "name": new_name})
 
 

classiq/interface/model/inplace_binary_operation.py

@@ -1,15 +1,8 @@
 from typing import Literal, Mapping, Sequence
 
 from classiq.interface.enum_utils import StrEnum
-from classiq.interface.generator.functions.builtins.core_library import (
-    INTEGER_XOR_FUNCTION,
-    MODULAR_ADD_FUNCTION,
-)
 from classiq.interface.helpers.pydantic_model_helpers import nameables_to_dict
 from classiq.interface.model.handle_binding import ConcreteHandleBinding, HandleBinding
-from classiq.interface.model.quantum_function_declaration import (
-    NamedParamsQuantumFunctionDeclaration,
-)
 from classiq.interface.model.quantum_statement import HandleMetadata, QuantumOperation
 
 
@@ -17,13 +10,6 @@ class BinaryOperation(StrEnum):
     Addition = "inplace_add"
     Xor = "inplace_xor"
 
-    @property
-    def internal_function_declaration(self) -> NamedParamsQuantumFunctionDeclaration:
-        return {
-            BinaryOperation.Addition: MODULAR_ADD_FUNCTION,
-            BinaryOperation.Xor: INTEGER_XOR_FUNCTION,
-        }[self]
-
 
 class InplaceBinaryOperation(QuantumOperation):
     kind: Literal["InplaceBinaryOperation"]

classiq/interface/model/model.py

@@ -1,5 +1,5 @@
 from collections import Counter
-from typing import List, Literal, Mapping, NewType, Set
+from typing import List, Literal, Mapping, NewType
 
 import pydantic
 
@@ -54,9 +54,6 @@ class VersionedSerializedModel(VersionedModel):
 
 
 class Model(VersionedModel, ASTNode):
-    """
-    All the relevant data for generating quantum circuit in one place.
-    """
 
     kind: Literal["user"] = pydantic.Field(default=USER_MODEL_MARKER)
 
@@ -133,20 +130,6 @@ class Model(VersionedModel, ASTNode):
             functions.append(_create_empty_main_function())
         return functions
 
-    @pydantic.validator("types")
-    def types_validator(cls, types: List[StructDeclaration]) -> List[StructDeclaration]:
-        user_defined_types: Set[str] = set()
-        for ctype in types:
-            if ctype.name in StructDeclaration.BUILTIN_STRUCT_DECLARATIONS:
-                raise ClassiqValueError(
-                    TYPE_NAME_CONFLICT_BUILTIN.format(name=ctype.name)
-                )
-            if ctype.name in user_defined_types:
-                raise ClassiqValueError(TYPE_NAME_CONFLICT_USER.format(name=ctype.name))
-            user_defined_types.add(ctype.name)
-
-        return types
-
     def get_model(self) -> SerializedModel:
         return SerializedModel(
             self.json(exclude_defaults=True, exclude_unset=True, indent=2)

classiq/interface/model/port_declaration.py

@@ -2,7 +2,7 @@ from typing import Any, Dict, Literal, Mapping, Optional
 
 import pydantic
 
-from classiq.interface.exceptions import ClassiqValueError
+from classiq.interface.exceptions import ClassiqInternalError, ClassiqValueError
 from classiq.interface.generator.expressions.expression import Expression
 from classiq.interface.generator.functions.concrete_types import ConcreteQuantumType
 from classiq.interface.generator.functions.port_declaration import (
@@ -19,7 +19,7 @@ class AnonPortDeclaration(Parameter):
     kind: Literal["PortDeclaration"]
 
     quantum_type: ConcreteQuantumType
-    size: Optional[Expression] = pydantic.Field(default=None)
+    size: Optional[Expression] = pydantic.Field(default=None, exclude=True)
     direction: PortDeclarationDirection
 
     @pydantic.root_validator(pre=True)
@@ -44,6 +44,8 @@ class AnonPortDeclaration(Parameter):
         return QuantumVariableDeclaration._propagate_size_to_type(size, values)
 
     def rename(self, new_name: str) -> "PortDeclaration":
+        if type(self) not in (AnonPortDeclaration, PortDeclaration):
+            raise ClassiqInternalError
         return PortDeclaration(**{**self.__dict__, "name": new_name})
 
 

classiq/interface/model/quantum_function_declaration.py

@@ -1,6 +1,5 @@
 from typing import (
     Any,
-    ClassVar,
     Dict,
     Literal,
     Sequence,
@@ -11,6 +10,7 @@ from typing import (
 import pydantic
 from typing_extensions import Annotated
 
+from classiq.interface.exceptions import ClassiqInternalError
 from classiq.interface.generator.arith.register_user_input import RegisterUserInput
 from classiq.interface.generator.function_params import ArithmeticIODict, PortDirection
 from classiq.interface.generator.functions.function_declaration import (
@@ -132,7 +132,22 @@ class AnonQuantumFunctionDeclaration(FunctionDeclaration):
         }
 
     def rename(self, new_name: str) -> "QuantumFunctionDeclaration":
-        return QuantumFunctionDeclaration(**{**self.__dict__, "name": new_name})
+        if type(self) not in (
+            AnonQuantumFunctionDeclaration,
+            QuantumFunctionDeclaration,
+            NamedParamsQuantumFunctionDeclaration,
+        ):
+            raise ClassiqInternalError
+        return QuantumFunctionDeclaration(
+            **{
+                **{
+                    field_name: field_value
+                    for field_name, field_value in self.__dict__.items()
+                    if field_name in AnonQuantumFunctionDeclaration.__fields__
+                },
+                "name": new_name,
+            }
+        )
 
 
 class AnonQuantumOperandDeclaration(AnonQuantumFunctionDeclaration):
@@ -148,6 +163,8 @@ class AnonQuantumOperandDeclaration(AnonQuantumFunctionDeclaration):
         return values_with_discriminator(values, "kind", "QuantumOperandDeclaration")
 
     def rename(self, new_name: str) -> "QuantumOperandDeclaration":
+        if type(self) not in (AnonQuantumOperandDeclaration, QuantumOperandDeclaration):
+            raise ClassiqInternalError
         return QuantumOperandDeclaration(**{**self.__dict__, "name": new_name})
 
 
@@ -157,10 +174,6 @@ AnonQuantumFunctionDeclaration.update_forward_refs()
 class QuantumFunctionDeclaration(AnonQuantumFunctionDeclaration):
     name: str
 
-    BUILTIN_FUNCTION_DECLARATIONS: ClassVar[
-        Dict[str, "NamedParamsQuantumFunctionDeclaration"]
-    ] = {}
-
 
 class QuantumOperandDeclaration(
     QuantumFunctionDeclaration, AnonQuantumOperandDeclaration

classiq/interface/model/quantum_lambda_function.py

@@ -1,4 +1,4 @@
-from typing import TYPE_CHECKING, Dict, List, Optional, Union, cast
+from typing import TYPE_CHECKING, Callable, Dict, List, Optional, Union, cast
 
 import pydantic
 
@@ -19,6 +19,7 @@ class QuantumLambdaFunction(ASTNode):
 
     rename_params: Dict[str, str] = pydantic.Field(
         default_factory=dict,
+        exclude=False,
     )
 
     pos_rename_params: List[str] = pydantic.Field(
@@ -34,6 +35,15 @@ class QuantumLambdaFunction(ASTNode):
         default=None
     )
 
+    _py_callable: Callable = pydantic.PrivateAttr(default=None)
+
+    @property
+    def py_callable(self) -> Callable:
+        return self._py_callable
+
+    def set_py_callable(self, py_callable: Callable) -> None:
+        self._py_callable = py_callable
+
     @property
     def func_decl(self) -> AnonQuantumOperandDeclaration:
         if self._func_decl is None:

classiq/interface/model/quantum_variable_declaration.py

@@ -14,7 +14,7 @@ from classiq.interface.model.quantum_type import (
 class QuantumVariableDeclaration(ASTNode):
     name: str
     quantum_type: ConcreteQuantumType
-    size: Optional[Expression] = pydantic.Field(default=None)
+    size: Optional[Expression] = pydantic.Field(default=None, exclude=True)
 
     @pydantic.validator("size")
     def _propagate_size_to_type(