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

classiq/__init__.py

@@ -52,6 +52,7 @@ from classiq.open_library import *  # noqa: F403
 from classiq.open_library import __all__ as _open_library_all
 from classiq.qmod import *  # noqa: F403
 from classiq.qmod import __all__ as _qmod_all
+from classiq.qprog_to_cudaq import qprog_to_cudaq_kernel
 from classiq.quantum_program import ExecutionParams, assign_parameters, transpile
 from classiq.synthesis import (
     QmodFormat,
@@ -117,6 +118,7 @@ __all__ = (
         "matrix_to_hamiltonian",
         "matrix_to_pauli_operator",
         "pauli_operator_to_matrix",
+        "qprog_to_cudaq_kernel",
         "quantum_program_from_qasm",
         "quantum_program_from_qasm_async",
         "QmodFormat",

classiq/_internals/authentication/auth0.py

@@ -11,6 +11,8 @@ from classiq.interface.exceptions import ClassiqAuthenticationError
 
 from classiq._internals.config import CONFIG_ENV_FILES
 
+GRANT_TYPE_CLIENT_CREDENTIALS = "client_credentials"
+
 
 class AuthSettings(BaseSettings):
     domain: str = Field(
@@ -144,3 +146,30 @@ class Auth0:
             access_token=data["access_token"],
             refresh_token=data.get("refresh_token", None),
         )
+
+    async def client_credentials_login(
+        self, client_id: str, client_secret: str, organization: str | None = None
+    ) -> dict[str, Any]:
+        """Authenticate using client credentials (M2M flow).
+
+        Args:
+            client_id: The M2M application client ID
+            client_secret: The M2M application client secret
+            organization: Optional organization ID for organization-specific access
+
+        Returns:
+            Dictionary containing token data from Auth0
+        """
+        payload = {
+            "client_id": client_id,
+            "client_secret": client_secret,
+            "grant_type": GRANT_TYPE_CLIENT_CREDENTIALS,
+            "audience": self._auth_settings.audience,
+        }
+        if organization:
+            payload["organization"] = organization
+
+        return await self._make_request(
+            url="/oauth/token",
+            payload=payload,
+        )

classiq/_internals/authentication/auth_flow_factory.py

@@ -0,0 +1,43 @@
+import logging
+
+from classiq._internals.authentication import password_manager as pm
+from classiq._internals.authentication.authorization_flow import AuthorizationFlow
+from classiq._internals.authentication.hybrid_flow import HybridFlow
+from classiq._internals.authentication.machine_credentials_flow import (
+    M2MClientCredentialsFlow,
+)
+from classiq._internals.config import Configuration
+
+_logger = logging.getLogger(__name__)
+
+
+class AuthFlowFactory:
+    """Factory for creating appropriate authorization and authentication flows based on context."""
+
+    @staticmethod
+    def create_flow(
+        password_manager: pm.PasswordManager, config: Configuration
+    ) -> AuthorizationFlow:
+        """
+        Create an authentication with or without authentication flow based on the password manager type.
+
+        Args:
+            password_manager: The password manager instance.
+            config: Configuration for authentication.
+
+        Returns:
+            Appropriate AuthorizationFlow instance (M2MClientCredentialsFlow or HybridFlow).
+
+        Raises:
+            ClassiqAuthenticationError: If M2M token generation failed.
+        """
+        # M2M authentication flow using client credentials to authenticate with Auth0 and get access token
+        if isinstance(password_manager, pm.M2MPasswordManager):
+            return M2MClientCredentialsFlow(
+                client_id=password_manager.client_id,
+                client_secret=password_manager.client_secret,
+                organization=password_manager.org_id,
+            )
+
+        # Interactive user authentication flow
+        return HybridFlow(require_refresh_token=True, text_only=config.text_only)

classiq/_internals/authentication/machine_credentials_flow.py

@@ -0,0 +1,26 @@
+from classiq._internals.authentication.auth0 import Tokens
+from classiq._internals.authentication.authorization_flow import AuthorizationFlow
+
+
+class M2MClientCredentialsFlow(AuthorizationFlow):
+    """Machine-to-Machine (M2M) authentication using OAuth2 Client Credentials flow."""
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        organization: str | None = None,
+    ) -> None:
+        # M2M authentication doesn't use refresh tokens or interactive flows
+        super().__init__(require_refresh_token=False, text_only=False)
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.organization = organization
+
+    async def get_tokens(self) -> Tokens:
+        data = await self.auth0_client.client_credentials_login(
+            client_id=self.client_id,
+            client_secret=self.client_secret,
+            organization=self.organization,
+        )
+        return self.handle_ready_data(data)

classiq/_internals/authentication/password_manager.py

@@ -37,6 +37,8 @@ class PasswordManagerSettings(BaseSettings):
 
 class PasswordManager(abc.ABC):
     _SERVICE_NAME: str = "classiqTokenService"
+    text_only_supported: bool = True
+    has_refresh_token: bool = True
 
     def __init__(self) -> None:
         self._settings = PasswordManagerSettings()
@@ -76,6 +78,8 @@ class PasswordManager(abc.ABC):
 
 
 class KeyringPasswordManager(PasswordManager):
+    text_only_supported: bool = False
+
     def _get(self, key: str) -> str | None:
         return keyring.get_password(service_name=self._SERVICE_NAME, username=key)
 
@@ -154,3 +158,83 @@ class FilePasswordManager(PasswordManager):
     @staticmethod
     def is_supported() -> bool:
         return "windows" not in platform.platform().lower()
+
+
+class M2MPasswordManager(PasswordManager):
+    """Password manager for M2M authentication using environment variables.
+
+    Supports machine-to-machine authentication by reading credentials from:
+    - CLASSIQ_CLIENT_ID (required)
+    - CLASSIQ_CLIENT_SECRET (required)
+    - CLASSIQ_ORG_ID (optional)
+
+    This manager stores tokens in memory after M2M authentication.
+    """
+
+    has_refresh_token: bool = False
+
+    M2M_CREDS_ENV_KEYS = {
+        "client_id": "CLASSIQ_CLIENT_ID",
+        "client_secret": "CLASSIQ_CLIENT_SECRET",
+        "org_id": "CLASSIQ_ORG_ID",
+    }
+
+    M2M_REQUIRED_CREDS = {"client_id", "client_secret"}
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._token_storage: dict[str, str | None] = {}
+        # Initialize all environment variable values
+        self._m2m_creds: dict[str, str | None] = {
+            key: os.getenv(env_key) for key, env_key in self.M2M_CREDS_ENV_KEYS.items()
+        }
+
+    def _get(self, key: str) -> str | None:
+        """Get token from in-memory storage."""
+        return self._token_storage.get(key)
+
+    def _set(self, key: str, value: str | None) -> None:
+        """Store token in memory."""
+        if value is None:
+            self._clear(key)
+            return
+        self._token_storage[key] = value
+
+    def _clear(self, key: str) -> None:
+        """Clear token from memory storage."""
+        self._token_storage.pop(key, None)
+
+    @staticmethod
+    def is_supported() -> bool:
+        """Check if required M2M environment variables are present."""
+        manager = M2MPasswordManager()
+        return all(
+            manager._m2m_creds.get(key) for key in M2MPasswordManager.M2M_REQUIRED_CREDS
+        )
+
+    def _get_required_cred(self, key: str) -> str:
+        value = self._m2m_creds.get(key)
+        if value is None:
+            raise ValueError(
+                f"M2M authentication requires {self.M2M_CREDS_ENV_KEYS[key]} environment variable"
+            )
+        return value
+
+    # to prevent mypy from complaining about the return type
+    def _get_optional_cred(self, key: str) -> str | None:
+        return self._m2m_creds.get(key)
+
+    @property
+    def client_id(self) -> str:
+        """Get client ID from initialized credentials."""
+        return self._get_required_cred("client_id")
+
+    @property
+    def client_secret(self) -> str:
+        """Get client secret from initialized credentials."""
+        return self._get_required_cred("client_secret")
+
+    @property
+    def org_id(self) -> str | None:
+        """Get organization ID from initialized credentials (optional)."""
+        return self._get_optional_cred("org_id")

classiq/_internals/authentication/token_manager.py

@@ -11,13 +11,15 @@ from classiq.interface.exceptions import (
 
 from classiq._internals.authentication import password_manager as pm
 from classiq._internals.authentication.auth0 import Auth0, Tokens
-from classiq._internals.authentication.hybrid_flow import HybridFlow
+from classiq._internals.authentication.auth_flow_factory import AuthFlowFactory
 from classiq._internals.config import Configuration
 
-PASSWORD_MANAGERS: Sequence[type[pm.PasswordManager]] = [
+SUPPORTED_PASSWORD_MANAGERS: Sequence[type[pm.PasswordManager]] = [
+    pm.M2MPasswordManager,
     pm.KeyringPasswordManager,
     pm.FilePasswordManager,
 ]
+
 _logger = logging.getLogger(__name__)
 
 
@@ -57,9 +59,11 @@ class TokenManager:
 
         if should_skip_authentication:
             return pm.DummyPasswordManager()
-        if config.text_only:
-            return pm.FilePasswordManager()
-        for password_manager in PASSWORD_MANAGERS:
+
+        # Filter out M2MPasswordManager and FilePasswordManager in text-only mode
+        for password_manager in SUPPORTED_PASSWORD_MANAGERS:
+            if config.text_only and not password_manager.text_only_supported:
+                continue
             if password_manager.is_supported():
                 return password_manager()
         raise ClassiqPasswordManagerSelectionError(
@@ -75,6 +79,10 @@ class TokenManager:
         self._save_tokens(tokens)
 
     async def update_expired_access_token(self) -> None:
+        if not self._password_manager.has_refresh_token:
+            await self._authentication_helper()
+            return
+
         if self._refresh_token is not None:
             await self._refresh()
             return
@@ -84,6 +92,11 @@ class TokenManager:
         )
 
     async def manual_authentication(self, overwrite: bool) -> None:
+        # For M2M authentication, always re-authenticate (no refresh token concept)
+        if not self._password_manager.has_refresh_token:
+            await self._authentication_helper()
+            return
+
         if self._refresh_token is None:
             await self._authentication_helper()
             return
@@ -126,8 +139,11 @@ class TokenManager:
     async def _authentication_helper(self) -> None:
         # TODO: consider using refresh token rotation
         #  (https://auth0.com/docs/tokens/refresh-tokens/refresh-token-rotation)
-        authorization_flow = HybridFlow(
-            require_refresh_token=True, text_only=self._config.text_only
+        authorization_flow = AuthFlowFactory.create_flow(
+            password_manager=self._password_manager, config=self._config
         )
         tokens = await authorization_flow.get_tokens()
-        self._save_tokens(tokens, force_override_refresh_token=True)
+
+        # Password managers without refresh tokens don't use rotation
+        force_override = self._password_manager.has_refresh_token
+        self._save_tokens(tokens, force_override_refresh_token=force_override)

classiq/analyzer/show_interactive_hack.py

@@ -7,8 +7,6 @@ from tempfile import NamedTemporaryFile
 from urllib.parse import urljoin
 
 from classiq.interface.analyzer.result import DataID
-from classiq.interface.exceptions import ClassiqAnalyzerVisualizationError
-from classiq.interface.generator.model.preferences.preferences import QuantumFormat
 from classiq.interface.generator.quantum_program import QuantumProgram
 
 from classiq._internals.api_wrapper import ApiWrapper
@@ -116,12 +114,6 @@ def get_visualization_renderer() -> VisualizationRenderer:
 
 
 async def handle_remote_app(circuit: QuantumProgram, display_url: bool = True) -> None:
-    if circuit.outputs.get(QuantumFormat.QASM) is None:
-        raise ClassiqAnalyzerVisualizationError(
-            "Missing QASM transpilation: visualization is only supported "
-            "for QASM programs. Try adding QASM to the output formats "
-            "synthesis preferences"
-        )
     circuit_dataid = DataID(id=circuit.program_id)
 
     renderer = get_visualization_renderer()

classiq/applications/combinatorial_optimization/combinatorial_problem.py

@@ -37,7 +37,7 @@ class CombinatorialProblem:
         self,
         pyo_model: pyo.ConcreteModel,
         num_layers: int,
-        penalty_factor: int = 1,
+        penalty_factor: float = 1,
     ):
         self.problem_vars_, self.cost_func = pyo_model_to_qmod_problem(
             pyo_model, penalty_factor

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/functions/__init__.py

@@ -1,3 +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__ = ["_new_sample"]
+__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
+        )