intrico 2.1.1

High-performance Quantum Computing library to simulate quantum circuits with precision and power.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

//! # 🚀 Intrico
//!
//! ### High-performance quantum computing library for Rust
//! **Simulate quantum circuits with precision and speed**
//!

pub mod encoder;
pub mod library;
pub mod visualisations;

// Re-exports from intrico-core — users only need to depend on `intrico`
pub use intrico_core::{
    ClassicalRegister,
    Complex,
    ExecutionContext,
    ExecutionTime,
    GateKind,
    MeasurementResult,
    Operation,
    QuantumCircuit,
    QuantumGate,
    QuantumNode,
    QuantumState,
    SamplingResult,
};

pub use visualisations::plot_histogram;

/// Execute a circuit once, returning the statevector and classical register.
pub fn execute(circuit: &QuantumCircuit) -> MeasurementResult {
    use std::time::Instant;
    let start = Instant::now();
    let mut ctx = ExecutionContext::new(circuit.num_qubits(), circuit.classical_regs());
    ctx.run(circuit);
    let (statevector, classical_register) = ctx.into_inner();
    MeasurementResult {
        statevector,
        classical_register,
        shots: 1,
        execution_time: ExecutionTime::from_duration(start.elapsed()),
    }
}

/// Sample a circuit over `shots` executions, returning outcome counts.
pub fn sample(circuit: &QuantumCircuit, shots: usize) -> SamplingResult {
    use std::collections::HashMap;
    use std::time::Instant;
    use rand::RngExt;

    let start = Instant::now();
    let mut counts: HashMap<String, usize> = HashMap::new();
    let creg_size = circuit.classical_regs();

    if circuit.has_terminal_measurements_only() {
        // Optimised: run gates once, sample from the statevector probability distribution
        let mut ctx = ExecutionContext::new(circuit.num_qubits(), 0);
        ctx.run_gates_only(circuit);

        let probs: Vec<f64> = ctx
            .state()
            .statevector()
            .iter()
            .map(|a| a.norm_squared())
            .collect();

        let measurements: Vec<(usize, usize)> = circuit
            .nodes()
            .iter()
            .filter_map(|n| match &n.operation {
                Operation::Measure { qubit, classical_bit } => Some((*qubit, *classical_bit)),
                _ => None,
            })
            .collect();

        let dim = 1 << circuit.num_qubits();
        let mut rng = rand::rng();

        for _ in 0..shots {
            let r: f64 = rng.random();
            let mut cumulative = 0.0;
            let mut sampled_index = dim - 1;
            for (i, &p) in probs.iter().enumerate() {
                cumulative += p;
                if r < cumulative {
                    sampled_index = i;
                    break;
                }
            }

            let mut creg = ClassicalRegister::new(creg_size);
            for &(qubit, classical_bit) in &measurements {
                creg.set(classical_bit, ((sampled_index >> qubit) & 1) as u8);
            }
            *counts.entry(creg.bitstring()).or_insert(0) += 1;
        }
    } else {
        // Full re-execution each shot (required for mid-circuit measurement)
        for _ in 0..shots {
            let mut ctx = ExecutionContext::new(circuit.num_qubits(), creg_size);
            ctx.run(circuit);
            *counts
                .entry(ctx.classical_register().bitstring())
                .or_insert(0) += 1;
        }
    }

    SamplingResult {
        counts,
        shots,
        execution_time: ExecutionTime::from_duration(start.elapsed()),
    }
}