Helpers

Helper methods for mapping Qiskit classes to IonQ REST API compatible values.

qiskit_ionq.helpers.circuit_requires_qasm3(input_circuit: QuantumCircuit) → bool[source]

True for circuits the flat v1 gate list can’t express – mid-circuit measurement, reset, or control flow – which are submitted as OpenQASM 3.

Control flow is detected and routed, but isn’t supported server-side yet.

qiskit_ionq.helpers.compress_to_metadata_string(metadata: dict | list) → str[source]

Convert a metadata object to a compact string format (dumped, gzipped, base64 encoded) for storing in IonQ API metadata

Parameters:

metadata (dict or list) – a dict or list of dicts with metadata relevant to building the results object on a returned job.

Returns:

encoded string

Return type:

str

qiskit_ionq.helpers.decompress_metadata_string(input_string: str | None) → dict | list | None[source]

Convert compact string format (dumped, gzipped, base64 encoded) from IonQ API metadata back into a dict or list of dicts relevant to building the results object on a returned job.

Parameters:

input_string (str | None) – compressed string format of metadata dict, or None when the API omitted metadata.

Returns:

decompressed metadata, or None if the input was None.

Return type:

dict or list or None

qiskit_ionq.helpers.get_n_qubits(backend, fallback=4)[source]

Get the number of qubits for a given backend.

qiskit_ionq.helpers.get_user_agent() → str[source]

Generates the user agent string which is helpful in identifying different tools in the internet. Valid user-agent ionq_client header that indicates the request is from qiskit_ionq along with the system, os, python,libraries details.

Returns:

A string of generated user agent.

Return type:

str

qiskit_ionq.helpers.qiskit_circ_to_ionq_circ(input_circuit: QuantumCircuit, gateset: Literal['qis', 'native'] = 'qis', ionq_compiler_synthesis: bool = False)[source]

Build a circuit in IonQ’s instruction format from qiskit instructions.

Attention

This function ignores the following compiler directives: * barrier

Parameters:

  • input_circuit (qiskit.circuit.QuantumCircuit) – A Qiskit quantum circuit.

  • gateset (string) – Set of gates to target. It can be QIS (required transpilation pass in IonQ backend, which is sent standard gates) or native (only IonQ native gates are allowed, in the future we may provide transpilation to these gates in Qiskit).

  • ionq_compiler_synthesis (bool) – Whether to opt-in to IonQ compiler’s intelligent trotterization.

Raises:

  • IonQGateError – If an unsupported instruction is supplied.

  • IonQMidCircuitMeasurementError – If a qubit is used after measurement. The flat v1 format can’t express this; backend.run routes such circuits to OpenQASM 3, so this only fires when this builder is called directly.

  • IonQPauliExponentialError – If non-commuting PauliExponentials are found without the appropriate flag.

Returns:

A list of instructions in a converted dict format. int: The number of measurements. dict: The measurement map from qubit number to classical bit number.

Return type:

list[dict]

qiskit_ionq.helpers.qiskit_to_ionq(circuit, backend, passed_args: dict | None = None, extra_query_params: dict | None = None, extra_metadata: dict | None = None) → str[source]

Convert a Qiskit circuit to a IonQ compatible dict.

Parameters:

  • circuit (qiskit.circuit.QuantumCircuit) – A Qiskit quantum circuit.

  • backend (qiskit_ionq.IonQBackend) – The IonQ backend.

  • passed_args (dict) – Dictionary containing additional passed arguments, eg. shots.

  • extra_query_params (dict) – Specify any parameters to include in the request

  • extra_metadata (dict) – Specify any additional metadata to include.

Returns:

A string / JSON-serialized dictionary with IonQ API compatible values.

Return type:

str

qiskit_ionq.helpers.resolve_credentials(token: str | None = None, url: str | None = None) → dict[source]

Resolve credentials for use in IonQ API calls.

If the provided token and url are both None, the token is read from IONQ_API_KEY (also QISKIT_IONQ_API_TOKEN or IONQ_API_TOKEN) and the url from IONQ_API_URL (or QISKIT_IONQ_API_URL).

If no url is discovered, then https://api.ionq.co/v0.4 is used.

Parameters:

  • token (str) – IonQ API access token.

  • url (str, optional) – IonQ API url. Defaults to None.

Returns:

A dict with “token” and “url” keys, for use by a client.

Return type:

dict[str]

qiskit_ionq.helpers.retry(exceptions: Any, tries: int = -1, delay: float = 0, max_delay: float = inf, backoff: float = 1, jitter: float = 0, enable_logging: bool = True)[source]

Retry decorator with exponential backoff.

Parameters:

  • exceptions – The exception(s) to catch. Can be a tuple of exceptions.

  • tries – Number of attempts before giving up. -1 means infinite tries.

  • delay – Initial delay between retries in seconds.

  • max_delay – Maximum delay between retries.

  • backoff – Multiplier applied to delay after each retry.

  • jitter – Maximum random jitter added to delay.

  • enable_logging – Whether to log failures.