CNS-OIST/compétence-modélisation-STEPS

Modélisation STEPS (API_2 / steps.interface)

STEPS simule la réaction-diffusion stochastique dans des géométries 3D. Depuis la v3.6, l'interface idiomatique est API_2 (steps.interface) — un style pythonique basé sur les gestionnaires de contexte. Écrivez tous les nouveaux modèles avec cette API. Cette compétence encode les conventions du manuel (https://steps.sourceforge.net/manual) ainsi que les pièges qui surprennent les agents IA.

Lisez reference.md pour l'antisèche complète (tableau des solveurs, unités, EField/complexes/parallèle, recettes ResultSelector, notes sur le maillage depuis un pipeline). Commencez par un modèle et adaptez-le. Les règles ci-dessous sont celles à ne pas enfreindre.

Règles cardinales

1. Imports, dans l'ordre. import steps.interface en PREMIER, puis importez les sous-modules avec *. Ne mélangez jamais API_1 et API_2 dans un même 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. Les objets se nomment eux-mêmes à partir de l'affectation. cyt = Compartment.Create(...) nomme l'objet 'cyt' en lisant la ligne source. Vous l'utilisez ensuite dans les chemins de simulation sous la forme sim.cyt.Ca.Count. Ainsi, le nom de la variable à gauche est le nom dans la simulation — choisissez des noms que vous utiliserez, et ils doivent être des identifiants Python valides.

3. .Create() nécessite une ligne source réelle name = X.Create(...). Cela échoue dans une boucle, une compréhension de liste, un appel multiligne, python -c, ou tout REPL sans source (« does not match the expected format for automatic assignment »). Pour créer des objets par programmation (par exemple, une ROI par région dans une boucle), utilisez le constructeur avec name= à la place : ROI(triList, name=nomRegion).

4. Les réactions vivent dans un bloc with et utilisent un ReactionManager r.

   r = ReactionManager()
   with vsys:
       A + B <r['bind']> C          # réversible
       r['bind'].K = 1e6, 0.7       # (kf, kb) ; irréversible '>r[..]>' prend un seul K
   

   Les réactions de surface marquent chaque espèce avec son emplacement : .i compartiment interne, .o compartiment externe, .s la surface du patch. Tous les réactifs volumiques doivent être dans le même compartiment. Exemple de pompe : Ca.i + P.s >r['pump']> Ca.o + P.s.

5. Le compartiment intérieur du patch vient en premier : Patch.Create(tris, interieur, exterieur, ssys). Une membrane limite sans rien à l'extérieur utilise exterieur=None.

6. Tout est en SI, mais Conc est en molaire. Constantes de diffusion en m²/s, longueurs en m, Count en molécules entières, Conc en mol/L (molaire). TetMesh.LoadGmsh(chemin, scale=...) multiplie les coordonnées du maillage en mètres — un maillage en nanomètres nécessite scale=1e-9.

7. Enregistrez avec ResultSelector, pas de lectures ad-hoc.

   rs = ResultSelector(sim)
   caConc = rs.cyt.Ca.Conc            # construit un sélecteur
   sim.toSave(caConc, dt=0.01)        # enregistrer AVANT l'exécution
   ...
   caConc.data[run, idxTemps, col]; caConc.time[run]; caConc.labels
   

   Accès par groupe : .ALL(), .LIST(A, B), .MATCH(regex), .SUM(...), et pour les éléments du maillage sim.TET(t)/TETS(liste), sim.TRI(t)/TRIS(liste). sim.MATCH('regex') sur toute la simulation sélectionne chaque compartiment/patch/ROI dont le nom correspond — la façon propre d'adresser plusieurs régions nommées à la fois.

8. Boucle d'exécution : sim.newRun() réinitialise l'état ; définissez les conditions initiales après ; puis sim.run(tempsFin). Enveloppez plusieurs exécutions dans une boucle for pour les statistiques.

9. Noms réservés. Les lettres majuscules isolées (A=Aire, V=Volume, D, I, ...) et les mots fonctionnels (Ves, ...) sont réservés — les noms d'espèces/objets doivent être des identifiants descriptifs de plusieurs lettres (Ca, IP3, mitoMemb).

Squelette canonique (spatial, Tetexact)

Voir templates/spatial_tetexact.py pour une version exécutable ; templates/well_mixed.py pour le cas bien mélangé.

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)     # coordonnées maillage 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        # molaire
sim.memb.P.Count = 100
sim.run(1.0)
print(caConc.data[0, -1], 'à t =', caConc.time[0, -1])

Valider un script

Avant d'exécuter un script STEPS, vérifiez-le pour les pièges ci-dessus — sans exécution, STEPS n'est pas requis :

python validate_steps_script.py model.py

Il signale chaque problème avec une correction concrète : ordre d'import / mélange API_1↔API_2, mauvaise utilisation de .Create() (boucles, absence d'affectation), noms d'espèces réservés, unités et échelle biologique (Conc est molaire, Diffusion en m²/s, scale= du maillage), ordre newRun/toSave/run, et constantes de réaction déclarées mais jamais définies. Le code de sortie est non nul en cas d'ERREUR (pour une pré-exécution ou un CI) ; --selftest vérifie le validateur.

Maintenir cette compétence

Lorsque vous rencontrez une erreur de script STEPS que cette compétence n'a pas empêchée, étendez-la dans la même modification : ajoutez une vérification (avec un cas de test) à validate_steps_script.py, et enregistrez le piège dans les règles cardinales ci-dessus, dans le tableau des erreurs courantes de reference.md, et dans la liste de débogage ci-dessous. Gardez le validateur et la documentation synchronisés — le validateur doit détecter tous les pièges documentés.

Liste de débogage

• Assertion Fail: i < 4 lors de la configuration du solveur → un triangle de surface apparaît comme deux éléments pour une face de tétraèdre (facettes d'interface dupliquées). Chaque facette doit avoir exactement un élément triangulaire ; dédupliquez le maillage. (Voir reference.md → « Maillages depuis un pipeline ».)
• « does not match the expected format for automatic assignment » → un .Create() qui n'est pas sur sa propre ligne name = ...Create(...) ; utilisez le constructeur avec name= (règle 3).
• « name is reserved » → renommez l'espèce/l'objet (règle 9).
• « Outer compartment not defined for this patch » → une réaction de surface a utilisé .o sur un patch limite créé avec exterieur=None ; ce patch ne peut accueillir que des espèces .i/.s.
• Tous les comptes à zéro après une exécution → la constante de réaction K est trop petite, ou la densité du réactif volumique à la surface est ~0 ; augmentez K ou Count, ou vérifiez les unités (Conc est molaire).