STEPS 建模（API_2 / steps.interface）
STEPS 在 3D 幾何中模擬隨機反應擴散。從 v3.6 開始，慣用的介面是 API_2（steps.interface）——一種 Pythonic 的、使用 context manager 的風格。所有新模型都應使用此介面。此技能編碼了手冊（https://steps.sourceforge.net/manual）的慣例以及經常困擾 AI 代理的陷阱。
閱讀 reference.md 以獲取完整速查表（求解器表格、單位、EField/複合體/平行、ResultSelector 配方、網格管線注意事項）。從範本開始並進行改編。以下規則是您絕對不能搞錯的。
基本規則
-
匯入，按順序。 首先
import steps.interface，然後星號匯入子模組。切勿在同一腳本中混合 API_1 和 API_2。import steps.interface from steps.model import * from steps.geom import * from steps.rng import * from steps.sim import * from steps.saving import * -
物件從賦值語句中獲取名稱。
cyt = Compartment.Create(...)透過讀取原始碼行來命名物件為'cyt'。然後您在模擬路徑中以sim.cyt.Ca.Count來定址它。因此，左側的變數名稱就是模擬名稱——請選擇您將使用的名稱，且它們必須是有效的 Python 識別碼。 -
.Create()需要一個實際的name = X.Create(...)原始碼行。 它在迴圈、推導式、多行呼叫、python -c或任何沒有原始碼的 REPL 中都會失敗（「不符合自動賦值的預期格式」）。要以程式化方式建立物件（例如在迴圈中為每個區域建立一個 ROI），請改用帶有name=參數的建構子：ROI(triList, name=regionName)。 -
反應位於
with區塊內，並使用 ReactionManagerr。r = ReactionManager() with vsys: A + B <r['bind']> C # 可逆反應 r['bind'].K = 1e6, 0.7 # (kf, kb)；不可逆反應 '>r[..]>' 只需一個 K表面反應會用位置標記每個物種：
.i內部隔室、.o外部隔室、.s補丁表面。所有體積反應物必須位於同一隔室中。泵：Ca.i + P.s >r['pump']> Ca.o + P.s。 -
補丁內部隔室在前：
Patch.Create(tris, inner, outer, ssys)。對於外部無物的邊界膜，使用outer=None。 -
一切都是 SI 單位，但
Conc是莫耳濃度。 擴散常數單位 m²/s，長度單位 m，Count是整數分子數，Conc是 mol/L（莫耳濃度）。TetMesh.LoadGmsh(path, scale=...)將網格座標乘以比例轉換為公尺——奈米網格需要scale=1e-9。 -
使用 ResultSelector 進行記錄，而非即時讀取。
rs = ResultSelector(sim) caConc = rs.cyt.Ca.Conc # 建立選擇器 sim.toSave(caConc, dt=0.01) # 在運行之前註冊 ... caConc.data[run, timeIdx, col]; caConc.time[run]; caConc.labels群組存取：
.ALL()、.LIST(A, B)、.MATCH(regex)、.SUM(...)，以及對於網格元素sim.TET(t)/TETS(list)、sim.TRI(t)/TRIS(list)。sim.MATCH('regex')遍歷整個模擬，選取名稱匹配的每個隔室/補丁/ROI——這是在一次操作中處理多個命名區域的簡潔方式。 -
執行迴圈：
sim.newRun()重設狀態；在它之後設定初始條件；然後sim.run(endTime)。將多次運行包裝在for迴圈中以進行統計。 -
保留名稱。 單個大寫字母（
A=面積、V=體積、D、I……）和功能詞彙（Ves……）是保留的——物種/物件名稱必須是描述性的多字母識別碼（Ca、IP3、mitoMemb）。
典型骨架（空間、Tetexact）
請參閱 templates/spatial_tetexact.py 以取得可執行版本；templates/well_mixed.py 適用於均相情況。
import steps.interface
from steps.model import *
from steps.geom import *
from steps.rng import *
from steps.sim import *
from steps.saving import *
mdl = Model()
r = ReactionManager()
with mdl:
Ca, P = Species.Create()
vsys = VolumeSystem.Create()
with vsys:
Diffusion(Ca, 1e-12)
ssys = SurfaceSystem.Create()
with ssys:
Ca.i + P.s >r['pump']> Ca.o + P.s
r['pump'].K = 2e8
mesh = TetMesh.LoadGmsh('model.msh', scale=1e-9) # 網格座標 nm -> m
with mesh:
cyt = Compartment.Create(mesh.tetGroups[(0, 'cytosol')], vsys)
er = Compartment.Create(mesh.tetGroups[(0, 'ER')], vsys)
memb = Patch.Create(mesh.triGroups[(0, 'ER_surface')], er, cyt, ssys)
rng = RNG('mt19937', 512, 1234)
sim = Simulation('Tetexact', mdl, mesh, rng)
rs = ResultSelector(sim)
caConc = rs.cyt.Ca.Conc
sim.toSave(caConc, dt=0.01)
sim.newRun()
sim.cyt.Ca.Conc = 1e-6 # 莫耳濃度
sim.memb.P.Count = 100
sim.run(1.0)
print(caConc.data[0, -1], 'at t =', caConc.time[0, -1])
驗證腳本
在執行 STEPS 腳本之前，針對上述陷阱對其進行語法檢查，無需執行，也無需 STEPS：
python validate_steps_script.py model.py
它會報告每個問題並附上具體的修正建議：匯入順序 / API_1↔API_2 混用、.Create() 誤用（迴圈、無賦值）、保留的物種名稱、單位與生物尺度（Conc 為莫耳濃度、Diffusion 單位 m²/s、網格 scale=）、newRun/toSave/run 的順序，以及已宣告但從未設定的反應速率。錯誤時退出代碼非零（因此適合做為執行前 / CI 關卡）；--selftest 用於檢查檢查器本身。
維護此技能
當您遇到此技能未能預防的 STEPS 腳本錯誤時，請在同一變更中擴展它：在 validate_steps_script.py 中新增一個檢查（附上自測案例），並將該陷阱記錄在上述基本規則、reference.md 的常見錯誤表格以及下面的除錯檢查清單中。保持驗證器與文件同步——驗證器應能捕捉到所有記錄在案的陷阱。
除錯檢查清單
- 求解器設定時出現
Assertion Fail: i < 4→ 一個表面三角形作為一個四面體面的兩個元素出現（重複的介面面）。每個面需要恰好一個三角形元素；對網格進行去重。（參見 reference.md →「來自管線的網格」。） - 「不符合自動賦值的預期格式」→
.Create()不在其專用的name = ...Create(...)行上；使用帶有name=的建構子（規則 3）。 - 「名稱已被保留」→ 重新命名物種/物件（規則 9）。
- 「未為此補丁定義外部隔室」→ 表面反應在一個以
outer=None建立的邊界補丁上使用了.o；該補丁只能容納.i/.s物種。 - 運行後所有計數為零 → 反應
K太小，或體積反應物在表面上的密度接近 0；提高K或Count，或檢查單位（Conc是莫耳濃度）。