STEPS 모델링 스킬 (API_2 / steps.interface)

STEPS 모델링 (API_2 / steps.interface)

STEPS는 3D 형상에서 확률론적 반응-확산을 시뮬레이션합니다. v3.6부터 관용적 인터페이스는 API_2 (steps.interface)입니다 — Python 스타일의 컨텍스트 매니저 방식입니다. 모든 새 모델은 이 인터페이스로 작성하세요. 이 스킬은 수동 문서(https://steps.sourceforge.net/manual)의 규칙과 AI 에이전트가 자주 실수하는 함정을 인코딩합니다.

전체 치트시트는 reference.md를 참조하세요 (솔버 테이블, 단위, EField/복합체/병렬, ResultSelector 레시피, 파이프라인에서 메시 생성 관련 참고 사항). 템플릿에서 시작하여 적응시키세요. 아래 규칙은 반드시 지켜야 하는 규칙입니다.

핵심 규칙

1. 임포트 순서. 먼저 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 *
   

2. 객체는 할당문에서 이름을 가져옵니다. cyt = Compartment.Create(...)는 소스 라인을 읽어 객체 이름을 'cyt'로 지정합니다. 이후 시뮬레이션 경로에서 sim.cyt.Ca.Count와 같이 접근합니다. 따라서 왼쪽 변수 이름이 시뮬레이션 이름이 됩니다 — 사용할 이름을 선택하고, 유효한 Python 식별자여야 합니다.

3. .Create()는 실제 name = X.Create(...) 소스 라인이 필요합니다. 루프, 컴프리헨션, 여러 줄 호출, python -c, 또는 소스가 없는 REPL에서는 실패합니다("does not match the expected format for automatic assignment"). 객체를 프로그래밍 방식으로 생성해야 하는 경우(예: 각 영역별 ROI를 루프로 생성), 대신 생성자에 name=을 사용하세요: ROI(triList, name=regionName).

4. 반응은 with 블록 안에 있으며 ReactionManager r을 사용합니다.

   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.

5. 패치 내부 구획이 먼저 옵니다: Patch.Create(tris, inner, outer, ssys). 외부가 없는 경계막은 outer=None을 사용합니다.

6. 모든 것은 SI 단위지만, Conc는 몰 농도입니다. 확산 상수 m²/s, 길이 m, Count는 분자 수, Conc는 mol/L (몰)입니다. TetMesh.LoadGmsh(path, scale=...)는 메시 좌표를 미터 단위로 변환합니다 — 나노미터 메시는 scale=1e-9가 필요합니다.

7. 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를 선택합니다 — 여러 명명된 영역을 한 번에 처리하는 깔끔한 방법입니다.

8. 실행 루프: sim.newRun()은 상태를 리셋합니다; 그 후에 초기 조건을 설정하고, sim.run(endTime)을 실행합니다. 통계를 위해 여러 실행을 for 루프로 감쌉니다.

9. 예약된 이름. 단일 대문자(A=Area, V=Volume, D, I, ...) 및 특징 단어(Ves, ...)는 예약되어 있습니다 — Species/객체 이름은 설명적인 여러 글자 식별자여야 합니다(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() 오용 (루프, 할당 없음), 예약된 Species 이름, 단위 및 생물학적 스케일 (Conc는 몰, Diffusion은 m²/s, mesh scale=), newRun/toSave/run 순서, 선언되었지만 설정되지 않은 반응 속도. ERROR가 있으면 종료 코드가 0이 아닙니다 (따라서 실행 전 / CI 게이트에 적합); --selftest는 검사기를 테스트합니다.

이 스킬 유지보수

이 스킬이 방지하지 못한 STEPS 스크립팅 오류를 발견하면, 동일한 변경에서 확장하세요: validate_steps_script.py에 검사(셀프테스트 케이스 포함)를 추가하고, 위의 핵심 규칙, reference.md의 공통 오류 테이블, 그리고 아래의 디버깅 체크리스트에 함정을 기록하세요. 검증기와 문서를 동기화 상태로 유지하세요 — 검증기는 문서화된 모든 함정을 잡아내야 합니다.

디버깅 체크리스트

• 솔버 설정 시 Assertion Fail: i < 4 → 표면 삼각형이 하나의 테트 면에 대해 두 요소로 나타납니다 (중복 인터페이스 면). 각 면에는 정확히 하나의 삼각형 요소가 필요합니다; 메시 중복을 제거하세요. (reference.md → "파이프라인에서 메시 생성" 참조.)
• "does not match the expected format for automatic assignment" → .Create()가 자체 name = ...Create(...) 라인에 있지 않습니다; name=을 가진 생성자를 사용하세요 (규칙 3).
• "name is reserved" → Species/객체 이름을 변경하세요 (규칙 9).
• "Outer compartment not defined for this patch" → 표면 반응이 outer=None으로 생성된 경계 패치에서 .o를 사용했습니다; 해당 패치는 .i/.s 종만 호스팅할 수 있습니다.
• 실행 후 모든 Count가 0 → 반응 K가 너무 작거나, 표면에서 체적 반응물의 밀도가 0에 가깝습니다; K 또는 Count를 높이거나, 단위를 확인하세요 (Conc는 몰입니다).