j2k_modules.md

 [[_TOC_]]
 
-# Principe général
+# Introduction
+
+Un modèle J2K est un agencement de modules associé à un état initial et à des valeurs de paramètres. Le fonctionnement des modules est codé en java mais la plupart des utilisateurs ne programment pas eux-mêmes les modules, ils utilisent des modules existant qu'ils agencent et paramétrisent en utilisant un logiciel dédié appelé juice. 
 
-Un modèle J2K est un agencement de modules associé à un état initial et des valeurs de paramètres. Le fonctionnement des modules est codé en java mais la plupart des utilisateurs ne programment pas eux-mêmes les modules, ils utilisent des modules existant qu'ils agencent et paramétrisent en utilisant un logiciel dédié appelé juice. 
+Pour organiser la communication avec des modèles J2K depuis l'extérieur, nous avons programmé et compilés des modules dédiés en Java. Reste à l'utilisateur d'intégrer correctement ces modules dans ses modèles. Ce chapitre décrit le fonctionnement interne de nos modules et la marche qu'un utilisateur doit suivre pour les utiliser.
 
-Pour organiser la communication avec des modèles J2K depuis l'extérieur, nous avons programmé des modules dédiés en Java. Reste à l'utilisateur d'intégrer correctement ces modules dans ses modèles.
+Les développeurs qui souhaiteraient modifier nos modules ou créer de nouveaux modules de communication spécifiques sont invités à consulter le chapitre sur le [Développement des modules](netbeans).
 
-# Édition d'un modèle
+# Principe général
 
-Il faut lancer juice. Pas besoin d'utiliser Netbeans pour ça.
+Un modèle J2K est spécifié dans un fichier JAMS (extension .jams") qui s'édite avec le logciel "Juice". 
 
 Pour lancer Juice, il faut aller dans la racine de JAMS et lancer juice avec java :
 
@@ -18,7 +20,14 @@ ls # verifier que juice-starter.jar est bien là
 java -jar juice-starter.jar
 ```
 
-# Exemple de plan des modules
+L'ordonnancement des modèles J2K est classiquement organisés en au moins trois boucles principales: Une boucle dîte "temporelle" qui décrit la succession des opérations à effectuer à chaque pas de temps, et qui contient elle même une boucle dîte "spatiale" (qui décrit la succession des opérations à effectuer sur les entitiés spatiales (HRU) classées de l'amont vers l'aval) et une boucles sur les brins de rivières (ReachLoop) classées également de l'amont vers l'aval. 
+
+L'enjeu du couplage est de pouvoir intervenir sur le système à tout moment de la simulation mais sans perturber la logique des calculs hydrologiques prévus pour être ordonancée de l'amont vers l'aval. Pour cette raison les modules de communications sont organisés de la manière suivante: 
+    * le module CouplingCommunication, situé en début de boucle temporel reçoit toutes perturbations que subit le modèle à un pas de temps donné. 
+    * ces perturbations sont enregistrées avant l'exécution du pas de temps dans J2K mais ne sont pas répercutées immédiatements sur les variables d'état du système
+    * lors du parcours des boucles spatiales (HRULoop) et de brins de rivières (ReachLoop) des modules de communication secondaires (par exemple "Drip irrigation") vont être exécutés à chaque fois qu'une modification a été prévu pour ce pas de temps au fur et à mesure du parcours de la boucle et donc en respectant l'ordonancement amont / aval et la logique des calculs hydrologiques. La section ci-dessous présente un exemple type d'ordonancement de modèle communicant.
+
+## Exemple d'ordonnancement des modules d'un modèle J2K communicant
 
 * timeloop
     * **CouplingCommunication**