CNS-OIST/steps-modeling-skill

Modelado en STEPS (API_2 / steps.interface)

STEPS simula reacción-difusión estocástica en geometrías 3D. Desde la versión 3.6 la interfaz idiomática es API_2 (steps.interface) — un estilo pitónico con gestor de contexto. Escribe todos los modelos nuevos en ella. Esta habilidad codifica las convenciones del manual (https://steps.sourceforge.net/manual) además de los obstáculos que suelen atrapar a los agentes de IA.

Lee reference.md para la chuleta completa (tabla de solvers, unidades, EField/complejos/paralelo, recetas de ResultSelector, notas sobre mallas procedentes de pipelines). Empieza desde una plantilla y adáptala. Las reglas siguientes son las que no debes incumplir.

Reglas cardinales

1. Importaciones, en orden. import steps.interface PRIMERO, luego importa con asterisco los submódulos. Nunca mezcles API_1 y API_2 en un mismo 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. Los objetos se nombran a sí mismos a partir de la asignación. cyt = Compartment.Create(...) nombra al objeto 'cyt' leyendo la línea fuente. Luego lo referencias en las rutas de simulación como sim.cyt.Ca.Count. Por lo tanto, el nombre de la variable a la izquierda es el nombre de simulación — elige nombres que vayas a usar, y deben ser identificadores Python válidos.

3. .Create() necesita una línea fuente real name = X.Create(...). Falla en un bucle, comprensión, llamada multilínea, python -c o cualquier REPL sin fuente ("does not match the expected format for automatic assignment"). Para crear objetos programáticamente (ej. un ROI por región en un bucle), usa el constructor con name= en su lugar: ROI(triList, name=nombreRegion).

4. Las reacciones viven dentro de un bloque with y usan un ReactionManager r.

   r = ReactionManager()
   with vsys:
       A + B <r['bind']> C          # reversible
       r['bind'].K = 1e6, 0.7       # (kf, kb); irreversible '>r[..]>' toma una K
   

   Las reacciones de superficie etiquetan cada especie con su ubicación: .i compartimento interno, .o compartimento externo, .s la superficie del parche. Todos los reactivos de volumen deben estar en el mismo compartimento. Una bomba: Ca.i + P.s >r['pump']> Ca.o + P.s.

5. El compartimento interno del parche va primero: Patch.Create(tris, interno, externo, ssys). Una membrana límite sin nada fuera usa externo=None.

6. Todo está en SI, pero Conc es molar. Constantes de difusión en m²/s, longitudes en m, Count son moléculas enteras, Conc está en mol/L (molar). TetMesh.LoadGmsh(ruta, scale=...) multiplica las coordenadas de la malla para obtener metros — una malla en nanómetros necesita scale=1e-9.

7. Registra con ResultSelector, no con lecturas ad-hoc.

   rs = ResultSelector(sim)
   caConc = rs.cyt.Ca.Conc            # construye un selector
   sim.toSave(caConc, dt=0.01)        # registra ANTES de ejecutar
   ...
   caConc.data[run, timeIdx, col]; caConc.time[run]; caConc.labels
   

   Acceso por grupos: .ALL(), .LIST(A, B), .MATCH(regex), .SUM(...), y para elementos de malla sim.TET(t)/TETS(lista), sim.TRI(t)/TRIS(lista). sim.MATCH('regex') sobre toda la simulación selecciona todo compartimento/parche/ROI cuyo nombre coincida — la forma limpia de referirse a múltiples regiones nombradas a la vez.

8. Bucle de ejecución: sim.newRun() reinicia el estado; establece condiciones iniciales después de él; luego sim.run(tiempoFinal).

9. Nombres reservados. Mayúsculas simples (A=Área, V=Volumen, D, I, ...) y palabras clave (Ves, ...) están reservados — los nombres de Species/objetos deben ser identificadores descriptivos de varias letras (Ca, IP3, mitoMemb).

Esqueleto canónico (espacial, Tetexact)

Consulta templates/spatial_tetexact.py para una versión ejecutable; templates/well_mixed.py para el caso bien mezclado.

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 malla 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], 'en t =', caConc.time[0, -1])

Validar un script

Antes de ejecutar un script de STEPS, revísalo con el linter para detectar los problemas anteriores — sin ejecución, no requiere STEPS:

python validate_steps_script.py model.py

Reporta cada problema con una corrección concreta: orden de importación / mezcla API_1↔API_2, mal uso de .Create() (bucles, sin asignación), nombres reservados de Species, unidades y escala biológica (Conc es molar, Difusión en m²/s, scale= en malla), orden de newRun/toSave/run, y constantes de reacción declaradas pero nunca establecidas. El código de salida es distinto de cero en caso de ERROR (así encaja en una puerta de pre-ejecución / CI); --selftest verifica el propio comprobador.

Mantenimiento de esta habilidad

Cuando encuentres un error de scripteo en STEPS que esta habilidad no previó, amplíala en el mismo cambio: añade una comprobación (con un caso de auto-prueba) a validate_steps_script.py, y registra la trampa en las reglas cardinales anteriores, en la tabla de errores comunes de reference.md, y en la lista de verificación de depuración más abajo. Mantén el validador y la documentación sincronizados — el validador debe detectar cada obstáculo documentado.

Lista de verificación de depuración

• Assertion Fail: i < 4 al configurar el solver → un triángulo de superficie aparece como dos elementos para una cara de tetraedro (facetas de interfaz duplicadas). Cada faceta necesita exactamente un elemento triángulo; desduplica la malla. (Ver reference.md → "Mallas procedentes de una pipeline".)
• "does not match the expected format for automatic assignment" → un .Create() que no está en su propia línea name = ...Create(...); usa el constructor con name= (regla 3).
• "name is reserved" → renombra la Species/objeto (regla 9).
• "Outer compartment not defined for this patch" → una reacción de superficie usó .o en un parche límite creado con outer=None; ese parche solo puede albergar especies .i/.s.
• Todos los Counts son cero tras una ejecución → la constante K de reacción es demasiado pequeña, o la densidad del reactivo de volumen en la superficie es ~0; aumenta K o Count, o verifica las unidades (Conc es molar).