You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This page explains the layering and dependency philosophy of the RQM ecosystem, and why the stack is organized the way it is.
3
+
This page explains the layering and dependency philosophy of the RQM platform, and why the stack is organized the way it is.
4
4
5
5
---
6
6
7
7
## Design Principles
8
8
9
9
### 1. Canonical math lives in `rqm-core`
10
10
11
-
`rqm-core` is the single source of truth for all quaternion algebra, spinor representations, Bloch vector geometry, and SU(2) group operations. No other repository in the ecosystem duplicates this logic.
11
+
`rqm-core` is the single source of truth for all quaternion algebra, spinor representations, Bloch vector geometry, and SU(2) group operations. No other package in the platform duplicates this logic.
12
12
13
13
If you need to compute a spinor normalization, convert to a Bloch vector, or construct an SU(2) rotation matrix — that implementation belongs in `rqm-core`.
14
14
15
-
### 2. Execution lives in `rqm-qiskit`
15
+
### 2. Compilation lives in `rqm-compiler`
16
16
17
-
`rqm-qiskit` is the bridge between the mathematical abstractions in `rqm-core` and the Qiskit circuit framework. It does not re-implement math; it maps it.
17
+
`rqm-compiler` is the bridge between the math layer and execution backends. It accepts backend-agnostic programs and produces a normalized instruction set that any backend can consume.
18
18
19
-
State preparation, gate construction, and simulator interaction belong here. The dependency direction is strictly one way: `rqm-qiskit` imports from `rqm-core`, never the reverse.
19
+
The compiler resolves logical gate names to explicit unitary matrices using `rqm-core` primitives. It applies normalization passes to ensure the IR is backend-ready. Backends do not perform gate resolution — that work is done once at the compiler level.
20
20
21
-
### 3. Teaching lives in `rqm-notebooks`
21
+
### 3. Execution lives in the backend packages
22
22
23
-
`rqm-notebooks` provides the guided learning experience. Notebooks demonstrate how to use both `rqm-core` and `rqm-qiskit` together to explore quantum geometry and run circuits.
23
+
`rqm-qiskit` and `rqm-braket` are execution backends. They translate the compiler IR into their respective native circuit formats and run them on simulators or hardware.
24
24
25
-
Notebooks are allowed to be exploratory and pedagogical, but they do not define new math or new library functions.
25
+
Neither backend reimplements math or compilation logic. They each implement the same interface contract, which is why the same program runs on either backend without modification.
26
26
27
27
### 4. Documentation lives in `rqm-docs`
28
28
29
-
`rqm-docs` (this site) organizes and explains the ecosystem. It does not introduce new algorithms, theory, or notebook content. Its job is to make everything else discoverable, understandable, and usable.
29
+
`rqm-docs` (this site) organizes and explains the platform. It does not introduce new algorithms, theory, or notebook content. Its job is to make everything else discoverable, understandable, and usable.
30
+
31
+
---
32
+
33
+
## Compiler-First Pipeline
34
+
35
+
The full lowering path from program to result:
36
+
37
+
```
38
+
RQMGate list
39
+
│
40
+
▼
41
+
rqm-compiler
42
+
(normalize gates, resolve matrices, produce IR)
43
+
│
44
+
├──────────────────┐
45
+
▼ ▼
46
+
rqm-qiskit rqm-braket
47
+
(Qiskit circuit) (Braket circuit)
48
+
│ │
49
+
▼ ▼
50
+
simulator/hardware simulator/hardware
51
+
│ │
52
+
▼ ▼
53
+
result.counts result.counts
54
+
```
55
+
56
+
The program is defined once. The compiler processes it once. Execution backends are interchangeable.
30
57
31
58
---
32
59
33
60
## Dependency Graph
34
61
35
62
```
36
-
rqm-notebooks ──► rqm-qiskit ──► rqm-core
37
-
└─────────────► rqm-core
63
+
rqm-braket ──► rqm-compiler ──► rqm-core
64
+
rqm-qiskit ──► rqm-compiler ──► rqm-core
65
+
rqm-notebooks ──► rqm-qiskit, rqm-braket
38
66
```
39
67
40
68
-`rqm-core` has no ecosystem dependencies.
41
-
-`rqm-qiskit` depends on `rqm-core`.
42
-
-`rqm-notebooks` depends on both `rqm-core` and `rqm-qiskit`.
43
-
-`rqm-docs` references all three but has no runtime dependency on any of them.
69
+
-`rqm-compiler` depends on `rqm-core`.
70
+
-`rqm-qiskit` depends on `rqm-compiler` (and transitively `rqm-core`).
71
+
-`rqm-braket` depends on `rqm-compiler` (and transitively `rqm-core`).
72
+
-`rqm-notebooks` depends on the execution backends.
73
+
-`rqm-docs` references all packages but has no runtime dependency on any of them.
Separating concerns across repositories gives each layer a clear scope:
109
+
Separating math, compilation, and execution into distinct layers provides concrete benefits:
77
110
78
-
- It keeps `rqm-core` dependency-light and testable in isolation.
79
-
- It allows `rqm-qiskit` to evolve with Qiskit without touching the math.
80
-
- It allows notebooks to be updated as learning content without affecting production code.
81
-
- It ensures that documentation can be maintained, versioned, and deployed independently.
111
+
-**`rqm-core` stays dependency-light** and can be tested in isolation without any quantum framework installed.
112
+
-**`rqm-compiler` is backend-neutral** — optimization and normalization passes apply once and benefit all backends.
113
+
-**Backends evolve independently** — changes to Qiskit's API do not affect the Braket backend, and vice versa.
114
+
-**Programs are portable** — the same program description runs on any registered backend.
115
+
-**Documentation is independently deployable** — `rqm-docs` has no runtime dependencies on the packages it documents.
82
116
83
-
Monorepos trade clarity for convenience. For an ecosystem centered on mathematical correctness and pedagogical value, clear boundaries are worth the additional structure.
117
+
For an ecosystem built around mathematical correctness and backend independence, clear layer boundaries are worth the additional structure.
This page explains the key design ideas behind the RQM platform: why it is built as a compiler-first system, what backend abstraction means in practice, and how the canonical lowering path works.
4
+
5
+
---
6
+
7
+
## Mental Model
8
+
9
+
Think of RQM as three distinct responsibilities:
10
+
11
+
-**`rqm-core`** → defines the physics (quaternions, spinors, SU(2))
12
+
-**`rqm-compiler`** → defines how programs are constructed
13
+
-**backends** → define where programs run
14
+
15
+
You write programs once at the compiler layer, and choose execution at the backend layer. The physics layer never changes regardless of which backend you use.
16
+
17
+
This separation is why the same program runs on Qiskit and Braket without modification.
18
+
19
+
---
20
+
21
+
## Compiler-First Design
22
+
23
+
Most quantum frameworks couple the program representation tightly to a single execution backend. RQM takes a different approach: the program is compiled first, then executed.
24
+
25
+
The compiler layer (`rqm-compiler`) sits between the math layer and the execution backends. Its job is to:
26
+
27
+
- Accept a backend-agnostic program (a list of `RQMGate` instructions)
28
+
- Normalize the instruction set to a canonical intermediate representation (IR)
29
+
- Produce an IR that any registered backend can consume
30
+
31
+
This means the same program description is valid input for any backend. The backends do not need to understand each other — they only need to implement the IR contract.
32
+
33
+
**Why this matters:**
34
+
35
+
- Programs are portable. A program written for Braket works on Qiskit without modification.
36
+
- Optimization passes can be applied at the compiler level, once, for all backends.
37
+
- Adding a new backend means implementing one interface, not rewriting programs.
38
+
39
+
---
40
+
41
+
## Backend Abstraction
42
+
43
+
RQM currently ships two execution backends:
44
+
45
+
| Backend | Package | Runtime |
46
+
|---|---|---|
47
+
| Qiskit |[`rqm-qiskit`](https://github.com/RQM-Technologies-dev/rqm-qiskit)| IBM Qiskit / Aer simulator |
48
+
| AWS Braket |[`rqm-braket`](https://github.com/RQM-Technologies-dev/rqm-braket)| Amazon Braket local and cloud |
49
+
50
+
Both backends expose the same interface. Swapping backends is a one-line change:
51
+
52
+
```python
53
+
# Braket
54
+
from rqm_braket import BraketBackend
55
+
backend = BraketBackend()
56
+
57
+
# Qiskit
58
+
from rqm_qiskit import QiskitBackend
59
+
backend = QiskitBackend()
60
+
61
+
# Same program works with either backend
62
+
result = backend.run_local(program)
63
+
```
64
+
65
+
The execution backend is responsible for:
66
+
67
+
- Translating the compiler IR into the native circuit format (Qiskit `QuantumCircuit` or Braket `Circuit`)
68
+
- Submitting the circuit to a local simulator or a cloud device
69
+
- Returning results in a normalized format (`result.counts`, `result.statevector`)
70
+
71
+
---
72
+
73
+
## Canonical Lowering Path
74
+
75
+
The full pipeline from program to result:
76
+
77
+
```
78
+
RQMGate list --> rqm-compiler IR --> backend circuit --> results
79
+
```
80
+
81
+
**Step 1: Program definition**
82
+
83
+
Programs are written as lists of `RQMGate` objects. Gates carry logical names (`"H"`, `"CNOT"`, `"RZ"`) and qubit targets. They do not reference any specific backend.
84
+
85
+
**Step 2: Compiler normalization**
86
+
87
+
`rqm-compiler` resolves each logical gate to a canonical matrix representation using the math primitives in `rqm-core` (quaternions, SU(2) matrices). It produces a normalized IR where all gates have explicit unitary matrices and explicit qubit mappings.
88
+
89
+
**Step 3: Backend translation**
90
+
91
+
The selected backend reads the normalized IR and constructs its native circuit representation. It does not perform any gate resolution or math — that work is already done.
92
+
93
+
**Step 4: Execution and result**
94
+
95
+
The backend runs the circuit and returns a result object. Results are normalized across backends so that `result.counts` and `result.statevector` are available regardless of which backend was used.
96
+
97
+
---
98
+
99
+
## The Math Foundation
100
+
101
+
`rqm-core` provides the mathematical primitives that the compiler uses:
102
+
103
+
-**Quaternions** — encode 3D rotations in four numbers; the primary representation for single-qubit gates
104
+
-**Spinors** — two-component complex vectors representing quantum states
105
+
-**SU(2) matrices** — 2×2 unitary matrices derived from quaternions; the gate representation consumed by backends
106
+
-**Bloch vectors** — geometric representation of qubit state on the unit sphere
107
+
108
+
These are defined once in `rqm-core` and shared across the entire stack. No backend reimplements them.
0 commit comments