🌐 [translation-sync] Improve NumPy vs Numba vs JAX lecture (#96)

* Update translation: lectures/numpy_vs_numba_vs_jax.md

* Update translation: .translate/state/numpy_vs_numba_vs_jax.md.yml

Author: mmcky

.translate/state/numpy_vs_numba_vs_jax.md.yml

@@ -1,6 +1,6 @@
-source-sha: 05ce95691fd97e48da39dd6d58fe032c03e8813d
-synced-at: "2026-04-08"
+source-sha: 94dd7d22385ec46d740db1fc2cddf05c29377594
+synced-at: "2026-04-12"
 model: claude-sonnet-4-6
 mode: UPDATE
 section-count: 3
-tool-version: 0.13.1
+tool-version: 0.14.1

lectures/numpy_vs_numba_vs_jax.md

@@ -17,8 +17,6 @@ translation:
     Vectorized operations::Parallelized Numba: Numba موازی شده
     Vectorized operations::Vectorized code with JAX: کد برداری شده با JAX
     Vectorized operations::JAX plus vmap: JAX به علاوه vmap
-    Vectorized operations::JAX plus vmap::Version 1: نسخه 1
-    Vectorized operations::vmap version 2: نسخه 2 vmap
     Vectorized operations::Summary: خلاصه
     Sequential operations: عملیات ترتیبی
     Sequential operations::Numba Version: نسخه Numba
@@ -27,7 +25,7 @@ translation:
     Overall recommendations: توصیه‌های کلی
 ---
 
-(parallel)=
+(numpy_numba_jax)=
 ```{raw} jupyter
 <div id="qe-notebook-header" align="right" style="text-align:right;">
         <a href="https://quantecon.org/" title="quantecon.org">
@@ -150,7 +148,7 @@ for x in grid:
 
 در اینجا از `np.meshgrid` برای ایجاد شبکه‌های ورودی دوبعدی `x` و `y` استفاده می‌کنیم به گونه‌ای که `f(x, y)` تمام ارزیابی‌ها را روی شبکه حاصلضرب تولید می‌کند.
 
-(این استراتژی به Matlab بازمی‌گردد.)
+(این استراتژی به MATLAB بازمی‌گردد.)
 
 ```{code-cell} ipython3
 grid = np.linspace(-3, 3, 3_000)
@@ -226,24 +224,44 @@ def compute_max_numba_parallel(grid):
 
 ```
 
-معمولاً این نتیجه نادرستی برمی‌گرداند:
+این `-inf` برمی‌گرداند --- مقدار اولیه `m`، انگار که هرگز به‌روزرسانی نشده است:
 
 ```{code-cell} ipython3
 z_max_parallel_incorrect = compute_max_numba_parallel(grid)
 print(f"Numba result: {z_max_parallel_incorrect} 😱")
 ```
 
-دلیل این است که متغیر `m` بین نخ‌ها مشترک است و به درستی کنترل نمی‌شود.
+برای درک چرایی این موضوع، به یاد بیاورید که `prange` حلقه بیرونی را بین نخ‌ها تقسیم می‌کند.
 
-وقتی چندین نخ سعی می‌کنند همزمان `m` را بخوانند و بنویسند، با یکدیگر تداخل می‌کنند.
+هر نخ یک نسخه خصوصی از `m` دارد که با مقدار `-np.inf` مقداردهی اولیه شده و آن را در بازه تکرارهای خود به درستی به‌روزرسانی می‌کند.
 
-نخ‌ها مقادیر قدیمی `m` را می‌خوانند یا به‌روزرسانی‌های یکدیگر را بازنویسی می‌کنند --- یا `m` هرگز از مقدار اولیه خود به‌روزرسانی نمی‌شود.
+اما در پایان حلقه، Numba باید نسخه‌های هر نخ از `m` را در یک مقدار واحد ترکیب کند --- یک **تقلیل (reduction)**.
 
-در اینجا یک نسخه با دقت بیشتری نوشته شده است.
+برای الگوهایی که تشخیص می‌دهد، مانند `m += z` (جمع) یا `m = max(m, z)` (max)، Numba عملگر ترکیب را می‌شناسد.
+
+اما الگوی `if z > m: m = z` را به عنوان یک تقلیل max تشخیص نمی‌دهد، بنابراین نتایج هر نخ هرگز ترکیب نمی‌شوند و `m` مقدار اولیه خود را حفظ می‌کند.
+
+ساده‌ترین راه‌حل جایگزینی شرط با `max` است که Numba آن را می‌شناسد:
 
 ```{code-cell} ipython3
 @numba.jit(parallel=True)
 def compute_max_numba_parallel(grid):
+    n = len(grid)
+    m = -np.inf
+    for i in numba.prange(n):
+        for j in range(n):
+            x = grid[i]
+            y = grid[j]
+            z = np.cos(x**2 + y**2) / (1 + x**2 + y**2)
+            m = max(m, z)
+    return m
+```
+
+یک روش جایگزین این است که بدنه حلقه را بین `i` ها کاملاً مستقل کنیم و تقلیل را خودمان انجام دهیم:
+
+```{code-cell} ipython3
+@numba.jit(parallel=True)
+def compute_max_numba_parallel_v2(grid):
     n = len(grid)
     row_maxes = np.empty(n)
     for i in numba.prange(n):
@@ -258,9 +276,7 @@ def compute_max_numba_parallel(grid):
     return np.max(row_maxes)
 ```
 
-اکنون بلوک کدی که `for i in numba.prange(n)` روی آن عمل می‌کند بین `i` ها مستقل است.
-
-هر نخ به یک عنصر جداگانه از آرایه `row_maxes` می‌نویسد و موازی‌سازی ایمن است.
+در اینجا هر نخ به یک عنصر جداگانه از `row_maxes` می‌نویسد، بنابراین تقلیل را خودمان از طریق `np.max` انجام می‌دهیم.
 
 ```{code-cell} ipython3
 z_max_parallel = compute_max_numba_parallel(grid)
@@ -321,7 +337,7 @@ with qe.Timer(precision=8):
 
 ### JAX به علاوه vmap
 
-یک مشکل با کد NumPy و کد JAX وجود دارد:
+یک مشکل با کد NumPy و کد JAX فوق وجود دارد:
 
 در حالی که آرایه‌های تخت حافظه کمی دارند
 
@@ -339,9 +355,9 @@ x_mesh.nbytes + y_mesh.nbytes
 
 خوشبختانه، JAX رویکرد متفاوتی را با استفاده از [jax.vmap](https://docs.jax.dev/en/latest/_autosummary/jax.vmap.html) می‌پذیرد.
 
-#### نسخه 1
+ایده `vmap` این است که برداری‌سازی را به مراحل تقسیم کند و تابعی که روی مقادیر تکی عمل می‌کند را به تابعی تبدیل کند که روی آرایه‌ها عمل می‌کند.
 
-در اینجا یک راه برای اعمال `vmap` آمده است.
+در اینجا نحوه اعمال آن به مسئله ما آمده است.
 
 ```{code-cell} ipython3
 # f را تنظیم کنید تا f(x, y) را در هر x برای هر y داده شده محاسبه کند
@@ -368,31 +384,19 @@ with qe.Timer(precision=8):
     z_max.block_until_ready()
 ```
 
-با اجتناب از آرایه‌های ورودی بزرگ `x_mesh` و `y_mesh`، این نسخه `vmap` از حافظه بسیار کمتری استفاده می‌کند.
-
-وقتی روی CPU اجرا می‌شود، زمان اجرای آن شبیه به نسخه meshgrid است.
-
-وقتی روی GPU اجرا می‌شود، معمولاً به طور قابل توجهی سریعتر است.
-
-در واقع، استفاده از `vmap` مزیت دیگری دارد: به ما اجازه می‌دهد برداری‌سازی را به مراحل تقسیم کنیم.
-
-این منجر به کدی می‌شود که اغلب راحت‌تر از کد برداری شده سنتی قابل درک است.
-
-ما این ایده‌ها را بیشتر هنگام حل مسائل بزرگتر بررسی خواهیم کرد.
+با اجتناب از آرایه‌های ورودی بزرگ `x_mesh` و `y_mesh`، این نسخه `vmap` از حافظه بسیار کمتری با زمان اجرای مشابه استفاده می‌کند.
 
-### نسخه 2 vmap
+اما هنوز برخی بهره‌های سرعت را از دست می‌دهیم.
 
-می‌توانیم با استفاده از vmap همچنان کارآمدتر از نظر حافظه باشیم.
+کد فوق آرایه دوبعدی کامل `f(x,y)` را محاسبه می‌کند و سپس max را می‌گیرد.
 
-در حالی که در نسخه قبلی از آرایه‌های ورودی بزرگ اجتناب می‌کنیم، هنوز آرایه خروجی بزرگ `f(x,y)` را قبل از محاسبه حداکثر ایجاد می‌کنیم.
+علاوه بر این، فراخوانی `jnp.max` خارج از تابع JIT-کامپایل شده `f` قرار دارد، بنابراین کامپایلر نمی‌تواند این عملیات را در یک kernel واحد ادغام کند.
 
-بیایید یک رویکرد کمی متفاوت را امتحان کنیم که max را به داخل می‌برد.
-
-به دلیل این تغییر، ما هرگز آرایه دوبعدی `f(x,y)` را محاسبه نمی‌کنیم.
+می‌توانیم هر دو مشکل را با انتقال max به داخل و پوشاندن همه چیز در یک `@jax.jit` واحد برطرف کنیم:
 
 ```{code-cell} ipython3
 @jax.jit
-def compute_max_vmap_v2(grid):
+def compute_max_vmap(grid):
     # یک تابع بسازید که حداکثر را در امتداد هر سطر بگیرد
     f_vec_x_max = lambda y: jnp.max(f(grid, y))
     # تابع را برداری کنید تا بتوانیم روی تمام سطرها همزمان فراخوانی کنیم
@@ -408,24 +412,26 @@ def compute_max_vmap_v2(grid):
 
 ما این تابع را روی تمام سطرها اعمال می‌کنیم و سپس حداکثر max های سطر را می‌گیریم.
 
+چون max را به داخل منتقل می‌کنیم، هرگز آرایه دوبعدی کامل `f(x,y)` را نمی‌سازیم و حافظه بیشتری صرفه‌جویی می‌شود.
+
+و چون همه چیز زیر یک `@jax.jit` واحد قرار دارد، کامپایلر می‌تواند تمام عملیات را در یک kernel بهینه ادغام کند.
+
 بیایید آن را امتحان کنیم.
 
 ```{code-cell} ipython3
 with qe.Timer(precision=8):
-    z_max = compute_max_vmap_v2(grid).block_until_ready()
+    z_max = compute_max_vmap(grid).block_until_ready()
 
-print(f"JAX vmap v2 result: {z_max:.6f}")
+print(f"JAX vmap result: {z_max:.6f}")
 ```
 
 بیایید دوباره اجرا کنیم تا زمان کامپایل حذف شود:
 
 ```{code-cell} ipython3
 with qe.Timer(precision=8):
-    z_max = compute_max_vmap_v2(grid).block_until_ready()
+    z_max = compute_max_vmap(grid).block_until_ready()
 ```
 
-اگر این را روی GPU اجرا می‌کنید، همانطور که ما این کار را می‌کنیم، باید افزایش سرعت قابل توجه دیگری را ببینید.
-
 ### خلاصه
 
 به نظر ما، JAX برنده برای عملیات برداری شده است.
@@ -531,7 +537,7 @@ with qe.Timer(precision=8):
 
 JAX نیز برای این عملیات ترتیبی کاملاً کارآمد است.
 
-هم JAX و هم Numba عملکرد قوی پس از کامپایل ارائه می‌دهند، با این که Numba معمولاً (اما نه همیشه) سرعت‌های کمی بهتری در عملیات کاملاً ترتیبی ارائه می‌دهد.
+هم JAX و هم Numba عملکرد قوی پس از کامپایل ارائه می‌دهند.
 
 ### خلاصه
 
@@ -545,7 +551,7 @@ JAX نیز برای این عملیات ترتیبی کاملاً کارآمد 
 
 علاوه بر این، آرایه‌های تغییرناپذیر JAX به این معنی است که نمی‌توانیم به سادگی عناصر آرایه را در جا به‌روزرسانی کنیم و تکرار مستقیم الگوریتم مورد استفاده توسط Numba را سخت می‌کند.
 
-برای این نوع عملیات ترتیبی، Numba برنده واضح از نظر وضوح کد و سهولت پیاده‌سازی، و همچنین عملکرد بالا است.
+برای این نوع عملیات ترتیبی، Numba برنده واضح از نظر وضوح کد و سهولت پیاده‌سازی است.
 
 ## توصیه‌های کلی
 
@@ -563,11 +569,12 @@ JAX نیز برای این عملیات ترتیبی کاملاً کارآمد 
 
 کد طبیعی و خوانا است --- صرفاً یک حلقه پایتون با یک decorator --- و کارایی آن عالی است.
 
-JAX می‌تواند مسائل ترتیبی را از طریق `lax.scan` مدیریت کند، اما نحو آن کمتر شهودی است و برای کارهای کاملاً ترتیبی، بهره‌وری اضافی ناچیز است.
-
-با این حال، `lax.scan` یک مزیت مهم دارد: از مشتق‌گیری خودکار در طول حلقه پشتیبانی می‌کند، که Numba قادر به انجام آن نیست.
+JAX می‌تواند مسائل ترتیبی را از طریق `lax.scan` مدیریت کند، اما نحو آن کمتر شهودی است.
 
+```{note}
+یک مزیت مهم `lax.scan` این است که از مشتق‌گیری خودکار در طول حلقه پشتیبانی می‌کند، که Numba قادر به انجام آن نیست.
 اگر نیاز دارید از طریق یک محاسبه ترتیبی مشتق بگیرید (مثلاً محاسبه حساسیت‌های یک مسیر نسبت به پارامترهای مدل)، JAX علی‌رغم نحو کمتر طبیعی‌اش، انتخاب بهتری است.
+```
 
 در عمل، بسیاری از مسائل ترکیبی از هر دو الگو هستند.