/**
 * @mainpage Maestro — Unified Quantum Circuit Simulation
 *
 * @tableofcontents
 *
 * @section intro Introduction
 *
 * **Maestro** is a high-performance C++ library that provides a unified
 * interface and intelligent orchestration layer for quantum circuit simulation.
 * It automates the complexity of selecting and configuring simulators, enabling
 * researchers and developers to execute quantum circuits efficiently across
 * CPUs, GPUs, and distributed HPC environments — without manual tuning.
 *
 * - **Version:** 0.1.0
 * - **License:** GPL-3.0
 * - **Organisation:** [Qoro Quantum](https://qoroquantum.de)
 *
 * ---
 *
 * @section features Key Features
 *
 * | Feature | Description |
 * |---------|-------------|
 * | **Unified Abstraction** | Write your circuit once (Qiskit / OpenQASM) and Maestro compiles it to the native format of the target backend |
 * | **Prediction Engine** | Automatically analyses circuit features (gate density, entanglement, locality) to predict and select the fastest backend |
 * | **High-Performance** | Multi-threading, multi-processing, and optimised state sampling to maximise throughput |
 * | **GPU Acceleration** | Integrated NVIDIA cuStateVec, custom MPS, tensor network, stabiliser, and Pauli propagator GPU kernels |
 * | **Distributed QC** | P-block composite simulation to break the memory ceiling of monolithic simulators |
 * | **Extensible** | New backends can be added by implementing a single C++ interface |
 * | **Python Bindings** | High-performance nanobind-based Python API |
 *
 * ---
 *
 * @section arch Architecture Overview
 *
 * @verbatim
 *  ┌─────────────────────────────────────────────────────────────────┐
 *  │                        User Application                        │
 *  │               (C++ API  ·  Python bindings  ·  CLI)            │
 *  ├─────────────────────────────────────────────────────────────────┤
 *  │                                                                 │
 *  │   ┌──────────┐    ┌──────────────┐    ┌───────────────────┐    │
 *  │   │  QASM /  │───▶│   Circuit    │───▶│   Prediction      │    │
 *  │   │  Qiskit  │    │   IR         │    │   Engine           │    │
 *  │   └──────────┘    └──────────────┘    └───────┬───────────┘    │
 *  │                                               │                 │
 *  │                        ┌──────────────────────┘                 │
 *  │                        ▼                                        │
 *  │   ┌────────────────────────────────────────────────────────┐   │
 *  │   │              Simulation Backends                        │   │
 *  │   │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │   │
 *  │   │  │   CPU    │ │   GPU    │ │  Tensor  │ │Composite │  │   │
 *  │   │  │  SV/MPS  │ │  SV/MPS  │ │  %Network │ │ (p-block)│  │   │
 *  │   │  └──────────┘ └──────────┘ └──────────┘ └──────────┘  │   │
 *  │   └────────────────────────────────────────────────────────┘   │
 *  │                                                                 │
 *  │   ┌──────────┐    ┌──────────┐    ┌──────────┐                 │
 *  │   │ Scheduler│    │ %Network  │    │Estimators│                 │
 *  │   │          │    │  (DQC)   │    │          │                 │
 *  │   └──────────┘    └──────────┘    └──────────┘                 │
 *  └─────────────────────────────────────────────────────────────────┘
 * @endverbatim
 *
 * ---
 *
 * @section modules API Modules
 *
 * The documentation is organised into the following thematic modules.
 * Click on a module name to browse its classes, functions, and detailed
 * documentation.
 *
 * | Module | Description |
 * |--------|-------------|
 * | @ref core | Core types, orchestration entry point, and library interface |
 * | @ref circuits | Quantum circuit IR — gates, operations, measurements |
 * | @ref simulators | Simulator interfaces and all backend implementations |
 * | @ref network | Distributed quantum computing — hosts, controllers, topology |
 * | @ref tensor_networks | Tensor network simulation and contraction strategies |
 * | @ref schedulers | Job scheduling and parallel execution |
 * | @ref estimators | Runtime estimation and automatic backend selection |
 * | @ref qasm | OpenQASM 2.0 parsing and serialisation |
 * | @ref utils | Thread pool, tensors, logging, and other utilities |
 * | @ref python | High-performance Python bindings |
 *
 * ---
 *
 * @section quickstart Getting Started
 *
 * @subsection build_sec Building from Source
 *
 * @code{.sh}
 * git clone https://github.com/QoroQuantum/maestro.git
 * cd maestro
 * chmod +x build.sh
 * ./build.sh
 * @endcode
 *
 * For detailed build options (GPU support, optional dependencies, etc.),
 * see the @ref md_INSTALL "Installation Guide".
 *
 * @subsection cpp_example C++ Example
 *
 * @code{.cpp}
 * #include "maestrolib/Interface.h"
 *
 * int main() {
 *     // Define a simple Bell-state circuit in OpenQASM
 *     std::string qasm = R"(
 *         OPENQASM 2.0;
 *         include "qelib1.inc";
 *         qreg q[2];
 *         creg c[2];
 *         h q[0];
 *         cx q[0], q[1];
 *         measure q -> c;
 *     )";
 *
 *     // Let Maestro choose the best backend and execute
 *     MaestroLibrary lib;
 *     lib.LoadCircuitFromQasm(qasm);
 *     auto results = lib.Execute(1024);
 *     // results now contains measurement counts
 * }
 * @endcode
 *
 * @subsection py_example Python Example
 *
 * @code{.py}
 * import maestro
 *
 * qasm = """
 * OPENQASM 2.0;
 * include "qelib1.inc";
 * qreg q[2];
 * h q[0];
 * cx q[0], q[1];
 * """
 *
 * result = maestro.simple_execute(qasm, shots=1024)
 * print(f"Counts: {result['counts']}")
 * @endcode
 *
 * For a comprehensive walkthrough, see the @ref md_TUTORIAL "Tutorial".
 *
 * ---
 *
 * @section backends Simulation Backends
 *
 * Maestro integrates or wraps the following simulation technologies:
 *
 * | Category | Technology | Notes |
 * |----------|------------|-------|
 * | CPU Statevector | QCSim, Qiskit Aer | Full state-vector simulation |
 * | CPU MPS | QCSim | Matrix Product State with configurable bond dimension |
 * | GPU Statevector | NVIDIA cuStateVec | Via dynamic GPU library loading |
 * | GPU MPS | Custom CUDA | Custom GPU MPS implementation |
 * | GPU Tensor %Network | Custom CUDA | Tensor network simulation on GPU |
 * | Stabiliser / Clifford | Custom CUDA | Efficient Clifford-only simulation |
 * | Pauli Propagator | Custom CUDA | Pauli propagation simulation |
 * | QuEST | QuEST library | Alternative CPU simulator |
 * | Composite | p-block | Distributed state across sub-simulators |
 *
 * Each backend is accessed through a C++ adapter implementing the
 * @ref Simulators::ISimulator interface.
 *
 * ---
 *
 * @section auto_backend Automatic Backend Selection
 *
 * Maestro's prediction engine:
 * 1. Extracts structural features from the circuit (gate density, entanglement
 *    locality, circuit width/depth)
 * 2. Uses a regression model trained on benchmark data
 * 3. Estimates relative runtimes across all available backends
 * 4. Selects the backend expected to be fastest on the current hardware
 *
 * The model normalises performance features to reduce hardware dependence
 * and can be recalibrated at installation time.
 *
 * @sa @ref estimators
 *
 * ---
 *
 * @section additional Additional Resources
 *
 * | Page | Description |
 * |------|-------------|
 * | @ref md_INSTALL "Installation" | Build instructions and optional dependency setup |
 * | @ref md_TUTORIAL "Tutorial" | Step-by-step API usage guide |
 * | @ref md_CONTRIBUTING "Contributing" | How to contribute to Maestro |
 * | @ref md_CODE__OF__CONDUCT "Code of Conduct" | Community guidelines |
 *
 * ---
 *
 * @section citation Citation
 *
 * If you use Maestro in your research, please cite:
 *
 * @code{.bib}
 * @article{bertomeu2025maestro,
 *   title   = {Maestro: Intelligent Execution for Quantum Circuit Simulation},
 *   author  = {Bertomeu, Oriol and Ghayas, Hamzah and Roman, Adrian and DiAdamo, Stephen},
 *   organization = {Qoro Quantum},
 *   year    = {2025}
 * }
 * @endcode
 *
 * ---
 *
 * @section license License
 *
 * This project is licensed under the **GNU General Public License v3.0**.
 * See the `LICENSE` file for the full text.
 */
