Reference

qedma_api.clients.client.Client

Bases: BaseClient

set_provider

set_provider(provider: ClientProvider) -> None

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

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

unregister_qpu_token

unregister_qpu_token() -> None

Unregisters a vendor token for an account.

qedma_api.clients.base_client.BaseClient

Bases: ABC

create_job

create_job(
    *,
    circuit: JobCircuitPayload,
    observables: ObservablesGroups | None = None,
    observables_metadata: Sequence[ObservableMetadata]
    | None = None,
    parameters: Mapping[str | Parameter, Sequence[float]]
    | None = None,
    precision: float | PrecisionPerFactor | 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,
    enable_notifications: bool = True,
    single_mitigation_step: bool = False,
    reuse_characterization: bool = False,
    characterization_from_job_id: str | None = None,
) -> ClientJobDetails

Submit a new job to the API Gateway.

Parameters:

Name	Type	Description	Default
circuit	JobCircuitPayload	The circuit to run.	required
observables	ObservablesGroups | None	The observables to measure. Can be either models.Observable, Sequence[models.Observable], or qiskit.quantum_info.SparsePauliOp.	None
precision	float | PrecisionPerFactor | None	The target absolute precision to achieve for each input observable. If a PrecisionPerFactor is provided, it should be a map from a quantum error tuning factor (error amplification or reduction factor) to the desired precision at that factor (for all observables).	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
enable_notifications	bool	Whether to enable email notifications for this job.	True
single_mitigation_step	bool	Whether to run mitigation in a single step. Default is False.	False
reuse_characterization	bool	Whether this job may reuse a saved characterization. When no characterization_from_job_id is given, reuse applies between batches of this job. Default is False.	False
characterization_from_job_id	str | None	The ID of a recent job (with similar layers) whose characterization will be used for this job. Requires reuse_characterization=True.	None

Returns:

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

start_job

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

Start running a QESEM job.

Parameters:

Name	Type	Description	Default
job_id	str	The ID of the job.	required
max_qpu_time	timedelta | None	The maximum allowed QPU time for an IBM job.	None
max_hqc	float | None	The maximum allowed HQC cost for a Quantinuum job.	None
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

start_resource_estimation

start_resource_estimation(job_id: str) -> None

Start empirical estimation for a Quantinuum job.

Parameters:

Name	Type	Description	Default
job_id	str	The ID of the job.	required

run_device_characterization

run_device_characterization(
    *,
    circuit: QuantumCircuit,
    backend: str,
    enable_notifications: bool = True,
) -> CharacterizationJobDetails

Submit a new job to the API Gateway.

Parameters:

Name	Type	Description	Default
circuit	QuantumCircuit	The circuit to choose the best layout for (acccording to the infidelities).	required
backend	str	The backend (QPU) to run on. (e.g., ibm_fez)	required
enable_notifications	bool	Whether to enable email notifications for this job.	True

Returns:

Type	Description
CharacterizationJobDetails	The layout selected circuit and a dict containing the device characterization: - a dictionary from qubit index to measurement error (dict[int, float]) - a dictionary of gate infidelities per gate type and qubits (dict[tuple[str, tuple[int, int]]])

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

get_job

get_job(
    job_id: str,
    *,
    include_circuits: bool = False,
    include_results: bool = False,
    qedma_observable_model: bool = False,
) -> ClientJobDetails

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
qedma_observable_model	bool	Whether to return the results with Qedma's observable model, or Qiskit SparsePauliOp.	False

Returns:

Type	Description
ClientJobDetails	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,
    qedma_observable_model: bool = False,
) -> list[ClientJobDetails]

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
qedma_observable_model	bool	Whether to return the results with Qedma's observable model, or Qiskit SparsePauliOp.	False

Returns:

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

list_jobs

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

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 | QuantinuumGetJobDetails]	The list of requested jobs.

get_characterization_jobs

get_characterization_jobs(
    jobs_ids: list[str],
) -> list[CharacterizationJobDetails]

Get multiple jobs' details.

Parameters:

Name	Type	Description	Default
jobs_ids	list[str]	The IDs of the jobs.	required

Returns:

Type	Description
list[CharacterizationJobDetails]	the characterization jobs details.

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.

wait_for_analytical_resource_estimation

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

Wait until a Quantinuum job's analytical HQC estimation is available.

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 estimation is available.	None

Returns:

Type	Description
float | None	The analytical HQC estimation of the job.

wait_for_resource_estimation

wait_for_resource_estimation(
    job_id: str,
    *,
    interval: timedelta = STATUS_POLLING_INTERVAL,
    max_poll_time: timedelta | None = None,
) -> tuple[float | None, QuantinuumResults | None]

Wait until a Quantinuum job reaches ESTIMATED status with an empirical HQC 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 estimation is available.	None

Returns:

Type	Description
tuple[float | None, QuantinuumResults | None]	The empirical HQC estimation of the job.

wait_for_job_complete

wait_for_job_complete(
    job_id: str,
    *,
    interval: timedelta = STATUS_POLLING_INTERVAL,
    max_poll_time: timedelta | None = None,
    qedma_observable_model: bool = False,
) -> ClientJobDetails

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
qedma_observable_model	bool	Whether to return the results with Qedma's observable model, or Qiskit SparsePauliOp.	False

Returns:

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

wait_for_characterization_job_complete

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

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
CharacterizationJobDetails	The job results

qedma_api.models

Qedma Public API

JobCircuit module-attribute

JobCircuit: TypeAlias = (
    QiskitCircuit
    | ErrorSuppressionCircuit
    | QuantinuumCircuit
)

Circuit payloads built by job creation and sent in job requests.

JobCircuitPayload module-attribute

JobCircuitPayload: TypeAlias = (
    _QiskitCircuitType | _QuantinuumCircuitType
)

Raw circuit object used when building a job circuit payload.

CircuitOptions module-attribute

CircuitOptions: TypeAlias = (
    QiskitCircuitOptions | QuantinuumCircuitOptions
)

Circuit options accepted by BaseClient.create_job.

ClientJobDetails module-attribute

ClientJobDetails: TypeAlias = (
    IbmClientJobDetails | QuantinuumClientJobDetails
)

Job details returned to API clients for any supported provider.

BaseProvider

Bases: BaseModel

Base class for QPU provider parameters sent by clients.

JobStatus

Bases: str, Enum

The status of a job.

INITIALIZING class-attribute instance-attribute

INITIALIZING = 'INITIALIZING'

Job was created and QESEM is currently initializing it.

ESTIMATING class-attribute instance-attribute

ESTIMATING = 'ESTIMATING'

QESEM is currently estimating the job.

ESTIMATED class-attribute instance-attribute

ESTIMATED = 'ESTIMATED'

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

ESTIMATING_ANALYTICAL class-attribute instance-attribute

ESTIMATING_ANALYTICAL = 'ESTIMATING_ANALYTICAL'

Qesem is currently running analytical HQC estimation.

ESTIMATED_ANALYTICAL class-attribute instance-attribute

ESTIMATED_ANALYTICAL = 'ESTIMATED_ANALYTICAL'

Qesem completed analytical HQC estimation.

ESTIMATING_EMPIRICAL class-attribute instance-attribute

ESTIMATING_EMPIRICAL = 'ESTIMATING_EMPIRICAL'

Qesem is currently running empirical HQC estimation.

ESTIMATED_EMPIRICAL class-attribute instance-attribute

ESTIMATED_EMPIRICAL = 'ESTIMATED_EMPIRICAL'

Qesem completed empirical HQC estimation. Issue the qedma_client.start_job(..., max_hqc=...) API request to initiate execution.

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.

FAILED class-attribute instance-attribute

FAILED = 'FAILED'

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

CANCELLED class-attribute instance-attribute

CANCELLED = 'CANCELLED'

The job was cancelled by the user.

TranspilationLevel

Bases: str, Enum

The level of transpilation applied to the circuit.

MINIMAL class-attribute instance-attribute

MINIMAL = 'minimal'

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

MINIMAL_WITH_LAYOUT_OPT class-attribute instance-attribute

MINIMAL_WITH_LAYOUT_OPT = 'minimal_with_layout_opt'

Minimal transpilation: the mitigated circuit will closely resemble the input circuit structurally. Additionally, the qubit layout will be optimized.

STANDARD class-attribute instance-attribute

STANDARD = 'standard'

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

ObservableMetadata

Bases: BaseModel

Metadata for a quantum observable.

description instance-attribute

description: str

Description of the observable.

Observable

Bases: RootModel[dict[ObsTerm, float]]

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

Each ObsTerm represents a product of operators acting on specific qubits from the following types: - Identity operator: "I" - Pauli operators: "X", "Y", "Z" - Projection operators: - "0": projector to positive eigenstate of Z - "1": projector to negative eigenstate of Z - "r": projector to positive eigenstate of Y - "l": projector to negative eigenstate of Y - "+": projector to positive eigenstate of X - "-": projector to negative eigenstate of X - A general U3 rotation represented as "{op|theta;phi;lambda}" where op is either "Z","0" or "1" in the given U3 rotation of the euler angles (theta, phi, lambda), which represent the following rotation matrix:

[[cos(theta/2), -exp(1jlambda)sin(theta/2)], [exp(1jphi)sin(theta/2), exp(1j(phi+lambda))cos(theta/2)]]

E.g., "{0|1.5;2.4;1}" represents a projection on the positive part of the U3 axis defined by the euler angles (theta=1.5, phi=2.4, lambda=1) with respect to the Z axis.

qubits property

qubits: set[int]

Returns a set of qubits that are used in the observable.

observables_to_qubits staticmethod

observables_to_qubits(
    observables: list[Observable],
) -> set[int]

Returns a set of qubits that are used in the observables.

from_sparse_pauli_op classmethod

from_sparse_pauli_op(pauli_op: SparsePauliOp) -> Observable

Convert a qiskit.quantum_info.SparsePauliOp to an Observable.

SparsePauliOp, like all of qiskit, uses little-endian convention. This means that the operator Pauli("XY") or SparsePauliOp(["XY"],[1]) have the "X" acting on qubit 1 and "Y" acting on qubit 0.

Parameters:

Name	Type	Description	Default
pauli_op	SparsePauliOp	The SparsePauliOp to convert	required

Returns:

Type	Description
Observable	An Observable instance representing the same operator

Raises:

Type	Description
ValueError	If the SparsePauliOp contains phases or complex coefficients, or if it contains only identity Paulis with zero coefficients

to_sparse_pauli_op

to_sparse_pauli_op(
    num_qubits: int | None = None,
) -> SparsePauliOp

Convert this Observable to a qiskit.quantum_info.SparsePauliOp.

SparsePauliOp, like all of qiskit, uses little-endian convention. This means that the operator Pauli("XY") or SparsePauliOp(["XY"],[1]) have the "X" acting on qubit 1 and "Y" acting on qubit 0.

Parameters:

Name	Type	Description	Default
num_qubits	int | None	The number of qubits in the resulting SparsePauliOp. If None, it will be determined from the highest qubit index in the observable	None

from_sparse_observable classmethod

from_sparse_observable(
    sparse_obs: SparseObservable,
) -> Observable

Convert a qiskit.quantum_info.SparseObservable to an Observable.

SparseObservable, like all of qiskit, uses little-endian convention. This means that the operator SparseObservable("XY") have the "X" acting on qubit 1 and "Y" acting on qubit 0.

Parameters:

Name	Type	Description	Default
sparse_obs	SparseObservable	The qiskit.quantum_info.SparseObservable to convert	required

Returns:

Type	Description
Observable	An Observable instance representing the same operator

Raises:

Type	Description
ValueError	If the SparseObservable contains phases or complex coefficients, or if it contains only identity Paulis with zero coefficients

to_sparse_observable

to_sparse_observable(
    num_qubits: int | None = None,
) -> SparseObservable

Convert this Observable to a qiskit.quantum_info.SparseObservable.

SparseObservable, like all of qiskit, uses little-endian convention. This means that the operator SparseObservable("XY") have the "X" acting on qubit 1 and "Y" acting on qubit 0.

Parameters:

Name	Type	Description	Default
num_qubits	int | None	The number of qubits in the resulting SparseObservable. If None, it will be determined from the highest qubit index in the observable	None

MeasurementBasis

Bases: RootModel[str]

A quantum circuit measurement basis represented as a Pauli axis or a general U3 rotation with 3 euler angles represented as "{theta;phi;lambda}" per qubit index. The euler rotation angle matrix representation is:

[[cos(theta/2), -exp(1jlambda)sin(theta/2)], [exp(1jphi)sin(theta/2), exp(1j(phi+lambda))cos(theta/2)]]

E.g., "{1.5;2.4;1}" represents a measurement basis defined by the euler angles (theta=1.5, phi=2.4, lambda=1) with respect to the Z axis.

ExpectationValue

Bases: ResponseBase

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

value instance-attribute

value: float

The expected value of the quantum measurement.

error_bar instance-attribute

error_bar: float

The standard error associated with the measurement.

ScaleExpectationValue

Bases: ExpectationValue

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

scale instance-attribute

scale: float

The quantum error tuning scale (error amplification or reduction scale).

NoiseScalingResult

Bases: ResponseBase

Result for each of the noise scaling factors.

scaling_method class-attribute instance-attribute

scaling_method: Literal['QESEM'] = 'QESEM'

The noise scaling method used.

results_with_REM instance-attribute

results_with_REM: list[ScaleExpectationValue]

List of results for each nonzero noise scaling factor.

scale_factors property

scale_factors: list[float]

List of scale factors used in the noise scaling results.

HeuristicResult

Bases: ExpectationValue

Result of an extrapolation to zero noise.

extrapolation instance-attribute

extrapolation: str

The extrapolation method used (e.g., 'exponential', 'linear', 'quadratic').

scale_factors instance-attribute

scale_factors: list[float]

The scale factors used in the extrapolation.

QuantinuumObservableResult

Bases: ResponseBase

mitigated instance-attribute

mitigated: ExpectationValue | None

The result with no error mitigation.

unmitigated instance-attribute

unmitigated: ExpectationValue | None

The result with no error mitigation.

QesemObservableResult

Bases: ResponseBase

Collection of quantum measurement results for a single observable.

unmitigated instance-attribute

unmitigated: ExpectationValue | None

The result with no error mitigation.

qesem instance-attribute

qesem: ExpectationValue | None

The mitigated QESEM result.

noise_scaling instance-attribute

noise_scaling: NoiseScalingResult

Result for each noise scaling factor.

qesem_heuristic class-attribute instance-attribute

qesem_heuristic: list[HeuristicResult] | None = None

Extrapolated zero noise results.

CircuitQesemResults

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

Collection of quantum measurement results for a single circuit, pairing observables and quantum error tuning factor (error amplification or reduction factor) with their measured expectation values.

QesemResults

Bases: RootModel[list[CircuitQesemResults]]

Collection of quantum measurement results for multiple circuits.

CircuitQiskitResults

Bases: list[tuple[SparseObservable, QesemObservableResult]]

Collection of quantum measurement results for a single circuit, pairing observables and quantum error tuning factor (error amplification or reduction factor) with their measured expectation values.

QiskitResults

Bases: list[CircuitQiskitResults]

Results for multiple circuits.

QesResults

Bases: ResponseBase

Quantum Error suppression results

PrecisionMode

Bases: str, Enum

Precision mode types when executing a parameterized circuit.

JOB class-attribute instance-attribute

JOB = 'JOB'

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

CIRCUIT class-attribute instance-attribute

CIRCUIT = 'CIRCUIT'

QESEM will target the specified precision for each circuit.

ExecutionMode

Bases: str, Enum

The mode of execution.

SESSION class-attribute instance-attribute

SESSION = 'SESSION'

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

BATCH class-attribute instance-attribute

BATCH = 'BATCH'

QESEM will execute the job in multiple IBM batches.

JobOptions

Bases: RequestBase

Additional options for a job request.

execution_mode class-attribute instance-attribute

execution_mode: ExecutionMode = pydantic.Field(
    default=ExecutionMode.BATCH
)

Execution mode type. Default is BATCH.

ReadoutErrorMitigationOptions

Bases: RequestBase

Options for readout error mitigation

num_samples class-attribute instance-attribute

num_samples: int | None = None

The number of samples for mitigating readout errors. When None will use the original amount of shots of the circuit.

algorithm class-attribute instance-attribute

algorithm: Literal["stochastic", "deterministic"] = (
    "stochastic"
)

Algorithm used for readout error mitigation.

CircuitOptionsBase

Bases: RequestBase

measurement_bases class-attribute instance-attribute

measurement_bases: list[MeasurementBasis] | None = None

If provided, the measurement will be performed in the specified bases. The given measurement bases must be able to measure all the observables in the circuit, otherwise an error will be raised.

min_number_of_converged_observables class-attribute instance-attribute

min_number_of_converged_observables: int | None = None

The required number of observables that reach the given precision to consider a success. When None all observables must reach the required precision.

transpilation_level class-attribute instance-attribute

transpilation_level: TranspilationLevel = pydantic.Field(
    default=TranspilationLevel.STANDARD
)

Transpilation level type.

QiskitCircuitOptions

Bases: CircuitOptionsBase

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!

twirl class-attribute instance-attribute

twirl: bool | None = None

Use twirls during transpilation. Only relevant when error_suppression_only is True (Otherwise it is always on).

readout_error_mitigation class-attribute instance-attribute

readout_error_mitigation: (
    ReadoutErrorMitigationOptions | None
) = ReadoutErrorMitigationOptions()

Mitigate readout errors. Only relevant when error_suppression_only is True (Otherwise it is always on).

parallel_execution class-attribute instance-attribute

parallel_execution: bool = False

Whether to parallel the circuit over multiple copies (if possible). Useful for small circuits over large QPUs.

PrecisionPerFactor

Bases: RootModel[dict[float, float]]

A dictionary mapping quantum error tuning factors (error amplification or reduction factors) to desired precisions (for all observables).

BareCircuit

Bases: RequestBase

Minimal quantum circuit representation.

circuit instance-attribute

circuit: _QiskitCircuitType | _QuantinuumCircuitType

The quantum circuit to be executed.

QuantinuumCircuit

Bases: RequestBase

A Quantinuum quantum circuit configuration.

circuit instance-attribute

circuit: _QuantinuumCircuitType

The pytket or Hugr quantum circuit to be executed.

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.

QiskitCircuit

Bases: RequestBase

A Qiskit quantum circuit configuration with error mitigation.

circuit instance-attribute

circuit: _QiskitCircuitType

The Qiskit 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.

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.

precision instance-attribute

precision: float | PrecisionPerFactor

Target precision for the error mitigated expectation value measurements (a.k.a, 0.0 error reduction factor). If a PrecisionPerFactor is provided, it should be a map from a quantum error tuning factor (error amplification or reduction factor) to the desired precision at that factor (for all observables).

options instance-attribute

options: QiskitCircuitOptions

Additional options for circuit execution.

ErrorSuppressionCircuit

Bases: RequestBase

A quantum circuit configuration for error-suppression-only execution.

circuit instance-attribute

circuit: _QiskitCircuitType

The Qiskit 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.

shots instance-attribute

shots: int

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

options instance-attribute

options: QiskitCircuitOptions

Additional options for circuit execution.

QPUTime

Bases: TypedDict

Time metrics for quantum processing unit (QPU) usage.

execution instance-attribute

execution: timedelta

Actual time spent executing the quantum circuit on the QPU.

estimation instance-attribute

estimation: NotRequired[timedelta]

Estimated time required for QPU execution, may not be present.

TranspiledCircuit

Bases: BaseModel

Circuit to be executed on QPU

circuit instance-attribute

circuit: _QiskitCircuitType

The quantum circuit after optimization, ready for execution.

qubit_maps class-attribute instance-attribute

qubit_maps: list[dict[int, int]] = pydantic.Field(
    validation_alias=pydantic.AliasChoices(
        "qubit_maps", "qubit_map"
    )
)

A list of mapping between logical qubits in the original circuit and physical qubits on the QPU, one for each copy of the original circuit (if parallel execution is not used, will contain only one mapping).

num_measurement_bases instance-attribute

num_measurement_bases: int

Number of different measurement bases required for this circuit.

ExecutionDetails

Bases: ResponseBase

Detailed statistics about the quantum circuit execution.

total_shots instance-attribute

total_shots: int

Total number of times the quantum circuit was executed.

mitigation_shots instance-attribute

mitigation_shots: int

Number of shots used for error mitigation.

gate_fidelities instance-attribute

gate_fidelities: dict[str, float]

Dictionary mapping gate names to their measured fidelities on the QPU.

transpiled_circuits class-attribute instance-attribute

transpiled_circuits: list[TranspiledCircuit] | None = None

List of circuits after optimization and mapping to the QPU architecture. None unless include_circuits is True.

JobStep

Bases: BaseModel

Represents a single step in a job progress

name instance-attribute

name: Annotated[
    str, Field(description="The name of the step")
]

The name of the step.

JobProgress

Bases: BaseModel

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

steps instance-attribute

steps: Annotated[
    list[JobStep],
    Field(
        description="List of steps corresponding to JobStep values",
        default_factory=list,
    ),
]

List of steps taken.

CharacterizationJobStatus

Bases: str, Enum

The status of a job.

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.

FAILED class-attribute instance-attribute

FAILED = 'FAILED'

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

CANCELLED class-attribute instance-attribute

CANCELLED = 'CANCELLED'

The job was cancelled by the user.

GateInfidelity

Bases: ResponseBase

Gate infidelity information for a specific gate type and qubits.

name instance-attribute

name: str

The type of gate.

qubits instance-attribute

qubits: tuple[int, ...]

The qubits the gate acts on.

infidelity instance-attribute

infidelity: float

The gate infidelity value.

CharacterizationJobDetails

Bases: ResponseBase

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

account_id instance-attribute

account_id: str

The unique identifier of the user account.

account_email instance-attribute

account_email: str

The email address associated with the user account.

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.

qpu_name instance-attribute

qpu_name: str

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

circuit instance-attribute

circuit: BareCircuit | None

The quantum circuit to choose the layout for.

status instance-attribute

status: CharacterizationJobStatus

Current status of the job.

created_at instance-attribute

created_at: datetime

Timestamp when the job was created.

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.

errors class-attribute instance-attribute

errors: list[str] | None = None

List of error messages generated during job execution.

measurement_errors class-attribute instance-attribute

measurement_errors: dict[int, float] | None = None

qubits measurement errors.

gate_infidelities class-attribute instance-attribute

gate_infidelities: list[GateInfidelity] | None = None

Gate infidelities per gate type and qubits.

layout_optimized_circuit class-attribute instance-attribute

layout_optimized_circuit: BareCircuit | None = None

The quantum circuit after layout optimization.

qubit_map class-attribute instance-attribute

qubit_map: dict[int, int] | None = None

The chosen mapping of the layout optimization process.

enable_notifications class-attribute instance-attribute

enable_notifications: bool = True

Whether to enable email notifications for this job.

JobRequestBase

Bases: RequestBase, Generic[ProviderT]

Request to create a new job

CharacterizationJobRequestBase

Bases: RequestBase

Request to create a new job

StartJobRequest

Bases: RequestBase

Start a job.

QuantinuumStartJobRequest

Bases: RequestBase

Start a Quantinuum job.

IbmGetJobDetails

Bases: JobDetails

Wire-format job details for IBM get-jobs responses.

QuantinuumGetJobDetails

Bases: ResponseBase

Detailed information about a Quantinuum job.

account_id instance-attribute

account_id: str

The unique identifier of the user account.

account_email instance-attribute

account_email: str

The email address associated with the user account.

job_id instance-attribute

job_id: str

The unique identifier of the job.

description class-attribute instance-attribute

description: str = ''

Optional description 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.

qpu_name instance-attribute

qpu_name: str

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

circuit class-attribute instance-attribute

circuit: QuantinuumCircuit | None = None

The quantum circuit to be executed. None unless include_circuit is True.

status instance-attribute

status: JobStatus

Current status of the job.

analytical_hqc_estimation instance-attribute

analytical_hqc_estimation: float | None

Analytical HQC cost estimation.

empirical_hqc_estimation class-attribute instance-attribute

empirical_hqc_estimation: float | None = None

Empirical HQC cost estimation based on actual runs.

total_execution_time instance-attribute

total_execution_time: timedelta

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

created_at instance-attribute

created_at: datetime

Timestamp when the job was created.

updated_at instance-attribute

updated_at: datetime

Timestamp when the job was last updated.

hqc instance-attribute

hqc: float

Actual HQC cost used for execution.

empirical_hqc class-attribute instance-attribute

empirical_hqc: float | None = None

Actual HQC cost used during empirical estimation.

max_hqc class-attribute instance-attribute

max_hqc: float | None = None

Maximum allowed HQC cost.

warnings class-attribute instance-attribute

warnings: list[str] | None = None

List of warning messages generated during job execution.

errors class-attribute instance-attribute

errors: list[str] | None = None

List of error messages generated during job execution.

empirical_estimation_mitigation_results class-attribute instance-attribute

empirical_estimation_mitigation_results: (
    QuantinuumResults | None
) = None

Mitigation results obtained during empirical time estimation. None unless include_results is True.

intermediate_results class-attribute instance-attribute

intermediate_results: QuantinuumResults | None = None

If the job hasn't finished yet or failed, partial results will be stored here. Set include_results to True to get these results, if any.

results class-attribute instance-attribute

results: QuantinuumResults | None = None

Final results of the quantum computation. None unless include_results is True.

execution_details class-attribute instance-attribute

execution_details: ExecutionDetails | None = None

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

empirical_estimation_execution_details class-attribute instance-attribute

empirical_estimation_execution_details: (
    ExecutionDetails | None
) = None

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

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().

execution_mode instance-attribute

execution_mode: ExecutionMode

The mode of execution.

enable_notifications class-attribute instance-attribute

enable_notifications: bool = True

Whether to enable email notifications for this job.

GetJobsDetailsResponse

Bases: ResponseBase

Get-jobs response that may contain a mix of QESEM and Quantinuum jobs.

GetCharJobsDetailsResponse

Bases: ResponseBase

An internal object.

RegisterQpuTokenRequest

Bases: RequestBase

Store qpu token request model

DecomposeResponse

Bases: ResponseBase

Decompose response model

QedmaServerError

Bases: Exception

An exception raised when the server returns an error.

QedmaBadGatewayError

Bases: QedmaServerError

And exception raised when the server returns a 502 Bad Gateway error.

ResultNotReadyError

Bases: QedmaServerError

An exception raised when the server returns an error.

ClientJobDetailsBase

Bases: BaseModel

Common job details returned to API clients. Use IbmClientJobDetails or QuantinuumClientJobDetails for provider-specific fields.

account_id instance-attribute

account_id: str

The unique identifier of the user account.

account_email instance-attribute

account_email: str

The email address associated with the user account.

job_id instance-attribute

job_id: str

The unique identifier of the job.

description class-attribute instance-attribute

description: str = ''

Optional description 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.

qpu_name instance-attribute

qpu_name: str

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

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.

created_at instance-attribute

created_at: datetime

Timestamp when the job was created.

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

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.

empirical_estimation_execution_details class-attribute instance-attribute

empirical_estimation_execution_details: (
    ExecutionDetails | None
) = None

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

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().

enable_notifications class-attribute instance-attribute

enable_notifications: bool = True

Whether to enable email notifications for this job.

IbmClientJobDetails

Bases: ClientJobDetailsBase

Job details for IBM jobs.

circuit class-attribute instance-attribute

circuit: QiskitCircuit | ErrorSuppressionCircuit | None = (
    None
)

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

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.

analytical_qpu_time_estimation instance-attribute

analytical_qpu_time_estimation: timedelta | None

Theoretical estimation of QPU execution time.

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.

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.

empirical_estimation_mitigation_results class-attribute instance-attribute

empirical_estimation_mitigation_results: (
    QiskitResults | QesemResults | None
) = None

Mitigation results obtained during empirical time estimation.

intermediate_results class-attribute instance-attribute

intermediate_results: (
    QiskitResults | QesemResults | None
) = None

Partial results obtained during job execution.

results class-attribute instance-attribute

results: (
    QiskitResults | QesemResults | QesResults | None
) = None

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

execution_mode class-attribute instance-attribute

execution_mode: ExecutionMode | None = None

The mode of execution.

QuantinuumClientJobDetails

Bases: ClientJobDetailsBase

Job details for Quantinuum jobs.

circuit class-attribute instance-attribute

circuit: QuantinuumCircuit | None = None

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

analytical_hqc_estimation class-attribute instance-attribute

analytical_hqc_estimation: float | None = None

Analytical HQC cost estimation.

empirical_hqc_estimation class-attribute instance-attribute

empirical_hqc_estimation: float | None = None

Empirical HQC cost estimation based on actual runs.

hqc class-attribute instance-attribute

hqc: float = 0.0

Actual HQC cost used for execution.

empirical_hqc class-attribute instance-attribute

empirical_hqc: float | None = None

Actual HQC cost used during empirical estimation.

max_hqc class-attribute instance-attribute

max_hqc: float | None = None

Maximum allowed HQC cost.

empirical_estimation_mitigation_results class-attribute instance-attribute

empirical_estimation_mitigation_results: (
    QuantinuumResults | None
) = None

Mitigation results obtained during empirical time estimation.

intermediate_results class-attribute instance-attribute

intermediate_results: QuantinuumResults | None = None

Partial results obtained during job execution.

results class-attribute instance-attribute

results: QuantinuumResults | None = None

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

execution_mode class-attribute instance-attribute

execution_mode: ExecutionMode | None = None

The mode of execution.