Reference

cancel_job

cancel_job(job_id: str) -> None

Cancel a job. Please note that the cancel_job API will prevent QESEM from sending new circuits to the QPU. Circuits which are already running on the QPU cannot be cancelled.

Parameters:

Name	Type	Description	Default
job_id	str	The job_id to cancel	required

create_job

create_job(
    *,
    circuit: QuantumCircuit,
    observables: Observable
    | Sequence[Observable]
    | None = None,
    observables_metadata: Sequence[ObservableMetadata]
    | None = None,
    parameters: Mapping[str | Parameter, Sequence[float]]
    | None = None,
    precision: float | None = None,
    backend: str,
    empirical_time_estimation: bool = False,
    description: str = "",
    circuit_options: CircuitOptions | None = None,
    precision_mode: PrecisionMode | None = None,
    shots: int | None = None
) -> JobDetails

Submit a new job to the API Gateway.

Parameters:

Name	Type	Description	Default
circuit	QuantumCircuit	The circuit to run.	required
observables	Observable | Sequence[Observable] | None	The observables to measure.	None
precision	float | None	The target absolute precision to achieve for each input observable.	None
backend	str	The backend (QPU) to run on. (e.g., ibm_fez)	required
parameters	Mapping[str | Parameter, Sequence[float]] | None	Used when a parameterized circuit is provided. The parameters to run the circuit with (mapping from parameter to sequence of values, all parameters must have the same number of values) If given, the number of observables must be equal to the number of values.	None
empirical_time_estimation	bool	Whether to use empirical time estimation.	False
description	str	A description for the job.	''
circuit_options	CircuitOptions | None	Additional options for a circuit.	None
precision_mode	PrecisionMode | None	The precision mode to use. Can only be used when parameters are set.	None
shots	int | None	The number of shots to execute. Only used when error_suppression_only=True.	None

Returns:

Type	Description
JobDetails	The job's details including its ID.

get_job

get_job(
    job_id: str,
    include_circuits: bool = False,
    include_results: bool = False,
) -> JobDetails

Get a job's details.

Parameters:

Name	Type	Description	Default
job_id	str	The ID of the job.	required
include_circuits	bool	Whether to include the input circuit.	False
include_results	bool	Whether to include the result of the job (if it is ready).	False

Returns:

Type	Description
JobDetails	Details about the job, with the data from the flags.

get_jobs

get_jobs(
    jobs_ids: list[str],
    include_circuits: bool = False,
    include_results: bool = False,
) -> list[JobDetails]

Get multiple jobs' details.

Parameters:

Name	Type	Description	Default
jobs_ids	list[str]	The IDs of the jobs.	required
include_circuits	bool	Whether to include the input circuits.	False
include_results	bool	Whether to include the results of the jobs (if they are ready).	False

Returns:

Type	Description
list[JobDetails]	Details about the jobs, with the data from the flags.

list_jobs

list_jobs(
    skip: int = 0, limit: int = 50
) -> list[JobDetails]

Paginate jobs.

Parameters:

Name	Type	Description	Default
skip	int	How many jobs to skip.	0
limit	int	Maximum amount of jobs to return.	50

Returns:

Type	Description
list[JobDetails]	The list of requested jobs.

register_qpu_token

register_qpu_token(token: str) -> None

registers the QPU vendor token.

Parameters:

Name	Type	Description	Default
token	str	The vendor token.	required

set_provider

set_provider(provider: IBMQProvider) -> None

Set the provider of the client. (e.g. IBMQProvider)

start_job

start_job(
    job_id: str,
    max_qpu_time: timedelta,
    options: JobOptions | None = None,
    force_start: bool = False,
) -> None

Start running an estimation job.

Parameters:

Name	Type	Description	Default
job_id	str	The ID of the job.	required
max_qpu_time	timedelta	The maximum allowed QPU time.	required
options	JobOptions | None	Additional options for the job (see JobOptions).	None
force_start	bool	If True, the job will automatically start once the estimation completes.	False

unregister_qpu_token

unregister_qpu_token() -> None

Unregisters a vendor token for an account.

wait_for_job_complete

wait_for_job_complete(
    job_id: str,
    *,
    interval: timedelta = STATUS_POLLING_INTERVAL,
    max_poll_time: timedelta | None = None
) -> JobDetails

Wait until the job finishes, and get the results. While the job is running, this function also prints the job's current step and intermediate results

Parameters:

Name	Type	Description	Default
job_id	str	The ID of the job.	required
interval	timedelta	The interval between two polls. Defaults to 10 seconds.	STATUS_POLLING_INTERVAL
max_poll_time	timedelta | None	Max time until a timeout. If left empty, the method will return only when the job finishes.	None

Returns:

Type	Description
JobDetails	The details of the job, including its results.

wait_for_time_estimation

wait_for_time_estimation(
    job_id: str,
    *,
    interval: timedelta = STATUS_POLLING_INTERVAL,
    max_poll_time: timedelta | None = None
) -> timedelta | None

Wait until a job reaches the time-estimation part, and get the estimation.

Parameters:

Name	Type	Description	Default
job_id	str	The ID of the job.	required
interval	timedelta	The interval between two polls. Defaults to 10 seconds.	STATUS_POLLING_INTERVAL
max_poll_time	timedelta | None	Max time until a timeout. If left empty, the method will return only when the job finishes.	None

Returns:

Type	Description
timedelta | None	The time estimation of the job.

Qedma Public API

Circuit

Bases: ParameterizedCircuit

A quantum circuit configuration including the circuit itself, observables to measure, and execution parameters.

observables instance-attribute

observables: tuple[Observable, ...]

Tuple of observables to be measured. Each observable represents a measurement configuration.

observables_metadata class-attribute instance-attribute

observables_metadata: tuple[
    ObservableMetadata, ...
] | None = None

Tuple of metadata for the observables. Each metadata corresponds to the observable at the same index.

options instance-attribute

options: CircuitOptions

Additional options for circuit execution

precision instance-attribute

precision: float

Target precision for the expectation value measurements

CircuitOptions

Bases: RequestBase

Qesem circuits circuit_options

error_suppression_only class-attribute instance-attribute

error_suppression_only: bool = False

No error mitigation. This results in a much shorter but biased run. When True, the shots parameter becomes mandatory, while precision and observables will be ignored!

transpilation_level class-attribute instance-attribute

transpilation_level: TranspilationLevel = Field(
    default=LEVEL_1
)

Transpilation level type

ErrorSuppressionCircuit

Bases: ParameterizedCircuit

options instance-attribute

options: CircuitOptions

Additional options for circuit execution

shots instance-attribute

shots: int

Amount of shots to run this circuit. Only viable when error-suppression only is True!

ExecutionDetails

Bases: ResponseBase

Detailed statistics about the quantum circuit execution.

gate_fidelities instance-attribute

gate_fidelities: dict[str, float]

Dictionary mapping gate names to their measured fidelities on the QPU

mitigation_shots instance-attribute

mitigation_shots: int

Number of shots used for error mitigation

total_shots instance-attribute

total_shots: int

Total number of times the quantum circuit was executed

transpiled_circuits class-attribute instance-attribute

transpiled_circuits: list[TranspiledCircuit] | None = None

List of circuits after optimization and mapping to the QPU architecture.

ExecutionMode

Bases: str, Enum

The mode of execution.

BATCH class-attribute instance-attribute

BATCH = 'BATCH'

QESEM will execute the job in multiple IBM batches.

SESSION class-attribute instance-attribute

SESSION = 'SESSION'

QESEM will execute the job in a single IBM dedicated session.

ExpectationValue

Bases: ResponseBase

Result of a quantum measurement, containing both the measured value and its uncertainty.

error_bar instance-attribute

error_bar: float

The standard error associated with the measurement

value instance-attribute

value: float

The expected value of the quantum measurement

ExpectationValues

Bases: RootModel[list[tuple[Observable, ExpectationValue]]]

Collection of quantum measurement results, pairing observables with their measured expectation values.

JobDetails

Bases: ResponseBase

Detailed information about a quantum job, including its status, execution details, and results.

account_email instance-attribute

account_email: str

The email address associated with the user account

account_id instance-attribute

account_id: str

The unique identifier of the user account

analytical_qpu_time_estimation instance-attribute

analytical_qpu_time_estimation: timedelta | None

Theoretical estimation of QPU execution time

circuit class-attribute instance-attribute

circuit: Circuit | ErrorSuppressionCircuit | None = None

The quantum circuit to be executed. Returns only if include_circuit is True

created_at instance-attribute

created_at: datetime

Timestamp when the job was created

description class-attribute instance-attribute

description: str = ''

Optional description of the job

empirical_qpu_time_estimation class-attribute instance-attribute

empirical_qpu_time_estimation: timedelta | None = None

Measured estimation of QPU execution time based on actual runs

errors class-attribute instance-attribute

errors: list[str] | None = None

List of error messages generated during job execution

execution_details class-attribute instance-attribute

execution_details: ExecutionDetails | None = None

Information about the execution process. Includes total shots, mitigation shots, and gate fidelities.

intermediate_results class-attribute instance-attribute

intermediate_results: ExpectationValues | None = None

Partial results obtained during job execution.

job_id instance-attribute

job_id: str

The unique identifier of the job

masked_account_token instance-attribute

masked_account_token: str

Partially hidden account authentication token

masked_qpu_token instance-attribute

masked_qpu_token: str

Partially hidden QPU access token

noisy_results class-attribute instance-attribute

noisy_results: ExpectationValues | list[
    dict[int, int]
] | None = None

Results without error mitigation applied.

precision_mode class-attribute instance-attribute

precision_mode: PrecisionMode | None = None

The precision mode used for execution. Can only be used when parameters are set.

progress class-attribute instance-attribute

progress: JobProgress | None = None

Current progress information of the job. Printed automatically when calling qedma_client.wait_for_job_complete().

qpu_name instance-attribute

qpu_name: str

Name of the quantum processing unit (or simulator) being used

qpu_time instance-attribute

qpu_time: QPUTime | None

Actual QPU time used for execution and estimation.

qpu_time_limit class-attribute instance-attribute

qpu_time_limit: timedelta | None = None

Maximum allowed QPU execution time

results class-attribute instance-attribute

results: ExpectationValues | list[
    dict[int, int]
] | None = None

Final results of the quantum computation. Returns only if include_results is True

status instance-attribute

status: JobStatus

Current status of the job

total_execution_time instance-attribute

total_execution_time: timedelta

Total time taken for the job execution. Includes QPU and classical processing time.

updated_at instance-attribute

updated_at: datetime

Timestamp when the job was last updated

warnings class-attribute instance-attribute

warnings: list[str] | None = None

List of warning messages generated during job execution

JobOptions

Bases: RequestBase

Additional options for a job request

execution_mode class-attribute instance-attribute

execution_mode: ExecutionMode | None = None

Execution mode type. Default is BATCH

JobProgress

Bases: BaseModel

Represents job progress, i.e. a list of sequential steps

JobStatus

Bases: str, Enum

The status of a job.

CANCELLED class-attribute instance-attribute

CANCELLED = 'CANCELLED'

The job was cancelled by the user.

ESTIMATED class-attribute instance-attribute

ESTIMATED = 'ESTIMATED'

Job was estimated. Issue the qedma_client.start_job() api request to initiate the execution.

ESTIMATING class-attribute instance-attribute

ESTIMATING = 'ESTIMATING'

Job was created and QESEM is currently estimating it.

FAILED class-attribute instance-attribute

FAILED = 'FAILED'

Job failed. Review the error message in the job.errors field.

RUNNING class-attribute instance-attribute

RUNNING = 'RUNNING'

Job started running. Monitor its progress using the qedma_client.wait_for_job_complete() method.

SUCCEEDED class-attribute instance-attribute

SUCCEEDED = 'SUCCEEDED'

Job finished successfully. The user can now get the results via the qedma_client.get_job() API with the include_results = True flag.

JobStep

Bases: BaseModel

Represents a single step in a job progress

Observable

Bases: RootModel[dict[Pauli, float]]

A quantum observable represented as a mapping of Pauli strings to their coefficients.

ObservableMetadata

Bases: BaseModel

Metadata for a quantum observable.

description instance-attribute

description: str

Description of the observable

ParameterizedCircuit

Bases: RequestBase

circuit instance-attribute

circuit: QuantumCircuit

The quantum circuit to be executed.

parameters class-attribute instance-attribute

parameters: dict[str, tuple[float, ...]] | None = None

Optional dictionary mapping parameter names to their values for parameterized circuits.

PrecisionMode

Bases: str, Enum

Precision mode types when executing a parameterized circuit.

CIRCUIT class-attribute instance-attribute

CIRCUIT = 'CIRCUIT'

QESEM will target the specified precision for each circuit.

JOB class-attribute instance-attribute

JOB = 'JOB'

QESEM will treat the precision as a precision for the sum of the expectation values.

QPUTime

Bases: TypedDict

Time metrics for quantum processing unit (QPU) usage.

estimation instance-attribute

estimation: NotRequired[timedelta]

Estimated time required for QPU execution, may not be present

execution instance-attribute

execution: timedelta

Actual time spent executing the quantum circuit on the QPU

TranspilationLevel

Bases: IntEnum

LEVEL_0 class-attribute instance-attribute

LEVEL_0 = 0

Minimal transpilation: the mitigated circuit will closely resemble the input circuit structurally.

LEVEL_1 class-attribute instance-attribute

LEVEL_1 = 1

Prepares several alternative transpilations and chooses the one that minimizes QPU time.

TranspiledCircuit

Bases: BaseModel

Circuit to be executed on QPU

circuit instance-attribute

circuit: QuantumCircuit

The quantum circuit after optimization, ready for execution.

num_measurement_bases instance-attribute

num_measurement_bases: int

Number of different measurement bases required for this circuit

qubit_map instance-attribute

qubit_map: dict[int, int]

Mapping between logical qubits in the original circuit and physical qubits on the QPU