Appendix C: Environment Setup

The exact environment this book's code was written and executed in, plus the failure modes worth knowing about.

Versions used

Every example in this book ran against these:

Python                   3.12
qiskit                   2.5.1
qiskit-aer               0.17.2
qiskit-ibm-runtime       0.48.0
pennylane                0.45.1
cirq                     1.7.0
qdk (Q#)                 1.31.0
amazon-braket-sdk        1.125.0
numpy                    2.x
scipy                    1.18.0
scikit-learn             1.9.0
networkx                 3.6.1
cvxpy                    1.9.2          (Chapter 37 only)
cryptography             50.0.0         (Chapter 38 only — ships ML-KEM)
matplotlib               3.x

Minimal install

python -m venv qenv
source qenv/bin/activate            # Windows: qenv\Scripts\activate
python -m pip install --upgrade pip

pip install qiskit qiskit-aer qiskit-ibm-runtime matplotlib

That covers Parts I, II, and most of IV–V. Add per part:

pip install pennylane scikit-learn          # Parts IV, VI
pip install cirq-core                       # Chapter 14
pip install qsharp                          # Chapter 15
pip install amazon-braket-sdk               # Chapter 17
pip install networkx cvxpy                  # Chapter 37
pip install "cryptography>=46"              # Chapter 38 (ML-KEM)

⚠️ Do not install everything at once. Cirq, Qiskit, and PennyLane have overlapping transitive dependencies and pinning conflicts are common. Install per part, in separate environments if you hit one.

Cloud credentials

from qiskit_ibm_runtime import QiskitRuntimeService
QiskitRuntimeService.save_account(channel="ibm_quantum_platform", token="YOUR_TOKEN")

The token is stored in ~/.qiskit/qiskit-ibm.json. Never commit it.

export QISKIT_IBM_TOKEN="..."       # the alternative, for CI

For Braket, configure AWS credentials normally (aws configure).

Verifying the install

import qiskit, qiskit_aer
from qiskit import QuantumCircuit, transpile
from qiskit_aer import AerSimulator

print(qiskit.__version__, qiskit_aer.__version__)

qc = QuantumCircuit(2); qc.h(0); qc.cx(0, 1); qc.measure_all()
print(AerSimulator().run(transpile(qc, AerSimulator()), shots=1024).result().get_counts())

Roughly 50/50 between 00 and 11, with nothing in between. If you see 01 or 10, something is wrong with the install, not with quantum mechanics.

Failure modes worth knowing

qiskit.pulse does not exist. Removed in Qiskit 2.0, along with QuantumCircuit.add_calibration, .calibrations, backend.defaults(), instruction_schedule_map, and drive_channel. Chapter 31 covers what replaced it. Tutorials written before 2024 will not run.

BackendV1 is gone. Use backend.target for everything: gate durations, error rates, coupling map, dt.

Deprecation warnings that are load-bearing. QuantumCircuit.duration (use ALAPScheduleAnalysis), the QFT class (use synth_qft_full), the EfficientSU2 class (use efficient_su2()). These still work and will not.

PennyLane gradients returning shape (0,). Parameters must be pennylane.numpy arrays with requires_grad=True, not plain NumPy. Chapter 32 lost time to this.

PennyLane QNode loops being 100× too slow. PennyLane broadcasts over a leading batch axis. Passing samples one at a time timed out at 10 minutes in Chapter 33; batched, it took seconds.

Windows PowerShell and UTF-8. PowerShell 5.1's Set-Content defaults to the system codepage, which corrupts em-dashes and box-drawing characters. Pass -Encoding utf8 explicitly, or use Python for any file that contains non-ASCII.

Terminal mojibake that is not a bug. If Mølmer–Sørensen prints as M�lmer�S�rensen, check the file's bytes before fixing anything — twice while writing this book the file was correct UTF-8 and the terminal was the problem.

Running this book's code

Each chapter has a code/ directory:

cd part-07-applications-and-career/chapter-37-quantum-optimization-qaoa/code
python example-01-maxcut-and-the-baselines.py
python project-checkpoint.py                    # the chapter's tests

Checkpoints import from vqelab/, which sits beside them. Run from inside code/ so the import resolves.

Set PYTHONIOENCODING=utf-8 if your terminal mangles the output — every example prints ★ and box characters.

Hardware access is optional

Everything in this book except the explicitly-flagged hardware sections runs on a local simulator. Chapter 39 measured why that is not a compromise: local simulation of a 4,096-shot job took 22–74 ms against the device's 7–43 ms of execution time — the same order of magnitude, with no queue and no bill.

Use hardware for the one thing only hardware provides: real noise.

See also: Appendix A (Qiskit API), Appendix G (hardware), Appendix H (the wider ecosystem).