ActivePapers 教學指南

ActivePapers 教學指南 本簡短教學將示範如何： * 檢視 ActivePaper 的內容 * 擷取代碼與文件（包含圖表） * 修改計算參數 * 修改代碼 * 重新執行計算 * 從頭建立一個 ActivePaper 本教學的範例檔案可從 Figshare 下載。同時建議您參閱 Figshare 網站上的說明。您無需理解其運作原理或目的，但若有興趣，歡迎閱讀描述此項工作的論文，該論文探討如何根據分子動力學軌跡，計算溶液中蛋白質的平移與旋轉擴散張量。 請將下載的 ActivePaper 檔案複製到一個空目錄中。開啟終端機視窗，並進入該目錄。當您輸入 ls -l 時，應該會看到類似以下的內容： -rw-r--r-- 1 hinsen staff 148133188 Sep 26 16:21 lysozyme_diffusion.ap ## 檢視內容 執行 aptool ls 會產生一長串的資料集清單，起始內容如下： code/correlation_functions code/diffusion_tensor code/identify_trajectories code/plots code/python-packages/fitting code/python-packages/molecular_structure code/python-packages/mosaic code/python-packages/quaternion code/python-packages/time_series code/python-packages/units code/thermal_averages code/trajectory_processing data/coordinate_trajectories/rotation_laboratory_frame_1 data/coordinate_trajectories/rotation_laboratory_frame_10 data/coordinate_trajectories/rotation_laboratory_frame_2 但 aptool 如何知道您要檢視哪個 ActivePaper 檔案呢？其實，若目前目錄中只有一個副檔名為 .ap 的檔案，它就會自動選用該檔案。這也正是為何建議每個 ActivePaper 專案都使用獨立目錄的原因。若因某些原因您不想這麼做，也可以明確指定 ActivePaper 檔名： aptool ls -p lysozyme_diffusion.ap 使用 aptool ls -l 可獲取更詳細的資訊，輸出結果如下： 2013-06-07/09:13:05 calclet code/correlation_functions 2013-06-07/09:19:48 calclet code/diffusion_tensor 2013-06-07/10:02:29 calclet code/identify_trajectories 2013-06-12/08:03:48 calclet code/plots 2013-06-04/15:42:02 module code/python-packages/fitting 2013-05-02/15:11:53 module code/python-packages/molecular_structure 2013-06-14/15:46:18 reference code/python-packages/mosaic 2013-05-23/11:42:31 module code/python-packages/quaternion 2013-05-27/04:13:09 module code/python-packages/time_series 2013-05-02/15:12:07 module code/python-packages/units 此外還有許多類似行列。第一欄顯示每個資料集最後修改的日期與時間。第二欄則顯示資料集的類型。上述清單中包含兩種可執行代碼的類型：calclet 與 module。還有一種未在此清單中出現的類型：importlet。 module 正如 Python 程式設計師所預期：一個供其他 Python 代碼匯入的 Python 原始碼檔案。calclet 和 importlet 則是 ActivePapers 提供的兩種腳本變體。最常見的類型是 calclet，它是一種權限受限的 Python 腳本：無法在所含的 ActivePaper 檔案之外進行任何輸入/輸出操作，這意味著它既無法存取檔案，也無法存取網路資源。這些限制確保了可重現性（所有輸入資料保證都位於 ActivePaper 內），並保護使用者免受錯誤或惡意代碼的侵害。但這也意味著 calclet 不能用來將資料匯入 ActivePaper。這時就輪到 importlet 登場：它們可以使用任何 Python 功能並存取任何資源。這也表示，在未先檢視他人編寫的 importlet 之前，切勿執行它們。[[Calclets]] 頁面將告訴您如何編寫 calclet 和 importlet。 上述清單中還有一種資料集類型：reference（參考），用於引用其他 ActivePaper 檔案中的資料集。參考由兩部分組成：對檔案的參考，以及該檔案內資料集的名稱。檔案參考可以是已發表檔案的 DOI，也可以是本機檔名。顯然，本機檔名在其他人的電腦上毫無意義，因此本機參考有點像 importlet：它們記錄資料來源，但並未實際提供該資料。 讓我們檢視我們 ActivePaper 中的參考： aptool refs 我們會發現一個 DOI 和十個本機參考： doi:10.6084/m9.figshare.705829 local:lysozyme_spce_rbt_1 local:lysozyme_spce_rbt_10 local:lysozyme_spce_rbt_2 local:lysozyme_spce_rbt_3 local:lysozyme_spce_rbt_4 local:lysozyme_spce_rbt_5 local:lysozyme_spce_rbt_6 local:lysozyme_spce_rbt_7 local:lysozyme_spce_rbt_8 local:lysozyme_spce_rbt_9 該 DOI 對應於 deposited 在 Figshare 上的 pyMosaic 程式庫版本 0.1.1。本機檔案則是在 ActivePaper 中分析的模擬軌跡。 讓我們進一步獲取這些參考的詳細資訊： aptool refs -v doi:10.6084/m9.figshare.705829 links: code/python-packages/mosaic local:lysozyme_spce_rbt_1 copies: data/center_of_mass data/orientation data/reference_structure data/time 其餘九個輸入檔案亦然。這顯示 DOI 被用於連結至目標檔案的資料集 code/python-packages/mosaic，而本機檔案則作為複製到 ActivePaper 內部資料的來源。因此，複製參考僅用於文件記錄，無需擁有被參考檔案的副本。 回到資料集類型。還有幾種類型未在 aptool ls -l 的前幾行中出現，讓我們檢視剩餘行列中的幾個範例： 2013-07-03/12:24:26 text documentation/README 2013-06-14/15:55:08 file documentation/c_rr_diagonals.pdf 2013-06-14/15:55:00 data data/correlation_function_integration_limit 2013-06-14/15:46:47 dummy data/coordinate_trajectories/rotation_laboratory_frame_1 您大概能猜出 text 的含義。而 file 就是 Unix 世界中的檔案：一串位元組，沒有附加任何特定詮釋。稍後您將看到如何擷取此类檔案。data 的含義或許較不明顯，特別是它與 file 有何不同。答案是：data 是一個任意的 HDF5 資料集，由資料空間和資料類型所特徵化。若您願意，可將其視為陣列，事實上確實非常接近。 最後剩下 dummy，這是一個不存在的資料集。更精確地說，是曾經存在但现已刪除的資料集。它是由 calclet 生成的資料集，隨後被明確移除（使用 aptool dummy ...）以縮減檔案大小。若您想檢視它，或執行任何讀取它的 calclet，必須先透過重新執行該 calclet 來重新生成它。 那麼讓我們這麼做： aptool update -v 這會更新 ActivePaper 中所有需要更新的內容：包括 dummy 資料集，以及過時的資料集（即比生成它们的 calclet 當前版本更舊的資料集）。-v 選項會啟用詳細模式，告知您執行了哪些 calclet 及其原因。請做好等待準備；在我的機器上，此操作大約需要八分鐘。 我們可以發現檔案大小顯著增加： ls -l -rw-r--r-- 1 hinsen staff 540352636 Oct 23 14:54 lysozyme_diffusion.ap 此外，原先的 dummy 資料集現在已是真實存在的資料集： aptool ls -l data/coordinate_trajectories/rotation_laboratory_frame_1 2013-10-23/14:45:29 data data/coordinate_trajectories/rotation_laboratory_frame_1 ## 擷取圖表 若您檢視 aptool ls -l 的完整輸出，會注意到 documentation 下有幾個 PDF 檔案。若要檢視它們，請將其擷取為真實檔案： aptool checkout documentation 這也會讓您取得 README，因為它會將 HDF5 群組 documentation 中的所有內容擷取到一個名為 documentation 的本機目錄（沒錯，就是這個名字）。ActivePaper 中的 documentation 群組專為供人類閱讀的資料設計，通常不用作計算輸入。 當然，您也可以單獨擷取特定檔案，例如： aptool checkout documentation/README.txt checkout 命令僅擷取那些比磁碟上對應檔案更新的資料集（若該檔案已存在）。因此您可以編輯已擷取的檔案，而不必擔心它們被覆蓋。接下來在处理代碼時，我們將立即看到這一點。 ## 擷取並修改代碼 接下來，讓我們檢視所有代碼