CNS-OIST/steps-modeling-skill

STEPS-Modellierung (API_2 / steps.interface)

STEPS simuliert stochastische Reaktions-Diffusion in 3D-Geometrien. Seit v3.6 ist die idiomatische Schnittstelle API_2 (steps.interface) – ein pythonischer Stil mit Context-Managern. Schreiben Sie alle neuen Modelle darin. Dieser Skill kodiert die Konventionen des Handbuchs (https://steps.sourceforge.net/manual) sowie Fallstricke, die KI-Agenten ausbremsen.

Lesen Sie reference.md für das vollständige Cheatsheet (Solver-Tabelle, Einheiten, EField/Komplexe/Parallel, ResultSelector-Rezepte, Mesh-aus-Pipeline-Hinweise). Starten Sie von einer Vorlage und passen Sie sie an. Die folgenden Regeln dürfen Sie nicht falsch machen.

Kardinalregeln

1. Imports, in dieser Reihenfolge. import steps.interface zuerst, dann Stern-Importe der Submodule. Mischen Sie niemals API_1 und API_2 in einem Skript.

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

2. Objekte benennen sich selbst über die Zuweisung. cyt = Compartment.Create(...) benennt das Objekt 'cyt' durch Lesen der Quellzeile. Sie verwenden es dann in Simulationspfaden als sim.cyt.Ca.Count. Der linke Variablenname ist also der Simulationsname – wählen Sie Namen, die Sie verwenden, und sie müssen gültige Python-Bezeichner sein.

3. .Create() benötigt eine echte name = X.Create(...) Quellzeile. Es schlägt fehl in einer Schleife, Comprehension, mehrzeiligen Aufruf, python -c oder jeder REPL ohne Source („entspricht nicht dem erwarteten Format für automatische Zuweisung“). Um Objekte programmatisch zu erstellen (z.B. ein ROI pro Region in einer Schleife), rufen Sie stattdessen den Konstruktor mit name= auf: ROI(triList, name=regionName).

4. Reaktionen leben in einem with-Block und verwenden einen ReactionManager r.

   r = ReactionManager()
   with vsys:
       A + B <r['bind']> C          # reversibel
       r['bind'].K = 1e6, 0.7       # (kf, kb); irreversibel '>r[..]>' benötigt nur ein K
   

   Oberflächenreaktionen markieren jede Spezies mit ihrem Ort: .i inneres Kompartiment, .o äußeres Kompartiment, .s die Patchoberfläche. Alle Volumen-Reaktanten müssen sich im selben Kompartiment befinden. Beispiel Pumpe: Ca.i + P.s >r['pump']> Ca.o + P.s.

5. Inneres Kompartiment des Patches kommt zuerst: Patch.Create(tris, inner, outer, ssys). Eine Begrenzungsmembran ohne Außenseite verwendet outer=None.

6. Alles ist SI, aber Conc ist molar. Diffusionskonstanten m²/s, Längen m, Count ist ganze Molekülzahl, Conc ist mol/L (molar). TetMesh.LoadGmsh(path, scale=...) multipliziert Mesh-Koordinaten in Meter – ein Nanometer-Mesh benötigt scale=1e-9.

7. Aufzeichnen mit ResultSelector, nicht mit ad-hoc-Abfragen.

   rs = ResultSelector(sim)
   caConc = rs.cyt.Ca.Conc            # Selektor bauen
   sim.toSave(caConc, dt=0.01)        # VOR dem Lauf registrieren
   ...
   caConc.data[run, timeIdx, col]; caConc.time[run]; caConc.labels
   

   Gruppen-Zugriff: .ALL(), .LIST(A, B), .MATCH(regex), .SUM(...), und für Mesh-Elemente sim.TET(t)/TETS(list), sim.TRI(t)/TRIS(list). sim.MATCH('regex') über die gesamte Simulation wählt jedes Kompartiment/Patch/ROI aus, dessen Name passt – der saubere Weg, viele benannte Regionen auf einmal anzusprechen.

8. Lauf-Schleife: sim.newRun() setzt den Zustand zurück; setzen Sie Anfangsbedingungen danach; dann sim.run(endTime). Für Statistiken mehrere Läufe in einer for-Schleife kapseln.

9. Reservierte Namen. Einzelne Großbuchstaben (A=Fläche, V=Volumen, D, I, ...) und Merkmalswörter (Ves, ...) sind reserviert – Spezies-/Objektnamen müssen beschreibende mehrbuchstabige Bezeichner sein (Ca, IP3, mitoMemb).

Kanonisches Skelett (räumlich, Tetexact)

Siehe templates/spatial_tetexact.py für eine lauffähige Version; templates/well_mixed.py für den gut durchmischten Fall.

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)     # Mesh-Koordinaten 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], 'at t =', caConc.time[0, -1])

Skript validieren

Vor dem Ausführen eines STEPS-Skripts, linten Sie es auf die obigen Fallstricke – keine Ausführung, STEPS nicht erforderlich:

python validate_steps_script.py model.py

Es meldet jedes Problem mit einer konkreten Korrektur: Import-Reihenfolge / API_1↔API_2-Vermischung, .Create() Missbrauch (Schleifen, keine Zuweisung), reservierte Spezies-Namen, Einheiten & biologischer Maßstab (Conc ist molar, Diffusion in m²/s, mesh scale=), newRun()/toSave()/run()-Reihenfolge, und Reaktionsraten, die deklariert aber nie gesetzt wurden. Exit-Code ist ungleich Null bei FEHLERN (passt also als Pre-Run-/CI-Gate); --selftest prüft den Prüfer.

Wartung dieses Skills

Wenn Sie einen STEPS-Skriptfehler treffen, den dieser Skill nicht verhindert hat, erweitern Sie ihn im selben Änderungssatz: Fügen Sie eine Prüfung (mit einem Selbsttestfall) zu validate_steps_script.py hinzu, dokumentieren Sie die Falle in den obigen Kardinalregeln, der reference.md-Tabelle häufiger Fehler und der folgenden Debugging-Checkliste. Halten Sie den Validator und die Dokumentation synchron – der Validator sollte jede dokumentierte Falle abfangen.

Debugging-Checkliste

• Assertion Fail: i < 4 beim Solver-Setup → ein Oberflächendreieck erscheint als zwei Elemente für eine Tet-Fläche (doppelte Grenzflächen-Facetten). Jede Facette benötigt genau ein Dreieckselement; das Mesh deduplizieren. (Siehe reference.md → „Meshes from a pipeline“.)
• „entspricht nicht dem erwarteten Format für automatische Zuweisung“ → ein .Create() nicht in einer eigenen name = ...Create(...) Zeile; den Konstruktor mit name= verwenden (Regel 3).
• „Name ist reserviert“ → die Spezies/das Objekt umbenennen (Regel 9).
• „Äußeres Kompartiment für diesen Patch nicht definiert“ → eine Oberflächenreaktion verwendete .o auf einem Begrenzungs-Patch, der mit outer=None erstellt wurde; dieser Patch kann nur .i/.s-Spezies aufnehmen.
• Alle Anzahlen nach einem Lauf null → Reaktions-K zu klein, oder die Dichte des Volumen-Reaktanten an der Oberfläche ist ~0; K oder Count erhöhen, oder Einheiten prüfen (Conc ist molar).