paraview python macro

paraview 是一套強大的、可用於呈現 VTK 系列檔案[1]的工具，同時也是由 Kitware 公司維護的 open source software。

通常操作 paraview 的流程是：啟動 GUI、讀入檔案[2]、選擇要呈現的屬性[3]、操作 camera 來檢視圖形、播放隨時間流逝的動畫（需要讀入數個檔案，見[2]）。

在 CFD 開發與實驗的過程中，如果每次產生的資料與數據，都要手動調整 GUI （例如上述的步驟）來檢查每次的結果，是非常沒有效率的事情。paraview 有提供接口，讓使用者可以透過 python 來操作 paraview 引擎；因此使用者可以撰寫 python macro 來簡化每次的操作。

安裝

Ubuntu 可以透過安裝 paraview-python 套件來取得 python 支援。

使用

參考 paraview wiki，或是 paraview 本身的 document 都很不錯。

tips - 好用的 trace

paraview 本身有提供「記錄使用者操作的流程，然後直接輸出成 python macro 」的超級好用功能。這樣使用者可以很直觀地操作之後（例如轉動物體到自己看得順眼的角度），直接取得 python script （欸欸欸這樣認真 K 上面 document 或是 wiki 的人情何以堪 XD）。

使用上就從 GUI 選擇 Tools 列表中的 Start Trace 選項，然後開始操作 paraview GUI[4]。操作完畢後選擇 Stop Trace ，並且存檔取得 python script。這樣就大功告成了。非常方便的功能！

理解 paraview python script

paraview 的運作邏輯大致上如下：

• 資料 IO 、讀入檔案（注意支援一次讀多個檔案），用 reader 物件代表讀入結果。
• Show：產生即將要呈現的資料的圖形屬性管理者 display
• Render：渲染、呈現 display。包括動畫的部份。
• Camera：決定使用者的視角（所以旋轉圖形什麼的由這裡操作）

由 paraview.simple module 提供操作層。（注意不是 module paraview；module paraview 應該是引擎本身）

資料讀入

• OpenDataFile (泛用的方法，會自己判定是哪種 grid 幾何）
• XMLUnstructuredGridReader、xxxxReader （直接指定 reader，注意可以透過 Filename keyword 來傳入檔案 list）

[1] 一種檔案格式，有多種延伸格式（例如 vtu）。常用於呈現 3D 幾何圖形，廣泛在地球科學與計算流體力學中被採用。特色之一是支援平行化運算。
[2] paraview 支援一次讀入檔名連續的不同檔案，常用於顯示不同時間的圖形幾何。
[3] 通常是用來呈現物理意義上的屬性。由檔案寫入者決定任何的 attribute 名稱。例如可以是壓力或者溫度。
[4] 你可能會遇到需要 python-pygments 套件的問題；Ubuntu 上透過 apt 安裝該套件可以解決這個問題。

diff 工具中的 unified format

稍早在討論 cram 這個測試工具的文章中[1]，有提到 unified format。這邊文章稍微補充一些更多的香關知識。動機很單純，因為 diff 這個實用的工具用很久了，順便整理一下對於新接觸這種格式的人可能會有的障礙。wikipedia 上面其實已經整理得很清楚了[2]，這邊算是中文摘要。

[1] http://zh-tw-tai271828.blogspot.tw/2017/01/cram.html
[2] https://en.wikipedia.org/wiki/Diff_utility#Unified_format

unified format

最主要是要知道要怎麼解讀這個格式

@@ -l,s +l,s @@ optional section heading

• 格式開頭由兩個 @包夾
• - 原本的檔案
• + 更動後的檔案
• l 開始的行數
• s 由開始起算的相關行數（刪減、更動或是增加）

簡史

Wayne Davison 在 1990 八月提出，隨後由 Richard Stallman 加入 GNU diff 中 (GNU diff 1.15)

字彙

• hunk - 在這裡指「一整個更動過的文字區塊」。了解這個字義有助於使用 patch 時，可以更清楚地解讀上 patch 後 patch 工具所反饋的訊息。

初探命令列測試工具 cram

cram 簡介

cram 是一個設計來適用於測試命令列的工具。包括下面特性

• 執行一個 .t extention file 來進行測試
• 測試結果使用 unified format[1] 呈現

我的心得是似乎是一個可以用於 function test or API test 的工具：測試產品整體的執行結果。[2] 另外就是近年來似乎使用 command pattern + factory pattern 的命令列實作似乎越來越常見[3]，或許是一個值得了解的測試方式。

[1] https://en.wikipedia.org/wiki/Diff_utility#Unified_format

[2] 請見下面的「mercurial 的測試設計思想」

[3] kubernetes, mercurial, MAAS, checkbox(這個不完全是，沒有前面三者這麼"API")

使用範例

安裝

pip install cram

取得 cram source code (我只是要拿裡面 cram 測試自己 source code 的 test file)

git clone git@github.com:brodie/cram.git

進到取得的 source code 中存放  test file 之處

cd <cram source root>/cram/tests

執行看看

cram usage.t

稍微改動一下 usage.t，比較一下前後輸入輸出結果，大概就會有些感覺了。包括：

• .t file 基本上由兩者構成：「要執行的命令」、「執行後的輸出」
• 由空白兩行的縮排來告知 cram 「這是要執行的命令與執行後的輸出」

已經有過的討論案例：mercurial 的測試設計思想

在研究 cram 的過程中，我發現了這個討論串[1][2]，大致上是說

• mercurial 的開發上，產品的測試佔極大部份（程式碼幾乎是產品本身行數的一半），unit test 只有一點點
• 上面這種測試的中心思想是「我只保證 API 行為始終一致，中間怎麼實作基本上你不要管我」。優點是向下相容容易、測試程式碼不需要跟著一直改動。
• 有人就建議那這樣可能適合使用 cram[3]

[1] https://www.selenic.com/blog/?p=663

[2] https://www.selenic.com/blog/?p=582

[3] 我不知道最後 mercurial 最後有沒有採取這個作法，有興趣可以追一下。cram 的開發好像也沈寂了一段時間了就是。（cram 在 github 上面的 README 中，有些 link 還是指到 bitbucket 上呢）

自己想用上的案例：SOLVCON 上面使用 cram

動機

在 2015 的計畫中（對滿一年了 XD），我們有考慮設計 mesh IO 的 API。目前 mesh 工具也是朝著 command + factory pattern 的方式實作。

可以預期的問題

• 有些行為本質是亂數，例如切  partition 的方式
• elapsed time 資訊不太可能每次一樣

所以至少第一步是要先挑出究竟哪些 mesh/block 行為並不會改變，再去實作。

書摘：Effective Debugging - Item 21 修正所有造成問題的類別實例

這也是很直觀，不過作者舉了一些找出類似實例的方式，例如

• 用 grep 找出關鍵字、使用 -v [1] 做過濾、使用 --color=always 高亮自己要的訊息
• sort -u 移除重複

在某些情況下，例如使用不推薦或是錯誤的 API，可以使用 global include file 來重新定義錯誤的 API 名稱，讓他改作其他事情（例如拋出警告取代實際執行），這樣就可以在程式早期（例如編譯或是連結的時候）就發現問題了。

[1] 我自己 -v 也是用很兇，在這裡看到有同好也是，覺得安心 XDDDD

書摘：Effective Debugging - Item 20 除錯前後理清資訊

debugging 是一個在複雜的環境中找線索的過程，起頭往往可以是（部份舉例）

• 能夠協助你找到問題的工具是什麼？
• warnings 訊息等等是什麼？
• 好像跟你的問題有關的、但你又讀不懂的程式碼段
• comment 有些關鍵字例如 "should" "think" "must" "FIXME" "TODO" 等等的程式碼附近。

關掉或是移除這些嫌疑犯（例如會產生 warning 的程式碼片段）來找出錯誤；注意因為可能性太多了，所以務必要在除錯之前，把要除錯系統先「穩定」下來；除非你真的很確定有幫助，不然不要貿然升級或是改動程式碼等等。

除錯完成後，記得

• 在程式裡面尋找類似的錯誤
• 加入可以在未來協助找出類似錯誤的例外處理 [1]
• undo 任何暫時性的修改（可以考慮搭配 version control）

[1] 這點對我而言有被刺激到，例如我後來就在 SOLVCON 裡面加入了類似的檢查，來找出未來 boundary condition 是一個 generic layer 而不是具體的 boundary condition 時，拋出訊息。https://github.com/solvcon/solvcon/pull/180/commits/d946c3d1b6bb23d9011f0f774cf9c2c917848579

書摘：Effective Debugging - Item 19 自動化除錯任務

這其實滿直觀的一種想法：把針對某個任務常用到的指令整合、寫下等等方便重複利用，或是反覆替自己找出有用的資訊。這章節的價值在於作者很具體地提供某些工具的名稱和應用方式。例如：

• which 很慢，如何分析自己的 PATH 變數（搭配 sed, pipe and while)，找出 typo

作者另外指出各種怪現象都有對應的工具（並且列出書中對應章節供更進一步的參考），例如：

• API violations
• memory butter overflows
• race conditions

我自己是有一個心得，使用編輯器的 exhaustive search 之前，可以先大概想一下，自己遇到的這個案例，適合這樣做，或是適合先寫個 script 來幫你過濾程式碼或是 log。

總之如作者所說：「computer time is cheap, yours is expensive.」（我個人是覺得把 time 換成專注力，應該更貼切）

書摘：Effective Debugging - Item 18 從你的桌面替其他不便的系統除錯

不是自己平常使用的系統當然很不習慣，例如缺少某些自己慣用的工具，這個章節提供幾個方法讓想要除錯的系統盡可能地接近自己習慣的環境。

• 對於手機 app 或是有些 embedded devices，使用 device emulator；這樣就可以使用自己習慣的螢幕、鍵盤和編輯器。缺點是可能無法使用 symbolic debugger。
• 搭配 device emulator，使用 shim 這種技巧的概念：使用一個中介（例如檔案 IO），來存放執行時相關的資料或是參數，實際的 code 則是跑在本機。本技巧通常只是用演算法測試，不包括 UI 測試。我自己是覺得 core.dump 就是類似的東西。書中是舉手機中某個會用到網路與 API 的應用程式先在本機上寫好並且測試好，然後包成一個 class 整合進去原本的程式碼。
• Teamviewer 這東東應該不用再多說明了，名氣響亮。
• Teamviewer + strace or truss command on a third-party computer.
• KVM over IP device；使用情境：inaccessible data center. 我自己有用過這種東西（使用跟架設都有），有點厲害。例如，自己桌機的鍵盤訊號可以透過網路，在遠端的機器上就像真實的鍵盤輸入一樣（螢幕輸出則是由遠端電器訊號忠實送到你面前）。這種物理手段可以作到連 BIOS 階段都可以進去、調整。只是因為訊號傳送要一段時間，所以想要進 BIOS 有點要透過盲按 XDD 因為 BIOS 畫面往往幾秒而已，等送到你的螢幕上時早就跳掉了。