Skip to content

Commit 1d3b2c2

Browse files
WeiguoMaWeiguoMa
committed
add tutorials in both chinese and english for quditcircuit.
1 parent 7252970 commit 1d3b2c2

File tree

2 files changed

+539
-90
lines changed

2 files changed

+539
-90
lines changed

‎docs/source/tutorials/circuit_qudit_basics.ipynb‎

Lines changed: 95 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -18,12 +18,11 @@
1818
"\n",
1919
"## Overview\n",
2020
"\n",
21-
"This tutorial shows how to build and simulate **qudit** circuits (d‑level systems, where `d ≥ 3`) using `tensorcircuit`'s `QuditCircuit` API. It mirrors the structure of the classic *Circuit Basics* notebook but focuses on **qutrits and higher**.\n",
22-
"\n",
21+
"This tutorial shows how to build and simulate **qudit** circuits (d‑level systems, where `d ≥ 3`) using `tensorcircuit`'s `QuditCircuit` API.\n",
2322
"**Highlights**\n",
2423
"- Create a `QuditCircuit(nqudits, dim)` with dimension `dim ∈ [3, 36]`.\n",
25-
"- Use generalized gates: `X`, `Z`, `H`, rotations `RX/RY/RZ` on selected levels `(j, k)`.\n",
26-
"- Two‑qudit interactions: `RXX`, `RZZ`, and the generalized controlled‑sum `CSUM` and controlled-phase `CPHASE`.\n",
24+
"- Single-qudit gates: `X`, `Z`, `H`, rotations `RX/RY/RZ` on selected levels `(j, k)`.\n",
25+
"- Two‑qudit gates: `RXX`, `RZZ`, and the generalized controlled‑sum `CSUM` and controlled-phase `CPHASE`.\n",
2726
"- Obtain wavefunctions, probabilities, samples, expectations, and sub‑system projections.\n",
2827
"- Samples and bitstrings use base‑36 digits (`0–9A–Z`) where `A = 10, ..., Z = 35`.\n"
2928
]
@@ -42,8 +41,8 @@
4241
"id": "8f2d9565",
4342
"metadata": {
4443
"ExecuteTime": {
45-
"end_time": "2025-09-10T09:52:45.586900Z",
46-
"start_time": "2025-09-10T09:52:45.584017Z"
44+
"end_time": "2025-09-10T10:32:59.941117Z",
45+
"start_time": "2025-09-10T10:32:58.690552Z"
4746
}
4847
},
4948
"source": [
@@ -62,7 +61,7 @@
6261
]
6362
}
6463
],
65-
"execution_count": 30
64+
"execution_count": 1
6665
},
6766
{
6867
"cell_type": "markdown",
@@ -72,23 +71,23 @@
7271
"\n",
7372
"## Hello, Qutrit! (dim = 13)\n",
7473
"\n",
75-
"We'll prepare a **single qutrit** (`nqudits=1`, `dim=3`), apply a generalized Hadamard `H` to put it into an equal superposition, and inspect the resulting state and probabilities.\n"
74+
"We'll prepare a **single qudit** (`nqudits=1`, `dim=13`), apply a generalized Hadamard `H` to put it into an equal superposition, and inspect the resulting state and probabilities.\n"
7675
]
7776
},
7877
{
7978
"cell_type": "code",
8079
"id": "3fa13efe",
8180
"metadata": {
8281
"ExecuteTime": {
83-
"end_time": "2025-09-10T09:52:46.860189Z",
84-
"start_time": "2025-09-10T09:52:46.856020Z"
82+
"end_time": "2025-09-10T10:33:00.001551Z",
83+
"start_time": "2025-09-10T10:32:59.998454Z"
8584
}
8685
},
8786
"source": [
8887
"c = QuditCircuit(nqudits=1, dim=13)\n",
8988
"c.h(0) # generalized Hadamard on the only qudit\n",
90-
"psi = c.wavefunction() # state vector of length 13^1 = 13\n",
91-
"probs = c.probability() # probability vector (length 3)\n",
89+
"psi = c.wavefunction() # state vector of length 13^1 = 13\n",
90+
"probs = c.probability() # probability vector (length 3)\n",
9291
"print(r\"\\psi:\", psi)\n",
9392
"print(\"P:\", probs)"
9493
],
@@ -106,7 +105,7 @@
106105
]
107106
}
108107
],
109-
"execution_count": 31
108+
"execution_count": 2
110109
},
111110
{
112111
"cell_type": "markdown",
@@ -118,22 +117,22 @@
118117
"\n",
119118
"Let's move to **two qutrits** and create a maximally entangled state using `H` and the qudit controlled‑sum `CSUM`.\n",
120119
"\n",
121-
"The operator `CSUM(control, target, cv=None)` adds the control's value to the target modulo `dim`. It's a natural generalization of CNOT. If you pass `cv`, the gate activates only when the control equals that value (default is `1`).\n"
120+
"The operator `CSUM(control, target, cv=None)` adds the control's value to the target modulo `dim`. It's a natural generalization of CNOT. If you pass `cv`, the gate activates only when the control equals that value (default is `None`).\n"
122121
]
123122
},
124123
{
125124
"cell_type": "code",
126125
"id": "c53a755e",
127126
"metadata": {
128127
"ExecuteTime": {
129-
"end_time": "2025-09-10T09:52:49.285065Z",
130-
"start_time": "2025-09-10T09:52:49.281466Z"
128+
"end_time": "2025-09-10T10:33:00.018234Z",
129+
"start_time": "2025-09-10T10:33:00.014110Z"
131130
}
132131
},
133132
"source": [
134-
"cq = QuditCircuit(nqudits=2, dim=3) # two qutrits\n",
135-
"cq.h(0) # superpose control\n",
136-
"cq.csum(0, 1) # qudit CNOT analog (control=0, target=1)\n",
133+
"cq = QuditCircuit(nqudits=2, dim=3) # two qutrits\n",
134+
"cq.h(0) # superpose control\n",
135+
"cq.csum(0, 1) # qudit CNOT analog (control=0, target=1)\n",
137136
"psi = cq.wavefunction()\n",
138137
"probs = cq.probability()\n",
139138
"print(r\"|\\psi|^2 (length 3^2=9):\", probs)"
@@ -148,7 +147,7 @@
148147
]
149148
}
150149
],
151-
"execution_count": 32
150+
"execution_count": 3
152151
},
153152
{
154153
"cell_type": "markdown",
@@ -166,28 +165,27 @@
166165
"id": "6542deab",
167166
"metadata": {
168167
"ExecuteTime": {
169-
"end_time": "2025-09-10T09:53:30.797350Z",
170-
"start_time": "2025-09-10T09:53:30.502390Z"
168+
"end_time": "2025-09-10T10:33:00.335589Z",
169+
"start_time": "2025-09-10T10:33:00.031885Z"
171170
}
172171
},
173172
"source": [
174-
"\n",
175173
"samples = cq.sample(batch=512, format=\"count_dict_bin\") # e.g., '00', '11', '22'\n",
176-
"samples\n"
174+
"samples"
177175
],
178176
"outputs": [
179177
{
180178
"data": {
181179
"text/plain": [
182-
"{'00': 180, '11': 167, '22': 165}"
180+
"{'00': 160, '11': 171, '22': 181}"
183181
]
184182
},
185-
"execution_count": 37,
183+
"execution_count": 4,
186184
"metadata": {},
187185
"output_type": "execute_result"
188186
}
189187
],
190-
"execution_count": 37
188+
"execution_count": 4
191189
},
192190
{
193191
"cell_type": "markdown",
@@ -211,17 +209,17 @@
211209
"id": "e4e2b769",
212210
"metadata": {
213211
"ExecuteTime": {
214-
"end_time": "2025-09-10T09:54:39.562209Z",
215-
"start_time": "2025-09-10T09:54:39.556487Z"
212+
"end_time": "2025-09-10T10:33:00.350793Z",
213+
"start_time": "2025-09-10T10:33:00.346566Z"
216214
}
217215
},
218216
"source": [
219217
"import numpy as np\n",
220218
"\n",
221-
"c = QuditCircuit(nqudits=1, dim=5) # a ququint\n",
222-
"c.h(0) # start in equal superposition\n",
223-
"c.rx(0, theta=np.pi/3, j=1, k=3) # rotate levels 1 and 3\n",
224-
"c.rz(0, theta=np.pi/5, j=4) # add a phase to level 4\n",
219+
"c = QuditCircuit(nqudits=1, dim=5) # a ququint\n",
220+
"c.h(0) # start in equal superposition\n",
221+
"c.rx(0, theta=np.pi / 3, j=1, k=3) # rotate levels 1 and 3\n",
222+
"c.rz(0, theta=np.pi / 5, j=4) # add a phase to level 4\n",
225223
"psi = c.wavefunction()\n",
226224
"probs = c.probability()\n",
227225
"psi, probs"
@@ -237,12 +235,12 @@
237235
" dtype=float32))"
238236
]
239237
},
240-
"execution_count": 38,
238+
"execution_count": 5,
241239
"metadata": {},
242240
"output_type": "execute_result"
243241
}
244242
],
245-
"execution_count": 38
243+
"execution_count": 5
246244
},
247245
{
248246
"cell_type": "markdown",
@@ -265,15 +263,16 @@
265263
"id": "a56be75e",
266264
"metadata": {
267265
"ExecuteTime": {
268-
"end_time": "2025-09-10T09:54:46.472203Z",
269-
"start_time": "2025-09-10T09:54:46.468063Z"
266+
"end_time": "2025-09-10T10:33:00.361091Z",
267+
"start_time": "2025-09-10T10:33:00.357370Z"
270268
}
271269
},
272270
"source": [
273-
"c2 = QuditCircuit(nqudits=2, dim=4) # two ququarts\n",
274-
"c2.h(0); c2.h(1)\n",
275-
"c2.rxx(0, 1, theta=np.pi/4, j1=0, k1=2, j2=1, k2=3)\n",
276-
"c2.rzz(0, 1, theta=np.pi/7, j1=0, k1=1, j2=0, k2=1)\n",
271+
"c2 = QuditCircuit(nqudits=2, dim=4) # two ququarts\n",
272+
"c2.h(0)\n",
273+
"c2.h(1)\n",
274+
"c2.rxx(0, 1, theta=np.pi / 4, j1=0, k1=2, j2=1, k2=3)\n",
275+
"c2.rzz(0, 1, theta=np.pi / 7, j1=0, k1=1, j2=0, k2=1)\n",
277276
"c2.probability()"
278277
],
279278
"outputs": [
@@ -285,12 +284,12 @@
285284
" dtype=float32)"
286285
]
287286
},
288-
"execution_count": 39,
287+
"execution_count": 6,
289288
"metadata": {},
290289
"output_type": "execute_result"
291290
}
292291
],
293-
"execution_count": 39
292+
"execution_count": 6
294293
},
295294
{
296295
"cell_type": "markdown",
@@ -308,13 +307,14 @@
308307
"id": "fe4ed499",
309308
"metadata": {
310309
"ExecuteTime": {
311-
"end_time": "2025-09-10T09:55:01.754737Z",
312-
"start_time": "2025-09-10T09:55:01.750563Z"
310+
"end_time": "2025-09-10T10:33:00.372256Z",
311+
"start_time": "2025-09-10T10:33:00.367671Z"
313312
}
314313
},
315314
"source": [
316315
"# Example: build a diagonal operator on a single qutrit (dim=3)\n",
317316
"import numpy as np\n",
317+
"\n",
318318
"c = QuditCircuit(1, dim=3)\n",
319319
"c.h(0)\n",
320320
"op = np.diag([0.0, 0.5, 1.0]) # acts on subspace levels 0,1,2\n",
@@ -328,12 +328,12 @@
328328
"array(0.49999997+0.j, dtype=complex64)"
329329
]
330330
},
331-
"execution_count": 41,
331+
"execution_count": 7,
332332
"metadata": {},
333333
"output_type": "execute_result"
334334
}
335335
],
336-
"execution_count": 41
336+
"execution_count": 7
337337
},
338338
{
339339
"metadata": {},
@@ -348,8 +348,8 @@
348348
{
349349
"metadata": {
350350
"ExecuteTime": {
351-
"end_time": "2025-09-10T09:59:59.378191Z",
352-
"start_time": "2025-09-10T09:59:46.147228Z"
351+
"end_time": "2025-09-10T10:33:14.972605Z",
352+
"start_time": "2025-09-10T10:33:00.385060Z"
353353
}
354354
},
355355
"cell_type": "code",
@@ -367,50 +367,50 @@
367367
{
368368
"data": {
369369
"text/plain": [
370-
"{'00': 33,\n",
371-
" '11': 26,\n",
372-
" '22': 30,\n",
373-
" '33': 35,\n",
370+
"{'00': 29,\n",
371+
" '11': 35,\n",
372+
" '22': 29,\n",
373+
" '33': 41,\n",
374374
" '44': 25,\n",
375-
" '55': 31,\n",
376-
" '66': 27,\n",
377-
" '77': 36,\n",
378-
" '88': 31,\n",
379-
" '99': 39,\n",
380-
" 'AA': 32,\n",
381-
" 'BB': 32,\n",
382-
" 'CC': 36,\n",
383-
" 'DD': 29,\n",
384-
" 'EE': 22,\n",
385-
" 'FF': 26,\n",
386-
" 'GG': 28,\n",
387-
" 'HH': 24,\n",
388-
" 'II': 20,\n",
389-
" 'JJ': 27,\n",
390-
" 'KK': 24,\n",
391-
" 'LL': 39,\n",
392-
" 'MM': 23,\n",
393-
" 'NN': 40,\n",
394-
" 'OO': 22,\n",
395-
" 'PP': 18,\n",
396-
" 'QQ': 25,\n",
397-
" 'RR': 27,\n",
398-
" 'SS': 28,\n",
399-
" 'TT': 24,\n",
400-
" 'UU': 28,\n",
401-
" 'VV': 29,\n",
402-
" 'WW': 21,\n",
403-
" 'XX': 29,\n",
404-
" 'YY': 30,\n",
405-
" 'ZZ': 28}"
375+
" '55': 28,\n",
376+
" '66': 28,\n",
377+
" '77': 35,\n",
378+
" '88': 32,\n",
379+
" '99': 27,\n",
380+
" 'AA': 38,\n",
381+
" 'BB': 35,\n",
382+
" 'CC': 29,\n",
383+
" 'DD': 31,\n",
384+
" 'EE': 30,\n",
385+
" 'FF': 22,\n",
386+
" 'GG': 26,\n",
387+
" 'HH': 19,\n",
388+
" 'II': 26,\n",
389+
" 'JJ': 24,\n",
390+
" 'KK': 37,\n",
391+
" 'LL': 27,\n",
392+
" 'MM': 34,\n",
393+
" 'NN': 27,\n",
394+
" 'OO': 31,\n",
395+
" 'PP': 31,\n",
396+
" 'QQ': 28,\n",
397+
" 'RR': 26,\n",
398+
" 'SS': 23,\n",
399+
" 'TT': 27,\n",
400+
" 'UU': 32,\n",
401+
" 'VV': 27,\n",
402+
" 'WW': 19,\n",
403+
" 'XX': 27,\n",
404+
" 'YY': 22,\n",
405+
" 'ZZ': 17}"
406406
]
407407
},
408-
"execution_count": 52,
408+
"execution_count": 8,
409409
"metadata": {},
410410
"output_type": "execute_result"
411411
}
412412
],
413-
"execution_count": 52
413+
"execution_count": 8
414414
},
415415
{
416416
"cell_type": "markdown",
@@ -431,12 +431,17 @@
431431
]
432432
},
433433
{
434-
"metadata": {},
434+
"metadata": {
435+
"ExecuteTime": {
436+
"end_time": "2025-09-10T10:33:14.985131Z",
437+
"start_time": "2025-09-10T10:33:14.983579Z"
438+
}
439+
},
435440
"cell_type": "code",
436-
"outputs": [],
437-
"execution_count": null,
438441
"source": "",
439-
"id": "9a33f318814fa510"
442+
"id": "9a33f318814fa510",
443+
"outputs": [],
444+
"execution_count": null
440445
}
441446
],
442447
"metadata": {},

0 commit comments

Comments
 (0)