CNS-OIST/habilidade-modelagem-steps

Modelagem STEPS (API_2 / steps.interface)

STEPS simula reação-difusão estocástica em geometrias 3D. Desde a v3.6, a interface idiomática é API_2 (steps.interface) — um estilo pythonico com gerenciadores de contexto. Escreva todos os novos modelos nela. Esta habilidade codifica as convenções do manual (https://steps.sourceforge.net/manual) além de pegadinhas que pegam agentes de IA.

Leia reference.md para a cola completa (tabela de solvers, unidades, EField/complexos/paralelo, receitas de ResultSelector, notas sobre malha de pipeline). Comece a partir de um modelo e adapte. As regras abaixo são aquelas que você não deve errar.

Regras cardinais

1. Importações, em ordem. import steps.interface PRIMEIRO, depois importe com estrela os submódulos. Nunca misture API_1 e API_2 em um mesmo script.

   import steps.interface
   from steps.model import *
   from steps.geom import *
   from steps.rng import *
   from steps.sim import *
   from steps.saving import *
   

2. Objetos se nomeiam a partir da atribuição. cyt = Compartment.Create(...) nomeia o objeto 'cyt' lendo a linha de código fonte. Você então o endereça nos caminhos de simulação como sim.cyt.Ca.Count. Portanto, o nome da variável à esquerda é o nome da simulação — escolha nomes que você usará, e eles devem ser identificadores Python válidos.

3. .Create() precisa de uma linha fonte real nome = X.Create(...). Ele falha em um loop, compreensão, chamada multilinha, python -c ou qualquer REPL sem código fonte ("não corresponde ao formato esperado para atribuição automática"). Para criar objetos programaticamente (ex.: um ROI por região em um loop), chame o construtor com name= em vez disso: ROI(triList, name=nomeRegiao).

4. Reações vivem em um bloco with e usam um ReactionManager r.

   r = ReactionManager()
   with vsys:
       A + B <r['bind']> C          # reversível
       r['bind'].K = 1e6, 0.7       # (kf, kb); irreversível '>r[..]>' leva um K
   

   Reações de superfície marcam cada espécie com sua localização: .i compartimento interno, .o compartimento externo, .s a superfície da patch. Todos os reagentes de volume devem estar no mesmo compartimento. Uma bomba: Ca.i + P.s >r['pump']> Ca.o + P.s.

5. Compartimento interno da patch vem primeiro: Patch.Create(tris, interno, externo, ssys). Uma membrana de fronteira sem nada do lado de fora usa externo=None.

6. Tudo é SI, mas Conc é molar. Constantes de difusão em m²/s, comprimentos em m, Count são moléculas inteiras, Conc é mol/L (molar). TetMesh.LoadGmsh(caminho, scale=...) multiplica as coordenadas da malha para metros — uma malha em nanômetros precisa de scale=1e-9.

7. Registre com ResultSelector, não com leituras ad-hoc.

   rs = ResultSelector(sim)
   caConc = rs.cyt.Ca.Conc            # constrói um seletor
   sim.toSave(caConc, dt=0.01)        # registra ANTES de executar
   ...
   caConc.data[execucao, idxTempo, col]; caConc.time[execucao]; caConc.labels
   

   Acesso a grupos: .ALL(), .LIST(A, B), .MATCH(regex), .SUM(...), e para elementos da malha sim.TET(t)/TETS(lista), sim.TRI(t)/TRIS(lista). sim.MATCH('regex') sobre toda a simulação seleciona todo compartimento/patch/ROI cujo nome corresponda — a maneira limpa de endereçar muitas regiões nomeadas de uma vez.

8. Loop de execução: sim.newRun() redefine o estado; defina condições iniciais após ele; depois sim.run(tempoFim) . Envolva múltiplas execuções em um loop for para estatísticas.

9. Nomes reservados. Letras maiúsculas únicas (A=Área, V=Volume, D, I, ...) e palavras de recurso (Ves, ...) são reservados — nomes de Species/objeto devem ser identificadores descritivos com múltiplas letras (Ca, IP3, mitoMemb).

Esqueleto canônico (espacial, Tetexact)

Veja templates/spatial_tetexact.py para uma versão executável; templates/well_mixed.py para o caso bem misturado.

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)     # coordenadas da malha 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        # molar
sim.memb.P.Count = 100
sim.run(1.0)
print(caConc.data[0, -1], 'em t =', caConc.time[0, -1])

Validar um script

Antes de executar um script STEPS, faça lint dele para as armadilhas acima — sem execução, STEPS não é necessário:

python validate_steps_script.py modelo.py

Ele reporta cada problema com uma correção concreta: ordem de importação / mistura API_1↔API_2, uso incorreto de .Create() (loops, sem atribuição), nomes de Species reservados, unidades e escala biológica (Conc é molar, Difusão em m²/s, scale= da malha), ordenação newRun/toSave/run, e taxas de reação declaradas mas nunca definidas. O código de saída é não-zero em ERROS (então se encaixa em uma porta pré-execução / CI); --selftest verifica o verificador.

Manutenção desta habilidade

Quando você encontrar um erro de script STEPS que esta habilidade não preveniu, estenda-a na mesma alteração: adicione uma verificação (com um caso de autoteste) ao validate_steps_script.py, e registre a armadilha nas regras cardinais acima, na tabela de erros comuns do reference.md, e na lista de verificação de depuração abaixo. Mantenha o validador e a documentação sincronizados — o validador deve pegar toda pegadinha documentada.

Lista de verificação de depuração

• Assertion Fail: i < 4 na configuração do solver → um triângulo de superfície aparece como dois elementos para uma face de tetraedro (faces de interface duplicadas). Cada face precisa exatamente de um elemento de triângulo; deduplique a malha. (Veja reference.md → "Malhas de um pipeline".)
• "não corresponde ao formato esperado para atribuição automática" → um .Create() não em sua própria linha nome = ...Create(...); use o construtor com name= (regra 3).
• "nome é reservado" → renomeie a Species/objeto (regra 9).
• "Compartimento externo não definido para esta patch" → uma reação de superfície usou .o em uma patch de fronteira criada com externo=None; essa patch só pode hospedar espécies .i/.s.
• Contagens todas zero após uma execução → constante de reação K muito pequena, ou a densidade do reagente de volume na superfície é ~0; aumente K ou Contagem, ou verifique as unidades (Conc é molar).