classiq 0.102.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

classiq/evaluators/qmod_type_inference/quantum_type_comparison.py

@@ -0,0 +1,52 @@
+from classiq.interface.exceptions import (
+    ClassiqInternalExpansionError,
+)
+from classiq.interface.generator.expressions.expression import Expression
+from classiq.interface.generator.functions.type_name import TypeName
+from classiq.interface.model.quantum_type import (
+    QuantumBit,
+    QuantumBitvector,
+    QuantumNumeric,
+    QuantumType,
+)
+
+
+def _compare_expressions(expr1: Expression | None, expr2: Expression | None) -> bool:
+    if expr1 is None:
+        return expr2 is None
+    if expr2 is None:
+        return False
+    return expr1.expr == expr2.expr
+
+
+def compare_quantum_types(type_1: QuantumType, type_2: QuantumType) -> bool:
+    for qmod_type in (type_1, type_2):
+        if isinstance(qmod_type, TypeName) and not qmod_type.has_fields:
+            raise ClassiqInternalExpansionError("Quantum struct expected")
+    if isinstance(type_1, QuantumBit):
+        return isinstance(type_2, QuantumBit)
+    if isinstance(type_1, QuantumNumeric):
+        return (
+            isinstance(type_2, QuantumNumeric)
+            and _compare_expressions(type_1.size, type_2.size)
+            and _compare_expressions(type_1.is_signed, type_2.is_signed)
+            and _compare_expressions(type_1.fraction_digits, type_2.fraction_digits)
+        )
+    if isinstance(type_1, QuantumBitvector):
+        return (
+            isinstance(type_2, QuantumBitvector)
+            and _compare_expressions(type_1.length, type_2.length)
+            and compare_quantum_types(type_1.element_type, type_2.element_type)
+        )
+    if isinstance(type_1, TypeName):
+        return (
+            isinstance(type_2, TypeName)
+            and type_1.name == type_2.name
+            and all(
+                compare_quantum_types(field_type_1, field_type_2)
+                for field_type_1, field_type_2 in zip(
+                    type_1.fields.values(), type_2.fields.values(), strict=True
+                )
+            )
+        )
+    raise ClassiqInternalExpansionError(f"Unexpected type {type(type_1).__name__}")

classiq/execution/all_hardware_devices.py

@@ -1,7 +1,15 @@
-from classiq.interface.hardware import HardwareInformation
+from typing import TYPE_CHECKING
+
+from classiq.interface.hardware import HardwareInformation, Provider
 
 from classiq._internals import async_utils
 from classiq._internals.api_wrapper import ApiWrapper
+from classiq.execution.functions.util.parse_provider_backend import (
+    _PROVIDER_TO_CANONICAL_NAME,
+)
+
+if TYPE_CHECKING:
+    from pandas import DataFrame
 
 
 def get_all_hardware_devices() -> list[HardwareInformation]:
@@ -9,3 +17,53 @@ def get_all_hardware_devices() -> list[HardwareInformation]:
     Returns a list of all hardware devices known to Classiq.
     """
     return async_utils.run(ApiWrapper.call_get_all_hardware_devices())
+
+
+def _extract_relevant_hardware_fields_for_user(info: HardwareInformation) -> tuple:
+    return (
+        _PROVIDER_TO_CANONICAL_NAME[info.provider],
+        info.name,
+        info.number_of_qubits,
+        info.status.availability.is_available,
+        info.status.pending_jobs,
+        info.status.queue_time,
+    )
+
+
+_NON_DISPLAYED_DEVICES = [
+    (Provider.CLASSIQ, "simulator_statevector"),
+    (Provider.CLASSIQ, "nvidia_simulator_statevector"),
+    (Provider.GOOGLE, "cuquantum_statevector"),
+]
+
+
+def get_backend_details() -> "DataFrame":
+    """
+    Returns a pandas DataFrame containing hardware devices known to Classiq.
+    """
+    from pandas import DataFrame
+
+    devices = get_all_hardware_devices()
+    displayed_devices = [
+        device
+        for device in devices
+        if (device.provider, device.name) not in _NON_DISPLAYED_DEVICES
+    ]
+    # Remove "ibm_" prefix.
+    for device in displayed_devices:
+        if device.provider == Provider.IBM_QUANTUM and device.name.startswith("ibm_"):
+            device.name = device.name[len("ibm_") :]
+    tuples = [
+        _extract_relevant_hardware_fields_for_user(info) for info in displayed_devices
+    ]
+    return DataFrame(
+        tuples,
+        columns=[
+            "provider",
+            "name",
+            "number of qubits",
+            "available",
+            "pending jobs",
+            "queue time",
+        ],
+    )

classiq/execution/execution_session.py

@@ -365,7 +365,7 @@ class ExecutionSession:
              A list of tuples, each containing the estimated cost and the corresponding parameters for that iteration. `cost` is a float, and `parameters` is a dictionary matching the execution parameter format.
 
         See Also:
-            The [Classiq Tutorial](https://docs.classiq.io/latest/getting-started/classiq_tutorial/execution_tutorial_part2/) has examples on using this method in variational quantum algorithms.
+            The [Execution Tutorial](https://docs.classiq.io/latest/getting-started/classiq_tutorial/execution_tutorial_part2/) has examples on using this method in variational quantum algorithms.
             More information about [Hamiltonians](https://docs.classiq.io/latest/qmod-reference/language-reference/classical-types/#hamiltonians).
         """
         _hamiltonian_deprecation_warning(cost_function)

classiq/execution/functions/__init__.py

@@ -0,0 +1,13 @@
+from classiq.execution.functions.expectation_value import _get_expectation_value
+from classiq.execution.functions.minimize import _minimize
+from classiq.execution.functions.sample import _new_sample
+from classiq.execution.functions.state_vector import _calculate_state_vector
+from classiq.execution.functions.util.constants import Verbosity
+
+__all__ = [
+    "Verbosity",
+    "_calculate_state_vector",
+    "_get_expectation_value",
+    "_minimize",
+    "_new_sample",
+]

classiq/execution/functions/expectation_value.py

@@ -0,0 +1,106 @@
+from typing import Any
+
+from classiq.interface.backend.backend_preferences import (
+    BackendPreferencesTypes,
+    ClassiqBackendPreferences,
+)
+from classiq.interface.backend.provider_config.provider_config import ProviderConfig
+from classiq.interface.backend.quantum_backend_providers import (
+    ClassiqSimulatorBackendNames,
+)
+from classiq.interface.executor.execution_preferences import ExecutionPreferences
+from classiq.interface.generator.model.preferences import create_random_seed
+from classiq.interface.generator.model.preferences.preferences import (
+    TranspilationOption,
+)
+from classiq.interface.hardware import Provider
+
+from classiq import (
+    ExecutionParams,
+    QuantumProgram,
+)
+from classiq.execution.execution_session import ExecutionSession
+from classiq.execution.functions.util._logging import _logger
+from classiq.execution.functions.util.backend_preferences import (
+    _get_backend_preferences_from_specifier,
+)
+from classiq.execution.functions.util.constants import Verbosity
+from classiq.execution.functions.util.parse_provider_backend import (
+    _parse_provider_backend,
+)
+from classiq.qmod.builtins.structs import SparsePauliOp
+
+_DEFAULT_BACKEND_NAME = "simulator"
+
+
+def _get_backend_preferences(
+    backend: str, estimate: bool, config: dict[str, Any] | ProviderConfig | None
+) -> BackendPreferencesTypes:
+    provider, backend_name = _parse_provider_backend(backend)
+    backend_preferences: BackendPreferencesTypes
+    if not estimate:
+        if not (
+            provider == Provider.CLASSIQ and backend_name.lower().strip() == "simulator"
+        ):
+            raise ValueError(
+                "Calculating exact expectation value is supported only for the 'classiq/simulator' backend"
+            )
+        backend_preferences = ClassiqBackendPreferences(
+            # This backend name is for exact simulation
+            backend_name=ClassiqSimulatorBackendNames.SIMULATOR_STATEVECTOR
+        )
+    else:
+        backend_preferences = _get_backend_preferences_from_specifier(
+            backend, config or {}
+        )
+    return backend_preferences
+
+
+def _get_expectation_value(
+    qprog: QuantumProgram,
+    observable: SparsePauliOp,
+    backend: str | None = None,
+    *,
+    estimate: bool = True,
+    parameters: ExecutionParams | None = None,
+    config: dict[str, Any] | ProviderConfig | None = None,
+    num_shots: int | None = None,
+    random_seed: int | None = None,
+    transpilation_option: TranspilationOption = TranspilationOption.DECOMPOSE,
+    verbosity: Verbosity = Verbosity.INFO,
+) -> complex:
+    """
+    Get the expectation value of the observable O with respect to the state |psi>
+
+    Args:
+        qprog: The quantum program which generates the state |psi> to be observed
+        observable: The observable O
+        backend: The device (hardware or simulator) on which to run the quantum program. Specified as "provider/device_id". Use the `get_backend_details` function to see supported devices.
+        estimate: Whether to estimate the expectation value by repeatedly measuring the circuit, or else calculate the expectation value using a simulator.
+        parameters: The classical parameters for the quantum program
+        config: Provider-specific configuration, such as api keys
+        num_shots:
+        random_seed: The random seed used for transpilation and simulation
+        transpilation_option: Advanced configuration for hardware-specific transpilation
+        verbosity: What level of information should be logged
+
+    Returns: The expectation value
+    """
+    if backend is None:
+        backend = _DEFAULT_BACKEND_NAME
+    backend_preferences = _get_backend_preferences(backend, estimate, config)
+    ep = ExecutionPreferences(
+        backend_preferences=backend_preferences,
+        num_shots=num_shots,
+        random_seed=create_random_seed() if random_seed is None else random_seed,
+        transpile_to_hardware=transpilation_option,
+    )
+
+    if verbosity != Verbosity.QUIET:
+        _logger.info(f"Submitting job to {backend}")
+    with ExecutionSession(qprog, execution_preferences=ep) as session:
+        job = session.submit_estimate(hamiltonian=observable, parameters=parameters)
+        if verbosity != Verbosity.QUIET:
+            _logger.info(f"Job id: {job.id}")
+        result = job.get_estimate_result()
+        return result.value

classiq/execution/functions/minimize.py

@@ -0,0 +1,90 @@
+from typing import Any
+
+from classiq.interface.backend.provider_config.provider_config import ProviderConfig
+from classiq.interface.executor.execution_preferences import ExecutionPreferences
+from classiq.interface.generator.model.preferences import create_random_seed
+from classiq.interface.generator.model.preferences.preferences import (
+    TranspilationOption,
+)
+
+from classiq import (
+    ExecutionParams,
+    QuantumProgram,
+)
+from classiq.execution.execution_session import ExecutionSession
+from classiq.execution.functions.util._logging import _logger
+from classiq.execution.functions.util.backend_preferences import (
+    _get_backend_preferences_from_specifier,
+)
+from classiq.execution.functions.util.constants import Verbosity
+from classiq.qmod.builtins.structs import SparsePauliOp
+from classiq.qmod.qmod_variable import QmodExpressionCreator
+
+_DEFAULT_BACKEND_NAME = "simulator"
+
+
+def _minimize(
+    qprog: QuantumProgram,
+    cost_function: SparsePauliOp | QmodExpressionCreator,
+    initial_params: ExecutionParams,
+    max_iteration: int,
+    backend: str | None = None,
+    *,
+    quantile: float = 1.0,
+    tolerance: float | None = None,
+    config: dict[str, Any] | ProviderConfig | None = None,
+    random_seed: int | None = None,
+    transpilation_option: TranspilationOption = TranspilationOption.DECOMPOSE,
+    verbosity: Verbosity = Verbosity.INFO,
+) -> list[tuple[float, ExecutionParams]]:
+    """
+    Minimize the given cost function using the quantum program.
+
+    Args:
+        qprog: The parametric quantum program that generates the state (ansatz).
+               Only quantum programs with exactly one execution parameter are supported.
+        cost_function: The cost function to minimize. It can be one of the following:
+            - A quantum cost function defined by a Hamiltonian.
+            - A classical cost function represented as a callable that returns a Qmod expression.
+              The callable should accept `QVar`s as arguments and use names matching the Model outputs.
+        initial_params: The initial parameters for the minimization.
+             This parameter must be of type `CReal` or `CArray`. The dictionary must contain a single key-value pair, where:
+                - The key is the name of the parameter.
+                - The value is either a float or a list of floats.
+        max_iteration: The maximum number of iterations for the minimization.
+        backend: The device (hardware or simulator) on which to run the quantum programs. Specified as "provider/device_id". Use the `get_backend_details` function to see supported devices.
+        quantile: The quantile to use for cost estimation.
+        tolerance: The tolerance for the minimization.
+        config: Provider-specific configuration, such as api keys
+        random_seed: Set this to increase determinism
+        transpilation_option: Advanced configuration for hardware-specific transpilation
+        verbosity: What level of information should be logged
+    Returns:
+         A list of tuples, each containing the estimated cost and the corresponding parameters for that iteration. `cost` is a float, and `parameters` is a dictionary matching the execution parameter format.
+
+    See Also:
+        The [Execution Tutorial](https://docs.classiq.io/latest/getting-started/classiq_tutorial/execution_tutorial_part2/) has examples on using this method in variational quantum algorithms.
+        More information about [Hamiltonians](https://docs.classiq.io/latest/qmod-reference/language-reference/classical-types/#hamiltonians).
+    """
+    if backend is None:
+        backend = _DEFAULT_BACKEND_NAME
+    backend_preferences = _get_backend_preferences_from_specifier(backend, config or {})
+
+    ep = ExecutionPreferences(
+        backend_preferences=backend_preferences,
+        random_seed=create_random_seed() if random_seed is None else random_seed,
+        transpile_to_hardware=transpilation_option,
+    )
+
+    if verbosity != Verbosity.QUIET:
+        _logger.info(f"Submitting job to {backend}")
+    with ExecutionSession(qprog, execution_preferences=ep) as session:
+        job = session.submit_minimize(
+            cost_function, initial_params, max_iteration, quantile, tolerance
+        )
+        if verbosity != Verbosity.QUIET:
+            _logger.info(f"Job id: {job.id}")
+        result = job.get_minimization_result()
+        return session._minimize_result_to_result(
+            result=result, initial_params=initial_params
+        )

classiq/execution/functions/sample.py

@@ -0,0 +1,76 @@
+from typing import TYPE_CHECKING, Any
+
+from classiq.execution.functions.util.backend_preferences import (
+    _get_backend_preferences_from_specifier,
+)
+
+if TYPE_CHECKING:
+    from pandas import DataFrame
+
+from classiq.interface.backend.provider_config.provider_config import ProviderConfig
+from classiq.interface.executor.execution_preferences import ExecutionPreferences
+from classiq.interface.generator.model.preferences import create_random_seed
+from classiq.interface.generator.model.preferences.preferences import (
+    TranspilationOption,
+)
+
+from classiq import (
+    ExecutionParams,
+    QuantumProgram,
+)
+from classiq.execution import ExecutionSession
+from classiq.execution.functions.util._logging import _logger
+from classiq.execution.functions.util.constants import Verbosity
+
+_DEFAULT_BACKEND_NAME = "simulator"
+
+
+def _new_sample(
+    qprog: QuantumProgram,
+    backend: str | None = None,
+    *,
+    parameters: ExecutionParams | None = None,
+    config: dict[str, Any] | ProviderConfig | None = None,
+    num_shots: int | None = None,
+    random_seed: int | None = None,
+    transpilation_option: TranspilationOption = TranspilationOption.DECOMPOSE,
+    verbosity: Verbosity = Verbosity.INFO,
+) -> "DataFrame":
+    """
+    Sample a quantum program.
+
+    Args:
+        qprog: The quantum program
+        backend: The device (hardware or simulator) on which to run the quantum program. Specified as "provider/device_id". Use the `get_backend_details` function to see supported devices.
+        parameters: The classical parameters for the quantum program
+        config: Provider-specific configuration, such as api keys
+        num_shots: The number of times to sample
+        random_seed: The random seed used for transpilation and simulation
+        transpilation_option: Advanced configuration for hardware-specific transpilation
+        verbosity: What level of information should be logged
+
+    Returns: A dataframe containing the histogram
+    """
+    if num_shots is not None and num_shots < 1:
+        raise ValueError(f"Argument num_shots must be greater than 0, got {num_shots}")
+    if config is None:
+        config = {}
+    if backend is None:
+        backend = _DEFAULT_BACKEND_NAME
+    backend_preferences = _get_backend_preferences_from_specifier(backend, config)
+    ep = ExecutionPreferences(
+        backend_preferences=backend_preferences,
+        num_shots=num_shots,
+        random_seed=create_random_seed() if random_seed is None else random_seed,
+        transpile_to_hardware=transpilation_option,
+    )
+    if verbosity != Verbosity.QUIET:
+        _logger.info(f"Submitting job to {backend}")
+    with ExecutionSession(qprog, execution_preferences=ep) as session:
+        job = session.submit_sample(parameters)
+        if verbosity != Verbosity.QUIET:
+            _logger.info(f"Job id: {job.id}")
+        result = job.get_sample_result()
+
+    df = result.dataframe
+    return df

classiq/execution/functions/state_vector.py

@@ -0,0 +1,113 @@
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from pandas import DataFrame
+
+from classiq.interface.backend.backend_preferences import (
+    BackendPreferencesTypes,
+    ClassiqBackendPreferences,
+    GCPBackendPreferences,
+)
+from classiq.interface.backend.quantum_backend_providers import (
+    ClassiqNvidiaBackendNames,
+    ClassiqSimulatorBackendNames,
+    GoogleNvidiaBackendNames,
+)
+from classiq.interface.executor.execution_preferences import ExecutionPreferences
+from classiq.interface.generator.model.preferences import create_random_seed
+from classiq.interface.generator.model.preferences.preferences import (
+    TranspilationOption,
+)
+from classiq.interface.hardware import Provider
+
+from classiq import (
+    ExecutionParams,
+    QuantumProgram,
+)
+from classiq.execution import ExecutionSession
+from classiq.execution.functions.util._logging import _logger
+from classiq.execution.functions.util.constants import Verbosity
+from classiq.execution.functions.util.parse_provider_backend import (
+    _PROVIDER_TO_CANONICAL_NAME,
+    _parse_provider_backend,
+)
+
+_DEFAULT_STATE_VECTOR_BACKEND_NAME = "simulator"
+
+
+def _calculate_state_vector(
+    qprog: QuantumProgram,
+    backend: str | None = None,
+    *,
+    parameters: ExecutionParams | None = None,
+    filters: dict[str, Any] | None = None,
+    random_seed: int | None = None,
+    transpilation_option: TranspilationOption = TranspilationOption.DECOMPOSE,
+    verbosity: Verbosity = Verbosity.INFO,
+) -> "DataFrame":
+    """
+    Calculate the state vector of a quantum program.
+
+    Args:
+        qprog: The quantum program
+        backend: The simulator on which to simulate the quantum program. Specified as "provider/device_id"
+        parameters: The classical parameters for the quantum program
+        filters: Only states where the variables match these values will be included in the state vector.
+        random_seed: The random seed used for transpilation and simulation
+        transpilation_option: Advanced configuration for hardware-specific transpilation
+        verbosity: What level of information should be logged
+
+    Returns: A dataframe containing the state vector
+    """
+    if backend is None:
+        backend = _DEFAULT_STATE_VECTOR_BACKEND_NAME
+
+    provider, raw_backend_name = _parse_provider_backend(backend)
+    backend_name_lower = raw_backend_name.lower()
+    backend_preferences: BackendPreferencesTypes
+
+    if provider == Provider.CLASSIQ:
+        if backend_name_lower == "simulator":
+            backend_name = str(ClassiqSimulatorBackendNames.SIMULATOR_STATEVECTOR)
+        elif backend_name_lower == "nvidia_simulator":
+            backend_name = str(ClassiqNvidiaBackendNames.SIMULATOR_STATEVECTOR)
+        else:
+            raise ValueError(
+                f"Unsupported backend '{backend}'. "
+                "Under the Classiq provider, only 'classiq/simulator' and 'classiq/nvidia_simulator' are supported."
+            )
+        backend_preferences = ClassiqBackendPreferences(backend_name=backend_name)
+    elif provider == Provider.GOOGLE:
+        if backend_name_lower == "cuquantum":
+            backend_name = str(GoogleNvidiaBackendNames.CUQUANTUM_STATEVECTOR)
+        else:
+            raise ValueError(
+                f"Unsupported backend '{backend}'. "
+                "Under the Google provider, only 'google/cuquantum' is supported."
+            )
+        backend_preferences = GCPBackendPreferences(backend_name=backend_name)
+    else:
+        raise ValueError(
+            f"Provider '{_PROVIDER_TO_CANONICAL_NAME.get(provider) or provider}' does not support this operation."
+        )
+
+    ep = ExecutionPreferences(
+        backend_preferences=backend_preferences,
+        random_seed=create_random_seed() if random_seed is None else random_seed,
+        transpile_to_hardware=transpilation_option,
+    )
+    if verbosity != Verbosity.QUIET:
+        _logger.info(f"Submitting job to {backend}")
+    with ExecutionSession(qprog, execution_preferences=ep) as session:
+        if filters is not None:
+            for output_name, value in filters.items():
+                session.set_measured_state_filter(
+                    output_name, lambda state, val=value: state == val
+                )
+        job = session.submit_sample(parameters)
+        if verbosity != Verbosity.QUIET:
+            _logger.info(f"Job id: {job.id}")
+        result = job.get_sample_result()
+
+    df = result.dataframe
+    return df

classiq/execution/functions/util/_logging.py

@@ -0,0 +1,19 @@
+import logging
+
+_logger = logging.getLogger(__name__)
+
+
+def _setup_logging() -> None:
+    if _logger.handlers:
+        return
+
+    handler = logging.StreamHandler()
+    formatter = logging.Formatter("%(message)s")
+    handler.setFormatter(formatter)
+    _logger.addHandler(handler)
+    _logger.setLevel(logging.INFO)
+
+    _logger.propagate = False
+
+
+_setup_logging()