Execution - Classiq Docs

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.

ExecutionSession

A session for executing a quantum program. 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.
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.
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.
minimize	Minimizes the given cost function using the quantum program.
submit_minimize	Initiates an execution job with the `minimize` primitive.
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
`quantum_program`	`QuantumProgram`	The quantum program to execute.
`execution_preferences`	`Optional[ExecutionPreferences]`	Execution preferences for the Quantum Program.

program

program: QuantumProgram = quantum_program

close

close(
self:
) -> None

Close the session and clean up its resources. 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 | None = None
) -> ExecutionDetails

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

Name	Type	Description	Default
`self`	“		required
`parameters`	`ExecutionParams \| None`	The values to set for the parameters of the quantum program when sampling. 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

Returns:

Type: ExecutionDetails
The result of the sampling.

submit_sample

submit_sample(
self: ,
parameters: ExecutionParams | 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 \| None`	The values to set for the parameters of the quantum program when sampling. 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

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. 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. This is a non-blocking version of batch_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`	`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.

estimate

estimate(
self: ,
hamiltonian: Hamiltonian,
parameters: ExecutionParams | None = None
) -> 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 \| None`	The values to set for the parameters of the quantum program when estimating. 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

Returns:

Type: EstimationResult
The result of the estimation.

submit_estimate

submit_estimate(
self: ,
hamiltonian: Hamiltonian,
parameters: ExecutionParams | None = None,
_check_deprecation: bool = True
) -> ExecutionJob

Initiates an execution job with the estimate primitive. This is a non-blocking version of estimate: 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 \| None`	The values to set for the parameters of the quantum program when estimating. 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
`_check_deprecation`	`bool`		True

Returns:

Type: ExecutionJob
The execution job.

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. 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],
_check_deprecation: bool = True
) -> ExecutionJob

Initiates an execution job with the batch_estimate primitive. This is a non-blocking version of batch_estimate: 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`	`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
`_check_deprecation`	`bool`		True

Returns:

Type: ExecutionJob
The execution job.

minimize

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

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

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.

submit_minimize

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

Initiates an execution job with the minimize primitive. This is a non-blocking version of minimize: 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
`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
`_check_deprecation`	`bool`		True

Returns:

Type: ExecutionJob
The execution job.

estimate_cost

estimate_cost(
self: ,
cost_func: Callable[[ParsedState], float],
parameters: ExecutionParams | None = None,
quantile: float = 1.0
) -> 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

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

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
`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.

noise_properties

noise_properties: NoiseProperties | None = pydantic.Field(default=None, description='Properties of the noise in the circuit')

random_seed

random_seed: int = pydantic.Field(default_factory=create_random_seed, description='The random seed used for the execution')

backend_preferences

backend_preferences: BackendPreferencesTypes = backend_preferences_field(backend_name=(ClassiqSimulatorBackendNames.SIMULATOR))

num_shots

num_shots: pydantic.PositiveInt | None = pydantic.Field(default=None)

transpile_to_hardware

transpile_to_hardware: TranspilationOption = pydantic.Field(default=(TranspilationOption.DECOMPOSE), description='Transpile the circuit to the hardware basis gates before execution', title='Transpilation Option')

job_name

job_name: str | None = pydantic.Field(min_length=1, description='The job name', default=None)

include_zero_amplitude_outputs

include_zero_amplitude_outputs: bool = pydantic.Field(default=False, description='In state vector simulation, whether to include zero-amplitude states in the result')

BackendPreferences

Preferences for the execution of the quantum program. Methods:

Name	Description
batch_preferences
is_nvidia_backend

Attributes:

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

backend_service_provider

backend_service_provider: ProviderVendor = pydantic.Field(..., description='Provider company or cloud for the requested backend.')

backend_name

backend_name: str = pydantic.Field(..., description='Name of the requested backend or target.')

hw_provider

hw_provider: Provider Members:

Name	Description
`ExecutionJobFilters`	Filter parameters for querying execution jobs.
`get_execution_jobs`	Query execution jobs.
`get_execution_actions`	Query execution jobs with optional filters.

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.

id

id: str | None = None

session_id

session_id: str | None = None

status

status: JobStatus | None = None

name

name: str | None = None

provider

provider: str | None = None

backend

backend: str | None = None

program_id

program_id: str | None = None

total_cost_min

total_cost_min: float | None = None

total_cost_max

total_cost_max: float | None = None

start_time_min

start_time_min: datetime | None = None

start_time_max

start_time_max: datetime | None = None

end_time_min

end_time_min: datetime | None = None

end_time_max

end_time_max: datetime | None = 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, cost.

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.

Providers

Applications

Qmod

​execute

​ExecutionSession

​program

​close

​update_execution_preferences

​sample

​submit_sample

​batch_sample

​submit_batch_sample

​estimate

​submit_estimate

​batch_estimate

​submit_batch_estimate

​minimize

​submit_minimize

​estimate_cost

​set_measured_state_filter

​ExecutionPreferences

​noise_properties

​random_seed

​backend_preferences

​num_shots

​transpile_to_hardware

​job_name

​include_zero_amplitude_outputs

​BackendPreferences

​backend_service_provider

​backend_name

​hw_provider

​ExecutionJobFilters

​id

​session_id

​status

​name

​provider

​backend

​program_id

​total_cost_min

​total_cost_max

​start_time_min

​start_time_max

​end_time_min

​end_time_max

​format_filters

​get_execution_jobs

​get_execution_actions

​assign_parameters

​transpile

​get_budget

​set_budget_limit

​clear_budget_limit

execute

ExecutionSession

program

close

update_execution_preferences

sample

submit_sample

batch_sample

submit_batch_sample

estimate

submit_estimate

batch_estimate

submit_batch_estimate

minimize

submit_minimize

estimate_cost

set_measured_state_filter

ExecutionPreferences

noise_properties

random_seed

backend_preferences

num_shots

transpile_to_hardware

job_name

include_zero_amplitude_outputs

BackendPreferences

backend_service_provider

backend_name

hw_provider

ExecutionJobFilters

id

session_id

status

name

provider

backend

program_id

total_cost_min

total_cost_max

start_time_min

start_time_max

end_time_min

end_time_max

format_filters

get_execution_jobs

get_execution_actions

assign_parameters

transpile

get_budget

set_budget_limit

clear_budget_limit