Notebooks and Learning Path¶
rqm-notebooks is the primary learning interface for the RQM ecosystem. It provides a structured sequence of Jupyter notebooks that guide users from first principles through practical quantum circuit execution.
Notebooks are conceptual
The notebooks illustrate mathematical ideas and platform workflows. They are not production deployment patterns. For running circuits in a production context, use rqm-api and rqm-circuits as described in the Quickstart.
Role of rqm-notebooks¶
The notebooks serve three purposes:
- Demonstration — show how
rqm-core,rqm-circuits, and the execution backends work together in realistic scenarios. - Explanation — provide prose, equations, and visualizations that connect the math to the code.
- Exploration — offer runnable examples that users can modify and extend.
Notebooks are the main learning interface for the ecosystem. They are not a substitute for the API documentation, but they are the best starting point for building intuition.
Learning Path¶
Follow this structured sequence to move from introductory concepts to full circuit execution.
Step 1: Foundations (Notebooks 00–02)¶
These notebooks introduce the core mathematical objects: quaternions, spinors, and Bloch vectors. No Qiskit knowledge is required.
| Notebook | Topic |
|---|---|
00_quaternion_basics.ipynb |
Quaternion representation and multiplication |
01_spinors_and_bloch.ipynb |
Spinor states and their Bloch sphere interpretation |
02_su2_rotations.ipynb |
SU(2) group elements and rotation matrices |
Goal: Understand the objects that rqm-core operates on.
Theory reference
Notebook 00_quaternion_basics demonstrates that quaternion multiplication composes rotations. For the exact mathematical basis — including why this is equivalent to gate composition on S³ — see Complete Quaternion Theory, Section 10: Why quaternion multiplication models gate composition.
Step 2: Core Library Workflows (Notebooks 03–05)¶
These notebooks demonstrate the rqm-core API directly — normalization, conversion, and geometric operations.
| Notebook | Topic |
|---|---|
03_spinor_normalization.ipynb |
Using spinor.normalize_spinor and related utilities |
04_bloch_conversions.ipynb |
Converting between spinors, Bloch vectors, and quaternions |
05_su2_construction.ipynb |
Building SU(2) matrices from quaternion parameters |
Goal: Become fluent with the rqm-core API.
Step 3: Ecosystem Architecture (Notebook 10)¶
This notebook provides a high-level tour of the full ecosystem stack — how the repos relate to each other and how data flows from rqm-circuits through rqm-compiler to a circuit result.
| Notebook | Topic |
|---|---|
10_ecosystem_architecture.ipynb |
Full stack walkthrough: circuits → compiler → backend → result |
Goal: Understand the architecture in code, not just diagrams.
Step 4: Execution Workflows¶
These notebooks use rqm-circuits and rqm-api to construct and run circuits on execution backends.
| Notebook | Topic |
|---|---|
20_state_preparation.ipynb |
Preparing quantum states from RQM spinors |
21_gate_construction.ipynb |
Building circuits from SU(2) matrices |
22_simulation_and_results.ipynb |
Running circuits and interpreting results |
Goal: Execute real quantum circuits using RQM geometry objects.
Running the Notebooks¶
Clone the repository and launch Jupyter:
git clone https://github.com/RQM-Technologies-dev/rqm-notebooks.git
cd rqm-notebooks
pip install -r requirements.txt
jupyter lab
Open notebooks in the numbered order for the best learning experience.
Prerequisites
Steps 1 and 2 require only rqm-core. Steps 3 and 4 require rqm-circuits, rqm-api, and an execution backend. See the installation guide for setup instructions.