Skip to content

API Reference - Hardware

Detailed API reference for IBM Quantum hardware integration and noisy simulation.

quantumpytho.modules.hardware_ibm

Classes

IBMHardwareEngine

from quantumpytho.modules.hardware_ibm import IBMHardwareEngine

engine = IBMHardwareEngine(config: HardwareConfig | None = None)

Engine for running circuits on IBM Quantum hardware.

Parameters:

  • config (HardwareConfig, optional) - Hardware configuration object

Methods:

connect
engine.connect() -> None

Connect to IBM Quantum using saved account or token.

Raises:

  • RuntimeError - If connection fails or token not found
run
result = engine.run(
    circuit: QuantumCircuit,
    shots: int = 1024
) -> HardwareResult

Run circuit on IBM Quantum hardware.

Parameters:

  • circuit (QuantumCircuit) - Quantum circuit to run
  • shots (int, optional) - Number of measurement shots. Default: 1024

Returns:

HardwareResult object containing: - counts (dict) - Measurement counts - job_id (str) - IBM Quantum job ID - backend_name (str) - Backend used - shots (int) - Number of shots - status (str) - Job status

Example:

from qiskit import QuantumCircuit
from quantumpytho.modules.hardware_ibm import IBMHardwareEngine

# Create circuit
qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)
qc.measure_all()

# Run on hardware
engine = IBMHardwareEngine()
engine.connect()
result = engine.run(qc, shots=1024)

print(f"Counts: {result.counts}")
print(f"Job ID: {result.job_id}")
list_backends
backends = engine.list_backends() -> list[dict]

List all available IBM Quantum backends.

Returns:

List of backend information dictionaries

Example:

engine = IBMHardwareEngine()
engine.connect()
backends = engine.list_backends()

for backend in backends:
    print(f"{backend['name']}: {backend['num_qubits']} qubits")
select_backend
backend_name = engine.select_backend(
    min_qubits: int = 1,
    least_busy: bool = True
) -> str

Select an appropriate backend.

Parameters:

  • min_qubits (int, optional) - Minimum required qubits. Default: 1
  • least_busy (bool, optional) - Select least busy backend. Default: True

Returns:

Backend name

Example:

engine = IBMHardwareEngine()
engine.connect()
backend = engine.select_backend(min_qubits=5, least_busy=True)
print(f"Selected backend: {backend}")
get_backend_info
info = engine.get_backend_info(backend: str) -> dict

Get detailed information about a backend.

Parameters:

  • backend (str) - Backend name

Returns:

Dictionary with backend information

Example:

engine = IBMHardwareEngine()
engine.connect()
info = engine.get_backend_info("ibm_brisbane")

print(f"Qubits: {info['num_qubits']}")
print(f"Queue: {info['pending_jobs']}")

NoisySimulatorEngine

from quantumpytho.modules.hardware_ibm import NoisySimulatorEngine

engine = NoisySimulatorEngine(noise_profile: str | None = None)

Engine for running circuits with realistic noise from vendor-neutral backend profiles.

Parameters:

  • noise_profile (str, optional) - Noise profile name. Default: None (uses synthetic demo)

Methods:

run
result = engine.run(
    circuit: QuantumCircuit,
    shots: int = 1024
) -> NoisySimulatorResult

Run circuit with noise simulation.

Parameters:

  • circuit (QuantumCircuit) - Quantum circuit to run
  • shots (int, optional) - Number of measurement shots. Default: 1024

Returns:

NoisySimulatorResult object containing: - counts (dict) - Measurement counts - noise_profile (str) - Noise profile used - shots (int) - Number of shots

Example:

from qiskit import QuantumCircuit
from quantumpytho.modules.hardware_ibm import NoisySimulatorEngine

# Create circuit
qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)
qc.measure_all()

# Run with noise
engine = NoisySimulatorEngine(noise_profile="ibm_brisbane")
result = engine.run(qc, shots=1024)

print(f"Counts: {result.counts}")
print(f"Noise profile: {result.noise_profile}")
get_available_profiles
profiles = engine.get_available_profiles() -> list[str]

List all available noise profiles.

Returns:

List of profile names

Example:

engine = NoisySimulatorEngine()
profiles = engine.get_available_profiles()

for profile in profiles:
    print(profile)
get_profile_info
info = engine.get_profile_info(profile: str) -> dict

Get detailed information about a noise profile.

Parameters:

  • profile (str) - Profile name

Returns:

Dictionary with profile information: - name (str) - Profile name - num_qubits (int) - Number of qubits - avg_t1_us (float) - Average T1 time in microseconds - avg_t2_us (float) - Average T2 time in microseconds - avg_readout_error (float) - Average readout error rate

Example:

engine = NoisySimulatorEngine()
info = engine.get_profile_info("ibm_brisbane")

print(f"Qubits: {info['num_qubits']}")
print(f"Avg T1: {info['avg_t1_us']} μs")
print(f"Avg T2: {info['avg_t2_us']} μs")
print(f"Readout error: {info['avg_readout_error'] * 100:.3f}%")

Functions

run_with_noise

from quantumpytho.modules.hardware_ibm import run_with_noise

result = run_with_noise(
    circuit: QuantumCircuit,
    noise_profile: str,
    shots: int = 1024
) -> dict

Convenience function to run circuit with noise.

Parameters:

  • circuit (QuantumCircuit) - Quantum circuit to run
  • noise_profile (str) - Noise profile name
  • shots (int, optional) - Number of measurement shots. Default: 1024

Returns:

Dictionary with results

Example:

from qiskit import QuantumCircuit
from quantumpytho.modules.hardware_ibm import run_with_noise

# Create circuit
qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)
qc.measure_all()

# Run with noise
result = run_with_noise(qc, "ibm_brisbane", shots=1024)
print(f"Counts: {result['counts']}")

check_credentials

from quantumpytho.modules.hardware_ibm import check_credentials

has_credentials = check_credentials() -> bool

Check if IBM Quantum credentials are available.

Returns:

True if credentials are available, False otherwise

Example:

from quantumpytho.modules.hardware_ibm import check_credentials

if check_credentials():
    print("Credentials found")
else:
    print("Please set QISKIT_IBM_TOKEN environment variable")

quantumpytho.modules.noise_builder

Classes

NoiseProfile

from quantumpytho.modules.noise_builder import NoiseProfile

profile = NoiseProfile(
    name: str,
    num_qubits: int,
    avg_t1_us: float,
    avg_t2_us: float,
    avg_readout_error: float,
    single_qubit_errors: dict,
    two_qubit_errors: dict,
    connectivity: list
)

Noise profile data structure.

Functions

import_calibration_csv

from quantumpytho.modules.backend_profiles import import_calibration_csv, SourceProvider

profile = import_calibration_csv(
    path: str | Path,
    provider: SourceProvider,
    backend_name: str,
    validate: bool = True
) -> BackendProfile

Import backend calibration data from a user-provided CSV file.

Parameters:

  • path (str | Path) - Path to CSV file
  • provider (SourceProvider) - Source provider (IBM, IonQ, etc.)
  • backend_name (str) - Name of the backend
  • validate (bool, optional) - Validate imported data. Default: True

Returns:

BackendProfile object

build_noise_model_from_profile

from quantumpytho.modules.noise_builder import build_noise_model_from_profile

noise_model = build_noise_model_from_profile(profile: BackendProfile) -> NoiseModel

Build Qiskit Aer noise model from profile.

Parameters:

  • profile (NoiseProfile) - Noise profile object

Returns:

Qiskit Aer NoiseModel object

Example:

from quantumpytho.modules.noise_builder import (
    parse_calibration_csv,
    build_noise_model_from_profile
)

# Parse calibration data
profile = parse_calibration_csv("ibm_brisbane")

# Build noise model
noise_model = build_noise_model_from_profile(profile)

# Use with simulator
from qiskit_aer import AerSimulator
simulator = AerSimulator(noise_model=noise_model)

get_backend_profile_names

from quantumpytho.modules.noise_builder import get_backend_profile_names

profiles = get_backend_profile_names() -> list[str]

Get list of available backend profile names.

Returns:

List of profile names

See Also