Numba lecture: @jit vs @njit usage and cache=True in Jupyter

[mmcky]

Summary

During review of the downstream translation sync PR (QuantEcon/lecture-python-programming.zh-cn#17), several issues were identified in the Numba lecture content introduced by PR #512. These are source content concerns, not translation bugs.

Status (updated 2026-08-04): Item 3 is resolved — the "Caching Compiled Code" section and all cache=True usage are gone from main. Items 1–2 remain live (16 @jit, 0 @njit in numba.md) and reduce to a single house-style decision: adopt @njit explicitly throughout numba.md, or close this issue recording @jit as the accepted convention. In modern Numba @jit defaults to nopython mode, so the practical risk has narrowed to explicitness for readers on older environments.

Issues

1. @jit vs @njit equivalence claim may mislead readers

The lecture note states that @jit and @njit are now equivalent since nopython mode is the default. However, in some environments @jit can still fallback to object mode without raising an error. This could lead to readers getting inconsistent results, especially when they expect compilation failures to surface as errors.

Suggestion: Consider using @njit explicitly in all examples, or add a caveat about environment-specific behavior.

2. @jit(parallel=True) should be @njit(parallel=True)

The parallelization example uses @jit(parallel=True) with prange. Numba's parallel optimization requires the nopython compilation path; if @jit falls back to object mode, parallel=True may silently not take effect. Using @njit(parallel=True) (or @jit(nopython=True, parallel=True)) would guarantee the example behaves as described.

3. cache=True limitation in Jupyter environments — resolved

Resolved: no cache=True usage and no caching section remain on main, so there is nothing left to caveat.

Source

• Upstream PR: Modernize Numba lecture #512
• Translation sync PR: QuantEcon/lecture-python-programming.zh-cn#17

[mmcky]

Decision (2026-08-04): @jit is the accepted house convention for numba.md.

Modern Numba compiles @jit in nopython mode — the object-mode fallback that motivated items 1–2 was removed upstream — so @njit is now an alias, and switching the 16 @jit sites would churn three translation repos with no behavioral change. Item 3 (cache=True) was already resolved on main (see the status block in the body).

Closing as resolved by convention. If a future Numba release reintroduces a meaningful distinction, reopen.