Author: jcouteau Date: 2010-06-01 12:15:30 +0000 (Tue, 01 Jun 2010) New Revision: 3048 Log: Add analysis plan doc Added: isis-fish/trunk/src/site/rst/documentation/userManual/analysisPlan.rst Modified: isis-fish/trunk/src/site/rst/documentation/userManual.rst Added: isis-fish/trunk/src/site/rst/documentation/userManual/analysisPlan.rst =================================================================== --- isis-fish/trunk/src/site/rst/documentation/userManual/analysisPlan.rst (rev 0) +++ isis-fish/trunk/src/site/rst/documentation/userManual/analysisPlan.rst 2010-06-01 12:15:30 UTC (rev 3048) @@ -0,0 +1,175 @@ +============== +Plan d'analyse +============== + +Les plans d'analyses servent à enchaîner plusieurs simulations. Chaque +simulation peut-être paramétrée en fonction des résultats des +anciennes simulations ou de valeurs aléatoires. + +Il est possible de composé un plan d'analyse à partir de plusieurs +plans. Par exemple créer sont propre plan et utiliser aussi le plan +*Max* qui permet de fixer le nombre maximum de simulation du plan. + +Principe général +================ + +Le plan d'analyse est une classe Java contenant quelques méthodes: + +- getDescription qui permet de décrire le plan +- init qui est appelé une seul fois pour toutes les simulations +- beforeSimulation qui est appelé avant chaque simulation +- afterSimulation qui est appelé après chaque simulation + +La méthode init permet de modifier des paramètres pour toutes les +simulations ou de fixer des valeurs dans le contexte de +plan. Potentiellement il est aussi possible de faire apparaître de +boites de dialogues pour demander des informations supplémentaire à +l'utilisateur. + +La méthode *beforeSimulation* permet de modifier les paramètres de la simulation +ou les données de la prochaine simulation. Elle prend en paramètre +*AnalysePlanContext* et *SimulationStorage*. Pour avoir plus +d'information sur ces deux objets reportez-vous à la Javadoc. La +méthode next retourne un booléen. Si la méthode retourne faux cela +indique que le plan doit se finir et que la prochaine simulation +n'aura pas lieu, et les autres méthodes before des plans ne seront +pas appelées. + +La méthode *afterSimulation* est appelé après la simulation. Si l'un +des plans retourne false lors de l'appel à cette méthode alors la +prochaine simulation ne sera pas faite, mais les autres méthodes +after des plans seront tout de même appelé. + +Il est possible de définir des attributs dans la classe qui seront +automatiquement paramètrable par l'interface de sélection des plans +d'analyses. Ces attributs doivent commencer par le préfix **param_** +et être soit de type primitif (String, int, double, ...), soit de type +Date ou Mois, soit de type entité (Metier, Stratégies, ...). + +Choix d'implantation +==================== + +Il a été choisi d'offrir deux méthodes (before, after) dans les plans +d'analyses et non pas de permettre au plan d'analyse d'appeler eux même des +simulation, car si un plan d'analyse est lancé en queue de simulation et que +l'on exécute ensuite une simulation prioritaire, on souhaite que le plan +d'analyse laisse cette simulation prioritaire se faire au milieu du plan. Or +si le plan lançait lui même les simulations on ne pourrait pas reprendre la +main pour cela. + +Exemple +======= + +Plan d'analyse qui permet de fixer un nombre maximal de simulation:: + + public class Max implements AnalysePlan { + public int param_max = 10; + + public String getDescription() throws Exception { + return _("Permit to specify maximum simulation numbers"); + } + public void init(AnalysePlanContext context) throws Exception { + } + public boolean next(AnalysePlanContext context, SimulationStorage nextSimulation) throws Exception { + boolean result = nextSimulation.getParameter().getAnalysePlanNumber() < param_max; + return result; + } + } + +Il est possible de coupler ce plan avec un plan qui par exemple +modifirait aléatoirement et indéfiniment une variable de la base. + +Modification des paramètres pour la simulation suivante +======================================================= + +Pour modifier les paramètres il faut les récupérer avec la méthode +*nextSimulation.getParameter()* ce qui retourne un objet de type +*SimulationParameter*. Pour plus de documentation sur cet objet +reportez-vous à la javadoc. + +Récupération d'une simulation précédente +======================================== + +exemple:: + // reccupération de la simulation n + SimulationStorage firstSim = context.getSimulation(n); + +ATTENTION : +Le context fait référence au plan d'analyse en cours : par exemple appeler la +méthode getNumber() au cours du plan renverra le numero de la derniere +simulation crée qui peut etre différente de la simulation en cours ! pour +appeler le numero de la simulation en cours il faut utiliser les objets +nextSimulation et lastSimulation selon que l'on est en beforeSimulation ou en +afterSimulation. + + + +Récupération des résultats d'une simulation +=========================================== + +exemple:: + + ResultStorage results = sim.getResultStorage(); + MatrixND n = results.getMatrix(ResultName.MATRIX_ABUNDANCE); + +Modification de la base de données pour la prochaine simulation +=============================================================== + +exemple:: + + TopiaContext db = nextSimulation.getStorage(); + MetierDAO dao = IsisFishDAOHelper.getMetierDAO(db); + Metier metier = dao.findByName("Mon metier"); + metier.setGearParameterValue("30"); + +Exemple de méthode next qui modifie le paramètre de l'engin +=========================================================== + +:: + + public boolean next(AnalysePlanContext context, SimulationStorage nextSimulation) throws Exception { + String [] values = new String[]{"10", "20", "30"}; + int number = nextSimulation.getParameter().getAnalysePlanNumber(); + + if (number < values.length) { + TopiaContext db = nextSimulation.getStorage().beginTransaction(); + MetierDAO dao = IsisFishDAOHelper.getMetierDAO(db); + Metier metier = dao.findByName("Mon metier"); + metier.setGearParameterValue(values[number]); + db.commitTransaction(); + db.closeContext(); + return true; + } else { + return false; + } + } + + +Dans cette exemple nous ferons trois simulation en modifiant la valeur +du paramètre controlable de l'engin pour le métier *Mon metier*. Une +fois ces trois simulations faites le plan s'arrêtera. + +Des tutoriaux et exemples de plans d'analyse pour l'analyse de sensibilité et la calibration +============================================================================================ +sont disponibles : + +http://isis-fish.labs.libre-entreprise.org/wiki-moin/instance/cgi-bin/moin.c... + +Pense bête : avant de lancer un plan d'analyse +============================================== + +vérifier: + +* Les effectifs initiaux + +* la présence des règles de gestion (non ajoutées par le plan) + +* Le nom de la simu + +remarque : Il peut etre pratique si on suit une matrice d'expérience de faire figurer dans le nom le numero de la premiere ligne lancée : exemple "planMPA_54" si on lance le plan a partir de la ligne 54 de la matrice, isis appelera la premiere simu "planMPA_54 2008-11-13-16-50_0" et en sommant les 2 chiffres on retrouve ... le numero de la ligne, pratique pour l'exploitation des résultats. + +* vérifier les paramètres du plan : en particulier qu on a bien entré la ligne de la matrice d'expérience à laquelle commencer les simulations ou encore le chemin d'acces aux fichiers à charger + +* que les resultats a exporter et sauvegarder sont selectionnés et que le repertoire d'export est correct + +* enfin verifier la duree de simulation et c'est parti ! Modified: isis-fish/trunk/src/site/rst/documentation/userManual.rst =================================================================== --- isis-fish/trunk/src/site/rst/documentation/userManual.rst 2010-06-01 09:57:31 UTC (rev 3047) +++ isis-fish/trunk/src/site/rst/documentation/userManual.rst 2010-06-01 12:15:30 UTC (rev 3048) @@ -10,8 +10,7 @@ + `Rendu des resultats`_ + `Editeur de script`_ + `Queue de simulation`_ -- `Plan d experience/Plan d analyse`_ -- `Analyses de sensibilite`_ +- `Plan d experience-Plan d analyse`_ .. _Introduction:: userManual/introduction.html .. _Interface utilisateur:: userManual/GUI.html @@ -20,4 +19,5 @@ .. _Lanceur d analyse de sensibilite:: userManual/sensitivity.html .. _Rendu des resultats:: userManual/results.html .. _Editeur de script:: userManual/scripts.html -.. _Queue de simulation:: userManual/queue.html \ No newline at end of file +.. _Queue de simulation:: userManual/queue.html +.. _Plan d experience-Plan d analyse:: userManual/analysisPlan.html \ No newline at end of file