Build initial production v0 of rqm-optimize package

Co-authored-by: RQM-Technologies-dev <267137213+RQM-Technologies-dev@users.noreply.github.com>

Author: Copilot

AGENTS.md

@@ -0,0 +1,93 @@
+# AGENTS.md — rqm-optimize repo discipline
+
+## Purpose
+
+`rqm-optimize` is the **optimization layer** in the RQM Technologies quantum software stack.
+
+Its job is to reduce circuit depth and gate count by compressing single-qubit gate runs through SU(2)-aware fusion, and to provide a foundation for backend-aware optimization in future versions.
+
+---
+
+## Stack position
+
+```text
+rqm-core      → canonical quaternion / SU(2) / Bloch math
+rqm-compiler  → circuit construction / normalization
+rqm-qiskit    → Qiskit lowering / execution bridge
+rqm-braket    → Braket lowering / execution bridge
+rqm-optimize  → optimization / compression layer  ← this repo
+```
+
+---
+
+## What belongs here
+
+- Single-qubit run fusion and compression logic
+- SU(2)-aware decomposition helpers that are specific to optimization workflows
+- Gate count metrics and optimization quality metrics
+- Future: backend-aware native-axis alignment
+- Future: drift-aware path selection
+- Future: quaternionic error metrics
+- Future: Braket circuit support (adapter only, not execution)
+
+---
+
+## What does NOT belong here
+
+- **Canonical quaternion or SU(2) math** — that belongs in `rqm-core`. Do not duplicate it here.
+- **Qiskit execution** — that belongs in `rqm-qiskit`.
+- **Hardware execution** — never here.
+- **Backend calibration mutation** — never here.
+- **Full transpilation** — this is an optimizer, not a transpiler.
+- **Circuit construction** — that belongs in `rqm-compiler`.
+
+---
+
+## Module responsibilities
+
+| Module | Responsibility |
+|--------|---------------|
+| `optimizer.py` | Public API, type dispatch, strategy validation, result packaging |
+| `fusion.py` | Scanning circuits, identifying single-qubit runs, fusing them |
+| `geometry.py` | SU(2) / global-phase normalization helpers (small, rigorous) |
+| `metrics.py` | Gate count metrics, matrix error norms, stubs for future quaternionic metrics |
+| `qiskit_adapter.py` | Qiskit-specific instruction inspection, matrix extraction, Euler emission |
+
+---
+
+## Public API rules
+
+- The public API lives in `src/rqm_optimize/__init__.py` and is controlled by `__all__`.
+- Keep the public API small: `optimize` and `OptimizationResult` are the surface area.
+- New public symbols require deliberate addition to `__all__`.
+- Do not expose internal helpers in the public API.
+
+---
+
+## Code discipline
+
+- All public functions must have type hints and docstrings.
+- All behavior changes require tests.
+- No placeholder TODO spam in production code.
+- No speculative claims in code comments.
+- No dead code.
+- Functions should be small and do one thing.
+- Prefer readability over cleverness.
+
+---
+
+## Testing
+
+- Tests live in `tests/`.
+- Use `pytest` for all tests.
+- Equivalence tests must use tolerance-aware comparison (`numpy.allclose` or `Operator` fidelity).
+- Circuits with measurements cannot be compared by unitary — compare structure or unitary prefix.
+- All regression bugs get a test.
+
+---
+
+## Versioning
+
+- v0.1.x: Qiskit single-qubit run fusion only.
+- v0.2.x: Backend-aware native-axis alignment (planned).
+- v1.0: Stable public API, Braket support, quaternionic metrics.

README.md

@@ -1,2 +1,140 @@
 # rqm-optimize
-rqm-optimize compresses single-qubit gate runs into shorter SU(2)-equivalent forms, reducing unnecessary depth without changing the user workflow.
+
+> `rqm-optimize` improves quantum circuits by compressing single-qubit gate runs through SU(2)-aware fusion, reducing unnecessary gate depth while preserving circuit behavior.
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+---
+
+## Purpose
+
+`rqm-optimize` is the **optimization layer** of the RQM Technologies quantum software stack. It accepts a Qiskit `QuantumCircuit`, scans it for contiguous single-qubit gate runs, fuses those runs into minimal SU(2)-equivalent operations, and returns a simplified circuit that is unitary-equivalent to the original up to global phase.
+
+---
+
+## Stack placement
+
+```text
+rqm-core      → canonical quaternion / SU(2) / Bloch math
+rqm-compiler  → circuit construction / normalization
+rqm-qiskit    → Qiskit lowering / execution bridge
+rqm-braket    → Braket lowering / execution bridge
+rqm-optimize  → optimization / compression layer  ← this package
+```
+
+---
+
+## Installation
+
+```bash
+pip install rqm-optimize
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/RQM-Technologies-dev/rqm-optimize.git
+cd rqm-optimize
+pip install -e ".[dev]"
+```
+
+---
+
+## Quickstart
+
+```python
+from qiskit import QuantumCircuit
+from rqm_optimize import optimize
+
+qc = QuantumCircuit(1)
+qc.rx(0.5, 0)
+qc.ry(0.3, 0)
+qc.rz(0.2, 0)
+
+# Simple usage — returns an optimized QuantumCircuit.
+qc_opt = optimize(qc)
+
+# With metadata.
+result = optimize(qc, return_metadata=True)
+print(result.original_gate_count)   # 3
+print(result.optimized_gate_count)  # 1
+print(result.fused_runs)            # 1
+print(result.circuit)
+```
+
+---
+
+## What v0 does
+
+- Detects **contiguous single-qubit gate runs** on each qubit.
+- Fuses each run into a **single SU(2)-equivalent gate** using matrix
+  multiplication followed by Qiskit's `OneQubitEulerDecomposer`.
+- Skips fusion when the decomposition would produce more gates than the
+  original (i.e., only applies optimizations that reduce or maintain gate count).
+- Preserves **barriers, measurements, resets, and multi-qubit gates** exactly
+  as hard boundaries.
+- Never mutates the input circuit.
+- Returns deterministic output.
+
+### Supported gates in v0
+
+`rx`, `ry`, `rz`, `u`, `u3`, `u2`, `u1`, `p`, `x`, `y`, `z`, `h`, `s`, `sdg`,
+`t`, `tdg`, `id`, `sx`, `sxdg`, `r`, and any generic single-qubit
+`UnitaryGate` whose matrix can be extracted.
+
+---
+
+## What v0 does not yet do
+
+- Backend-aware native-axis alignment (planned for v0.2).
+- Quaternionic error metrics and drift-aware path selection (planned).
+- Braket circuit support (planned).
+- Two-qubit gate optimization.
+
+---
+
+## Architecture
+
+```
+src/rqm_optimize/
+├── __init__.py         # Public API: optimize, OptimizationResult
+├── optimizer.py        # Type dispatch, strategy validation, result packaging
+├── fusion.py           # Single-qubit run identification and matrix fusion
+├── geometry.py         # SU(2) / global-phase normalization helpers
+├── metrics.py          # Gate count metrics, matrix error norms
+├── qiskit_adapter.py   # Qiskit instruction inspection, matrix extraction, Euler emission
+└── py.typed            # PEP 561 marker
+```
+
+The public surface area is intentionally minimal: `optimize()` and
+`OptimizationResult`. All internal helpers are private.
+
+---
+
+## Development and testing
+
+```bash
+# Install with dev dependencies.
+pip install -e ".[dev]"
+
+# Run tests.
+pytest
+
+# Run the example.
+python examples/basic_optimize.py
+```
+
+Tests cover:
+
+- Public API importability and `__all__` contract.
+- Fusion correctness (runs compressed, boundaries respected, equivalence up to global phase).
+- Integration tests comparing unitaries using `qiskit.quantum_info.Operator`.
+- Measurement / barrier / multi-qubit structure preservation.
+- Metadata fields and determinism.
+
+---
+
+## License
+
+MIT © RQM Technologies

examples/basic_optimize.py

@@ -0,0 +1,30 @@
+"""examples/basic_optimize.py — Minimal runnable example for rqm-optimize.
+
+Demonstrates the core workflow: build a circuit, optimize it, inspect results.
+"""
+
+from qiskit import QuantumCircuit
+
+from rqm_optimize import optimize
+
+# Build a simple one-qubit circuit with multiple rotations.
+qc = QuantumCircuit(1, name="example")
+qc.rx(0.5, 0)
+qc.ry(0.3, 0)
+qc.rz(0.2, 0)
+qc.h(0)
+qc.rx(1.1, 0)
+qc.rz(0.8, 0)
+
+print("Original circuit:")
+print(qc)
+print(f"Original gate count: {len(qc.data)}")
+
+# Optimize with metadata.
+result = optimize(qc, return_metadata=True)
+
+print("\nOptimized circuit:")
+print(result.circuit)
+print(f"Optimized gate count: {result.optimized_gate_count}")
+print(f"Fused runs:           {result.fused_runs}")
+print(f"Strategy:             {result.strategy}")

pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "rqm-optimize"
+version = "0.1.0"
+description = "SU(2)-aware circuit compression for quantum workflows"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "RQM Technologies", email = "dev@rqm.tech" }]
+keywords = ["quantum", "optimization", "qiskit", "circuit", "su2", "quaternion"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Physics",
+    "Typing :: Typed",
+]
+requires-python = ">=3.9"
+dependencies = [
+    "qiskit>=1.0",
+    "numpy>=1.24",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "pytest-cov"]
+
+[project.urls]
+Homepage = "https://github.com/RQM-Technologies-dev/rqm-optimize"
+Repository = "https://github.com/RQM-Technologies-dev/rqm-optimize"
+Issues = "https://github.com/RQM-Technologies-dev/rqm-optimize/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/rqm_optimize"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v"

src/rqm_optimize/__init__.py

@@ -0,0 +1,12 @@
+"""rqm-optimize — SU(2)-aware circuit compression for quantum workflows.
+
+Public API::
+
+    from rqm_optimize import optimize, OptimizationResult
+
+    result = optimize(qc, return_metadata=True)
+"""
+
+from .optimizer import OptimizationResult, optimize
+
+__all__ = ["optimize", "OptimizationResult"]