prism-q 0.35.0

//! PRISM-Q, a fast Rust quantum circuit simulator.
//!
//! OpenQASM 3.0 input, nine CPU backends selected at dispatch, AVX2 SIMD kernels, an
//! optional CUDA path, an optional MPI path, QEC tooling, and Python bindings.
//!
//! # Quick start
//!
//! ```
//! use prism_q::run_qasm;
//!
//! let qasm = r#"
//!     OPENQASM 3.0;
//!     include "stdgates.inc";
//!     qubit[2] q;
//!     bit[2] c;
//!     h q[0];
//!     cx q[0], q[1];
//! "#;
//!
//! let result = run_qasm(qasm, 42).expect("parse/sim failed");
//! let probs = result.probabilities.expect("no probabilities").to_vec();
//! // Bell state: ~50% |00>, ~50% |11>
//! assert!((probs[0] - 0.5).abs() < 1e-10);
//! assert!((probs[3] - 0.5).abs() < 1e-10);
//! ```
//!
//! # Input model
//!
//! [`run_qasm`] takes OpenQASM 3.0 source; [`circuit::openqasm`] lists the supported
//! subset.
//!
//! # Backends
//!
//! - [`StatevectorBackend`]: full state-vector simulation
//! - [`StabilizerBackend`]: Clifford-only O(n^2) simulation
//! - [`SparseBackend`]: sparse state-vector O(k) simulation
//! - [`MpsBackend`]: Matrix Product State O(n * chi^2) simulation
//! - [`ProductStateBackend`]: per-qubit O(n) simulation for non-entangling circuits
//! - [`TensorNetworkBackend`]: deferred contraction for low-treewidth circuits
//! - [`FactoredBackend`]: dynamic split-state simulation for sparse-entanglement circuits
//! - [`FactoredStabilizerBackend`]: per-group tableaux for large sparse-entanglement Clifford circuits
//! - [`backend::density_matrix::DensityMatrixBackend`]: 4^n density matrix for exact channel semantics
//! - `DistributedStatevectorBackend`: statevector sharded across ranks (`distributed` feature)
//!
//! # Native QEC
//!
//! Measurement-record QEC programs use [`QecProgram`] or [`parse_qec_program`].
//! [`run_qec_program`] executes supported Clifford QEC programs through packed
//! compiled sampling with Pauli-noise annotations. [`run_qec_program_reference`]
//! runs small correctness checks through the reference path.

#![cfg_attr(docsrs, feature(doc_cfg))]

pub mod backend;
pub mod circuit;
pub mod circuits;
#[cfg(feature = "distributed")]
pub mod distributed;
mod env_knobs;
pub mod error;
pub mod gates;
#[cfg(feature = "gpu")]
pub mod gpu;
mod hash;
pub mod qec;
pub mod sim;
#[cfg(feature = "parallel")]
pub mod threading;

pub use backend::density_matrix::DensityMatrixBackend;
#[cfg(feature = "distributed")]
pub use backend::distributed_statevector::DistributedStatevectorBackend;
pub use backend::factored::FactoredBackend;
pub use backend::factored_stabilizer::FactoredStabilizerBackend;
pub use backend::mps::MpsBackend;
pub use backend::product::ProductStateBackend;
pub use backend::sparse::SparseBackend;
pub use backend::stabilizer::StabilizerBackend;
pub use backend::statevector::StatevectorBackend;
pub use backend::tensornetwork::TensorNetworkBackend;
pub use circuit::builder::CircuitBuilder;
pub use circuit::dynamic::{DynamicProgram, DynamicProgramBuilder};
pub use circuit::{
    Circuit, ClassicalCondition, Instruction, ParamLink, Parameters, PreparedCircuit, SaveRecord,
    SaveSpec, SavedValue, SvgOptions, TextOptions,
};
#[cfg(feature = "distributed-mpi")]
pub use distributed::MpiComm;
#[cfg(feature = "distributed")]
pub use distributed::{DistributedContext, RankComm, SerialComm};
pub use error::{PrismError, ResourceKind, ResourceLimit, Result};
pub use gates::{
    BatchPhaseData, Gate, GeneratorKind, McuData, Multi2qData, MultiFusedData, UnitaryData,
};
pub use qec::{
    BpMethod, BpOsdDecoder, BpOsdOptions, DetectorErrorModel, ErrorMechanism, MatchingDecoder,
    OsdMethod, QecBasis, QecCircuitNoise, QecCompiledRows, QecMeasurementRow, QecNoise,
    QecObservableEstimate, QecObservableReroute, QecOp, QecOptions, QecPauli, QecProgram,
    QecRecordRef, QecSampleResult, QecTStrategy, UnionFindDecoder, compile_qec_program_rows,
    parse_qec_program, run_qec_program, run_qec_program_reference, run_qec_program_spd_rerouted,
    run_qec_program_with_strategy,
};
#[cfg(feature = "bench-internal")]
pub use qec::{QecProfiledCounts, QecProfiledSampler, compile_qec_profiled_sampler};
pub use sim::calibration::{DeviceCalibration, GateCalibration, GateTimes, QubitCalibration};
pub use sim::compiled::{
    CompiledDetectorSampler, CompiledSampler, CorrelatorAccumulator, DetectorSampleBatch,
    HistogramAccumulator, MarginalsAccumulator, NullAccumulator, PackedShots, ParityStats,
    PauliExpectationAccumulator, ShotAccumulator, ShotLayout, compile_detector_sampler,
    compile_forward, compile_measurements, run_shots_compiled,
};
pub use sim::gradient::{
    ExpectationGradient, run_expectation_gradient, run_expectation_gradient_shift,
};
pub use sim::homological::{ErrorChainComplex, noisy_marginals_analytical};
pub use sim::noise::{
    DriftDistribution, GateFilter, NoiseBuilder, NoiseChannel, NoiseEvent, NoiseModel,
    NoisyCompiledSampler, ReadoutError, compile_noisy, density_matrix_expectation_values,
    run_shots_noisy,
};
pub use sim::stabilizer_rank::{
    StabRankResult, run_stabilizer_rank, run_stabilizer_rank_approx, stabilizer_inner_product,
    stabilizer_overlap_sq,
};
pub use sim::unified_pauli::{
    PauliAxis, PauliTerm, SpdObservableResult, SpdResult, SpdTruncation, SppObservableResult,
    SppResult, inverse_light_cone, run_spd, run_spd_observable, run_spd_observable_budgeted,
    run_spd_observable_light_cone, run_spd_with, run_spp, run_spp_observable,
};
pub use sim::{
    BackendKind, BondReport, CountsResult, Engine, EntropyResult, Exactness, ExpectationResult,
    FactoredBlock, MarginalsResult, ObservableExpectation, ObservableVariance, OverlapResult,
    PauliObservable, Placement, Probabilities, ReducedDensityMatrix, ResolvedBackend, RunMetadata,
    RunOutcome, Seeded, ShotsResult, Simulate, SimulateProgram, Unseeded, bitstring,
    run_expectation_values, run_observable_expectation, run_on, run_on_state, run_qasm, simulate,
    simulate_program,
};
#[cfg(feature = "parallel")]
pub use threading::ThreadPool;

#[cfg(feature = "gpu")]
pub use sim::compiled::{DevicePackedShots, run_shots_compiled_with_gpu};

// Runs the Rust code blocks of the user guides and tutorials under `cargo test --doc`. Their
// Python blocks are executed by the bindings' test suite instead. mdbook-admonish blocks
// carry `title="..."`, which rustdoc reads as a malformed attribute on a block it never runs.
#[cfg(doctest)]
#[allow(rustdoc::invalid_codeblock_attributes)]
mod guide_examples {
    #[doc = include_str!("../docs/guides/backends.md")]
    struct Backends;
    #[doc = include_str!("../docs/guides/capabilities.md")]
    struct Capabilities;
    #[doc = include_str!("../docs/guides/clifford-t.md")]
    struct CliffordT;
    #[doc = include_str!("../docs/guides/drawing.md")]
    struct Drawing;
    #[doc = include_str!("../docs/guides/gpu.md")]
    struct Gpu;
    #[doc = include_str!("../docs/guides/openqasm.md")]
    struct OpenQasm;
    #[doc = include_str!("../docs/guides/performance.md")]
    struct Performance;
    #[doc = include_str!("../docs/guides/qec.md")]
    struct Qec;
    #[doc = include_str!("../docs/tutorials/dynamic-circuits.md")]
    struct TutorialDynamicCircuits;
    #[doc = include_str!("../docs/tutorials/large-circuits.md")]
    struct TutorialLargeCircuits;
    #[doc = include_str!("../docs/tutorials/noisy-simulation.md")]
    struct TutorialNoisySimulation;
    #[doc = include_str!("../docs/tutorials/qec-memory.md")]
    struct TutorialQecMemory;
    #[doc = include_str!("../docs/tutorials/simulate-and-sample.md")]
    struct TutorialSimulateAndSample;
    #[doc = include_str!("../docs/tutorials/variational.md")]
    struct TutorialVariational;
}