Author: echatellier Date: 2018-01-29 14:35:47 +0100 (Mon, 29 Jan 2018) New Revision: 336 Url: http://forge.codelutin.com/projects/isis-fish-docs/repository/revisions/336 Log: Ajout de la documentation des scripts d'optimisation Added: trunk/src/site/rst/v4/user/tutorials/optimization.rst Modified: trunk/src/site/site_fr.xml Copied: trunk/src/site/rst/v4/user/tutorials/optimization.rst (from rev 335, trunk/src/site/rst/v4/user/usermanual/analysisPlan.rst) =================================================================== --- trunk/src/site/rst/v4/user/tutorials/optimization.rst (rev 0) +++ trunk/src/site/rst/v4/user/tutorials/optimization.rst 2018-01-29 13:35:47 UTC (rev 336) @@ -0,0 +1,172 @@ +.. - +.. * #%L +.. * IsisFish +.. * +.. * $Id$ +.. * $HeadURL$ +.. * %% +.. * Copyright (C) 2018 Ifremer, Code Lutin +.. * %% +.. * This program is free software: you can redistribute it and/or modify +.. * it under the terms of the GNU General Public License as +.. * published by the Free Software Foundation, either version 3 of the +.. * License, or (at your option) any later version. +.. * +.. * This program is distributed in the hope that it will be useful, +.. * but WITHOUT ANY WARRANTY; without even the implied warranty of +.. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.. * GNU General Public License for more details. +.. * +.. * You should have received a copy of the GNU General Public +.. * License along with this program. If not, see +.. * <http://www.gnu.org/licenses/gpl-3.0.html>. +.. * #L% +.. - + +============ +Optimisation +============ + +Les scripts d'optimsation servent à lancer plusieurs série de simulation et évaluant à chaque itération si le script doit continuer. +Cette condition est vérifiée par une fonction d'objectif qui analyse les exports habituels des simulations par rapport aux observations renseignées +dans la base de données. + + +Script d'optimisation +===================== + +Un script d'optimisation est relativement similaire à un plan d'analyse, mais il comprend quelques méthodes en plus. Son but est de générer un +ensemble de simulation à être executée et déterminer une condition à l'arrêt du script. + +Voici l'ensemble des méthodes présentes dans le script: + * ``getNecessaryResult()`` : retourne l'ensemble des résultats devant être calculés par l'ensemble des simulations et nécessaire à l'execution du + script d'optimsation + * ``getDescription()`` : retourne une description du script à destination de l’utilisateur (affichée dans l'interface de lancement) + * ``init(OptimizationContext)`` : sert à initialiser le script d’optimisation (appelée une fois, avant le lancement du script) + * ``firstSimulation(OptimizationContext)`` : sert à générer la première génération de simulation (appelée une fois au lancement du script) + * ``nextSimulation(OptimizationContext)`` : est appelée plusieurs fois, a chaque génération de simulation + * ``endSimulation(OptimizationContext)`` : est appelée plusieurs fois, à chaque fin d’exécution d'une génération de simulation + * ``finish(OptimizationContext context)`` : appelée une fois, à la fin du script, lorsque que l'ensemble des générations de simulation ont terminé + + +Génération de simulation +------------------------ + +Dans les scripts d'optimisation, on parle de "génération de simulation" pour désigner un ensemble de simulation que le script d'optimisation +génere à chaque itération. + +Chaque génération comprend plusieurs simulation qui sont executées en parallèle. Mais les "génération de simulation" sont exeution séquantiellement. + + +OptimisationContext +------------------- + +L'objet ``OptimizationContext`` est un object qui est donné à chaque méthode du script d'otpimisation. Il permet de: + * connaitre l'état d'avancement du script + * de produire de nouvelles simulation dans la génération courante + +Liste des méthodes disponibles: + * ``context.getCurrentGeneration()`` : permet de connaitre le numéro de la génération en cours. Par exemple, au 3ème appel de ``nextSimulation()`` le + compteur sera égal à ``3`` (en prenant en compte que le compteur est égale à ``0`` dans la méthode ``firstSimulation()`` + * ``context.newSimulation()`` : crée une nouvelle simulation dans la simulation courante et la retourne sous forme de SimulationStorage (pour être + modifiée par l'utilsateur avant son lancement) + * ``context.getLastSimulations()`` : retourne l'ensemble des simulations exécutée dans la dernière génération. Les ``SimulationStorage`` retournée peuvent + être lu pour en extraire des résultats + + +Condition d'arrêt +----------------- + +Un script d'optimisation s'arrête lorsqu'il n'y a plus de simulation à executer. + +Donc, pour arrêter un script, il faut, dans la méthode ``nextSimulation(OptimizationContext)`` ne faire aucun appel à ``context.newSimulation()``. + + +Fonction d'objectif +=================== + +Une fonction d'objectif sert à retourner un indicateur sur l'execution d'une simulation. Cette fonction d'objectif est à paramêtre à définir lors +du lancement d'un script d'optimsation et peut donc être différente à chaque fois. + + +Structure +--------- + +Un script d'optimisation à des méthodes classiques aux autres scripts: + - init() pour initialiser la fonction d'objectif + - getNecessaryResult() pour définir les résultats à calculer pour le fonction d'objectif + - getDescription()pour fournir une description à l'utilsateur + +Il contient surtout une seule méthode spécifique : ``double eval(OptimizationContext context, List<MatrixND> exports, List<MatrixND> observations)``. + +Cette méthode prend en paramètres: + * le contexte de simulation + * les résultats des exports définis au lancement du script d'optimisation + * les observations définis lors du lancement du script d'optimisation + +Le but de la fonction d'objectif est de comparer les exports aux observations et à définir un indicateur ``double`` qui pourra être utile au script +d'optimisation. + +Le résultat de la fonction d'objectif est stocké dans le SimulationStorage et pour être récupéré, à la fin de chaque génération, avec la méthode +``SimulationStorage#getObjective()`` + + +Exemple +======= + +Fonction d'objectif ``Objectif3Iteration.java``. Cette fonction d'objectif est très simple. Elle retourne -1 losque que 3 générations de simulation +ont été executées. + +.. class:: java + +:: + + public class Objective3Iteration implements Objective { + + public double eval(OptimizationContext context, List<MatrixND> exports, List<MatrixND> observations) { + double result = 0; + if (context.getCurrentGeneration() >= 3) { + result = -1; + } + return result; + } + } + +Script d'optimisation ``ExampleObjectif.java``. Cet example génère des séries de 2 simulations, tant que la fonction d'objectif n'a pas retourné ``-1``. + +.. class:: java + +:: + + public class ExampleOptimization implements Optimization { + + protected boolean stopped = false; + + public void firstSimulation(OptimizationContext context) throws Exception { + for (int i = 0; i <= 2; i++) { + SimulationStorage storage = context.newSimulation(); + // modify simulation storage + } + } + + public void nextSimulation(OptimizationContext context) throws Exception { + if (!stopped) { + for (int i = 0; i <= 2; i++) { + SimulationStorage storage = context.newSimulation(); + // modify simulation storage + } + } + } + + public void endSimulation(OptimizationContext context) throws Exception { + List<SimulationStorage> lastGeneration = context.getLastSimulations(); + for (SimulationStorage simulation : lastGeneration) { + double objective = simulation.getObjective(); + if (objective <= -1) { + stopped = true; + } + } + } + } + +Dans cette exemple, cette fonction d'optimasation aura lancé 8 simulations (4 séries de 2 simulations). Modified: trunk/src/site/site_fr.xml =================================================================== --- trunk/src/site/site_fr.xml 2018-01-26 10:54:38 UTC (rev 335) +++ trunk/src/site/site_fr.xml 2018-01-29 13:35:47 UTC (rev 336) @@ -110,6 +110,7 @@ <item name="Première utilisation" href="v4/user/tutorials/firstLaunch.html"/> <item name="Paramétrisation" href="v4/user/tutorials/parameterising.html"/> <item name="Plans d'analyse" href="v4/user/tutorials/simulationPlan.html"/> + <item name="Script d'optimisation" href="v4/user/tutorials/optimization.html"/> <item name="Utilisation des APIs" href="v4/user/tutorials/useAPI.html"/> <item name="Commandes CAPARMOR" href="v4/user/tutorials/utilCaparmor.html"/> </menu>