Check your setup and list QPUs

The repository ships a small script, ibm_check/check_ibm.py, that tells you whether your setup works and which IBM QPUs your instance can use. Run it after Credentials and first connection, and any time something stops working.

Note

Like the rest of this section, the checker is for the Python track only, for now.

It is read-only: it submits no jobs and uses none of your Open Plan minutes. It never prints your API key.

Run it

With the qalgos environment active, from the repository root:

python ibm_check/check_ibm.py

Or without cloning the repository:

curl -fsSL https://raw.githubusercontent.com/ag4267research1/Quantum-Algorithms/main/ibm_check/check_ibm.py | python -

Options:

python ibm_check/check_ibm.py --name qalgos           # a named saved account
python ibm_check/check_ibm.py --include-simulators    # also list IBM cloud simulators

The exit code is 0 when everything passes and 1 otherwise, so you can use it in scripts.

What it checks

Packages. Qiskit, Qiskit Aer, qiskit-ibm-runtime, numpy and pyyaml are installed, and Qiskit is version 2 or newer.
Local simulator. A Bell-state circuit runs on AerSimulator. This needs no account, so it tells you the Python side works even if IBM does not.
Credentials. It connects to the IBM Quantum Platform with your saved account, or with QISKIT_IBM_TOKEN and QISKIT_IBM_INSTANCE, and prints the channel and instance it used.
QPUs. It lists the backends your instance can use: name, number of qubits, processor family, online or offline, and queue length. The list is sorted with online devices and the shortest queue first, and the script names the least busy one.

Reading the output

The lines look like this (the QPU names and numbers are illustrative; yours will differ):

1. Packages
[ ok ] qiskit 2.5.2
[ ok ] qiskit-aer 0.17.2
[ ok ] qiskit-ibm-runtime 0.49.0
...
2. Local simulator (no account needed)
[ ok ] Bell-state test on AerSimulator: {'00': 491, '11': 509}

4. Available backends
       name                 qubits  processor   status    queue
       ibm_example_a           156  Heron       online        3
       ibm_example_b           127  Eagle       online       41
[ ok ] 2 of 2 backends online
       shortest queue: ibm_example_a

Everything works.

Any line that starts with [FAIL] explains what is wrong.

If a check fails

Check 1 fails: Run ./install.sh and conda activate qalgos, then try again.
Check 2 fails: Qiskit Aer is broken or missing. Reinstall it with pip install --force-reinstall qiskit-aer.
Check 3 fails with Unable to find account: No credentials are saved, or you used a different name. See Credentials and first connection.
Check 3 fails with an authentication error: The API key is wrong or was deleted. Create a new one on the Platform dashboard and save it again.
Check 4 lists no backends: Check the account and region switchers on the Platform, and that the instance you saved is the CRN of an Open Plan instance you can access.
Everything is offline: The devices may be in maintenance. Check the Platform dashboard and try again later.