Author: jcouteau Date: 2013-01-22 17:56:23 +0100 (Tue, 22 Jan 2013) New Revision: 123 Url: http://forge.codelutin.com/projects/isis-fish-docs/repository/revisions/123 Log: Continue translating FAQ into english. Add tuto that are linked from FAQ (not translated) Added: trunk/src/site/en/rst/v4/user/tutorials/ trunk/src/site/en/rst/v4/user/tutorials/simulationPlan.rst trunk/src/site/en/rst/v4/user/tutorials/useAPI.rst Modified: trunk/src/site/en/rst/v4/user/FAQ.rst Modified: trunk/src/site/en/rst/v4/user/FAQ.rst =================================================================== --- trunk/src/site/en/rst/v4/user/FAQ.rst 2013-01-21 15:43:25 UTC (rev 122) +++ trunk/src/site/en/rst/v4/user/FAQ.rst 2013-01-22 16:56:23 UTC (rev 123) @@ -117,10 +117,165 @@ In the rules or plan script (script editor), * at the imports levels, add : import fr.ifremer.isisfish.util.Doc * on top of the parameter to document (for example public Zone param_zone = - null;), add @Doc("the parameter Zone correspond to ???") + null;), add @Doc("the parameter Zone correspond to ???") Insert comments in a script ~~~~~~~~~~~~~~~~~~~~~~~~~~~ System.out.println (); +How to use APIs ? +~~~~~~~~~~~~~~~~~ + +cf tutorial_ . + +.. _tutorial: tutorials/useAPI.html + + +How to create simulation plan scripts +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +`cf tutorial`_ + +.. _cf tutorial: tutorials/simulationPlan.html + +What is the structure of an analysis plan or management rules script ? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +cf simulation procedure at the bottom of `this page`_ and `this one`_ + +.. _this page: ../devel/architecture.html + +.. _this one: usermanual/analysisPlan.html + +A parameter of my rule behaves strangely, what is happening ? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The rules parameters variables (thos which start by \param_) are initialized at +the beginning of each simulation and not each time step. So you have not to +modify them but use intermediate variables. + +User interfaces +--------------- + +Verifying fishery parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* For all the fishery. In the region interface : bottom button to check. + + - blue : ok + - orange : parameters with a problem +* For an equation. In the equation editor : check button - syntax verification +* For a script (rule, AnalysisPlan,...). In the script editor : check button - + syntax verification. You can check the differences between your version and + the server version using the server menu from the script editor interface. + +What "tag" is for in the launcing interface, in the advanced parameters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Parameterize exports, the simulator or equations. + +Example : In the simulator, simulate economical variables:: + + if (!"false".equalsIgnoreCase(param.getTagValue().get("ecoResult"))) { + control.setText("Add economics results"); + saveGravityModel(date, resManager, gravityModel); + } + +Here the tag is called ecoResult + +Effort description +~~~~~~~~~~~~~~~~~~ + +The variables 'Fishing operation number' and 'gear number per operation' are +taken into account in the equations for the "effort standardisation by trip" +this way:: + + StdEffortPerHour = Fstd * FishingOperationNumber * GearNumberPerOperation. + +So they have to be fille din when Fstd is computed at FishingOperation*gear +scale. + +If Fstd is computed at trip scale, you HAVE TO put 1 in both variable (or +catches will be nil). The "fishingOperationLength" variable is not used in +equations. + +Units... +~~~~~~~~ + +Trip types : + + * Trip length in hours + * Minimum time between two trips : unused + +Vessel type + + * Trip max length : unused + * speed in km/h + * activity interval : unused + +Enter a management rule application month in the simulation launching interface +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +That is the number of the month that is queried, so a number between 0 and 11 +(0 : january, 11 : december). Otherwise you will have a bug ! + +Did the simulation run ? +~~~~~~~~~~~~~~~~~~~~~~~~ + +* Ensure the simulation is in "simulation finished" state in the simulation + queue + +* Select the simulation in the table (or in simulation result interface) and + click on "see the logs" + +* Select fatal, error and warning : If something appears, there is a bug. Below + ERROR is the exception. You have to look into the stacktrace and watch for a + line with ifremer.isisfish and see what it says. + +See Numbers and biomasses in the results window +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Small tweak : In the results window, the numbers, biomass of a population for a +month is the number/biomass at the end of the previous time step. + +You do not use the correct repository for your ISIS-Fish version +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following message appear :: + You don't use correct repository script for your application version 3.2.0.8. + Do you want to switch your repository ? + +This message appear when you use a new major version of ISIS-Fish. It simply +asks you if you want to use the new script version that works with your new +version. + +Modeling tips +------------- + +Split males and females with different growth +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We create consecutive length classes for males and others for the females that +will follow. For examples, for males we got those classes:: + + 60-70 70-77 77-110 110-166 + +and for females :: + + 60-70 70-78 78-86 + +you click on 'recruit classes'. For the first length, enter '60'. +Then for the max lengths, enter : +'70;77;110;166;70;78;86' and validate. That will create a 4th class with +minimal length of 166 and maximal length of 70 ! + +In the population group interface, modify the minimal length of the 4th class +(the first female class) : from 166 to 60. You save and that's all !!! + +To do not take into account the trip time in the effort +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The tip consists in entering a huge vessel speed (fo example 10^9). The trip +length becomes really small ~0. + Copied: trunk/src/site/en/rst/v4/user/tutorials/simulationPlan.rst (from rev 121, trunk/src/site/rst/v4/user/tutorials/simulationPlan.rst) =================================================================== --- trunk/src/site/en/rst/v4/user/tutorials/simulationPlan.rst (rev 0) +++ trunk/src/site/en/rst/v4/user/tutorials/simulationPlan.rst 2013-01-22 16:56:23 UTC (rev 123) @@ -0,0 +1,208 @@ +.. - +.. * #%L +.. * IsisFish +.. * +.. * $Id$ +.. * $HeadURL$ +.. * %% +.. * Copyright (C) 1999 - 2011 Ifremer, Code Lutin, Chatellier Eric +.. * %% +.. * 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% +.. - + +Tutorial to use simulation plans +================================ + +This tutorial have not been translated yet. Here is the French version + +Un plan d'analyse est un ensemble d'expériences (simulations) pour lesquelles on +va modifier la valeur de certains paramètres selon un protocole défini pour +répondre à une question. On distingue des plans de simulations pour lesquels + +* *les expériences sont indépendantes* . C'est à dire que l'ordre des + simulations n'a pas d'importance et que l'on pourrait par exemple les lancer + sur des ordinateurs différents. Les valeurs que les paramètres devront prendre + à chaque nouvelle simulation sont déterminées au préalable. + +* *les expériences sont séquentielles* . Les valeurs des paramètres de la + simulation n+1 dépendent des résultats de la simulation n. + +Expériences Indépendantes : exemple d'une analyse de sensibilité +---------------------------------------------------------------- + +Dans le cas d'expériences indépendantes, la première étape est de définir les +paramètres à modifier et les différentes valeurs qu'ils devront prendre +(appelées « modalités »). On les organise ensuite selon un plan d'expérience +adéquat (plan complet, factoriel, optimisé...) qu'on écrit sous forme de matrice. +Des méthodes sont déjà disponibles pour réaliser ce type de plans sous +ISIS-Fish. Ils sont décrits ici mais libre à l'utilisateur d'écrire ses propres +scripts si la méthode actuellement utilisée ne répond pas à ses besoins. Voici +la description et le fonctionnement des scripts existants : ils nécessitent +l'écriture de 3 types de fichiers : un script de plan d'analyse, une matrice +d'expérience et des fichiers paramètre : + +La matrice d'expérience +~~~~~~~~~~~~~~~~~~~~~~~ + +*La matrice d'expérience* est une matrice [expériences x paramètres] : chaque +colonne correspond à l'un des paramètres à modifier et chaque ligne contient +les modalités des paramètres pour une expérience donnée. Les modalités sont +codées par des entiers (-1 ;0 ;1 etc). Cette matrice est copiée dans un +fichier .txt sans en-tête de colonnes ni de lignes. + +Les fichiers paramètres +~~~~~~~~~~~~~~~~~~~~~~~ + +*Les fichiers paramètres* : un fichier .txt par paramètre donnant la +correspondance entre la valeur de la modalité (-1 ;0 ;1) dans la matrice et la +valeur du paramètre. Ce paramètre peut être un réel, une liste de réels, une +équation… Si l'on nomme les modalités –1 et 1, le fichier est de la forme + +Pour un paramètre qui est une liste +___________________________________ + +:: + + -1=0.5;0.8;0.9;0.11 + 1=0.5;0.11;0.15;0.41 + +Pour un paramètre qui est une équation +______________________________________ + +:: + + -1=if(condition = true) return 5 ; else return 3 ; + 1=if(condition = true) return 7 ; else return 3 ; + +Pour un paramètre qui est un réel +_________________________________ + +:: + + -1=0.8 + 1=1.2 + +Autres +______ + +On peut aussi modifier les paramètres des règles de gestion...(voir +exemple). Il faut alors indiquer dans le .txt tous les paramètres public de +la règle. Attention pour certaines règles de gestion il faut définir la +population, l'engin, la zone... ciblée par la règle dans les paramètres. +Pour ce faire il n'est pas possible d'écrire le nom de la population, de la +zone... il faut déterminer le code correspondant qui est du genre + +:: + + fr.ifremer.isisfish.entities.Zone#1169028645767#0.37798185123822536 + +Pour cela on peut faire tourner une simulation avec la règle en question +correctement paramétrée et aller voir dans les logs (fichier debug.txt dans +le même dossier que le .bat de lancement), ces codes sont inscrits à coté du +nom du paramètre au moment de l'initialisation des règle de gestion. + +*Attention !!!!* dans ces fichiers la syntaxe est importante: + +* Pas d'espace +* Pas de « ; » à la fin des lignes +* Pas de « + » devant un chiffre quand il désigne une modalité (+1=NON ; 1=OUI) + +Les fichier matrix.txt et les fichiers paramètres.txt doivent être placés *dans +un même dossier* de préférence localisé dans le dossier contenant le .bat de +lancement d'ISIS-Fish (qui est la racine pour le logiciel). + +Exemple +~~~~~~~ + +On propose ici la matrice et les fichiers paramètres d'une analyse +de sensibilité sur les paramètres de croissance, capturabilité, selectivité et +la période de fermeture d'un cantonnement. + +`Fichiers parametres et matrice`_ + +.. _Fichiers parametres et matrice: ../../downloads/Exemple_directory.zip + +*Le script de plan de simulation* (écrit à partir de l'éditeur de scripts) +permet de récupérer et modifier les valeurs des paramètres en fonction de la +matrice d'expérience pour chaque simulation. (Voir le manuel pour l'explication +de la structure des scripts de plans de simulation.) + +On joint ici le script commenté correspondant à l'analyse de sensibilité +précédante. Le script contient les méthodes nécessaires à lire les fichiers +matrice.txt et les fichiers contenant les modalités des paramètres. Il contient +aussi le code servant à modifier les valeurs de ces paramètres dans la base de +donnée (pour connaitre les méthodes permettant d'accéder aux différents +paramètres de la base de donnée, se référer aux APIs). + +`Script d'analyse de sensibilite`_ + +.. _Script d'analyse de sensibilite: ../../downloads/Exemple_PlanSimulation.java + +Plans sequentiels : exemple de calibration par la méthode du simplexe +--------------------------------------------------------------------- + +Dans ce cas, les modalités prises par les paramètres à la simulation suivante +dépendent des résultats des simulations précédentes. Il faut donc écrire +l'algorithme de calcul de ces nouvelles valeurs en fonction des résultats de +simulation dans le script du plan d'analyse. Il faut également écrire le code +permettant de modifier la valeur des paramètres pour la remplacer par la +nouvelle valeur calculée. + +Exemple +~~~~~~~ + +L'exemple reprend un script qui permet de calibrer deux paramètres (ici la +capturabilité) par la méthode du simplexe à pas variable à partir des +débarquements trimestriels. + +`Script de calibration`_ + +.. _Script de calibration: ../../downloads/calibration.java + +Lancement d'un Plan d'analyse +----------------------------- + +Quand les scripts sont écrits, c'est tout simple ! + +Dans l'interface de lancement de simulation on prépare sa simulation comme +d'habitude à l'exception des règles de gestion : il ne faut pas charger une +règle si elle doit être modifiée par le plan car elle sera ajoutée par le plan +d'analyse à la suite des règles entrées dans l'interface. On coche la case +« Utiliser le plan d'analyse ». On sélectionne le plan Exemple_PlanAnalyse ou +CalibrationExpeceq1q2 dans la liste déroulante. On remplit les paramètres du +plan et on lance la simulation. + +PS : Attention à bien vérifier les différentes étapes listées dans le Pense-Bête +sinon gare aux 500 simulations sans effectifs initiaux... ;-) + +Biblio intéressante +------------------- + +* Drouineau, H., Mahévas, S., Pelletier, D. and Beliaeff, B. 2006. Assessing the + impact of different management options using ISIS-Fish: the French + Hake-Nephrops mixed fishery of the Bay of Biscay. Aquatic living resource, + 19 : 15-29. +* Saltelli, A., Tarantola, S., Campolongo, F. and Ratto, M. 2004. Sensitivity + Analysis in Practise. A guide to Assessing Scientific Models. J.W.&. Sons. pp. +* Kleijnen, J.P.C. 1998. Experimental Design for Sensitivity Analysis, + Optimization, and Validation of Simulations Models. In Handbook of simulation. + Principles, Methodology, Advances, Applications and Practise, pp. 173-224. Ed. + by Banks, J. Wiley, New York. Engeneering and Management Press. 864 pp. +* Walters, F.H., Parker, L.R., Morgan, S.L. and Deming, S.N. 1991. Sequential + Simplex optimization: a technique for improving quality and productivity in + research, development, and manufacturing (Chemometrics series). B.R. CRC Press + LLC. 402 pp. +* Nocedal, J., and Wright, S.J. 2006. Numerical Optimization. Mikosch, T. V., Resnick, S. I. , andRobinson, S. M. (Eds.). 2nd Ed., Springer Series in Operations Research, New York. \ No newline at end of file Copied: trunk/src/site/en/rst/v4/user/tutorials/useAPI.rst (from rev 121, trunk/src/site/rst/v4/user/tutorials/useAPI.rst) =================================================================== --- trunk/src/site/en/rst/v4/user/tutorials/useAPI.rst (rev 0) +++ trunk/src/site/en/rst/v4/user/tutorials/useAPI.rst 2013-01-22 16:56:23 UTC (rev 123) @@ -0,0 +1,137 @@ +.. - +.. * #%L +.. * IsisFish +.. * +.. * $Id$ +.. * $HeadURL$ +.. * %% +.. * Copyright (C) 1999 - 2010 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% +.. - + +Tutorial on APIs use +==================== + +This tutorial have not been translated to english yet. + +Avant tout il faut savoir, que toutes les valeurs saisies dans l'interface de +saisie par l'utilisateur sont stoquées dans les objets d'ISIS correspondants. +Pour modifier ces valeurs avant ou en cours de simulation, il faut connaitre +leur nature et leur structure, savoir comment y accéder et les modifier. +Pour savoir comment y accéder il faut connaitre les dépendances entre objets +(objets qui sont des attributs d'autres objets). Pour cela on consulte +l'architecture de la base de donnée ( `Modele ISIS-Fish`_ ) qui se reflète dans +l'architecture de l'interface de saisie. + +Pour savoir comment passer d'un objet a un autre il faut connaitre les méthodes +appliquables aux objets : tout est dans l'API. + +Remarque : Il vaut mieux commencer par se familiariser avec les differents types +d'objets JAVA (double, boolean, string, integer, equation, matrix,...), les +attributs et les methodes (cf tutoriaux JAVA). + +Voici un exemple "pas à pas" pour le cas ou l'on voudrait modifier l'equation de +mortalité naturelle dans un plan d'analyse par exemple. On veut remplacer +provisoirement la valeur de la base par une autre. On crée un objet String +rempli avec l'autre valeur par exemple:: + + String mortalitenaturelle = "if (groupe.getId() == 0) return 1.5; else return 0.2;" + +Se poser la question : "Dans la base de donnée où se trouve la mortalité naturelle ?" +------------------------------------------------------------------------------------- + +Réponse : dans l'interface de saisie, elle est dans la branche "population" et +l'onglet "equations". +(au passage le titre de l'onglet nous renseigne sur le type d'objet auquel on a +affaire : ya de grandes chances pour que parmi la batterie d'objets possibles +(int, double, matrice...) la mortalité naturelle soit une equation ;-) ) + +En francais on dirait "dans population, va chercher l'objet equation de +mortalité naturelle, et attribut lui la valeur du string mortalitenaturelle", ya +pu qu'a le dire en java. + +Ouvrir la page des APIs +----------------------- + +Dans la colonne de gauche de l'API (sous "all classes") on cherche l'entite +"population" et on clique dessus. + +Les méthodes disponibles +------------------------ + +Toutes méthodes que l'on peut appliquer à un objet population (colonne de +droite) s'affichent , et le type d'objet qu'elles renvoient (colonne de gauche). + +c'est a dire que les lignes de commandes qu'on ecrira seront de la forme:: + + objet_renvoyé_indiqué_à_gauche nomObjet = population.methode_ecrite_à_droite(argument de la methode); + +Il y a surtout deux grands types de méthodes : + +* les méthodes "get" : qui vont chercher un objet +* les méthodes "set" : qui assignent une valeur a un objet. + +Dans notre exemple on veut changer l'equation de mortalité naturelle, c est donc +un set ! + +On cherche une méthode qui parle de mortalité naturelle... +---------------------------------------------------------- + +On trouve getNaturalDeathRate() qui renvoit un objet equation (c'est l'objet +equation qui contient la valeur de l'equation de mortalite naturelle remplie par +l'utilisateur) et setNaturalDeathRate(Equation naturalDeathRate) pour laquelle +on doit passer un objet equation (une equation de naturalDeathRate) en argument. + +(en cliquant sur le nom de la méthode on a une description sommaire de ce +qu'elle fait) + +setNaturalDeathRate() parait être ce qu'on veut faire... +mais la méthode setNaturalDeathRate prend en argument une equation, on ne peut +donc pas faire:: + + pop.setNaturalDeathRate(mortalitenaturelle); + +puisque mortalitenaturelle n'est pas une equation mais un string. + + +Créer une équation +------------------ + +Du coup il faut trouver autre chose qui fasse le lien entre un string et une +equation. En cliquant sur "equation" dans la page d'API on tombe sur la page des +méthodes qui s'appliquent aux objets qui sont des equations. On trouve une +méthode .setContent(String ) qui prend en argument un string. Ca veut dire que +si on a une equation, on peut lui changer sa valeur en utilisant cette methode +avec un string en argument. +L'equation dont on veut changer la valeur on sait la récupérer:: + + Equation eqMortalite = pop.getNaturalDeathRate(); + +L'objet eqMortalite est un objet equation:: + + eqMortalite.setContent(mortalitenaturelle); + +et là on a le droit vu que mortalitenaturelle est un string et que la méthode +prend un string en argument. + +et voilà c'est fait ! + +remarque : on pourrait le faire en 1 ligne:: + + pop.getNaturalDeathRate().setContent(mortalitenaturelle); + +.. _Modele ISIS-Fish: ../isisFishModel.html