cqlib.benchmark package

Benchmarking tools for cqlib.

cqlib.benchmark.bind_1q_target(int_templates: list[dict[str, Any]], target_qcis: str, *, placeholder: str = 'CUSTOM_TARGET_QCIS_LINE') → list[dict[str, Any]]

Replace 1Q interleaved placeholder with concrete target QCIS.

Input physical meaning: - target_qcis is your real pulse-level gate implementation to benchmark.

Supports: - “{q}” placeholder inside target_qcis.

cqlib.benchmark.bind_2q_target(int_templates: list[dict[str, Any]], target_qcis: str, *, placeholder: str = 'CUSTOM_TARGET_QCIS_LINE') → list[dict[str, Any]]

Replace 2Q interleaved placeholder with concrete target QCIS.

Supports: - “{q0}” and “{q1}” placeholders in target_qcis.

cqlib.benchmark.build_1q_templates(qubit: str, m_list: list[int], target: str | list[str], k: int, *, seed: int = 2026, placeholder: str = 'CUSTOM_TARGET_QCIS_LINE', max_tries: int = 200) → tuple[list[dict[str, Any]], list[dict[str, Any]], dict[str, Any]]

Build paired reference/interleaved 1Q IRB templates.

Inputs: - qubit: measured qubit id - m_list: Clifford lengths - target: symbolic target gate used inside interleaved branch - k: number of random paired sequences per m

Output: - tuple containing:

• list of reference templates,

• list of interleaved templates with placeholder,

• dictionary of generation metadata

Physical meaning: - ref and int share the same random Clifford base sequence for each (m, k). - only interleaved branch inserts target gate between Cliffords.

cqlib.benchmark.build_2q_templates(q0: str, q1: str, m_list: list[int], target: str, k: int, *, seed: int = 2026, placeholder: str = 'CUSTOM_TARGET_QCIS_LINE', max_tries: int = 200) → tuple[list[dict[str, Any]], list[dict[str, Any]], dict[str, Any]]

Build paired reference/interleaved 2Q IRB templates.

Inputs: - q0, q1: measured qubit pair - m_list: Clifford lengths - target: “CZ” or “CNOT” - k: number of random paired sequences per m

Output: - tuple containing:

• list of reference templates,

• list of interleaved templates with placeholder,

• dictionary of generation metadata

cqlib.benchmark.estimate_1q_irb(ref_branch: dict[str, Any], int_branch: dict[str, Any], *, is_print: bool = False) → dict[str, Any]

Estimate 1Q target gate fidelity from branch fits.

Theory: - p_target = p_int / p_ref - F_1q = (1 + p_target) / 2

Optional: - is_print=True prints compact ref/int fit summary and target fidelity.

cqlib.benchmark.estimate_2q_irb(ref_branch: dict[str, Any], int_branch: dict[str, Any], *, is_print: bool = False) → dict[str, Any]

Estimate 2Q target gate fidelity from branch fits.

Theory: - p_target = p_int / p_ref - F_2q = (1 + 3*p_target) / 4

Optional: - is_print=True prints compact ref/int fit summary and target fidelity.

cqlib.benchmark.fit_1q_branch(results: list[dict[str, Any]], m_list: list[int], *, group: str, sigma_floor: float = 0.001, is_show: bool = False, title: str | None = None) → dict[str, Any]

Fit one 1Q branch (reference or interleaved).

Output fields: - m_data, mean, sem - fit: {A, p, B, p_std, r2}

cqlib.benchmark.fit_1q_irb(results: list[dict[str, Any]], m_list: list[int], *, sigma_floor: float = 0.001, is_show: bool = False, qubit: str = 'Q0', target_name: str = 'CUSTOM') → dict[str, Any]

Full 1Q IRB fit: fit ref/int branches + estimate target fidelity.

cqlib.benchmark.fit_2q_branch(results: list[dict[str, Any]], m_list: list[int], *, group: str, sigma_floor: float = 0.001, is_show: bool = False, title: str | None = None) → dict[str, Any]

Fit one 2Q branch (reference or interleaved).

cqlib.benchmark.fit_2q_irb(results: list[dict[str, Any]], m_list: list[int], *, sigma_floor: float = 0.001, is_show: bool = False, q0: str = 'Q0', q1: str = 'Q1', target_name: str = 'CZ') → dict[str, Any]

Full 2Q IRB fit: fit ref/int branches + estimate target fidelity.

cqlib.benchmark.native_1q(symbolic_seq: list[str]) → list[str]

Convert symbolic 1Q sequence to native pulse sequence.

cqlib.benchmark.plot_irb(ref_branch: dict[str, Any], int_branch: dict[str, Any], *, title: str = 'Paired IRB Fit', ylabel: str = 'Survival probability') → None

Plot reference/interleaved branches on one figure.

Inputs: - ref_branch: output of fit_1q_branch or fit_2q_branch for group=’ref’ - int_branch: output of fit_1q_branch or fit_2q_branch for group=’int’ - title: figure title - ylabel: y-axis label (e.g. Survival probability P(0) or P(00))

Physical meaning: - This plot compares decay of reference RB and interleaved RB under the same

sequence lengths m, which is the direct visual basis of IRB analysis.

cqlib.benchmark.print_1q(summary: dict[str, Any]) → None

Print compact 1Q IRB fit summary.

cqlib.benchmark.print_2q(summary: dict[str, Any]) → None

Print compact 2Q IRB fit summary.

cqlib.benchmark.qcis_1q(qubit: str, gate: str | list[str]) → str

Return QCIS lines of a symbolic 1Q gate.

Output physical meaning: - This string is the pulse-level implementation used as interleaved target.

cqlib.benchmark.qcis_2q(q0: str, q1: str, target: str) → str

Return default QCIS implementation of 2Q target gate (CZ or CNOT).

cqlib.benchmark.run_1q_batch(circuits: list[dict[str, Any]], *, platform: Any, num_shots: int = 100, max_wait_time: int = 600, exp_prefix: str = '1qrb', print_every: int = 20) → dict[str, Any]

Run executable 1Q circuits (ref-only, int-only, or mixed).

cqlib.benchmark.run_1q_irb(ref_circuits: list[dict[str, Any]], int_templates: list[dict[str, Any]], target_qcis: str, *, platform: Any, num_shots: int = 100, max_wait_time: int = 600, exp_prefix: str = '1qirb', print_every: int = 20, placeholder: str = 'CUSTOM_TARGET_QCIS_LINE') → dict[str, Any]

Convenience wrapper: bind target into interleaved templates and run all 1Q circuits.

cqlib.benchmark.run_2q_batch(circuits: list[dict[str, Any]], *, platform: Any, num_shots: int = 100, max_wait_time: int = 600, exp_prefix: str = '2qrb', print_every: int = 20) → dict[str, Any]

Run executable 2Q circuits (ref-only, int-only, or mixed).

cqlib.benchmark.run_2q_irb(ref_circuits: list[dict[str, Any]], int_templates: list[dict[str, Any]], target_qcis: str, *, platform: Any, num_shots: int = 100, max_wait_time: int = 600, exp_prefix: str = '2qirb', print_every: int = 20, placeholder: str = 'CUSTOM_TARGET_QCIS_LINE') → dict[str, Any]

Convenience wrapper: bind target into interleaved templates and run all 2Q circuits.

cqlib.benchmark.unitary_1q(gate: str | list[str]) → ndarray

Return 2x2 unitary of a symbolic 1Q gate.

Input physical meaning: - gate can be one symbolic gate (e.g. “H”) or a symbolic gate list.