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
Copy file name to clipboardExpand all lines: README.md
+54-25Lines changed: 54 additions & 25 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,23 +1,69 @@
1
1
# rqm-docs
2
2
3
-
**Official documentation hub for the RQM quantum geometry ecosystem.**
3
+
**Official documentation hub for the RQM quantum computing platform.**
4
4
5
5
This site is built with [MkDocs](https://www.mkdocs.org/) and the [Material theme](https://squidfunk.github.io/mkdocs-material/) and is deployed to GitHub Pages.
6
6
7
+
Live site: **[https://rqm-technologies-dev.github.io/rqm-docs/](https://rqm-technologies-dev.github.io/rqm-docs/)**
8
+
7
9
---
8
10
9
11
## The RQM Ecosystem
10
12
11
-
| Repository | Role |
12
-
|---|---|
13
-
|[`rqm-core`](https://github.com/RQM-Technologies-dev/rqm-core)| Canonical math engine: quaternions, spinors, Bloch vectors, SU(2) |
14
-
|[`rqm-qiskit`](https://github.com/RQM-Technologies-dev/rqm-qiskit)| Execution bridge: Qiskit circuits, gates, and simulators |
15
-
|[`rqm-notebooks`](https://github.com/RQM-Technologies-dev/rqm-notebooks)| Guided learning: Jupyter notebooks and demos |
16
-
|[`rqm-docs`](https://github.com/RQM-Technologies-dev/rqm-docs)| This documentation site |
13
+
RQM is a compiler-first quantum software platform. The ecosystem is organized as a layered stack:
|[`rqm-docs`](https://github.com/RQM-Technologies-dev/rqm-docs)| Docs | This documentation site |
48
+
49
+
---
50
+
51
+
## Why This Repo Exists
52
+
53
+
As the RQM ecosystem has grown across multiple repositories, the need for a unified documentation layer has become clear.
54
+
55
+
`rqm-docs` exists to:
56
+
57
+
-**Improve usability** — give users a single entry point to understand and navigate the full stack.
58
+
-**Improve credibility** — a professional documentation site signals that the ecosystem is maintained and production-worthy.
59
+
-**Improve discoverability** — clear docs help new users find the right repo for their needs.
60
+
-**Improve adoption** — lower the barrier to entry through installation guides, concept explanations, API overviews, and a structured learning path.
61
+
62
+
This repo does not introduce new math, algorithms, or notebook content. Its role is to organize, explain, and guide.
17
63
18
64
---
19
65
20
-
## Local Development
66
+
## How to Run Locally
21
67
22
68
Install dependencies and run the local development server:
23
69
@@ -41,20 +87,3 @@ Output is written to the `site/` directory (excluded from version control).
41
87
## Deployment
42
88
43
89
The site is automatically built and deployed to GitHub Pages on every push to `main` via the workflow in `.github/workflows/deploy.yml`.
44
-
45
-
Live site: `https://rqm-technologies-dev.github.io/rqm-docs/`
46
-
47
-
---
48
-
49
-
## Why This Repo Exists
50
-
51
-
As the RQM ecosystem has grown across multiple repositories — a core math library, a Qiskit execution bridge, and a suite of learning notebooks — the need for a unified documentation layer has become clear.
52
-
53
-
`rqm-docs` exists to:
54
-
55
-
-**Improve usability** — give users a single entry point to understand and navigate the full stack.
56
-
-**Improve credibility** — a professional documentation site signals that the ecosystem is maintained and production-worthy.
57
-
-**Improve discoverability** — clear docs help new users find the right repo for their needs, whether that is math, execution, or learning.
58
-
-**Improve adoption** — lower the barrier to entry by providing installation guides, concept explanations, API overviews, and a structured learning path.
59
-
60
-
This repo does not introduce new math, algorithms, or notebook content. Its role is to organize, explain, and guide.
RQM supports multiple execution backends. All backends consume the same `u1q` IR produced by `rqm-compiler`, so the same program runs on any backend without modification.
4
+
5
+
---
6
+
7
+
## Available Backends
8
+
9
+
| Backend | Package | Runtime |
10
+
|---|---|---|
11
+
|`"qiskit"`|`rqm-qiskit`| Qiskit Aer simulator / IBM hardware |
12
+
|`"braket"`|`rqm-braket`| Amazon Braket local simulator / AWS hardware |
[`rqm-qiskit`](https://github.com/RQM-Technologies-dev/rqm-qiskit) translates the `u1q` IR into Qiskit circuits and executes them on the Aer simulator or IBM hardware.
43
+
44
+
**Install:**
45
+
46
+
```bash
47
+
pip install rqm-qiskit
48
+
```
49
+
50
+
**Key class:**`QiskitBackend`
51
+
52
+
```python
53
+
from rqm_qiskit import QiskitBackend
54
+
55
+
backend = QiskitBackend()
56
+
result = backend.run_local(program) # local Aer simulator
57
+
result = backend.run_device(program, device="ibm_nairobi") # IBM hardware
[`rqm-braket`](https://github.com/RQM-Technologies-dev/rqm-braket) translates the `u1q` IR into Amazon Braket circuits and executes them locally or on AWS quantum hardware.
67
+
68
+
**Install:**
69
+
70
+
```bash
71
+
pip install rqm-braket
72
+
```
73
+
74
+
**Key class:**`BraketBackend`
75
+
76
+
```python
77
+
from rqm_braket import BraketBackend
78
+
79
+
backend = BraketBackend()
80
+
result = backend.run_local(program) # local simulator
81
+
result = backend.run_device(program, device_arn="arn:...") # AWS hardware
`rqm-api` is the user-facing API layer for the RQM ecosystem. It coordinates circuit intake, compilation, optional optimization, and backend dispatch in a single unified interface. This page provides an overview of its primary functions and usage patterns.
4
+
5
+
---
6
+
7
+
## Role of `rqm-api`
8
+
9
+
`rqm-api` is the top of the stack. It is the primary entry point for users who want to run circuits without managing individual layers:
1.**Backend dispatch** — route execution to the correct backend based on the `backend` argument
26
+
2.**Pipeline coordination** — invoke the compiler and optionally the optimizer before execution
27
+
3.**Result normalization** — return a consistent result object regardless of backend
28
+
29
+
---
30
+
31
+
## Modules
32
+
33
+
| Module | Responsibility |
34
+
|---|---|
35
+
|`rqm_api.run`| Top-level `run()` function for circuit execution |
36
+
|`rqm_api.result`|`Result` type returned by `run()`|
37
+
|`rqm_api.backends`| Backend registry and backend selection helpers |
38
+
39
+
---
40
+
41
+
## `rqm_api.run`
42
+
43
+
### `run`
44
+
45
+
Compiles and executes a circuit on the specified backend.
46
+
47
+
```python
48
+
from rqm_api import run
49
+
50
+
result = run(qc, backend="qiskit")
51
+
print(result.counts)
52
+
# {"00": 512, "11": 512}
53
+
```
54
+
55
+
**Parameters**:
56
+
-`circuit` — a `rqm_circuits.Circuit` object (or compatible gate list).
57
+
-`backend` — string backend name (`"qiskit"`, `"braket"`, `"pennylane"`) or a backend instance.
58
+
-`shots` — optional number of measurement shots (default: `1024`).
59
+
-`optimize` — optional boolean; if `True`, runs `rqm-optimize` before execution (default: `False`).
60
+
-`device` — optional device identifier for hardware execution (default: local simulator).
61
+
62
+
**Returns**: `rqm_api.result.Result` object.
63
+
64
+
---
65
+
66
+
## `rqm_api.result`
67
+
68
+
### `Result`
69
+
70
+
The normalized result object returned by `run()`.
71
+
72
+
```python
73
+
from rqm_api import run
74
+
75
+
result = run(qc, backend="braket")
76
+
77
+
print(result.counts) # {"00": 512, "11": 512}
78
+
print(result.backend) # "braket"
79
+
print(result.shots) # 1024
80
+
```
81
+
82
+
**Key attributes**:
83
+
84
+
| Attribute | Description |
85
+
|---|---|
86
+
|`counts`| Dict mapping bitstring to observation count |
87
+
|`backend`| Backend name used for execution |
88
+
|`shots`| Number of measurement shots |
89
+
|`metadata`| Dict with additional backend-specific metadata |
90
+
91
+
---
92
+
93
+
## Usage Examples
94
+
95
+
### Bell state on Qiskit
96
+
97
+
```python
98
+
from rqm_circuits import Circuit, Gate
99
+
from rqm_api import run
100
+
101
+
qc = Circuit(num_qubits=2)
102
+
qc.add(Gate("H", target=0))
103
+
qc.add(Gate("CNOT", control=0, target=1))
104
+
105
+
result = run(qc, backend="qiskit", shots=1024)
106
+
print(result.counts)
107
+
```
108
+
109
+
### Same circuit on Braket
110
+
111
+
```python
112
+
result = run(qc, backend="braket", shots=1024)
113
+
print(result.counts)
114
+
```
115
+
116
+
### Same circuit on PennyLane
117
+
118
+
```python
119
+
result = run(qc, backend="pennylane", shots=1024)
120
+
print(result.counts)
121
+
```
122
+
123
+
### With optimization
124
+
125
+
```python
126
+
result = run(qc, backend="qiskit", shots=1024, optimize=True)
127
+
print(result.counts)
128
+
```
129
+
130
+
---
131
+
132
+
!!! note "Full API Reference"
133
+
Auto-generated API documentation with full signatures, type annotations, and docstrings is planned for a future release. In the meantime, refer to the source code in the [`rqm-api` repository](https://github.com/RQM-Technologies-dev/rqm-api).
0 commit comments