Update translation: lectures/numba.md

Author: mmcky

lectures/numba.md

@@ -15,18 +15,14 @@ translation:
     Overview: مروری کلی
     Compiling Functions: کامپایل کردن توابع
     Compiling Functions::An Example: یک مثال
-    Compiling Functions::How and When it Works: چگونه و چه زمانی کار می‌کند
-    Decorator Notation: نماد Decorator
-    Type Inference: استنتاج نوع
-    Dangers and Limitations: خطرات و محدودیت‌ها
-    Dangers and Limitations::Limitations: محدودیت‌ها
-    'Dangers and Limitations::A Gotcha: Global Variables': 'یک مشکل: متغیرهای سراسری'
-    Dangers and Limitations::Caching Compiled Code: ذخیره‌سازی کد کامپایل‌شده
+    Compiling Functions::An Example::Base Version: نسخه پایه
+    Compiling Functions::An Example::Acceleration via Numba: شتاب‌دهی از طریق Numba
+    Compiling Functions::How and When it Works: چگونگی و زمان عملکرد
     Multithreaded Loops in Numba: حلقه‌های چندنخی در Numba
     Exercises: تمرین‌ها
 ---
 
-(speed)=
+(numba_lecture)=
 ```{raw} jupyter
 <div id="qe-notebook-header" align="right" style="text-align:right;">
         <a href="https://quantecon.org/" title="quantecon.org">
@@ -86,24 +82,22 @@ Numba توابع را در حین اجرا به دستورالعمل‌های ک
 (quad_map_eg)=
 ### یک مثال
 
-بیایید مسئله‌ای را در نظر بگیریم که برداری‌سازی آن دشوار است: تولید مسیر یک معادله تفاضلی با توجه به یک شرط اولیه.
+بیایید مسئله‌ای را در نظر بگیریم که برداری‌سازی آن دشوار است (یعنی، واگذار کردن آن به عملیات پردازش آرایه).
 
-معادله تفاضلی را نگاشت درجه دوم در نظر می‌گیریم:
+این مسئله شامل تولید مسیر از طریق نگاشت درجه دوم است:
 
 $$
     x_{t+1} = \alpha x_t (1 - x_t)
 $$
 
-در ادامه مقدار زیر را تنظیم می‌کنیم:
+در ادامه، مقدار $\alpha = 4$ را تنظیم می‌کنیم.
 
-```{code-cell} ipython3
-α = 4.0
-```
+#### نسخه پایه
 
-در اینجا نمودار یک مسیر معمول را مشاهده می‌کنید که از $x_0 = 0.1$ شروع می‌شود و $t$ روی محور x قرار دارد:
+در اینجا نمودار یک مسیر معمولی آمده است که از $x_0 = 0.1$ شروع می‌شود و $t$ روی محور افقی است:
 
 ```{code-cell} ipython3
-def qm(x0, n):
+def qm(x0, n, α=4.0):
     x = np.empty(n+1)
     x[0] = x0
     for t in range(n):
@@ -118,235 +112,94 @@ ax.set_ylabel('$x_{t}$', fontsize = 12)
 plt.show()
 ```
 
-برای تسریع تابع `qm` با استفاده از Numba، اولین گام ما این است:
-
-```{code-cell} ipython3
-from numba import jit
-
-qm_numba = jit(qm)
-```
-
-تابع `qm_numba` نسخه‌ای از `qm` است که برای کامپایل JIT «هدف‌گذاری» شده است.
-
-به زودی توضیح خواهیم داد که این به چه معناست.
-
-بیایید فراخوانی‌های یکسان تابع را در این دو نسخه زمان‌بندی و مقایسه کنیم، ابتدا با تابع اصلی `qm`:
+بیایید ببینیم برای $n$ بزرگ، اجرای این تابع چقدر طول می‌کشد:
 
 ```{code-cell} ipython3
 n = 10_000_000
 
 with qe.Timer() as timer1:
-    qm(0.1, int(n))
-time1 = timer1.elapsed
-```
-
-حالا بیایید qm_numba را امتحان کنیم:
+    # Time Python base version
+    x = qm(0.1, n)
 
-```{code-cell} ipython3
-with qe.Timer() as timer2:
-    qm_numba(0.1, int(n))
-time2 = timer2.elapsed
 ```
 
-این از قبل یک افزایش سرعت بسیار زیاد است.
-
-در واقع، دفعه بعد و تمام دفعات بعدی حتی سریع‌تر اجرا می‌شود زیرا تابع کامپایل شده و در حافظه قرار دارد:
+#### شتاب‌دهی از طریق Numba
 
-(qm_numba_result)=
+برای افزایش سرعت تابع `qm` با استفاده از Numba، ابتدا تابع `jit` را وارد می‌کنیم:
 
 ```{code-cell} ipython3
-with qe.Timer() as timer3:
-    qm_numba(0.1, int(n))
-time3 = timer3.elapsed
-```
-
-```{code-cell} ipython3
-time1 / time3  # Calculate speed gain
+from numba import jit
 ```
 
-### چگونه و چه زمانی کار می‌کند
-
-Numba تلاش می‌کند با استفاده از زیرساختی که [پروژه LLVM](https://llvm.org/) فراهم کرده، کد ماشین سریع تولید کند.
-
-این کار را با استنتاج اطلاعات نوع به صورت لحظه‌ای انجام می‌دهد.
-
-(برای بحث درباره انواع، {doc}`درس قبلی <need_for_speed>` ما درباره محاسبات علمی را ببینید.)
-
-ایده اصلی این است:
-
-* پایتون بسیار انعطاف‌پذیر است و از این رو می‌توانیم تابع qm را با انواع مختلفی فراخوانی کنیم.
-    * مثلاً `x0` می‌تواند یک آرایه NumPy یا یک لیست باشد، `n` می‌تواند یک عدد صحیح یا یک عدد اعشاری باشد و غیره.
-* این امر *پیش*-کامپایل کردن تابع (یعنی کامپایل پیش از زمان اجرا) را دشوار می‌سازد.
-* اما وقتی واقعاً تابع را فراخوانی می‌کنیم، مثلاً با اجرای `qm(0.5, 10)`، انواع `x0` و `n` مشخص می‌شوند.
-* علاوه بر این، انواع *سایر متغیرها* در `qm` *می‌توانند پس از مشخص شدن انواع ورودی استنتاج شوند*.
-* بنابراین استراتژی Numba و سایر کامپایلرهای JIT این است که تا این لحظه صبر کنند و سپس تابع را کامپایل کنند.
-
-به همین دلیل است که به آن کامپایل «درست به موقع» (just-in-time) گفته می‌شود.
-
-توجه داشته باشید که اگر `qm(0.5, 10)` را فراخوانی کنید و سپس `qm(0.9, 20)` را دنبال آن بیاورید، کامپایل تنها در اولین فراخوانی انجام می‌شود.
-
-این به این دلیل است که کد کامپایل‌شده در حافظه نهان ذخیره می‌شود و در صورت نیاز مجدداً استفاده می‌شود.
-
-به همین دلیل است که در کد بالا، `time3` کوچک‌تر از `time2` است.
-
-## نماد Decorator
-
-در کد بالا، نسخه کامپایل شده JIT از `qm` را از طریق فراخوانی ایجاد کردیم
+حالا آن را روی `qm` اعمال می‌کنیم و تابع جدیدی تولید می‌کنیم:
 
 ```{code-cell} ipython3
 qm_numba = jit(qm)
 ```
 
-در عمل، این معمولاً با استفاده از یک سینتکس جایگزین *decorator* انجام می‌شود.
-
-(ما decoratorها را در یک {doc}`درس جداگانه <python_advanced_features>` بحث می‌کنیم اما می‌توانید جزئیات را در این مرحله رد کنید.)
-
-به طور مشخص، برای هدف‌گیری یک تابع برای کامپایل JIT، می‌توانیم `@jit` را قبل از تعریف تابع قرار دهیم.
+تابع `qm_numba` نسخه‌ای از `qm` است که برای کامپایل JIT "هدف‌گذاری" شده است.
 
-در اینجا نحوه انجام این کار برای `qm` آمده است
-
-```{code-cell} ipython3
-@jit
-def qm(x0, n):
-    x = np.empty(n+1)
-    x[0] = x0
-    for t in range(n):
-        x[t+1] = α * x[t] * (1 - x[t])
-    return x
-```
-
-این معادل افزودن `qm = jit(qm)` بعد از تعریف تابع است.
-
-موارد زیر اکنون از نسخه jitted استفاده می‌کنند:
+به زودی توضیح خواهیم داد که این به چه معناست.
 
-```{code-cell} ipython3
-with qe.Timer(precision=4):
-    qm(0.1, 100_000)
-```
+بیایید این نسخه جدید را زمان‌سنجی کنیم:
 
 ```{code-cell} ipython3
-with qe.Timer(precision=4):
-    qm(0.1, 100_000)
+with qe.Timer() as timer2:
+    # Time jitted version
+    x = qm_numba(0.1, n)
 ```
 
-Numba همچنین چندین آرگومان برای decoratorها جهت تسریع محاسبات و ذخیره‌سازی cache توابع ارائه می‌دهد -- [اینجا](https://numba.readthedocs.io/en/stable/user/performance-tips.html) را ببینید.
-
-## استنتاج نوع
-
-استنتاج موفقیت‌آمیز نوع، بخش کلیدی کامپایل JIT است.
-
-همانطور که می‌توانید تصور کنید، استنتاج انواع برای اشیاء ساده Python (مثلاً انواع داده اسکالر ساده مانند اعشاری و صحیح) آسان‌تر است.
-
-Numba همچنین با آرایه‌های NumPy که انواع به خوبی تعریف شده دارند، به خوبی کار می‌کند.
-
-در یک محیط ایده‌آل، Numba می‌تواند تمام اطلاعات نوع لازم را استنتاج کند.
-
-این به آن اجازه می‌دهد تا کد ماشین بومی تولید کند، بدون نیاز به فراخوانی محیط زمان اجرای Python.
+این یک افزایش سرعت قابل توجه است.
 
-وقتی Numba نمی‌تواند تمام اطلاعات نوع را استنتاج کند، خطا ایجاد می‌کند.
+در واقع، دفعه بعد و تمام دفعات بعدی سریع‌تر اجرا می‌شود، چراکه تابع کامپایل شده و در حافظه قرار دارد:
 
-```{note}
-در نسخه‌های قدیمی‌تر Numba، دکوراتور `@jit` در صورت عدم توانایی در استنتاج همه انواع، به آرامی به «حالت شیء» بازمی‌گشت که سرعت چندانی به همراه نداشت. نسخه‌های فعلی Numba به طور پیش‌فرض از حالت `nopython` استفاده می‌کنند، به این معنا که کامپایلر بر استنتاج کامل نوع اصرار دارد و در صورت شکست، خطا ایجاد می‌کند. اغلب در کدهای دیگر `@njit` را می‌بینید که صرفاً یک نام مستعار برای `@jit(nopython=True)` است. از آنجا که حالت nopython اکنون پیش‌فرض است، `@jit` و `@njit` معادل یکدیگرند.
-```
-
-به عنوان مثال، در تنظیم (مصنوعی) زیر، Numba قادر به تعیین نوع تابع `mean` هنگام کامپایل تابع `bootstrap` نیست
+(qm_numba_result)=
 
 ```{code-cell} ipython3
-@jit
-def bootstrap(data, statistics, n_resamples):
-    bootstrap_stat = np.empty(n_resamples)
-    n = len(data)
-    for i in range(n_resamples):
-        resample = np.random.choice(data, size=n, replace=True)
-        bootstrap_stat[i] = statistics(resample)
-    return bootstrap_stat
-
-# هیچ decorator اینجا نیست.
-def mean(data):
-    return np.mean(data)
-
-data = np.array((2.3, 3.1, 4.3, 5.9, 2.1, 3.8, 2.2))
-n_resamples = 10
-
-# این کد خطا ایجاد می‌کند
-try:
-    bootstrap(data, mean, n_resamples)
-except Exception as e:
-    print(e)
+with qe.Timer() as timer3:
+    # Second run
+    x = qm_numba(0.1, n)
 ```
 
-می‌توانیم این خطا را در این مورد به راحتی با کامپایل کردن `mean` برطرف کنیم.
+در اینجا میزان افزایش سرعت آمده است:
 
 ```{code-cell} ipython3
-@jit
-def mean(data):
-    return np.mean(data)
-
-with qe.Timer():
-    bootstrap(data, mean, n_resamples)
+timer1.elapsed /  timer3.elapsed
 ```
 
-## خطرات و محدودیت‌ها
+این یک بهبود قابل توجه با تغییر اندکی در کد اصلی ماست.
 
-بیایید برخی یادداشت‌های احتیاطی اضافه کنیم.
+بیایید درباره نحوه عملکرد آن بحث کنیم.
 
-### محدودیت‌ها
+### چگونگی و زمان عملکرد
 
-همانطور که دیدیم، Numba باید اطلاعات نوع را روی تمام متغیرها استنتاج کند تا دستورالعمل‌های سریع سطح ماشین تولید کند.
+Numba تلاش می‌کند با استفاده از زیرساخت ارائه‌شده توسط [پروژه LLVM](https://llvm.org/)، کد ماشین سریعی تولید کند.
 
-برای روال‌های ساده، Numba انواع را بسیار خوب استنتاج می‌کند.
+این کار را از طریق استنتاج اطلاعات نوع به‌صورت پویا انجام می‌دهد.
 
-برای روال‌های بزرگتر، یا برای روال‌هایی که از کتابخانه‌های خارجی استفاده می‌کنند، به راحتی می‌تواند شکست بخورد.
+(برای بحث درباره انواع، به {doc}`درس <need_for_speed>` قبلی ما درباره محاسبات علمی مراجعه کنید.)
 
-از این رو، بهتر است روی تسریع قطعات کوچک و حیاتی کد تمرکز کنید.
-
-این به شما عملکرد بسیار بهتری نسبت به پوشاندن برنامه‌های Python خود با عبارت‌های `@jit` می‌دهد.
-
-### یک مشکل: متغیرهای سراسری
-
-چیز دیگری که هنگام استفاده از Numba باید مراقب آن باشید در اینجا است.
-
-مثال زیر را در نظر بگیرید
-
-```{code-cell} ipython3
-a = 1
-
-@jit
-def add_a(x):
-    return a + x
-
-print(add_a(10))
-```
-
-```{code-cell} ipython3
-a = 2
-
-print(add_a(10))
-```
+ایده اصلی این است:
 
-توجه داشته باشید که تغییر global هیچ تأثیری بر مقدار برگشتی توسط تابع نداشت.
+* پایتون بسیار انعطاف‌پذیر است و از این رو می‌توانیم تابع qm را با انواع مختلفی فراخوانی کنیم.
+    * به عنوان مثال، `x0` می‌تواند یک آرایه NumPy یا یک لیست باشد، `n` می‌تواند یک عدد صحیح یا اعشاری باشد، و غیره.
+* این امر، تولید کد ماشین کارآمد *پیش از اجرا* (یعنی قبل از زمان اجرا) را بسیار دشوار می‌کند.
+* اما وقتی واقعاً تابع را *فراخوانی می‌کنیم*، مثلاً با اجرای `qm(0.5, 10)`، نوع‌های `x0`، `α` و `n` مشخص می‌شوند.
+* علاوه بر این، نوع‌های *سایر متغیرها* در `qm` *به محض مشخص شدن نوع‌های ورودی قابل استنتاج هستند*.
+* بنابراین، استراتژی Numba و سایر کامپایلرهای JIT این است که *صبر کنند تا تابع فراخوانی شود*، و سپس کامپایل کنند.
 
-وقتی Numba کد ماشین را برای توابع کامپایل می‌کند، متغیرهای سراسری را به عنوان ثابت برای اطمینان از پایداری نوع درمان می‌کند.
+این روش "کامپایل درست-به-موقع" نامیده می‌شود.
 
-### ذخیره‌سازی کد کامپایل‌شده
+توجه داشته باشید که اگر `qm_numba(0.5, 10)` را فراخوانی کنید و سپس `qm_numba(0.9, 20)` را اجرا کنید، کامپایل تنها در اولین فراخوانی انجام می‌شود.
 
-به طور پیش‌فرض، Numba در هر بار شروع یک نشست Python جدید، توابع را مجدداً کامپایل می‌کند.
+دلیل این امر آن است که کد کامپایل‌شده در حافظه نهان ذخیره می‌شود و در صورت نیاز مجدداً استفاده می‌شود.
 
-برای جلوگیری از این سربار، می‌توانید `cache=True` را به دکوراتور ارسال کنید:
+به همین دلیل است که در کد بالا، اجرای دوم `qm_numba` سریع‌تر است.
 
-```{code-cell} ipython3
-@jit(cache=True)
-def qm(x0, n):
-    x = np.empty(n+1)
-    x[0] = x0
-    for t in range(n):
-        x[t+1] = α * x[t] * (1 - x[t])
-    return x
+```{admonition} توضیح
+در عمل، به جای نوشتن `qm_numba = jit(qm)`، معمولاً از نحو *دکوراتور* استفاده می‌کنیم و `@jit` را قبل از تعریف تابع قرار می‌دهیم. این معادل افزودن `qm = jit(qm)` پس از تعریف است.
 ```
 
-این کد کامپایل‌شده را روی دیسک ذخیره می‌کند تا نشست‌های بعدی بتوانند از مرحله کامپایل صرف‌نظر کنند.
-
-(multithreading)=
 ## حلقه‌های چندنخی در Numba
 
 علاوه بر کامپایل JIT، Numba پشتیبانی از محاسبات موازی در CPUها ارائه می‌دهد.