qsimulator 0.7.0

A quantum circuit simulator with noise, density matrices, and OpenQASM 2 and 3 support
Documentation
//! A tiny line-based program format for describing circuits as text, so the
//! CLI can run a circuit without recompiling.
//!
//! One instruction per line. `#` starts a comment; blank lines are ignored.
//! The first instruction must be `qubits N`. Example:
//!
//! ```text
//! qubits 3
//! h 0
//! cnot 0 1
//! cnot 1 2      # GHZ state
//! sample 1000 42
//! ```
//!
//! Supported instructions: `qubits N`; single-qubit `id/h/x/y/z/s/t/sdg/tdg/sx/sxdg Q`;
//! rotations `rx/ry/rz THETA Q`, phase `p THETA Q`, and the general
//! `u2 PHI LAMBDA Q` / `u3 THETA PHI LAMBDA Q`; two-qubit `cnot/cy/cz/ch C T`,
//! `crz/cp THETA C T`, `cu3 THETA PHI LAMBDA C T`, and `swap A B`; three-qubit
//! `toffoli C1 C2 T` and `cswap C A B`; the open-ended multi-controlled
//! `mcx C... T` and `mcu3 THETA PHI LAMBDA C... T`; `measure Q`, which
//! collapses a qubit mid-circuit, `reset Q`, which forces it to |0>, and
//! `if VALUE INSTRUCTION`, which guards one instruction on the classical
//! register; the noise channels `depolarizing/bit_flip/phase_flip/
//! amplitude_damping/phase_damping P Q`; and a terminal
//! `sample SHOTS SEED`. An angle is an arithmetic expression over numbers and
//! `pi` — `0.7`, `pi`, `pi/2`, `-pi/4`, `2pi`, or `(pi/4 + 0.1)*2` — with the
//! operators `+ - * / ^`, parentheses, and `sin`/`cos`/`tan`/`exp`/`ln`/`sqrt`.

use crate::error::ParseError;
use crate::Circuit;

/// Largest register a program may declare, matching the OpenQASM importer.
/// Guards against a malformed huge `qubits N` aborting on allocation.
const MAX_QUBITS: usize = 30;

/// A parsed program: the built circuit plus an optional `sample` directive.
#[derive(Debug, Clone)]
pub struct Program {
    /// The circuit built from the program's gate instructions.
    pub circuit: Circuit,
    /// The `sample SHOTS SEED` directive, if the program had one.
    pub sample: Option<SampleSpec>,
}

/// Parameters from a `sample SHOTS SEED` directive.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct SampleSpec {
    /// Number of shots to sample.
    pub shots: usize,
    /// RNG seed, for reproducible sampling.
    pub seed: u64,
}

/// Parse a program from its textual form, or return a [`ParseError`] tagged
/// with the offending line number.
pub fn parse(src: &str) -> Result<Program, ParseError> {
    let mut circuit: Option<Circuit> = None;
    let mut n = 0usize;
    let mut sample: Option<SampleSpec> = None;

    for (lineno, raw) in src.lines().enumerate() {
        // Strip comments and surrounding whitespace.
        let line = raw.split('#').next().unwrap_or("").trim();
        if line.is_empty() {
            continue;
        }
        let toks: Vec<&str> = line.split_whitespace().collect();
        let cmd = toks[0];
        let at = |msg: String| ParseError::at_line(lineno + 1, msg);

        if cmd == "qubits" {
            if circuit.is_some() {
                return Err(at("`qubits` may only appear once".into()));
            }
            expect_arity(&toks, 2).map_err(&at)?;
            n = toks[1]
                .parse()
                .map_err(|_| at(format!("invalid qubit count `{}`", toks[1])))?;
            if n == 0 {
                return Err(at("qubit count must be >= 1".into()));
            }
            if n > MAX_QUBITS {
                return Err(at(format!(
                    "qubit count {n} exceeds the maximum of {MAX_QUBITS}"
                )));
            }
            circuit = Some(Circuit::new(n));
            continue;
        }

        let c = circuit
            .as_mut()
            .ok_or_else(|| at("first instruction must be `qubits N`".into()))?;

        match cmd {
            "sample" => {
                if sample.is_some() {
                    return Err(at("`sample` may only appear once".into()));
                }
                expect_arity(&toks, 3).map_err(&at)?;
                let shots = toks[1]
                    .parse()
                    .map_err(|_| at(format!("invalid shot count `{}`", toks[1])))?;
                let seed = toks[2]
                    .parse()
                    .map_err(|_| at(format!("invalid seed `{}`", toks[2])))?;
                sample = Some(SampleSpec { shots, seed });
            }
            _ => apply_instruction(c, &toks, n).map_err(&at)?,
        }
    }

    let circuit =
        circuit.ok_or_else(|| ParseError::new("program is empty (expected `qubits N`)"))?;
    Ok(Program { circuit, sample })
}

/// Apply one circuit instruction. Errors carry no line number; the caller adds
/// it. Split out from `parse` so a conditional can re-enter it for the
/// statement it guards.
fn apply_instruction(c: &mut Circuit, toks: &[&str], n: usize) -> Result<(), String> {
    let cmd = toks[0];
    match cmd {
        "id" | "h" | "x" | "y" | "z" | "s" | "t" | "sdg" | "tdg" | "sx" | "sxdg" => {
            expect_arity(toks, 2)?;
            let q = parse_qubit(toks, 1, n)?;
            match cmd {
                "id" => c.id(q),
                "h" => c.h(q),
                "x" => c.x(q),
                "y" => c.y(q),
                "z" => c.z(q),
                "s" => c.s(q),
                "t" => c.t(q),
                "sdg" => c.sdg(q),
                "sx" => c.sx(q),
                "sxdg" => c.sxdg(q),
                "tdg" => c.tdg(q),
                _ => unreachable!(),
            };
        }
        "rx" | "ry" | "rz" | "p" => {
            expect_arity(toks, 3)?;
            let theta = parse_angle(toks[1])?;
            let q = parse_qubit(toks, 2, n)?;
            match cmd {
                "rx" => c.rx(theta, q),
                "ry" => c.ry(theta, q),
                "rz" => c.rz(theta, q),
                "p" => c.p(theta, q),
                _ => unreachable!(),
            };
        }
        "u2" => {
            expect_arity(toks, 4)?;
            let phi = parse_angle(toks[1])?;
            let lambda = parse_angle(toks[2])?;
            let q = parse_qubit(toks, 3, n)?;
            c.u2(phi, lambda, q);
        }
        "u3" => {
            expect_arity(toks, 5)?;
            let theta = parse_angle(toks[1])?;
            let phi = parse_angle(toks[2])?;
            let lambda = parse_angle(toks[3])?;
            let q = parse_qubit(toks, 4, n)?;
            c.u3(theta, phi, lambda, q);
        }
        "cnot" | "cz" | "cy" | "ch" => {
            expect_arity(toks, 3)?;
            let ctrl = parse_qubit(toks, 1, n)?;
            let tgt = parse_qubit(toks, 2, n)?;
            if ctrl == tgt {
                return Err("control and target must differ".into());
            }
            match cmd {
                "cnot" => c.cnot(ctrl, tgt),
                "cy" => c.cy(ctrl, tgt),
                "ch" => c.ch(ctrl, tgt),
                _ => c.cz(ctrl, tgt),
            };
        }
        "cswap" => {
            expect_arity(toks, 4)?;
            let ctrl = parse_qubit(toks, 1, n)?;
            let a = parse_qubit(toks, 2, n)?;
            let b = parse_qubit(toks, 3, n)?;
            if ctrl == a || ctrl == b || a == b {
                return Err("cswap qubits must be distinct".into());
            }
            c.cswap(ctrl, a, b);
        }
        "crz" | "cp" => {
            expect_arity(toks, 4)?;
            let theta = parse_angle(toks[1])?;
            let ctrl = parse_qubit(toks, 2, n)?;
            let tgt = parse_qubit(toks, 3, n)?;
            if ctrl == tgt {
                return Err("control and target must differ".into());
            }
            match cmd {
                "crz" => c.crz(theta, ctrl, tgt),
                _ => c.cp(theta, ctrl, tgt),
            };
        }
        "cu3" => {
            expect_arity(toks, 6)?;
            let theta = parse_angle(toks[1])?;
            let phi = parse_angle(toks[2])?;
            let lambda = parse_angle(toks[3])?;
            let ctrl = parse_qubit(toks, 4, n)?;
            let tgt = parse_qubit(toks, 5, n)?;
            if ctrl == tgt {
                return Err("control and target must differ".into());
            }
            c.cu3(theta, phi, lambda, ctrl, tgt);
        }
        "swap" => {
            expect_arity(toks, 3)?;
            let a = parse_qubit(toks, 1, n)?;
            let b = parse_qubit(toks, 2, n)?;
            c.swap(a, b);
        }
        "toffoli" => {
            expect_arity(toks, 4)?;
            let c1 = parse_qubit(toks, 1, n)?;
            let c2 = parse_qubit(toks, 2, n)?;
            let tgt = parse_qubit(toks, 3, n)?;
            if c1 == tgt || c2 == tgt {
                return Err("control and target must differ".into());
            }
            c.toffoli(c1, c2, tgt);
        }
        // Multi-controlled gates: every token but the last is a control,
        // the last is the target, so the arity is open-ended.
        "mcx" => {
            let (controls, tgt) = parse_control_list(toks, 1, n)?;
            c.mcx(&controls, tgt);
        }
        "mcu3" => {
            let theta = parse_angle(toks.get(1).copied().unwrap_or(""))?;
            let phi = parse_angle(toks.get(2).copied().unwrap_or(""))?;
            let lambda = parse_angle(toks.get(3).copied().unwrap_or(""))?;
            let (controls, tgt) = parse_control_list(toks, 4, n)?;
            c.mcu(crate::gates::u3(theta, phi, lambda), &controls, tgt);
        }
        // Noise channels: a probability (or damping rate) and a qubit.
        "depolarizing" | "bit_flip" | "phase_flip" | "amplitude_damping" | "phase_damping" => {
            expect_arity(toks, 3)?;
            let p = parse_angle(toks[1])?;
            if !(0.0..=1.0).contains(&p) {
                return Err(format!("noise strength must be in 0..=1, got {p}"));
            }
            let q = parse_qubit(toks, 2, n)?;
            match cmd {
                "depolarizing" => c.depolarizing(p, q),
                "bit_flip" => c.bit_flip(p, q),
                "phase_flip" => c.phase_flip(p, q),
                "amplitude_damping" => c.amplitude_damping(p, q),
                _ => c.phase_damping(p, q),
            };
        }
        "measure" | "reset" => {
            expect_arity(toks, 2)?;
            let q = parse_qubit(toks, 1, n)?;
            if cmd == "measure" {
                c.measure(q);
            } else {
                c.reset(q);
            }
        }
        // `if VALUE INSTRUCTION ...` guards one instruction on the classical
        // register, the native spelling of OpenQASM's `if (c == VALUE)`.
        "if" => {
            if toks.len() < 3 {
                return Err("`if` expects a value then an instruction".to_string());
            }
            let value: u64 = toks[1]
                .parse()
                .map_err(|_| format!("invalid conditional value `{}`", toks[1]))?;
            let guarded = &toks[2..];
            if matches!(guarded[0], "measure" | "reset" | "if") {
                return Err(format!(
                    "only a gate may be conditional, not `{}`",
                    guarded[0]
                ));
            }
            // Build in isolation so operand errors surface before wrapping.
            let mut block = Circuit::new(n);
            apply_instruction(&mut block, guarded, n)?;
            c.if_classical_eq(value, |inner| inner.extend_from(&block));
        }
        other => return Err(format!("unknown instruction `{other}`")),
    }
    Ok(())
}

/// Require a line to have exactly `k` whitespace tokens.
fn expect_arity(toks: &[&str], k: usize) -> Result<(), String> {
    if toks.len() == k {
        Ok(())
    } else {
        Err(format!(
            "`{}` expects {} tokens, got {}",
            toks[0],
            k,
            toks.len()
        ))
    }
}

/// Parse the qubit list of a multi-controlled instruction: tokens from `start`
/// to the end, where the last is the target and the rest are controls.
///
/// Requires at least one control (use the plain gate for none) and rejects a
/// repeated qubit, which would mean controlling a gate on its own target.
fn parse_control_list(
    toks: &[&str],
    start: usize,
    n: usize,
) -> Result<(Vec<usize>, usize), String> {
    if toks.len() < start + 2 {
        return Err(format!(
            "`{}` expects at least {} tokens (one or more controls, then a target), got {}",
            toks[0],
            start + 2,
            toks.len()
        ));
    }
    let qubits: Vec<usize> = (start..toks.len())
        .map(|i| parse_qubit(toks, i, n))
        .collect::<Result<_, _>>()?;
    for (i, q) in qubits.iter().enumerate() {
        if qubits[..i].contains(q) {
            return Err(format!("qubit {q} is repeated; all must be distinct"));
        }
    }
    let (&target, controls) = qubits.split_last().expect("checked non-empty above");
    Ok((controls.to_vec(), target))
}

/// Parse token `idx` as a qubit index and bounds-check it against `n`.
fn parse_qubit(toks: &[&str], idx: usize, n: usize) -> Result<usize, String> {
    let s = toks
        .get(idx)
        .ok_or_else(|| "missing qubit argument".to_string())?;
    let q: usize = s.parse().map_err(|_| format!("invalid qubit `{s}`"))?;
    if q >= n {
        return Err(format!("qubit {q} out of range (0..{n})"));
    }
    Ok(q)
}

/// Parse an angle: an arithmetic expression over numbers and `pi`, such as
/// `0.7`, `pi`, `pi/2`, `-pi/4`, `2pi`, `2*pi`, or `pi/2 + 0.3`.
///
/// Shared with the OpenQASM importer, which uses the same angle syntax — see
/// [`crate::expr`] for the full grammar.
pub(crate) fn parse_angle(s: &str) -> Result<f64, String> {
    crate::expr::eval(s, &std::collections::HashMap::new())
}