topqad_sdk.quantum_resource_estimator package

class topqad_sdk.quantum_resource_estimator.QREOutputs(reports: dict[str, dict], mode: QREMode)[source]

Result of the Quantum Resource Estimator containing the report contents on the Pareto frontier solutions.

as_dict()[source]

Convert the model to a dictionary.

get_summary() → dict[source]

Returns a summary dictionary for each architecture, mapping architecture name to its summary fields.

reports: dict[str, Report]
show_report(report_name: str) → Report[source]

Returns the report for a specific architecture.

Parameters:

report_name (str) – The name of the architecture to retrieve the report for.

Returns:

The report object for the specified architecture.

Return type:

Report

space_optimal_architecture() → Report[source]

Returns the space-optimal architecture report.

The space-optimal architecture is the one with the lowest number of physical qubits.

time_optimal_architecture() → Report[source]

Returns the time-optimal architecture report.

The time-optimal architecture is the one with the lowest expected runtime.

to_json(save_path='qre_output.json', indent=2)[source]

Save the quantum resource estimaton output to a JSON file.

Parameters:

  • save_path (str or Path) – Path to save the JSON file. Defaults to “qre_output.json”.

  • indent (int) – Number of spaces to use for indentation in the JSON file. Defaults to 2.

class topqad_sdk.quantum_resource_estimator.QuantumResourceEstimator[source]

The QuantumResourceEstimator provides an interface for TopQAD’s Quantum Resource Estimator (QRE) service.

This class allows users to estimate the resources required to execute quantum circuits on specific hardware configurations. It supports both full estimation for detailed analysis and Lite mode for streamlined estimation without needing a full circuit file.

This class supports both synchronous and asynchronous execution modes, making it easy to integrate into quantum workflows.

cancel() → dict[source]

Cancel a running QRE job.

This method allows the user to cancel the currently running job associated with this instance (i.e., the most recent job submitted).

Returns:

  • pipeline_id (str): The pipeline ID of the request to be cancelled.

  • status (str): The status of the job after the cancel request, with possible values including “cancel_pending” (the cancel request was successful, and the job is being cancelled) or the current status of the job (e.g., “done”, “failed”, etc.) if the cancel request was declined or the job cannot be cancelled.

  • message (str): Information about the cancellation request.

Return type:

dict

Raises:

  • TopQADError – If the cancellation fails due to an internal error.

  • ValueError – If no pipeline ID is found.

Examples

from topqad_sdk.library import CircuitLibrary, HardwareParameters
from topqad_sdk.noiseprofiler import qre_noiseprofile
from topqad_sdk.quantum_resource_estimator import QuantumResourceEstimator

# See `CircuitLibrary` documentation for more details.
circuit = CircuitLibrary()
circuit = circuit.example_circuits[0]

# Create a hardware noise profile from a built-in preset
# See `HardwareParameters` documentation for more details.
noise_profile_preset = qre_noiseprofile.noise_profile_from_preset(
    "physical_depolarizing_target"
)
hardware_params = HardwareParameters()
hardware_params.load_from_json_string(noise_profile_preset)

qre = QuantumResourceEstimator()

qre.run(
    circuit=circuit,
    hardware_parameters=hardware_params,
    global_error_budget=0.01,
    async_mode=True, # Async mode
)
print(qre.cancel())

Starting quantum resource estimation...
QRE request with pipeline_id ... has been submitted. Please come back later and call get_reports
Cancel request for pipeline_id ... has been submitted.
{'pipeline_id': '...', 'status': 'cancel_pending', 'message': 'Cancellation request submitted.'}
get_reports(download_reports_flag: bool = False, reports_output_file: str | Path = 'reports.json') → QREOutputs | dict[source]

Retrieve the QRE reports from the request.

Parameters:

  • download_reports_flag (bool, optional) – When enabled, saves the reports to the path specified by reports_output_file. Defaults to False.

  • reports_output_file (str | Path, optional) – Path to the output file for saving downloaded reports. Only used if download_reports_flag is True. Defaults to “reports.json”.

Returns:

The generated reports for the QRE request. If download_reports_flag is enabled, the reports are also saved locally. If the reports have not finished then the current status and pipeline ID of job will be returned.

Return type:

QREOutputs|dict

load(pipeline_id)[source]

Retrieves and loads pipeline information from server using given pipeline_id.

This method fetches the status and results of a previously submitted QRE job. If the job is complete, the reports are also loaded into the current instance. Any existing cached data (e.g., reports, status, pipeline ID) in the instance will be overwritten.

Use this method when you have a pipeline_id from a previously submitted job and want to retrieve its current status or results.

Parameters:

pipeline_id (str) – The ID of the QRE pipeline.

Returns:

Status and pipeline ID of the request.

Return type:

dict

Examples

from topqad_sdk.quantum_resource_estimator import QuantumResourceEstimator

qre = QuantumResourceEstimator()

pipeline_id = "12345" # Replace with your actual pipeline ID
print(qre.load(pipeline_id))

{'pipeline_id': '12345', 'status': 'done'}
run(circuit: LiteCircuit, hardware_parameters: HardwareParameters | str, global_error_budget: float, timeout: str = '0', async_mode: bool = False, *, download_reports_flag: bool = False, cost: float = 0, reports_output_file: str | Path = 'reports.json', overwrite_reports: bool = False) → QREOutputs | dict[source]
run(circuit: Circuit, hardware_parameters: HardwareParameters | str, global_error_budget: float, async_mode: bool = False, *, download_reports_flag: bool = False, number_of_repetitions: int = 1, cost: float = 0, remove_clifford_gates: bool = True, insights_only: bool = False, reports_output_file: str | Path = 'reports.json', overwrite_reports: bool = False) → QREOutputs | dict

Estimate quantum resources for a given circuit.

This method supports two execution modes: Synchronous and Asynchronous.

  • Sync Mode: The method waits for the job to complete and retrieves the results immediately. Use this mode when you want to block execution until the job finishes.

  • Async Mode: The method submits the job and returns immediately with the pipeline_id and status. Use this mode when you want to submit the job and retrieve the results later.

Interactive Cancellation (sync mode):

In a terminal: While waiting for the job to complete, you can press Ctrl+C to interrupt polling.

When interrupted, you will be prompted to choose one of the following options:

  1. Stop tracking the job (exit, job continues on server).

  2. Send a cancellation request to the server and exit.

  3. Resume waiting for the job to complete.

In a Jupyter notebook: Interrupting the cell (by pressing the stop button ■ in the notebook interface) while the job is running in synchronous mode will cancel the job on the server.

Parameters:

  • circuit (Circuit | LiteCircuit) – The quantum circuit to estimate. Use LiteCircuit for streamlined estimation.

  • hardware_parameters (HardwareParameters | str) – A HardwareParameters object or one of the strings: “baseline”, “desired”, or “target”.

  • global_error_budget (float) – Maximum allowable error for the circuit.

  • async_mode (bool, optional) – When enabled, allows asynchronous execution. Defaults to False. This feature is not available in the Beta version.

  • download_reports_flag (bool, optional) – When enabled, download detailed reports to the path specified in the reports_output_file. Defaults to False.

  • number_of_repetitions (int, optional) – Number of repetitions. Defaults to 1.

  • cost (float, optional) – Cost for QRE execution. Defaults to 0.

  • remove_clifford_gates (bool, optional) – Whether to remove Clifford gates. Defaults to True.

  • insights_only (bool, optional) – Whether to only generate insights (skip scheduling). Defaults to False.

  • reports_output_file (str | Path, optional) – Output file for downloaded reports. Only applicable if download_reports_flag is True. Defaults to “reports.json”.

  • overwrite_reports (bool) – Flag to overwrite existing reports if they exists. Defaults to False.

Returns:

Contains the generated reports, viewable as an HTML table in Jupyter or as the raw dictionary. Returns dict of pipeline_id and status if async_mode set to True.

Return type:

QREOutputs|dict

Raises:

  • KeyboardInterrupt – If the job is interrupted by the user.

  • ValueError – If hardware_parameters is not a valid HardwareParameters object or an accepted string.

  • ValueError – If the pipeline ID is not found in the response.

  • TopQADTimeoutError – If polling for the QRE job times out.

  • RuntimeError – If the QRE job fails or polling times out.

Examples

Synchronous Mode
from topqad_sdk.library import CircuitLibrary, HardwareParameters
from topqad_sdk.noiseprofiler import qre_noiseprofile
from topqad_sdk.quantum_resource_estimator import QuantumResourceEstimator

# See `CircuitLibrary` documentation for more details.
circuit = CircuitLibrary()
circuit = circuit.example_circuits[0]

# Create a hardware noise profile from a built-in preset
# See `HardwareParameters` documentation for more details.
noise_profile_preset = qre_noiseprofile.noise_profile_from_preset(
    "physical_depolarizing_target"
)
hardware_params = HardwareParameters()
hardware_params.load_from_json_string(noise_profile_preset)

qre = QuantumResourceEstimator()

qre_output = qre.run(
    circuit=circuit,
    hardware_parameters=hardware_params,
    global_error_budget=0.01,
)

# See `QREOutputs` documentation for details on output handling
print(qre_output.get_summary())

Starting quantum resource estimation...
QuantumResourceEstimator completed...
{'1': {'expected_runtime': ..., 'num_physical_qubits': ..., 'computation_cost': ...}}
Asynchronous Mode
from topqad_sdk.library import CircuitLibrary, HardwareParameters
from topqad_sdk.noiseprofiler import qre_noiseprofile
from topqad_sdk.quantum_resource_estimator import QuantumResourceEstimator

circuit = CircuitLibrary()
circuit = circuit.example_circuits[0]

noise_profile_preset = qre_noiseprofile.noise_profile_from_preset(
    "physical_depolarizing_target"
)
hardware_params = HardwareParameters()
hardware_params.load_from_json_string(noise_profile_preset)

qre = QuantumResourceEstimator()

response = qre.run(
    circuit=circuit,
    hardware_parameters=hardware_params,
    global_error_budget=0.01,
    async_mode=True,  # Asynchronous mode
)
pipeline_id = response["pipeline_id"] # Store the job ID for later use

qre.load(pipeline_id=pipeline_id) # Load the job later
qre_output = qre.get_reports() # Retrieve and display reports when ready

print(qre_output.get_summary())

Starting quantum resource estimation...
QRE request with pipeline_id ... has been submitted. Please come back later and call get_reports
Existing reports for pipeline ID ... found. Returning...
{'1': {'expected_runtime': ..., 'num_physical_qubits': ..., 'computation_cost': ...}}
Lite Mode
from topqad_sdk.models import LiteCircuit
from topqad_sdk.library import HardwareParameters
from topqad_sdk.noiseprofiler import qre_noiseprofile
from topqad_sdk.quantum_resource_estimator import QuantumResourceEstimator

# Define a LiteCircuit for streamlined estimation instead of a full circuit file.
lite_circuit = LiteCircuit(num_qubits = 50, num_operations = 1e10)

noise_profile_preset = qre_noiseprofile.noise_profile_from_preset(
    "physical_depolarizing_target"
)
hardware_params = HardwareParameters()
hardware_params.load_from_json_string(noise_profile_preset)

qre = QuantumResourceEstimator()

qre_output = qre.run(
    circuit=lite_circuit,
    hardware_parameters=hardware_params,
    global_error_budget=0.01,
)
print(qre_output.get_summary())

Starting quantum resource estimation...
QuantumResourceEstimator completed...
{'1': {'expected_runtime': ..., 'num_physical_qubits': ..., 'computation_cost': ...}}