Execution

execute

execute(
    quantum_program: SerializedQuantumProgram,
) -> 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`	`SerializedQuantumProgram`	The quantum program to execute. This is the result of the synthesize method.	required

Returns:

Name	Type	Description
`ExecutionJob`	`ExecutionJob`	The result of the execution.

For examples please see Execution Documentation

ExecutionSession

ExecutionSession(
    quantum_program: Program,
    execution_preferences: Optional[
        ExecutionPreferences
    ] = None,
)

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.

Attributes:

Name	Type	Description
`quantum_program`	`Union[SerializedQuantumProgram, QuantumProgram]`	The quantum program to execute.
`execution_preferences`	`Optional[ExecutionPreferences]`	Execution preferences for the Quantum Program.

Methods:

Name	Description
`batch_estimate`	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.
`batch_sample`	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.
`close`	Close the session and clean up its resources.
`estimate`	Estimates the expectation value of the given Hamiltonian using the quantum program.
`estimate_cost`	Estimates circuit cost using a classical cost function.
`sample`	Samples the quantum program with the given parameters, if any.
`set_measured_state_filter`	EXPERIMENTAL
`submit_batch_estimate`	Initiates an execution job with the `batch_estimate` primitive.
`submit_batch_sample`	Initiates an execution job with the `batch_sample` primitive.
`submit_estimate`	Initiates an execution job with the `estimate` primitive.
`submit_sample`	Initiates an execution job with the `sample` primitive.
`update_execution_preferences`	Update the execution preferences for the session.

Attributes:

Name	Type	Description
`program`	`QuantumProgram`

program

program: QuantumProgram = _deserialize_program(
    quantum_program
)

batch_estimate

batch_estimate(
    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
`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	Description
`list[EstimationResult]`	List[EstimationResult]: The results of all the estimation iterations.

batch_sample

batch_sample(
    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
`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	Description
`list[ExecutionDetails]`	List[ExecutionDetails]: The results of all the sampling iterations.

close

close() -> None

Close the session and clean up its resources.

estimate

estimate(
    hamiltonian: Hamiltonian,
    parameters: Optional[ExecutionParams] = None,
) -> EstimationResult

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

Parameters:

Name	Type	Description	Default
`hamiltonian`	`Hamiltonian`	The Hamiltonian to estimate the expectation value of.	required
`parameters`	`Optional[ExecutionParams]`	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:

Name	Type	Description
`EstimationResult`	`EstimationResult`	The result of the estimation.

estimate_cost

estimate_cost(
    cost_func: Callable[[ParsedState], float],
    parameters: Optional[ExecutionParams] = None,
    quantile: float = 1.0,
) -> float

Estimates circuit cost using a classical cost function.

Parameters:

Name	Type	Description	Default
`cost_func`	`Callable[[ParsedState], float]`	classical circuit sample cost function	required
`parameters`	`Optional[ExecutionParams]`	execution parameters sent to 'sample'	`None`
`quantile`	`float`	drop cost values outside the specified quantile	`1.0`

Returns:

Type	Description
`float`	cost estimation

sample

sample(
    parameters: Optional[ExecutionParams] = None,
) -> ExecutionDetails

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

Parameters:

Name	Type	Description	Default
`parameters`	`Optional[ExecutionParams]`	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	Description
`ExecutionDetails`	The result of the sampling.

set_measured_state_filter

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

EXPERIMENTAL

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

submit_batch_estimate

submit_batch_estimate(
    hamiltonian: Hamiltonian,
    parameters: list[ExecutionParams],
) -> 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
`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	Description
`ExecutionJob`	The execution job.

submit_batch_sample

submit_batch_sample(
    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
`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	Description
`ExecutionJob`	The execution job.

submit_estimate

submit_estimate(
    hamiltonian: Hamiltonian,
    parameters: Optional[ExecutionParams] = None,
) -> 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
`hamiltonian`	`Hamiltonian`	The Hamiltonian to estimate the expectation value of.	required
`parameters`	`Optional[ExecutionParams]`	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	Description
`ExecutionJob`	The execution job.

submit_sample

submit_sample(
    parameters: Optional[ExecutionParams] = 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
`parameters`	`Optional[ExecutionParams]`	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	Description
`ExecutionJob`	The execution job.

update_execution_preferences

update_execution_preferences(
    execution_preferences: Optional[ExecutionPreferences],
) -> None

Update the execution preferences for the session.

Parameters:

Name	Type	Description	Default
`execution_preferences`	`Optional[ExecutionPreferences]`	The execution preferences to update.	required

Returns:

Type	Description
`None`	None

ExecutionPreferences

Bases: BaseModel

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

Attributes:

Name	Type	Description
`backend_preferences`	`BackendPreferencesTypes`
`job_name`	`Optional[str]`
`noise_properties`	`Optional[NoiseProperties]`
`num_shots`	`Optional[PositiveInt]`
`random_seed`	`int`
`transpile_to_hardware`	`TranspilationOption`

backend_preferences

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

job_name

job_name: Optional[str] = Field(
    min_length=1, description="The job name", default=None
)

noise_properties

noise_properties: Optional[NoiseProperties] = Field(
    default=None,
    description="Properties of the noise in the circuit",
)

num_shots

num_shots: Optional[PositiveInt] = Field(default=None)

random_seed

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

transpile_to_hardware

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

BackendPreferences

Bases: BaseModel

Preferences for the execution of the quantum program.

For more details, refer to: BackendPreferences

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.

Methods:

Name	Description
`batch_preferences`
`is_nvidia_backend`

Attributes:

Name	Type	Description
`backend_name`	`str`
`backend_service_provider`	`ProviderVendor`
`hw_provider`	`Provider`

backend_name

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

backend_service_provider

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

hw_provider

hw_provider: Provider

batch_preferences

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

is_nvidia_backend

is_nvidia_backend() -> bool

jobs

Classes:

Name	Description
`ClassiqExecutionResultError`
`ExecutionJob`

Functions:

Name	Description
`get_execution_jobs_async`

Attributes:

Name	Type	Description
`get_execution_jobs`

get_execution_jobs

get_execution_jobs = syncify_function(
    get_execution_jobs_async
)

ClassiqExecutionResultError

ClassiqExecutionResultError(primitive: str)

Bases: ClassiqError

ExecutionJob

ExecutionJob(details: _JobDetails)

Methods:

Name	Description
`cancel_async`	Cancels the execution job. This implies the cancellation of any ongoing jobs
`cost`
`from_id`
`from_id_async`
`get_batch_estimate_result`	Returns the job's result as a single batch_estimate result after validation. If the result is not yet available, waits for it.
`get_batch_sample_result`	Returns the job's result as a single batch_sample result after validation. If the result is not yet available, waits for it.
`get_estimate_result`	Returns the job's result as a single estimate result after validation. If the result is not yet available, waits for it.
`get_sample_result`	Returns the job's result as a single sample result after validation. If the result is not yet available, waits for it.
`open_in_ide`
`poll_async`
`rename_async`
`result_async`
`result_value`

Attributes:

Name	Type	Description
`backend_name`	`Optional[str]`
`cancel`
`end_time`	`Optional[datetime]`
`error`	`Optional[str]`
`id`	`str`
`ide_url`	`str`
`name`	`Optional[str]`
`num_shots`	`Optional[int]`
`poll`
`program_id`	`Optional[str]`
`provider`	`Optional[str]`
`rename`
`result`
`start_time`	`datetime`
`status`	`JobStatus`

backend_name

backend_name: Optional[str]

cancel

cancel = syncify_function(cancel_async)

end_time

end_time: Optional[datetime]

error

error: Optional[str]

id

id: str

ide_url

ide_url: str

name

name: Optional[str]

num_shots

num_shots: Optional[int]

poll

poll = syncify_function(poll_async)

program_id

program_id: Optional[str]

provider

provider: Optional[str]

rename

rename = syncify_function(rename_async)

result

result = syncify_function(result_async)

start_time

start_time: datetime

status

status: JobStatus

cancel_async

cancel_async(
    _http_client: Optional[AsyncClient] = None,
) -> None

Cancels the execution job. This implies the cancellation of any ongoing jobs sent to the provider during this execution job.

The function returns without waiting to the actual cancellation. It is possible to continue polling the job in order to ensure its cancellation, which might not be immediate.

cost

cost(*, verbose: bool = False) -> Union[str, JobCost]

from_id

from_id(
    id: str, _http_client: Optional[AsyncClient] = None
) -> ExecutionJob

from_id_async

from_id_async(
    id: str, _http_client: Optional[AsyncClient] = None
) -> ExecutionJob

get_batch_estimate_result

get_batch_estimate_result(
    _http_client: Optional[AsyncClient] = None,
) -> list[EstimationResult]

Returns the job's result as a single batch_estimate result after validation. If the result is not yet available, waits for it.

Returns:

Type	Description
`list[EstimationResult]`	The batch_estimate result of the execution job.

Raises:

Type	Description
`ClassiqExecutionResultError`	In case the result does not contain a single batch_estimate result.
`ClassiqAPIError`	In case the job has failed.

get_batch_sample_result

get_batch_sample_result(
    _http_client: Optional[AsyncClient] = None,
) -> list[ExecutionDetails]

Returns the job's result as a single batch_sample result after validation. If the result is not yet available, waits for it.

Returns:

Type	Description
`list[ExecutionDetails]`	The batch_sample result of the execution job.

Raises:

Type	Description
`ClassiqExecutionResultError`	In case the result does not contain a single batch_sample result.
`ClassiqAPIError`	In case the job has failed.

get_estimate_result

get_estimate_result(
    _http_client: Optional[AsyncClient] = None,
) -> EstimationResult

Returns the job's result as a single estimate result after validation. If the result is not yet available, waits for it.

Returns:

Type	Description
`EstimationResult`	The estimate result of the execution job.

Raises:

Type	Description
`ClassiqExecutionResultError`	In case the result does not contain a single estimate result.
`ClassiqAPIError`	In case the job has failed.

get_sample_result

get_sample_result(
    _http_client: Optional[AsyncClient] = None,
) -> ExecutionDetails

Returns the job's result as a single sample result after validation. If the result is not yet available, waits for it.

Returns:

Type	Description
`ExecutionDetails`	The sample result of the execution job.

Raises:

Type	Description
`ClassiqExecutionResultError`	In case the result does not contain a single sample result.
`ClassiqAPIError`	In case the job has failed.

open_in_ide

open_in_ide() -> None

poll_async

poll_async(
    timeout_sec: Optional[float] = None,
    _http_client: Optional[AsyncClient] = None,
) -> None

rename_async

rename_async(
    name: str, _http_client: Optional[AsyncClient] = None
) -> None

result_async

result_async(
    timeout_sec: Optional[float] = None,
    _http_client: Optional[AsyncClient] = None,
) -> ResultsCollection

result_value

result_value(*args: Any, **kwargs: Any) -> Any

get_execution_jobs_async

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