Skip to content

Commit 56ae1b5

Browse files
RQM-Technologies-devRQM-Technologies-dev
authored
Merge pull request #10 from RQM-Technologies-dev/copilot/update-rqm-docs-for-onboarding
Introducing the RQM Optimization API for new users
2 parents b98379c + 7b8e7d2 commit 56ae1b5

4 files changed

Lines changed: 281 additions & 144 deletions

File tree

‎docs/api/quickstart.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# API Quickstart
2+
3+
Get your first optimized circuit in under 30 seconds.
4+
5+
**Base URL:** `https://rqm-api.onrender.com`
6+
7+
[:material-book-open-variant: Open Swagger UI](https://rqm-api.onrender.com/docs){ .md-button .md-button--primary }
8+
9+
---
10+
11+
## Endpoints Overview
12+
13+
| Endpoint | Method | Purpose |
14+
|---|---|---|
15+
| `/v1/circuits/optimize` | `POST` | **Primary** — optimize a circuit |
16+
| `/v1/circuits/example` | `GET` | Fetch a ready-to-use example circuit |
17+
| `/v1/circuits/validate` | `POST` | Validate a circuit payload |
18+
| `/v1/circuits/analyze` | `POST` | Analyze a circuit without optimizing |
19+
20+
---
21+
22+
## Step 1 — Fetch an example circuit
23+
24+
```bash
25+
curl https://rqm-api.onrender.com/v1/circuits/example
26+
```
27+
28+
Copy the returned JSON. It is a valid input for the `/optimize` endpoint.
29+
30+
---
31+
32+
## Step 2 — Optimize the circuit
33+
34+
Save the example JSON to a file:
35+
36+
```bash
37+
curl https://rqm-api.onrender.com/v1/circuits/example > example.json
38+
```
39+
40+
Then submit it for optimization:
41+
42+
```bash
43+
curl -X POST https://rqm-api.onrender.com/v1/circuits/optimize \
44+
-H "Content-Type: application/json" \
45+
-d @example.json
46+
```
47+
48+
The response includes the optimized circuit, gate count, depth, and an optimization report.
49+
50+
---
51+
52+
## Step 3 — Read the result
53+
54+
The response is structured as:
55+
56+
```json
57+
{
58+
"optimized_circuit": { ... },
59+
"gate_count_before": 12,
60+
"gate_count_after": 7,
61+
"depth_before": 8,
62+
"depth_after": 5,
63+
"report": { ... }
64+
}
65+
```
66+
67+
Refer to the [Swagger UI](https://rqm-api.onrender.com/docs) for the current response schema.
68+
69+
---
70+
71+
## Support Endpoints
72+
73+
### `POST /v1/circuits/validate`
74+
75+
Checks whether a circuit payload is well-formed before submitting for optimization.
76+
77+
```bash
78+
curl -X POST https://rqm-api.onrender.com/v1/circuits/validate \
79+
-H "Content-Type: application/json" \
80+
-d @example.json
81+
```
82+
83+
### `POST /v1/circuits/analyze`
84+
85+
Returns a structural analysis of the circuit (gate count, depth, gate types) without modifying it.
86+
87+
```bash
88+
curl -X POST https://rqm-api.onrender.com/v1/circuits/analyze \
89+
-H "Content-Type: application/json" \
90+
-d @example.json
91+
```
92+
93+
---
94+
95+
## Troubleshooting
96+
97+
**Error: `"instructions": ["string"]`**
98+
99+
This is the default Swagger placeholder. The `instructions` field must contain structured gate objects, not plain strings.
100+
101+
**Fix:** Use `GET /v1/circuits/example` to get a valid payload, then send that to `/optimize`.
102+
103+
---
104+
105+
## Next Steps
106+
107+
| Goal | Where to go |
108+
|---|---|
109+
| Full API schema | [Swagger UI](https://rqm-api.onrender.com/docs) |
110+
| API reference overview | [rqm-api docs](rqm-api-api.md) |
111+
| Platform architecture | [Ecosystem](../ecosystem.md) |
112+
| Theory and deep dives | [Concepts](../concepts.md) |
113+
| Python SDK quickstart | [SDK Quickstart](../quickstart.md) |

‎docs/api/rqm-api-api.md‎

Lines changed: 73 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -1,133 +1,121 @@
1-
# rqm-api API Guide
1+
# RQM Optimization API — Reference
22

3-
`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.
3+
`rqm-api` is the HTTP service for geometry-aware quantum circuit optimization. The primary endpoint is `POST /v1/circuits/optimize`.
44

5-
---
5+
**Base URL:** `https://rqm-api.onrender.com`
66

7-
## Role of `rqm-api`
7+
[:material-book-open-variant: Swagger UI](https://rqm-api.onrender.com/docs){ .md-button .md-button--primary }
8+
[:material-lightning-bolt: API Quickstart](quickstart.md){ .md-button }
89

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:
10+
---
1011

11-
```
12-
rqm-circuits (circuit object)
13-
→ rqm-api
14-
├── rqm-compiler (gate resolution → u1q IR)
15-
├── [optional] rqm-optimize (gate fusion, compression)
16-
└── backend dispatch
17-
├── rqm-qiskit
18-
├── rqm-braket
19-
└── rqm-pennylane
20-
→ result
21-
```
12+
## Primary Endpoint: `/v1/circuits/optimize`
2213

23-
Its responsibilities:
14+
**`POST /v1/circuits/optimize`**
2415

25-
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
16+
Upload a quantum circuit. Get back a measurably better one.
2817

29-
---
18+
What you get back:
3019

31-
## Modules
20+
- **Optimized circuit** — fewer gates, lower depth
21+
- **Gate count reduction** — before and after
22+
- **Depth reduction** — before and after
23+
- **Canonical structure** — SU(2)-normalized gate representation
24+
- **Optimization report** — structured summary of all transformations applied
3225

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 |
26+
```bash
27+
curl -X POST https://rqm-api.onrender.com/v1/circuits/optimize \
28+
-H "Content-Type: application/json" \
29+
-d @example.json
30+
```
3831

39-
---
32+
Use `GET /v1/circuits/example` to get a valid `example.json` payload.
4033

41-
## `rqm_api.run`
34+
---
4235

43-
### `run`
36+
## Support Endpoints
4437

45-
Compiles and executes a circuit on the specified backend.
38+
### `GET /v1/circuits/example`
4639

47-
```python
48-
from rqm_api import run
40+
Returns a ready-to-use example circuit payload. Use this to test `/optimize` without constructing a circuit manually.
4941

50-
result = run(qc, backend="qiskit")
51-
print(result.counts)
52-
# {"00": 512, "11": 512}
42+
```bash
43+
curl https://rqm-api.onrender.com/v1/circuits/example
5344
```
5445

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).
46+
### `POST /v1/circuits/validate`
6147

62-
**Returns**: `rqm_api.result.Result` object.
48+
Checks whether a circuit payload is well-formed. Use this before submitting to `/optimize` if you are constructing circuits programmatically.
6349

64-
---
50+
```bash
51+
curl -X POST https://rqm-api.onrender.com/v1/circuits/validate \
52+
-H "Content-Type: application/json" \
53+
-d @example.json
54+
```
6555

66-
## `rqm_api.result`
56+
### `POST /v1/circuits/analyze`
6757

68-
### `Result`
58+
Returns a structural analysis of the circuit (gate count, depth, gate types) without optimizing it.
6959

70-
The normalized result object returned by `run()`.
60+
```bash
61+
curl -X POST https://rqm-api.onrender.com/v1/circuits/analyze \
62+
-H "Content-Type: application/json" \
63+
-d @example.json
64+
```
7165

72-
```python
73-
from rqm_api import run
66+
---
67+
68+
## Role of `rqm-api`
7469

75-
result = run(qc, backend="braket")
70+
`rqm-api` is the top of the stack. It coordinates circuit intake, compilation, optimization, and result delivery:
7671

77-
print(result.counts) # {"00": 512, "11": 512}
78-
print(result.backend) # "braket"
79-
print(result.shots) # 1024
72+
```
73+
circuit input (JSON)
74+
→ rqm-api
75+
├── rqm-compiler (gate resolution → u1q IR)
76+
├── rqm-optimize (gate fusion, compression)
77+
└── result: optimized circuit + report
8078
```
8179

82-
**Key attributes**:
80+
Its responsibilities:
8381

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 |
82+
1. **Circuit intake** — accept and validate circuit payloads
83+
2. **Pipeline coordination** — invoke the compiler and optimizer
84+
3. **Result delivery** — return a structured response with optimized circuit and report
9085

9186
---
9287

93-
## Usage Examples
88+
## Python SDK
9489

95-
### Bell state on Qiskit
90+
The API is also accessible via the Python SDK. See [SDK Quickstart](../quickstart.md) for setup.
9691

9792
```python
98-
from rqm_circuits import Circuit, Gate
9993
from rqm_api import run
10094

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)
95+
result = run(qc, backend="qiskit", optimize=True)
10696
print(result.counts)
10797
```
10898

109-
### Same circuit on Braket
99+
**Parameters**:
100+
- `circuit` — a `rqm_circuits.Circuit` object (or compatible gate list).
101+
- `backend` — string backend name (`"qiskit"`, `"braket"`, `"pennylane"`) or a backend instance.
102+
- `shots` — optional number of measurement shots (default: `1024`).
103+
- `optimize` — optional boolean; if `True`, runs `rqm-optimize` before execution (default: `False`).
104+
- `device` — optional device identifier for hardware execution (default: local simulator).
105+
106+
**Returns**: `rqm_api.result.Result` object.
110107

111-
```python
112-
result = run(qc, backend="braket", shots=1024)
113-
print(result.counts)
114-
```
108+
---
115109

116-
### Same circuit on PennyLane
110+
## Troubleshooting
117111

118-
```python
119-
result = run(qc, backend="pennylane", shots=1024)
120-
print(result.counts)
121-
```
112+
**Error: `"instructions": ["string"]`**
122113

123-
### With optimization
114+
This is the default Swagger placeholder. The `instructions` field must contain structured gate objects, not plain strings.
124115

125-
```python
126-
result = run(qc, backend="qiskit", shots=1024, optimize=True)
127-
print(result.counts)
128-
```
116+
**Fix:** Use `GET /v1/circuits/example` to get a valid payload, then send that to `POST /v1/circuits/optimize`.
129117

130118
---
131119

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).
120+
!!! note "Full schema"
121+
For request/response schemas and field-level documentation, use the [Swagger UI](https://rqm-api.onrender.com/docs). Auto-generated Python API docs are 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

Comments
 (0)