Execution - Classiq Docs

Members:

Name	Description
`ProviderConfig`	Provider-specific configuration data for execution, such as API keys and machine-specific parameters.
`ExecutionPreferences`	Represents the execution settings for running a quantum program.
`TranspilationOption`	Transpilation optimization level for quantum circuits.
`ExecutionSession`	A session for executing a quantum program or OpenQASM source text.
`sample`	Sample a quantum program or OpenQASM circuit.

ProviderConfig

Provider-specific configuration data for execution, such as API keys and machine-specific parameters.

ExecutionPreferences

Represents the execution settings for running a quantum program. Execution preferences for running a quantum program. For more details, refer to: ExecutionPreferences example: ExecutionPreferences.. Attributes:

Name	Type	Description
`include_zero_amplitude_outputs`	`bool`
`amplitude_threshold`	`float`
`noise_properties`	`Optional[NoiseProperties]`	Properties defining the noise in the quantum circuit. Defaults to `None`.
`random_seed`	`int`	The random seed used for the execution. Defaults to a randomly generated seed.
`backend_preferences`	`BackendPreferencesTypes`	Preferences for the backend used to execute the circuit. Defaults to the Classiq Simulator.
`num_shots`	`Optional[pydantic.PositiveInt]`	The number of shots (executions) to be performed.
`transpile_to_hardware`	`TranspilationOption`	Option to transpile the circuit to the hardware’s basis gates before execution. Defaults to `TranspilationOption.DECOMPOSE`.
`job_name`	`Optional[str]`	The name of the job, with a minimum length of 1 character.

TranspilationOption

Transpilation optimization level for quantum circuits. Attributes:

Name	Type	Description
`NONE`	`'none'`
`DECOMPOSE`	`'decompose'`
`AUTO_OPTIMIZE`	`'auto optimize'`
`LIGHT`	`'light'`
`MEDIUM`	`'medium'`
`INTENSIVE`	`'intensive'`
`CUSTOM`	`'custom'`

ExecutionSession

A session for executing a quantum program or OpenQASM source text. ExecutionSession allows to execute the quantum program with different parameters and operations without the need to re-synthesize the model. The session must be closed in order to ensure resources are properly cleaned up. It’s recommended to use ExecutionSession as a context manager for this purpose. Alternatively, you can directly use the close method. Methods:

Name	Description
close	Close the session and clean up its resources.
get_session_id
update_execution_preferences	Update the execution preferences for the session.
sample	Samples the quantum program with the given parameters, if any.
submit_sample	Initiates an execution job with the `sample` primitive.
calculate_state_vector	Calculate the state vector of the quantum program.
submit_calculate_state_vector	Initiates an execution job with the `calculate_state_vector` primitive.
batch_sample	Samples the quantum program multiple times with the given parameters for each iteration.
submit_batch_sample	Initiates an execution job with the `batch_sample` primitive.
observe	Estimates the expectation value of the given Hamiltonian using the quantum program.
submit_observe	Initiates an execution job with the `observe` primitive.
estimate	Estimates the expectation value of the given Hamiltonian using the quantum program.
submit_estimate	Initiates an execution job with the `estimate` primitive.
batch_estimate	Estimates the expectation value of the given Hamiltonian multiple times using the quantum program, with the given parameters for each iteration.
submit_batch_estimate	Initiates an execution job with the `batch_estimate` primitive.
variational_minimize	Variationally minimizes the given cost function using the quantum program.
minimize	.
submit_variational_minimize	Initiates an execution job with the variational minimization primitive.
submit_minimize	.
estimate_cost	Estimates circuit cost using a classical cost function.
set_measured_state_filter	When simulating on a statevector simulator, emulate the behavior of postprocessing by discarding amplitudes for which their states are “undesirable”.

Attributes:

Name	Type	Description
`program`	`QuantumProgram`	The quantum program to execute, or a placeholder when the first constructor argument was OpenQASM source text.

close

close(
self:
) -> None

Close the session and clean up its resources. Parameters:

Name	Type	Description	Default
`self`	“		required

get_session_id

get_session_id(
self:
) -> str

Parameters:

Name	Type	Description	Default
`self`	“		required

update_execution_preferences

update_execution_preferences(
self: ,
execution_preferences: ExecutionPreferences | None
) -> None

Update the execution preferences for the session. Parameters:

Name	Type	Description	Default
`self`	“		required
`execution_preferences`	ExecutionPreferences \| None	The execution preferences to update.	required

Returns:

Type: None

sample

sample(
self: ,
parameters: ExecutionParams | list[ExecutionParams] | None = None,
num_shots: int | None = None,
run_via_classiq: bool | None = None
) -> ExecutionDetails | list[ExecutionDetails]

Samples the quantum program with the given parameters, if any. Parameters:

Name	Type	Description	Default
`self`	“		required
`parameters`	`ExecutionParams \| list[ExecutionParams] \| None`	A dictionary of parameter values, or a list of dictionaries for batch execution. Each key should be the name of a parameter in the quantum program (parameters of the main function), and the value should be the value to set for that parameter.	None
`num_shots`	`int \| None`	Number of shots for this call only; overrides the session default when set.	None
`run_via_classiq`	`bool \| None`	Run via Classiq credentials for this call only; overrides the session default when set.	None

Returns:

Type: ExecutionDetails \| list[ExecutionDetails]
The result of the sampling, or a list of results when
parameters is a list.

submit_sample

submit_sample(
self: ,
parameters: ExecutionParams | list[ExecutionParams] | None = None,
num_shots: int | None = None,
run_via_classiq: bool | None = None
) -> ExecutionJob

Initiates an execution job with the sample primitive. This is a non-blocking version of sample: it gets the same parameters and initiates the same execution job, but instead of waiting for the result, it returns the job object immediately. Parameters:

Name	Type	Description	Default
`self`	“		required
`parameters`	`ExecutionParams \| list[ExecutionParams] \| None`	A dictionary of parameter values, or a list of dictionaries for batch execution. Each key should be the name of a parameter in the quantum program (parameters of the main function), and the value should be the value to set for that parameter.	None
`num_shots`	`int \| None`	Number of shots for this call only; overrides the session default when set.	None
`run_via_classiq`	`bool \| None`	Run via Classiq credentials for this call only; overrides the session default when set.	None

Returns:

Type: ExecutionJob
The execution job.

calculate_state_vector

calculate_state_vector(
self: ,
parameters: ExecutionParams | list[ExecutionParams] | None = None,
filters: dict[str, Any] | None = None,
amplitude_threshold: float = 0.0
) -> DataFrame | list[DataFrame]

Calculate the state vector of the quantum program. The session must be configured with a Classiq simulator ("classiq/simulator", "classiq/nvidia_simulator") or "google/cuquantum". The corresponding statevector variant is selected automatically; callers do not need to know about the _statevector backend names. Parameters:

Name	Type	Description	Default
`self`	“		required
`parameters`	`ExecutionParams \| list[ExecutionParams] \| None`	A dictionary of parameter values, or a list of dictionaries for batch execution.	None
`filters`	`dict[str, Any] \| None`	Only states where the variables match these values will be included in the state vector.	None
`amplitude_threshold`	`float`	If provided, only states whose amplitude magnitude is strictly greater than this value will be included in the result. Defaults to 0 (filters exactly zero-amplitude states).	0.0

Returns:

Type: DataFrame \| list[DataFrame]
A dataframe containing the state vector, or a list of dataframes when
parameters is a list.

submit_calculate_state_vector

submit_calculate_state_vector(
self: ,
parameters: ExecutionParams | list[ExecutionParams] | None = None,
filters: dict[str, Any] | None = None,
amplitude_threshold: float = 0.0
) -> ExecutionJob

Initiates an execution job with the calculate_state_vector primitive. This is a non-blocking version of calculate_state_vector(): it gets the same parameters and initiates the same execution job, but instead of waiting for the result, it returns the job object immediately. Parameters:

Name	Type	Description	Default
`self`	“		required
`parameters`	`ExecutionParams \| list[ExecutionParams] \| None`	See calculate_state_vector().	None
`filters`	`dict[str, Any] \| None`	See calculate_state_vector().	None
`amplitude_threshold`	`float`	See calculate_state_vector().	0.0

Returns:

Type: ExecutionJob
The execution job.

batch_sample

batch_sample(
self: ,
parameters: list[ExecutionParams]
) -> list[ExecutionDetails]

Samples the quantum program multiple times with the given parameters for each iteration. The number of samples is determined by the length of the parameters list. Deprecated: Pass a list of parameter dicts to sample() instead. Parameters:

Name	Type	Description	Default
`self`	“		required
`parameters`	`list[ExecutionParams]`	A list of the parameters for each iteration. Each item is a dictionary where each key should be the name of a parameter in the quantum program (parameters of the main function), and the value should be the value to set for that parameter.	required

Returns:

Type: list[ExecutionDetails]
List[ExecutionDetails]: The results of all the sampling iterations.

submit_batch_sample

submit_batch_sample(
self: ,
parameters: list[ExecutionParams]
) -> ExecutionJob

Initiates an execution job with the batch_sample primitive. Deprecated: Pass a list of parameter dicts to submit_sample() instead. Parameters:

Name	Type	Description	Default
`self`	“		required
`parameters`	`list[ExecutionParams]`	A list of the parameters for each iteration. Each item is a dictionary where each key should be the name of a parameter in the quantum program (parameters of the main function), and the value should be the value to set for that parameter.	required

Returns:

Type: ExecutionJob
The execution job.

observe

observe(
self: ,
hamiltonian: Hamiltonian,
parameters: ExecutionParams | list[ExecutionParams] | None = None,
num_shots: int | None = None,
run_via_classiq: bool | None = None
) -> EstimationResult | list[EstimationResult]

Estimates the expectation value of the given Hamiltonian using the quantum program. Parameters:

Name	Type	Description	Default
`self`	“		required
`hamiltonian`	`Hamiltonian`	The Hamiltonian to estimate the expectation value of.	required
`parameters`	`ExecutionParams \| list[ExecutionParams] \| None`	A dictionary of parameter values, or a list of dictionaries for batch execution. Each key should be the name of a parameter in the quantum program (parameters of the main function), and the value should be the value to set for that parameter.	None
`num_shots`	`int \| None`	Number of shots for this call only; overrides the session default when set.	None
`run_via_classiq`	`bool \| None`	Run via Classiq credentials for this call only; overrides the session default when set.	None

Returns:

Type: EstimationResult \| list[EstimationResult]
The estimation result, or a list of results when parameters
is a list.

submit_observe

submit_observe(
self: ,
hamiltonian: Hamiltonian,
parameters: ExecutionParams | list[ExecutionParams] | None = None,
num_shots: int | None = None,
run_via_classiq: bool | None = None
) -> ExecutionJob

Initiates an execution job with the observe primitive. This is a non-blocking version of observe(): it gets the same parameters and initiates the same execution job, but instead of waiting for the result, it returns the job object immediately. Parameters:

Name	Type	Description	Default
`self`	“		required
`hamiltonian`	`Hamiltonian`	The Hamiltonian to estimate the expectation value of.	required
`parameters`	`ExecutionParams \| list[ExecutionParams] \| None`	A dictionary of parameter values, or a list of dictionaries for batch execution. Each key should be the name of a parameter in the quantum program (parameters of the main function), and the value should be the value to set for that parameter.	None
`num_shots`	`int \| None`	Number of shots for this call only; overrides the session default when set.	None
`run_via_classiq`	`bool \| None`	Run via Classiq credentials for this call only; overrides the session default when set.	None

Returns:

Type: ExecutionJob
The execution job.

estimate

estimate(
self: ,
hamiltonian: Hamiltonian,
parameters: ExecutionParams | list[ExecutionParams] | None = None,
num_shots: int | None = None,
run_via_classiq: bool | None = None
) -> EstimationResult | list[EstimationResult]

Estimates the expectation value of the given Hamiltonian using the quantum program. Deprecated: estimate is deprecated and will no longer be supported starting on 2026-06-22. Use observe() instead. Parameters:

Name	Type	Default
`self`	“	required
`hamiltonian`	`Hamiltonian`	required
`parameters`	`ExecutionParams \| list[ExecutionParams] \| None`	None
`num_shots`	`int \| None`	None
`run_via_classiq`	`bool \| None`	None

submit_estimate

submit_estimate(
self: ,
hamiltonian: Hamiltonian,
parameters: ExecutionParams | list[ExecutionParams] | None = None,
num_shots: int | None = None,
run_via_classiq: bool | None = None
) -> ExecutionJob

Initiates an execution job with the estimate primitive. Deprecated: submit_estimate is deprecated and will no longer be supported starting on 2026-06-22. Use submit_observe() instead. Parameters:

Name	Type	Default
`self`	“	required
`hamiltonian`	`Hamiltonian`	required
`parameters`	`ExecutionParams \| list[ExecutionParams] \| None`	None
`num_shots`	`int \| None`	None
`run_via_classiq`	`bool \| None`	None

batch_estimate

batch_estimate(
self: ,
hamiltonian: Hamiltonian,
parameters: list[ExecutionParams]
) -> list[EstimationResult]

Estimates the expectation value of the given Hamiltonian multiple times using the quantum program, with the given parameters for each iteration. The number of estimations is determined by the length of the parameters list. Deprecated: Pass a list of parameter dicts to observe() instead. Parameters:

Name	Type	Description	Default
`self`	“		required
`hamiltonian`	`Hamiltonian`	The Hamiltonian to estimate the expectation value of.	required
`parameters`	`list[ExecutionParams]`	A list of the parameters for each iteration. Each item is a dictionary where each key should be the name of a parameter in the quantum program (parameters of the main function), and the value should be the value to set for that parameter.	required

Returns:

Type: list[EstimationResult]
List[EstimationResult]: The results of all the estimation iterations.

submit_batch_estimate

submit_batch_estimate(
self: ,
hamiltonian: Hamiltonian,
parameters: list[ExecutionParams]
) -> ExecutionJob

Initiates an execution job with the batch_estimate primitive. Deprecated: Pass a list of parameter dicts to submit_observe() instead. Parameters:

Name	Type	Description	Default
`self`	“		required
`hamiltonian`	`Hamiltonian`	The Hamiltonian to estimate the expectation value of.	required
`parameters`	`list[ExecutionParams]`	A list of the parameters for each iteration. Each item is a dictionary where each key should be the name of a parameter in the quantum program (parameters of the main function), and the value should be the value to set for that parameter.	required

Returns:

Type: ExecutionJob
The execution job.

variational_minimize

variational_minimize(
self: ,
cost_function: Hamiltonian | QmodExpressionCreator,
initial_params: ExecutionParams,
max_iteration: int,
quantile: float = 1.0,
tolerance: float | None = None,
hosted: bool = False,
num_shots: int | None = None,
run_via_classiq: bool | None = None
) -> list[tuple[float, ExecutionParams]]

Variationally minimizes the given cost function using the quantum program. Parameters:

Name	Type	Description	Default
`self`	“		required
`cost_function`	`Hamiltonian \| QmodExpressionCreator`	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.	required
`initial_params`	`ExecutionParams`	The initial parameters for the minimization. Only Models with exactly one execution parameter are supported. 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.	required
`max_iteration`	`int`	The maximum number of iterations for the minimization.	required
`quantile`	`float`	The quantile to use for cost estimation.	1.0
`tolerance`	`float \| None`	The tolerance for the minimization.	None
`hosted`	`bool`	When `True` on an IonQ backend, submit a Classiq execution job that runs the optimization loop on IonQ Hosted Hybrid in the backend. Defaults to `False`.	False
`num_shots`	`int \| None`	Number of shots for this call only; overrides the session default when set.	None
`run_via_classiq`	`bool \| None`	Run via Classiq credentials for this call only; overrides the session default when set.	None

Returns:

Type: list[tuple[float, ExecutionParams]]
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.

minimize

minimize(
self: ,
cost_function: Hamiltonian | QmodExpressionCreator,
initial_params: ExecutionParams,
max_iteration: int,
quantile: float = 1.0,
tolerance: float | None = None,
num_shots: int | None = None,
run_via_classiq: bool | None = None
) -> list[tuple[float, ExecutionParams]]

Deprecated: Use variational_minimize() instead. This name is kept for backward compatibility and will be removed in a future release. Parameters:

Name	Type	Default
`self`	“	required
`cost_function`	`Hamiltonian \| QmodExpressionCreator`	required
`initial_params`	`ExecutionParams`	required
`max_iteration`	`int`	required
`quantile`	`float`	1.0
`tolerance`	`float \| None`	None
`num_shots`	`int \| None`	None
`run_via_classiq`	`bool \| None`	None

submit_variational_minimize

submit_variational_minimize(
self: ,
cost_function: Hamiltonian | QmodExpressionCreator,
initial_params: ExecutionParams,
max_iteration: int,
quantile: float = 1.0,
tolerance: float | None = None,
hosted: bool = False,
num_shots: int | None = None,
run_via_classiq: bool | None = None
) -> ExecutionJob

Initiates an execution job with the variational minimization primitive. Non-blocking counterpart of variational_minimize(): same parameters and job, but returns the ExecutionJob immediately. Parameters:

Name	Type	Description	Default
`self`	“		required
`cost_function`	`Hamiltonian \| QmodExpressionCreator`	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.	required
`initial_params`	`ExecutionParams`	The initial parameters for the minimization. Only Models with exactly one execution parameter are supported. 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.	required
`max_iteration`	`int`	The maximum number of iterations for the minimization.	required
`quantile`	`float`	The quantile to use for cost estimation.	1.0
`tolerance`	`float \| None`	The tolerance for the minimization.	None
`hosted`	`bool`	When `True` on an IonQ backend, submit a Classiq execution job that runs the optimization loop on IonQ Hosted Hybrid in the backend. Defaults to `False`.	False
`num_shots`	`int \| None`	Number of shots for this call only; overrides the session default when set.	None
`run_via_classiq`	`bool \| None`	Run via Classiq credentials for this call only; overrides the session default when set.	None

Returns:

Type: ExecutionJob
The execution job. When hosted=True on an IonQ backend, the backend
worker submits and polls IonQ Hosted Hybrid while this job tracks
progress through the standard Classiq execution API.

submit_minimize

submit_minimize(
self: ,
cost_function: Hamiltonian | QmodExpressionCreator,
initial_params: ExecutionParams,
max_iteration: int,
quantile: float = 1.0,
tolerance: float | None = None,
num_shots: int | None = None,
run_via_classiq: bool | None = None
) -> ExecutionJob

Deprecated: Use submit_variational_minimize() instead. This name is kept for backward compatibility and will be removed in a future release. Parameters:

Name	Type	Default
`self`	“	required
`cost_function`	`Hamiltonian \| QmodExpressionCreator`	required
`initial_params`	`ExecutionParams`	required
`max_iteration`	`int`	required
`quantile`	`float`	1.0
`tolerance`	`float \| None`	None
`num_shots`	`int \| None`	None
`run_via_classiq`	`bool \| None`	None

estimate_cost

estimate_cost(
self: ,
cost_func: Callable[[ParsedState], float],
parameters: ExecutionParams | None = None,
quantile: float = 1.0,
num_shots: int | None = None,
run_via_classiq: bool | None = None
) -> float

Estimates circuit cost using a classical cost function. Parameters:

Name	Type	Description	Default
`self`	“		required
`cost_func`	`Callable[[ParsedState], float]`	classical circuit sample cost function	required
`parameters`	`ExecutionParams \| None`	execution parameters sent to ‘sample’	None
`quantile`	`float`	drop cost values outside the specified quantile	1.0
`num_shots`	`int \| None`	Number of shots for this call only; overrides the session default when set.	None
`run_via_classiq`	`bool \| None`	Run via Classiq credentials for this call only; overrides the session default when set.	None

Returns:

Type: float
cost estimation

set_measured_state_filter

set_measured_state_filter(
self: ,
output_name: str,
condition: Callable
) -> None

When simulating on a statevector simulator, emulate the behavior of postprocessing by discarding amplitudes for which their states are “undesirable”. Parameters:

Name	Type	Description	Default
`self`	“		required
`output_name`	`str`	The name of the register to filter	required
`condition`	`Callable`	Filter out values of the statevector for which this callable is False	required

sample

sample(
qprog: QuantumProgram | str,
backend: str | None = None,
parameters: ExecutionParams | list[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,
run_via_classiq: bool = False
) -> DataFrame | list[DataFrame]

Sample a quantum program or OpenQASM circuit. Parameters:

Name	Type	Description	Default
`qprog`	`QuantumProgram \| str`	A synthesized `QuantumProgram`, or OpenQASM 2.0 / 3.0 source as a single string (for example output of `qiskit.qasm2.dumps` or `qiskit.qasm3.dumps`).	required
`backend`	`str \| None`	The hardware or simulator on which to run the quantum program. Use `"simulator"` for Classiq’s default simulator, or specify a backend as `"provider/device_id"`. Use the `get_backend_details` function to see supported devices.	None
`parameters`	`ExecutionParams \| list[ExecutionParams] \| None`	A dictionary of parameter values, or a list of dictionaries for batch execution. Each key should be the name of a parameter in the quantum program (parameters of the `main` function), and the value should be the value to set for that parameter. Not supported when `qprog` is an OpenQASM string (use a `QuantumProgram` or bind values in QASM before calling `sample`).	None
`config`	dict[str, Any] \| ProviderConfig \| None	Provider-specific configuration, such as API keys. For full details, see the SDK reference under Providers.	None
`num_shots`	`int \| None`	The number of times to sample.	None
`random_seed`	`int \| None`	The random seed used for transpilation and simulation.	None
`transpilation_option`	`TranspilationOption`	Advanced configuration for hardware-specific transpilation.	TranspilationOption.DECOMPOSE
`run_via_classiq`	`bool`	Run via Classiq’s credentials while using your allocated budget. Defaults to `False`.	False

Returns:

Type: DataFrame \| list[DataFrame]
A dataframe containing the histogram, or a list of dataframes when
parameters is a list.

BraketConfig

Configuration specific to Amazon Braket. Attributes:

Name	Type	Description
`braket_access_key_id`	`str \| None`	The access key id of user with full braket access
`braket_secret_access_key`	`str \| None`	The secret key assigned to the access key id for the user with full braket access.
`s3_bucket_name`	`str \| None`	The name of the S3 bucket where results and other related data will be stored. This field should contain a valid S3 bucket name under your AWS account.
`s3_folder`	`pydantic_backend.PydanticS3BucketKey \| None`	The folder path within the specified S3 bucket. This allows for organizing results and data under a specific directory within the S3 bucket.

IBMConfig

Configuration specific to IBM. Attributes:

Name	Type	Description
`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 \| None`	The IBM Cloud instance CRN (Cloud Resource Name) for the IBM Quantum service.
`emulate`	`bool`	If True, run on a Classiq-hosted simulator with IBM noise derived from the backend name. Defaults to `False`.

IonQConfig

Configuration specific to IonQ. Attributes: api_key (PydanticIonQApiKeyType | None): Key to access IonQ API. error_mitigation (bool): A configuration option to enable or disable error mitigation during execution. Defaults to False. emulate (bool): If True, run on IonQ simulator with noise model derived from the backend name. Defaults to False. Attributes:

Name	Type	Description
`api_key`	`pydantic_backend.PydanticIonQApiKeyType \| None`
`error_mitigation`	`bool`
`emulate`	`bool`

AzureConfig

Configuration specific to Azure. Attributes:

Name	Type	Description
`location`	`str`	Azure region. Defaults to `"East US"`.
`tenant_id`	`str \| None`	Azure Tenant ID used to identify the directory in which the application is registered.
`client_id`	`str \| None`	Azure Client ID, also known as the application ID, which is used to authenticate the application.
`client_secret`	`str \| None`	Azure Client Secret associated with the application, used for authentication.
`resource_id`	`str \| None`	Azure Resource ID, including the subscription ID, resource group, and workspace, typically used for personal resources.
`ionq_error_mitigation`	`bool`	Should use error mitigation when running on IonQ via Azure. Defaults to `False`.
`emulate`	`bool`	When True, request IonQ hardware noise simulation on Azure Quantum for IonQ QPU targets (`ionq.qpu.*`). No effect for `ionq.simulator` or non-IonQ targets. Defaults to `False`.

AQTConfig

Configuration specific to AQT (Alpine Quantum Technologies). Attributes:

Name	Type	Description
`api_key`	`str`	The API key required to access AQT’s quantum computing services.
`workspace`	`str`	The AQT workspace where the simulator/hardware is located.

AliceBobConfig

Configuration specific to Alice&Bob. Attributes:

Name	Type	Description
`distance`	`int \| None`	The number of times information is duplicated in the repetition code. - Tooltip: Phase-flip probability decreases exponentially with this parameter, bit-flip probability increases linearly. - Supported Values: 3 to 300, though practical values are usually lower than 30. - Default: None.
`kappa_1`	`float \| None`	The rate at which the cat qubit loses one photon, creating a bit-flip. - Tooltip: Lower values mean lower error rates. - Supported Values: 10 to 10^5. Current hardware is at ~10^3. - Default: None.
`kappa_2`	`float \| None`	The rate at which the cat qubit is stabilized using two-photon dissipation. - Tooltip: Higher values mean lower error rates. - Supported Values: 100 to 10^9. Current hardware is at ~10^5. - Default: None.
`average_nb_photons`	`float \| None`	The average number of photons. - Tooltip: Bit-flip probability decreases exponentially with this parameter, phase-flip probability increases linearly. - Supported Values: 4 to 10^5, though practical values are usually lower than 30. - Default: None.

ProviderConfig

Provider-specific configuration data for execution, such as API keys and machine-specific parameters.

ExecutionSession

Name	Description
close	Close the session and clean up its resources.
get_session_id
update_execution_preferences	Update the execution preferences for the session.
sample	Samples the quantum program with the given parameters, if any.
submit_sample	Initiates an execution job with the `sample` primitive.
calculate_state_vector	Calculate the state vector of the quantum program.
submit_calculate_state_vector	Initiates an execution job with the `calculate_state_vector` primitive.
batch_sample	Samples the quantum program multiple times with the given parameters for each iteration.
submit_batch_sample	Initiates an execution job with the `batch_sample` primitive.
observe	Estimates the expectation value of the given Hamiltonian using the quantum program.
submit_observe	Initiates an execution job with the `observe` primitive.
estimate	Estimates the expectation value of the given Hamiltonian using the quantum program.
submit_estimate	Initiates an execution job with the `estimate` primitive.
batch_estimate	Estimates the expectation value of the given Hamiltonian multiple times using the quantum program, with the given parameters for each iteration.
submit_batch_estimate	Initiates an execution job with the `batch_estimate` primitive.
variational_minimize	Variationally minimizes the given cost function using the quantum program.
minimize	.
submit_variational_minimize	Initiates an execution job with the variational minimization primitive.
submit_minimize	.
estimate_cost	Estimates circuit cost using a classical cost function.
set_measured_state_filter	When simulating on a statevector simulator, emulate the behavior of postprocessing by discarding amplitudes for which their states are “undesirable”.

Attributes:

Name	Type	Description
`program`	`QuantumProgram`	The quantum program to execute, or a placeholder when the first constructor argument was OpenQASM source text.

close

close(
self:
) -> None

Close the session and clean up its resources. Parameters:

Name	Type	Description	Default
`self`	“		required

get_session_id

get_session_id(
self:
) -> str

Parameters:

Name	Type	Description	Default
`self`	“		required

update_execution_preferences

update_execution_preferences(
self: ,
execution_preferences: ExecutionPreferences | None
) -> None

Update the execution preferences for the session. Parameters:

Name	Type	Description	Default
`self`	“		required
`execution_preferences`	ExecutionPreferences \| None	The execution preferences to update.	required

Returns:

Type: None

sample

sample(
self: ,
parameters: ExecutionParams | list[ExecutionParams] | None = None,
num_shots: int | None = None,
run_via_classiq: bool | None = None
) -> ExecutionDetails | list[ExecutionDetails]

Samples the quantum program with the given parameters, if any. Parameters:

Name	Type	Description	Default
`self`	“		required
`parameters`	`ExecutionParams \| list[ExecutionParams] \| None`	A dictionary of parameter values, or a list of dictionaries for batch execution. Each key should be the name of a parameter in the quantum program (parameters of the main function), and the value should be the value to set for that parameter.	None
`num_shots`	`int \| None`	Number of shots for this call only; overrides the session default when set.	None
`run_via_classiq`	`bool \| None`	Run via Classiq credentials for this call only; overrides the session default when set.	None

Returns:

Type: ExecutionDetails \| list[ExecutionDetails]
The result of the sampling, or a list of results when
parameters is a list.

submit_sample

submit_sample(
self: ,
parameters: ExecutionParams | list[ExecutionParams] | None = None,
num_shots: int | None = None,
run_via_classiq: bool | None = None
) -> ExecutionJob

Name	Type	Description	Default
`self`	“		required
`parameters`	`ExecutionParams \| list[ExecutionParams] \| None`	A dictionary of parameter values, or a list of dictionaries for batch execution. Each key should be the name of a parameter in the quantum program (parameters of the main function), and the value should be the value to set for that parameter.	None
`num_shots`	`int \| None`	Number of shots for this call only; overrides the session default when set.	None
`run_via_classiq`	`bool \| None`	Run via Classiq credentials for this call only; overrides the session default when set.	None

Returns:

Type: ExecutionJob
The execution job.

calculate_state_vector

calculate_state_vector(
self: ,
parameters: ExecutionParams | list[ExecutionParams] | None = None,
filters: dict[str, Any] | None = None,
amplitude_threshold: float = 0.0
) -> DataFrame | list[DataFrame]

Name	Type	Description	Default
`self`	“		required
`parameters`	`ExecutionParams \| list[ExecutionParams] \| None`	A dictionary of parameter values, or a list of dictionaries for batch execution.	None
`filters`	`dict[str, Any] \| None`	Only states where the variables match these values will be included in the state vector.	None
`amplitude_threshold`	`float`	If provided, only states whose amplitude magnitude is strictly greater than this value will be included in the result. Defaults to 0 (filters exactly zero-amplitude states).	0.0

Returns:

Type: DataFrame \| list[DataFrame]
A dataframe containing the state vector, or a list of dataframes when
parameters is a list.

submit_calculate_state_vector

submit_calculate_state_vector(
self: ,
parameters: ExecutionParams | list[ExecutionParams] | None = None,
filters: dict[str, Any] | None = None,
amplitude_threshold: float = 0.0
) -> ExecutionJob

Name	Type	Description	Default
`self`	“		required
`parameters`	`ExecutionParams \| list[ExecutionParams] \| None`	See calculate_state_vector().	None
`filters`	`dict[str, Any] \| None`	See calculate_state_vector().	None
`amplitude_threshold`	`float`	See calculate_state_vector().	0.0

Returns:

Type: ExecutionJob
The execution job.

batch_sample

batch_sample(
self: ,
parameters: list[ExecutionParams]
) -> list[ExecutionDetails]

Name	Type	Description	Default
`self`	“		required
`parameters`	`list[ExecutionParams]`	A list of the parameters for each iteration. Each item is a dictionary where each key should be the name of a parameter in the quantum program (parameters of the main function), and the value should be the value to set for that parameter.	required

Returns:

Type: list[ExecutionDetails]
List[ExecutionDetails]: The results of all the sampling iterations.

submit_batch_sample

submit_batch_sample(
self: ,
parameters: list[ExecutionParams]
) -> ExecutionJob

Initiates an execution job with the batch_sample primitive. Deprecated: Pass a list of parameter dicts to submit_sample() instead. Parameters:

Name	Type	Description	Default
`self`	“		required
`parameters`	`list[ExecutionParams]`	A list of the parameters for each iteration. Each item is a dictionary where each key should be the name of a parameter in the quantum program (parameters of the main function), and the value should be the value to set for that parameter.	required

Returns:

Type: ExecutionJob
The execution job.

observe

observe(
self: ,
hamiltonian: Hamiltonian,
parameters: ExecutionParams | list[ExecutionParams] | None = None,
num_shots: int | None = None,
run_via_classiq: bool | None = None
) -> EstimationResult | list[EstimationResult]

Estimates the expectation value of the given Hamiltonian using the quantum program. Parameters:

Name	Type	Description	Default
`self`	“		required
`hamiltonian`	`Hamiltonian`	The Hamiltonian to estimate the expectation value of.	required
`parameters`	`ExecutionParams \| list[ExecutionParams] \| None`	A dictionary of parameter values, or a list of dictionaries for batch execution. Each key should be the name of a parameter in the quantum program (parameters of the main function), and the value should be the value to set for that parameter.	None
`num_shots`	`int \| None`	Number of shots for this call only; overrides the session default when set.	None
`run_via_classiq`	`bool \| None`	Run via Classiq credentials for this call only; overrides the session default when set.	None

Returns:

Type: EstimationResult \| list[EstimationResult]
The estimation result, or a list of results when parameters
is a list.

submit_observe

submit_observe(
self: ,
hamiltonian: Hamiltonian,
parameters: ExecutionParams | list[ExecutionParams] | None = None,
num_shots: int | None = None,
run_via_classiq: bool | None = None
) -> ExecutionJob

Name	Type	Description	Default
`self`	“		required
`hamiltonian`	`Hamiltonian`	The Hamiltonian to estimate the expectation value of.	required
`parameters`	`ExecutionParams \| list[ExecutionParams] \| None`	A dictionary of parameter values, or a list of dictionaries for batch execution. Each key should be the name of a parameter in the quantum program (parameters of the main function), and the value should be the value to set for that parameter.	None
`num_shots`	`int \| None`	Number of shots for this call only; overrides the session default when set.	None
`run_via_classiq`	`bool \| None`	Run via Classiq credentials for this call only; overrides the session default when set.	None

Returns:

Type: ExecutionJob
The execution job.

estimate

estimate(
self: ,
hamiltonian: Hamiltonian,
parameters: ExecutionParams | list[ExecutionParams] | None = None,
num_shots: int | None = None,
run_via_classiq: bool | None = None
) -> EstimationResult | list[EstimationResult]

Name	Type	Default
`self`	“	required
`hamiltonian`	`Hamiltonian`	required
`parameters`	`ExecutionParams \| list[ExecutionParams] \| None`	None
`num_shots`	`int \| None`	None
`run_via_classiq`	`bool \| None`	None

submit_estimate

submit_estimate(
self: ,
hamiltonian: Hamiltonian,
parameters: ExecutionParams | list[ExecutionParams] | None = None,
num_shots: int | None = None,
run_via_classiq: bool | None = None
) -> ExecutionJob

Name	Type	Default
`self`	“	required
`hamiltonian`	`Hamiltonian`	required
`parameters`	`ExecutionParams \| list[ExecutionParams] \| None`	None
`num_shots`	`int \| None`	None
`run_via_classiq`	`bool \| None`	None

batch_estimate

batch_estimate(
self: ,
hamiltonian: Hamiltonian,
parameters: list[ExecutionParams]
) -> list[EstimationResult]

Name	Type	Description	Default
`self`	“		required
`hamiltonian`	`Hamiltonian`	The Hamiltonian to estimate the expectation value of.	required
`parameters`	`list[ExecutionParams]`	A list of the parameters for each iteration. Each item is a dictionary where each key should be the name of a parameter in the quantum program (parameters of the main function), and the value should be the value to set for that parameter.	required

Returns:

Type: list[EstimationResult]
List[EstimationResult]: The results of all the estimation iterations.

submit_batch_estimate

submit_batch_estimate(
self: ,
hamiltonian: Hamiltonian,
parameters: list[ExecutionParams]
) -> ExecutionJob

Initiates an execution job with the batch_estimate primitive. Deprecated: Pass a list of parameter dicts to submit_observe() instead. Parameters:

Name	Type	Description	Default
`self`	“		required
`hamiltonian`	`Hamiltonian`	The Hamiltonian to estimate the expectation value of.	required
`parameters`	`list[ExecutionParams]`	A list of the parameters for each iteration. Each item is a dictionary where each key should be the name of a parameter in the quantum program (parameters of the main function), and the value should be the value to set for that parameter.	required

Returns:

Type: ExecutionJob
The execution job.

variational_minimize

variational_minimize(
self: ,
cost_function: Hamiltonian | QmodExpressionCreator,
initial_params: ExecutionParams,
max_iteration: int,
quantile: float = 1.0,
tolerance: float | None = None,
hosted: bool = False,
num_shots: int | None = None,
run_via_classiq: bool | None = None
) -> list[tuple[float, ExecutionParams]]

Variationally minimizes the given cost function using the quantum program. Parameters:

Name	Type	Description	Default
`self`	“		required
`cost_function`	`Hamiltonian \| QmodExpressionCreator`	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.	required
`initial_params`	`ExecutionParams`	The initial parameters for the minimization. Only Models with exactly one execution parameter are supported. 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.	required
`max_iteration`	`int`	The maximum number of iterations for the minimization.	required
`quantile`	`float`	The quantile to use for cost estimation.	1.0
`tolerance`	`float \| None`	The tolerance for the minimization.	None
`hosted`	`bool`	When `True` on an IonQ backend, submit a Classiq execution job that runs the optimization loop on IonQ Hosted Hybrid in the backend. Defaults to `False`.	False
`num_shots`	`int \| None`	Number of shots for this call only; overrides the session default when set.	None
`run_via_classiq`	`bool \| None`	Run via Classiq credentials for this call only; overrides the session default when set.	None

Returns:

Type: list[tuple[float, ExecutionParams]]
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.

minimize

minimize(
self: ,
cost_function: Hamiltonian | QmodExpressionCreator,
initial_params: ExecutionParams,
max_iteration: int,
quantile: float = 1.0,
tolerance: float | None = None,
num_shots: int | None = None,
run_via_classiq: bool | None = None
) -> list[tuple[float, ExecutionParams]]

Deprecated: Use variational_minimize() instead. This name is kept for backward compatibility and will be removed in a future release. Parameters:

Name	Type	Default
`self`	“	required
`cost_function`	`Hamiltonian \| QmodExpressionCreator`	required
`initial_params`	`ExecutionParams`	required
`max_iteration`	`int`	required
`quantile`	`float`	1.0
`tolerance`	`float \| None`	None
`num_shots`	`int \| None`	None
`run_via_classiq`	`bool \| None`	None

submit_variational_minimize

submit_variational_minimize(
self: ,
cost_function: Hamiltonian | QmodExpressionCreator,
initial_params: ExecutionParams,
max_iteration: int,
quantile: float = 1.0,
tolerance: float | None = None,
hosted: bool = False,
num_shots: int | None = None,
run_via_classiq: bool | None = None
) -> ExecutionJob

Name	Type	Description	Default
`self`	“		required
`cost_function`	`Hamiltonian \| QmodExpressionCreator`	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.	required
`initial_params`	`ExecutionParams`	The initial parameters for the minimization. Only Models with exactly one execution parameter are supported. 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.	required
`max_iteration`	`int`	The maximum number of iterations for the minimization.	required
`quantile`	`float`	The quantile to use for cost estimation.	1.0
`tolerance`	`float \| None`	The tolerance for the minimization.	None
`hosted`	`bool`	When `True` on an IonQ backend, submit a Classiq execution job that runs the optimization loop on IonQ Hosted Hybrid in the backend. Defaults to `False`.	False
`num_shots`	`int \| None`	Number of shots for this call only; overrides the session default when set.	None
`run_via_classiq`	`bool \| None`	Run via Classiq credentials for this call only; overrides the session default when set.	None

Returns:

Type: ExecutionJob
The execution job. When hosted=True on an IonQ backend, the backend
worker submits and polls IonQ Hosted Hybrid while this job tracks
progress through the standard Classiq execution API.

submit_minimize

submit_minimize(
self: ,
cost_function: Hamiltonian | QmodExpressionCreator,
initial_params: ExecutionParams,
max_iteration: int,
quantile: float = 1.0,
tolerance: float | None = None,
num_shots: int | None = None,
run_via_classiq: bool | None = None
) -> ExecutionJob

Deprecated: Use submit_variational_minimize() instead. This name is kept for backward compatibility and will be removed in a future release. Parameters:

Name	Type	Default
`self`	“	required
`cost_function`	`Hamiltonian \| QmodExpressionCreator`	required
`initial_params`	`ExecutionParams`	required
`max_iteration`	`int`	required
`quantile`	`float`	1.0
`tolerance`	`float \| None`	None
`num_shots`	`int \| None`	None
`run_via_classiq`	`bool \| None`	None

estimate_cost

estimate_cost(
self: ,
cost_func: Callable[[ParsedState], float],
parameters: ExecutionParams | None = None,
quantile: float = 1.0,
num_shots: int | None = None,
run_via_classiq: bool | None = None
) -> float

Estimates circuit cost using a classical cost function. Parameters:

Name	Type	Description	Default
`self`	“		required
`cost_func`	`Callable[[ParsedState], float]`	classical circuit sample cost function	required
`parameters`	`ExecutionParams \| None`	execution parameters sent to ‘sample’	None
`quantile`	`float`	drop cost values outside the specified quantile	1.0
`num_shots`	`int \| None`	Number of shots for this call only; overrides the session default when set.	None
`run_via_classiq`	`bool \| None`	Run via Classiq credentials for this call only; overrides the session default when set.	None

Returns:

Type: float
cost estimation

set_measured_state_filter

set_measured_state_filter(
self: ,
output_name: str,
condition: Callable
) -> None

When simulating on a statevector simulator, emulate the behavior of postprocessing by discarding amplitudes for which their states are “undesirable”. Parameters:

Name	Type	Description	Default
`self`	“		required
`output_name`	`str`	The name of the register to filter	required
`condition`	`Callable`	Filter out values of the statevector for which this callable is False	required

ExecutionPreferences

Name	Type	Description
`include_zero_amplitude_outputs`	`bool`
`amplitude_threshold`	`float`
`noise_properties`	`Optional[NoiseProperties]`	Properties defining the noise in the quantum circuit. Defaults to `None`.
`random_seed`	`int`	The random seed used for the execution. Defaults to a randomly generated seed.
`backend_preferences`	`BackendPreferencesTypes`	Preferences for the backend used to execute the circuit. Defaults to the Classiq Simulator.
`num_shots`	`Optional[pydantic.PositiveInt]`	The number of shots (executions) to be performed.
`transpile_to_hardware`	`TranspilationOption`	Option to transpile the circuit to the hardware’s basis gates before execution. Defaults to `TranspilationOption.DECOMPOSE`.
`job_name`	`Optional[str]`	The name of the job, with a minimum length of 1 character.

CostEstimateResult

Result of sample cost estimation. Attributes:

Name	Type	Description
`cost`	`float`
`currency`	`str`

BackendPreferences

Preferences for the execution of the quantum program. Methods:

Name	Description
batch_preferences
is_nvidia_backend

Attributes:

Name	Type	Description
`hw_provider`	`Provider`
`backend_service_provider`	`str`	Provider company or cloud for the requested backend.
`backend_name`	`str`	Name of the requested backend or target.

batch_preferences

batch_preferences(
cls: ,
backend_names: Iterable[str],
kwargs: Any = 
) -> list[BackendPreferences]

Parameters:

Name	Type	Default
`cls`	“	required
`backend_names`	`Iterable[str]`	required
`kwargs`	`Any`

is_nvidia_backend

is_nvidia_backend(
self:
) -> bool

Parameters:

Name	Type	Description	Default
`self`	“		required
Members:

Name	Description
`program_id_scope`	Within the scope, HTTP spans emitted by Client.request stamp `classiq.program.id`.
`ExecutionJobResults`	Results from `ExecutionJob.result()`: list-like with job-level metadata.
`SubmittedCircuit`	A quantum circuit that was submitted to the provider.
`ExecutionJobFilters`	Filter parameters for querying execution jobs.
`get_execution_jobs`	Query execution jobs.
`get_execution_actions`	Query execution jobs with optional filters.

program_id_scope

program_id_scope(
program_id: str | None
) -> Generator[None, None, None]

Within the scope, HTTP spans emitted by Client.request stamp classiq.program.id. None = no-op, leaves any outer scope intact. Parameters:

Name	Type	Description	Default
`program_id`	`str \| None`		required

ExecutionJobResults

Results from ExecutionJob.result(): list-like with job-level metadata. Attributes:

Name	Type	Description
`hardware_execution_duration_ms`	`int \| None`

SubmittedCircuit

A quantum circuit that was submitted to the provider. Wraps the circuit in QASM format. Use to_qasm() for the text representation or to_qiskit() for a Qiskit QuantumCircuit (requires qiskit). Methods:

Name	Description
to_qasm	Return the circuit as a QASM string (OpenQASM 2.0 or 3.0).
to_qiskit	Return the circuit as a Qiskit QuantumCircuit.

to_qasm

to_qasm(
self:
) -> str

Return the circuit as a QASM string (OpenQASM 2.0 or 3.0). Parameters:

Name	Type	Description	Default
`self`	“		required

to_qiskit

to_qiskit(
self:
) -> Any

Return the circuit as a Qiskit QuantumCircuit. Requires qiskit. Parameters:

Name	Type	Description	Default
`self`	“		required

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. Methods:

Name	Description
format_filters	Convert filter fields to API kwargs, excluding None values and converting datetimes.

Attributes:

Name	Type	Description
`id`	`str \| None`
`session_id`	`str \| None`
`status`	`JobStatus \| None`
`name`	`str \| None`
`provider`	`str \| None`
`backend`	`str \| None`
`program_id`	`str \| None`
`total_cost_min`	`float \| None`
`total_cost_max`	`float \| None`
`start_time_min`	`datetime \| None`
`start_time_max`	`datetime \| None`
`end_time_min`	`datetime \| None`
`end_time_max`	`datetime \| None`

format_filters

format_filters(
self:
) -> dict[str, Any]

Convert filter fields to API kwargs, excluding None values and converting datetimes. Parameters:

Name	Type	Description	Default
`self`	“		required

get_execution_jobs

get_execution_jobs(
offset: int = 0,
limit: int = 50
) -> list[ExecutionJob]

Query execution jobs. Parameters:

Name	Type	Description	Default
`offset`	`int`	Number of results to skip (default: 0)	0
`limit`	`int`	Maximum number of results to return (default: 50)	50

Returns:

Type: list[ExecutionJob]
List of ExecutionJob objects.

get_execution_actions

get_execution_actions(
offset: int = 0,
limit: int = 50,
filters: ExecutionJobFilters | None = None
) -> pd.DataFrame

Query execution jobs with optional filters. Parameters:

Name	Type	Description	Default
`offset`	`int`	Number of results to skip (default: 0)	0
`limit`	`int`	Maximum number of results to return (default: 50)	50
`filters`	`ExecutionJobFilters \| None`	Optional ExecutionJobFilters object containing filter parameters.	None

Returns:

Type: pd.DataFrame
pandas.DataFrame containing execution job information with columns:
id, name, start_time, end_time, provider, backend_name, status,
num_shots, program_id, error, total_cost, currency_code, runtime_ms
(provider-reported hardware execution duration in milliseconds when available).

BenchmarkClass

Benchmark problem classes supported by the Classiq platform. Attributes:

Name	Type	Description
`ADDER`	`'ADDER'`
`GHZ`	`'GHZ'`
`QFT`	`'QFT'`
`STATE_PREPARATION`	`'STATE_PREPARATION'`

BenchmarkRequest

Request body for run_benchmark. Submits one benchmark class across multiple problem_sizes and backend targets in a single asynchronous session. Attributes:

Name	Type	Description
`benchmark_class`	`BenchmarkClass`
`backends`	`list[BackendExecutionDetails]`
`problem_sizes`	`list[int]`

BackendExecutionDetails

Execution configuration for a benchmark backend target. The object defines how all requested problem_sizes should run on a specific backend. Attributes:

Name	Type	Description
`backend_name`	`str`
`run_via_classiq`	`bool`
`transpilation_option`	`TranspilationOption`
`shots`	`int`
`provider_config`	`dict[str, Any]`

BenchmarkSession

A handle to a submitted benchmark run. This is the same serializable session object the API returns from the submit endpoint (so SDK users and other services share the contract), extended with convenience methods for fetching results from Python. run_benchmark returns the session immediately, without waiting for the executions to finish. Use fetch_results (or fetch_results_async) to retrieve the current status and result of every submitted job; results that reached a final status are cached and not re-fetched. Methods:

Name	Description
fetch_results_async	Fetch the current status and result of every submitted job.
fetch_results	Synchronous wrapper for `fetch_results_async`.
cancel_async	Request cancellation of all incomplete jobs in this benchmark session.
cancel	Synchronous wrapper for `cancel_async`.
to_dataframe	Per-target benchmark table built from the results fetched so far.

fetch_results_async

fetch_results_async(
self: ,
_http_client: httpx.AsyncClient | None = None
) -> list[BackendBenchmarkResult]

Fetch the current status and result of every submitted job. Parameters:

Name	Type	Description	Default
`self`	“		required
`_http_client`	`httpx.AsyncClient \| None`		None

Returns:

Type: list[BackendBenchmarkResult]
Latest per-job results for all successfully submitted targets in this session.

fetch_results

fetch_results(
self: ,
_http_client: httpx.AsyncClient | None = None
) -> list[BackendBenchmarkResult]

Synchronous wrapper for fetch_results_async. Parameters:

Name	Type	Description	Default
`self`	“		required
`_http_client`	`httpx.AsyncClient \| None`		None

Returns:

Type: list[BackendBenchmarkResult]
Latest per-job results for all successfully submitted targets in this session.

cancel_async

cancel_async(
self: ,
_http_client: httpx.AsyncClient | None = None
) -> None

Request cancellation of all incomplete jobs in this benchmark session. Parameters:

Name	Type	Description	Default
`self`	“		required
`_http_client`	`httpx.AsyncClient \| None`		None

cancel

cancel(
self: ,
_http_client: httpx.AsyncClient | None = None
) -> None

Synchronous wrapper for cancel_async. Request cancellation of all incomplete jobs in this benchmark session Parameters:

Name	Type	Description	Default
`self`	“		required
`_http_client`	`httpx.AsyncClient \| None`		None

to_dataframe

to_dataframe(
self:
) -> BenchmarkResponse

Per-target benchmark table built from the results fetched so far. Columns: problem_size, success, error, run_via_classiq, transpilation_option, score, cost, submission_date. Targets whose result has not been fetched (or is still pending) appear as unsuccessful rows with a missing score. Parameters:

Name	Type	Description	Default
`self`	“		required

BenchmarkSessionTarget

A single execution target within a benchmark session. job_id is the internal handle used to fetch this target’s result; it is None when the submission itself failed (submission_error is then populated). execution_job_id is the actual execution job id when it is known. Attributes:

Name	Type	Description
`problem_size`	`int`
`backend_name`	`str`
`run_via_classiq`	`bool`
`transpilation_option`	`TranspilationOption`
`shots`	`int`
`job_id`	`str \| None`
`execution_job_id`	`str \| None`
`submission_error`	`BenchmarkTargetError \| None`

BenchmarkSessionsQueryResults

List response payload for benchmark session queries. Attributes:

Name	Type	Description
`sessions`	`list[BenchmarkSession]`

BenchmarkJobStatus

Status of an asynchronously tracked benchmark job. PENDING means the job is still in progress. COMPLETED means execution and scoring succeeded. FAILED means execution or scoring failed. CANCELLED means the job was cancelled before completion. Attributes:

Name	Type	Description
`PENDING`	`'PENDING'`
`COMPLETED`	`'COMPLETED'`
`FAILED`	`'FAILED'`
`CANCELLED`	`'CANCELLED'`

BackendBenchmarkResult

Asynchronously-fetched result for a previously submitted benchmark job. Attributes:

Name	Type	Description
`job_id`	`str`
`execution_job_id`	`str \| None`
`problem_size`	`int`
`status`	`BenchmarkJobStatus`
`backend_benchmark`	`BackendBenchmark \| None`
`error`	`BenchmarkTargetError \| None`

BackendBenchmarkResponse

Benchmark execution outcome for a single backend target. Attributes:

Name	Type	Description
`success`	`bool`
`backend_benchmark`	`BackendBenchmark \| None`
`error`	`BenchmarkTargetError \| None`

BenchmarkResponse

Tabular benchmark response wrapper returned by BenchmarkSession.to_dataframe. Attributes:

Name	Type	Description
`model_config`
`data`	`pd.DataFrame`

BenchmarkTargetError

Structured error details for a benchmark target failure. Attributes:

Name	Type	Description
`backend_name`	`str \| None`
`message`	`str`

BackendBenchmark

Benchmark score payload for a completed backend run. Attributes:

Name	Type	Description
`benchmark_class`	`BenchmarkClass`
`problem_size`	`int`
`score`	`float`
`metadata`	`BenchmarkMetadata`

BenchmarkMetadata

Metadata captured for a completed benchmark target run. Attributes:

Name	Type	Description
`benchmark_class_version`	`int`
`execution_duration_ms`	`int \| None`
`cost`	`float \| None`
`submission_date`	`str \| None`
`backend_execution_details`	`BackendExecutionDetailsResponse`

BackendExecutionDetailsResponse

Backend execution settings recorded in benchmark result metadata. Attributes:

Name	Type	Description
`backend_name`	`str`
`run_via_classiq`	`bool`
`transpilation_option`	`TranspilationOption`
`shots`	`int`

BenchmarkClassMetadata

Metadata associated with a benchmark class. Attributes:

Name	Type	Description
`limits`	`ProblemSizeLimits \| None`	Optional problem-size bounds for this benchmark class.

ProblemSizeLimits

Optional lower/upper bounds for valid problem sizes of a class. Attributes:

Name	Type	Description
`min`	`int \| None`	Inclusive minimum supported problem size, when defined.
`max`	`int \| None`	Inclusive maximum supported problem size, when defined.

Functions

calculate_state_vector

calculate_state_vector(
qprog: QuantumProgram,
backend: str | None = None,
parameters: ExecutionParams | list[ExecutionParams] | None = None,
filters: dict[str, Any] | None = None,
random_seed: int | None = None,
transpilation_option: TranspilationOption = TranspilationOption.DECOMPOSE,
amplitude_threshold: float = 0.0
) -> DataFrame | list[DataFrame]

Calculate the state vector of a quantum program. This function is only available for Classiq simulators (e.g. "classiq/simulator"). Parameters:

Name	Type	Description	Default
`qprog`	`QuantumProgram`	The quantum program to be executed.	required
`backend`	`str \| None`	The simulator on which to simulate the quantum program. Specified as `"provider/backend_name"`. Use the `get_backend_details` function to see supported backends. Only Classiq simulators are supported.	None
`parameters`	`ExecutionParams \| list[ExecutionParams] \| None`	A dictionary of parameter values, or a list of dictionaries for batch execution. Each key should be the name of a parameter in the quantum program (parameters of the main function), and the value should be the value to set for that parameter.	None
`filters`	`dict[str, Any] \| None`	Only states where the variables match these values will be included in the state vector.	None
`random_seed`	`int \| None`	The random seed for reproducibility.	None
`transpilation_option`	`TranspilationOption`	Advanced configuration for hardware-specific transpilation.	TranspilationOption.DECOMPOSE
`amplitude_threshold`	`float`	If provided, only states whose amplitude magnitude is strictly greater than this value will be included in the result. Defaults to 0 (filters exactly zero-amplitude states).	0.0

Returns:

Type: DataFrame \| list[DataFrame]
A dataframe containing the state vector, or a list of dataframes when
parameters is a list.

observe

observe(
qprog: QuantumProgram,
observable: SparsePauliOp,
backend: str | None = None,
estimate: bool = True,
parameters: ExecutionParams | list[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,
run_via_classiq: bool = False
) -> float | list[float]

Get the expectation value of the observable O with respect to the state \|psi>, which is prepared by the provided quantum program. Parameters:

Name	Type	Description	Default
`qprog`	`QuantumProgram`	The quantum program that generates the state `\|psi>` to be observed.	required
`observable`	`SparsePauliOp`	The observable O, a Hermitian operator defined as a `SparsePauliOp` (sum of Pauli terms).	required
`backend`	`str \| None`	The hardware or simulator on which to run the quantum program. Use `"simulator"` for Classiq’s default simulator, or specify a backend as `"provider/backend_name"`. Use the `get_backend_details` function to see supported devices.	None
`estimate`	`bool`	Whether to estimate the expectation value by repeatedly measuring the circuit `num_shots` times, or calculate the exact expectation value using a simulated statevector. Note that the available options depend on the specified backend. Defaults to `True`.	True
`parameters`	`ExecutionParams \| list[ExecutionParams] \| None`	A dictionary of parameter values, or a list of dictionaries for batch execution. Each key should be the name of a parameter in the quantum program (parameters of the main function), and the value should be the value to set for that parameter.	None
`config`	dict[str, Any] \| ProviderConfig \| None	Provider-specific configuration, such as API keys. For full details, see the SDK reference under Providers.	None
`num_shots`	`int \| None`	The number of measurement shots. Only relevant when `estimate=True`.	None
`random_seed`	`int \| None`	The random seed for reproducibility.	None
`transpilation_option`	`TranspilationOption`	Advanced configuration for hardware-specific transpilation.	TranspilationOption.DECOMPOSE
`run_via_classiq`	`bool`	Run via Classiq’s credentials while using your allocated budget. Defaults to `False`.	False

Returns:

Type: float \| list[float]
The expectation value as a float, or a list of floats when
parameters is a list.

variational_minimize

variational_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,
hosted: bool = False,
config: dict[str, Any] | ProviderConfig | None = None,
random_seed: int | None = None,
transpilation_option: TranspilationOption = TranspilationOption.DECOMPOSE,
run_via_classiq: bool = False
) -> list[tuple[float, ExecutionParams]]

Minimize the given cost function over the parameter values of the provided quantum program. Parameters:

Name	Type	Description	Default
`qprog`	`QuantumProgram`	The parametric quantum program that generates the state (ansatz). Only quantum programs with exactly one execution parameter are supported.	required
`cost_function`	`SparsePauliOp \| QmodExpressionCreator`	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.	required
`initial_params`	`ExecutionParams`	The initial parameter values 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.	required
`max_iteration`	`int`	The maximum number of iterations for the minimization.	required
`backend`	`str \| None`	The hardware or simulator on which to run the quantum programs. Use `"simulator"` for Classiq’s default simulator, or specify a backend as `"provider/backend_name"`. Use the `get_backend_details` function to see supported devices.	None
`quantile`	`float`	The quantile to use for cost estimation.	1.0
`tolerance`	`float \| None`	The tolerance for the minimization.	None
`hosted`	`bool`	When `True` and the configured backend is IonQ, delegate the optimization loop to IonQ’s Hosted Hybrid Service instead of running it locally. Defaults to `False`.	False
`config`	dict[str, Any] \| ProviderConfig \| None	Provider-specific configuration, such as API keys. For full details, see the SDK reference under Providers.	None
`random_seed`	`int \| None`	The random seed for reproducibility.	None
`transpilation_option`	`TranspilationOption`	Advanced configuration for hardware-specific transpilation.	TranspilationOption.DECOMPOSE
`run_via_classiq`	`bool`	Run via Classiq’s credentials while using your allocated budget. Defaults to `False`.	False

Returns:

Type: list[tuple[float, ExecutionParams]]
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.

execute

execute(
quantum_program: QuantumProgram
) -> ExecutionJob

Execute a quantum program. The preferences for execution are set on the quantum program using the method set_execution_preferences. Parameters:

Name	Type	Description	Default
`quantum_program`	`QuantumProgram`	The quantum program to execute. This is the result of the synthesize method.	required

Returns:

Type: ExecutionJob
The result of the execution.

estimate_sample_cost

estimate_sample_cost(
quantum_program: QuantumProgram,
execution_options: ExecutionPreferences | str,
config: dict[str, Any] | None = None,
num_shots: int | None = None,
transpilation_option: TranspilationOption = TranspilationOption.DECOMPOSE
) -> CostEstimateResult

Estimate the cost for sampling a quantum program. execution_options may be a full ExecutionPreferences object, or the same backend specifier string used by sample() (for example "braket/SV1" or "azure/ionq.simulator"). When it is a string, optional config, num_shots, and transpilation_option are applied like the sample() helpers. String backends are always resolved with run via Classiq when the provider supports it (no user cloud credentials required for cost estimation). Parameters:

Name	Type	Description	Default
`quantum_program`	`QuantumProgram`	The quantum program (output of synthesize).	required
`execution_options`	ExecutionPreferences \| str	Execution preferences or a backend specifier string.	required
`config`	`dict[str, Any] \| None`	Passed only for string backends (non-credential options, e.g. Azure `location`).	None
`num_shots`	`int \| None`	Shots when using a string backend; ignored when using `ExecutionPreferences`.	None
`transpilation_option`	`TranspilationOption`	Transpilation when using a string backend; ignored otherwise.	TranspilationOption.DECOMPOSE

Returns:

Type: CostEstimateResult
CostEstimateResult with cost and currency.

estimate_sample_batch_cost

estimate_sample_batch_cost(
quantum_program: QuantumProgram,
execution_backend: BackendPreferencesTypes | str,
transpilation_level: TranspilationOption = TranspilationOption.DECOMPOSE,
shots: int = 1000,
params: list[dict] | None = None,
config: dict[str, Any] | None = None
) -> CostEstimateResult

Estimate the cost for batch sampling a quantum program. execution_backend may be backend preferences or a sample()-style specifier string. With a string backend, pass non-credential options in config; resolution uses run via Classiq whenever the provider supports it (same rule as estimate_sample_cost). Parameters:

Name	Type	Description	Default
`quantum_program`	`QuantumProgram`	The quantum program (output of synthesize).	required
`execution_backend`	`BackendPreferencesTypes \| str`	Backend preferences or specifier string.	required
`transpilation_level`	`TranspilationOption`	Transpilation option for the circuit.	TranspilationOption.DECOMPOSE
`shots`	`int`	Number of shots per sample.	1000
`params`	`list[dict] \| None`	Optional list of parameter sets for batch. If None, single sample.	None
`config`	`dict[str, Any] \| None`	Non-credential provider options when `execution_backend` is a string.	None

Returns:

Type: CostEstimateResult
CostEstimateResult with cost and currency.

assign_parameters

assign_parameters(
quantum_program: QuantumProgram,
parameters: ExecutionParams
) -> QuantumProgram

Assign parameters to a parametric quantum program. Parameters:

Name	Type	Description	Default
`quantum_program`	`QuantumProgram`	The quantum program to be assigned. This is the result of the synthesize method.	required
`parameters`	`ExecutionParams`	The parameter assignments.	required

Returns:

Type: QuantumProgram
The quantum program after assigning parameters.

transpile

transpile(
quantum_program: QuantumProgram,
preferences: Preferences | None = None
) -> QuantumProgram

Transpiles a quantum program. Parameters:

Name	Type	Description	Default
`quantum_program`	`QuantumProgram`	The quantum program to transpile. This is the result of the synthesize method.	required
`preferences`	`Preferences \| None`	The transpilation preferences.	None

Returns:

Type: QuantumProgram
The result of the transpilation (Optional).

get_budget

get_budget(
provider: ProviderVendor | None = None
) -> UserBudgets

Retrieve the user’s budget information for quantum computing resources. Parameters:

Name	Type	Description	Default
`provider`	`ProviderVendor \| None`	(Optional) The quantum backend provider to filter budgets by. If not provided, budgets for all providers will be returned.	None

Returns:

Type: UserBudgets
An object containing the user’s budget information.

set_budget_limit

set_budget_limit(
provider: ProviderVendor,
limit: float
) -> UserBudgets

Set a budget limit for a specific quantum backend provider. Parameters:

Name	Type	Description	Default
`provider`	`ProviderVendor`	The quantum backend provider for which to set the budget limit.	required
`limit`	`float`	The budget limit to set. Must be greater than zero and not exceed the available budget.	required

Returns:

Type: UserBudgets
An object containing the updated budget information.

clear_budget_limit

clear_budget_limit(
provider: ProviderVendor
) -> UserBudgets

Clear the budget limit for a specific quantum backend provider. Parameters:

Name	Type	Description	Default
`provider`	`ProviderVendor`	The quantum backend provider for which to clear the budget limit.	required

Returns:

Type: UserBudgets
An object containing the updated budget information.

run_benchmark

run_benchmark(
request: BenchmarkRequest
) -> BenchmarkSession

Submit a benchmark class across problem sizes and execution targets. Every backend in request.backends is paired with every value in request.problem_sizes and submitted up front. The call returns immediately with a BenchmarkSession and does not wait for executions to complete. Use BenchmarkSession.fetch_results or BenchmarkSession.fetch_results_async to poll statuses and fetch results. Targets that fail during submission are still included in the session with submission_error populated and no job_id. Parameters:

Name	Type	Description	Default
`request`	BenchmarkRequest	Benchmark submission settings including benchmark class, requested problem sizes, and per-target backend execution configuration.	required

Returns:

Type: BenchmarkSession
A BenchmarkSession containing session metadata, per-target submission handles, and any fetched results.

get_benchmark_sessions

get_benchmark_sessions() -> list[BenchmarkSession]

Return all benchmark sessions stored for the user. Returns:

Type: list[BenchmarkSession]
Benchmark sessions for the current user, including session ids and any
results fetched so far. Use this after reconnecting to resume in-flight runs.

get_benchmark_classes

get_benchmark_classes() -> dict[BenchmarkClass, BenchmarkClassMetadata]

Return benchmark classes supported by the platform. Returns:

Type: dict[BenchmarkClass, BenchmarkClassMetadata]
Mapping from each supported BenchmarkClass to BenchmarkClassMetadata, including any known problem-size limits.

⌘I

​ProviderConfig

​ExecutionPreferences

​TranspilationOption

​ExecutionSession

​close

​get_session_id

​update_execution_preferences

​sample

​submit_sample

​calculate_state_vector

​submit_calculate_state_vector

​batch_sample

​submit_batch_sample

​observe

​submit_observe

​estimate

​submit_estimate

​batch_estimate

​submit_batch_estimate

​variational_minimize

​minimize

​submit_variational_minimize

​submit_minimize

​estimate_cost

​set_measured_state_filter

​sample

​BraketConfig

​IBMConfig

​IonQConfig

​AzureConfig

​AQTConfig

​AliceBobConfig

​ProviderConfig

​ExecutionSession

​close

​get_session_id

​update_execution_preferences

​sample

​submit_sample

​calculate_state_vector

​submit_calculate_state_vector

​batch_sample

​submit_batch_sample

​observe

​submit_observe

​estimate

​submit_estimate

​batch_estimate

​submit_batch_estimate

​variational_minimize

​minimize

​submit_variational_minimize

​submit_minimize

​estimate_cost

​set_measured_state_filter

​ExecutionPreferences

​CostEstimateResult

​BackendPreferences

​batch_preferences

​is_nvidia_backend

​program_id_scope

​ExecutionJobResults

​SubmittedCircuit

​to_qasm

​to_qiskit

​ExecutionJobFilters

​format_filters

​get_execution_jobs

​get_execution_actions

​BenchmarkClass

​BenchmarkRequest

​BackendExecutionDetails

​BenchmarkSession

​fetch_results_async

​fetch_results

​cancel_async

​cancel

​to_dataframe

​BenchmarkSessionTarget

​BenchmarkSessionsQueryResults

ProviderConfig

ExecutionPreferences

TranspilationOption

ExecutionSession

close

get_session_id

update_execution_preferences

sample

submit_sample

calculate_state_vector

submit_calculate_state_vector

batch_sample

submit_batch_sample

observe

submit_observe

estimate

submit_estimate

batch_estimate

submit_batch_estimate

variational_minimize

minimize

submit_variational_minimize

submit_minimize

estimate_cost

set_measured_state_filter

sample

BraketConfig

IBMConfig

IonQConfig

AzureConfig

AQTConfig

AliceBobConfig

ProviderConfig

ExecutionSession

close

get_session_id

update_execution_preferences

sample

submit_sample

calculate_state_vector

submit_calculate_state_vector

batch_sample

submit_batch_sample

observe

submit_observe

estimate

submit_estimate

batch_estimate

submit_batch_estimate

variational_minimize

minimize

submit_variational_minimize

submit_minimize

estimate_cost

set_measured_state_filter

ExecutionPreferences

CostEstimateResult

BackendPreferences

batch_preferences

is_nvidia_backend

program_id_scope

ExecutionJobResults

SubmittedCircuit

to_qasm

to_qiskit

ExecutionJobFilters

format_filters

get_execution_jobs

get_execution_actions

BenchmarkClass

BenchmarkRequest

BackendExecutionDetails

BenchmarkSession

fetch_results_async

fetch_results

cancel_async

cancel

to_dataframe

BenchmarkSessionTarget

BenchmarkSessionsQueryResults