From 73b069f47a351efea572bcfa81262dd25424df72 Mon Sep 17 00:00:00 2001 From: Rajarshi Tiwari Date: Fri, 24 Apr 2026 13:15:48 +0100 Subject: [PATCH 1/9] doc update --- docs/index.md | 171 ++++++++++++++++++++++++++++++++++--------- qse/calc/__init__.py | 8 +- qse/calc/myqlm.py | 22 +++++- 3 files changed, 160 insertions(+), 41 deletions(-) diff --git a/docs/index.md b/docs/index.md index b71daa09..fdcfde05 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,20 +12,145 @@ mystnb: render_markdown_format: myst --- -# QSE +# Quantum Simulation Environment (QSE) -The Quantum Simulation Environment (QSE) package is intended to provide a flexible, -modular way to frame a quantum simulation problem involving position-dependent quantum degrees of freedom. -Primarily we look at a collection of qubits at given set of coordinates. These can be arbitrary coordinates, or defined on a lattice. +The **Quantum Simulation Environment (QSE)** is a flexible, modular, high-level Python library designed to +decouple the essence of the quantum simulation problem from the technicalities of the backend software/hardware. -QSE's design is adapted from Atomic Simulation Environment (ASE) to suit the needs -for an abstract representation for -1. **defining quantum computing systems** -2. **computing operations/simulations** +## 🎯 The Philosophy: Separation of Concerns + +The core value of QSE is the strict separation between **Problem Framing** and **Problem Execution** + +| Phase | Responsibility | User Focus | +| ----------------- | -------------------- | ---------- | +| Problem Framing | `Qbits` & `Lattices` | Defining geometry, positions, and quantum degrees of freedom. | +| Backend Execution | `Calculators` | Handling SDK-specific syntax, hardware constraints, and simulators. | + +```{admonition} Why this matters: +:class: note + +1. **Backend Agnostic:** Frame your problem once; simulate it on Pulser, myQLM, or QuTiP just by switching one line of code. +2. **No More "Jargon":** You don't need to learn the specific pulse sequences or gate-level syntax of every vendor to get started. You focus on the lattice and the physics. +3. **Reproducibility:** Your problem definition remains a "clean" representation of the physical model, making it easier to share and verify across different research groups. +``` + +## Architectural Overview + +QSE organizes these concerns into modular components. The user interacts primarily +with the `Qbits` and `Lattices` to frame the problem, then attaches a `Calculator`. -in a vendor and backend agnostic way. ASE's modular nature, and extensibility make it very useful for a similar quantum computing application. -Below is the visual organization of the components of QSE. + +```{mermaid} +graph TD + subgraph Framing [Problem Framing - User Level] + Lattices --> Qbits + Utils --> Qbits + end + + subgraph Interface [The Connection] + Qbits --- Calculator + end + + subgraph Execution [Backend Execution - Jargon Level] + Calculator --> Pulser + Calculator --> MyQLM + Calculator --> Qutip + end +``` + +### Core Components + +#### 1. Framing the System (`Qbits`) + +`Qbits` class represents the spatial setup, where you define the "What.". +It is a collection of quantum degrees of freedom defined by their coordinates. +Instead of thinking about qubits as abstract indices in a register, you treat +them as physical entities with coordinates. + +- Arbitrary Coordinates: Place qubits exactly where you need them. +- Lattice Generation: Quickly build 2D/3D grids (Square, Kagome, Triangular, etc.). + +#### 2. Solving the Problem (`Calculator`) + +The `Calculator` is a high-level wrapper. It defines the interaction between the +quantum degrees of freedom represented by the `Qbits`. Once Qbits are defined, +you "attach" them to a calculator. The calculator translates your physical setup +into the specific language required by the backend (e.g., Pulser's pulses or QuTiP's Hamiltonians). + +## Quick Start: Defining a Lattice + +This example shows how easily a physical system on a lattice can be defined without any +backend specific code. + +```{code-cell} +import qse + +# 1. Frame the problem: Create a 4x4 square lattice +qsqr = qse.lattices.square( + lattice_spacing=2.0, + repeats_x=4, repeats_y=4) + +# 2. Visualise the lattice +qsqr.draw(radius=5.0) + +# 3. Choose your backend calculator +# calc = qse.calc.Pulser(...) +# calc.qbits = qsqr # attach the system +``` + +### Qbits + +`Qbit` is the smallest class that represents just one qubits. `Qbits` is the primary class that represents a collection of qubits. +It can be instantiated by providing a list of coordinates, or as an empty class. +See the [Qbits examples](https://ichec.github.io/qse/tutorials/creating_and_manipulating_qbits.html) for more details. + +### Calculator + +Calculators are high level wrappers that let us offload the quantum problem to several backends. +Currently the list of backends supported are following, and they largely support analog quantum +simulation. + +- [Pulser](https://pulser.readthedocs.io/en/stable/), +- [myQLM](https://myqlm.github.io/), and +- [Qutip](https://qutip.org/) + + +## 📍Position-Dependent Quantum Degrees of Freedom + +Unlike standard gate-based frameworks where qubits are abstract entities in a register, QSE treats qubits as physical objects with coordinates. This is crucial for simulations where the interaction strength between qubits is a function of their spatial separation. + +### Why Positions Matter + +In many physical implementations of quantum simulators—such as Rydberg Atom Arrays or Trapped Ions—the Hamiltonian of the system is governed by the distance Rij​ between qubits i and j: + +$$ +H = \sum_i \Omega_i\sigma_i^x - \sum_i \delta_i n_i + \sum_{i Date: Fri, 24 Apr 2026 13:42:41 +0100 Subject: [PATCH 2/9] reorganize --- docs/index.md | 114 +++++++++++++++++++++++++------------------------- 1 file changed, 57 insertions(+), 57 deletions(-) diff --git a/docs/index.md b/docs/index.md index fdcfde05..74b0f051 100644 --- a/docs/index.md +++ b/docs/index.md @@ -14,25 +14,33 @@ mystnb: # Quantum Simulation Environment (QSE) +```{important} +This project is under active development. +``` + The **Quantum Simulation Environment (QSE)** is a flexible, modular, high-level Python library designed to decouple the essence of the quantum simulation problem from the technicalities of the backend software/hardware. -## 🎯 The Philosophy: Separation of Concerns - -The core value of QSE is the strict separation between **Problem Framing** and **Problem Execution** - -| Phase | Responsibility | User Focus | -| ----------------- | -------------------- | ---------- | -| Problem Framing | `Qbits` & `Lattices` | Defining geometry, positions, and quantum degrees of freedom. | -| Backend Execution | `Calculators` | Handling SDK-specific syntax, hardware constraints, and simulators. | - -```{admonition} Why this matters: -:class: note +```{mermaid} +:config: {"layout": "tidy-tree"} -1. **Backend Agnostic:** Frame your problem once; simulate it on Pulser, myQLM, or QuTiP just by switching one line of code. -2. **No More "Jargon":** You don't need to learn the specific pulse sequences or gate-level syntax of every vendor to get started. You focus on the lattice and the physics. -3. **Reproducibility:** Your problem definition remains a "clean" representation of the physical model, making it easier to share and verify across different research groups. +mindmap + root((QSE)) + Qbits + Qbit + Cell + Calculator + Pulser + MyQLM + Qutip + Utils + Magnetic + Signals + lattices + 2D + 3D + Visualise ``` ## Architectural Overview @@ -40,25 +48,6 @@ The core value of QSE is the strict separation between **Problem Framing** and * QSE organizes these concerns into modular components. The user interacts primarily with the `Qbits` and `Lattices` to frame the problem, then attaches a `Calculator`. - -```{mermaid} -graph TD - subgraph Framing [Problem Framing - User Level] - Lattices --> Qbits - Utils --> Qbits - end - - subgraph Interface [The Connection] - Qbits --- Calculator - end - - subgraph Execution [Backend Execution - Jargon Level] - Calculator --> Pulser - Calculator --> MyQLM - Calculator --> Qutip - end -``` - ### Core Components #### 1. Framing the System (`Qbits`) @@ -116,6 +105,41 @@ simulation. - [Qutip](https://qutip.org/) +```{mermaid} +graph LR + subgraph Framing [Problem Framing] + Lattices --> Qbits + Utils --> Qbits + end + + subgraph Interface [The Connection] + Qbits --- Calculator + end + + subgraph Execution [Backend Execution] + Calculator ---> Pulser + Calculator ---> MyQLM + Calculator ---> Qutip + end +``` + +## 🎯 The Philosophy: Separation of Concerns + +The core value of QSE is the strict separation between **Problem Framing** and **Problem Execution** + +| Phase | Responsibility | User Focus | +| ----------------- | -------------------- | ---------- | +| Problem Framing | `Qbits` & `Lattices` | Defining geometry, positions, and quantum degrees of freedom. | +| Backend Execution | `Calculators` | Handling SDK-specific syntax, hardware constraints, and simulators. | + +```{admonition} Why this matters: +:class: note + +1. **Backend Agnostic:** Frame your problem once; simulate it on Pulser, myQLM, or QuTiP just by switching one line of code. +2. **No More "Jargon":** You don't need to learn the specific pulse sequences or gate-level syntax of every vendor to get started. You focus on the lattice and the physics. +3. **Reproducibility:** Your problem definition remains a "clean" representation of the physical model, making it easier to share and verify across different research groups. +``` + ## 📍Position-Dependent Quantum Degrees of Freedom Unlike standard gate-based frameworks where qubits are abstract entities in a register, QSE treats qubits as physical objects with coordinates. This is crucial for simulations where the interaction strength between qubits is a function of their spatial separation. @@ -152,30 +176,6 @@ By keeping the problem definition independent of the backend, QSE ensures that t remains portable even as the quantum hardware landscape changes. ``` -```{mermaid} -:config: {"layout": "tidy-tree"} - -mindmap - root((QSE)) - Qbits - Qbit - Cell - Calculator - Pulser - MyQLM - Qutip - Utils - Magnetic - Signals - lattices - 2D - 3D - Visualise -``` -```{note} - -This project is under active development. -``` From 35efa2106ae3be54fe40f7a2cdf7cc7d843503c1 Mon Sep 17 00:00:00 2001 From: Rajarshi Tiwari Date: Fri, 24 Apr 2026 14:35:45 +0100 Subject: [PATCH 3/9] Update docs/index.md Co-authored-by: sherryblair <77493674+sherryblair@users.noreply.github.com> --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 74b0f051..100f8111 100644 --- a/docs/index.md +++ b/docs/index.md @@ -90,7 +90,7 @@ qsqr.draw(radius=5.0) ### Qbits -`Qbit` is the smallest class that represents just one qubits. `Qbits` is the primary class that represents a collection of qubits. +`Qbit` is the smallest class that represents just one qubit. `Qbits` is the primary class that represents a collection of qubits. It can be instantiated by providing a list of coordinates, or as an empty class. See the [Qbits examples](https://ichec.github.io/qse/tutorials/creating_and_manipulating_qbits.html) for more details. From d2d3f8cdbc5c3e2a249800569492a69ebf1f0e06 Mon Sep 17 00:00:00 2001 From: Rajarshi Tiwari Date: Fri, 24 Apr 2026 14:36:18 +0100 Subject: [PATCH 4/9] Update docs/index.md Co-authored-by: sherryblair <77493674+sherryblair@users.noreply.github.com> --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 100f8111..07843dad 100644 --- a/docs/index.md +++ b/docs/index.md @@ -146,7 +146,7 @@ Unlike standard gate-based frameworks where qubits are abstract entities in a re ### Why Positions Matter -In many physical implementations of quantum simulators—such as Rydberg Atom Arrays or Trapped Ions—the Hamiltonian of the system is governed by the distance Rij​ between qubits i and j: +In many physical implementations of quantum simulators—such as Rydberg Atom Arrays or Trapped Ions—the Hamiltonian of the system is governed by the distance $R_{ij}​=|{\bf R}_i - {\bf R}_j|$ between qubits $i$ and $j$: $$ H = \sum_i \Omega_i\sigma_i^x - \sum_i \delta_i n_i + \sum_{i Date: Fri, 24 Apr 2026 14:36:37 +0100 Subject: [PATCH 5/9] Update docs/index.md Co-authored-by: sherryblair <77493674+sherryblair@users.noreply.github.com> --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 07843dad..7b31810a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -157,7 +157,7 @@ In QSE, you don't manually calculate these interaction terms. By defining the sp #### The Mapping Process 1. **Define Geometry:** You place qubits in a 1D, 2D, or 3D arrangement. -2. **Assign Degrees of Freedom:** Each position is assigned quantum properties (e.g., ground and Rydberg states). +2. **Assign Degrees of Freedom:** Each qubit is assigned quantum properties (e.g., ground and Rydberg states). 3. **Automatic Interaction Mapping:** The `Calculator` uses the spatial data to build the interaction matrix (e.g., $\frac{1}{r^6}$ or $\frac {1}{r^3}$ scaling) specific to that backend’s hardware logic. ## Status & Contribution From c6b77d1bea24ca4ec06e080f8d9c30fde1c570ab Mon Sep 17 00:00:00 2001 From: Rajarshi Tiwari Date: Fri, 24 Apr 2026 14:36:50 +0100 Subject: [PATCH 6/9] Update docs/index.md Co-authored-by: sherryblair <77493674+sherryblair@users.noreply.github.com> --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 7b31810a..1723e18a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -163,7 +163,7 @@ In QSE, you don't manually calculate these interaction terms. By defining the sp ## Status & Contribution QSE is currently under active development (TRL 7-8). This project was initially developed and supported -by the HPCQS project and is a currently supported by the upcoming QEX project. We are focused on expanding +by the HPCQS project and is currently supported by the upcoming QEX project. We are focused on expanding our calculator suite to support more backends and post-processing tools. - **Target Users:** Scientific researchers in quantum optimization and many-body physics. From 1a543fee7dc0567b47b54679fcb6e956dd8029f1 Mon Sep 17 00:00:00 2001 From: Rajarshi Tiwari Date: Fri, 24 Apr 2026 14:41:39 +0100 Subject: [PATCH 7/9] Update qse/calc/myqlm.py Co-authored-by: emildi --- qse/calc/myqlm.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/qse/calc/myqlm.py b/qse/calc/myqlm.py index 2df4b132..1b481bb7 100644 --- a/qse/calc/myqlm.py +++ b/qse/calc/myqlm.py @@ -7,7 +7,7 @@ Ref: https://myqlm.github.io/ -`myqlm` is a software backend to potentially several quantum +`myqlm` is a software middleware to potentially several quantum hardware providers, such as Pasqal devices for analog quantum computing. From f2facf706dea04e595eab05652804010a4e2ad0d Mon Sep 17 00:00:00 2001 From: Rajarshi Tiwari Date: Fri, 24 Apr 2026 14:41:53 +0100 Subject: [PATCH 8/9] Update qse/calc/myqlm.py Co-authored-by: emildi --- qse/calc/myqlm.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/qse/calc/myqlm.py b/qse/calc/myqlm.py index 1b481bb7..989539fa 100644 --- a/qse/calc/myqlm.py +++ b/qse/calc/myqlm.py @@ -11,7 +11,7 @@ hardware providers, such as Pasqal devices for analog quantum computing. -It lets one offload an analog quantum workflow to myqlm backend +It lets one offload an analog quantum workflow to myqlm middleware which could be simulated ot real quantum device. It has been tested in HPC setting for simulated backend, and From 56e907e15f6e899b07c83189d78b7adf0cabea67 Mon Sep 17 00:00:00 2001 From: Rajarshi Tiwari Date: Fri, 24 Apr 2026 14:44:15 +0100 Subject: [PATCH 9/9] fix --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 1723e18a..b711a1c0 100644 --- a/docs/index.md +++ b/docs/index.md @@ -163,7 +163,7 @@ In QSE, you don't manually calculate these interaction terms. By defining the sp ## Status & Contribution QSE is currently under active development (TRL 7-8). This project was initially developed and supported -by the HPCQS project and is currently supported by the upcoming QEX project. We are focused on expanding +by the HPCQS project and is currently supported by the QEX project. We are focused on expanding our calculator suite to support more backends and post-processing tools. - **Target Users:** Scientific researchers in quantum optimization and many-body physics.