Skip to content

Commit ac7ffbd

Browse files
RQM-Technologies-devRQM-Technologies-dev
authored
Merge pull request #21 from RQM-Technologies-dev/copilot/update-rqm-docs-to-reflect-current-state
Refresh docs for current RQM stack boundaries and product surface
2 parents c3c1b11 + 0a4b910 commit ac7ffbd

24 files changed

Lines changed: 1241 additions & 1630 deletions

‎README.md‎

Lines changed: 12 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,72 +1,27 @@
11
# rqm-docs
22

3-
**Official documentation hub for the RQM quantum computing platform.**
3+
**Official documentation hub for the current RQM Technologies stack.**
44

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.
5+
This site is built with [MkDocs](https://www.mkdocs.org/) and the [Material theme](https://squidfunk.github.io/mkdocs-material/) and is deployed from this repository.
66

7-
Live site: **[https://rqm-technologies-dev.github.io/rqm-docs/](https://rqm-technologies-dev.github.io/rqm-docs/)**
7+
Canonical docs URL: **[https://docs.rqmtechnologies.com/](https://docs.rqmtechnologies.com/)**
88

99
---
1010

11-
## The RQM Ecosystem
11+
## Scope
1212

13-
RQM is a compiler-first quantum software platform. The ecosystem is organized as a layered stack:
13+
`rqm-docs` documents the current platform layers reflected in this site:
1414

15-
```
16-
┌─────────────────────────────────────────────┐
17-
│ User Layer │
18-
│ rqm-api · rqm-circuits │
19-
└─────────────────┬───────────────────────────┘
20-
│
21-
┌─────────────────▼───────────────────────────┐
22-
│ Compiler Layer │
23-
│ rqm-compiler · rqm-optimize │
24-
└──────┬──────────────────────┬───────────────┘
25-
│ │
26-
┌──────▼──────┐ ┌────────────▼──┐ ┌────────────────┐
27-
│ rqm-qiskit │ │ rqm-braket │ │ rqm-pennylane │
28-
│ (Qiskit) │ │ (AWS Braket) │ │ (PennyLane) │
29-
└─────────────┘ └───────────────┘ └────────────────┘
30-
┌─────────────────────────────────────────────┐
31-
│ Foundation Layer │
32-
│ rqm-core │
33-
└─────────────────────────────────────────────┘
34-
```
35-
36-
| Repository | Layer | Role |
37-
|---|---|---|
38-
| [`rqm-api`](https://github.com/RQM-Technologies-dev/rqm-api) | User | High-level API for program submission and results |
39-
| [`rqm-circuits`](https://github.com/RQM-Technologies-dev/rqm-circuits) | User | Circuit construction: gates, registers, circuit objects |
40-
| [`rqm-compiler`](https://github.com/RQM-Technologies-dev/rqm-compiler) | Compiler | IR generation, gate normalization, `u1q` canonical lowering |
41-
| [`rqm-optimize`](https://github.com/RQM-Technologies-dev/rqm-optimize) | Compiler | SU(2)-aware gate fusion and circuit optimization |
42-
| [`rqm-qiskit`](https://github.com/RQM-Technologies-dev/rqm-qiskit) | Execution | Qiskit execution backend |
43-
| [`rqm-braket`](https://github.com/RQM-Technologies-dev/rqm-braket) | Execution | AWS Braket execution backend |
44-
| [`rqm-pennylane`](https://github.com/RQM-Technologies-dev/rqm-pennylane) | Execution | PennyLane integration backend |
45-
| [`rqm-core`](https://github.com/RQM-Technologies-dev/rqm-core) | Foundation | Canonical math: quaternions, spinors, Bloch vectors, SU(2) |
46-
| [`rqm-notebooks`](https://github.com/RQM-Technologies-dev/rqm-notebooks) | Learning | Jupyter notebooks: demos and guided learning path |
47-
| [`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.
15+
- `rqm-core` — mathematical spine
16+
- `rqm-compiler` — internal optimization and rewriting engine
17+
- `rqm-api` — canonical service boundary
18+
- `rqm-studio` — visual and workflow layer
19+
- `rqm-docs` — documentation layer
6320

6421
---
6522

6623
## How to Run Locally
6724

68-
Install dependencies and run the local development server:
69-
7025
```bash
7126
pip install -r requirements.txt
7227
mkdocs serve
@@ -77,7 +32,7 @@ The site will be available at `http://127.0.0.1:8000`.
7732
To build the static site:
7833

7934
```bash
80-
mkdocs build
35+
mkdocs build --strict
8136
```
8237

8338
Output is written to the `site/` directory (excluded from version control).
@@ -86,4 +41,4 @@ Output is written to the `site/` directory (excluded from version control).
8641

8742
## Deployment
8843

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+
The site is built and deployed by the GitHub Actions workflow in `.github/workflows/deploy.yml`.

‎docs/api/authentication.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Authentication
2+
3+
`rqm-api` uses a **bearer-session** model for authenticated account surfaces.
4+
5+
**Base URL:** `https://rqm-api.onrender.com`
6+
7+
---
8+
9+
## Current endpoints
10+
11+
- `GET /v1/auth/diagnostics`
12+
- `POST /v1/auth/register`
13+
- `POST /v1/auth/login`
14+
- `GET /v1/auth/me`
15+
- `POST /v1/auth/logout`
16+
17+
---
18+
19+
## Bearer-session model
20+
21+
The current docs describe auth as a session-bearing API surface rather than a public anonymous circuit-only interface.
22+
23+
In practice, authentication matters when a workflow needs:
24+
25+
- account identity
26+
- Pro/account state
27+
- billing and wallet visibility
28+
- dashboard access
29+
- managed execution flows tied to user state
30+
31+
That is why auth belongs in the canonical API overview, not as an afterthought.
32+
33+
---
34+
35+
## Endpoint roles
36+
37+
### `GET /v1/auth/diagnostics`
38+
Use this when checking whether the current deployment and auth configuration are behaving as expected.
39+
40+
### `POST /v1/auth/register`
41+
Creates an account or initiates the account-registration flow.
42+
43+
### `POST /v1/auth/login`
44+
Starts or refreshes an authenticated session.
45+
46+
### `GET /v1/auth/me`
47+
Returns the current authenticated identity and is the natural identity check for clients that need to know whether they should expose account-bound surfaces.
48+
49+
### `POST /v1/auth/logout`
50+
Ends the current authenticated session.
51+
52+
---
53+
54+
## Why auth matters beyond login
55+
56+
Authentication is the bridge between basic circuit workflows and managed product surfaces such as:
57+
58+
- Studio account views
59+
- Pro/account readiness
60+
- billing dashboard and wallet actions
61+
- quote / hold / release flows for hardware-oriented operations
62+
63+
Auth does **not** by itself grant hardware access. It simply establishes the account context required for those flows.

‎docs/api/backends.md‎

Lines changed: 25 additions & 130 deletions
Original file line numberDiff line numberDiff line change
@@ -1,149 +1,44 @@
1-
# Execution Backends
1+
# Backends
22

3-
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.
3+
RQM is **backend-agnostic at the public circuit boundary** and **explicit about backend targeting later**.
44

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 |
13-
| `"pennylane"` | `rqm-pennylane` | PennyLane default device / hardware plugins |
14-
15-
---
16-
17-
## Selecting a Backend
18-
19-
Pass the backend name string to `rqm_api.run`:
20-
21-
```python
22-
from rqm_api import run
23-
24-
result = run(qc, backend="qiskit")
25-
result = run(qc, backend="braket")
26-
result = run(qc, backend="pennylane")
27-
```
28-
29-
Or use a backend instance directly:
30-
31-
```python
32-
from rqm_qiskit import QiskitBackend
33-
34-
backend = QiskitBackend()
35-
result = run(qc, backend=backend)
36-
```
5+
This page documents backend families from the perspective of the current stack, not from the perspective of internal compiler IR.
376

387
---
398

40-
## rqm-qiskit
41-
42-
[`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
58-
```
59-
60-
**IR mapping:** `u1q` → Qiskit `U` gate (ZYZ decomposition)
61-
62-
---
63-
64-
## rqm-braket
65-
66-
[`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.
9+
## Current backend families exposed through the API
6710

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
82-
```
83-
84-
**IR mapping:** `u1q` → Braket arbitrary rotation gate
85-
86-
---
87-
88-
## rqm-pennylane
89-
90-
[`rqm-pennylane`](https://github.com/RQM-Technologies-dev/rqm-pennylane) provides a PennyLane integration, exposing RQM circuits as PennyLane devices and supporting differentiable quantum workflows.
91-
92-
**Install:**
93-
94-
```bash
95-
pip install rqm-pennylane
96-
```
97-
98-
**Key class:** `PennyLaneBackend`
99-
100-
```python
101-
from rqm_pennylane import PennyLaneBackend
102-
103-
backend = PennyLaneBackend()
104-
result = backend.run_local(program)
105-
```
11+
| Backend hint or route | Current role |
12+
|---|---|
13+
| `generic` | Backend-neutral optimization/output posture |
14+
| `qiskit` | Qiskit-facing optimization hint and execution route |
15+
| `braket` | Braket-facing optimization hint and execution route |
10616

107-
**IR mapping:** `u1q` → PennyLane native rotation operation
17+
At the API layer, these appear in optimization and execution workflows.
10818

10919
---
11020

111-
## Backend Interface Contract
112-
113-
All backends implement the same interface:
21+
## Important distinction
11422

115-
| Method | Description |
116-
|---|---|
117-
| `run_local(program)` | Execute on a local simulator |
118-
| `run_device(program, **kwargs)` | Execute on hardware |
23+
A backend hint on `/v1/circuits/optimize` is not the same thing as execution routing, and neither is the same thing as internal compiler IR.
11924

120-
All backends return a `Result` object with a `counts` attribute:
25+
RQM keeps these concerns separate:
12126

122-
```python
123-
result.counts # {"00": 512, "11": 512}
124-
```
125-
126-
This normalized contract means programs are fully portable across backends.
27+
1. public circuit intake
28+
2. internal optimization
29+
3. optional explicit backend lowering
30+
4. execution routing and readiness checks
12731

12832
---
12933

130-
## Swapping Backends
131-
132-
Swapping backends requires only one change:
133-
134-
```python
135-
# Before
136-
result = run(qc, backend="qiskit")
34+
## What to document conservatively
13735

138-
# After
139-
result = run(qc, backend="braket")
140-
```
36+
- some backend-hint behavior may be reserved or equivalent in the current release
37+
- execution availability should be inspected through capabilities, not assumed from a backend name alone
38+
- hardware-oriented flows still depend on provider readiness, credentials, and billing state
14139

142-
The circuit, compiler pipeline, and result interface are identical in both cases.
143-
144-
---
40+
See:
14541

146-
!!! tip "See also"
147-
- [Quickstart](../quickstart.md) — minimal working example
148-
- [rqm-api API guide](rqm-api-api.md) — full `run()` function reference
149-
- [Canonical IR (u1q)](../compiler/canonical-ir.md) — how backends consume the IR
42+
- [Execution](execution.md)
43+
- [Execution Capabilities](execution-capabilities.md)
44+
- [Optimization](../optimization.md)

0 commit comments

Comments
 (0)