7.9。模板注釋 · Numba 0.44 中文文檔

# 7.9。模板注釋 > 原文： [http://numba.pydata.org/numba-doc/latest/developer/stencil.html](http://numba.pydata.org/numba-doc/latest/developer/stencil.html) Numba 提供 [@stencil 裝飾器](../user/stencil.html#numba-stencil)來表示模板計算。本文檔介紹了如何在 Numba 中提供的幾種不同模式中實現此功能。目前，支持從非 jitted 代碼調用模板以及來自 jitted 代碼的調用，無論是否有 [parallel = True](../user/jit.html#parallel-jit-option) 選項。 ## 7.9.1。模板裝飾模板裝飾器本身只返回一個`StencilFunc`對象。該對象封裝了程序中指定的原始模板內核函數以及傳遞給模板裝飾器的選項。另外值得注意的是，在模板的第一次編譯之后，模板的計算鄰域存儲在`neighborhood`屬性中的`StencilFunc`對象中。 ## 7.9.2。處理三種模式如上所述，Numba 支持從`@jit`編譯函數內部或外部調用模板，有或沒有 [parallel = True](../user/jit.html#parallel-jit-option) 選項。 ### 7.9.2.1。外部 jit 上下文 `StencilFunc`覆蓋`__call__`方法，以便調用`StencilFunc`對象執行模板： ```py def __call__(self, *args, **kwargs): result = kwargs.get('out') new_stencil_func = self._stencil_wrapper(result, None, *args) if result is None: return new_stencil_func.entry_point(*args) else: return new_stencil_func.entry_point(*args, result) ``` 首先，檢查是否存在可選的 [out](../user/stencil.html#stencil-function-out) 參數。如果存在則輸出數組存儲在`result`中。然后，對`_stencil_wrapper`的調用在給定結果和參數類型的情況下生成模板函數，最后執行生成的模板函數并返回其結果。 ### 7.9.2.2。沒有`parallel=True` 的 Jit 構造時，`StencilFunc`將自身插入到鍵入上下文的用戶函數集中，并提供`_type_me`回調。通過這種方式，標準 Numba 編譯器能夠確定`StencilFunc`的輸出類型和簽名。每個`StencilFunc`都維護一個先前看到的輸入參數類型和關鍵字類型組合的緩存。如果先前看到，`StencilFunc`返回計算的簽名。如果以前沒有計算過，`StencilFunc`通過在模板內核上運行 Numba 編譯器前端，然后在 [Numba IR](../glossary.html#term-numba-ir) （IR）上執行類型推斷來獲得標量返回類型，從而計算模板的返回類型內核。從那里，構造一個 Numpy 數組類型，其元素類型與標量返回類型匹配。在為先前看不見的輸入和關鍵字類型組合計算模板的簽名后，`StencilFunc`然后[創建模板函數](#arch-stencil-create-function)本身。 `StencilFunc`然后在目標上下文中安裝新的模板函數的定義，以便 jitted 代碼能夠調用它。因此，在這種模式下，生成的模板函數是一個獨立的函數，稱為 jitted 代碼中的正常函數。 ### 7.9.2.3。 Jit 與`parallel=True` 當使用`parallel=True`從 jitted 上下文調用`StencilFunc`時，不會使用由[創建的單獨的模板函數創建模板函數](#arch-stencil-create-function)。相反， <cite>parfors</cite> （[階段 6b：執行自動并行化](architecture.html#parallel-accelerator)）是在實現模板的當前函數中創建的。此代碼再次從模板內核開始并執行類似的內核大小計算，但是然后而不是標準的 Python 循環語法，創建相應的 <cite>parfors</cite> ，以便模板的執行將并行進行。通過設置`parallel={'stencil': False}`以及[階段 6b：執行自動并行化](architecture.html#parallel-accelerator)中描述的其他子選項，也可以選擇性地禁用 <cite>parfor</cite> 轉換的模板。 ## 7.9.3。創建模板功能從概念上講，通過在內核周圍添加循環代碼，根據循環索引將相對內核索引轉換為絕對數組索引，并使用要分配的語句替換內核的`return`語句，從用戶指定的模板內核創建模板函數。將計算值輸入到輸出數組中。為了完成這種轉換，首先，創建模板內核 IR 的副本，以便隨后對不同模板簽名的 IR 的修改不會相互影響。然后，采用類似于為 <cite>parfors</cite> 創建 GUFunc 的方法。在文本緩沖區中，使用唯一名稱創建 Python 函數。輸入數組參數被添加到函數定義中，如果存在`out`參數類型，則會將`out`參數添加到模板函數定義中。如果`out`參數不存在，則首先創建一個輸出數組，其中`numpy.zeros`具有與輸入數組相同的形狀。然后分析內核以計算模板尺寸和邊界的形狀（或者`neighborhood`模板裝飾器參數用于此目的，如果存在的話）。然后，將輸入數組的每個維度的一個`for`循環添加到模板函數定義中。每個循環的范圍由先前計算的模板內核大小控制，以便輸出圖像的邊界不被修改，而是保持原樣。最內層`for`循環的主體是單個`sentinel`語句，在 IR 中很容易識別。使用文本緩沖區調用`exec`用于強制模板功能存在，并使用`eval`訪問相應的函數，在該函數上使用`run_frontend`獲取模板函數 IR。在模板函數 IR 和內核 IR 上執行各種重命名和重新標記，以便兩者可以無沖突地組合。內核 IR 中的相對索引（即`getitem`調用）被表達式替換，其中相應的循環索引變量被添加到相對索引。內核 IR 中的`return`語句被輸出數組中相應元素的`setitem`替換。然后掃描模板函數 IR 以獲得標記，并且用修改的內核 IR 替換標記。接下來，`compile_ir`用于編譯組合模板函數 IR。生成的編譯結果緩存在`StencilFunc`中，以便對同一模板的其他調用不需要再次執行此過程。 ## 7.9.4。例外情況在模板編譯期間執行各種檢查，以確保用戶指定的選項不會相互沖突或與其他運行時參數沖突。例如，如果用戶手動為模板裝飾器指定了`neighborhood`，則該鄰域的長度必須與輸入數組的維度相匹配。如果不是這種情況，則會引發`ValueError`。如果尚未指定鄰域，則必須推斷它并且推斷內核的要求是所有索引都是常量整數。如果不是，則引發`ValueError`，表明內核索引可能不是非常數。最后，模板實現通過在模板內核上運行 Numba 類型推斷來檢測輸出數組類型。如果此內核的返回類型與傳遞給`cval`模板裝飾器選項的值的類型不匹配，則會引發`ValueError`。