walkthrough.md

lindblad Implementation Walkthrough

Purpose

This document provides a practical orientation to the current implementation. It is intended for developers who want to understand how the framework is organized and where to make targeted changes.

End-to-End Flow

A typical execution path follows this sequence:

1. Construct a QuantumCircuit.
2. Optionally bind symbolic parameters.
3. Optionally run transpiler passes.
4. Execute with simulator backend or primitive.
5. Consume outputs in algorithms or application code.

Main Subsystems

Core representation

• include/lindblad/circuit.hpp, src/circuit.cpp
• include/lindblad/dag.hpp, src/dag.cpp

These files define circuit instructions, fluent construction APIs, and DAG transformations used by compilation flows.

Simulation

• include/lindblad/simulators/*.hpp
• src/simulators/*.cpp

Statevector, density matrix, Clifford, and MPS simulators each provide specialized execution behavior.

Noise and quantum information

• include/lindblad/noise.hpp, src/noise/*.cpp
• include/lindblad/operators.hpp, src/quantum_info/*.cpp

These modules model channels/noise and provide operator algebra and metrics used by primitives and algorithms.

Transpiler

• include/lindblad/transpiler.hpp
• src/transpiler/**/*.cpp

Layout, routing, basis translation, and local optimization passes are implemented here.

Primitives and algorithms

• include/lindblad/primitives.hpp, src/primitives/*.cpp
• include/lindblad/algorithms.hpp, src/algorithms/*.cpp

Primitives (Estimator, Sampler) provide reusable execution interfaces. Algorithms build on primitives.

Integration surfaces

• src/backends/local_backend.cpp
• bindings/python_bindings.cpp
• src/qasm/*.cpp

These files expose runtime selection behavior, Python interoperability, and QASM import/export pathways.

Validation and Performance

• Unit tests: tests/
• Benchmarks: benchmarks/

Use tests for correctness checks and benchmarks for performance regressions or optimizations.

Related Documentation

• README.md
• docs/Architecture.md
• docs/BuildAndTest.md
• docs/APIOverview.md
• docs/DevelopmentGuide.md
• docs/algorithms/ — one page per algorithm family (QPE, QFT, VQE, QAOA, Grover, BV, Simon, etc.)
• docs/api/ — method and class deep-dives (circuit, gates, simulators, backends, noise, transpiler, etc.)