QuScope v0.2.0 Documentation

QuScope is a Python package for applying quantum computing algorithms to Transmission Electron Microscopy (TEM) simulation. Built on Qiskit, it provides fully-quantum circuit implementations of every stage of the TEM imaging pipeline — from specimen interaction to detector readout — validated against classical reference implementations with fidelity ≥ 0.9999.

🔬 Key Features

Quantum CTEM: Single-slice (WPOA) and multislice conventional TEM image simulation as one quantum circuit (state prep -> QFT -> diagonal-gate phase grating/lens CTF -> IQFT)
Quantum STEM: Per-probe-position quantum circuits with HAADF / ADF / ABF / BF / iDPC detector channels
Quantum Diffraction: WPOA, SAED, CBED, nano-beam diffraction (nBD), Kikuchi, and EBSD patterns
Dynamical Scattering: Bloch-wave formalism with eigenvalues extracted via Quantum Phase Estimation
Thermal Diffuse Scattering: Quantum frozen-phonon modules (QTPC, QPS, Lindblad channel) for Debye-Waller-parameterized thermal effects
Backend Management: Local Qiskit Aer simulators and real IBM Quantum hardware via Qiskit Runtime
Ready-to-Use Notebooks: A full notebook gallery demonstrating every module above on real materials (MoS₂, graphene, Si₃N₄)

🚀 Quick Start

Install QuScope via pip:

pip install quscope

Basic usage — simulate a quantum CTEM image and validate it against a classical reference:

from quscope.quantum_ctem import (
    QuantumCTEMCircuit,
    QuantumCTEMParameters,
    QuantumClassicalValidator,
)
import numpy as np

# 8x8 grid (6 qubits), 200 kV, Scherzer condition
params = QuantumCTEMParameters(
    acceleration_voltage=200e3,
    grid_size=8,
    pixel_size=0.5,       # Angstrom/pixel
    defocus=-659.7,       # Angstrom (Scherzer defocus)
    cs=1.3,               # mm
)
sim = QuantumCTEMCircuit(params)

# Simulate a random projected potential
V = np.random.rand(8, 8) * 100          # projected potential in V*Angstrom

result = sim.simulate(V)
print("Wave function shape:", result["wave_function"].shape)   # (8, 8)
print("Intensity range   :", result["intensity"].min(), "-", result["intensity"].max())

# Validate against classical implementation
validator = QuantumClassicalValidator(params)
comparison = validator.compare(V)
print(f"Quantum-classical fidelity: {comparison['fidelity']:.6f}")   # -> 1.000000

See the Notebook Gallery for the full set of runnable demonstrations (CTEM, STEM, diffraction, Bloch wave, and frozen phonons).

🔗 Links

Repository: https://github.com/QuScope/QuScope
Issues: https://github.com/QuScope/QuScope/issues
PyPI: https://pypi.org/project/quscope/

📖 Indices and Tables

🔬 QuScope v0.2.0: Quantum Algorithms for Electron Microscopy

QuScope is a Python package for applying quantum computing algorithms to Transmission Electron Microscopy (TEM) simulation. Built on Qiskit, it expresses the TEM image-formation pipeline as quantum circuits — the electron wavefunction is amplitude-encoded on qubits, and every optical element (phase grating, Fresnel propagation, objective lens) is a diagonal unitary conjugated by quantum Fourier transforms — validated against classical reference implementations to unit fidelity.

v0.2.0 provides four fully-quantum imaging pipelines: CTEM (WPOA), CTEM multislice, STEM (WPOA), and STEM multislice.

Developed by Sean D. Lam and Roberto dos Reis · Northwestern University

📄 Paper: Quantum Algorithm Framework for Phase-Contrast Transmission Electron Microscopy Image Simulation — arXiv:2602.13438 [quant-ph], Feb 2026

🚀 Quick Start

pip install quscope

from quscope.quantum_ctem import (
    QuantumCTEMCircuit,
    QuantumCTEMParameters,
    QuantumClassicalValidator,
)
import numpy as np

# 8×8 grid (6 qubits), 200 kV, Scherzer condition
params = QuantumCTEMParameters(
    acceleration_voltage=200e3,
    grid_size=8,
    pixel_size=0.5,       # Å/pixel
    defocus=-659.7,       # Å  (Scherzer defocus)
    cs=1.3,               # mm
)
sim = QuantumCTEMCircuit(params)

# Simulate a random projected potential
V = np.random.rand(8, 8) * 100          # projected potential in V·Å

result = sim.simulate(V)
print("Image shape    :", result["intensity"].shape)   # (8, 8)
print("Intensity range:", result["intensity"].min(), "–", result["intensity"].max())

# Validate against classical implementation
validator = QuantumClassicalValidator(params)
comparison = validator.compare(V)
print(f"Quantum–classical fidelity: {comparison['fidelity']:.6f}")   # → 1.000000

✨ Available Modules (v0.2.0)

Module	Technique	Quantum Engine
`quantum_ctem_circuit`	CTEM bright-field imaging (WPOA + CTF)	Phase-grating DiagonalGate → QFT → CTF DiagonalGate → IQFT
`quantum_multislice_circuit`	CTEM multislice propagation	Alternating phase grating / Fresnel-propagator DiagonalGates + QFT
`quantum_stem`	STEM imaging (single-slice WPOA)	One quantum circuit per probe position
`quantum_stem_multislice`	STEM multislice propagation	Probe state through the multislice circuit per scan position

Supporting infrastructure: ctf_calculator (aberration function), hamiltonian (TEM Hamiltonian), momentum_space, quantum_encoding, classical reference implementations (classical_validation, ctem/, simulations/), Kirkland scattering-factor tables (utils/), materials workflows (MoS₂, graphene), circuit optimization, and IBM Quantum backend wrappers.

STEM Detector Channels

Channel	Inner (mrad)	Outer (mrad)	Contrast
HAADF	60	200	Z-contrast
ADF	25	60	Mixed
ABF	10	25	Light elements
BF	0	10	Phase
iDPC	—	—	From BF centre-of-mass

🛣 Roadmap

Quantum diffraction modes (SAED, CBED, nBD, Kikuchi, EBSD), frozen-phonon / thermal-diffuse-scattering channels, and the Bloch-wave QPE eigensolver are under development on the dev branch and planned for a future release.

📦 Installation

From PyPI (recommended)

pip install quscope

Development install

git clone https://github.com/QuScope/QuScope.git
cd QuScope
pip install -e ".[all]"

IBM Quantum access (optional — for real hardware)

export IBMQ_TOKEN="YOUR_API_TOKEN"

🗂 Repository Structure

quantum_algo_microscopy/
├── src/quscope/
│   ├── quantum_ctem/                        # Core quantum TEM modules
│   │   ├── quantum_ctem_circuit.py          # CTEM WPOA: QFT + CTF DiagonalGate
│   │   ├── quantum_multislice_circuit.py    # CTEM multislice: Fresnel + QFT
│   │   ├── quantum_stem.py                  # STEM WPOA (HAADF/ADF/ABF/BF/iDPC)
│   │   ├── quantum_stem_multislice.py       # STEM multislice
│   │   ├── quantum_encoding.py              # Amplitude encoding utilities
│   │   ├── quantum_simulation.py            # High-level simulation runner
│   │   ├── quantum_wave_function.py         # Wavefunction helper
│   │   ├── quantum_tomography.py            # Quantum state tomography
│   │   ├── ctf_calculator.py                # CTF + aberration function
│   │   ├── hamiltonian.py                   # Full TEM Hamiltonian
│   │   ├── momentum_space.py                # Reciprocal-space utilities
│   │   ├── classical_integration.py         # abTEM / Kirkland bridge
│   │   ├── classical_validation.py          # Classical reference implementations
│   │   ├── circuit_optimization.py          # Gate cancellation & transpilation
│   │   ├── performance_benchmarking.py      # Benchmark suite
│   │   ├── materials/                       # MoS₂, Graphene structure factors
│   │   ├── mos2_workflow/                   # End-to-end MoS₂ orchestration
│   │   ├── workflows/                       # Reusable workflow base classes
│   │   └── backends/                        # IBM Quantum / Aer backend wrappers
│   ├── ctem/                                # Classical CTEM (reference)
│   ├── simulations/                         # Shared simulation utilities
│   ├── utils/                               # Constants, Kirkland parameters
│   └── quantum_backend.py                   # IBM Quantum session manager
├── notebooks/                               # Executable documentation
├── pyproject.toml
└── docs/                                    # Sphinx documentation source

💡 Usage Examples

1. Quantum CTEM (bright-field imaging, WPOA)

from quscope.quantum_ctem import QuantumCTEMCircuit, QuantumCTEMParameters
import numpy as np

params = QuantumCTEMParameters(
    acceleration_voltage=200e3,
    grid_size=16,
    pixel_size=0.25,
    defocus=-659.7,
    cs=1.3,
)
result = QuantumCTEMCircuit(params).simulate(np.random.rand(16, 16) * 50)
# result keys: circuit, psi_image, intensity, metrics, parameters

2. Quantum CTEM Multislice

from quscope.quantum_ctem import (
    QuantumMultisliceCircuit,
    QuantumMultisliceParameters,
    QuantumClassicalMultisliceValidator,
)

params = QuantumMultisliceParameters(
    acceleration_voltage=200e3,
    grid_size=8,
    pixel_size=0.5,
    defocus=-500.0,
    cs=1.3,
    slice_thickness=2.0,   # Å per slice
)
potentials = [np.random.rand(8, 8) * 30 for _ in range(4)]   # 4-slice specimen
result = QuantumMultisliceCircuit(params).simulate(potentials)

# Validate against the classical multislice reference
cmp = QuantumClassicalMultisliceValidator(params).compare(potentials)
print(f"fidelity: {cmp['fidelity']:.6f}")   # → 1.000000

3. Quantum STEM (single-slice WPOA)

from quscope.quantum_ctem import run_stem, STEMDetectors
import numpy as np

N, px = 16, 0.12                     # Nyquist must exceed detector angles:
V = np.random.rand(N, N) * 100       # k_max = 1/(2·px) vs θ/λ

result = run_stem(
    V, pixel_size=px, voltage=200e3,
    convergence_mrad=20.0,
    detectors=STEMDetectors(),       # default angular ranges
    scan_step_px=1,
)
# result["HAADF"], result["ADF"], result["ABF"], result["BF"], result["iDPC"]

4. Quantum STEM Multislice

from quscope.quantum_ctem import run_stem_multislice

result = run_stem_multislice(
    V, pixel_size=px, voltage=200e3,
    n_slices=4, slice_thickness=6.5,   # or pass a (n_slices, N, N) array
    convergence_mrad=20.0,
)
# Same detector channels as run_stem; per-position quantum multislice circuit

✅ Validated Results

Every quantum pipeline is validated against a classical twin implementation:

Check	Result
Relativistic wavelength vs literature (100/200/300 kV)	exact (0.037014 / 0.025079 / 0.019687 Å)
Interaction constant σ vs literature	exact (e.g. 0.72884×10⁻³ rad V⁻¹Å⁻¹ at 200 kV)
CTF χ(k) and Fresnel propagator vs Kirkland closed forms	machine precision
Quantum vs classical multislice exit wave	fidelity 1.000000
STEM multislice single-slice limit vs `run_stem`	correlation 1.0000

All simulations run on Qiskit Statevector (exact) and are ready for transpilation to IBM hardware.

📓 Notebooks

Notebook	Description
01_getting_started	Package overview, CTEM basics, Scherzer defocus
02_quantum_ctem_advanced	Advanced CTEM: aberrations, CTF envelopes
03_material_workflows	MoS₂ and Graphene end-to-end workflows
05_fully_quantum_ctem	Quantum circuit CTEM showcase (pre-executed)
06_quantum_ctf_envelope	CTF envelope & damping functions
07_si3n4_quantum_multislice	Si₃N₄ multislice quantum simulation
10_quantum_ctem	Quantum circuit CTEM demonstration — WPOA & multislice
11_quantum_stem	Quantum circuit STEM demonstration — WPOA & multislice

⚙️ Circuit Architectures

CTEM (WPOA)

|0⟩⊗n ─[H⊗n]─[DiagGate(exp(iσV))]─[QFT]─[DiagGate(exp(iχ))]─[QFT†]─ |ψ_image⟩
              phase grating           k-sp  lens CTF              image

Multislice (Fresnel propagation)

|0⟩⊗n ─[H⊗n]─( [PhaseGrating(V_j)] ─ [QFT] ─ [FresnelProp(dz)] ─ [QFT†] )×N_slices─ |ψ⟩

STEM (per probe position)

|probe(r_s)⟩ ─( [PhaseGrating(V_j)] ─ [QFT] ─ [FresnelProp(dz)] ─ [QFT†] )×N_slices─ → detector integrals

📋 API Reference

from quscope.quantum_ctem import (
    # CTEM (WPOA)
    QuantumCTEMCircuit, QuantumCTEMParameters, QuantumClassicalValidator,
    # CTEM multislice
    QuantumMultisliceCircuit, QuantumMultisliceParameters,
    FresnelPropagatorCircuit, QuantumClassicalMultisliceValidator,
    # STEM
    STEMDetectors, run_stem,
    # STEM multislice
    run_stem_multislice, build_probe_circuit, fresnel_propagator_phase,
    # CTF
    CTFCalculator,
    # Hamiltonian
    TEMHamiltonian,
)

Full Sphinx documentation: quscope.readthedocs.io

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/my-feature)
Commit with descriptive messages
Ensure pytest passes and coverage remains ≥ 80 %
Open a Pull Request to main

📄 License

MIT License — see LICENSE for details.

📜 Citation

If you use QuScope in your research, please cite the companion paper:

@article{lam2026quantum,
  title     = {{Quantum Algorithm Framework for Phase-Contrast Transmission
               Electron Microscopy Image Simulation}},
  author    = {Lam, Sean D. and dos Reis, Roberto},
  journal   = {arXiv preprint},
  volume    = {arXiv:2602.13438},
  year      = {2026},
  url       = {https://arxiv.org/abs/2602.13438},
  doi       = {10.48550/arXiv.2602.13438}
}

QuScope v0.2.0 Documentation

🔬 Key Features

🚀 Quick Start

📚 Documentation Structure

🔗 Links

📖 Indices and Tables

🔬 QuScope v0.2.0: Quantum Algorithms for Electron Microscopy

🚀 Quick Start

✨ Available Modules (v0.2.0)

STEM Detector Channels

🛣 Roadmap

📦 Installation

From PyPI (recommended)

Development install

IBM Quantum access (optional — for real hardware)

🗂 Repository Structure

💡 Usage Examples

1. Quantum CTEM (bright-field imaging, WPOA)

2. Quantum CTEM Multislice

3. Quantum STEM (single-slice WPOA)

4. Quantum STEM Multislice

✅ Validated Results

📓 Notebooks

⚙️ Circuit Architectures

CTEM (WPOA)

Multislice (Fresnel propagation)

STEM (per probe position)

📋 API Reference

🤝 Contributing

📄 License

📜 Citation