rqm-core 0.1.0__tar.gz

rqm_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RQM Technologies
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rqm_core-0.1.0/PKG-INFO

@@ -0,0 +1,353 @@
+Metadata-Version: 2.4
+Name: rqm-core
+Version: 0.1.0
+Summary: Core quaternion, spinor, SU(2), and Bloch mathematics for the RQM Python ecosystem
+Author: RQM Technologies
+License: MIT License
+        
+        Copyright (c) 2026 RQM Technologies
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://rqmtechnologies.com
+Project-URL: Documentation, https://docs.rqmtechnologies.com
+Project-URL: Source, https://github.com/RQM-Technologies-dev/rqm-core
+Project-URL: Issues, https://github.com/RQM-Technologies-dev/rqm-core/issues
+Keywords: quaternion,su2,bloch sphere,spinor,quantum,linear algebra,rotation,mathematics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Dynamic: license-file
+
+# RQM Core
+
+> Core quaternion, spinor, SU(2), and Bloch mathematics for the RQM Python ecosystem.
+
+[![PyPI version](https://img.shields.io/pypi/v/rqm-core.svg)](https://pypi.org/project/rqm-core/)
+[![Python versions](https://img.shields.io/pypi/pyversions/rqm-core.svg)](https://pypi.org/project/rqm-core/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Documentation](https://img.shields.io/badge/docs-rqmtechnologies.com-blue.svg)](https://docs.rqmtechnologies.com)
+[![Website](https://img.shields.io/badge/website-rqmtechnologies.com-blue.svg)](https://rqmtechnologies.com)
+
+---
+
+## 🌐 RQM Platform
+
+This repository is part of the RQM Technologies ecosystem.
+
+→ Website: https://rqmtechnologies.com  
+→ Documentation: https://docs.rqmtechnologies.com
+
+---
+
+## Install
+
+```bash
+pip install rqm-core
+```
+
+`rqm-core` is the mathematical foundation layer. It has no RQM-level dependencies — only `numpy` at runtime.
+
+---
+
+## Where This Fits
+
+```
+rqm-core  →  rqm-compiler  →  rqm-qiskit / rqm-braket
+```
+
+`rqm-core` provides the canonical mathematical layer of the RQM ecosystem, including quaternion, spinor, Bloch, and SU(2) foundations. Higher-level packages (`rqm-compiler`, `rqm-qiskit`, `rqm-braket`) build on top of it.
+
+---
+
+## Next Steps
+
+- Documentation: https://docs.rqmtechnologies.com
+- Website: https://rqmtechnologies.com
+- Next package in the stack: [`rqm-compiler`](https://github.com/RQM-Technologies-dev/rqm-compiler)
+
+---
+
+## Why This Package Exists
+
+Higher-level RQM libraries (simulators, compilers, hardware adapters) all require a
+common, reliable layer of linear algebra and quantum geometry.  `rqm-core` is that layer.
+
+It provides a single, versioned source of truth for the mathematical primitives shared
+across the whole ecosystem: no duplication, no conflicting conventions, and no framework lock-in.
+
+---
+
+## Design Principles
+
+| Principle | What it means in practice |
+|---|---|
+| **Tiny** | Only implement primitives that are needed by ≥2 packages |
+| **Stable** | Slow to change; breaking changes require a major version bump |
+| **Dependency-light** | Only `numpy` at runtime |
+| **Canonical** | One correct convention, clearly documented, used everywhere |
+| **Well-tested** | Strong test coverage from the first commit |
+
+---
+
+## What Is Included
+
+- **Quaternion primitives** – Hamilton product, conjugate, inverse, axis-angle construction, SO(3) and SU(2) conversions
+- **Spinor helpers** – normalization, norm, fidelity, spinor↔quaternion/SU(2) mappings
+- **SU(2) conversions** – construction from quaternions and axis-angle, validation, round-trips
+- **Bloch sphere mappings** – state↔Bloch, Bloch↔state, quaternion rotation to Bloch vector
+- **Matrix helpers** – trace, determinant, conjugate transpose (dagger), norm, closeness checks
+- **Validation utilities** – axis, complex pair, matrix shape, real number, tolerance checks
+
+---
+
+## Mathematical Conventions
+
+The full reference lives in [`CONVENTIONS.md`](CONVENTIONS.md).
+The five items every downstream package needs to know:
+
+### 1 · SU(2) Convention
+
+A unit quaternion `q = w + xi + yj + zk` maps to SU(2) as:
+
+```
+U(q) = [[ w − iz ,  −y − ix ],
+         [ y − ix ,   w + iz ]]
+```
+
+Implemented in `Quaternion.to_su2_matrix()`; inverted by `su2_to_quaternion()`.
+
+### 2 · Spinor Convention
+
+States are written `|ψ⟩ = α|0⟩ + β|1⟩` with `|0⟩` as the north-pole
+computational-basis ground state.  Amplitudes are always passed as the ordered
+pair `(alpha, beta)`.  Functions that require unit norm normalize internally.
+
+### 3 · Bloch Sphere Parameterization
+
+```
+|ψ⟩ = cos(θ/2)|0⟩ + e^{iφ} sin(θ/2)|1⟩
+```
+
+`theta` ∈ `[0, π]` (polar/colatitude), `phi` ∈ `[0, 2π)` (azimuthal).
+`|0⟩` → north pole `(0, 0, +1)`;  `|1⟩` → south pole `(0, 0, −1)`.
+
+### 4 · Global Phase
+
+`q` and `−q` represent the same rotation.  `spinor_to_quaternion` encodes
+the rotation up to global phase — never rely on the sign of the scalar part.
+
+### 5 · Default Tolerance and Axis Labels
+
+All closeness checks default to `atol = 1e-9` (absolute, no relative
+component).  Axis labels are `"x"`, `"y"`, `"z"` (case-insensitive);
+all angles are in **radians**.
+
+---
+
+## What Is Intentionally *Not* Included
+
+- Qiskit / PennyLane / Cirq adapters
+- Backend execution or hardware drivers
+- Circuit transpilation or compilation
+- Plotting or visualisation
+- Cloud workflow integration
+- Notebook tooling
+- Algorithm frameworks or optimisation workflows
+
+Those belong in higher-level packages.
+
+---
+
+## Installation
+
+```bash
+pip install rqm-core
+```
+
+Development install (includes `pytest` and `pytest-cov`):
+
+```bash
+pip install "rqm-core[dev]"
+```
+
+---
+
+## Ecosystem Role
+
+`rqm-core` is the **spine** of the RQM Python ecosystem.  It provides the
+single canonical implementation of all shared mathematical primitives so that
+downstream packages never need to re-implement or copy them.
+
+**How downstream packages declare the dependency** (example `pyproject.toml` excerpt):
+
+```toml
+[project]
+dependencies = [
+    "rqm-core>=0.1.0",
+]
+```
+
+**How downstream packages import:**
+
+```python
+# rqm-qiskit, rqm-circuits, rqm-compiler, etc.
+from rqm_core import Quaternion, axis_angle_to_su2, state_to_bloch
+```
+
+**Contract for downstream maintainers:**
+
+- All conventions are defined in [`CONVENTIONS.md`](CONVENTIONS.md) and must
+  not be re-defined or overridden locally.
+- Breaking changes to `rqm-core` require a **major version bump** (`1.0.0`, …).
+- Any primitive needed by two or more packages belongs here, not in the
+  individual packages.
+
+---
+
+## Quickstart
+
+```python
+from rqm_core import Quaternion, state_to_bloch, axis_angle_to_su2
+import math
+
+# 90° rotation around Y
+q = Quaternion.from_axis_angle("y", math.pi / 2)
+print(q)
+# Quaternion(0.7071..., 0.0, 0.7071..., 0.0)
+
+# SU(2) matrix directly from axis-angle
+print(axis_angle_to_su2("y", math.pi / 2))
+
+# |+⟩ state on the Bloch sphere → equator at (1, 0, 0)
+c = 1 / math.sqrt(2)
+x, y, z = state_to_bloch(c, c)
+print(x, y, z)  # 1.0  0.0  0.0
+```
+
+---
+
+## Package Structure
+
+```
+rqm-core/
+  CONVENTIONS.md            – canonical mathematical conventions reference
+  pyproject.toml            – package metadata and build config
+  src/rqm_core/
+    __init__.py      – canonical public API (import everything from here)
+    py.typed         – PEP 561 marker (enables type checking in downstream packages)
+    quaternion.py    – Quaternion class (Hamilton algebra, SO(3)/SU(2) conversions)
+    spinor.py        – spinor normalization, fidelity, spinor↔quaternion/SU(2)
+    su2.py           – SU(2) construction, validation, quaternion round-trips
+    bloch.py         – Bloch sphere mappings and validation
+    linalg.py        – matrix helpers (dagger, trace, determinant, closeness)
+    validation.py    – shared validation helpers (axis, matrix shape, tolerances)
+    types.py         – shared type aliases (ComplexVector2, BlochVector, SU2Matrix, …)
+    utils.py         – small math utilities (angle_wrap, safe_norm, is_finite_*)
+
+  tests/
+    test_quaternion.py
+    test_spinor.py
+    test_su2.py
+    test_bloch.py
+    test_linalg.py
+    test_utils.py
+    test_validation.py
+    test_public_api.py
+
+  examples/
+    quaternion_basics.py    – quaternion construction, composition, conversion
+    spinor_basics.py        – spinor normalization, Bloch mapping, fidelity
+    su2_bloch_demo.py       – axis-angle → SU(2) → Bloch pipeline
+    bloch_mapping_demo.py   – canonical Bloch vectors and round-trip checks
+    su2_rotation_demo.py    – SU(2) construction and quaternion round-trip
+```
+
+---
+
+## Testing
+
+```bash
+# Install the package in editable mode with test dependencies
+pip install -e ".[dev]"
+
+# Run the full test suite
+pytest
+
+# Run with coverage report
+pytest --cov=rqm_core --cov-report=term-missing
+
+# Run a single test file
+pytest tests/test_quaternion.py -v
+
+# Run only the public-API contract tests
+pytest tests/test_public_api.py -v
+```
+
+---
+
+## Architectural Notes
+
+- **`su2.is_unitary` is a thin domain-scoped shim** over `linalg.is_unitary`.
+  Both exist intentionally: `linalg.is_unitary` is the general-purpose helper;
+  `su2.is_unitary` is the public entry point for SU(2)-context callers and is
+  what `rqm_core.is_unitary` resolves to in the top-level API.
+
+- **`q` and `−q` represent the same rotation.**  Round-trip conversions
+  `q → SU(2) → q` are tested against both `q` and `−q`.  Downstream code
+  must never compare quaternion scalar parts for sign equality.
+
+- **The `src/` layout** means `rqm_core` is only importable after installation
+  (`pip install -e .`).  Running tests directly without installing first will
+  produce `ModuleNotFoundError`.
+
+- **`py.typed`** is included in the installed wheel (via `[tool.setuptools.package-data]`),
+  enabling `mypy` and `pyright` in any package that depends on `rqm-core`.
+
+---
+
+## Roadmap
+
+`rqm-core` is intended to remain **small and stable** while higher-level packages evolve around it.
+
+Planned additions for future minor versions:
+
+- [ ] Quaternion SLERP (spherical linear interpolation)
+- [ ] SO(3) rotation-matrix ↔ quaternion round-trip helpers
+- [ ] Mixed-state density matrix utilities
+- [ ] SU(2) Lie-algebra generators and exponential map
+- [ ] Type stub files (`.pyi`) for IDE completions
+
+No Qiskit or framework dependencies will ever be added to this package.
+

rqm_core-0.1.0/README.md

@@ -0,0 +1,301 @@
+# RQM Core
+
+> Core quaternion, spinor, SU(2), and Bloch mathematics for the RQM Python ecosystem.
+
+[![PyPI version](https://img.shields.io/pypi/v/rqm-core.svg)](https://pypi.org/project/rqm-core/)
+[![Python versions](https://img.shields.io/pypi/pyversions/rqm-core.svg)](https://pypi.org/project/rqm-core/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Documentation](https://img.shields.io/badge/docs-rqmtechnologies.com-blue.svg)](https://docs.rqmtechnologies.com)
+[![Website](https://img.shields.io/badge/website-rqmtechnologies.com-blue.svg)](https://rqmtechnologies.com)
+
+---
+
+## 🌐 RQM Platform
+
+This repository is part of the RQM Technologies ecosystem.
+
+→ Website: https://rqmtechnologies.com  
+→ Documentation: https://docs.rqmtechnologies.com
+
+---
+
+## Install
+
+```bash
+pip install rqm-core
+```
+
+`rqm-core` is the mathematical foundation layer. It has no RQM-level dependencies — only `numpy` at runtime.
+
+---
+
+## Where This Fits
+
+```
+rqm-core  →  rqm-compiler  →  rqm-qiskit / rqm-braket
+```
+
+`rqm-core` provides the canonical mathematical layer of the RQM ecosystem, including quaternion, spinor, Bloch, and SU(2) foundations. Higher-level packages (`rqm-compiler`, `rqm-qiskit`, `rqm-braket`) build on top of it.
+
+---
+
+## Next Steps
+
+- Documentation: https://docs.rqmtechnologies.com
+- Website: https://rqmtechnologies.com
+- Next package in the stack: [`rqm-compiler`](https://github.com/RQM-Technologies-dev/rqm-compiler)
+
+---
+
+## Why This Package Exists
+
+Higher-level RQM libraries (simulators, compilers, hardware adapters) all require a
+common, reliable layer of linear algebra and quantum geometry.  `rqm-core` is that layer.
+
+It provides a single, versioned source of truth for the mathematical primitives shared
+across the whole ecosystem: no duplication, no conflicting conventions, and no framework lock-in.
+
+---
+
+## Design Principles
+
+| Principle | What it means in practice |
+|---|---|
+| **Tiny** | Only implement primitives that are needed by ≥2 packages |
+| **Stable** | Slow to change; breaking changes require a major version bump |
+| **Dependency-light** | Only `numpy` at runtime |
+| **Canonical** | One correct convention, clearly documented, used everywhere |
+| **Well-tested** | Strong test coverage from the first commit |
+
+---
+
+## What Is Included
+
+- **Quaternion primitives** – Hamilton product, conjugate, inverse, axis-angle construction, SO(3) and SU(2) conversions
+- **Spinor helpers** – normalization, norm, fidelity, spinor↔quaternion/SU(2) mappings
+- **SU(2) conversions** – construction from quaternions and axis-angle, validation, round-trips
+- **Bloch sphere mappings** – state↔Bloch, Bloch↔state, quaternion rotation to Bloch vector
+- **Matrix helpers** – trace, determinant, conjugate transpose (dagger), norm, closeness checks
+- **Validation utilities** – axis, complex pair, matrix shape, real number, tolerance checks
+
+---
+
+## Mathematical Conventions
+
+The full reference lives in [`CONVENTIONS.md`](CONVENTIONS.md).
+The five items every downstream package needs to know:
+
+### 1 · SU(2) Convention
+
+A unit quaternion `q = w + xi + yj + zk` maps to SU(2) as:
+
+```
+U(q) = [[ w − iz ,  −y − ix ],
+         [ y − ix ,   w + iz ]]
+```
+
+Implemented in `Quaternion.to_su2_matrix()`; inverted by `su2_to_quaternion()`.
+
+### 2 · Spinor Convention
+
+States are written `|ψ⟩ = α|0⟩ + β|1⟩` with `|0⟩` as the north-pole
+computational-basis ground state.  Amplitudes are always passed as the ordered
+pair `(alpha, beta)`.  Functions that require unit norm normalize internally.
+
+### 3 · Bloch Sphere Parameterization
+
+```
+|ψ⟩ = cos(θ/2)|0⟩ + e^{iφ} sin(θ/2)|1⟩
+```
+
+`theta` ∈ `[0, π]` (polar/colatitude), `phi` ∈ `[0, 2π)` (azimuthal).
+`|0⟩` → north pole `(0, 0, +1)`;  `|1⟩` → south pole `(0, 0, −1)`.
+
+### 4 · Global Phase
+
+`q` and `−q` represent the same rotation.  `spinor_to_quaternion` encodes
+the rotation up to global phase — never rely on the sign of the scalar part.
+
+### 5 · Default Tolerance and Axis Labels
+
+All closeness checks default to `atol = 1e-9` (absolute, no relative
+component).  Axis labels are `"x"`, `"y"`, `"z"` (case-insensitive);
+all angles are in **radians**.
+
+---
+
+## What Is Intentionally *Not* Included
+
+- Qiskit / PennyLane / Cirq adapters
+- Backend execution or hardware drivers
+- Circuit transpilation or compilation
+- Plotting or visualisation
+- Cloud workflow integration
+- Notebook tooling
+- Algorithm frameworks or optimisation workflows
+
+Those belong in higher-level packages.
+
+---
+
+## Installation
+
+```bash
+pip install rqm-core
+```
+
+Development install (includes `pytest` and `pytest-cov`):
+
+```bash
+pip install "rqm-core[dev]"
+```
+
+---
+
+## Ecosystem Role
+
+`rqm-core` is the **spine** of the RQM Python ecosystem.  It provides the
+single canonical implementation of all shared mathematical primitives so that
+downstream packages never need to re-implement or copy them.
+
+**How downstream packages declare the dependency** (example `pyproject.toml` excerpt):
+
+```toml
+[project]
+dependencies = [
+    "rqm-core>=0.1.0",
+]
+```
+
+**How downstream packages import:**
+
+```python
+# rqm-qiskit, rqm-circuits, rqm-compiler, etc.
+from rqm_core import Quaternion, axis_angle_to_su2, state_to_bloch
+```
+
+**Contract for downstream maintainers:**
+
+- All conventions are defined in [`CONVENTIONS.md`](CONVENTIONS.md) and must
+  not be re-defined or overridden locally.
+- Breaking changes to `rqm-core` require a **major version bump** (`1.0.0`, …).
+- Any primitive needed by two or more packages belongs here, not in the
+  individual packages.
+
+---
+
+## Quickstart
+
+```python
+from rqm_core import Quaternion, state_to_bloch, axis_angle_to_su2
+import math
+
+# 90° rotation around Y
+q = Quaternion.from_axis_angle("y", math.pi / 2)
+print(q)
+# Quaternion(0.7071..., 0.0, 0.7071..., 0.0)
+
+# SU(2) matrix directly from axis-angle
+print(axis_angle_to_su2("y", math.pi / 2))
+
+# |+⟩ state on the Bloch sphere → equator at (1, 0, 0)
+c = 1 / math.sqrt(2)
+x, y, z = state_to_bloch(c, c)
+print(x, y, z)  # 1.0  0.0  0.0
+```
+
+---
+
+## Package Structure
+
+```
+rqm-core/
+  CONVENTIONS.md            – canonical mathematical conventions reference
+  pyproject.toml            – package metadata and build config
+  src/rqm_core/
+    __init__.py      – canonical public API (import everything from here)
+    py.typed         – PEP 561 marker (enables type checking in downstream packages)
+    quaternion.py    – Quaternion class (Hamilton algebra, SO(3)/SU(2) conversions)
+    spinor.py        – spinor normalization, fidelity, spinor↔quaternion/SU(2)
+    su2.py           – SU(2) construction, validation, quaternion round-trips
+    bloch.py         – Bloch sphere mappings and validation
+    linalg.py        – matrix helpers (dagger, trace, determinant, closeness)
+    validation.py    – shared validation helpers (axis, matrix shape, tolerances)
+    types.py         – shared type aliases (ComplexVector2, BlochVector, SU2Matrix, …)
+    utils.py         – small math utilities (angle_wrap, safe_norm, is_finite_*)
+
+  tests/
+    test_quaternion.py
+    test_spinor.py
+    test_su2.py
+    test_bloch.py
+    test_linalg.py
+    test_utils.py
+    test_validation.py
+    test_public_api.py
+
+  examples/
+    quaternion_basics.py    – quaternion construction, composition, conversion
+    spinor_basics.py        – spinor normalization, Bloch mapping, fidelity
+    su2_bloch_demo.py       – axis-angle → SU(2) → Bloch pipeline
+    bloch_mapping_demo.py   – canonical Bloch vectors and round-trip checks
+    su2_rotation_demo.py    – SU(2) construction and quaternion round-trip
+```
+
+---
+
+## Testing
+
+```bash
+# Install the package in editable mode with test dependencies
+pip install -e ".[dev]"
+
+# Run the full test suite
+pytest
+
+# Run with coverage report
+pytest --cov=rqm_core --cov-report=term-missing
+
+# Run a single test file
+pytest tests/test_quaternion.py -v
+
+# Run only the public-API contract tests
+pytest tests/test_public_api.py -v
+```
+
+---
+
+## Architectural Notes
+
+- **`su2.is_unitary` is a thin domain-scoped shim** over `linalg.is_unitary`.
+  Both exist intentionally: `linalg.is_unitary` is the general-purpose helper;
+  `su2.is_unitary` is the public entry point for SU(2)-context callers and is
+  what `rqm_core.is_unitary` resolves to in the top-level API.
+
+- **`q` and `−q` represent the same rotation.**  Round-trip conversions
+  `q → SU(2) → q` are tested against both `q` and `−q`.  Downstream code
+  must never compare quaternion scalar parts for sign equality.
+
+- **The `src/` layout** means `rqm_core` is only importable after installation
+  (`pip install -e .`).  Running tests directly without installing first will
+  produce `ModuleNotFoundError`.
+
+- **`py.typed`** is included in the installed wheel (via `[tool.setuptools.package-data]`),
+  enabling `mypy` and `pyright` in any package that depends on `rqm-core`.
+
+---
+
+## Roadmap
+
+`rqm-core` is intended to remain **small and stable** while higher-level packages evolve around it.
+
+Planned additions for future minor versions:
+
+- [ ] Quaternion SLERP (spherical linear interpolation)
+- [ ] SO(3) rotation-matrix ↔ quaternion round-trip helpers
+- [ ] Mixed-state density matrix utilities
+- [ ] SU(2) Lie-algebra generators and exponential map
+- [ ] Type stub files (`.pyi`) for IDE completions
+
+No Qiskit or framework dependencies will ever be added to this package.
+