classiq 0.100.0__py3-none-any.whl → 0.104.0__py3-none-any.whl

classiq/execution/functions/_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()

classiq/execution/functions/constants.py

@@ -0,0 +1,9 @@
+from enum import auto, unique
+
+from classiq.interface.enum_utils import StrEnum
+
+
+@unique
+class Verbosity(StrEnum):
+    QUIET = auto()
+    INFO = auto()

classiq/execution/functions/parse_provider_backend.py

@@ -0,0 +1,90 @@
+from classiq.interface.hardware import Provider
+
+_PROVIDER_BACKEND_SEPARATOR = "/"
+
+_PROVIDER_TO_CANONICAL_NAME: dict[Provider, str] = {
+    Provider.IBM_QUANTUM: "ibm",
+    Provider.AZURE_QUANTUM: "azure",
+    Provider.AMAZON_BRAKET: "braket",
+    Provider.IONQ: "ionq",
+    Provider.CLASSIQ: "classiq",
+    Provider.GOOGLE: "google",
+    Provider.ALICE_AND_BOB: "alice&bob",
+    Provider.OQC: "oqc",
+    Provider.INTEL: "intel",
+    Provider.AQT: "aqt",
+    Provider.CINECA: "cineca",
+    Provider.SOFTBANK: "softbank",
+}
+
+_CANONICAL_NAMES_TO_PROVIDER: dict[str, Provider] = {
+    name: provider for provider, name in _PROVIDER_TO_CANONICAL_NAME.items()
+}
+
+
+def _error_suggested_provider(provider_name: str) -> Provider | None:
+    """
+    In the case that receive an incorrect provider name, return a possible suggestion.
+    """
+    provider_name = provider_name.strip().lower()
+    for canonical_name in _CANONICAL_NAMES_TO_PROVIDER:
+        if canonical_name in provider_name:
+            return _CANONICAL_NAMES_TO_PROVIDER[canonical_name]
+    # Special cases
+    if "gcp" in provider_name:
+        return Provider.GOOGLE
+    if "microsoft" in provider_name:
+        return Provider.AZURE_QUANTUM
+    if "amazon" in provider_name or "aws" in provider_name:
+        return Provider.AMAZON_BRAKET
+    if "oxford" in provider_name:
+        return Provider.OQC
+    if "alice" in provider_name or "bob" in provider_name:
+        return Provider.ALICE_AND_BOB
+    if "alpine" in provider_name:
+        return Provider.AQT
+
+    return None
+
+
+def _parse_provider_backend(spec: str) -> tuple[Provider, str]:
+    """
+    Parse a backend specification into (provider, backend). Provider is case-insensitive.
+    Backend must NOT contain the separator. If provider is not specified, it defaults to
+    Classiq.
+    """
+    if not spec.strip():
+        raise ValueError("Backend specification must be a non-empty string")
+
+    spec = spec.strip()
+
+    if _PROVIDER_BACKEND_SEPARATOR not in spec:
+        return Provider.CLASSIQ, spec
+
+    provider_raw, backend = spec.split(_PROVIDER_BACKEND_SEPARATOR, 1)
+
+    if _PROVIDER_BACKEND_SEPARATOR in backend:
+        raise ValueError(
+            f"Backend name must not contain '{_PROVIDER_BACKEND_SEPARATOR}': '{backend}'"
+        )
+
+    provider_key = provider_raw.strip().lower()
+    backend = backend.strip()
+
+    if not provider_key:
+        raise ValueError("Provider name cannot be empty")
+    if not backend:
+        raise ValueError("Backend name cannot be empty")
+
+    try:
+        provider = _CANONICAL_NAMES_TO_PROVIDER[provider_key]
+    except KeyError:
+        error_message = f"Unrecognized provider '{provider_raw}'."
+        suggested_provider = _error_suggested_provider(provider_key)
+        if suggested_provider is not None:
+            error_message += (
+                f" Did you mean '{_PROVIDER_TO_CANONICAL_NAME[suggested_provider]}'?"
+            )
+        raise ValueError(error_message) from None
+
+    return provider, backend

classiq/execution/functions/sample.py

@@ -0,0 +1,257 @@
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal
+
+if TYPE_CHECKING:
+    from pandas import DataFrame
+
+from classiq.interface.backend.backend_preferences import (
+    AliceBobBackendPreferences,
+    AQTBackendPreferences,
+    AwsBackendPreferences,
+    AzureBackendPreferences,
+    AzureCredential,
+    BackendPreferencesTypes,
+    ClassiqBackendPreferences,
+    GCPBackendPreferences,
+    IBMBackendPreferences,
+    IntelBackendPreferences,
+    IonqBackendPreferences,
+)
+from classiq.interface.backend.provider_config.provider_config import ProviderConfig
+from classiq.interface.backend.provider_config.providers.alice_bob import AliceBobConfig
+from classiq.interface.backend.provider_config.providers.aqt import AQTConfig
+from classiq.interface.backend.provider_config.providers.azure import AzureConfig
+from classiq.interface.backend.provider_config.providers.braket import BraketConfig
+from classiq.interface.backend.provider_config.providers.ibm import IBMConfig
+from classiq.interface.backend.provider_config.providers.ionq import IonQConfig
+from classiq.interface.backend.quantum_backend_providers import (
+    ClassiqNvidiaBackendNames,
+    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 import ExecutionSession
+from classiq.execution.functions._logging import _logger
+from classiq.execution.functions.constants import Verbosity
+from classiq.execution.functions.parse_provider_backend import (
+    _PROVIDER_TO_CANONICAL_NAME,
+    _parse_provider_backend,
+)
+
+
+@dataclass
+class _ProviderConfigToBackendPrefSpec:
+    backend_preferences_class: type[BackendPreferencesTypes]
+    config_class: type[ProviderConfig] | None = None
+    # Maps the config dict (either passed in directly or dumped from config class) to a
+    # dict that we can load into the given BackendPreferences class. This is in case
+    # we need to rename fields or change structure.
+    config_dict_to_backend_preferences_dict: (
+        Callable[[dict[str, Any]], dict[str, Any]] | None
+    ) = None
+    # Maps from SDK names to names our backend recognizes, raising a useful error
+    # if the name is unrecognized.
+    backend_name_mapper: Callable[[str], str] | None = None
+
+
+def _classiq_backend_name_mapper(backend_name: str) -> str:
+    backend_name = backend_name.lower()
+    if backend_name in [
+        ClassiqSimulatorBackendNames.SIMULATOR,
+        ClassiqSimulatorBackendNames.SIMULATOR_MATRIX_PRODUCT_STATE,
+        ClassiqSimulatorBackendNames.SIMULATOR_DENSITY_MATRIX,
+    ]:
+        return backend_name
+    if backend_name == "nvidia_simulator":
+        return ClassiqNvidiaBackendNames.SIMULATOR
+    if any(keyword in backend_name for keyword in ["gpu", "nvidia"]):
+        suggested_backend_name = "nvidia_simulator"
+    else:
+        suggested_backend_name = "simulator"
+    raise ValueError(
+        f"Unsupported backend name {backend_name}. Did you mean '{suggested_backend_name}'?"
+    )
+
+
+def _ibm_backend_name_mapper(backend_name: str) -> str:
+    ibm_prefix: Literal["ibm_"] = "ibm_"
+    backend_name = backend_name.lower()
+    if backend_name.startswith(ibm_prefix):
+        backend_name_no_prefix = backend_name.removeprefix(ibm_prefix)
+        raise ValueError(
+            f"IBM backend names shouldn't start with ibm_. Try 'ibm/{backend_name_no_prefix}'."
+        )
+    return ibm_prefix + backend_name
+
+
+def _azure_config_dict_to_backend_preferences_dict(
+    config_dict: dict[str, Any],
+) -> dict[str, Any]:
+    if "location" not in config_dict:
+        raise ValueError("Azure config must have 'location' property")
+    credentials = None
+    if all(
+        config_dict.get(key) is not None
+        for key in ["tenant_id", "client_id", "client_secret", "resource_id"]
+    ):
+        credentials = AzureCredential.model_validate(
+            {
+                "tenant_id": config_dict["tenant_id"],
+                "client_id": config_dict["client_id"],
+                "client_secret": config_dict["client_secret"],
+                "resource_id": config_dict["resource_id"],
+            }
+        )
+    return {
+        "location": config_dict["location"],
+        "credentials": credentials,
+        "ionq_error_mitigation_flag": config_dict.get("ionq_error_mitigation"),
+    }
+
+
+def _braket_config_dict_to_backend_preferences_dict(
+    config_dict: dict[str, Any],
+) -> dict[str, Any]:
+    config_dict["aws_access_key_id"] = config_dict.pop("braket_access_key_id", None)
+    config_dict["aws_secret_access_key"] = config_dict.pop(
+        "braket_secret_access_key", None
+    )
+    return config_dict
+
+
+_PROVIDER_CONFIG_TO_BACKEND_PREFERENCES_SPEC = {
+    Provider.CLASSIQ: _ProviderConfigToBackendPrefSpec(
+        backend_preferences_class=ClassiqBackendPreferences,
+        backend_name_mapper=_classiq_backend_name_mapper,
+    ),
+    Provider.GOOGLE: _ProviderConfigToBackendPrefSpec(
+        backend_preferences_class=GCPBackendPreferences
+    ),
+    Provider.INTEL: _ProviderConfigToBackendPrefSpec(
+        backend_preferences_class=IntelBackendPreferences
+    ),
+    Provider.IBM_QUANTUM: _ProviderConfigToBackendPrefSpec(
+        backend_preferences_class=IBMBackendPreferences,
+        config_class=IBMConfig,
+        backend_name_mapper=_ibm_backend_name_mapper,
+    ),
+    Provider.AMAZON_BRAKET: _ProviderConfigToBackendPrefSpec(
+        backend_preferences_class=AwsBackendPreferences,
+        config_dict_to_backend_preferences_dict=_braket_config_dict_to_backend_preferences_dict,
+        config_class=BraketConfig,
+    ),
+    Provider.IONQ: _ProviderConfigToBackendPrefSpec(
+        backend_preferences_class=IonqBackendPreferences,
+        config_class=IonQConfig,
+    ),
+    Provider.ALICE_AND_BOB: _ProviderConfigToBackendPrefSpec(
+        backend_preferences_class=AliceBobBackendPreferences,
+        config_class=AliceBobConfig,
+    ),
+    Provider.AQT: _ProviderConfigToBackendPrefSpec(
+        backend_preferences_class=AQTBackendPreferences,
+        config_class=AQTConfig,
+    ),
+    Provider.AZURE_QUANTUM: _ProviderConfigToBackendPrefSpec(
+        backend_preferences_class=AzureBackendPreferences,
+        config_dict_to_backend_preferences_dict=_azure_config_dict_to_backend_preferences_dict,
+        config_class=AzureConfig,
+    ),
+}
+
+
+def _get_backend_preferences_from_specifier(
+    backend_spec: str, config: dict[str, Any] | ProviderConfig
+) -> BackendPreferencesTypes:
+    provider, backend_name = _parse_provider_backend(backend_spec)
+
+    if provider not in _PROVIDER_CONFIG_TO_BACKEND_PREFERENCES_SPEC:
+        raise NotImplementedError(
+            f"Unsupported provider '{_PROVIDER_TO_CANONICAL_NAME.get(provider) or provider}'"
+        )
+
+    provider_spec = _PROVIDER_CONFIG_TO_BACKEND_PREFERENCES_SPEC[provider]
+    if isinstance(config, ProviderConfig):
+        if provider_spec.config_class is None:
+            raise ValueError(
+                f"This provider does not support any ProviderConfig classes. Received '{config.__class__.__name__}'"
+            )
+        if not isinstance(config, provider_spec.config_class):
+            raise ValueError(
+                f"{_PROVIDER_TO_CANONICAL_NAME[provider]} devices require {provider_spec.config_class.__name__}, got {config.__class__.__name__}"
+            )
+        config_dict = config.model_dump()
+    else:
+        config_dict = config
+    if provider_spec.backend_name_mapper is not None:
+        backend_name = provider_spec.backend_name_mapper(backend_name)
+
+    if provider_spec.config_dict_to_backend_preferences_dict is not None:
+        config_dict = provider_spec.config_dict_to_backend_preferences_dict(config_dict)
+
+    config_dict["backend_name"] = backend_name
+    return provider_spec.backend_preferences_class.model_validate(config_dict)
+
+
+_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"
+        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/jobs.py

@@ -1,7 +1,11 @@
 import warnings
 import webbrowser
+from dataclasses import asdict, dataclass
 from datetime import datetime
-from typing import Any
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import pandas as pd
 from urllib.parse import urljoin
 
 import httpx
@@ -29,6 +33,10 @@ from classiq._internals.async_utils import syncify_function
 from classiq._internals.client import client
 from classiq._internals.jobs import JobID, JobPoller
 
+TOTAL_COST = "total_cost"
+CURRENCY_CODE = "currency_code"
+COST = "cost"
+
 
 class ClassiqExecutionResultError(ClassiqError):
     def __init__(self, primitive: str) -> None:
@@ -37,6 +45,42 @@ class ClassiqExecutionResultError(ClassiqError):
         )
 
 
+@dataclass
+class ExecutionJobFilters:
+    """
+    Filter parameters for querying execution jobs.
+
+    All filters are combined using AND logic: only jobs matching all specified filters are returned.
+    Range filters (with _min/_max suffixes) are inclusive.
+    Datetime filters are compared against the job's timestamps.
+    """
+
+    id: str | None = None  # Exact match on job ID
+    session_id: str | None = None  # Exact match on session ID
+    status: JobStatus | None = (
+        None  # Exact match on job status (e.g., "COMPLETED", "FAILED")
+    )
+    name: str | None = None  # Exact match on job name
+    provider: str | None = None  # Exact match on provider name (e.g., "ibm", "aws")
+    backend: str | None = None  # Exact match on backend name
+    program_id: str | None = None  # Exact match on program ID
+    total_cost_min: float | None = None  # Minimum total cost (inclusive)
+    total_cost_max: float | None = None  # Maximum total cost (inclusive)
+    start_time_min: datetime | None = None  # Earliest job start time (inclusive)
+    start_time_max: datetime | None = None  # Latest job start time (inclusive)
+    end_time_min: datetime | None = None  # Earliest job end time (inclusive)
+    end_time_max: datetime | None = None  # Latest job end time (inclusive)
+
+    def format_filters(self) -> dict[str, Any]:
+        """Convert filter fields to API kwargs, excluding None values and converting datetimes."""
+        filter_dict = asdict(self)
+        return {
+            k: (v.isoformat() if isinstance(v, datetime) else v)
+            for k, v in filter_dict.items()
+            if v is not None
+        }
+
+
 class ExecutionJob:
     _details: ExecutionJobDetails
     _result: ResultsCollection | None
@@ -352,10 +396,83 @@ class ExecutionJob:
 
 
 async def get_execution_jobs_async(
-    offset: int = 0, limit: int = 50
+    offset: int = 0,
+    limit: int = 50,
 ) -> list[ExecutionJob]:
-    result = await ApiWrapper().call_query_execution_jobs(offset=offset, limit=limit)
-    return [ExecutionJob(details) for details in result.results]
+    execution_user_jobs = await ApiWrapper.call_query_execution_jobs(
+        offset, limit, http_client=None
+    )
+    return [ExecutionJob(details) for details in execution_user_jobs.results]
+
+
+def get_execution_jobs(
+    offset: int = 0,
+    limit: int = 50,
+) -> list[ExecutionJob]:
+    """Query execution jobs.
+
+    Args:
+        offset: Number of results to skip (default: 0)
+        limit: Maximum number of results to return (default: 50)
+
+    Returns:
+        List of ExecutionJob objects.
+
+    Examples:
+        # Query all jobs:
+        jobs = get_execution_jobs(limit=10)
+    """
+    return syncify_function(get_execution_jobs_async)(offset, limit)
+
+
+def _flatten_cost_field(action_dict: dict[str, Any]) -> dict[str, Any]:
+    cost_obj = action_dict.pop(COST, {}) or {}
+    action_dict[TOTAL_COST] = cost_obj.get(TOTAL_COST, 0)
+    action_dict[CURRENCY_CODE] = cost_obj.get(CURRENCY_CODE)
+    return action_dict
+
+
+async def get_execution_actions_async(
+    offset: int = 0,
+    limit: int = 50,
+    filters: ExecutionJobFilters | None = None,
+) -> "pd.DataFrame":
+    import pandas as pd
+
+    api_kwargs = filters.format_filters() if filters is not None else {}
+    execution_user_actions = await ApiWrapper.call_query_execution_jobs(
+        offset, limit, http_client=None, **api_kwargs
+    )
+    execution_actions = execution_user_actions.results
+
+    if not execution_actions:
+        return pd.DataFrame()
+
+    data = [_flatten_cost_field(action.model_dump()) for action in execution_actions]
+    return pd.DataFrame(data)
+
+
+def get_execution_actions(
+    offset: int = 0, limit: int = 50, filters: ExecutionJobFilters | None = None
+) -> "pd.DataFrame":
+    """Query execution jobs with optional filters.
+
+    Args:
+        offset: Number of results to skip (default: 0)
+        limit: Maximum number of results to return (default: 50)
+        filters: Optional ExecutionJobFilters object containing filter parameters.
+
+    Returns:
+        pandas.DataFrame containing execution job information with columns:
+        id, name, start_time, end_time, provider, backend_name, status,
+        num_shots, program_id, error, cost.
 
+    Examples:
+        # Query all jobs:
+        df = get_execution_actions(limit=10)
 
-get_execution_jobs = syncify_function(get_execution_jobs_async)
+        # Query with filters:
+        filters = ExecutionJobFilters(status="COMPLETED", provider="ibm")
+        df = get_execution_actions(filters=filters, limit=10)
+    """
+    return syncify_function(get_execution_actions_async)(offset, limit, filters)

classiq/interface/_version.py

@@ -3,5 +3,5 @@ from packaging.version import Version
 # This file was generated automatically
 # Please don't track in version control (DONTTRACK)
 
-SEMVER_VERSION = '0.100.0'
+SEMVER_VERSION = '0.104.0'
 VERSION = str(Version(SEMVER_VERSION))

classiq/interface/backend/backend_preferences.py

@@ -454,6 +454,20 @@ class CINECABackendPreferences(BackendPreferences):
     )
 
 
+class SoftbankBackendPreferences(BackendPreferences):
+    """
+    Represents the backend preferences specific to Softbank.
+    """
+
+    backend_service_provider: ProviderTypeVendor.SOFTBANK = pydantic.Field(
+        default=ProviderVendor.SOFTBANK
+    )
+
+    priority: int | None = pydantic.Field(
+        default=None, description="Priority of the job"
+    )
+
+
 def is_exact_simulator(backend_preferences: BackendPreferences) -> bool:
     return backend_preferences.backend_name in EXACT_SIMULATORS
 
@@ -486,6 +500,7 @@ BackendPreferencesTypes = Union[
     IntelBackendPreferences,
     AQTBackendPreferences,
     CINECABackendPreferences,
+    SoftbankBackendPreferences,
 ]
 
 __all__ = [

classiq/interface/backend/provider_config/providers/aqt.py

@@ -12,5 +12,5 @@ class AQTConfig(ProviderConfig):
         workspace: The AQT workspace where the simulator/hardware is located.
     """
 
-    api_key: str | None = pydantic.Field(default=None, description="AQT API key")
+    api_key: str = pydantic.Field(description="AQT API key")
     workspace: str = pydantic.Field(description="AQT workspace")

classiq/interface/backend/provider_config/providers/azure.py

@@ -1,6 +1,5 @@
 import pydantic
 
-from classiq.interface.backend import pydantic_backend
 from classiq.interface.backend.provider_config.provider_config import ProviderConfig
 
 
@@ -26,7 +25,7 @@ class AzureConfig(ProviderConfig):
     client_secret: str | None = pydantic.Field(
         default=None, description="Azure Client Secret"
     )
-    resource_id: pydantic_backend.PydanticAzureResourceIDType | None = pydantic.Field(
+    resource_id: str | None = pydantic.Field(
         default=None,
         description="Azure Resource ID (including Azure subscription ID, resource "
         "group and workspace), for personal resource",

classiq/interface/backend/provider_config/providers/ibm.py

@@ -10,7 +10,7 @@ class IBMConfig(ProviderConfig):
     Attributes:
         access_token (str | None): The IBM Cloud access token to be used with IBM Quantum hosted backends. Defaults to `None`.
         channel (str): Channel to use for IBM cloud backends. Defaults to `"ibm_cloud"`.
-        instance_crn (str): The IBM Cloud instance CRN (Cloud Resource Name) for the IBM Quantum service.
+        instance_crn (str | None): The IBM Cloud instance CRN (Cloud Resource Name) for the IBM Quantum service.
     """
 
     access_token: str | None = pydantic.Field(

classiq/interface/backend/quantum_backend_providers.py

@@ -27,6 +27,7 @@ class ProviderVendor(StrEnum):
     INTEL = "Intel"
     AQT = "AQT"
     CINECA = "CINECA"
+    SOFTBANK = "Softbank"
 
 
 class ProviderTypeVendor:
@@ -41,6 +42,7 @@ class ProviderTypeVendor:
     INTEL = Literal[ProviderVendor.INTEL]
     AQT = Literal[ProviderVendor.AQT]
     CINECA = Literal[ProviderVendor.CINECA]
+    SOFTBANK = Literal[ProviderVendor.SOFTBANK]
 
 
 PROVIDER_NAME_MAPPER = {
@@ -54,6 +56,7 @@ PROVIDER_NAME_MAPPER = {
     ProviderVendor.INTEL: "INTEL",
     ProviderVendor.AQT: "AQT",
     ProviderVendor.CLASSIQ: "CLASSIQ",
+    ProviderVendor.SOFTBANK: "SOFTBANK",
 }