topqad_sdk.quantum_resource_estimator package

Submodules

topqad_sdk.quantum_resource_estimator.qre module

class topqad_sdk.quantum_resource_estimator.qre.QuantumResourceEstimator[source]

Bases: object

Wrapper class for TopQAD’s Quantum Resource Estimator (QRE) API.

Provides a simple interface to estimate quantum resources for a circuit on specified hardware parameters.

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') → QREOutputs[source]

Estimate quantum resources for a given circuit.

Parameters:

  • circuit_name (str) – Name of the circuit for reference.

  • circuit (Circuit) – The quantum circuit to estimate.

  • hardware_parameters (Union[HardwareParameters, DemoNoiseProfilerSpecs]) – 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”.

Returns:

Contains the generated reports, viewable as an HTML table in Jupyter or as the raw dictionary.

Return type:

QREOutputs

Raises:

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

topqad_sdk.quantum_resource_estimator.qre_output module

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

Bases: object

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.

topqad_sdk.quantum_resource_estimator.qre_output.build_report_views(results)[source]

Parse raw quantum resource estimation report results into structured report objects.

This function converts the raw quantum resource estimation report data into two forms:

  1. A summary view (QREOutputs) aggregating all reports.

  2. A dictionary mapping each architecture/pareto point to a detailed Report object.

Parameters:

results – An object containing quantum resource estimation reports, expected to have a results.assembler_reports attribute.

Returns:

  • summary_view (QREOutputs): Aggregated summary of all qre reports.

  • full_reports (dict[str, Report]): Dictionary of detailed report objects, keyed by pareto point or architecture name.

Return type:

tuple

topqad_sdk.quantum_resource_estimator.qre_output.download_reports(reports: dict, output_file: str | Path = 'reports.json')[source]

Save all Report objects into a single JSON file.

Each Report object’s internal data dictionary is serialized.

Parameters:

  • reports (dict) – Dictionary of Report objects, keyed by name.

  • output_file (str | Path, optional) – Path of the JSON file to create. Defaults to “reports.json” in the current directory.

topqad_sdk.quantum_resource_estimator.report module

class topqad_sdk.quantum_resource_estimator.report.Report(report: dict)[source]

Bases: object

Represents a detailed quantum resource estimation report with structured access to its fields.

Module contents

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

Bases: object

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]

Bases: object

Wrapper class for TopQAD’s Quantum Resource Estimator (QRE) API.

Provides a simple interface to estimate quantum resources for a circuit on specified hardware parameters.

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') → QREOutputs[source]

Estimate quantum resources for a given circuit.

Parameters:

  • circuit_name (str) – Name of the circuit for reference.

  • circuit (Circuit) – The quantum circuit to estimate.

  • hardware_parameters (Union[HardwareParameters, DemoNoiseProfilerSpecs]) – 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”.

Returns:

Contains the generated reports, viewable as an HTML table in Jupyter or as the raw dictionary.

Return type:

QREOutputs

Raises:

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

class topqad_sdk.quantum_resource_estimator.Report(report: dict)[source]

Bases: object

Represents a detailed quantum resource estimation report with structured access to its fields.