bilinear-quantum 1.0.0__py3-none-any.whl

bilinear_quantum/__init__.py

@@ -0,0 +1,44 @@
+"""Bilinear Quantum Learning and Hirota Quantum Bilinear Learning.
+
+The package separates exact mathematical reductions from empirical claims.
+Importing the top-level package does not import TensorFlow Quantum; backend
+modules load that relatively expensive dependency only when it is requested.
+"""
+
+from .core.bql import (
+    Calibration,
+    CalibrationParameters,
+    bql_exact_numpy,
+    calibration_parameters,
+    classical_bilinear,
+)
+from .core.factorization import (
+    BilinearFactorization,
+    factorize_bilinear_matrix,
+    projection_radii,
+    truncated_svd_error_bound,
+)
+from .core.hirota import (
+    exchange_parity_residual,
+    hirota_bilinear,
+    hirota_rank_channels,
+    required_jet_indices,
+)
+
+__all__ = [
+    "BilinearFactorization",
+    "Calibration",
+    "CalibrationParameters",
+    "bql_exact_numpy",
+    "calibration_parameters",
+    "classical_bilinear",
+    "exchange_parity_residual",
+    "factorize_bilinear_matrix",
+    "hirota_bilinear",
+    "hirota_rank_channels",
+    "projection_radii",
+    "required_jet_indices",
+    "truncated_svd_error_bound",
+]
+
+__version__ = "1.0.0"

bilinear_quantum/analysis/__init__.py

@@ -0,0 +1 @@
+"""Post-run statistical and claim-evidence audits."""

bilinear_quantum/analysis/audit.py

@@ -0,0 +1,351 @@
+"""Verify immutable evidence, run paired inference, and adjudicate claims."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from bilinear_quantum.statistics import holm_adjust, paired_comparison
+from bilinear_quantum.utils.artifacts import build_manifest, sha256_file, write_json_atomic
+
+EXPERIMENT_IDS = ("E1", "E2", "E3", "E4", "E4Q", "E5", "E6", "E7", "E8", "E9", "E10", "W0")
+
+
+def _read_json(path: Path):
+    with path.open(encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+def _verify_manifest(directory: Path) -> dict[str, object]:
+    manifest_path = directory / "manifest.json"
+    if not manifest_path.is_file():
+        raise FileNotFoundError(f"missing manifest: {manifest_path}")
+    manifest = _read_json(manifest_path)
+    checked = []
+    for record in manifest.get("files", []):
+        relative = Path(record["path"])
+        if relative.is_absolute() or ".." in relative.parts:
+            raise ValueError(f"unsafe manifest path in {manifest_path}: {relative}")
+        path = directory / relative
+        if not path.is_file():
+            raise FileNotFoundError(f"manifested file is missing: {path}")
+        actual_size, actual_hash = path.stat().st_size, sha256_file(path)
+        if actual_size != record["bytes"] or actual_hash != record["sha256"]:
+            raise ValueError(f"artifact integrity mismatch: {path}")
+        checked.append(relative.as_posix())
+    if not checked:
+        raise ValueError(f"empty evidence manifest: {manifest_path}")
+    return {"directory": directory.name, "files_verified": len(checked), "status": "pass"}
+
+
+def _load_experiment(root: Path, experiment: str) -> dict[str, object]:
+    directory = root / experiment
+    integrity = _verify_manifest(directory)
+    paths = {name: directory / name for name in ("results.csv", "run.json", "summary.json")}
+    missing = [str(path) for path in paths.values() if not path.is_file()]
+    if missing:
+        raise FileNotFoundError("missing mandatory result artifacts: " + ", ".join(missing))
+    return {
+        "frame": pd.read_csv(paths["results.csv"]),
+        "run": _read_json(paths["run.json"]),
+        "summary": _read_json(paths["summary.json"]),
+        "integrity": integrity,
+    }
+
+
+def _paired_from_frame(
+    frame: pd.DataFrame,
+    model_a: str,
+    model_b: str,
+    metric: str,
+    *,
+    higher_is_better: bool,
+    filters: dict[str, object] | None = None,
+) -> dict[str, object]:
+    selected = frame
+    for column, value in (filters or {}).items():
+        selected = selected[selected[column] == value]
+    pivot = selected.pivot_table(index="seed", columns="model", values=metric, aggfunc="mean")
+    if model_a not in pivot or model_b not in pivot:
+        raise ValueError(f"missing paired models {model_a}/{model_b} for {metric}")
+    pivot = pivot[[model_a, model_b]].dropna()
+    a, b = pivot[model_a].to_numpy(), pivot[model_b].to_numpy()
+    # Positive difference always means model A is better.
+    comparison = paired_comparison(a, b) if higher_is_better else paired_comparison(b, a)
+    return {
+        "model_a": model_a,
+        "model_b": model_b,
+        "metric": metric,
+        "higher_is_better": higher_is_better,
+        "filters": filters or {},
+        **comparison,
+        "model_a_mean": float(np.mean(a)),
+        "model_b_mean": float(np.mean(b)),
+    }
+
+
+def _superiority_gate(comparison: dict[str, object]) -> bool:
+    return bool(
+        comparison["mean_difference"] > 0
+        and comparison["ci95_low"] > 0
+        and comparison["holm_adjusted_p"] < 0.05
+        and comparison["fraction_positive"] >= 0.8
+    )
+
+
+def _online_quantum_value_decision(
+    *,
+    teacher_test_r2: float,
+    minimum_teacher_test_r2: float,
+    best_modest_fidelity: float,
+    fidelity_tolerance: float,
+) -> str:
+    """Adjudicate dequantization only after the teacher is predictively viable."""
+    if teacher_test_r2 < minimum_teacher_test_r2:
+        return "not_evaluable_teacher_below_predictive_skill_gate"
+    if best_modest_fidelity <= fidelity_tolerance:
+        return "weak_due_to_dequantization"
+    return "survives_tested_surrogates"
+
+
+def run(experiment_root: Path, gate_root: Path, output_directory: Path) -> None:
+    experiment_root, gate_root, output_directory = map(
+        Path, (experiment_root, gate_root, output_directory)
+    )
+    gate_integrity = _verify_manifest(gate_root)
+    gate_report = _read_json(gate_root / "gate_report.json")
+    if gate_report.get("status") != "pass":
+        raise RuntimeError("the mandatory mathematical/backend gate did not pass")
+
+    evidence = {
+        identifier: _load_experiment(experiment_root, identifier)
+        for identifier in EXPERIMENT_IDS
+    }
+    commits = {item["run"]["git_commit"] for item in evidence.values()}
+    profiles = {item["run"].get("profile") for item in evidence.values()}
+    registry_hashes = {item["run"]["registry_sha256"] for item in evidence.values()}
+    if profiles != {"full"}:
+        raise RuntimeError(f"claim audit accepts full-profile evidence only, found {profiles}")
+    if len(commits) != 1 or commits != {gate_report["git_commit"]}:
+        raise RuntimeError(
+            f"source provenance mismatch: experiments={sorted(commits)}, "
+            f"gate={gate_report['git_commit']}"
+        )
+    if len(registry_hashes) != 1:
+        raise RuntimeError(f"experiment registry hashes disagree: {sorted(registry_hashes)}")
+
+    frames = {identifier: item["frame"] for identifier, item in evidence.items()}
+    e2, e3, e4, e4q, e7, e8, e9, e10 = (
+        frames[identifier]
+        for identifier in ("E2", "E3", "E4", "E4Q", "E7", "E8", "E9", "E10")
+    )
+    comparisons = [
+        _paired_from_frame(
+            e2,
+            "quantum_hirota_core",
+            "ordinary_bilinear",
+            "rmse",
+            higher_is_better=False,
+            filters={"program": "anti_shortcut", "task": "TH", "domain": "iid"},
+        ),
+        _paired_from_frame(
+            e2,
+            "quantum_hirota_core",
+            "free_derivative",
+            "rmse",
+            higher_is_better=False,
+            filters={"program": "anti_shortcut", "task": "TH", "domain": "iid"},
+        ),
+        _paired_from_frame(
+            e3,
+            "operator_hirota",
+            "free_derivative",
+            "rmse",
+            higher_is_better=False,
+            filters={"task": "residual_regression", "domain": "ood_frequency"},
+        ),
+        _paired_from_frame(
+            e4,
+            "quantum_hirota_core_ps",
+            "quantum_bilinear_core",
+            "macro_f1",
+            higher_is_better=True,
+        ),
+        _paired_from_frame(
+            e4,
+            "quantum_hirota_core_ps",
+            "parameter_matched_mlp",
+            "macro_f1",
+            higher_is_better=True,
+        ),
+        _paired_from_frame(
+            e4q,
+            "structured_interact",
+            "no_entanglement",
+            "macro_f1",
+            higher_is_better=True,
+        ),
+        _paired_from_frame(
+            e4q,
+            "structured_interact",
+            "generic_pqc",
+            "macro_f1",
+            higher_is_better=True,
+        ),
+    ]
+    adjusted = holm_adjust([comparison["p_value"] for comparison in comparisons])
+    for comparison, adjusted_p in zip(comparisons, adjusted, strict=True):
+        comparison["holm_adjusted_p"] = adjusted_p
+
+    e2_th = e2[(e2.program == "anti_shortcut") & (e2.task == "TH") & (e2.domain == "iid")]
+    means_e2 = e2_th.groupby("model").rmse.mean()
+    e4_means = e4.groupby("model").macro_f1.mean()
+    e4q_means = e4q.groupby("model").macro_f1.mean()
+    modest = (
+        e10[e10.query_budget <= 256]
+        .groupby(["surrogate", "query_budget"], as_index=False)
+        .surrogate_fidelity_rmse.mean()
+    )
+    best_modest_row = modest.loc[modest.surrogate_fidelity_rmse.idxmin()]
+    best_modest_fidelity = float(best_modest_row.surrogate_fidelity_rmse)
+    teacher_scale = float(e10.groupby("seed").teacher_output_sd.first().mean())
+    teacher_test_r2 = float(e10.groupby("seed").teacher_test_r2.first().mean())
+    e10_summary = evidence["E10"]["summary"]
+    minimum_teacher_test_r2 = float(e10_summary["minimum_teacher_test_r2"])
+    fidelity_tolerance = max(
+        float(e10_summary["maximum_modest_query_fidelity_absolute"]),
+        float(e10_summary["maximum_modest_query_fidelity_fraction"]) * teacher_scale,
+    )
+    teacher_viable = bool(teacher_test_r2 >= minimum_teacher_test_r2)
+    symmetric = e8[e8.regime == "symmetric"].mean_parity_defect.mean()
+    asymmetric = e8[e8.regime == "asymmetric"].mean_parity_defect.mean()
+    c3_ordinary, _, _, c5_bilinear, c5_mlp, c4_local, c4_generic = comparisons
+    c3_competitive_free = bool(
+        means_e2["quantum_hirota_core"] <= 1.05 * means_e2["free_derivative"]
+    )
+    c4_supported = _superiority_gate(c4_local) and _superiority_gate(c4_generic)
+    c5_supported = _superiority_gate(c5_bilinear)
+    summaries = {identifier: item["summary"] for identifier, item in evidence.items()}
+    structural_pass = bool(
+        summaries["E1"]["oracle_bound_pass"]
+        and summaries["E3"]["symbolic_identity_pass"]
+        and summaries["E3"]["numeric_identity_pass"]
+        and summaries["E4"]["leakage_gate_pass"]
+        and summaries["E8"]["clean_parity_gate_pass"]
+    )
+    claim_decisions = {
+        "C1_exact_bql": {
+            "decision": "supported",
+            "basis": "canonical cross-backend gate passed with zero skips",
+        },
+        "C2_hirota_structure": {
+            "decision": "supported_under_stated_assumptions" if structural_pass else "rejected",
+            "basis": "analytic reduction, rank bound, identities, leakage, and clean parity gates",
+        },
+        "C3_hirota_specificity": {
+            "decision": (
+                "supported_on_controlled_TH"
+                if _superiority_gate(c3_ordinary) and c3_competitive_free
+                else "rejected_or_inconclusive"
+            ),
+            "beats_ordinary_gate": _superiority_gate(c3_ordinary),
+            "within_five_percent_of_free_derivative": c3_competitive_free,
+            "fixed_hirota_rmse": float(means_e2["quantum_hirota_core"]),
+            "ordinary_rmse": float(means_e2["ordinary_bilinear"]),
+            "free_derivative_rmse": float(means_e2["free_derivative"]),
+        },
+        "C4_quantum_interaction": {
+            "decision": "supported_on_har" if c4_supported else "not_supported_on_har",
+            "both_strict_superiority_gates_pass": c4_supported,
+            "macro_f1": e4q_means.to_dict(),
+        },
+        "C5_real_transfer": {
+            "decision": "supported_on_har" if c5_supported else "rejected_on_har",
+            "strict_superiority_over_ordinary_gate_pass": c5_supported,
+            "comparison_to_mlp_is_context_only": _superiority_gate(c5_mlp),
+            "macro_f1": {
+                "hirota_core": float(e4_means["quantum_hirota_core_ps"]),
+                "bilinear_core": float(e4_means["quantum_bilinear_core"]),
+            },
+        },
+        "C6_online_quantum_value": {
+            "decision": _online_quantum_value_decision(
+                teacher_test_r2=teacher_test_r2,
+                minimum_teacher_test_r2=minimum_teacher_test_r2,
+                best_modest_fidelity=best_modest_fidelity,
+                fidelity_tolerance=fidelity_tolerance,
+            ),
+            "teacher_viability_gate_pass": teacher_viable,
+            "mean_teacher_test_r2": teacher_test_r2,
+            "minimum_teacher_test_r2": minimum_teacher_test_r2,
+            "best_modest_query_fidelity_rmse": best_modest_fidelity,
+            "best_modest_surrogate": str(best_modest_row.surrogate),
+            "best_modest_query_budget": int(best_modest_row.query_budget),
+            "teacher_output_sd_scale": teacher_scale,
+            "fidelity_tolerance": fidelity_tolerance,
+        },
+        "C7_quantum_advantage": {
+            "decision": "not_authorized",
+            "basis": "no computational/access-model separation is proved",
+        },
+        "noise_parity_diagnostic": {
+            "symmetric_mean_defect": float(symmetric),
+            "asymmetric_mean_defect": float(asymmetric),
+        },
+        "trainability_scope": {
+            "cells": len(e9),
+            "decision": "finite_size_characterization_only",
+        },
+        "shot_scope": {
+            "cells": len(e7),
+            "decision": "simulated_pauli_sampling_only",
+        },
+    }
+    provenance = {
+        "schema_version": 1,
+        "status": "pass",
+        "git_commit": next(iter(commits)),
+        "registry_sha256": next(iter(registry_hashes)),
+        "gate": gate_integrity,
+        "experiments": [item["integrity"] for item in evidence.values()],
+        "full_profile_only": True,
+    }
+
+    if output_directory.exists():
+        raise FileExistsError(f"immutable audit output already exists: {output_directory}")
+    output_directory.parent.mkdir(parents=True, exist_ok=True)
+    staging = output_directory.parent / f".{output_directory.name}.staging-{os.getpid()}"
+    if staging.exists():
+        raise FileExistsError(f"stale audit staging directory requires review: {staging}")
+    staging.mkdir()
+    csv_path = staging / "paired_comparisons.csv"
+    pd.DataFrame(comparisons).to_csv(csv_path, index=False, lineterminator="\n")
+    comparison_path = staging / "paired_comparisons.json"
+    claim_path = staging / "claim_decisions.json"
+    provenance_path = staging / "provenance.json"
+    write_json_atomic(comparison_path, comparisons)
+    write_json_atomic(claim_path, claim_decisions)
+    write_json_atomic(provenance_path, provenance)
+    write_json_atomic(
+        staging / "manifest.json",
+        build_manifest([csv_path, comparison_path, claim_path, provenance_path], staging),
+    )
+    staging.replace(output_directory)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--experiments", type=Path, default=Path("artifacts/experiments"))
+    parser.add_argument("--gates", type=Path, default=Path("artifacts/gates"))
+    parser.add_argument("--output", type=Path, default=Path("artifacts/audit"))
+    arguments = parser.parse_args()
+    run(arguments.experiments, arguments.gates, arguments.output)
+
+
+if __name__ == "__main__":
+    main()

bilinear_quantum/backends/__init__.py

@@ -0,0 +1,5 @@
+"""Execution backends for canonical circuits."""
+
+from .cirq_backend import bql_exact_cirq, cirq_channel_expectations
+
+__all__ = ["bql_exact_cirq", "cirq_channel_expectations"]

bilinear_quantum/backends/cirq_backend.py

@@ -0,0 +1,38 @@
+"""Noiseless Cirq backend for exact BQL."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+import cirq
+import numpy as np
+
+from bilinear_quantum.circuits.bql_exact import build_parallel_bql_circuit
+from bilinear_quantum.core.bql import Calibration, calibration_parameters, encoded_coordinates
+from bilinear_quantum.core.factorization import BilinearFactorization
+
+
+def cirq_channel_expectations(
+    a: np.ndarray,
+    b: np.ndarray,
+    theta: float | Iterable[float],
+) -> np.ndarray:
+    circuit, observables, _, _ = build_parallel_bql_circuit(a, b, theta)
+    simulator = cirq.Simulator(dtype=np.complex128)
+    values = simulator.simulate_expectation_values(circuit, observables=observables)
+    return np.asarray([complex(value).real for value in values], dtype=np.float64)
+
+
+def bql_exact_cirq(
+    f: np.ndarray,
+    g: np.ndarray,
+    factorization: BilinearFactorization,
+    r_f: float,
+    r_g: float,
+    *,
+    calibration: Calibration | str = Calibration.READOUT,
+    margin: float = 1.0,
+) -> float:
+    a, b = encoded_coordinates(f, g, factorization, r_f, r_g)
+    params = calibration_parameters(factorization, r_f, r_g, calibration, margin=margin)
+    return float(params.readout @ cirq_channel_expectations(a, b, params.theta))

bilinear_quantum/backends/tfq_backend.py

@@ -0,0 +1,44 @@
+"""TensorFlow Quantum expectation backend for exact BQL."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterable
+
+# TFQ 0.7.6 is distributed against the legacy Keras API. This must be set
+# before importing TensorFlow in a fresh interpreter.
+os.environ.setdefault("TF_USE_LEGACY_KERAS", "1")
+
+import numpy as np
+import tensorflow as tf
+import tensorflow_quantum as tfq
+
+from bilinear_quantum.circuits.bql_exact import build_parallel_bql_circuit
+from bilinear_quantum.core.bql import Calibration, calibration_parameters, encoded_coordinates
+from bilinear_quantum.core.factorization import BilinearFactorization
+
+
+def tfq_channel_expectations(
+    a: np.ndarray,
+    b: np.ndarray,
+    theta: float | Iterable[float],
+) -> np.ndarray:
+    circuit, observables, _, _ = build_parallel_bql_circuit(a, b, theta)
+    circuit_tensor = tfq.convert_to_tensor([circuit])
+    output = tfq.layers.Expectation()(circuit_tensor, operators=observables)
+    return np.asarray(tf.cast(output[0], tf.float64).numpy(), dtype=np.float64)
+
+
+def bql_exact_tfq(
+    f: np.ndarray,
+    g: np.ndarray,
+    factorization: BilinearFactorization,
+    r_f: float,
+    r_g: float,
+    *,
+    calibration: Calibration | str = Calibration.READOUT,
+    margin: float = 1.0,
+) -> float:
+    a, b = encoded_coordinates(f, g, factorization, r_f, r_g)
+    params = calibration_parameters(factorization, r_f, r_g, calibration, margin=margin)
+    return float(params.readout @ tfq_channel_expectations(a, b, params.theta))

bilinear_quantum/circuits/__init__.py

@@ -0,0 +1,5 @@
+"""Cirq circuit builders used by exact and trainable quantum backends."""
+
+from .bql_exact import build_parallel_bql_circuit, xz_rotation_operations
+
+__all__ = ["build_parallel_bql_circuit", "xz_rotation_operations"]

bilinear_quantum/circuits/bql_exact.py

@@ -0,0 +1,56 @@
+"""Cirq construction of the exact rank-parallel BQL channel."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+import cirq
+import numpy as np
+
+
+def xz_rotation_operations(
+    q_f: cirq.Qid, q_g: cirq.Qid, theta: float
+) -> tuple[cirq.Operation, ...]:
+    """Decompose ``exp(-i theta X_F Z_G / 2)`` into elementary gates."""
+
+    return (
+        cirq.H(q_f),
+        cirq.CNOT(q_f, q_g),
+        cirq.rz(float(theta)).on(q_g),
+        cirq.CNOT(q_f, q_g),
+        cirq.H(q_f),
+    )
+
+
+def build_parallel_bql_circuit(
+    a: np.ndarray,
+    b: np.ndarray,
+    theta: float | Iterable[float],
+) -> tuple[cirq.Circuit, list[cirq.PauliString], list[cirq.Qid], list[cirq.Qid]]:
+    """Build one independent two-qubit channel per rank component."""
+
+    a = np.asarray(a, dtype=np.float64)
+    b = np.asarray(b, dtype=np.float64)
+    if a.ndim != 1 or b.shape != a.shape:
+        raise ValueError("a and b must be equal-length vectors")
+    if not np.all(np.isfinite(a)) or not np.all(np.isfinite(b)):
+        raise ValueError("coordinates must be finite")
+    if np.any(np.abs(a) > 1 + 1e-11) or np.any(np.abs(b) > 1 + 1e-11):
+        raise ValueError("all encoded coordinates must lie in [-1, 1]")
+    a, b = np.clip(a, -1, 1), np.clip(b, -1, 1)
+    theta_array = np.asarray(theta, dtype=np.float64)
+    if theta_array.ndim == 0:
+        theta_array = np.full(a.size, float(theta_array), dtype=np.float64)
+    if theta_array.shape != a.shape or not np.all(np.isfinite(theta_array)):
+        raise ValueError("theta must be finite and scalar or one value per channel")
+
+    f_qubits = [cirq.GridQubit(0, 2 * index) for index in range(a.size)]
+    g_qubits = [cirq.GridQubit(0, 2 * index + 1) for index in range(a.size)]
+    circuit = cirq.Circuit()
+    for q_f, q_g, a_value, b_value in zip(f_qubits, g_qubits, a, b, strict=True):
+        circuit.append(cirq.ry(float(np.arccos(a_value))).on(q_f))
+        circuit.append(cirq.ry(float(np.arccos(b_value))).on(q_g))
+    for q_f, q_g, angle in zip(f_qubits, g_qubits, theta_array, strict=True):
+        circuit.append(xz_rotation_operations(q_f, q_g, float(angle)))
+    observables = [cirq.PauliString(cirq.Y(q_f)) for q_f in f_qubits]
+    return circuit, observables, f_qubits, g_qubits

bilinear_quantum/circuits/canonical.py

@@ -0,0 +1,86 @@
+"""Canonical two-register, tied-template, swap-equivariant HQBL circuit."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import cirq
+import sympy
+
+
+@dataclass(frozen=True)
+class CanonicalCircuit:
+    circuit: cirq.Circuit
+    f_qubits: tuple[cirq.Qid, ...]
+    g_qubits: tuple[cirq.Qid, ...]
+    data_symbols: tuple[sympy.Symbol, ...]
+    trainable_symbols: tuple[sympy.Symbol, ...]
+    mixer_symbols: tuple[sympy.Symbol, ...]
+
+
+def _zz_rotation(q0: cirq.Qid, q1: cirq.Qid, angle) -> cirq.Operation:
+    return cirq.ZZPowGate(exponent=angle / sympy.pi).on(q0, q1)
+
+
+def build_canonical_hqbl_circuit(
+    register_size: int,
+    *,
+    reuploads: int = 2,
+    include_mixer: bool = True,
+) -> CanonicalCircuit:
+    """Build the architecture contract with tied local trainable parameters.
+
+    Branch data symbols are independent so that swapping inputs swaps symbols;
+    all trainable local symbols are shared between corresponding branch gates.
+    The cross-register ``ZZ`` mixer is invariant under register exchange.
+    """
+
+    if register_size <= 0 or reuploads <= 0:
+        raise ValueError("register_size and reuploads must be positive")
+    f_qubits = tuple(cirq.GridQubit(0, index) for index in range(register_size))
+    g_qubits = tuple(cirq.GridQubit(1, index) for index in range(register_size))
+    circuit = cirq.Circuit()
+    data_symbols: list[sympy.Symbol] = []
+    trainable_symbols: list[sympy.Symbol] = []
+    mixer_symbols: list[sympy.Symbol] = []
+    for layer in range(reuploads):
+        for index, (q_f, q_g) in enumerate(zip(f_qubits, g_qubits, strict=True)):
+            x_f = sympy.Symbol(f"x_f_{layer}_{index}")
+            x_g = sympy.Symbol(f"x_g_{layer}_{index}")
+            phi_y = sympy.Symbol(f"phi_y_{layer}_{index}")
+            phi_z = sympy.Symbol(f"phi_z_{layer}_{index}")
+            data_symbols.extend((x_f, x_g))
+            trainable_symbols.extend((phi_y, phi_z))
+            circuit.append((cirq.rx(x_f)(q_f), cirq.rx(x_g)(q_g)))
+            circuit.append((cirq.ry(phi_y)(q_f), cirq.ry(phi_y)(q_g)))
+            circuit.append((cirq.rz(phi_z)(q_f), cirq.rz(phi_z)(q_g)))
+        if register_size > 1:
+            for index in range(register_size - 1):
+                tied = sympy.Symbol(f"local_zz_{layer}_{index}")
+                trainable_symbols.append(tied)
+                circuit.append(
+                    (
+                        _zz_rotation(f_qubits[index], f_qubits[index + 1], tied),
+                        _zz_rotation(g_qubits[index], g_qubits[index + 1], tied),
+                    )
+                )
+        if include_mixer:
+            for index, (q_f, q_g) in enumerate(zip(f_qubits, g_qubits, strict=True)):
+                mixer = sympy.Symbol(f"mixer_zz_{layer}_{index}")
+                mixer_symbols.append(mixer)
+                circuit.append(_zz_rotation(q_f, q_g, mixer))
+    return CanonicalCircuit(
+        circuit=circuit,
+        f_qubits=f_qubits,
+        g_qubits=g_qubits,
+        data_symbols=tuple(data_symbols),
+        trainable_symbols=tuple(trainable_symbols),
+        mixer_symbols=tuple(mixer_symbols),
+    )
+
+
+def swap_qubit_map(canonical: CanonicalCircuit) -> dict[cirq.Qid, cirq.Qid]:
+    return {
+        **dict(zip(canonical.f_qubits, canonical.g_qubits, strict=True)),
+        **dict(zip(canonical.g_qubits, canonical.f_qubits, strict=True)),
+    }