mini_ker.texi(,12) @setfilename mini_ker.info
version.texi(,1) @set UPDATED 28 March 2002
version.texi(,2) @set UPDATED-MONTH March 2002
version.texi(,3) @set EDITION 4.2
version.texi(,4) @set VERSION 4.2
mini_ker.texi(,14) 
mini_ker.texi(,15) @c @set myversion @value{VERSION}
mini_ker.texi(,16) @set myversion 102
mini_ker.texi(,17) 
mini_ker.texi(,18) @set myurl @url{http://www.environnement.ens.fr/@/perso/@/dumas/@/mini_ker/@/software.html}
mini_ker.texi(,19) 
mini_ker.texi(,23) 
mini_ker.texi(Minik,24) @settitle Miniker 102 manual
mini_ker.texi(,25) 
mini_ker.texi(,26) @syncodeindex fn vr
mini_ker.texi(,27) 
mini_ker.texi(,28) @dircategory Miscellaneous
mini_ker.texi(,32) 
mini_ker.texi(,33) 
mini_ker.texi(,48) 
mini_ker.texi(,62) 
mini_ker.texi(,64) @node Top
mini_ker.texi(Minik,65) @top Miniker 102 manual
mini_ker.texi(,66) 
mini_ker.texi(,67) 
mini_ker.texi(,68) @c @insertcopying
mini_ker.texi(,70) 
mini_ker.texi(Minik,73) @top Miniker 102 manual
mini_ker.texi(,74) 
mini_ker.texi(,75) @strong{By: The TEF Collaboration}
mini_ker.texi(,76) 
mini_ker.texi(,77) @insertcopying
mini_ker.texi(,78) 
mini_ker.texi(,80) 
mini_ker.texi(,81) @menu
mini_ker.texi(,82) * Introduction::
mini_ker.texi(,83) * TEF overview::
mini_ker.texi(Minik,84) * A model with Miniker::
mini_ker.texi(,85) * Advanced programming::
mini_ker.texi(,86) * Dynamic system analysis::
mini_ker.texi(Minik,87) * Advanced use of Miniker with make::
mini_ker.texi(,88) 
mini_ker.texi(,89) Indices
mini_ker.texi(,90) 
mini_ker.texi(,91) * Concepts index::
mini_ker.texi(,92) * Variables macros and functions index::
mini_ker.texi(,93) 
mini_ker.texi(,94) Appendices
mini_ker.texi(,95) 
mini_ker.texi(,96) * Installation::
mini_ker.texi(,97) * Cmz directives reference::
mini_ker.texi(,102) * Copying This Manual::           The GNU Free Documentation License.
mini_ker.texi(,103) @end menu
mini_ker.texi(,104) 
mini_ker.texi(,105) @contents
mini_ker.texi(,106) 
mini_ker.texi(,107) @node Introduction
mini_ker.texi(,108) @unnumbered Introduction
mini_ker.texi(,109) 
mini_ker.texi(,110) @cindex TEF
mini_ker.texi(,111) @cindex cells
mini_ker.texi(,112) @cindex transfers
mini_ker.texi(,113) @cindex ZOOM
mini_ker.texi(,114) @cindex mortran 
mini_ker.texi(,115) 
mini_ker.texi(Minik,116)    Miniker is a modeling tool, built especially in order to implement
mini_ker.texi(,117) models written following the @acronym{TEF,Transfer Evolution Formalism} 
mini_ker.texi(,118) formalism, a mathematical framework for system analysis and
mini_ker.texi(Minik,119) simulation. Miniker allows for timewise simulation, system analysis,
mini_ker.texi(,120) adjoint computation, Kalman filtering and more.
mini_ker.texi(,121) 
mini_ker.texi(Minik,122) Miniker uses a fortran preprocessor, @command{mortran}, designed in the 
mini_ker.texi(,123) 1970's, to ease model writing using dedicated specific languages.
mini_ker.texi(,124) For example partial derivatives are
mini_ker.texi(Minik,125) symbolicaly determined by @command{mortran} macros in Miniker. 
mini_ker.texi(,126) For the selection of 
mini_ker.texi(,127) another compile-time features, another set of preprocessor directives,
mini_ker.texi(,128) the @dfn{cmz directives}, are used. In most cases the user does not need to
mini_ker.texi(,129) know anything about that preprocessing that occurs behind the scene,
mini_ker.texi(,130) he simply writes down the equations of his model and he is done.
mini_ker.texi(,131) 
mini_ker.texi(,132) @c All partial derivatives needed to solve the TEF system are automatically
mini_ker.texi(,133) @c determined during the pre-compilation stage.
mini_ker.texi(,134) @c Once all models written down and initial conditions
mini_ker.texi(,135) @c given using a pseudo-Fortran type of language, the model is ready to run.
mini_ker.texi(,136) 
mini_ker.texi(,137) @c The language developed to get automatic symbolic partial derivatives
mini_ker.texi(,138) @c uses the Fortran pre-compiler @command{mortran}, designed in the 1970's.
mini_ker.texi(,139) 
mini_ker.texi(,140) A comprehensive description
mini_ker.texi(,141) of the @acronym{TEF} formalism in available on 
mini_ker.texi(,142) @url{http://www.lmd.jussieu.fr/ZOOM/doc/tef-GB-partA5.pdf}).
mini_ker.texi(Minik,143) The Miniker software is a reduced version of 
mini_ker.texi(,144) @uref{http://www.lmd.jussieu.fr@//zoom,@strong{ZOOM}}, 
mini_ker.texi(,145) that can only handle a hundreds of variables, but is much easier to use.
mini_ker.texi(,146) 
mini_ker.texi(,147) @menu 
mini_ker.texi(,148) * Intended audience::
mini_ker.texi(,149) * Reading guide::
mini_ker.texi(,150) * Other Manuals and documentation::
mini_ker.texi(,151) @end menu 
mini_ker.texi(,152) 
mini_ker.texi(,153) @node Intended audience
mini_ker.texi(,154) @unnumberedsec Intended audience
mini_ker.texi(,155) 
mini_ker.texi(,156) The reader should have notions in system dynamics.
mini_ker.texi(,157) @c and understand the basis of the TEF. 
mini_ker.texi(,158) Moreover a minimal knowledge of programmation and fortran is 
mini_ker.texi(,159) required. What is required is a basic understanding of variable types, 
mini_ker.texi(,160) affectation and fortran expressions.
mini_ker.texi(,161) 
mini_ker.texi(,162) @node Reading guide
mini_ker.texi(,163) @unnumberedsec Reading guide
mini_ker.texi(,164) 
mini_ker.texi(,165) The first chapter is a brief overview of the @acronym{TEF}.
mini_ker.texi(Minik,166) The following describes how to write, compile and run a model in Miniker 
mini_ker.texi(,167) in its basic and comprehensive syntax.
mini_ker.texi(,168) @c Reading the sections of this chapter up to the section 
mini_ker.texi(,169) @c @emph{Symbolic model description} is required to know the
mini_ker.texi(,170) @c syntax of model description in @Minik{}.
mini_ker.texi(,171) Reading up to the section
mini_ker.texi(Minik,172) @emph{Controlling the run} is required to be able to use Miniker. 
mini_ker.texi(Minik,173) In this section it is assumed that Miniker is properly setup. The
mini_ker.texi(,174) installation instructions are in the appendix at
mini_ker.texi(,175) @ref{Installation}.
mini_ker.texi(,176) 
mini_ker.texi(,177) @c 2 programming environment to compile the model are available, with cmz 
mini_ker.texi(,178) @c and make, you can skip the method description you are not interested in. 
mini_ker.texi(,179) @c A reference for the usefull cmz directives is also in the appendix
mini_ker.texi(,180) @c (@pxref{Cmz directives reference}).
mini_ker.texi(,181) 
mini_ker.texi(,182) @c You should also
mini_ker.texi(,183) @c read the following section, @emph{Symbolic model description} which presents an
mini_ker.texi(,184) @c alternate syntax for model description, such that you can choose what you
mini_ker.texi(,185) @c prefer.
mini_ker.texi(,186) 
mini_ker.texi(,187) The next chapter describes advanced features, first a general introduction to
mini_ker.texi(,188) features settings and then a description of other model description related
mini_ker.texi(,189) features.
mini_ker.texi(,190) 
mini_ker.texi(Minik,191) The next chapter describes system analysis tools available with Miniker. The
mini_ker.texi(,192) sections are independant and each describes how to use a specific feature. If
mini_ker.texi(,193) you plan on using these features, you should also read 
mini_ker.texi(,194) @ref{Selecting features, , Overview of feature setting}.
mini_ker.texi(,195) 
mini_ker.texi(,196) A final chapter describes advanced features in a development environment
mini_ker.texi(,197) using make,
mini_ker.texi(,198) 
mini_ker.texi(,199) In the appendix the instructions for the installation are described
mini_ker.texi(,200) (@pxref{Installation}). 
mini_ker.texi(,201) 
mini_ker.texi(,202) @node Other Manuals and documentation
mini_ker.texi(,203) @unnumberedsec  Other Manuals and documentation
mini_ker.texi(,204) 
mini_ker.texi(,205) A programmers'Manual is available (in French), and can be asked for to 
mini_ker.texi(,206) any member of the collabration. See additional documents in 
mini_ker.texi(,207)  @url{http://www.lmd.jussieu.fr/Zoom/doc} or ask for Research 
mini_ker.texi(,208) texts and articles to members.
mini_ker.texi(,209) 
mini_ker.texi(,210) @node TEF overview
mini_ker.texi(,211) @chapter An overview of the @acronym{TEF} formalism
mini_ker.texi(,212) 
mini_ker.texi(,213) The @acronym{TEF, Transfer Evolution Formalism} is based on partitionning
mini_ker.texi(,214) and recoupling of model subsystems. It allows the study of the coupling 
mini_ker.texi(,215) between subsystems by the means of linearization and time discretization.
mini_ker.texi(,216) 
mini_ker.texi(,217) @menu 
mini_ker.texi(,218) * Cell and Transfer::
mini_ker.texi(,219) * Linearization and discretization::
mini_ker.texi(,220) @end menu
mini_ker.texi(,221) 
mini_ker.texi(,222) @node Cell and Transfer
mini_ker.texi(,223) @section Cell and Transfer equations
mini_ker.texi(,224) 
mini_ker.texi(,225) In the @acronym{TEF}, a model is
mini_ker.texi(,226) mathematically represented by a set of equations corresponding
mini_ker.texi(,227) to two kinds objects:
mini_ker.texi(,228) 
mini_ker.texi(,229) @enumerate
mini_ker.texi(,230) @item Cells which are elementary models and correspond to evolution equations
mini_ker.texi(,231) such as:
mini_ker.texi(,245) 
mini_ker.texi(,246) @noindent @math{d eta(t)/d t = g(eta(t),phi(t))}
mini_ker.texi(,247) 
mini_ker.texi(,250) 
mini_ker.texi(,251) Vector @math{\eta} represent the state variables of cells and
mini_ker.texi(,252) the vector @math{\varphi} represent the dependent
mini_ker.texi(,253) boundary conditions, @i{i.e.} the
mini_ker.texi(,254) variables considered as boundary conditions by a cell, but depending upon
mini_ker.texi(,255) the complete model state. This dependent boundary conditions are
mini_ker.texi(,256) required to make the cells correspond to well-posed problems.
mini_ker.texi(,257) @c FIXME acceptable?
mini_ker.texi(,258) These variables are often called state variables, and prognostic 
mini_ker.texi(,259) variables in meteorology.
mini_ker.texi(,260) 
mini_ker.texi(,261) 
mini_ker.texi(,262) @item Transfers which are determined by constraint equations such as:
mini_ker.texi(,278) 
mini_ker.texi(,279) @noindent @math{phi(t) = f(eta(t),phi(t))}
mini_ker.texi(,280) 
mini_ker.texi(,283) These equations are often called algebraic equations, and in meteorology
mini_ker.texi(,284) diagnostic equations.
mini_ker.texi(,285) @end enumerate
mini_ker.texi(,286) 
mini_ker.texi(,287) @node Linearization and discretization
mini_ker.texi(,288) @section Linearization and discretization in the @acronym{TEF}
mini_ker.texi(,289) 
mini_ker.texi(,290) The relations between sub-systems is excessively difficult to exhibit when
mini_ker.texi(,291) having to cope with non-linear system. In the @acronym{TEF}, the 
mini_ker.texi(,292) @acronym{TLS, Tangent Linear System} is constructed along the trajectory.
mini_ker.texi(,293) One considers the system over a small portion along the trajectory, say
mini_ker.texi(,294) between @math{t} and @math{t + \delta t}. The variation @math{\delta \eta}
mini_ker.texi(,295) of @math{\eta} and @math{\delta \varphi} of @math{\varphi} is obtained 
mini_ker.texi(,296) through a Pad@'e approximation of the state-transition matrix. The final
mini_ker.texi(,297) form of the algebraic system is closed to the classical Crank-Nicolson scheme:
mini_ker.texi(,298) 
mini_ker.texi(,299) @c FIXME PAd'e? od Taylor?
mini_ker.texi(,300) @c through a Taylor expansion followed by time integration.
mini_ker.texi(,301) @c A time scheme is then applied to the @acronym{TLS} (a Crank-Nicholson scheme),
mini_ker.texi(,302) @c to obtain an algebraic system describing the relationships between 
mini_ker.texi(,303) @c variations of transfers and cells variables:
mini_ker.texi(,304) 
mini_ker.texi(,305) 
mini_ker.texi(,319) 
mini_ker.texi(,328) 
mini_ker.texi(,329) The blocks appearing in the Jacobian matrix are constructed with partial derivative
mini_ker.texi(,330) of @math{f} and @math{g}, and with @math{\delta t}. From this system the
mini_ker.texi(,331) elimination of @math{\delta \eta} leads to another formulation giving
mini_ker.texi(,332) the coupling between transfers, and allows for the @math{\delta \varphi}
mini_ker.texi(,333) computation. The @math{\delta \varphi} value is then substitued in 
mini_ker.texi(,334) @math{\delta \eta} to complete the time-step solving process.
mini_ker.texi(,335) 
mini_ker.texi(Minik,336) @node A model with Miniker
mini_ker.texi(Minik,337) @chapter Miniker model programming
mini_ker.texi(,338) 
mini_ker.texi(,339) @cindex sequences
mini_ker.texi(,340) 
mini_ker.texi(Minik,341) Miniker works by combining the model specification code given by 
mini_ker.texi(,342) the user and other source files provided in the package. The code is
mini_ker.texi(,343) assembled, preprocessed, compiled, linked and the resulting program 
mini_ker.texi(,344) can be run to produce the model trajectory and dynamic analysis.
mini_ker.texi(,345) 
mini_ker.texi(,346) The code provided in the package contains a principal program, some usefull
mini_ker.texi(,347) subroutines and pieces of code called @dfn{sequences} combined with the
mini_ker.texi(,348) different codes. Among these sequences some hold the code describing the model
mini_ker.texi(,349) and are to be written by the user (sequences are similar to
mini_ker.texi(,350) Fortran include files).
mini_ker.texi(,351) 
mini_ker.texi(,352) @menu
mini_ker.texi(,353) * Structure of the code::
mini_ker.texi(,354) * A model description::
mini_ker.texi(,355) * Setting and running a model::
mini_ker.texi(,356) * Controlling the run::
mini_ker.texi(,357) @end menu
mini_ker.texi(,358) 
mini_ker.texi(,359) @node Structure of the code
mini_ker.texi(,360) @section General structure of the code
mini_ker.texi(,361) 
mini_ker.texi(,362) @cindex sequence
mini_ker.texi(,363) @cindex zinit, general
mini_ker.texi(,364) 
mini_ker.texi(,365) The sequences used to enter model description hold the @c vector dimensions, 
mini_ker.texi(,366) mathematical formulae for each cell and transfer component, dedicated
mini_ker.texi(,367) derived computations, and time-step 
mini_ker.texi(,368) steering. During the code generation stage, 
mini_ker.texi(,369) cmz directives are preprocessed, then the user pseudo-Fortran
mini_ker.texi(,370) instructions are translated by @command{mortran} using macros designed to 
mini_ker.texi(,371) generate in particular all Fortran instructions that compute the Jacobian 
mini_ker.texi(,372) matrices used in @acronym{TEF} modelling.
mini_ker.texi(,373) 
mini_ker.texi(,374) @c A first users' sequence to program is: @file{dimetaphi} where the model 
mini_ker.texi(,375) @c dimensions are given, for the two vector-array @code{eta(.)} for cells 
mini_ker.texi(,376) @c and @code{ff(.)} for transfers (@pxref{Model size,,Entering model size}).
mini_ker.texi(,377)  
mini_ker.texi(,378) The sequence @file{zinit} contains the mathematical formulation of the model
mini_ker.texi(,379) (@pxref{Model equation and parameters, Entering model equation and parameters}). 
mini_ker.texi(,380) Another sequence, @file{zsteer}, is merged at
mini_ker.texi(,381) the end of the time step advance of the simulation, where the user can 
mini_ker.texi(,382) monitor the time step values and printing levels, and perform particular 
mini_ker.texi(,383) computations etc.
mini_ker.texi(,384) (@pxref{End of time step, ,Executing code at the end of each time step}).
mini_ker.texi(,385) 
mini_ker.texi(,386) @node A model description
mini_ker.texi(Minik,387) @section Miniker programming illustrated
mini_ker.texi(,388) 
mini_ker.texi(,389) @cindex TEF
mini_ker.texi(,390) 
mini_ker.texi(,391) The general @acronym{TEF} system writes:
mini_ker.texi(,408) 
mini_ker.texi(,409) @noindent @math{d eta(t)/d t = g(eta(t),phi(t))@*
mini_ker.texi(,410) phi(t) = f(eta(t),phi(t))}
mini_ker.texi(,411) 
mini_ker.texi(,414) 
mini_ker.texi(Minik,415) To illustrate the model description in Miniker a simple predator-prey
mini_ker.texi(,416) model of Lotka-Volterra is used.
mini_ker.texi(,417) This model can be written in the following @acronym{TEF} form:
mini_ker.texi(,418) 
mini_ker.texi(,444) @noindent @math{d eta_prey(t)/d t = a * eta_prey - a * phi_meet@*
mini_ker.texi(,445) d eta_pred(t)/d t = -c * eta_pred +c * phi_meet}
mini_ker.texi(,446) 
mini_ker.texi(,447) @noindent @math{phi_meet = eta_prey * eta_pred}
mini_ker.texi(,450) 
mini_ker.texi(,451) with two cell equations, @i{i.e}. state evolution of the prey and predator 
mini_ker.texi(,452) groups, and one transfer accounting for the meeting of individuals of 
mini_ker.texi(,453) different group.
mini_ker.texi(,454) 
mini_ker.texi(,455) @menu
mini_ker.texi(,456) * A note about mortran and cmz directives::
mini_ker.texi(,457) * Model equation and parameters::
mini_ker.texi(,458) @end menu
mini_ker.texi(,459) 
mini_ker.texi(,460) @node A note about mortran and cmz directives
mini_ker.texi(,461) @subsection All you need to know about mortran and cmz directives
mini_ker.texi(,462) 
mini_ker.texi(,463) @cindex mortran 
mini_ker.texi(,464) 
mini_ker.texi(,465) The first stage of code generation consists in cmz directives preprocessing.
mini_ker.texi(,466) Cmz directives are used for conditional selection of features, and sequence 
mini_ker.texi(,467) inclusion. At that point you don't need to know anything about these
mini_ker.texi(,468) directives. They are only usefull if you want to take advantage of advanced 
mini_ker.texi(,469) features 
mini_ker.texi(,470) (@pxref{Programming with cmz directives}).
mini_ker.texi(,471) 
mini_ker.texi(,472) The code in sequences is written in Mortran and the second stage of code
mini_ker.texi(,473) generation consists in mortran macro expansion. The mortran language is 
mini_ker.texi(,474) described
mini_ker.texi(,475) in its own manual, here we only explain the very basics which is all you need
mini_ker.texi(Minik,476) to know to use Miniker. Mortran basic instructions are almost Fortran,
mini_ker.texi(,477) the differences are the following:
mini_ker.texi(,478) 
mini_ker.texi(,479) @itemize @bullet
mini_ker.texi(,480) @item The code is free-form, and each statement should end with a semi-colon 
mini_ker.texi(,481) @code{;}.
mini_ker.texi(,482) @item Comments may be introduced by an exclamation mark @code{!} at the 
mini_ker.texi(,483) beginning of a line, or appear within double quotes @code{"} in a single line.
mini_ker.texi(,484) @item It is possible to use blocs, for @code{do} or @code{if} statement 
mini_ker.texi(,485) for example, and they are enclosed within brackets @samp{<} and @samp{>}.
mini_ker.texi(,486) To be in the safe side, a semi-colon @code{;} should be added after a 
mini_ker.texi(,487) closng bracket @code{>}.
mini_ker.texi(,488) @end itemize
mini_ker.texi(,489) 
mini_ker.texi(,490) The following fictious code is legal mortran:
mini_ker.texi(,491) 
mini_ker.texi(,492) @example
mini_ker.texi(,493) real 
mini_ker.texi(,494)   param;
mini_ker.texi(,495) param = 3.; ff(1) = ff(3)**eta(1);       "a comment"                 
mini_ker.texi(,496) ! a line comment
mini_ker.texi(,497) do inode=1,n_node <eta_move(inode)=0.01; eta_speed(inode)=0.0;>;
mini_ker.texi(,498) @end example
mini_ker.texi(,499) 
mini_ker.texi(,500) Thanks to mortran the model code is very simply specified, as you'll 
mini_ker.texi(,501) see next.
mini_ker.texi(,502) 
mini_ker.texi(,503) 
mini_ker.texi(,504) @node Model equation and parameters
mini_ker.texi(,505) @subsection Entering model equation and parameters
mini_ker.texi(,506) 
mini_ker.texi(,507) @cindex @file{zinit}
mini_ker.texi(,508) @vindex dt
mini_ker.texi(,509) @vindex time
mini_ker.texi(,510) @vindex nstep
mini_ker.texi(,511) @vindex modzprint
mini_ker.texi(,512) 
mini_ker.texi(Minik,513) The model equation and parameters and some Miniker parameters are entered in
mini_ker.texi(,514) the @file{zinit} sequence. The whole layout of the model is given
mini_ker.texi(,515) before detailing the keywords.
mini_ker.texi(,516) 
mini_ker.texi(,517) @example
mini_ker.texi(,518) !%%%%%%%%%%%%%%%%%%%%%%
mini_ker.texi(,519) ! Parameters           
mini_ker.texi(,520) !%%%%%%%%%%%%%%%%%%%%%%
mini_ker.texi(,521)   real apar,bpar;        "optional Fortran type declaration"
mini_ker.texi(,522) 
mini_ker.texi(,523) ! required parameters
mini_ker.texi(,524)      dt=.01;             "initial time-step"
mini_ker.texi(,525)      nstep=10 000;       "number of iterations along the trajectory"
mini_ker.texi(,526)      time=0.;            "time initialisation "
mini_ker.texi(,527) 
mini_ker.texi(,528) ! model parameters            
mini_ker.texi(,529)      apar = 1.5;             
mini_ker.texi(,530)      cpar = 0.7;          
mini_ker.texi(,531)                                                   
mini_ker.texi(,532) ! misceallaneous parameters
mini_ker.texi(,533)      modzprint = 1000;    "printouts frequency" 
mini_ker.texi(,534) 
mini_ker.texi(,535) print*,'***************************************';
mini_ker.texi(,536) print*,'Lotka-Volterra model with parameters as:';
mini_ker.texi(,537) z_pr: apar,bpar;
mini_ker.texi(,538) print*,'***************************************';
mini_ker.texi(,539) 
mini_ker.texi(,540) !%%%%%%%%%%%%%%%%%%%%%%
mini_ker.texi(,541) ! Transfer definition
mini_ker.texi(,542) !%%%%%%%%%%%%%%%%%%%%%%
mini_ker.texi(,543) ! rencontre (meeting)
mini_ker.texi(,544) set_Phi
mini_ker.texi(,545) < var: ff_interact, fun: f_interact = eta_prey*eta_pred;
mini_ker.texi(,546) >;
mini_ker.texi(,547) 
mini_ker.texi(,548) !%%%%%%%%%%%%%%%%%%%%%%
mini_ker.texi(,549) ! Cell definition
mini_ker.texi(,550) !%%%%%%%%%%%%%%%%%%%%%%
mini_ker.texi(,551) 
mini_ker.texi(,552) set_eta
mini_ker.texi(,553) < var: eta_prey, fun: deta_prey =   apar*eta_prey - apar*ff_interact;
mini_ker.texi(,554)   var: eta_pred, fun: deta_pred = - cpar*eta_pred + cpar*ff_interact;
mini_ker.texi(,555) >;
mini_ker.texi(,556) 
mini_ker.texi(,557) 
mini_ker.texi(,558) !%%%%%%%%%%%%%%%%%%%%%%
mini_ker.texi(,559) ! Initial states
mini_ker.texi(,560) !%%%%%%%%%%%%%%%%%%%%%%
mini_ker.texi(,561)      eta_prey = 1.;
mini_ker.texi(,562)      eta_pred = 1.;
mini_ker.texi(,563) ;
mini_ker.texi(,564)     OPEN(50,FILE='title.tex',STATUS='UNKNOWN');   "title file"
mini_ker.texi(,565)     write(50,5000) apar,cpar;                     
mini_ker.texi(,566) 5000;format('Lotka-Volterra par:',2F4.1);
mini_ker.texi(,567) @end example
mini_ker.texi(,568) 
mini_ker.texi(,569) @subsubheading Variables and model parameters
mini_ker.texi(,570) 
mini_ker.texi(,571) The following variables are mandatory:
mini_ker.texi(,572) 
mini_ker.texi(,573) @table @code
mini_ker.texi(,574) @item dt
mini_ker.texi(,575) The time step.
mini_ker.texi(,576) @item time
mini_ker.texi(,577) Model time initialisation.
mini_ker.texi(,578) @item nstep
mini_ker.texi(,579) Number of iterations along the trajectory.
mini_ker.texi(,580) @end table
mini_ker.texi(,581) 
mini_ker.texi(,582) There are no other mandatory variables. Some optional variables are used
mini_ker.texi(,583) to monitor the printout and ouput of results of the code.
mini_ker.texi(,584) As an example, the variable @code{modzprint} is used to set
mini_ker.texi(,585) the frequency of the printout of the model matrix and vectors during the
mini_ker.texi(,586) run (@pxref{Controlling the printout and data output}).
mini_ker.texi(,587) 
mini_ker.texi(,588) User's defined variable and Fortran or Mortran instructions can always be
mini_ker.texi(,589) added for intermediate calculus. To avoid conflict with the variables of the
mini_ker.texi(Minik,590) Miniker code, the rule is that a users symbol must not have characters 
mini_ker.texi(,591) @samp{o} 
mini_ker.texi(,592) in the first two symbol characters.
mini_ker.texi(,593) 
mini_ker.texi(,594) In the predator-prey example there are two model parameters. The fortran
mini_ker.texi(,595) variables are called here @code{apar} for @math{a} and @code{cpar} for @math{c}.
mini_ker.texi(,596) If a Fortan type definition is needed, it should be set at the very beginning
mini_ker.texi(,597) of @file{zinit}. The predator-prey code variable initializations finally reads
mini_ker.texi(,598) 
mini_ker.texi(,599) @example
mini_ker.texi(,600) @group
mini_ker.texi(,601) !%%%%%%%%%%%%%%%%%%%%%%
mini_ker.texi(,602) ! Parameters         
mini_ker.texi(,603) !%%%%%%%%%%%%%%%%%%%%%%
mini_ker.texi(,604)   real apar,bpar;        "optional Fortran type declaration"
mini_ker.texi(,605) 
mini_ker.texi(,606)      dt=.01;           
mini_ker.texi(,607)      nstep=10 000;    
mini_ker.texi(,608)      time=0.;            
mini_ker.texi(,609) 
mini_ker.texi(,610) ! model parameters
mini_ker.texi(,611)      apar = 1.5;           
mini_ker.texi(,612)      cpar = 0.7;                                                            
mini_ker.texi(,613) 
mini_ker.texi(,614)      modzprint = 1000;  
mini_ker.texi(,615) @end group
mini_ker.texi(,616) @end example
mini_ker.texi(,617) 
mini_ker.texi(,618) @subsubheading Model equations
mini_ker.texi(,619) @anchor{Model equations}
mini_ker.texi(,620) 
mini_ker.texi(,621) @findex set_Phi
mini_ker.texi(,622) @findex set_eta
mini_ker.texi(,623) @vindex var:
mini_ker.texi(,624) @vindex fun:
mini_ker.texi(,625) @vindex eqn:
mini_ker.texi(,626) 
mini_ker.texi(,627) The model equations for cells and model equations for transferts are 
mini_ker.texi(,628) entered in two mortran blocks, one for the transferts, the other for the
mini_ker.texi(,629) cell components.  The model equations for cells are entered into a 
mini_ker.texi(,630) @code{set_eta} block, and the transfer equations are entered into a
mini_ker.texi(,631) @code{set_phi} block.
mini_ker.texi(,632) 
mini_ker.texi(,633) In each block the couples variable-function are specified. For
mini_ker.texi(,634) transfers the function defines the transfer itself while for cells
mini_ker.texi(,635) the function describes the cell evolution. The variable is specified
mini_ker.texi(,636) with @code{var:}, the function is defined with @code{fun:}.
mini_ker.texi(,637) 
mini_ker.texi(,638) In the case of the predator-prey model, the transfer variable
mini_ker.texi(,639) associated with @math{\varphi_{meet}} could be called @code{ff_interact}
mini_ker.texi(,640) and the transfer definition would be given by:
mini_ker.texi(,641) @example
mini_ker.texi(,642) set_Phi
mini_ker.texi(,643) < var: ff_interact, fun: f_interact = eta_prey*eta_pred;
mini_ker.texi(,644) >;
mini_ker.texi(,645) @end example
mini_ker.texi(,646) 
mini_ker.texi(,647) The two cell equations of the predator-prey model, with name
mini_ker.texi(,648) @code{eta_prey} for the prey (@math{\eta_{prey}}) and @code{eta_pred} 
mini_ker.texi(,649) for the predator (@math{\eta_{pred}}) are:
mini_ker.texi(,650) 
mini_ker.texi(,651) @example
mini_ker.texi(,652) set_eta
mini_ker.texi(,653) < var: eta_prey, fun: deta_prey =   apar*eta_prey - apar*ff_interact;
mini_ker.texi(,654)   var: eta_pred, fun: deta_pred = - cpar*eta_pred + cpar*ff_interact;
mini_ker.texi(,655) >;
mini_ker.texi(,656) @end example
mini_ker.texi(,657) 
mini_ker.texi(,658) The @samp{;} at the end of the mortran block is important.
mini_ker.texi(,659) 
mini_ker.texi(,660) @page
mini_ker.texi(,661) The whole model equations are setup with:
mini_ker.texi(,662) 
mini_ker.texi(,663) @example
mini_ker.texi(,664) @group
mini_ker.texi(,665) !%%%%%%%%%%%%%%%%%%%%%%
mini_ker.texi(,666) ! Transfer definition
mini_ker.texi(,667) !%%%%%%%%%%%%%%%%%%%%%%
mini_ker.texi(,668) ! rencontre (meeting)
mini_ker.texi(,669) set_Phi
mini_ker.texi(,670) < var: ff_interact, fun: f_interact = eta_prey*eta_pred;
mini_ker.texi(,671) >;
mini_ker.texi(,672) 
mini_ker.texi(,673) !%%%%%%%%%%%%%%%%%%%%%%
mini_ker.texi(,674) ! Cell definition
mini_ker.texi(,675) !%%%%%%%%%%%%%%%%%%%%%%
mini_ker.texi(,676) 
mini_ker.texi(,677) set_eta
mini_ker.texi(,678) < var: eta_prey, fun: deta_prey =   apar*eta_prey - apar*ff_interact;
mini_ker.texi(,679)   var: eta_pred, fun: deta_pred = - cpar*eta_pred + cpar*ff_interact;
mini_ker.texi(,680) >;
mini_ker.texi(,681) @end group
mini_ker.texi(,682) @end example
mini_ker.texi(,683) 
mini_ker.texi(,684) Whenever the user is not concerned with giving a specific name to a
mini_ker.texi(,685) function, it is possible to specify the equation only with
mini_ker.texi(,686) @code{eqn:}. Therefore the user may replace an instruction as:
mini_ker.texi(,687) @example
mini_ker.texi(,688)   var: ff_dump,
mini_ker.texi(,689)   fun: f_dump  = - rd*(eta_speed - eta_speed_limiting);
mini_ker.texi(,690) @end example
mini_ker.texi(,691) with:
mini_ker.texi(,692) @example
mini_ker.texi(,693)    eqn: ff_dump = - rd*(eta_speed - eta_speed_limiting);
mini_ker.texi(,694) @end example
mini_ker.texi(,695) 
mini_ker.texi(,696) In that case, the unnamed function will take the name of the defined
mini_ker.texi(,697) variable preceded by the @samp{$} sign: @code{$ff_dump}.
mini_ker.texi(,698) 
mini_ker.texi(,699) @subsubheading Starting points
mini_ker.texi(,700) 
mini_ker.texi(,701) @cindex starting point
mini_ker.texi(,702) 
mini_ker.texi(,703) The cells equations require state initial conditions. In some case, the 
mini_ker.texi(,704) transfers may also need starting points although they are determined from 
mini_ker.texi(,705) the cell values.
mini_ker.texi(,706) 
mini_ker.texi(,707) In the predator-prey model the starting points for cells are:
mini_ker.texi(,708) @example
mini_ker.texi(,709) !     initial state
mini_ker.texi(,710) !     -------------
mini_ker.texi(,711)      eta_prey = 1.;
mini_ker.texi(,712)      eta_pred = 1.;
mini_ker.texi(,713) @end example
mini_ker.texi(,714) 
mini_ker.texi(,715) When there is a non trivial implicit relationship between the transfers
mini_ker.texi(,716) in the model, it may be usefull or even necessary to set some
mini_ker.texi(,717) transfers to non-zero values. This difficulty is only relevant for the very
mini_ker.texi(,718) first step of the simulation and will be used as a 
mini_ker.texi(,719) first guess of @math{\varphi}. The uninitialized transfers having 
mini_ker.texi(,720) a default compiler-dependant (often zero) value, an initialization
mini_ker.texi(,721) to another value may help avoiding singular functions or matrix and
mini_ker.texi(,722) ensure convergence in the Newton algorithm used to solve the transfer implicit
mini_ker.texi(,723) equation. 
mini_ker.texi(,724) 
mini_ker.texi(,753) 
mini_ker.texi(,754) @subsubheading The cell and transfer arrays
mini_ker.texi(,755) 
mini_ker.texi(,756) @vindex eta(.)
mini_ker.texi(,757) @vindex ff(.)
mini_ker.texi(,758) @vindex mp
mini_ker.texi(,759) @vindex np
mini_ker.texi(,760) 
mini_ker.texi(,761) Sometime it is easier to iterate over an array than to use the 
mini_ker.texi(,762) cell or transfer variable name. This is possible because there is a
mini_ker.texi(,763) correspondence between the variable names 
mini_ker.texi(,764) and the fortran array @code{eta(.)} for the cell variables and
mini_ker.texi(,765) the fortran array @code{ff(.)} for the transfer variables@footnote{In fact
mini_ker.texi(,766) the variables names are transformed into fortran array elements
mini_ker.texi(,767) by mortran generated macros, so the symbolic names defined in the
mini_ker.texi(,768) mortran blocks never appears in the generated fortran code, they are
mini_ker.texi(,769) replaced by the fortran arrays.}.
mini_ker.texi(,770) 
mini_ker.texi(,771) The index of the variable is determined by the order of appearance in 
mini_ker.texi(,772) the variable definition blocks. It is reminded in the output, as
mini_ker.texi(,773) explained later (@pxref{Simulation and output}). 
mini_ker.texi(,774) 
mini_ker.texi(,775) The number of cells is in the integer @code{np} variable, and the
mini_ker.texi(,776) number of transfer is in the integer @code{mp} variable.
mini_ker.texi(,777) 
mini_ker.texi(,778) @subsubheading title file
mini_ker.texi(,779) 
mini_ker.texi(,780) @anchor{Title file}
mini_ker.texi(,781) @cindex title file
mini_ker.texi(,782) @cindex @file{title.tex}
mini_ker.texi(,783) 
mini_ker.texi(,784) For some graphics generation, a file with name @file{title.tex} is required
mini_ker.texi(,785) which sets the title. The following instructions take care of that:
mini_ker.texi(,786) 
mini_ker.texi(,787) @example
mini_ker.texi(,788)     OPEN(50,FILE='title.tex',STATUS='UNKNOWN');
mini_ker.texi(,789)     write(50,5000) apar,cpar;                 
mini_ker.texi(,790) 5000;format('Lotka-Volterra par:',2F4.1);
mini_ker.texi(,791) 
mini_ker.texi(,792)     close(50);
mini_ker.texi(,793) @end example
mini_ker.texi(,794) 
mini_ker.texi(,795) In that case the parameter values are written down, to differenciate between
mini_ker.texi(,796) different runs. This step is in general not needed.
mini_ker.texi(,797) 
mini_ker.texi(,798) @c The correspondence with basic components are printed out at execution
mini_ker.texi(,799) @c time as explained in @ref{Simulation and output,,
mini_ker.texi(,800) @c Running a simulation and using the output}. Also, a @file{Model.hlp} is
mini_ker.texi(,801) @c generated that recalls the basic names and equations of the model.
mini_ker.texi(,802) @c It may be noted that whenever 
mini_ker.texi(,803) @c the order of variable-functions is the same between indexed declaration and 
mini_ker.texi(,804) @c symbolic, the two generated Fortran code are almost identical.
mini_ker.texi(,805) 
mini_ker.texi(,806) @node  Setting and running a model
mini_ker.texi(,807) @section Setting and running a model
mini_ker.texi(,808) 
mini_ker.texi(,809) In this section it is assumed that a programming environment has been
mini_ker.texi(,810) properly setup. This environment may use either cmz or make to drive
mini_ker.texi(,811) the preprocessing and compilation. 
mini_ker.texi(,812) You can skip the part related with the environment you don't intend to use.
mini_ker.texi(,813) 
mini_ker.texi(,814) For instructions regarding the 
mini_ker.texi(,815) installation, see @ref{Installation}. 
mini_ker.texi(,816) 
mini_ker.texi(,817) 
mini_ker.texi(,818) @menu
mini_ker.texi(,819) * Setting up a model with cmz::
mini_ker.texi(,820) * Setting up a model with make::
mini_ker.texi(,821) * Simulation and output::
mini_ker.texi(,822) * Graphics::
mini_ker.texi(,823) @end menu
mini_ker.texi(,824) 
mini_ker.texi(,825) @node Setting up a model with cmz
mini_ker.texi(,826) @subsection Setup a model and compile with cmz
mini_ker.texi(,827) 
mini_ker.texi(,828) @cindex @command{mod}
mini_ker.texi(,829) @cindex @file{$zinit}
mini_ker.texi(,830) @cindex @file{$dimetaphi}
mini_ker.texi(,831) 
mini_ker.texi(,832) The user defined sequences are @samp{KEEP} in the
mini_ker.texi(,833) cmz world. The most common organization is to have a cmz file in a
mini_ker.texi(,834) subdirectory of the directory containing the @file{mini_ker.cmz} 
mini_ker.texi(,835) cmz file. In this
mini_ker.texi(,836) cmz file there should be a @samp{PATCH} called @samp{zinproc}
mini_ker.texi(,837) with the KEEPs within the patch. The KEEP must be called @file{$zinit}.
mini_ker.texi(,838) @c and @file{$dimetaphi}.
mini_ker.texi(,839) 
mini_ker.texi(,840) From within cmz in the directory of your model the source extraction, 
mini_ker.texi(,841) compilation and linking will be triggered by a @command{mod} command. This macro 
mini_ker.texi(,842) uses the @file{selseq.kumac} information to find the @file{mini_ker.cmz} 
mini_ker.texi(,843) cmz file.
mini_ker.texi(,844) @command{mod} 
mini_ker.texi(,845) shall create a directory with the same name than the cmz file, 
mini_ker.texi(,846) @file{mymodel/} in our example. In this directory there is another 
mini_ker.texi(,847) directory @file{cfs/} containing the sources extracted from the cmz file.
mini_ker.texi(,848) 
mini_ker.texi(,849) The file @file{mymodel_o.tmp} contains all the mortran code generated 
mini_ker.texi(,850) by cmz with the sequences substituted, including the @file{$zinit}. @c and 
mini_ker.texi(,851) @c @file{$dimetaphi} sequences (assembled code). 
mini_ker.texi(,852) The fortran produced by the preprocessing and
mini_ker.texi(,853) splitting of this file is in files with the traditional @samp{.f} suffix.
mini_ker.texi(,854) The principal program is in @file{principal.f}. An efficient way of getting 
mini_ker.texi(,855) familiar with mini_ker methods is looking at the @file{mymodel_o.tmp} where 
mini_ker.texi(,856) all sequences and main Mortran instructions are gathered. Symbolic derivation 
mini_ker.texi(,857) @c FIXME pas ici la symbolic derivation
mini_ker.texi(,858) is noted as @code{F_D(expression)(/variable)}, and the resulting Fortran code 
mini_ker.texi(,859) is in @file{principal.f}.
mini_ker.texi(,860) 
mini_ker.texi(,861) @command{mod} also triggers compilation and linking. The object files are in
mini_ker.texi(,862) the same @file{cfs/} directory and the executable is in the @file{mymodel/}
mini_ker.texi(,863) directory, with name @file{mymodel.exe}.
mini_ker.texi(,864) 
mini_ker.texi(,865) @node Setting up a model with make
mini_ker.texi(,866) @subsection Setup a model and compile with make
mini_ker.texi(,867) 
mini_ker.texi(,868) @cindex compilation
mini_ker.texi(,869) @c @cindex @file{dimetaphi.mti}
mini_ker.texi(,870) @cindex @file{zinit.mti}
mini_ker.texi(,871) @vindex model_file_name
mini_ker.texi(,872) 
mini_ker.texi(,873) With make, the sequences are files ending with @samp{.mti} (for
mini_ker.texi(,874) mortran include files),
mini_ker.texi(,875) called, for example, @file{zinit.mti}.
mini_ker.texi(,876) @c  and @file{dimetaphi.mti}. 
mini_ker.texi(,877) They are included by 
mini_ker.texi(,878) @command{mortran} in other source files. You also need a @file{Makefile}
mini_ker.texi(,879) to drive the compilation of the model.
mini_ker.texi(,880) 
mini_ker.texi(,881) If you don't need additional code or libraries to be linked with your 
mini_ker.texi(,882) model you have two alternatives. 
mini_ker.texi(,883) 
mini_ker.texi(,884) @enumerate
mini_ker.texi(,885) @item
mini_ker.texi(,886) The simplest alternative is to run
mini_ker.texi(,887) the @command{start_miniker} script with the model file name as argument.
mini_ker.texi(,888) It should copy a @file{zinit.mti} file
mini_ker.texi(,889) ready to be edited and a Makefile ready to compile the model. For
mini_ker.texi(,890) the predator prey model, for example, you could run
mini_ker.texi(,891) 
mini_ker.texi(,892) @example
mini_ker.texi(,893) $ start_miniker predator
mini_ker.texi(,894) @end example
mini_ker.texi(,895) 
mini_ker.texi(,896) @item
mini_ker.texi(,897) Otherwise you can copy the Makefile from @file{template/Makefile}
mini_ker.texi(,898) in the directory containing the sequences. You should then change the compiled
mini_ker.texi(,899) model file name, by changing  the value of the
mini_ker.texi(,900) @code{model_file_name} variable to the name of your choice
mini_ker.texi(,901) in the Makefile. It is set to @file{mymodel} in the template. For the 
mini_ker.texi(,902) predator-prey model, it could be set like
mini_ker.texi(,903) 
mini_ker.texi(,904) @example
mini_ker.texi(,905) model_file_name = predator
mini_ker.texi(,906) @end example
mini_ker.texi(,907) 
mini_ker.texi(,908) If you want the executable model file to be built in another directory, you could
mini_ker.texi(,909) set
mini_ker.texi(,910) 
mini_ker.texi(,911) @example
mini_ker.texi(,912) model_file_name = some_dir/predator
mini_ker.texi(,913) @end example
mini_ker.texi(,914) 
mini_ker.texi(,915) The other items set in the default Makefile should be right. 
mini_ker.texi(,916) @end enumerate
mini_ker.texi(,917) 
mini_ker.texi(,918) The preprocessing and the compilation are launched with
mini_ker.texi(,919) 
mini_ker.texi(,920) @example
mini_ker.texi(,921) make all
mini_ker.texi(,922) @end example
mini_ker.texi(,923) 
mini_ker.texi(,924) The mortran files are generated by the cmz directive preprocessor 
mini_ker.texi(,925) from files found in the package source directories. The mortran files 
mini_ker.texi(,926) end with @samp{.mtn} for the main files and  @samp{.mti} for 
mini_ker.texi(,927) include files. They are output in the current directory.
mini_ker.texi(,928) The mortran preprocessor then preprocess these mortran files and includes
mini_ker.texi(,929) the sequences. The resulting fortran code is also in the current directory, 
mini_ker.texi(,930) in files with a @samp{.f} suffix.
mini_ker.texi(,931) Some fortran files ending with @samp{.F} may also be
mini_ker.texi(,932) created by the cmz directive preprocessor.
mini_ker.texi(,933) The object files resulting from the compilation of all the
mini_ker.texi(,934) fortran files (generated from mortran or directly from fortran files) are
mini_ker.texi(,935) there too. 
mini_ker.texi(,936) 
mini_ker.texi(,937) In case you want to override the default sequences or a subroutine file 
mini_ker.texi(,938) you just have to create it in your working directory along with the
mini_ker.texi(,939) @file{zinit.mti}. @c and @file{dimetaphi.mti}. 
mini_ker.texi(,940) For example you could want to 
mini_ker.texi(,941) create or modify a @file{zsteer.mti} file (@pxref{End of time step,,
mini_ker.texi(,942) Executing code at the end of each time step}), a @file{zcmd_law.mti} file 
mini_ker.texi(,943) (@pxref{Control laws}), a @file{monitor.f} file 
mini_ker.texi(,944) (@pxref{Turning the model into a subroutine}) to take advantage of 
mini_ker.texi(,945) features presented later in this manual.
mini_ker.texi(,946) 
mini_ker.texi(Minik,947) More in-depth discussion of using make to run Miniker is covered in 
mini_ker.texi(Minik,948) @ref{Advanced use of Miniker with make}.
mini_ker.texi(,949) For example it is also possible to create files that are to be 
mini_ker.texi(,950) preprocessed by the cmz directive
mini_ker.texi(,951) preprocessor and separate source files and generated files.
mini_ker.texi(,952) This advanced use is more precisely covered in 
mini_ker.texi(,953) @ref{Programming with cmz directives}.
mini_ker.texi(,954) 
mini_ker.texi(,955) @page
mini_ker.texi(,956) @node Simulation and output
mini_ker.texi(,957) @subsection Running a simulation and using the output
mini_ker.texi(,958) 
mini_ker.texi(,959) @cindex running model
mini_ker.texi(,960) 
mini_ker.texi(,961) Once compiled the model is ready to run, it only has to be executed. On 
mini_ker.texi(,962) standard output informations about the states, transfers, tangent linear
mini_ker.texi(,963) system and other jacobian matrices are printed. 
mini_ker.texi(,964) For example the predator-prey model could be executed with:
mini_ker.texi(,965) 
mini_ker.texi(,966) @example
mini_ker.texi(,967) ./predator > result.lis
mini_ker.texi(,968) @end example
mini_ker.texi(,969) 
mini_ker.texi(,970) @cindex output file
mini_ker.texi(,971) @vindex dEta(.)
mini_ker.texi(,972) @cindex @file{res.data}
mini_ker.texi(,973) @cindex @file{dres.data}
mini_ker.texi(,974) @cindex @file{tr.data}
mini_ker.texi(,975) @cindex @file{aspha.data}
mini_ker.texi(,976) @cindex @file{Model.hlp}
mini_ker.texi(,977) 
mini_ker.texi(,978) @c In case of a model entered symbolically 
mini_ker.texi(,979) @c (@pxref{Symbolic model description})
mini_ker.texi(,980) The  correspondance
mini_ker.texi(,981) between the symbolic variables and the basic vectors and functions
mini_ker.texi(,982) are printed at run time:
mini_ker.texi(,983) 
mini_ker.texi(,984) @example
mini_ker.texi(,985)   ---------------- Informing on Phi definition -----------------
mini_ker.texi(,986)     Var-name,           Function-name,       index in ff vector
mini_ker.texi(,987)              ff_interact              f_interact  1
mini_ker.texi(,988)   ----------------------------------------------------
mini_ker.texi(,989) 
mini_ker.texi(,990)   --------------- Informing on Eta definition ------------------
mini_ker.texi(,991)    Var-name,           Function-name,       index in eta vector
mini_ker.texi(,992)                 eta_prey               deta_prey  1
mini_ker.texi(,993)                 eta_pred               deta_pred  2
mini_ker.texi(,994) @end example
mini_ker.texi(,995) 
mini_ker.texi(,996) A summary of the model equations are in @file{Model.hlp} file.  For
mini_ker.texi(,997) the same example:
mini_ker.texi(,998) 
mini_ker.texi(,999) @example
mini_ker.texi(,1000) ======================= set_Phi                                                                
mini_ker.texi(,1001)                                                                                          
mini_ker.texi(,1002)     1 ff_interact f_interact           eta_pray*eta_pred
mini_ker.texi(,1003) ======================= set_Eta                                                                
mini_ker.texi(,1004)                                                                                          
mini_ker.texi(,1005)     1 eta_pray    deta_pray            apar*eta_pray-apar*ff_interact
mini_ker.texi(,1006)     2 eta_pred    deta_pred            -cpar*eta_pred+cpar*ff_interact
mini_ker.texi(,1007) @end example
mini_ker.texi(,1008) @c FIXME never talked about that. Certainly not here
mini_ker.texi(,1009) when other general functions are specified with @code{f_set}, it can appear
mini_ker.texi(,1010) also in the same help file when replaced by @code{fun_set}.
mini_ker.texi(,1011) 
mini_ker.texi(,1012) As far as possible, all data printed in the listing are associated
mini_ker.texi(,1013) with a name related to a variable. Here is an extract:
mini_ker.texi(,1014) 
mini_ker.texi(,1015) @example
mini_ker.texi(,1016)  Gamma :-8.19100E-02-1.42151E-01 3.87150E-02
mini_ker.texi(,1017)          eta_courant eta_T_czcx  eta_T_sz   
mini_ker.texi(,1018)        ------------------------------------------------
mini_ker.texi(,1019)  Omega : 0.00000E+00 0.00000E+00 0.00000E+00 0.00000E+00
mini_ker.texi(,1020)          courant_L   T_czcx      Psi_Tczc    Psi_Tsz 
mini_ker.texi(,1021)        ------------------------------------------------
mini_ker.texi(,1022) @end example
mini_ker.texi(,1023) for the two known vectors of the system, and:
mini_ker.texi(,1024) @example
mini_ker.texi(,1025)  >ker : Matrice de couplage       4 4 4 4
mini_ker.texi(,1026) courant_L Raw(1,j=1,4):   1.000     -9.9010E-03  0.000       0.000    
mini_ker.texi(,1027) T_czcx    Raw(2,j=1,4): -2.7972E-02   1.000      0.000      9.9900E-04
mini_ker.texi(,1028) Psi_Tczcx Raw(3,j=1,4):  0.1605      9.7359E-02  1.000     -5.7321E-03
mini_ker.texi(,1029) Psi_Tsz   Raw(4,j=1,4):   0.000     -0.1376     5.7225E-03   1.000    
mini_ker.texi(,1030)           Var-Name      courant_L   T_czcx      Psi_Tczc    Psi_Tsz 
mini_ker.texi(,1031)           ----------------------------------------------------------
mini_ker.texi(,1032) @end example
mini_ker.texi(,1033) 
mini_ker.texi(,1034) where the @code{couplage} (coupling matrix) is given that corresponds 
mini_ker.texi(,1035) to the matrix coupling the four transfer components after @math{\delta\eta} 
mini_ker.texi(,1036) has been eliminated from system. It is computed in the subprogram 
mini_ker.texi(,1037) @file{oker} (for kernel) which solves the system.
mini_ker.texi(,1038) 
mini_ker.texi(,1039) Basic results are output in a set of @samp{.data} files. 
mini_ker.texi(,1040) The first line (or two lines) describes the column with a @samp{#}
mini_ker.texi(,1041) character used to mark the lines as comments (for @command{gnuplot} 
mini_ker.texi(,1042) for example).
mini_ker.texi(,1043) In the @samp{.data} files, the data are simply separated with spaces.
mini_ker.texi(,1044) Each data file has the @code{time} variable values as first column.
mini_ker.texi(,1045) @footnote{@file{dres.data} has another time related variable as second column:
mini_ker.texi(,1046) @cindex @file{dres.data}
mini_ker.texi(,1047) @vindex dt
mini_ker.texi(,1048) @code{dt}, the time step that can vary in the course of a simulation.}.
mini_ker.texi(,1049) Following columns give the values of @code{eta(.)} in @file{res.data}, 
mini_ker.texi(,1050) @code{dEta(.)} in @file{dres.data} -- the step by step variation of 
mini_ker.texi(,1051) @code{eta(.)} -- and @code{ff(.)} in @file{tr.data}.
mini_ker.texi(,1052) 
mini_ker.texi(,1053) Along the simulation the @acronym{TEF} Jacobian matrices are computed. 
mini_ker.texi(,1054) A transfer variables elimination process also leads to the definition 
mini_ker.texi(,1055) of the classical state advance matrix of the system 
mini_ker.texi(,1056) (the corresponding array is @code{aspha(.,.)} in the code).
mini_ker.texi(,1057) This matrix is output in the file @file{aspha.data} that is used to
mini_ker.texi(,1058) post-run dynamics analyses. The matrix columns are written column wise on each
mini_ker.texi(,1059) record.
mini_ker.texi(,1060) @xref{Stability of fastest modes,,Stability analysis of fastest modes}. 
mini_ker.texi(,1061) @xref{Generalized TLS,,Generalized 
mini_ker.texi(,1062) tangent linear system analysis}. It is not used in the solving process.
mini_ker.texi(,1063) 
mini_ker.texi(,1064) Other @samp{.data} files will be described later.
mini_ker.texi(,1065) 
mini_ker.texi(,1066) @c FIXME already said
mini_ker.texi(,1067) @c At the begining of a run, the help file @file{Model.hlp} is generated for
mini_ker.texi(,1068) @c global checkiing of the model. In the example, it is:
mini_ker.texi(,1069) 
mini_ker.texi(,1070) @c @example
mini_ker.texi(,1071) @c ======================= set_Phi                                                                                                                                              
mini_ker.texi(,1072) @c     1 ff_interact      f_interact   eta_pray*eta_pred
mini_ker.texi(,1073) @c ======================= set_Eta                                           
mini_ker.texi(,1074) @c     1 eta_pray         deta_pray    apar*eta_pray-apar*ff_interact
mini_ker.texi(,1075) @c     2 eta_pred         deta_pred    -cpar*eta_pred+cpar*ff_interact
mini_ker.texi(,1076) @c @end example
mini_ker.texi(,1077) 
mini_ker.texi(,1078) 
mini_ker.texi(,1079) @node Graphics
mini_ker.texi(,1080) @subsection Doing graphics
mini_ker.texi(,1081) 
mini_ker.texi(,1082) @cindex graphics
mini_ker.texi(,1083) @cindex graphics with @command{gnuplot}
mini_ker.texi(,1084) @cindex graphics with @command{PAW}
mini_ker.texi(,1085) 
mini_ker.texi(,1086) @c The format of the @samp{.data} files are coherent with GNU graphics, that is
mini_ker.texi(,1087) @c the data are simply separated with spaces. 
mini_ker.texi(,1088) Since the data are simply separated with spaces, and comment lines 
mini_ker.texi(,1089) begin with @samp{#}, the 
mini_ker.texi(,1090) files can be vizualised with many programs. 
mini_ker.texi(,1091) With @command{gnuplot}, for example, to plot @code{eta(@var{n})}, 
mini_ker.texi(,1092) the @command{gnuplot} statement could be:
mini_ker.texi(,1093) 
mini_ker.texi(,1094) @example
mini_ker.texi(,1095) plot "res.data" using 1:(@var{n}+1)
mini_ker.texi(,1096) @end example
mini_ker.texi(,1097) 
mini_ker.texi(,1098) The similar one for @code{ff(@var{n})}:
mini_ker.texi(,1099) @example
mini_ker.texi(,1100) plot "tr.data" using 1:(@var{n}+1)
mini_ker.texi(,1101) @end example
mini_ker.texi(,1102) 
mini_ker.texi(,1103) For people using @command{PAW}, the CERN graphical computer code, 
mini_ker.texi(Minik,1104) Miniker prepares
mini_ker.texi(,1105) kumacs that allow to read process the @samp{.data} files in the form of 
mini_ker.texi(,1106) @emph{n-tuples} (see the @cite{PAW manual} for more information). 
mini_ker.texi(,1107) In that cas, the flag @code{sel paw} has to be gievn in the @file{selsequ.kumac}.
mini_ker.texi(,1108) The generated  n-tuples are ready to use only
mini_ker.texi(,1109) for vector dimension of at most 10 (including the variable @code{time}).
mini_ker.texi(,1110) These kumacs are overwritten each time the model is run. Usaually, gnuplot has
mini_ker.texi(,1111) to be preferred, but when using surfaces and histograms, PAW is better.
mini_ker.texi(,1112) The @file{gains.f} (and @file{go.xqt}  is provided as an example in the 
mini_ker.texi(Minik,1113) Miniker files.
mini_ker.texi(,1114) 
mini_ker.texi(,1115) @node Controlling the run
mini_ker.texi(,1116) @section Controlling the run
mini_ker.texi(,1117) 
mini_ker.texi(,1118) @cindex controlling the run
mini_ker.texi(,1119) 
mini_ker.texi(,1120) It is possible to add code that will be executed at the end of each time
mini_ker.texi(,1121) step. It is also possible to specify which time step leads to a printout on
mini_ker.texi(,1122) standard output. For maximal control, the code running te model may be 
mini_ker.texi(,1123) turned into a subroutine to be called from another fortran (or C) 
mini_ker.texi(,1124) program, this possibility is covered in @ref{Calling the model code}.
mini_ker.texi(,1125) 
mini_ker.texi(,1126) @menu
mini_ker.texi(,1127) * End of time step::
mini_ker.texi(,1128) * Controlling the printout and data output::
mini_ker.texi(,1129) @end menu
mini_ker.texi(,1130) 
mini_ker.texi(,1131) @node End of time step
mini_ker.texi(,1132) @subsection Executing code at the end of each time step
mini_ker.texi(,1133) 
mini_ker.texi(,1134) @cindex @file{zsteer}
mini_ker.texi(,1135) @cindex @file{zsteer.inc}
mini_ker.texi(,1136) 
mini_ker.texi(,1137) The code in the sequence @file{zsteer} is executed at the end of each time
mini_ker.texi(,1138) step. It is possible to change the time step length (variable @code{dt})
mini_ker.texi(,1139) verify that the non linearity are not too big, or perform 
mini_ker.texi(,1140) discontinuous modifications of the states. One available variable @code{res}
mini_ker.texi(,1141) might be usefull for time step monitoring. At the end of the time step,
mini_ker.texi(,1142) as soon as @math{\varphi} has been computed, a numerical test is applied
mini_ker.texi(,1143) on a pseudo relative quadratic residual between 
mini_ker.texi(,1144) @math{\varphi=f(\eta(t-dt)+d\varphi} (@code{ ffl}), where @math{d\varphi}
mini_ker.texi(,1145) is given by the system resolution in @code{ker},and
mini_ker.texi(,1146) @math{\varphi=f(\eta),\varphi)},  Fortran variable (@code{ff}):
mini_ker.texi(,1147) 
mini_ker.texi(,1148) @verbatim
mini_ker.texi(,1149) ! ========================================================
mini_ker.texi(,1150) ! test linearite ffl - ff
mini_ker.texi(,1151) ! ========================================================
mini_ker.texi(,1152) if (istep.gt.1)
mini_ker.texi(,1153) < res=0.; <io=1,m; res = res +(ffl(io)-ff(io))**2/max(one,ff(io)*ff(io)); >;
mini_ker.texi(,1154)   if (res .gt. TOL_FFL)
mini_ker.texi(,1155)   < print*,'*** pb linearite : res > TOL_FFL a istep',istep,res,' > ',TOL_FFL;
mini_ker.texi(,1156)     do io=1,m < z_pr: io,ff(io),ff(io)-ffl(io); >;
mini_ker.texi(,1157)   >;
mini_ker.texi(,1158) >;
mini_ker.texi(,1159) @end verbatim
mini_ker.texi(,1160) 
mini_ker.texi(,1161) This test hence applies only for non linearities in tranfer models. Nevertheless,
mini_ker.texi(,1162) @code{res} might be usefull to monitor the time step @code{dt} in @code{ZSTEER}
mini_ker.texi(,1163) and eventually go backward one step (@code{goto :ReDoStep:}).
mini_ker.texi(,1164) This can more appropriatly be coded in the (empty in default case) 
mini_ker.texi(,1165) sequence @code{zstep}, inserted just before time-advancing
mini_ker.texi(,1166) states and @code{time} variables in @file{principal}.
mini_ker.texi(,1167) @vindex ffl(.)
mini_ker.texi(,1168) @cindex @code{ffl} (linearity test)
mini_ker.texi(,1169) @cindex linearity test
mini_ker.texi(,1170) 
mini_ker.texi(,1171) It is also possible to fix the value of the criterium @code{TOL_FFL} in
mini_ker.texi(,1172) @file{zinit} different from its default value of @math{10^{-3}} --
mini_ker.texi(,1173) independent of the Fortran precision.
mini_ker.texi(,1174) 
mini_ker.texi(,1175) 
mini_ker.texi(,1176) Many other variables are available, including
mini_ker.texi(,1177) @vtable @code
mini_ker.texi(,1178) @item istep
mini_ker.texi(,1179) The step number;
mini_ker.texi(,1180) @item couplage(.)
mini_ker.texi(,1181) The @acronym{TEF} coupling matrix between transfers;
mini_ker.texi(,1182) @item H
mini_ker.texi(,1183) The Jacobian matrix corresponding with:
mini_ker.texi(,1184) @c \varphi(t) &= f(\eta(t),\varphi(t))\cr
mini_ker.texi(,1185) @c \frac{\partial g(\eta(t),\varphi(t))}{\partial \eta(t)}
mini_ker.texi(,1191) g_1(eta,phi);
mini_ker.texi(,1193) @item Bb
mini_ker.texi(,1194) The Jacobian matrix corresponding with:
mini_ker.texi(,1200) g_2(eta,phi);
mini_ker.texi(,1202) @item Bt
mini_ker.texi(,1203) The Jacobian matrix corresponding with:
mini_ker.texi(,1209) f_1(eta,phi);
mini_ker.texi(,1211) @item D
mini_ker.texi(,1212) The Jacobian matrix corresponding with:
mini_ker.texi(,1218) f_2(eta,phi);
mini_ker.texi(,1220) 
mini_ker.texi(,1221) @item aspha
mini_ker.texi(,1222) The state advance matrix;
mini_ker.texi(,1223) @item dneta
mini_ker.texi(,1224) @itemx dphi
mini_ker.texi(,1225) the variable increments;
mini_ker.texi(,1226) @end vtable
mini_ker.texi(,1227) One should be aware of that the linearity test concerns the preceding step. 
mini_ker.texi(,1228) We have yet no example of managing the time-step.
mini_ker.texi(,1229) 
mini_ker.texi(,1230) @page
mini_ker.texi(,1231) @node Controlling the printout and data output
mini_ker.texi(,1232) @subsection Controlling the printout and data output
mini_ker.texi(,1233) 
mini_ker.texi(,1234) @cindex printing
mini_ker.texi(,1235) @vindex zprint
mini_ker.texi(,1236) @vindex modzprint
mini_ker.texi(,1237) 
mini_ker.texi(,1238) The printout on standard output is performed if the variable @code{zprint} 
mini_ker.texi(,1239) of type @code{logical} is true. Therefore it is possible to control this
mini_ker.texi(,1240) printout by setting @code{zprint} false or true. For example the following 
mini_ker.texi(,1241) code, in sequence @file{zsteer}, triggers printing for every 
mini_ker.texi(,1242) @code{modzprint} time step and the two following time steps:
mini_ker.texi(,1243) 
mini_ker.texi(,1244) @example
mini_ker.texi(,1245) ZPRINT = mod(istep+1,modzprint).eq.0;
mini_ker.texi(,1246) Zprint = zprint .or. mod(istep+1,modzprint).eq.1;
mini_ker.texi(,1247) Zprint = zprint .or. mod(istep+1,modzprint).eq.2;
mini_ker.texi(,1248) @end example
mini_ker.texi(,1249) 
mini_ker.texi(,1250) The data output to @file{.data} files described in @ref{Simulation and output,,
mini_ker.texi(,1251) Running a simulation and using the output} is performed if the
mini_ker.texi(,1252) @code{logical} variable @code{zout} is true. For example the following
mini_ker.texi(,1253) code, in @file{zsteer}, triggers output to @file{.data} files every 
mini_ker.texi(,1254) @code{modzout} step.
mini_ker.texi(,1255) 
mini_ker.texi(,1256) @example
mini_ker.texi(,1257) Zout = mod(istep,modzout).eq.0;
mini_ker.texi(,1258) @end example
mini_ker.texi(,1259) 
mini_ker.texi(,1260) @node Advanced programming
mini_ker.texi(Minik,1261) @chapter Advanced Miniker programming
mini_ker.texi(,1262) 
mini_ker.texi(,1263) @menu
mini_ker.texi(,1264) * Selecting features::
mini_ker.texi(,1265) * Calling the model code::
mini_ker.texi(,1266) * 1D gridded model::
mini_ker.texi(,1267) * Double precision::
mini_ker.texi(,1268) * Partial Derivatives::
mini_ker.texi(,1269) * Rule of programming non continuous models::
mini_ker.texi(,1270) * Parameters::
mini_ker.texi(,1271) * Observations and data::
mini_ker.texi(,1272) * Explicit model size::
mini_ker.texi(,1273) * Programming with cmz directives::
mini_ker.texi(,1274) @end menu
mini_ker.texi(,1275) 
mini_ker.texi(,1276) @node Selecting features
mini_ker.texi(,1277) @section Overview of additional features setting
mini_ker.texi(,1278) 
mini_ker.texi(,1279) @cindex feature setting
mini_ker.texi(,1280) @cindex select flag
mini_ker.texi(,1281) @cindex logical flags
mini_ker.texi(,1282) @cindex @file{selseq.kumac}
mini_ker.texi(,1283) 
mini_ker.texi(,1284) It is possible to enable some features by selecting which code should 
mini_ker.texi(,1285) be part of the principal program. Each of these optionnal features are 
mini_ker.texi(,1286) associated with a @dfn{select flag}. 
mini_ker.texi(,1287) For example 
mini_ker.texi(,1288) @c the optimisation with minuit is associated with the select
mini_ker.texi(,1289) @c flag @samp{minuik}, 
mini_ker.texi(,1290) double precision is used instead of simple precision with 
mini_ker.texi(,1291) the @samp{double} select flag,
mini_ker.texi(,1292) the model is a subroutine with the select flag @samp{monitor},
mini_ker.texi(,1293) the Kalman filter code is set with @samp{kalman} and the 1D gridded
mini_ker.texi(,1294) model capabilities are associated with @samp{grid1d}. 
mini_ker.texi(,1295) @c Currently it is only possible 
mini_ker.texi(,1296) @c to select features in cmz. 
mini_ker.texi(,1297) To select a given feature the cmz statement @code{sel @var{select_flag}} should
mini_ker.texi(,1298) be written down in the @file{selseq.kumac} found in the model directory.
mini_ker.texi(,1299) With make either the corresponding variable should be set to 1 or it
mini_ker.texi(,1300) should be added to the @code{SEL} make variable, depending on the feature.
mini_ker.texi(,1301) 
mini_ker.texi(,1302) Other features don't need different or additional code to be used. 
mini_ker.texi(,1303) Most of the features are enabled by setting specific logical variables to
mini_ker.texi(,1304) @samp{.true.}. This is the case for
mini_ker.texi(,1305) @code{zback} for the adjoint model, @code{zcommand} if the command is in a file
mini_ker.texi(,1306) and @code{zlaw} if it is a function and @code{zkalman} for the Kalman filter.
mini_ker.texi(,1307) These select and logical flags are described in the corresponding sections.
mini_ker.texi(,1308) 
mini_ker.texi(,1309) In cmz an alternative of writing select flags to @file{selseq.kumac} is to
mini_ker.texi(,1310) drive the compilation with @code{smod @var{sel_flag}}. In that case the
mini_ker.texi(,1311) @var{sel_flag} is selected and the files and executable goes to a directory
mini_ker.texi(,1312) named @file{sel_flag}. 
mini_ker.texi(,1313) 
mini_ker.texi(,1314) The select flags are taken into account during cmz directives preprocessing.
mini_ker.texi(,1315) Therefore you have the possibility to use these flags to conditionnaly 
mini_ker.texi(,1316) include pieces of code. In most cases you don't need to include code conditionally 
mini_ker.texi(,1317) yourself though, but if you want to, this is covered in 
mini_ker.texi(,1318) @ref{Programming with cmz directives}.
mini_ker.texi(,1319) 
mini_ker.texi(,1320) @node Calling the model code
mini_ker.texi(,1321) @section Calling the model code
mini_ker.texi(,1322) 
mini_ker.texi(,1323) When the model code is a subroutine, it can be called from another fortran
mini_ker.texi(,1324) program unit (or another program), and the model will be 
mini_ker.texi(,1325) run each time the subroutine is called.
mini_ker.texi(,1326) This technique could be used, for example to perform optimization 
mini_ker.texi(,1327) (@pxref{Adjoint model and optimisation,,Adjoint model and optimisation 
mini_ker.texi(Minik,1328) with Miniker}), or to run the model with different parameters.
mini_ker.texi(,1329) 
mini_ker.texi(,1330) @menu
mini_ker.texi(,1331) * Turning the model into a subroutine::
mini_ker.texi(,1332) * The model subroutine::
mini_ker.texi(,1333) @end menu
mini_ker.texi(,1334) 
mini_ker.texi(,1335) @node Turning the model into a subroutine
mini_ker.texi(,1336) @subsection Turning the model into a subroutine
mini_ker.texi(,1337) 
mini_ker.texi(,1338) @c This feature is allready enabled with @command{make}, and to 
mini_ker.texi(,1339) @c override the default program a file called @file{monitor.f} has to be created 
mini_ker.texi(,1340) @c in the working directory. The default program simple calls the model
mini_ker.texi(,1341) @c subroutine.
mini_ker.texi(,1342) 
mini_ker.texi(,1343) With cmz, one has to do a 
mini_ker.texi(,1344) @example
mini_ker.texi(,1345) sel monitor
mini_ker.texi(,1346) @end example
mini_ker.texi(,1347) in the @file{selseq.kumac} file and create the KEEP that call the 
mini_ker.texi(,1348) model code. @xref{Selecting features, Overview of additional features 
mini_ker.texi(,1349) setting}.
mini_ker.texi(,1350) 
mini_ker.texi(,1351) With make @samp{monitor} should be added to the @code{SEL} variable in
mini_ker.texi(,1352) the @file{Makefile}, for example:
mini_ker.texi(,1353) 
mini_ker.texi(,1354) @example
mini_ker.texi(,1355) SEL = monitor
mini_ker.texi(,1356) @end example
mini_ker.texi(,1357) 
mini_ker.texi(,1358) A file that call the principal subroutine should also be written, using
mini_ker.texi(,1359) the prefered language of the user. The additional object files should
mini_ker.texi(Minik,1360) then be linked with the Miniker objects. To that aim they may be added
mini_ker.texi(,1361) to the @code{miniker_user_objects} variable.
mini_ker.texi(,1362) 
mini_ker.texi(,1363) @node The model subroutine
mini_ker.texi(,1364) @subsection Calling the model subroutine
mini_ker.texi(,1365) 
mini_ker.texi(,1366) The model subroutine is called @samp{principal} and is called with the 
mini_ker.texi(,1367) following arguments:
mini_ker.texi(,1368) 
mini_ker.texi(,1369) @deffn Subroutine principal (Cost, ncall, integer_flag, file_suffix, info, idxerror)
mini_ker.texi(,1370) Where @var{Cost} is a real number, @code{real} or @code{double precision}, 
mini_ker.texi(,1371) and is set by the @code{principal}
mini_ker.texi(,1372) subroutine. It holds the value of the cost function if such function has been
mini_ker.texi(,1373) defined (the use and setting of a cost function is covered later, 
mini_ker.texi(,1374) see @ref{Cost function coding and adjoint modeling}). 
mini_ker.texi(,1375) @var{ncall} is an integer which corresponds with the number of 
mini_ker.texi(,1376) call to @code{principal} done so far, it should be initialized to 0 and 
mini_ker.texi(,1377) its value should not be changed, as it is changed in the @code{principal}
mini_ker.texi(,1378) subroutine.
mini_ker.texi(,1379) @var{integer_flag} is an integer that can be set by the user to be accessed 
mini_ker.texi(,1380) in the @code{principal} subroutine. For example its value could be used to
mini_ker.texi(,1381) set some flags in the @file{zinit} sequence.
mini_ker.texi(,1382) @var{file_suffix} is a character string, that is suffixed to the output files
mini_ker.texi(,1383) names instead of @samp{.data}. If the first character is the null character 
mini_ker.texi(,1384) @samp{char(0)}, the default suffix, @samp{.data} is appended.
mini_ker.texi(,1385) @var{info} and @var{idxerror} are integer used for error reporting.
mini_ker.texi(,1386) @var{idxerror} value is 0 if there was no error. It is negative for
mini_ker.texi(,1387) an alert, positive for a very serious error. The precise value determines
mini_ker.texi(,1388) where the error occured.
mini_ker.texi(,1389) @var{info} is an integer holding more precise information about the
mini_ker.texi(,1390) error. It is usually the information value from lapack.
mini_ker.texi(,1391) The precise meaning of these error codes is in @ref{tab:error_codes}.
mini_ker.texi(,1392) @end deffn
mini_ker.texi(,1393) 
mini_ker.texi(,1394) @float table, tab:error_codes 
mini_ker.texi(,1395) @multitable {kalman analysis state matrix advance in phase space, @math{(I-D)} inversion} {inversion} {@code{idxerror}}
mini_ker.texi(,1396) @headitem Source of error or warning @tab @code{info} @tab @code{idxerror}
mini_ker.texi(,1397) @c @item @code{} @tab @file{.data} @tab  @tab
mini_ker.texi(,1398) @item state matrix inversion in ker @tab inversion @tab 1
mini_ker.texi(,1399) @item time advance system resolution in ker  @tab system @tab 2
mini_ker.texi(,1400) @item transfer propagator, @math{(I-D)} inversion @tab inversion @tab 3
mini_ker.texi(,1401) @item kalman analysis state matrix advance in phase space, @math{(I-D)} inversion @tab inversion @tab 21
mini_ker.texi(,1402) @item kalman analysis variance covariance matrix non positive @tab Choleski @tab 22
mini_ker.texi(,1403) @item kalman analysis error matrix inversion @tab inversion @tab 23
mini_ker.texi(,1404) @item kalman error matrix advance @tab system @tab 24
mini_ker.texi(,1405) @item transfers determination linearity problem for transfers @tab  @tab -1
mini_ker.texi(,1406) @item transerts determination Newton D_loop does not converge @tab  @tab -2
mini_ker.texi(,1407) @end multitable
mini_ker.texi(,1408) @caption{Meaning of error codes returned by principal.}
mini_ker.texi(,1409) @end float
mini_ker.texi(,1410) 
mini_ker.texi(,1411) In general more information than the provided arguments has to be passed 
mini_ker.texi(,1412) to the @code{principal} subroutine, in that case a @code{common} block,
mini_ker.texi(,1413) to be written in the @file{zinit} sequence can be used.
mini_ker.texi(,1414) 
mini_ker.texi(,1415) @page
mini_ker.texi(,1416) @node 1D gridded model
mini_ker.texi(,1417) @section Describing 1D gridded model
mini_ker.texi(,1418) 
mini_ker.texi(,1419) Specific macros have been built that allow generic description of 1D gridded models.
mini_ker.texi(,1420) Because of the necessity of defining left and right limiting conditions, the models
mini_ker.texi(,1421) are partitionned in three groups for cell and transfer components. In the following example,
mini_ker.texi(,1422) a chain of masselottes linked by springs and dumps is bounded to a wall on the left,
mini_ker.texi(,1423) and open at right. The @acronym{TEF} formulation of the problem is written in the phase space (position-shift, velocity)
mini_ker.texi(,1424) for node @math{k}, with bounding conditions:
mini_ker.texi(,1470) 
mini_ker.texi(,1471) States:@*
mini_ker.texi(,1472) @noindent @math{d position(t,k)/d t = velocity(t,k)@* 
mini_ker.texi(,1473) d velocity (t,k)/d t =(spring(t,k) - spring(t,k+1)+ dump(t,k)- dump(t,k+1))/m_k}
mini_ker.texi(,1474) 
mini_ker.texi(,1475) Transfers:@*
mini_ker.texi(,1476) @noindent @math{spring(t,k) = -k_k (position(t,k)- position(t,k-1))@*
mini_ker.texi(,1477) dump(k,t) &= -d_k (velocity(t,k)- velocity(t,k-1))}
mini_ker.texi(,1478) 
mini_ker.texi(,1479) Bounding conditions:@*
mini_ker.texi(,1480) @noindent @math{position(t,0) = 0@*
mini_ker.texi(,1481) velocity(t,0) = 0@*
mini_ker.texi(,1482) spring(t,N+1) = 0@*
mini_ker.texi(,1483) dump(t,N+1) =0}
mini_ker.texi(,1484) 
mini_ker.texi(,1487) 
mini_ker.texi(,1488) @cindex down node
mini_ker.texi(,1489) @cindex up node
mini_ker.texi(,1490) 
mini_ker.texi(,1491) where @math{m_k} is the mass of node @math{k}, @math{r_k} and @math{d_k} 
mini_ker.texi(,1492) the rigidity of springs and dumping coefficients. There are @math{N} nodes
mini_ker.texi(,1493) in the grid, from 1 to @math{N}, and two nodes outside of the grid,
mini_ker.texi(,1494) a limiting node 0, and a limiting node @math{N+1}. The limiting node
mini_ker.texi(,1495) corresponding with node 0 is called the @dfn{down} node, while the limiting 
mini_ker.texi(,1496) node corresponding with node @math{N+1} is called the @dfn{up} node.
mini_ker.texi(,1497) Other models not part of the 1D grid may be added if any.
mini_ker.texi(,1498) 
mini_ker.texi(,1499) To enable 1D gridded models, one should set the select flag @samp{grid1d}.
mini_ker.texi(,1500) In cmz it is achieved setting the select flag in
mini_ker.texi(,1501) @file{selseq.kumac}, like
mini_ker.texi(,1502) 
mini_ker.texi(,1503) @example
mini_ker.texi(,1504) sel grid1d
mini_ker.texi(,1505) @end example
mini_ker.texi(,1506) 
mini_ker.texi(,1507) With make, the @code{SEL} variable should contain @code{grid1d}. For example
mini_ker.texi(,1508) to select @code{grid1d} and @code{monitor}, it could be
mini_ker.texi(,1509) @example
mini_ker.texi(,1510) SEL = grid1d,monitor
mini_ker.texi(,1511) @end example
mini_ker.texi(,1512) 
mini_ker.texi(,1513) 
mini_ker.texi(,1514) @menu
mini_ker.texi(,1515) * 1D gridded Model size::
mini_ker.texi(,1516) * 1D gridded model code::
mini_ker.texi(,1517) @end menu
mini_ker.texi(,1518) 
mini_ker.texi(,1519) @node 1D gridded Model size
mini_ker.texi(,1520) @subsection Setting dimensions for 1D gridded model
mini_ker.texi(,1521) 
mini_ker.texi(,1522) @c FIXME grid1d sans dimetaphi?
mini_ker.texi(,1523) In that case the number of nodes, the number of states and tranferts 
mini_ker.texi(,1524) per node, and the number of limiting transfers and states are required.
mini_ker.texi(,1525) These dimensions has to be entered in the
mini_ker.texi(,1526) @file{DimEtaPhi} sequence. The parameters for cells are
mini_ker.texi(,1527) @vtable @code
mini_ker.texi(,1528) @item n_node
mini_ker.texi(,1529) Number of cell nodes in the 1D grid.
mini_ker.texi(,1530) @item n_dwn
mini_ker.texi(,1531) Number of limiting cells with index -1, @i{i.e.} number of cells in the
mini_ker.texi(,1532) limiting down node.
mini_ker.texi(,1533) @item n_up
mini_ker.texi(,1534) Number of limiting cells with index +1, @i{i.e.} number of cells in the
mini_ker.texi(,1535) limiting up node.
mini_ker.texi(,1536) @item n_mult
mini_ker.texi(,1537) Number of cells in each node (multiplicity).
mini_ker.texi(,1538) @end vtable
mini_ker.texi(,1539) 
mini_ker.texi(,1540) @vindex m_node
mini_ker.texi(,1541) @vindex m_dwn
mini_ker.texi(,1542) @vindex m_up
mini_ker.texi(,1543) @vindex m_mult
mini_ker.texi(,1544) The parameters for transfers, are similarly 
mini_ker.texi(,1545) @code{m_node}, @code{m_dwn}, @code{m_up}, @code{m_mult}.
mini_ker.texi(,1546) The layout of their declaration should be respected as 
mini_ker.texi(,1547) the precompiler matches the line. Also this procedure is tedious, it
mini_ker.texi(,1548) should be selected for debuging processes (use the flag @code{sel dimetaphi}
mini_ker.texi(,1549) in ``selsequ.kumac''. Otherwise, the dimensioning sequence will be automaticaly
mini_ker.texi(,1550) generated, which is smart but can lead to diffculty in interpreting syntax errors.
mini_ker.texi(,1551) Once a model is correctly entred, turn off the sel flag and further modifications
mini_ker.texi(,1552) will automatically generate the proper dimensions. The correctness of dimensionning
mini_ker.texi(,1553) should nevertheless always be checked in @code{principal.f}, where you can also
mini_ker.texi(,1554) check that null valued parameters as @code{lp, mobs, nxp} will suppress parts
mini_ker.texi(,1555) of the code - this is signaled as Fortran comment cards.
mini_ker.texi(,1556) 
mini_ker.texi(,1557) In our example, there are three grids of cell and
mini_ker.texi(,1558) transfer variables (@code{n_node=m_node=3}). 
mini_ker.texi(,1559) There are two cells and two transfers in each node 
mini_ker.texi(,1560) (@code{n_mult=2} and @code{m_mult=2}). There is no limiting condition 
mini_ker.texi(,1561) for the states in the down node therefore @code{n_up=0}. 
mini_ker.texi(,1562) There is no transfer for the first limiting node, and 
mini_ker.texi(,1563) therefore @code{m_dwn=0}.
mini_ker.texi(,1564) There are two states in the limiting node 0, the down node, 
mini_ker.texi(,1565) @code{n_dwn=2}, and two transfers in the limiting last node the node up, 
mini_ker.texi(,1566) and @code{m_up=2}:
mini_ker.texi(,1567) 
mini_ker.texi(,1568) @example 
mini_ker.texi(,1569) ! ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
mini_ker.texi(,1570) ! nodes parameters, and Limiting Conditions (Low and High)
mini_ker.texi(,1571) ! ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
mini_ker.texi(,1572)       parameter (n_node=3,n_dwn=2,n_up=0,n_mult=2);
mini_ker.texi(,1573)       parameter (m_node=3,m_dwn=0,m_up=2,m_mult=2);
mini_ker.texi(,1574) ! ________________________________________________________
mini_ker.texi(,1575) @end example
mini_ker.texi(,1576) 
mini_ker.texi(,1587) 
mini_ker.texi(,1588) @node 1D gridded model code
mini_ker.texi(,1589) @subsection 1D gridded Model coding
mini_ker.texi(,1590) 
mini_ker.texi(,1591) The model code and parameters go in the @file{zinit} sequence.
mini_ker.texi(,1592) 
mini_ker.texi(,1593) @subsubheading Parameters
mini_ker.texi(,1594) 
mini_ker.texi(Minik,1595) A value for the Miniker parameters and the model parameters should be given in
mini_ker.texi(,1596) @file{zinit}, in our example we have
mini_ker.texi(,1597) 
mini_ker.texi(,1598) @example
mini_ker.texi(,1599) !%%%%%%%%%%%%%%%%%%%%%%
mini_ker.texi(,1600) ! Parameters
mini_ker.texi(,1601) !%%%%%%%%%%%%%%%%%%%%%%
mini_ker.texi(,1602) real rk(n_node),rd(n_node),rmassm1(n_node);
mini_ker.texi(,1603) 
mini_ker.texi(,1604) data rk/n_node*1./;
mini_ker.texi(,1605) data rd/n_node*0.1/;
mini_ker.texi(,1606) data rmassm1/n_node*1./;
mini_ker.texi(,1607)      dt=.01;
mini_ker.texi(,1608)      nstep=5 000;
mini_ker.texi(,1609)      modzprint = 1000;
mini_ker.texi(,1610)      time=0.;
mini_ker.texi(,1611) @end example
mini_ker.texi(,1612) 
mini_ker.texi(,1613) @subsubheading Limiting conditions
mini_ker.texi(,1614) 
mini_ker.texi(,1615) @cindex limiting conditions
mini_ker.texi(,1616) 
mini_ker.texi(,1617) @c The limiting states and transfer variables and the corresponding equations are
mini_ker.texi(,1618) @c declared using
mini_ker.texi(,1619) @c the symbolic model description 
mini_ker.texi(,1620) @c (@pxref{Symbolic model description}).
mini_ker.texi(,1621) There are four mortran blocks for @code{node} and @code{up} and @code{down}, both
mini_ker.texi(,1622) for states and transfers:
mini_ker.texi(,1623) 
mini_ker.texi(,1624) @findex set_dwn_eta
mini_ker.texi(,1625) @findex set_dwn_phi
mini_ker.texi(,1626) @findex set_up_eta
mini_ker.texi(,1627) @findex set_up_phi
mini_ker.texi(,1628) 
mini_ker.texi(,1629) @table @code
mini_ker.texi(,1630) @item set_dwn_eta
mini_ker.texi(,1631) down node cells
mini_ker.texi(,1632) @item set_up_eta
mini_ker.texi(,1633) up node cells
mini_ker.texi(,1634) @item set_dwn_phi
mini_ker.texi(,1635) down node transfers
mini_ker.texi(,1636) @item set_up_phi
mini_ker.texi(,1637) up node transfers
mini_ker.texi(,1638) @end table
mini_ker.texi(,1639) 
mini_ker.texi(,1640) The following scheme illustrates the example:
mini_ker.texi(,1641) @smallexample
mini_ker.texi(,1642) !%%%%%%%%%%%%%%%%%%%%%%%%%%================================================
mini_ker.texi(,1643) ! Maillage convention inode
mini_ker.texi(,1644) !%%%%%%%%%%%%%%%%%%%%%%%%%%                                 Open ended
mini_ker.texi(,1645) !(2 Down    Phi    Eta                         (n_node)
mini_ker.texi(,1646) ! Eta)  \|       .-----.       .-----.          .-----.        /
mini_ker.texi(,1647) ! wall  \|-\/\/\-|     |-\/\/\-|     |  . . .  -|     |-\/\/\- |dummy
mini_ker.texi(,1648) !  pos  \|--***--|  1  |--***--|  2  |  . . .  -|  n  |--***-- |Phis
mini_ker.texi(,1649) ! speed \|   1   |_____|   2   |_____|      n   |_____|  n+1   \(2 Up Phi)
mini_ker.texi(,1650) !
mini_ker.texi(,1651) @end smallexample
mini_ker.texi(,1652) 
mini_ker.texi(,1653) Two states are associated with the down node, they correspond to the position
mini_ker.texi(,1654) and speed of the wall. As the wall don't move these states are initialized to
mini_ker.texi(,1655) be 0, and the cells are stationnary cells, therefore these values remain 0.
mini_ker.texi(,1656) 
mini_ker.texi(,1657) @example
mini_ker.texi(,1658) ! Down cells (wall)
mini_ker.texi(,1659) ! -----------------
mini_ker.texi(,1660) eta_pos_wall = 0; eta_speed_wall = 0.;
mini_ker.texi(,1661) 
mini_ker.texi(,1662) set_dwn_eta
mini_ker.texi(,1663) < var: eta_pos_wall,  fun: deta_pos_wall  = 0.;
mini_ker.texi(,1664)   var: eta_speed_wall, fun: deta_speed_wall= 0.;
mini_ker.texi(,1665) >;
mini_ker.texi(,1666) @end example
mini_ker.texi(,1667) 
mini_ker.texi(,1668) There are 2 limiting transfers in the up node. They correspond with an open
mini_ker.texi(,1669) end and are therefore set to 0.
mini_ker.texi(,1670) 
mini_ker.texi(,1671) @example
mini_ker.texi(,1672) ! limiting Transfers : dummy ones
mini_ker.texi(,1673) ! -------------------------------
mini_ker.texi(,1674) set_Up_Phi
mini_ker.texi(,1675) < var:ff_dummy_1, fun: f_dummy_1=0.;
mini_ker.texi(,1676)   var:ff_dummy_2, fun: f_dummy_2=0.;
mini_ker.texi(,1677) >;
mini_ker.texi(,1678) @end example
mini_ker.texi(,1679) 
mini_ker.texi(,1680) @subsubheading Starting points
mini_ker.texi(,1681) 
mini_ker.texi(,1682) The cell node state values are initialized. They are in an array 
mini_ker.texi(,1683) indexed by the @code{inode} variable. In the example the variable 
mini_ker.texi(,1684) corresponding with position is @code{eta_move} and the variable corresponding
mini_ker.texi(,1685) with speed is @code{eta_speed}. Their initial values are set with the 
mini_ker.texi(,1686) following mortran code
mini_ker.texi(,1687) 
mini_ker.texi(,1688) @example
mini_ker.texi(,1689) !---------------
mini_ker.texi(,1690) ! Initialisation
mini_ker.texi(,1691) !---------------
mini_ker.texi(,1692) ;
mini_ker.texi(,1693) do inode=1,n_node <eta_move(inode)=0.01; eta_speed(inode)=0.0;>;
mini_ker.texi(,1694) @end example
mini_ker.texi(,1695) 
mini_ker.texi(,1696) If any transfer needs to be given a first-guess value, this is also done 
mini_ker.texi(,1697) using @code{inode} as the node index.
mini_ker.texi(,1698) 
mini_ker.texi(,1699) @subsubheading Grid node equations
mini_ker.texi(,1700) 
mini_ker.texi(,1701) @findex set_node_Phi
mini_ker.texi(,1702) @findex set_node_eta
mini_ker.texi(,1703) @cindex equations, grid
mini_ker.texi(,1704) 
mini_ker.texi(,1705) Each node is associated with an index @code{inode}. It allows to refer to the 
mini_ker.texi(,1706) preceding node, with @code{inode-1} and the following node @code{inode+1}.
mini_ker.texi(,1707) The node states are declared in @code{set_node_Eta} block and the transfers are
mini_ker.texi(,1708) in @code{set_node_Phi} blocks.
mini_ker.texi(,1709) 
mini_ker.texi(,1710) In the example, the cells are declared with
mini_ker.texi(,1711) 
mini_ker.texi(,1712) @example
mini_ker.texi(,1713) ! node cells
mini_ker.texi(,1714) ! ----------
mini_ker.texi(,1715) ;
mini_ker.texi(,1716) set_node_Eta
mini_ker.texi(,1717) < var: eta_move(inode),  fun: deta_move(inode) = eta_speed(inode);
mini_ker.texi(,1718)   var: eta_speed(inode),
mini_ker.texi(,1719)   fun: deta_speed(inode) = rmassm1(inode)
mini_ker.texi(,1720)                              *( - ff_spring(inode+1) + ff_spring(inode)
mini_ker.texi(,1721)                                - ff_dump(inode+1)  + ff_dump(inode)
mini_ker.texi(,1722)                               );
mini_ker.texi(,1723) >;
mini_ker.texi(,1724) @end example
mini_ker.texi(,1725) Note that the @code{inode} is dummy in the @code{var:} definition and can as
mini_ker.texi(,1726) well be written as: @code{var: eta_move(.)}.
mini_ker.texi(,1727) 
mini_ker.texi(,1728) 
mini_ker.texi(,1729) The transfers are (@code{ff_spring} corresponds with springs and 
mini_ker.texi(,1730) @code{ff_dump} with dumps):
mini_ker.texi(,1731) 
mini_ker.texi(,1732) @example
mini_ker.texi(,1733) !%%%%%%%%%%%%%%%%%%%%%%
mini_ker.texi(,1734) ! Transfer definition
mini_ker.texi(,1735) !%%%%%%%%%%%%%%%%%%%%%%
mini_ker.texi(,1736) ! node transfers
mini_ker.texi(,1737) ! --------------
mini_ker.texi(,1738) ! convention de signe spring : comprime:= +
mini_ker.texi(,1739) set_node_Phi
mini_ker.texi(,1740) < var: ff_spring(.),
mini_ker.texi(,1741)   fun:
mini_ker.texi(,1742)    f_spring(inode)= -rk(inode)*(eta_move(inode) - eta_move(inode-1));
mini_ker.texi(,1743)   var: ff_dump(.),
mini_ker.texi(,1744)   fun:
mini_ker.texi(,1745)    f_dump(inode)  = -rd(inode)*(eta_speed(inode) - eta_speed(inode-1));
mini_ker.texi(,1746) >;
mini_ker.texi(,1747) @end example
mini_ker.texi(,1748) 
mini_ker.texi(,1749) The limiting states and transfers are associated with the states or transfers
mini_ker.texi(,1750) with index @code{inode+1} or @code{inode-1} appearing in node cell and 
mini_ker.texi(,1751) transfer equations (@code{inode-1} for down limiting conditions and 
mini_ker.texi(,1752) @code{inode+1} for up limiting conditions) in their order of appearance.
mini_ker.texi(,1753) In our example, in the @code{eta_speed} state node equation
mini_ker.texi(,1754) @code{ff_spring(inode+1)} appears before @code{ff_dump(inode+1)} and is
mini_ker.texi(,1755) therefore associated with @code{ff_dummy_1} while @code{ff_dump(inode+1)} is
mini_ker.texi(,1756) associated with the @code{ff_dummy_2} limiting transfer, as @code{ff_dummy_1}
mini_ker.texi(,1757) appears before @code{ff_dummy_2} in the limiting up transfers definitions.
mini_ker.texi(,1758) Verification of the grid index coherence should be eased with the following
mini_ker.texi(,1759) help printed in the listing header:
mini_ker.texi(,1760) 
mini_ker.texi(,1761) @example
mini_ker.texi(,1762) 
mini_ker.texi(,1763) 
mini_ker.texi(,1764) 
mini_ker.texi(,1765) 
mini_ker.texi(,1766)   --------------- Informing on Dwn Eta definition ---------------
mini_ker.texi(,1767)  Var-name,            Function-name, index in eta vector
mini_ker.texi(,1768)          eta_pos_wall        deta_pos_wall  1 [
mini_ker.texi(,1769)        eta_speed_wall      deta_speed_wall  2 [
mini_ker.texi(,1770) 
mini_ker.texi(,1771)   -------------- Informing on Eta Nodes definition --------------
mini_ker.texi(,1772)  Var-name,     Function, k2index of (inode: 0 [ 1,...n_node ] n_node+1)
mini_ker.texi(,1773)             eta_move           deta_move    1 [   3 ...   7 ]   9
mini_ker.texi(,1774)            eta_speed          deta_speed    2 [   4 ...   8 ]  10
mini_ker.texi(,1775) 
mini_ker.texi(,1776)   ---------------- Informing on Up  Phi  definition -------------
mini_ker.texi(,1777)  Var-name,             Function-name, index in ff vector
mini_ker.texi(,1778)           ff_dummy_1           f_dummy_1 ]    7
mini_ker.texi(,1779)           ff_dummy_2           f_dummy_2 ]    8
mini_ker.texi(,1780)          ff_move_sum          f_move_sum ]    9
mini_ker.texi(,1781)         ff_speed_sum         f_speed_sum ]   10
mini_ker.texi(,1782)   ----------------------------------------------------
mini_ker.texi(,1783) 
mini_ker.texi(,1784)  -------------- Informing on Phi Nodes definition ---------------
mini_ker.texi(,1785)  Var-name,     Function, k2index of (inode: 0 [ 1,...m_node ] m_node+1)
mini_ker.texi(,1786)            ff_spring            f_spring   -1 [   1 ...   5 ]   7
mini_ker.texi(,1787)              ff_dump              f_dump    0 [   2 ...   6 ]   8
mini_ker.texi(,1788)   ----------------------------------------------------
mini_ker.texi(,1789) @end example
mini_ker.texi(,1790) 
mini_ker.texi(,1791) All variable names and functions are free but has to be
mini_ker.texi(,1792) different.
mini_ker.texi(,1793) Any particular node-attached variable @math{k} is referred to as: @samp{(inode:k)},
mini_ker.texi(,1794) where @math{k} has to be a Fortran expression allowed in arguments. The symbol 
mini_ker.texi(,1795) @samp{inode} is
mini_ker.texi(,1796) reserved. As usual other Fortran instructions can be written within the
mini_ker.texi(,1797) Mortran block @samp{< >} of each @code{set_} block.
mini_ker.texi(,1798) 
mini_ker.texi(,1799) @node Double precision
mini_ker.texi(,1800) @section Double precision
mini_ker.texi(,1801) 
mini_ker.texi(,1802) The default for real variables is the @code{real} Fortran type. It is possible to
mini_ker.texi(,1803) use double precision instead. In that case all the occurences of @samp{real@ }
mini_ker.texi(,1804) in mortran code is substituted with @samp{double precision@ } at 
mini_ker.texi(,1805) precompilation stage,
mini_ker.texi(,1806) and the Lapack subroutine names are replaced by the double precision names.
mini_ker.texi(,1807) Eventual users'declaration of @code{complex@ } Fortran variables is also 
mini_ker.texi(,1808) changed to @code{double complex@ }.
mini_ker.texi(,1809) 
mini_ker.texi(,1810) This feature is turned on by @code{sel double} in @file{selseq.kumac} with cmz
mini_ker.texi(,1811) and @code{double = 1} in the @file{Makefile} with make.
mini_ker.texi(,1812) 
mini_ker.texi(,1813) In order for the model to run as well in double as in simple precision, 
mini_ker.texi(,1814) some care should be taken to use the generic intrinsic functions, like 
mini_ker.texi(,1815) @code{sin} and not @code{dsin}. No numerical constant should be passed directly 
mini_ker.texi(,1816) to subroutines or functions, but instead a variable with the right type should
mini_ker.texi(,1817) be used to hold the constant value, taking advantage of the implicit casts 
mini_ker.texi(,1818) to the variable type.
mini_ker.texi(,1819) 
mini_ker.texi(,1820) @node Partial Derivatives
mini_ker.texi(,1821) @section  Partial Derivatives
mini_ker.texi(,1822) 
mini_ker.texi(,1823) The partial derivative rules are included in a @code{Mortran} macro series
mini_ker.texi(Minik,1824) in @file{Derive_mac} of Miniker files. When using an anusual function,
mini_ker.texi(,1825) one should verify that the corersponding rules are in that file.
mini_ker.texi(,1826) It is easy to understand and add new rules in analogy with the already existing ones.
mini_ker.texi(,1827) 
mini_ker.texi(,1828) For instance, suppose one wants to use the intrinsic Fortran function @code{ abs()}.
mini_ker.texi(,1829) Its derivatives uses the other function @code{sign()} this way:
mini_ker.texi(,1830) 
mini_ker.texi(,1831) @example
mini_ker.texi(,1832)  &'(ABS(#))(/#)' = '((#1)(/#2)*SIGN(1.,#1))'
mini_ker.texi(,1833) @end example
mini_ker.texi(,1834) 
mini_ker.texi(,1835) In such cases when one is adding a new rule, it is important to use the generic function names
mini_ker.texi(Minik,1836) only (i.e. @code{sin} not @code{dsin}), because when compilating Miniker in the double precision
mini_ker.texi(,1837) version, or complex version, the generic names will correctly handle the different variable
mini_ker.texi(,1838) types - which is not the case when coding with specific function names.
mini_ker.texi(,1839) 
mini_ker.texi(,1840) @menu
mini_ker.texi(,1841) * Derivating a power function::
mini_ker.texi(,1842) @end menu
mini_ker.texi(,1843) 
mini_ker.texi(,1844) @node Derivating a power function
mini_ker.texi(,1845) @subsection Derivating a power function
mini_ker.texi(,1846) 
mini_ker.texi(,1847) Partial derivative of a function in exponent is not secure in its Fortran form
mini_ker.texi(,1848) @code{g(x,y)**(f(y))}. It should be replaced by @code{power(g,f)} of 
mini_ker.texi(Minik,1849) the Miniker @file{mathlib},
mini_ker.texi(,1850) or by the explicit form @code{exp(f(y)*log(g(x,y)))}.
mini_ker.texi(,1851) 
mini_ker.texi(,1852) Its derivative will have the following form:
mini_ker.texi(,1853) 
mini_ker.texi(,1854) 
mini_ker.texi(,1868) 
mini_ker.texi(,1869) and is in the macros list already defined in: @file{DERIVE_MAC}.
mini_ker.texi(,1870) 
mini_ker.texi(,1871) @node Rule of programming non continuous  models
mini_ker.texi(,1872) @section  Rule of programming non continuous  models
mini_ker.texi(,1873) 
mini_ker.texi(,1874) Some models may originally be non continuous, as the ones using a Fortran instruction @code{IF}.
mini_ker.texi(,1875) Some may use implicitly a step function on a variable. In such cases, the model has to be
mini_ker.texi(,1876) set in a derivable form, and use a ``smooth step'' instead.
mini_ker.texi(,1877)  One should be aware of that this apparently mathematical treatment currently
mini_ker.texi(,1878) indeed leads to a physical question about the macroscopic form of a physical law.
mini_ker.texi(,1879) At a macroscipic level, a step function is usually a nonsense.
mini_ker.texi(,1880) @cindex Heaviside function
mini_ker.texi(,1881) Taking
mini_ker.texi(,1882) the example of phase-change, a fluid volume does not change phase at once, and a ``smooth
mini_ker.texi(,1883) change of state'' is a correct macroscopic model.
mini_ker.texi(,1884) 
mini_ker.texi(Minik,1885) Miniker provides with the smooth step function 
mini_ker.texi(,1886) @emph{Heavyside}@footnote{This naming is a joke
mini_ker.texi(Minik,1887) for ``Inert'' Heaviside function.} in the Miniker @file{mathlib}:
mini_ker.texi(,1888) 
mini_ker.texi(,1889) @example
mini_ker.texi(,1890)         Delta = -1."K";
mini_ker.texi(,1891)         A_Ice =  heavyside("in:" (T_K-Tf), Delta, "out:" dAIce_dT);
mini_ker.texi(,1892) @end example
mini_ker.texi(,1893) 
mini_ker.texi(,1894) in this example, @code{Tf} is the ice fusion-temperature, @code{A_ice} 
mini_ker.texi(,1895) gives the ice-fraction
mini_ker.texi(,1896) of the mesh-volume of water at temperature @code{T_k}. 
mini_ker.texi(,1897) The smooth-step function is a quasi
mini_ker.texi(,1898) hyperbolic tangent function of @math{x/\Delta}, 
mini_ker.texi(,1899) normalised from 0 to 1, with a maximum slope
mini_ker.texi(,1900) of 2.5, see figure @ref{heavy}.
mini_ker.texi(,1901) 
mini_ker.texi(,1902) @float Figure, heavy
mini_ker.texi(,1903) @image{heavyside}
mini_ker.texi(,1904) @caption{Heaviside function and derivative}
mini_ker.texi(,1905) @end float
mini_ker.texi(,1916) 
mini_ker.texi(,1917) For @code{Mortran} to be able to symbolicaly compute the partial derivarives, the rule
mini_ker.texi(,1918) is in the table of macros as:
mini_ker.texi(,1919) 
mini_ker.texi(,1920) @example
mini_ker.texi(,1921) &'(HEAVYSIDE(#,#,#))(/#)' = '((#1)(/#4)*HEAVYDELTA(#1,#2,#3))'
mini_ker.texi(,1922) @end example
mini_ker.texi(,1923) 
mini_ker.texi(,1924) which uses the Foratn entry point @code{HeavyDelta} in the Fortrsan function @code{heavyside}.
mini_ker.texi(,1925) 
mini_ker.texi(,1926) Another type of problem arises when coding a  
mini_ker.texi(,1927) @code{var=min(f(x),g(x))} Fortran instruction.
mini_ker.texi(,1928) In such a case one does not want a derivative and one will code:
mini_ker.texi(,1929) 
mini_ker.texi(,1930) @example
mini_ker.texi(,1931) var = HeavySide(f(x)-g(x),Delta,dum)*g(x) + (1.-HeavySide(f(x)-g(x),Delta,dum)*f(x);
mini_ker.texi(,1932) @end example
mini_ker.texi(,1933) 
mini_ker.texi(,1934) or equivalently:
mini_ker.texi(,1935) 
mini_ker.texi(,1936) @example
mini_ker.texi(,1937) var = HeavySide(f(x)-g(x),Delta,dum)*g(x) + HeavySide(g(x)-f(x),-Delta,dum)*f(x);
mini_ker.texi(,1938) @end example
mini_ker.texi(,1939) 
mini_ker.texi(,1940) @strong{Warning}: the value of the argument @var{Delta} is important because 
mini_ker.texi(,1941) it will fix the maximum
mini_ker.texi(,1942) slope of the function that will appear as a coefficient in the 
mini_ker.texi(,1943) Jacbian matrices.
mini_ker.texi(,1944) 
mini_ker.texi(,1945) @node Parameters
mini_ker.texi(,1946) @section Parameters
mini_ker.texi(,1947) 
mini_ker.texi(,1948) It is possible to specify some Fortran variables as specific model parameters.
mini_ker.texi(,1949) Model parameters
mini_ker.texi(,1950) may be used in sensitivity studies (@pxref{Sensitivity to a parameter})
mini_ker.texi(,1951) and in the adjoint model (@pxref{Sensitivity of cost function to parameters}). 
mini_ker.texi(,1952) Nothing special is done with parameters with Kalman filtering.
mini_ker.texi(,1953) 
mini_ker.texi(,1954) 
mini_ker.texi(,1955) @findex Free_parameter
mini_ker.texi(,1956) 
mini_ker.texi(,1957) The parameters are fortran variables that should be initialized somewhere 
mini_ker.texi(,1958) in @file{zinit}. For a variable to be considered as a parameter, it should 
mini_ker.texi(,1959) be passed as an
mini_ker.texi(,1960) argument to the @code{Free_parameters} macro. For example if 
mini_ker.texi(,1961) @code{apar} and @code{cpar} (from the predator example) are to be considered
mini_ker.texi(,1962) as parameters, @code{Free_parameters} should be called with:
mini_ker.texi(,1963) 
mini_ker.texi(,1964) @example
mini_ker.texi(,1965) Free_parameter: apar, cpar;
mini_ker.texi(,1966) @end example
mini_ker.texi(,1967) 
mini_ker.texi(,1968) @c Forward sensitivities are explained later (@pxref{Sensitivity to a parameter}), 
mini_ker.texi(,1969) @c the syntax only is described here.
mini_ker.texi(,1970) 
mini_ker.texi(,1971) 
mini_ker.texi(,1972) When used with grid1d models (@pxref{1D gridded model,,
mini_ker.texi(,1973) Describing 1D gridded model}) the @code{inode} number may appear in 
mini_ker.texi(,1974) parenthesis:
mini_ker.texi(,1975) 
mini_ker.texi(,1976) @example
mini_ker.texi(,1977) Free_parameter: rd(1), rk(2);
mini_ker.texi(,1978) @end example
mini_ker.texi(,1979) 
mini_ker.texi(,1980) @node Observations and data
mini_ker.texi(,1981) @section Observations and data
mini_ker.texi(,1982) 
mini_ker.texi(,1983) Some support for observations and interactions with data is available.
mini_ker.texi(,1984) The observations are functions of the model variables. They don't have 
mini_ker.texi(,1985) any action on the model result, but they may (in theory) be observed 
mini_ker.texi(,1986) and measured. The natural use of these observations is to be compared
mini_ker.texi(,1987) with data that correspond with the values from real measurements.
mini_ker.texi(,1988) They are used in the Kalman filter (@pxref{Kalman filter}).
mini_ker.texi(,1989) 
mini_ker.texi(,1990) The (model) observation vector is noted @math{\omega}
mini_ker.texi(,1991) @c FIXME is seems untrue?
mini_ker.texi(,1992) @c in this section ($\mu$ elsewhere,
mini_ker.texi(,1993) and the observation function is noted @math{h}:
mini_ker.texi(,1994) 
mini_ker.texi(,2001) 
mini_ker.texi(,2002) @noindent @math{omega(t) = h(eta(t), phi(t))}
mini_ker.texi(,2003) 
mini_ker.texi(,2005) 
mini_ker.texi(,2006) @menu
mini_ker.texi(,2007) * Observations::
mini_ker.texi(,2008) * Data::
mini_ker.texi(,2009) @end menu
mini_ker.texi(,2010) 
mini_ker.texi(,2011) @node Observations
mini_ker.texi(,2012) @subsection Observations
mini_ker.texi(,2013) 
mini_ker.texi(,2014) @vindex mobs
mini_ker.texi(,2015) 
mini_ker.texi(,2016) The observation functions are set in a @code{set_probe} block in 
mini_ker.texi(,2017) the @file{zinit} sequence.
mini_ker.texi(,2018) 
mini_ker.texi(,2019) @cindex observation function
mini_ker.texi(,2020) 
mini_ker.texi(,2021) @c FIXME doesn't exist anymore
mini_ker.texi(,2022) @c @defmac eqn: Obs_tef(@var{i}) = f(eta(.),ff(.))
mini_ker.texi(,2023) @c This macro defines the observation equation as usual in a @code{set_block<}.
mini_ker.texi(,2024) @c @code{f} is a fortran 
mini_ker.texi(,2025) @c expression which may be function of cell state variables, 
mini_ker.texi(,2026) @c @samp{eta(1)}@dots{}@samp{eta(np)} and transfers 
mini_ker.texi(,2027) @c @samp{ff(1)}@dots{}@samp{ff(mp)}, or of course their symbolic names.
mini_ker.texi(,2028) @c @end defmac
mini_ker.texi(,2029) 
mini_ker.texi(,2030) For example suppose that, in the predator-prey model, we only 
mini_ker.texi(,2031) have access to the total population of preys and predators, we would have:
mini_ker.texi(,2032) 
mini_ker.texi(,2033) @example
mini_ker.texi(,2034) set_probe
mini_ker.texi(,2035) < eqn: pop = eta_pred + eta_pray;
mini_ker.texi(,2036) >;
mini_ker.texi(,2037) @end example
mini_ker.texi(,2038) 
mini_ker.texi(,2039) @c it is always turned on, now
mini_ker.texi(,2040) @c The corresponding code is used with @code{sel obs} in @file{selseq.kumac} 
mini_ker.texi(,2041) @c with cmz and @code{obs = 1} in @file{Makefile} with make. And the feature
mini_ker.texi(,2042) @c is turned on and off at run time with the logical flag @code{zobs} corresponding
mini_ker.texi(,2043) @c to an available data from measurement
mini_ker.texi(,2044) 
mini_ker.texi(,2045) @c @vindex etaobs(.)
mini_ker.texi(,2046) @cindex @file{obs.data}
mini_ker.texi(,2047) 
mini_ker.texi(,2048) The number of observations is put in the integer variable @code{mobs}.
mini_ker.texi(,2049) The observation vector corresponds with the part of the @code{ff(.)} 
mini_ker.texi(,2050) array situated past the regular transferts, @code{ff(mp+.)}, and is output
mini_ker.texi(,2051) in the file @file{obs.data}.
mini_ker.texi(,2052) 
mini_ker.texi(,2053) @c @vindex obetad(.,.)
mini_ker.texi(,2054) @c @vindex obephid(.,.)
mini_ker.texi(,2055) @c @vindex obspha(.,.)
mini_ker.texi(,2056) 
mini_ker.texi(,2057) @node Data
mini_ker.texi(,2058) @subsection Data
mini_ker.texi(,2059) 
mini_ker.texi(,2060) @vindex zgetobs
mini_ker.texi(,2061) @vindex vobs(.)
mini_ker.texi(,2062) @cindex @file{data.data}
mini_ker.texi(,2063) 
mini_ker.texi(,2064) Currently this code is only used if the Kalman code is activated. This
mini_ker.texi(,2065) may be changed in the future.
mini_ker.texi(,2066) 
mini_ker.texi(,2067) The convention for data is that whenever some data are available, the 
mini_ker.texi(,2068) logical variable @code{zgetobs} should be set to @samp{.true.}. And the
mini_ker.texi(,2069) @code{vobs(.)} vector should be filled with the data values. This 
mini_ker.texi(,2070) vector has the same dimension than the observation
mini_ker.texi(,2071) vector and each coordinate is meant to correspond with one
mini_ker.texi(,2072) coordinate of the observation vector.
mini_ker.texi(,2073) 
mini_ker.texi(,2074) This feature is turned on by setting the logical variable @code{zdata}
mini_ker.texi(,2075) to @samp{.true.}, and the @code{zgetobs} flag is typically set in the
mini_ker.texi(,2076) @file{zsteer} sequence (@pxref{End of time step,,Executing code at
mini_ker.texi(,2077) the end of each time step}).
mini_ker.texi(,2078) Every instant data are available (@code{zgetobs} is true) the observations
mini_ker.texi(,2079) are written to the file @file{data.data}. With the Kalman filter more 
mini_ker.texi(,2080) informations are output to the @file{data.data} file, 
mini_ker.texi(,2081) see @ref{Kalman filter results}.
mini_ker.texi(,2082) 
mini_ker.texi(,2083) 
mini_ker.texi(,2084) @node Explicit model size
mini_ker.texi(,2085) @section Entering model size explicitely
mini_ker.texi(,2086) 
mini_ker.texi(,2087) It is possible to enter the model dimensions explicitely, instead of 
mini_ker.texi(,2088) generating them automatically, as it was done previously.
mini_ker.texi(,2089) This feature is turned on by @code{sel dimetaphi} 
mini_ker.texi(,2090) in @file{selseq.kumac} with cmz
mini_ker.texi(,2091) and @code{dimetaphi} added to the @code{SEL} variable in 
mini_ker.texi(,2092) the @file{Makefile} with make.
mini_ker.texi(,2093) 
mini_ker.texi(,2094) @menu
mini_ker.texi(,2095) * Size sequence::
mini_ker.texi(,2096) * Model with explicit size::
mini_ker.texi(,2097) @end menu
mini_ker.texi(,2098) 
mini_ker.texi(,2099) @node Size sequence
mini_ker.texi(,2100) @subsection The explicit size sequence
mini_ker.texi(,2101) 
mini_ker.texi(,2102) @cindex dimetaphi
mini_ker.texi(,2103) @cindex model size
mini_ker.texi(,2104) @vindex np
mini_ker.texi(,2105) @vindex mp
mini_ker.texi(,2106) @vindex maxstep
mini_ker.texi(,2107) @cindex @file{dimetaphi}
mini_ker.texi(,2108) 
mini_ker.texi(,2109) The dimension of the model is entered in the sequence @file{dimetaphi},
mini_ker.texi(,2110) using the fortran @code{parameter np} for @code{eta(.)} and
mini_ker.texi(,2111) @code{mp} for @code{ff(.)}.
mini_ker.texi(,2112) For the Lotka-Volterra model, we have two cell components and only one transfer.
mini_ker.texi(,2113) 
mini_ker.texi(,2114) @example
mini_ker.texi(,2115) parameter (np=2,mp=1);
mini_ker.texi(,2116) @end example
mini_ker.texi(,2117) 
mini_ker.texi(,2118) You should not change the layout of the parameter statement as the 
mini_ker.texi(,2119) mortran preprocessor matches the line.
mini_ker.texi(,2120) 
mini_ker.texi(,2121) You also have to provide other parameters even if you don't have any 
mini_ker.texi(,2122) use for them. If you don't it will trigger fortran errors.
mini_ker.texi(,2123) It includes the @code{maxstep} parameter that can have any value but 0,
mini_ker.texi(,2124) @code{lp} and @code{mobs} that should be 0 in the example, and  @code{nxp},
mini_ker.texi(,2125) @code{nyp} and @code{nzp} that should also be 0.
mini_ker.texi(,2126) The layout is the following:
mini_ker.texi(,2127) 
mini_ker.texi(,2128) @example
mini_ker.texi(,2129) parameter (np=2,mp=1);
mini_ker.texi(,2130) parameter (mobs=0);
mini_ker.texi(,2131) 
mini_ker.texi(,2132) parameter (nxp=0,nyp=0,nzp=0);
mini_ker.texi(,2133) parameter (lp=0);
mini_ker.texi(,2134) parameter (maxstep=1);
mini_ker.texi(,2135) @end example
mini_ker.texi(,2136) 
mini_ker.texi(,2137) If there are observations, (@pxref{Observations}), the
mini_ker.texi(,2138) size of the observation vector is set in the @file{dimetaphi} sequence
mini_ker.texi(,2139) by the @code{mobs} parameter. For example if there is one observation:
mini_ker.texi(,2140) 
mini_ker.texi(,2141) @example
mini_ker.texi(,2142) parameter (mobs=1);
mini_ker.texi(,2143) @end example
mini_ker.texi(,2144) 
mini_ker.texi(,2145) To specify parameters (@pxref{Parameters}), the number of such parameters 
mini_ker.texi(,2146) has to be declared in @file{dimetaphi} with the parameter @code{lp}. 
mini_ker.texi(,2147) Then, if there are two parameters, they are first declared with
mini_ker.texi(,2148) 
mini_ker.texi(,2149) @example
mini_ker.texi(,2150) parameter (lp=2);
mini_ker.texi(,2151) @end example
mini_ker.texi(,2152) 
mini_ker.texi(,2153) @node Model with explicit size
mini_ker.texi(,2154) @subsection Entering the model equations, with explicit sizes
mini_ker.texi(,2155) 
mini_ker.texi(,2156) @cindex model equations
mini_ker.texi(,2157) @findex Phi_tef(.)
mini_ker.texi(,2158) @findex deta_tef(.)
mini_ker.texi(,2159) @vindex eta(.), explicit sizes
mini_ker.texi(,2160) @vindex ff(.), explicit sizes
mini_ker.texi(,2161) 
mini_ker.texi(,2162) When sizes are explicit, another possibility exists for entering
mini_ker.texi(,2163) the model equations. The use of symbolic names, as described in
mini_ker.texi(,2164) @ref{Model equations} is still possible, and it also becomes possible to
mini_ker.texi(,2165) set directly the equations associated with the @code{eta(.)}
mini_ker.texi(,2166) and @code{ff(.)} vectors.
mini_ker.texi(,2167) 
mini_ker.texi(,2168) In case the symbolic names are not used, 
mini_ker.texi(,2169) the model equations for cells and transfers are entered using a mortran macro,
mini_ker.texi(,2170) @code{f_set}@footnote{@code{fun_set}, or equivalently @code{f_set}, is a 
mini_ker.texi(,2171) general mortran macro associating a symbol with a fortran expression. 
mini_ker.texi(,2172) Here, it is the name of the symbol (@code{eta}) that has a particular meaning
mini_ker.texi(,2173) for the building of the model.}, setting the @code{eta(.)} evolution with 
mini_ker.texi(,2174) @code{deta_tef(.)}
mini_ker.texi(,2175) and the transfer definitions @code{ff(.)} with @code{Phi_tef(.)}.
mini_ker.texi(,2176) 
mini_ker.texi(,2177) @defmac f_set Phi_tef(@var{i}) = f(eta(.),ff(.))
mini_ker.texi(,2178) This macro defines the transfer @var{i} static equation.
mini_ker.texi(,2179) @code{f} is a fortran 
mini_ker.texi(,2180) expression which may be function of cell state variables, 
mini_ker.texi(,2181) @samp{eta(1)}@dots{}@samp{eta(np)} and transfers 
mini_ker.texi(,2182) @samp{ff(1)}@dots{}@samp{ff(mp)}.
mini_ker.texi(,2183) @end defmac
mini_ker.texi(,2184) 
mini_ker.texi(,2185) In the case of the predator-prey model, the transfer definition for 
mini_ker.texi(,2186) @math{\varphi_{meet}} is:
mini_ker.texi(,2187) @example
mini_ker.texi(,2188) f_set Phi_tef(1) = eta(1)*eta(2);  
mini_ker.texi(,2189) @end example
mini_ker.texi(,2190) 
mini_ker.texi(,2191) @defmac f_set deta_tef(@var{i}) = g(eta(@var{i}),ff(.))
mini_ker.texi(,2192) This macro defines the cell state component @var{i} time evolution model. 
mini_ker.texi(,2193) @code{g} is a expression which may be function of cell state variables, 
mini_ker.texi(,2194) @samp{eta(1)}@dots{}@samp{eta(np)} and transfers 
mini_ker.texi(,2195) @samp{ff(1)}@dots{}@samp{ff(mp)}.
mini_ker.texi(,2196) @end defmac
mini_ker.texi(,2197) 
mini_ker.texi(,2198) The two cell equations of the predator-prey model are, with index 1 for the
mini_ker.texi(,2199) prey (@math{\eta_{prey}}) and index 2 for the predator (@math{\eta_{pred}}):
mini_ker.texi(,2200) 
mini_ker.texi(,2201) @example
mini_ker.texi(,2202) f_set  deta_tef(1) = apar*eta(1)-apar*ff(1);
mini_ker.texi(,2203) f_set  deta_tef(2) = - cpar*eta(2) + cpar*ff(1);
mini_ker.texi(,2204) @end example
mini_ker.texi(,2205) 
mini_ker.texi(,2206) The whole model is:
mini_ker.texi(,2207) 
mini_ker.texi(,2208) @example
mini_ker.texi(,2209) !%%%%%%%%%%%%%%%%%%%%%%
mini_ker.texi(,2210) ! Transfer definition
mini_ker.texi(,2211) !%%%%%%%%%%%%%%%%%%%%%%
mini_ker.texi(,2212) ! rencontres (meeting)
mini_ker.texi(,2213)     f_set Phi_tef(1) = eta(1)*eta(2); 
mini_ker.texi(,2214) 
mini_ker.texi(,2215) !%%%%%%%%%%%%%%%%%%%%%%
mini_ker.texi(,2216) ! Cell definition
mini_ker.texi(,2217) !%%%%%%%%%%%%%%%%%%%%%%
mini_ker.texi(,2218) ! eta(1) : prey
mini_ker.texi(,2219) ! eta(2) : predator      
mini_ker.texi(,2220) 
mini_ker.texi(,2221)     f_set  deta_tef(1) = apar*eta(1)-apar*ff(1);
mini_ker.texi(,2222)     f_set  deta_tef(2) = - cpar*eta(2) + cpar*ff(1);
mini_ker.texi(,2223) @end example
mini_ker.texi(,2224) 
mini_ker.texi(,2225) The starting points for cells are entered like:
mini_ker.texi(,2226) @example
mini_ker.texi(,2227) !     initial state
mini_ker.texi(,2228) !     -------------
mini_ker.texi(,2229)      eta(1) = 1.;
mini_ker.texi(,2230)      eta(2) = 1.;
mini_ker.texi(,2231) @end example
mini_ker.texi(,2232) 
mini_ker.texi(,2233) If there are observations, they are entered as special transferts with
mini_ker.texi(,2234) index above @code{mp}, for example:
mini_ker.texi(,2235) 
mini_ker.texi(,2236) @example
mini_ker.texi(,2237) f_set Phi_tef(mp+1) = ff(1) ;
mini_ker.texi(,2238) @end example
mini_ker.texi(,2239) 
mini_ker.texi(,2240) @node Programming with cmz directives
mini_ker.texi(,2241) @section Programming with cmz directives
mini_ker.texi(,2242) 
mini_ker.texi(,2243) @menu
mini_ker.texi(Minik,2244) * Cmz directives used with Miniker::
mini_ker.texi(Minik,2245) * Using cmz directives in Miniker::
mini_ker.texi(,2246) @end menu
mini_ker.texi(,2247) 
mini_ker.texi(Minik,2248) @node Cmz directives used with Miniker
mini_ker.texi(Minik,2249) @subsection Cmz directives used with Miniker
mini_ker.texi(,2250) 
mini_ker.texi(,2251) The main feature of cmz directive is to use code conditionnaly for a given
mini_ker.texi(,2252) select flag. For example when the double precision is selected
mini_ker.texi(,2253) (@pxref{Double precision}) the use of the conditionnal 
mini_ker.texi(,2254) @code{double} flag may be required in case there is a different subroutine 
mini_ker.texi(,2255) name for different types. If, for example, the user use the subroutine
mini_ker.texi(,2256) @code{smysub} for simple precision and @code{dmysub} for double
mini_ker.texi(,2257) precision the following code is an example of what could appear in the
mini_ker.texi(,2258) user code:
mini_ker.texi(,2259) 
mini_ker.texi(,2260) @verbatim
mini_ker.texi(,2261) +IF,double
mini_ker.texi(,2262)  call dmysub(eta);
mini_ker.texi(,2263) +ELSE
mini_ker.texi(,2264)  call smysub(eta);
mini_ker.texi(,2265) +ENDIF
mini_ker.texi(,2266) @end verbatim
mini_ker.texi(,2267) 
mini_ker.texi(,2268) For a complete reference on cmz directives see the appendix
mini_ker.texi(,2269) @ref{Cmz directives reference}.
mini_ker.texi(,2270) 
mini_ker.texi(Minik,2271) @node Using cmz directives in Miniker
mini_ker.texi(Minik,2272) @subsection Using cmz directives in Miniker
mini_ker.texi(,2273) 
mini_ker.texi(,2274) In cmz the KEEP and DECK have their cmz directives preprocessed as part
mini_ker.texi(,2275) of the source files extraction. And the +KEEP and +DECK 
mini_ker.texi(,2276) directives are automatically
mini_ker.texi(,2277) set when creating the KEEP or DECK. With make, files with these directives 
mini_ker.texi(,2278) has to be created within the files that are to be preprocessed by the
mini_ker.texi(,2279) cmz directives preprocessor.
mini_ker.texi(,2280) 
mini_ker.texi(,2281) To be processed by make, a file that contains cmz directives 
mini_ker.texi(,2282) should have a file suffix corresponding
mini_ker.texi(,2283) with the language of the resulting file and with the normal file suffix of
mini_ker.texi(,2284) that language. More precisely @samp{cm} should be added before the normal
mini_ker.texi(,2285) file suffix and after the @samp{.}. Therefore if the resulting file language
mini_ker.texi(,2286) is associated with a suffix @samp{.@var{suf}}, the file with cmz directives
mini_ker.texi(,2287) should have a @samp{.cm@var{suf}} suffix. The tradition is to have
mini_ker.texi(,2288) a different suffix for main files and include files. 
mini_ker.texi(,2289) To add directories searched for @dfn{cmfiles} (files with cmz directives) 
mini_ker.texi(,2290) they should be added to the @code{CMFDIRS} makefile variable, separated 
mini_ker.texi(,2291) by @samp{:}.
mini_ker.texi(,2292) 
mini_ker.texi(,2293) Rules for preprocessing of the files are defined in the file 
mini_ker.texi(,2294) @file{Makefile.miniker} for the file types described in 
mini_ker.texi(,2295) @ref{tab:cmfile_suffix}:
mini_ker.texi(,2296) 
mini_ker.texi(,2297) @float table, tab:cmfile_suffix
mini_ker.texi(,2298) @multitable {fortran preprocessed} {include/keep} {cmfile suffix} {suffix} {language}
mini_ker.texi(,2299) @headitem language  @tab file type @tab cmfile suffix @tab suffix @tab language
mini_ker.texi(,2300) @item fortran @tab main/deck @tab .cmf @tab .f @tab ftn
mini_ker.texi(,2301) @item fortran preprocessed @tab main/deck @tab .cmF @tab .F @tab f77
mini_ker.texi(,2302) @item fortran preprocessed @tab include/keep @tab .cminc @tab .inc @tab f77
mini_ker.texi(,2303) @item mortran @tab main/deck @tab .cmmtn @tab .mtn @tab mtn
mini_ker.texi(,2304) @item mortran @tab include/keep @tab .cmmti @tab .mti @tab mtn
mini_ker.texi(,2305) @end multitable
mini_ker.texi(,2306) @caption{Association between file language, file type, file suffixes and 
mini_ker.texi(,2307) language identifier in cmz directives. A main file is called a @dfn{deck}
mini_ker.texi(,2308) in cmz and an include file is called a @dfn{keep}.}
mini_ker.texi(,2309) @end float
mini_ker.texi(,2310) 
mini_ker.texi(,2311) @node Dynamic system analysis
mini_ker.texi(Minik,2312) @chapter Dynamic analysis of systems in Miniker
mini_ker.texi(,2313) 
mini_ker.texi(,2314) @menu
mini_ker.texi(,2315) * Sensitivities::
mini_ker.texi(,2316) * Adjoint model and optimisation::
mini_ker.texi(,2317) * Kalman filter::
mini_ker.texi(,2318) * Feedback gain::
mini_ker.texi(,2319) * Stability of fastest modes::
mini_ker.texi(,2320) * Generalized TLS::
mini_ker.texi(,2321) @end menu
mini_ker.texi(,2322) 
mini_ker.texi(,2323) @node Sensitivities
mini_ker.texi(,2324) @section Automatic sensitivity computation
mini_ker.texi(,2325) 
mini_ker.texi(,2326) @cindex sensitivities
mini_ker.texi(,2327) 
mini_ker.texi(,2328) An obvious advantage of having acces to the Jacobian matrices along the
mini_ker.texi(,2329) system trajectory concerns automatic sensitivity analyses, as either:
mini_ker.texi(,2330) @itemize @bullet
mini_ker.texi(,2331) @item the sensitivity of all variables to perturbation in the initial condition
mini_ker.texi(,2332)       of one state variable;
mini_ker.texi(,2333) @item the same sensitivities to an initial pulse (or step) on a transfer;
mini_ker.texi(,2334) @item the same sensitivities to a series of pulses (or steps) on a transfer;
mini_ker.texi(,2335) @item the same for a change in a parameter, eventually during the run;
mini_ker.texi(,2336) @item the sensitivity of the matrix of advance in state space to a change
mini_ker.texi(,2337)  in a parameter.
mini_ker.texi(,2338) @end itemize
mini_ker.texi(,2339) 
mini_ker.texi(,2340) This is declared in Zinit as:
mini_ker.texi(,2341) 
mini_ker.texi(,2342) @example
mini_ker.texi(,2343) ! -------------
mini_ker.texi(,2344) ! Sensitivities
mini_ker.texi(,2345) ! -------------
mini_ker.texi(,2346) Sensy_to_var
mini_ker.texi(,2347) < var: eta_pray, pert: INIT;
mini_ker.texi(,2348)   var: eta_pred, pert: INIT;
mini_ker.texi(,2349) >;
mini_ker.texi(,2350) @end example
mini_ker.texi(,2351) 
mini_ker.texi(,2352) Each variable at origin of a perturbation is declared as @code{var:},
mini_ker.texi(,2353) and the type of perturbation in @code{pert:}. Here, INIT conditions are
mini_ker.texi(,2354) only allowed because the two variables are states variables. For transfers,
mini_ker.texi(,2355) @code{pert: pulse} corresponds to an initial pulse, @code{pert: step_resp}
mini_ker.texi(,2356) and  @code{pert: step_eff} to initial steps, the difference between 
mini_ker.texi(,2357) @code{_resp} (response form)
mini_ker.texi(,2358) and @code{_eff} (effect form) concerns the 
mini_ker.texi(,2359) diagonal only of the sensitivity matrix
mini_ker.texi(,2360) (see Feedback gains in non-linear models).
mini_ker.texi(,2361) 
mini_ker.texi(,2362) Non initial perturbation can also be asked for:
mini_ker.texi(,2363) 
mini_ker.texi(,2364) @example
mini_ker.texi(,2365)   Sensy_to_var
mini_ker.texi(,2366)   <
mini_ker.texi(,2367) !*     var: eta_courant_L, pert: init at 100;
mini_ker.texi(,2368) !*     var: ff_T_czcx,     pert: pulse at 100 every 20;
mini_ker.texi(,2369) !*     var: ff_Psi_Tczcx,  pert: step_eff;
mini_ker.texi(,2370) !*     var: ff_Psi_Tczcx,  pert: step_Resp at 10 every 100;
mini_ker.texi(,2371) ! *** premiers tests identiques a lorhcl.ref
mini_ker.texi(,2372)     var: ff_courant_L , pert: step_eff;
mini_ker.texi(,2373)     var: ff_T_czcx    , pert: step_eff;
mini_ker.texi(,2374)     var: ff_Psi_Tczcx , pert: step_eff;
mini_ker.texi(,2375)     var: ff_Psi_Tsz   , pert: pulse at 100 every 50;
mini_ker.texi(,2376)   >;
mini_ker.texi(,2377) @end example
mini_ker.texi(,2378) 
mini_ker.texi(,2379) In this example taken from @file{lorhcl}, a sensitivity can increase so as to
mini_ker.texi(,2380) trespass the Fortran capacity, so that each  sensitivity vector (matrix column)
mini_ker.texi(,2381) can be reset at some time-increment @code{at III every JJJ;}
mini_ker.texi(,2382) 
mini_ker.texi(,2383) It is noteworthy that these sensitivity analyses are not based
mini_ker.texi(,2384) on difference between two runs with different initial states or
mini_ker.texi(,2385) parameter values, but on the formal derivatives of the model. This method 
mini_ker.texi(,2386) is not only numerically robust, but is also rigorously funded as based on 
mini_ker.texi(,2387) the TLS of the model@footnote{For a short introduction to automatic 
mini_ker.texi(,2388) sensitivity analysis, see the document:@*
mini_ker.texi(,2389) @url{http://lmd.jussieu.fr/zoom/doc/sensibilite.ps}, in French,
mini_ker.texi(,2390) or ask for the more complete research document to a member of the TEF-ZOOM
mini_ker.texi(,2391) collaboration}.
mini_ker.texi(,2392) 
mini_ker.texi(,2393) If the @code{dimetaphi} sequence is built by the users, he should declare
mini_ker.texi(,2394) the number of perturbing variables as @code{nxp=}:
mini_ker.texi(,2395) 
mini_ker.texi(,2396) @example
mini_ker.texi(,2397)       parameter (nxp=np,nyp=0,nzp=0);
mini_ker.texi(,2398) @end example
mini_ker.texi(,2399) here, all state variables are considered as perturbing variables.
mini_ker.texi(,2400) 
mini_ker.texi(,2401) @cindex sensitivity, output
mini_ker.texi(,2402) @cindex output, sensitivity
mini_ker.texi(,2403) @cindex @file{sens.data}
mini_ker.texi(,2404) @cindex @file{sigma.data}
mini_ker.texi(,2405) 
mini_ker.texi(,2406) The sensitivity vectors are output in the result files @file{sens.data} for 
mini_ker.texi(,2407) cells and @file{sigma.data} for transfers. In those files the first column
mini_ker.texi(,2408) corresponds again with time, and the other columns are relative sensitivities of the cell
mini_ker.texi(,2409) states (in @file{sens.data}) and transfers (in @file{sigma.data})
mini_ker.texi(,2410) with respect to the initial value of the perturbed state. 
mini_ker.texi(,2411) 
mini_ker.texi(,2412) In our predator-prey example, the second column of  @file{sens.data} will contain
mini_ker.texi(,2413) the derivative of @math{\eta_1(t)} with respect to @math{\eta_1(t=0)}.
mini_ker.texi(,2414) Drawing the
mini_ker.texi(,2415) second column of @file{sens.data} against the first one
mini_ker.texi(,2416) gives the time evolution of the sensitivity of @code{eta-pred}
mini_ker.texi(,2417) to a change in the initial value of @code{eta-pray}. One can check
mini_ker.texi(,2418) in that it is set to 1 at @math{t=0}:
mini_ker.texi(,2419) 
mini_ker.texi(,2420) @example
mini_ker.texi(,2421) #    Sensy_to: eta_pray         3        eta_pred         5       
mini_ker.texi(,2422) # time \\  of: eta_pray     eta_pred     eta_pray     eta_pred    
mini_ker.texi(,2423)   0.00000E+00  1.00000E+00  0.00000E+00  0.00000E+00  1.00000E+00
mini_ker.texi(,2424)   1.00000E-02  9.90868E-01  1.11905E-02 -1.26414E-02  9.98859E-01
mini_ker.texi(,2425) @end example
mini_ker.texi(,2426) The two last columns are the state sensitivity to a change in initial conditions
mini_ker.texi(,2427) of the number of predators.
mini_ker.texi(,2428) 
mini_ker.texi(,2429) In the same way, the @var{j+1}th column of @file{sigma.data} will be the
mini_ker.texi(,2430) derivative of @math{\phi_{j}(t)} with respect to @math{\eta_i(t=0)}. Here:
mini_ker.texi(,2431) @example
mini_ker.texi(,2432) #    Sensy_to: eta_pray     eta_pred    
mini_ker.texi(,2433) # time \\  of: ff_interact  ff_interact 
mini_ker.texi(,2434)   0.00000E+00  1.60683E+00  8.47076E-01
mini_ker.texi(,2435)   1.00000E-02  1.59980E+00  8.18164E-01
mini_ker.texi(,2436) @end example
mini_ker.texi(,2437) 
mini_ker.texi(,2438) the unique transfer variable gives rise to two sensitivity columns. 
mini_ker.texi(,2439) 
mini_ker.texi(,2440) Sensitivity studies are usefull to assess the
mini_ker.texi(,2441) predictability properties of the corresponding system.
mini_ker.texi(,2442) 
mini_ker.texi(,2443) @menu
mini_ker.texi(,2444) @c * Initial state sensitivity::
mini_ker.texi(,2445) @c * Sensitivity to a pulse or a step on transfer::
mini_ker.texi(,2446) @c * Extended Sensitivity studies::
mini_ker.texi(,2447) * Sensitivity to a parameter::
mini_ker.texi(,2448) * Advance matrix sensitivity::
mini_ker.texi(,2449) @end menu
mini_ker.texi(,2450) 
mini_ker.texi(,2451) 
mini_ker.texi(,2452) 
mini_ker.texi(,2453) @node Sensitivity to a parameter
mini_ker.texi(,2454) @subsection Sensitivity to a parameter
mini_ker.texi(,2455) 
mini_ker.texi(,2456) A forward sensitivity to a parameter will be computed when specified as
mini_ker.texi(,2457) described in @ref{Parameters}. For example, suppose that
mini_ker.texi(,2458) the sensitivity to an initial change in the @code{apar} parameter of
mini_ker.texi(,2459) the predator model is of interest. 
mini_ker.texi(,2460) @c In that case the number of
mini_ker.texi(,2461) @c parameters should be set to 1 in @file{dimetaphi}:
mini_ker.texi(,2462) @c 
mini_ker.texi(,2463) @c @example
mini_ker.texi(,2464) @c parameter (lp=2);
mini_ker.texi(,2465) @c @end example
mini_ker.texi(,2466) 
mini_ker.texi(,2467) The sensitivity calculs is turned on as a forward
mini_ker.texi(,2468) parameter specified on the @code{Free_parameter} list:
mini_ker.texi(,2469) 
mini_ker.texi(,2470) @example
mini_ker.texi(,2471) Free_parameter: [fwd: apar, cpar];
mini_ker.texi(,2472) @end example
mini_ker.texi(,2473) 
mini_ker.texi(,2474) The result are in @file{sensp.data} for cells and @file{sigmap.data}
mini_ker.texi(,2475) for transfers.
mini_ker.texi(,2476) 
mini_ker.texi(,2477) @example
mini_ker.texi(,2478) #    Sensy_to: pi_prandtl       3            4        pi_rayleigh_     6
mini_ker.texi(,2479) # time \\  of: eta_courant_ eta_T_czcx   eta_T_sz     eta_courant_ eta_T
mini_ker.texi(,2480)   0.00000E+00  0.00000E+00  0.00000E+00  0.00000E+00  0.00000E+00  0.000
mini_ker.texi(,2481)   2.00000E-03 -4.77172E-03 -3.99170E-05  3.55971E-05 -9.94770E-05 -1.004
mini_ker.texi(,2482) @end example
mini_ker.texi(,2483) In the above example from @file{lorhcl} sensitivity of the three states with respect
mini_ker.texi(,2484) to an initial change in two parameters are independantly given (first line also numbers
mini_ker.texi(,2485) the column to easy gnuplot using).
mini_ker.texi(,2486) 
mini_ker.texi(,2487) @node Advance matrix sensitivity
mini_ker.texi(,2488) @subsection Advance matrix sensitivity
mini_ker.texi(,2489) 
mini_ker.texi(,2490) 
mini_ker.texi(,2491) It is possible to look at the sensitivity of the matrix of advance in 
mini_ker.texi(,2492) states space (the matrix @code{aspha}) with regard to a parameter. 
mini_ker.texi(,2493) The parameter must be accounted for in the parameter number and be in the 
mini_ker.texi(,2494) parameter list, flagged as the matrix @code{mx} parameter, like in
mini_ker.texi(,2495) @example
mini_ker.texi(,2496) Free_parameter: [mx: apar], cpar;
mini_ker.texi(,2497) @end example
mini_ker.texi(,2498) 
mini_ker.texi(,2499) @vindex d_pi_aspha(.,.)
mini_ker.texi(,2500) 
mini_ker.texi(,2501) This feature is associated with a selecting flag, @samp{dPi_aspha}. One gets
mini_ker.texi(,2502) the result in the matrix @code{d_pi_aspha(.,.)} of dimension 
mini_ker.texi(,2503) (@code{np},@code{np}).
mini_ker.texi(,2504) 
mini_ker.texi(,2505) This matrix may be used to compute other quantities, for example
mini_ker.texi(,2506) it may be used to compute the sensitivity of the eigenvalues of
mini_ker.texi(,2507) the state-advance matrix with regard to the @code{[fwd]} parameter.
mini_ker.texi(,2508) These additional computations have to be programmed by the user in 
mini_ker.texi(,2509) @file{zsteer} with matrices declared and initialized in 
mini_ker.texi(,2510) @file{zinit}. An example is given in the example @file{lorhcl}
mini_ker.texi(Minik,2511) provided with the Miniker installation files, following a method proposed
mini_ker.texi(,2512) by Stephane Blanco.
mini_ker.texi(,2513) 
mini_ker.texi(,2514) @node Adjoint model and optimisation
mini_ker.texi(Minik,2515) @section Adjoint model and optimisation with Miniker
mini_ker.texi(,2516) 
mini_ker.texi(Minik,2517) In the following a possible use of Miniker for optimisation is discussed.
mini_ker.texi(Minik,2518) More precisely the use of adjoint and control laws in Miniker are presented.
mini_ker.texi(,2519) Optimisation isn't the only application of these tools, but it is the most
mini_ker.texi(,2520) common one. In that case the adjoint may be used to determine the gradient of a
mini_ker.texi(,2521) functional to perturbations in the control laws, and an optimisation process
mini_ker.texi(,2522) can use this
mini_ker.texi(,2523) information to search for the optimum.
mini_ker.texi(,2524) Another application of the adjoint is to compute the sensitivity of a
mini_ker.texi(,2525) cost function to parameters (the ones declared in the @code{free_parameters:}' list.
mini_ker.texi(,2526) Note that the cost function can be sensitive to probe's variables, even if these are
mini_ker.texi(,2527) uncoupled with standard variables in the forward calculations; this is the case
mini_ker.texi(,2528) when minimizing a quadratic distance function between probes (from the  model)
mini_ker.texi(,2529) and the corresponding measurements.
mini_ker.texi(,2530) 
mini_ker.texi(,2531) The code is close transcription of the mathematical calculus described
mini_ker.texi(,2532) in@* @url{http://www.lmd.jussieu.fr/ZOOM/doc/Adjoint.pdf} . It essentialy reverse time and
mini_ker.texi(,2533) transpose the four Jacobian matrices: states and transfers are saved in array dimensionned
mini_ker.texi(,2534) with @code{maxstep} Fortran parameter.
mini_ker.texi(,2535) @menu
mini_ker.texi(Minik,2536) * Overview of optimisation with Miniker::
mini_ker.texi(,2537) * Control laws::
mini_ker.texi(,2538) * Cost function coding and adjoint modeling::
mini_ker.texi(,2539) * Sensitivity of cost function to parameters::
mini_ker.texi(,2540) @end menu
mini_ker.texi(,2541) 
mini_ker.texi(Minik,2542) @node Overview of optimisation with Miniker
mini_ker.texi(Minik,2543) @subsection Overview of optimisation with Miniker
mini_ker.texi(,2544) 
mini_ker.texi(,2545) @cindex adjoint
mini_ker.texi(,2546) @cindex optimisation
mini_ker.texi(,2547) 
mini_ker.texi(Minik,2548) In the proposed method, Miniker is run twice, one time forward and then
mini_ker.texi(,2549) backward to determine the trajectory and the adjoint model. After that the 
mini_ker.texi(Minik,2550) control laws are modified by a program external to Miniker. The same steps
mini_ker.texi(,2551) are repeated until convergence. More pecisely,
mini_ker.texi(,2552) 
mini_ker.texi(,2553) @table @strong
mini_ker.texi(,2554) @item forward
mini_ker.texi(,2555) The command law @math{h(t)} is given (by an explicit law or taken from a file).
mini_ker.texi(,2556) The trajectory is computed in a classical way, with the additionnal computation
mini_ker.texi(,2557) of the functional to be optimised, @math{J}, prescribed with specific 
mini_ker.texi(,2558) @code{f_set} macros. The states, transfers and control laws are stored.  
mini_ker.texi(,2559) @item backward
mini_ker.texi(,2560) The adjoint variable is computed from the last time @math{T} backward. The
mini_ker.texi(,2561) time increment is re-read as it could have changed during the forward 
mini_ker.texi(,2562) simulation. The system is solved by using the same technics as in the forward 
mini_ker.texi(,2563) simulation, but with a negative time step.
mini_ker.texi(,2564) @item external phase
mini_ker.texi(,2565) Now the command should be corrected. This step isn't covered here, but, for
mini_ker.texi(,2566) example, minuit the optimisation tool from the CERN could be used. 
mini_ker.texi(Minik,2567) In order to ease such a use of Miniker, the principal program has to be 
mini_ker.texi(,2568) compiled as a subroutine to be driven by an external program 
mini_ker.texi(,2569) (@pxref{Calling the model code}).
mini_ker.texi(,2570) @end table
mini_ker.texi(,2571) 
mini_ker.texi(,2572) The functionnal @math{J} to be optimised is defined as
mini_ker.texi(,2573) 
mini_ker.texi(,2588) @noindent @math{J = psi(eta(T),phi(T),h(T)) + int_0^T l(eta(tau),phi(tau),h(tau)) d tau}
mini_ker.texi(,2591) 
mini_ker.texi(,2592) @cindex final cost
mini_ker.texi(,2593) @cindex integrand cost
mini_ker.texi(,2594) 
mini_ker.texi(,2595) Where @math{\psi} is the final cost function, @math{l} is the integrand
mini_ker.texi(,2596) cost function and @math{h} represents the control laws variations.
mini_ker.texi(,2597) 
mini_ker.texi(,2598) The general use of the adjoint model of a system is the determination of the 
mini_ker.texi(,2599) gradient of this @math{J} functional to be optimised, with respect to perturbations
mini_ker.texi(,2600) of the original conditions of the reference trajectory, that is, along its 
mini_ker.texi(,2601) GTLS@footnote{General Tangent Linear System, i.e. the TLS circulating along a trajectory.
mini_ker.texi(,2602) See the explanation in the document
mini_ker.texi(,2603) @url{http://www.lmd.jussieu.fr/Zoom/doc/Adjoint.pdf} (in French).}.
mini_ker.texi(,2604) 
mini_ker.texi(,2605) @node Control laws
mini_ker.texi(,2606) @subsection Control laws
mini_ker.texi(,2607) 
mini_ker.texi(,2608) @vindex zcommand
mini_ker.texi(,2609) @cindex command law
mini_ker.texi(,2610) 
mini_ker.texi(,2611) Each control law is associated with one cell or transfer equation, meaning that a command
mini_ker.texi(,2612) associated with an equation does not appear in any other equation.
mini_ker.texi(,2613) It is still possible
mini_ker.texi(,2614) to add commands acting anywhere by defining a transfer equal to that command.
mini_ker.texi(,2615) 
mini_ker.texi(,2616) 
mini_ker.texi(,2617) The control laws associated with states are in the @code{ux_com(.)} array, 
mini_ker.texi(,2618) control laws associated with transfers are in the @code{uy_com(.)} array.
mini_ker.texi(,2619) The control laws may be prescribed even when there is no adjoint computed, 
mini_ker.texi(,2620) nor any optimisation, and they are used during simulation, in which case they will
mini_ker.texi(,2621) act as external sources. To enable
mini_ker.texi(,2622) the use of commands, the logical flag @code{Zcommand} should be @code{.true.}.
mini_ker.texi(,2623) 
mini_ker.texi(,2624) @cindex @file{uxcom.data}
mini_ker.texi(,2625) @cindex @file{uycom.data}
mini_ker.texi(,2626) 
mini_ker.texi(,2627) The command can be given either as: 
mini_ker.texi(,2628) @enumerate 
mini_ker.texi(,2629) @item a table of numerical
mini_ker.texi(,2630) values in the files @file{uxcom.data} and @file{uycom.data}.
mini_ker.texi(,2631) @item a function
mini_ker.texi(,2632) @vindex zlaw
mini_ker.texi(,2633) @cindex @file{zcmd_law}
mini_ker.texi(,2634) @cindex @file{zcmd_law.inc}
mini_ker.texi(,2635) of the problem variables. To turn that feature on the logical flag 
mini_ker.texi(,2636) @code{Zlaw} should be set to @code{.true.} in @file{zinit}. The sequence 
mini_ker.texi(,2637) @file{zcmd_law} should hold
mini_ker.texi(,2638) the code filling the @code{ux_com(.)} and @code{uy_com(.)} arrays, as the code
mini_ker.texi(,2639) from that sequence is used whenever the control laws are needed.
mini_ker.texi(,2640) In that case the files  @file{uxcom.data} and @file{uycom.data} will 
mini_ker.texi(,2641) be filled by the command values generated by the function along the trajectory.
mini_ker.texi(,2642) @end enumerate
mini_ker.texi(,2643) 
mini_ker.texi(,2644) For example in the Lotka-Volterra model, the parameter @code{apar} could 
mini_ker.texi(,2645) be a control variable.
mini_ker.texi(,2646) In that case, @code{apar} would be defined as the variable @code{ux_com(1)}, 
mini_ker.texi(,2647) and either entered as a law
mini_ker.texi(,2648) in the sequence @file{zcmd_law} , either written in the file @file{uxcom.data} 
mini_ker.texi(,2649) step by step. In that case, there must be a perfect corresponodence between time
mini_ker.texi(,2650) of the commands and time of the run.
mini_ker.texi(,2651) 
mini_ker.texi(,2652) @node Cost function coding and adjoint modeling
mini_ker.texi(,2653) @subsection Cost function coding and adjoint modeling
mini_ker.texi(,2654) 
mini_ker.texi(,2655) @vindex zback
mini_ker.texi(,2656) @findex cout_Psi
mini_ker.texi(,2657) @findex cout_l
mini_ker.texi(,2658) 
mini_ker.texi(,2659) First of all the flag @code{zback} should be set to @code{.true.} in order to
mini_ker.texi(,2660) allow adjoint model computation:
mini_ker.texi(,2661) 
mini_ker.texi(,2662) @example
mini_ker.texi(,2663) Zback=.true.;
mini_ker.texi(,2664) @end example
mini_ker.texi(,2665) 
mini_ker.texi(,2666) The two functions @code{cout_Psi} corresponding with the final cost and 
mini_ker.texi(,2667) @code{cout_l} corresponding with the integrand cost are set up with the
mini_ker.texi(,2668) @code{f_set} macros.
mini_ker.texi(,2669) 
mini_ker.texi(,2670) @defmac f_set cout_Psi = f(eta(.),ff(.),ux_com(.),uy_com(.))
mini_ker.texi(,2671) This macro defines the final cost function.
mini_ker.texi(,2672) @code{f} is a fortran 
mini_ker.texi(,2673) expression which may be function of cell state variables, 
mini_ker.texi(,2674) @samp{eta(1)}@dots{}@samp{eta(np)}, transfers 
mini_ker.texi(,2675) @samp{ff(1)}@dots{}@samp{ff(mp)}, 
mini_ker.texi(,2676) state control laws
mini_ker.texi(,2677) @samp{ux_com(1)}@dots{}@samp{ux_com(np)}, and transfer control laws
mini_ker.texi(,2678) @samp{uy_com(1)}@dots{}@samp{uy_com(mp)}.
mini_ker.texi(,2679) @end defmac
mini_ker.texi(,2680) 
mini_ker.texi(,2681) @defmac f_set cout_l = f(eta(.),ff(.),ux_com(.),uy_com(.))
mini_ker.texi(,2682) This macro defines the integrand cost function.
mini_ker.texi(,2683) @code{f} is a fortran 
mini_ker.texi(,2684) expression which may be function of cell state variables, 
mini_ker.texi(,2685) @samp{eta(1)}@dots{}@samp{eta(np)}, transfers 
mini_ker.texi(,2686) @samp{ff(1)}@dots{}@samp{ff(mp)},
mini_ker.texi(,2687) state control laws
mini_ker.texi(,2688) @samp{ux_com(1)}@dots{}@samp{ux_com(np)}, and transfer control laws
mini_ker.texi(,2689) @samp{uy_com(1)}@dots{}@samp{uy_com(mp)}.
mini_ker.texi(,2690) @end defmac
mini_ker.texi(,2691) 
mini_ker.texi(,2692) For example, the following code sets a cost function for the masselottes
mini_ker.texi(,2693) model:
mini_ker.texi(,2694) 
mini_ker.texi(,2695) @example
mini_ker.texi(,2696) ! Initialisation 
mini_ker.texi(,2697)   F_set cout_Psi = eta_move(inode:1);
mini_ker.texi(,2698) !and f_set cout_l integrand in the functionnal    
mini_ker.texi(,2699)   F_set cout_l = 0.;
mini_ker.texi(,2700) @end example
mini_ker.texi(,2701) 
mini_ker.texi(,2702) In that example the functional is reduced to the final value
mini_ker.texi(,2703) of the first state component.
mini_ker.texi(,2704) Here, the adjoint vector will correspond to the final sensitivity 
mini_ker.texi(,2705) (at @math{t=0}) of 
mini_ker.texi(,2706) that component (here the first masselotte position) to a perturbation in 
mini_ker.texi(,2707) all initial conditions@footnote{For detailed explanation of the adjoint model,
mini_ker.texi(,2708) see the document in 
mini_ker.texi(,2709) @uref{http://www.lmd.jussieu.fr/@/ZOOM/doc/Adjoint.pdf,pdf}
mini_ker.texi(,2710) or @uref{http://www.lmd.jussieu.fr/@/ZOOM/doc/Adjoint.pdf,.ps.gz}}. 
mini_ker.texi(,2711) 
mini_ker.texi(,2712) @c In the code, the variables @code{v_adj(.)} and @code{w_adj(.)}
mini_ker.texi(,2713) @c are respectively adjoint to @code{eta(.)} and @code{ff(.)}. They are written in the
mini_ker.texi(,2714) @c two files: @file{vadj.data} and @file{wadj.data}.
mini_ker.texi(,2715) The following variables are set during the backward phase, and output
mini_ker.texi(,2716) in the associated files:
mini_ker.texi(,2717) 
mini_ker.texi(,2718) 
mini_ker.texi(,2719) @multitable {@code{gradufj(.)}} {@file{hamilton.data}} {time increment, hamiltonian, cost function increment}
mini_ker.texi(,2720) @headitem var @tab file @tab explanation
mini_ker.texi(,2721) @c @item @code{} @tab @file{.data} @tab  @tab
mini_ker.texi(,2722) @item @code{v_adj(.)} @tab @file{vadj.data} @tab adjoint to @code{eta(.)}
mini_ker.texi(,2723) @item @code{w_adj(.)} @tab @file{wadj.data} @tab adjoint to @code{ff(.)}
mini_ker.texi(,2724) @item @code{wadj(mp+.)} @tab @file{gradmuj.data} @tab adjoint to @code{ff(mp+.)}
mini_ker.texi(,2725) @item @code{graduej(.)} @tab @file{gradxj.data} @tab adjoint to @code{ux_com(.)}
mini_ker.texi(,2726) @item @code{gradufj(.)} @tab @file{gradyj.data} @tab adjoint to @code{uy_com(.)}
mini_ker.texi(,2727) @item @code{hamilton} @tab @file{hamilton.data} @tab time increment, hamiltonian, cost function increment
mini_ker.texi(,2728) @end multitable
mini_ker.texi(,2729) 
mini_ker.texi(,2730) @node Sensitivity of cost function to parameters
mini_ker.texi(,2731) @subsection Sensitivity of cost function to parameters
mini_ker.texi(,2732) 
mini_ker.texi(,2733) @cindex @file{gradpj.data}
mini_ker.texi(,2734) 
mini_ker.texi(,2735) The sensitivity of the cost function to all the parameters given as
mini_ker.texi(,2736) arguments of @code{Free_parameters} is computed. For the
mini_ker.texi(,2737) predator model the sensitivity of a cost function consisting in 
mini_ker.texi(,2738) the integral of the predator population with respect with
mini_ker.texi(,2739) @code{apar} an @code{cpar} is obtained with a number of parameters
mini_ker.texi(,2740) set to 2 in @file{dimetaphi}:
mini_ker.texi(,2741) 
mini_ker.texi(,2742) @example
mini_ker.texi(,2743) parameter (lp=2);
mini_ker.texi(,2744) @end example
mini_ker.texi(,2745) 
mini_ker.texi(,2746) And the cost function and @code{Free_parameters} list in @file{zinit}:
mini_ker.texi(,2747) 
mini_ker.texi(,2748) @example
mini_ker.texi(,2749) f_set cout_Psi = eta(2);
mini_ker.texi(,2750) f_set cout_l = eta(2);
mini_ker.texi(,2751) Free_parameters: apar,cpar;
mini_ker.texi(,2752) @end example
mini_ker.texi(,2753) 
mini_ker.texi(,2754) @code{apar} and @code{cpar} also have to be given a value.
mini_ker.texi(,2755) The result is output in @file{gradpj.data}.
mini_ker.texi(,2756) 
mini_ker.texi(,2757) @node Kalman filter
mini_ker.texi(,2758) @section Kalman filter
mini_ker.texi(,2759) 
mini_ker.texi(,2760) @cindex Kalman filter
mini_ker.texi(,2761) @cindex variance-covariance matrices, general
mini_ker.texi(,2762) @cindex observations, general
mini_ker.texi(,2763) 
mini_ker.texi(,2764) The Kalman filter allows for data assimilation along the model run. In 
mini_ker.texi(,2765) that case it is assumed that there is a real-world model with stochastic
mini_ker.texi(,2766) perturbations on the states, and that noisy observations are available. 
mini_ker.texi(Minik,2767) The situation implemented in Miniker corresponds to a continuous 
mini_ker.texi(,2768) stochastic perturbation on the state, and discrete noisy observations.
mini_ker.texi(,2769) In the @acronym{TEF} this leads to:
mini_ker.texi(,2770) 
mini_ker.texi(,2789) 
mini_ker.texi(,2790) @noindent @math{d eta(t)/d t = g(eta(t),phi(t)) + W(t) mu@*
mini_ker.texi(,2791) phi(i) = f(eta(t),phi(t))@*
mini_ker.texi(,2792) omega(t) = h(eta(t), phi(t)) + nu }
mini_ker.texi(,2793) 
mini_ker.texi(,2796) 
mini_ker.texi(,2797) @c FIXME partout omega
mini_ker.texi(,2798) @c (notice that in this paragraph, $\omega$ stands for the probe vector $\mu$ elsewhere,
mini_ker.texi(,2799) @c and $\mu$ is here a noise source.
mini_ker.texi(,2800) 
mini_ker.texi(,2801) The observations @math{\omega} are available at discrete time steps @math{t=s_i}. The
mini_ker.texi(,2802) stochastic perturbation on state, @math{\mu} is characterized by a 
mini_ker.texi(,2803) variance-covariance matrix @math{Q} and the noise on the observation,
mini_ker.texi(,2804) @math{\nu} has a variance-covariance matrix @math{R}. @math{W} relates states
mini_ker.texi(,2805) with stochastic perturbations. At each time step the Kalman filter recomputes 
mini_ker.texi(,2806) an estimation of the state and the variance-covariance matrix of the state.
mini_ker.texi(,2807) 
mini_ker.texi(,2808) In the following we use the example of a linear model with perturbation 
mini_ker.texi(,2809) on state and observation of state. The model has 3 states and 3 corresponding
mini_ker.texi(,2810) transfers (equal to the states), but the error on the state is of dimension 
mini_ker.texi(,2811) 2. The 3 states are observed. The corresponding equations read:
mini_ker.texi(,2812) 
mini_ker.texi(,2862) 
mini_ker.texi(,2864) 
mini_ker.texi(,2865) Cells:@*
mini_ker.texi(,2866) @noindent @math{d eta_1/dt = a_11 eta_1 + a_12 phi_2 + a_13 phi_3 + W_11 mu_1 + W_12 mu_2@*
mini_ker.texi(,2867) d eta_2/dt = a_21 phi_1 + a_22 eta_2 + a_23 phi_3 + W_21 mu_1 + W_22 mu_2@*
mini_ker.texi(,2868) d eta_3/dt = a_31 phi_1 + a_32 phi_2 + a_33 eta_3 + W_31 mu_1 + W_32 mu_2}
mini_ker.texi(,2869) 
mini_ker.texi(,2870) Transfers:@*
mini_ker.texi(,2871) @noindent @math{phi_1 = eta_1@*
mini_ker.texi(,2872) phi_2 = eta_2@*
mini_ker.texi(,2873) phi_3 = eta_3}
mini_ker.texi(,2874) 
mini_ker.texi(,2875) Observations:@*
mini_ker.texi(,2876) @noindent @math{omega_1 = phi_1 + nu_1@*
mini_ker.texi(,2877) omega_2 = eta_2 + nu_2@*
mini_ker.texi(,2878) omega_3 = eta_3 + nu_3}
mini_ker.texi(,2879) 
mini_ker.texi(,2882) 
mini_ker.texi(,2883) @menu 
mini_ker.texi(,2884) * Coding the Kalman filter::
mini_ker.texi(,2885) * Kalman filter run and output::
mini_ker.texi(,2886) * Executing code after the analysis::
mini_ker.texi(,2887) @end menu
mini_ker.texi(,2888) 
mini_ker.texi(,2889) @node Coding the Kalman filter
mini_ker.texi(,2890) @subsection Coding the Kalman filter
mini_ker.texi(,2891) 
mini_ker.texi(,2892) @vindex zkalman
mini_ker.texi(,2893) 
mini_ker.texi(,2894) First of all the Kalman filter code should be activated. The observations
mini_ker.texi(,2895) code is also required (@pxref{Observations}).
mini_ker.texi(,2896) If cmz is used the code
mini_ker.texi(,2897) should be selected with the select flag kalman 
mini_ker.texi(,2898) in the @file{selseq.kumac}:
mini_ker.texi(,2899) 
mini_ker.texi(,2900) @example
mini_ker.texi(,2901) sel kalman
mini_ker.texi(,2902) @end example
mini_ker.texi(,2903) 
mini_ker.texi(,2904) With make the @code{kalman} variable should be set to 1:
mini_ker.texi(,2905) 
mini_ker.texi(,2906) @example
mini_ker.texi(,2907) kalman = 1
mini_ker.texi(,2908) @end example
mini_ker.texi(,2909) 
mini_ker.texi(,2910) The kalman code is actually used by setting the flag
mini_ker.texi(,2911) @code{zkalman} to @code{.true.}, for example in the @file{zinit}:
mini_ker.texi(,2912) 
mini_ker.texi(,2913) @example
mini_ker.texi(,2914) zkalman = .True.;
mini_ker.texi(,2915) @end example
mini_ker.texi(,2916) 
mini_ker.texi(,2917) @c This will set the @code{zobs} and @code{zdata} flags to @code{.true.} 
mini_ker.texi(,2918) @c (@pxref{Observations and data}).
mini_ker.texi(,2919) 
mini_ker.texi(,2920) With the Kalman filter the dimension of estimated states, of the error 
mini_ker.texi(,2921) on the state and of the
mini_ker.texi(,2922) observation, the @math{W} matrix, the observation function,
mini_ker.texi(,2923) the initial
mini_ker.texi(,2924) variance-covariance matrices on the state and the variance-covariance matrices 
mini_ker.texi(,2925) of errors have to be given.
mini_ker.texi(,2926) 
mini_ker.texi(,2927) @menu 
mini_ker.texi(,2928) * Kalman filter vectors dimensions::
mini_ker.texi(,2929) * Error and observation matrices::
mini_ker.texi(,2930) @end menu
mini_ker.texi(,2931) 
mini_ker.texi(,2932) @node Kalman filter vectors dimensions
mini_ker.texi(,2933) @subsubsection Kalman filter vectors dimensions
mini_ker.texi(,2934) 
mini_ker.texi(,2935) @cindex error vector dimension
mini_ker.texi(,2936) @cindex @file{dimetaphi}, Kalman filter
mini_ker.texi(,2937) 
mini_ker.texi(,2938) These dimensions should be set in the @file{zinit} sequence.
mini_ker.texi(,2939) The size of the estimated states is given by the parameter @code{nkp}. 
mini_ker.texi(,2940) You can set this to @code{np} if all the states are estimated, but in case
mini_ker.texi(,2941) there are some deterministic state variables, @code{nkp} may be less than
mini_ker.texi(,2942) @code{np}. In that case the first @code{nkp} elements of @code{eta(.)}
mini_ker.texi(,2943) will be estimated using the Kalman filter.
mini_ker.texi(,2944) 
mini_ker.texi(,2945) The error on state dimension is associated with the parameter @code{nerrp}
mini_ker.texi(,2946) and the size of the observations vector is @code{mobs} 
mini_ker.texi(,2947) (@pxref{Observations}). In our example the dimensions are set with:
mini_ker.texi(,2948) 
mini_ker.texi(,2949) @example
mini_ker.texi(,2950) parameter (nkp=np);
mini_ker.texi(,2951) parameter (mobs=3);
mini_ker.texi(,2952) parameter (nerrp=2);
mini_ker.texi(,2953) @end example
mini_ker.texi(,2954) 
mini_ker.texi(,2955) All the states are estimated,
mini_ker.texi(,2956) there are 3 observation functions and the error on the state vector is of
mini_ker.texi(,2957) dimension 2.
mini_ker.texi(,2958) 
mini_ker.texi(,2959) If the sizes are set explicitely, the parameters should be set in
mini_ker.texi(,2960) @file{dimetaphi}.
mini_ker.texi(,2961) 
mini_ker.texi(,2962) @node Error and observation matrices
mini_ker.texi(,2963) @subsubsection Error and observation matrices
mini_ker.texi(,2964) 
mini_ker.texi(,2965) @cindex variance-covariance matrices
mini_ker.texi(,2966) @cindex observations
mini_ker.texi(,2967) @cindex @file{zinit}, Kalman filter
mini_ker.texi(,2968) 
mini_ker.texi(,2969) @subsubheading Initial variance-covariance matrix on the state
mini_ker.texi(,2970) 
mini_ker.texi(,2971) @cindex initial variance-covariance on states
mini_ker.texi(,2972) @vindex covfor(.,.)
mini_ker.texi(,2973) 
mini_ker.texi(,2974) The variance-covariance on the state matrix is @code{covfor(.,.)}. The initial
mini_ker.texi(,2975) values have to be given for this matrix, as in our example:
mini_ker.texi(,2976) 
mini_ker.texi(,2977) @example
mini_ker.texi(,2978) covfor(1,1) = 1000.; covfor(1,2) = 10.; covfor(1,3) = 10.;
mini_ker.texi(,2979) covfor(2,1) = 10.; covfor(2,2) = 5000.; covfor(2,3) = 5.;
mini_ker.texi(,2980) covfor(3,1) = 10.; covfor(3,2) = 5.; covfor(3,3) = 2000.;
mini_ker.texi(,2981) @end example
mini_ker.texi(,2982) 
mini_ker.texi(,2983) This matrix is updated by the filter at each time step because the states
mini_ker.texi(,2984) are pertubated by some noise, and when assimilation takes place as new
mini_ker.texi(,2985) information reduce the error.
mini_ker.texi(,2986) 
mini_ker.texi(,2987) @subsubheading Observations and error on state matrix
mini_ker.texi(,2988) 
mini_ker.texi(,2989) @cindex variance-covariance matrix on state
mini_ker.texi(,2990) @vindex mereta(.,.)
mini_ker.texi(,2991) 
mini_ker.texi(,2992) The matrix that relates errors on states vector components to states,
mini_ker.texi(,2993) corresponding with @math{W} is @code{mereta(.,.)}. In our example it is 
mini_ker.texi(,2994) set by:
mini_ker.texi(,2995) 
mini_ker.texi(,2996) @example
mini_ker.texi(,2997) mereta(1,1) = 1.;  mereta(1,2) = 0.;
mini_ker.texi(,2998) mereta(2,1) = 0.;  mereta(2,2) = 1.;
mini_ker.texi(,2999) mereta(3,1) = 0.5;  mereta(3,2) = 0.5;
mini_ker.texi(,3000) @end example
mini_ker.texi(,3001) 
mini_ker.texi(,3002) The observation functions are set by a @code{f_set} macro with 
mini_ker.texi(,3003) @code{Obs_tef(.)} as described in @ref{Observations}.
mini_ker.texi(,3004) In our example the observation functions are set by:
mini_ker.texi(,3005) 
mini_ker.texi(,3006) @example
mini_ker.texi(,3007) f_set Obs_tef(1) = ff(1) ;
mini_ker.texi(,3008) f_set Obs_tef(2) = eta(2);
mini_ker.texi(,3009) f_set Obs_tef(3) = eta(3);
mini_ker.texi(,3010) @end example
mini_ker.texi(,3011) 
mini_ker.texi(,3012) @subsubheading Error variance-covariance matrices
mini_ker.texi(,3013) 
mini_ker.texi(,3014) @cindex variance-covariance error
mini_ker.texi(,3015) @vindex covobs(.,.)
mini_ker.texi(,3016) 
mini_ker.texi(,3017) The variance-covariance matrix on observation noise is @code{covobs(.,.)}
mini_ker.texi(,3018) set, in our example, by:
mini_ker.texi(,3019) 
mini_ker.texi(,3020) @example
mini_ker.texi(,3021) covobs(1,1) = 0.3; covobs(1,2) = 0.; covobs(1,3) = 0.;
mini_ker.texi(,3022) covobs(2,1) = 0.; covobs(2,2) = 0.1; covobs(2,3) = 0.;
mini_ker.texi(,3023) covobs(3,1) = 0.; covobs(3,2) = 0.; covobs(3,3) = 0.2;
mini_ker.texi(,3024) @end example
mini_ker.texi(,3025) 
mini_ker.texi(,3026) @vindex coveta(.,.)
mini_ker.texi(,3027) The variance-covariance matrix on state noise is @code{coveta(.,.)}
mini_ker.texi(,3028) set, in our example, by:
mini_ker.texi(,3029) 
mini_ker.texi(,3030) @example
mini_ker.texi(,3031) coveta(1,1) = 0.2; coveta(1,2) = 0.001;
mini_ker.texi(,3032) coveta(2,1) = 0.001; coveta(2,2) = 0.1;
mini_ker.texi(,3033) @end example
mini_ker.texi(,3034) 
mini_ker.texi(,3035) These matrices are not changed during the run of the model as part
mini_ker.texi(,3036) of the filtering process. They may be changed by the user in @file{zsteer}.
mini_ker.texi(,3037) 
mini_ker.texi(,3038) @node Kalman filter run and output
mini_ker.texi(,3039) @subsection Kalman filter run and output
mini_ker.texi(,3040) 
mini_ker.texi(,3041) @menu
mini_ker.texi(,3042) * Feeding the observations::
mini_ker.texi(,3043) * Kalman filter results::
mini_ker.texi(,3044) @end menu
mini_ker.texi(,3045) 
mini_ker.texi(,3046) @node Feeding the observations
mini_ker.texi(,3047) @subsubsection Feeding the observations to the model
mini_ker.texi(,3048) 
mini_ker.texi(,3049) @vindex vobs(.)
mini_ker.texi(,3050) @vindex zgetobs
mini_ker.texi(,3051) @cindex @file{zsteer}, Kalman filter
mini_ker.texi(,3052) 
mini_ker.texi(,3053) The observations must be made available to the model during the run. These
mini_ker.texi(,3054) observations are set in the @code{vobs(.)} array, and the assimilation 
mini_ker.texi(,3055) (also called the analysis step of the filter) takes
mini_ker.texi(,3056) place if the logical variable @code{zgetobs} is @code{.true.} 
mini_ker.texi(,3057) (@pxref{Data}). 
mini_ker.texi(,3058) 
mini_ker.texi(,3059) These steps are
mini_ker.texi(,3060) typically performed in the @file{zsteer} sequence. In this sequence there should
mini_ker.texi(,3061) be some code such that when there are data ready to
mini_ker.texi(,3062) be assimilated, @code{zgetobs} is set to @code{.true.} and the data is
mini_ker.texi(,3063) stored in @code{vobs(.)}, ready for the next step processing.
mini_ker.texi(,3064) 
mini_ker.texi(,3065) @node Kalman filter results
mini_ker.texi(,3066) @subsubsection Kalman filter results
mini_ker.texi(,3067) 
mini_ker.texi(,3068) @cindex results, Kalman filter
mini_ker.texi(,3069) @cindex Kalman filter results
mini_ker.texi(,3070) @cindex output, Kalman filter
mini_ker.texi(,3071) @cindex Kalman filter output
mini_ker.texi(,3072) @cindex @file{data.data}
mini_ker.texi(,3073) 
mini_ker.texi(,3074) The estimated states and transfers are still in the same @samp{.data} files, 
mini_ker.texi(,3075) @file{res.data} and @file{tr.data} and there is the additional file with
mini_ker.texi(,3076) observations, called @file{obs.data} (@pxref{Observations}). 
mini_ker.texi(,3077) Each time @code{zgetobs} is @code{.true.} the data, and the optimally 
mini_ker.texi(,3078) weighted innovations are output 
mini_ker.texi(,3079) in the file associated with data, @file{data.data} (@pxref{Data}).
mini_ker.texi(,3080) 
mini_ker.texi(,3081) @node Executing code after the analysis
mini_ker.texi(,3082) @subsection Executing code after the analysis
mini_ker.texi(,3083) 
mini_ker.texi(,3084) The analysis takes place before the time step advance when @code{zgetobs}
mini_ker.texi(,3085) is @code{.true.}. It may be usefull to add some code after the analysis
mini_ker.texi(,3086) and before the time step advance. For example the analysis may lead to 
mini_ker.texi(,3087) absurd values for some states or parameters, it could be usefull to correct
mini_ker.texi(,3088) them in that case. The sequence included after the analysis is called
mini_ker.texi(,3089) @file{kalsteer}. At this point, in addition to the usual variables 
mini_ker.texi(,3090) the following variables could be usefull:
mini_ker.texi(,3091) 
mini_ker.texi(,3092) @vtable @code
mini_ker.texi(,3093) @item etafor(.)
mini_ker.texi(,3094) The state before the analysis.
mini_ker.texi(,3095) @item kgain(.)
mini_ker.texi(,3096) The Kalman gain.
mini_ker.texi(,3097) @item innobs(.)
mini_ker.texi(,3098) The innovation vector (observations coherent with the states minus data
mini_ker.texi(,3099) values).
mini_ker.texi(,3100) @item covana(.,.)
mini_ker.texi(,3101) The variance-covariance error matrix after the analysis.
mini_ker.texi(,3102) @end vtable
mini_ker.texi(,3103) 
mini_ker.texi(,3104) At each time step the derivative of the observation function with respect
mini_ker.texi(,3105) to transfer and cells variables are recomputed. The elimination of
mini_ker.texi(,3106) transfers is also performed to get the partial derivative of the observation
mini_ker.texi(,3107) function of the equivalent model, with states only, with respect to the 
mini_ker.texi(,3108) states. In other words, the Kalman filter does not follow the TEF formalism, because
mini_ker.texi(,3109) the advance of the var-covar matrix could not yet be set in the TEF form.
mini_ker.texi(,3110) @c There is a corresponding additional matrix:
mini_ker.texi(,3111) 
mini_ker.texi(,3112) @vtable @code
mini_ker.texi(,3113) @c @item obetad(.,.)
mini_ker.texi(,3114) @c derivative of observation function with respect to transfers.
mini_ker.texi(,3115) @c @item obphid(.,.)
mini_ker.texi(,3116) @c derivative of observation function with respect to cell variables.
mini_ker.texi(,3117) @item obspha(.,.)
mini_ker.texi(,3118) derivative of observation function in state space with respect to
mini_ker.texi(,3119) cell variables.
mini_ker.texi(,3120) @end vtable
mini_ker.texi(,3121) 
mini_ker.texi(,3122) 
mini_ker.texi(,3123) @node Feedback gain
mini_ker.texi(,3124) @section Feedback gain
mini_ker.texi(,3125) 
mini_ker.texi(,3126) 
mini_ker.texi(,3127) @cindex Borel sweep
mini_ker.texi(,3128) @cindex Feedback gain
mini_ker.texi(,3129) 
mini_ker.texi(,3130) The feedback dynamic gain associated with a feedback loop
mini_ker.texi(,3131) can be expressed as the inverse Borel 
mini_ker.texi(,3132) transform of the coefficient of the reduced scalar 
mini_ker.texi(,3133) coupling matrix, @math{g(\tau)},
mini_ker.texi(,3134) associated with a transfer. 
mini_ker.texi(,3135) A Borel sweep provides this @math{g(\tau)}. Therefore it is
mini_ker.texi(,3136) an interesting tool for the characterization of the feedback loop@footnote{
mini_ker.texi(,3137) More generally, the Borel sweep allows 
mini_ker.texi(,3138) the numerical study of the dependency in @math{\tau} of the Borel transform 
mini_ker.texi(,3139) of various coefficients in the system coupling  matrix.}. 
mini_ker.texi(,3140) 
mini_ker.texi(,3141) As explained in the 
mini_ker.texi(,3142) ZOOM web page document 
mini_ker.texi(,3143) @url{http://www.lmd.jussieu.fr/@/ZOOM/doc/@/Feedback_Gain.pdf},
mini_ker.texi(,3144) this allows for the calculation of the
mini_ker.texi(,3145) dynamic gain and factor of any feedback that goes through a unique
mini_ker.texi(,3146) transfer variable. An example of the conclusions that can be drawn from such
mini_ker.texi(,3147) an analysis is provided in the same document.
mini_ker.texi(,3148) 
mini_ker.texi(,3156) 
mini_ker.texi(,3157) 
mini_ker.texi(,3158) For linear systems -- whose GTLS are autonomous along the whole trajectory -- 
mini_ker.texi(,3159) the @math{\tau} function of the
mini_ker.texi(,3160) feedback gain is independent of the position on the system trajectory. 
mini_ker.texi(,3161) But in general it is dependant, and one can analyse the function 
mini_ker.texi(,3162) @math{g(\tau;t)} defined on a segment @math{t} of the trajectory.
mini_ker.texi(,3163) 
mini_ker.texi(,3164) The document introducing the TEF-ZOOM technique explains how a Crank-Nicolson
mini_ker.texi(,3165) scheme for the time discretisation
mini_ker.texi(,3166) symbolically gives the solution of the Borel transform of the system. One can
mini_ker.texi(,3167) identify the @code{dt} variable with the Borel @math{\tau} within a 
mini_ker.texi(,3168) factor @math{2}. Hence, to numerically study the @math{\tau} dependency of 
mini_ker.texi(,3169) the transform of various coefficients in the system coupling  matrix at one 
mini_ker.texi(,3170) point in time, one can calculate the Borel transform of the TLS solutions 
mini_ker.texi(,3171) by making a time-step sweep.
mini_ker.texi(,3172) 
mini_ker.texi(,3173) The function @math{g(\tau;t)} is simply output for the feedback gain 
mini_ker.texi(,3174) attached to a unique @code{ff(k)} transfer variable. 
mini_ker.texi(,3175) All the relevant informations should be entered in the @file{zinit} sequence.
mini_ker.texi(,3176) 
mini_ker.texi(,3177) @menu
mini_ker.texi(,3178) * Specifying the Borel sweep::
mini_ker.texi(,3179) * Borel sweep results::
mini_ker.texi(,3180) @end menu
mini_ker.texi(,3181) 
mini_ker.texi(,3182) @node Specifying the Borel sweep
mini_ker.texi(,3183) @subsection Specifying the Borel sweep
mini_ker.texi(,3184) 
mini_ker.texi(,3185) @vindex ZBorel
mini_ker.texi(,3186) 
mini_ker.texi(,3187) First of all the logical flag @code{ZBorel} should be raised:
mini_ker.texi(,3188) 
mini_ker.texi(,3189) @example
mini_ker.texi(,3190) ZBorel=.true.;
mini_ker.texi(,3191) @end example
mini_ker.texi(,3192) 
mini_ker.texi(,3193) @vindex index_ff_gain
mini_ker.texi(,3194) The index of the studied transfer is given in the @code{index_ff_gain}
mini_ker.texi(,3195) variable
mini_ker.texi(,3196) @example
mini_ker.texi(,3197) index_ff_gain=7;
mini_ker.texi(,3198) @end example
mini_ker.texi(,3199) 
mini_ker.texi(,3200) At each time step a Borel sweep may be performed. The time steps of interest 
mini_ker.texi(,3201) are
mini_ker.texi(,3202) specified with three variables, one for the first step, one for the last step
mini_ker.texi(,3203) and one for the number of steps between two Borel sweeps:
mini_ker.texi(,3204) 
mini_ker.texi(,3205) @vtable @code
mini_ker.texi(,3206) @item istep_B_deb
mini_ker.texi(,3207) First time step for the Borel sweep.
mini_ker.texi(,3208) @item  istep_B_fin
mini_ker.texi(,3209) Last time step for the Borel sweep.
mini_ker.texi(,3210) @item istep_B_inc
mini_ker.texi(,3211) Number of time steps between Borel sweeps.
mini_ker.texi(,3212) @end vtable
mini_ker.texi(,3213) 
mini_ker.texi(,3214) In the following examples Borel sweeps are performed from the 
mini_ker.texi(,3215) time step 1000 up to the time step 1200, with a sweep at each time step:
mini_ker.texi(,3216) @example
mini_ker.texi(,3217) istep_B_deb=1000;   
mini_ker.texi(,3218) istep_B_fin=1200;  
mini_ker.texi(,3219) istep_B_inc=1;      
mini_ker.texi(,3220) @end example
mini_ker.texi(,3221) 
mini_ker.texi(,3222) 
mini_ker.texi(,3223) For each Borel sweep, the range of the @math{\tau} variable should be 
mini_ker.texi(,3224) set. As this is a multiplicative variable the initial value, a multiplicative
mini_ker.texi(,3225) factor and the number of values are to be given.
mini_ker.texi(,3226) 
mini_ker.texi(,3227) @vtable @code
mini_ker.texi(,3228) @item tau_B_ini
mini_ker.texi(,3229) Initial value for @math{\tau}.
mini_ker.texi(,3230) @item tau_B_mult
mini_ker.texi(,3231) Multiplicative factor for sweep in @math{tau}.
mini_ker.texi(,3232) @item itau_max
mini_ker.texi(,3233) Number of @math{\tau} values.
mini_ker.texi(,3234) @end vtable
mini_ker.texi(,3235) 
mini_ker.texi(,3236) For example, in the following, at each time step, the Borel
mini_ker.texi(,3237) transform will be computed for @math{\tau} values
mini_ker.texi(,3238) starting at @math{0.2} and then multiplied a hundred times by @math{\sqrt{\sqrt{2}}}
mini_ker.texi(,3239) 
mini_ker.texi(,3240) @example
mini_ker.texi(,3241) tau_B_ini=0.2;    
mini_ker.texi(,3242) tau_B_mult=sqrt(sqrt(2.)); 
mini_ker.texi(,3243) itau_max=100;             
mini_ker.texi(,3244) @end example
mini_ker.texi(,3245) 
mini_ker.texi(,3246) When the initial value of @math{\tau} is set to a negative value 
mini_ker.texi(,3247) (@i{i.e.} @code{tau_B_ini=-0.2;}),
mini_ker.texi(,3248) the Borel sweep will first be applied with @code{itau_max} negative values 
mini_ker.texi(,3249) for @code{-0.2}, @code{tau_B_mult*(-0.2)},..., then for the zero value, 
mini_ker.texi(,3250) and finally for the symetric positive values, resulting in @code{2*itau_max+1} 
mini_ker.texi(,3251) values for @math{\tau}.
mini_ker.texi(,3252) 
mini_ker.texi(,3253) The whole example reads
mini_ker.texi(,3254) 
mini_ker.texi(,3255) @example
mini_ker.texi(,3256) ! -------------------
mini_ker.texi(,3257) ! Feedback gain
mini_ker.texi(,3258) ! Borel
mini_ker.texi(,3259) ! -------------------
mini_ker.texi(,3260) ZBorel=.true.;
mini_ker.texi(,3261) if ZBorel           
mini_ker.texi(,3262) <  istep_B_deb=1000; 
mini_ker.texi(,3263)    istep_B_fin=1200;
mini_ker.texi(,3264)    istep_B_inc=1;  
mini_ker.texi(,3265) ;
mini_ker.texi(,3266)    index_ff_gain=7; 
mini_ker.texi(,3267)    tau_B_ini=0.2;    
mini_ker.texi(,3268)    tau_B_mult=sqrt(sqrt(2.)); 
mini_ker.texi(,3269)    itau_max=100;             
mini_ker.texi(,3270)    z_pr/Borel/:tau_B_mult,tau_B_ini*(tau_B_mult)**itau_max;
mini_ker.texi(,3271) >;
mini_ker.texi(,3272) @end example
mini_ker.texi(,3273) 
mini_ker.texi(,3274) @findex zborel for
mini_ker.texi(,3275) 
mini_ker.texi(,3276) Instead of using the index of the transfer in @code{index_ff_gain} it is 
mini_ker.texi(,3277) possible to specify the name of the transfer.@c , whenever 
mini_ker.texi(,3278) @c the symbolic model description is used (@pxref{Symbolic model description}). 
mini_ker.texi(,3279) In that case the transfer is specified
mini_ker.texi(,3280) by the @code{zborel for} macro. For example if the transfer selected for the
mini_ker.texi(,3281) feedback gain computation is @var{b_transfer}, it can be selected
mini_ker.texi(,3282) with:
mini_ker.texi(,3283) 
mini_ker.texi(,3284) @example
mini_ker.texi(,3285) zborel for: @var{b_transfer};
mini_ker.texi(,3286) @end example
mini_ker.texi(,3287) 
mini_ker.texi(,3288) @node Borel sweep results
mini_ker.texi(,3289) @subsection Borel sweep results
mini_ker.texi(,3290) 
mini_ker.texi(,3291) @cindex Borel sweep results
mini_ker.texi(,3292) @cindex results, Borel sweep
mini_ker.texi(,3293) @cindex Borel sweep graphics
mini_ker.texi(,3294) @cindex graphics, Borel sweep
mini_ker.texi(,3295) 
mini_ker.texi(,3296) The file @file{tau_Borel.data} gives the @math{\tau} values of the @var{tau} sweep, 
mini_ker.texi(,3297) and the file @file{gains.data} records the feedback gain function values of 
mini_ker.texi(,3298) @math{g(\tau)}, with 
mini_ker.texi(,3299) one line for each sweep along the trajectory. In the 1.01 version, a new
mini_ker.texi(,3300) feature is also provided giving the poles and residuals of the Borel
mini_ker.texi(,3301) transform in the file @file{vpgains.data}. Consult the subroutine 
mini_ker.texi(,3302) @code{Boreleig}
mini_ker.texi(,3303) for (not definitive) output description.
mini_ker.texi(,3304) 
mini_ker.texi(,3305) One can easily obtain the surface contours of @math{g(t,\tau)} using
mini_ker.texi(,3306) the Fortran program provided as @file{gains.f} and its compilation shell 
mini_ker.texi(,3307) @file{gains.xqt},
mini_ker.texi(,3308) that builds 2D histograms for PAW, in which one uses the
mini_ker.texi(,3309) @file{borels.kumac} provided kumac.
mini_ker.texi(,3310) 
mini_ker.texi(,3311) @node Stability of fastest modes
mini_ker.texi(,3312) @section Stability analysis of fastest modes
mini_ker.texi(,3313) 
mini_ker.texi(,3314) @cindex SVD
mini_ker.texi(,3315) @cindex Singular Value Decomposition
mini_ker.texi(,3316) @cindex state matrix
mini_ker.texi(,3317) @cindex @file{sltc.exe}
mini_ker.texi(,3318) 
mini_ker.texi(,3319) The preceding analyses are done along with a simulation. One has also the
mini_ker.texi(,3320) possibility of using in a more classical fashion the state advance matrix
mini_ker.texi(,3321) @math{A_{st}}, after the end of the simulation. Code to perform the 
mini_ker.texi(,3322) @acronym{SVD, Singular Value Decomposition} of the state matrix @math{A_{st}}
mini_ker.texi(Minik,3323) and also of @math{A_{st} + A_{st}^\dagger} is provided with Miniker.
mini_ker.texi(,3324) The singular elements of these two matrices correspond to the most
mini_ker.texi(,3325) rapid modes of instability of the perturbed system.
mini_ker.texi(,3326) 
mini_ker.texi(,3327) The Singular value decomposition of a matrix is noted
mini_ker.texi(,3328) 
mini_ker.texi(,3335) 
mini_ker.texi(,3336) @noindent @math{U w V^t}
mini_ker.texi(,3337) 
mini_ker.texi(,3339) 
mini_ker.texi(,3340) An executable file, @file{sltc.exe} is generated and running this file will
mini_ker.texi(,3341) produce the corresponding results.
mini_ker.texi(,3342) 
mini_ker.texi(,3343) @menu
mini_ker.texi(,3344) * SVD with cmz::
mini_ker.texi(,3345) * SVD with make::
mini_ker.texi(,3346) * SVD run and output::
mini_ker.texi(,3347) @end menu
mini_ker.texi(,3348) 
mini_ker.texi(,3349) @node SVD with cmz
mini_ker.texi(,3350) @subsection Singular Value Decomposition with cmz
mini_ker.texi(,3351) 
mini_ker.texi(,3352) @cindex @command{smod}
mini_ker.texi(,3353) 
mini_ker.texi(,3354) The cmz macro @code{smod SLTC} prepares a main program
mini_ker.texi(,3355) (@file{circul} of +PATCH SLTC), provided as a base for user's own analysis,
mini_ker.texi(,3356) in the directory @file{sltc/}.
mini_ker.texi(,3357) 
mini_ker.texi(,3358) @node SVD with make
mini_ker.texi(,3359) @subsection Singular Value Decomposition with make
mini_ker.texi(,3360) 
mini_ker.texi(,3361) @cindex @file{Makefile.sltc}
mini_ker.texi(,3362) 
mini_ker.texi(,3363) To compile the singular value decomposition executable with @command{make} you 
mini_ker.texi(,3364) can do
mini_ker.texi(,3365) @example
mini_ker.texi(,3366) make sltc.exe
mini_ker.texi(,3367) @end example
mini_ker.texi(,3368) 
mini_ker.texi(,3369) If you want to have a separate directory for the SVD, you should copy 
mini_ker.texi(,3370) the sequence @file{dimetaphi.inc} (or make a link to that file) to the
mini_ker.texi(,3371) directory. You should also copy the file @file{Makefile.sltc} from the 
mini_ker.texi(,3372) @file{template/} directory in this directory, rename it @file{Makefile}
mini_ker.texi(Minik,3373) and set the Miniker directory path in the 
mini_ker.texi(,3374) @code{miniker_dir} variable. For
mini_ker.texi(Minik,3375) example, if the Miniker directory is in @file{/u/src/mini_ker}:
mini_ker.texi(,3376) 
mini_ker.texi(,3377) @example
mini_ker.texi(,3378) miniker_dir = /u/src/mini_ker
mini_ker.texi(,3379) @end example
mini_ker.texi(,3380) 
mini_ker.texi(,3381) @node SVD run and output
mini_ker.texi(,3382) @subsection Singular Value Decomposition run and output
mini_ker.texi(,3383) 
mini_ker.texi(,3384) @cindex SVD run
mini_ker.texi(,3385) @cindex run, SVD
mini_ker.texi(,3386) @cindex SVD output
mini_ker.texi(,3387) @cindex output, SVD
mini_ker.texi(,3388) @cindex @file{sltc.exe}
mini_ker.texi(,3389) @cindex @file{title.tex}, SVD
mini_ker.texi(,3390) @cindex @file{aspha.data}, SVD
mini_ker.texi(,3391) 
mini_ker.texi(,3392) As it is, the @file{sltc.exe} executable generated by the compilation 
mini_ker.texi(,3393) determines the SVD. This program requires @file{title.tex} (@pxref{Title file}) to
mini_ker.texi(,3394) transmit a title for output and graphics, and @file{aspha.data} 
mini_ker.texi(,3395) (@pxref{Simulation and output,,Running a simulation and using the output})
mini_ker.texi(,3396) to access the
mini_ker.texi(,3397) state matrix. To get access to these files (in case they are not in the current
mini_ker.texi(,3398) directory) it is possible to make a link to 
mini_ker.texi(,3399) the corresponding files in the model directory. Once it is done 
mini_ker.texi(,3400) the program may be run:
mini_ker.texi(,3401) 
mini_ker.texi(,3402) @example
mini_ker.texi(,3403) ./sltc.exe
mini_ker.texi(,3404) @end example
mini_ker.texi(,3405) 
mini_ker.texi(,3406) The files @file{u.data}, @file{w.data}, and @file{v.data} holds the singular elements 
mini_ker.texi(,3407) for @math{A_{st}} (@math{U}, @math{w} and @math{V}), 
mini_ker.texi(,3408) and @file{us.data}, @file{ws.data}, and @file{vs.data}
mini_ker.texi(,3409) holds the singular elements of @math{A_{st} + A_{st}^\dagger}.
mini_ker.texi(,3410) The corresponding macros @samp{.kumac} for PAW@footnote{Explanation in
mini_ker.texi(,3411) the research paper about SLTC (Al1 2003) available on request.} 
mini_ker.texi(,3412) are also generated.
mini_ker.texi(,3413) 
mini_ker.texi(,3414) @node Generalized TLS
mini_ker.texi(,3415) @section Generalized linear tangent system analysis
mini_ker.texi(,3416) 
mini_ker.texi(,3417) @cindex Generalized linear tangent system
mini_ker.texi(,3418) @cindex GTLS
mini_ker.texi(,3419) @cindex propagator
mini_ker.texi(,3420) @cindex Lyapunov exponents
mini_ker.texi(,3421) @cindex @file{sltcirc.exe}
mini_ker.texi(,3422) 
mini_ker.texi(,3423) The state matrix @math{A_{st}} may also be used to compute the
mini_ker.texi(,3424) GTLS propagator (or state transition matrix applied to perturbation), after the simulation.
mini_ker.texi(,3425) The algorithm is a finite product of 
mini_ker.texi(,3426) 5th order development of
mini_ker.texi(,3427) @math{\Phi(t+\delta t,t)=\exp{A_{st} \delta t}}.
mini_ker.texi(,3428) Numerous element of analysis are given, in particular the determination
mini_ker.texi(,3429) of the Lyapunov exponents of the system.
mini_ker.texi(,3430) 
mini_ker.texi(,3431) An executable file, @file{sltcirc.exe} is generated and running this file will
mini_ker.texi(,3432) produce the corresponding results.
mini_ker.texi(,3433) 
mini_ker.texi(,3434) @menu
mini_ker.texi(,3435) * GTLS with cmz::
mini_ker.texi(,3436) * GTLS with make::
mini_ker.texi(,3437) * GTLS run and output::
mini_ker.texi(,3438) @end menu
mini_ker.texi(,3439) 
mini_ker.texi(,3440) @node GTLS with cmz
mini_ker.texi(,3441) @subsection Generalized tangent linear system with cmz
mini_ker.texi(,3442) 
mini_ker.texi(,3443) @cindex @command{smod}
mini_ker.texi(,3444) 
mini_ker.texi(,3445) The cmz macro @code{smod SLTCIRC} prepares a main program
mini_ker.texi(,3446) (@file{circule} of +PATCH SLTCIRC), in the directory @file{sltcirc/}.
mini_ker.texi(,3447) 
mini_ker.texi(,3448) @node GTLS with make
mini_ker.texi(,3449) @subsection Generalized tangent linear system with make
mini_ker.texi(,3450) 
mini_ker.texi(,3451) @cindex @file{Makefile.sltcirc}
mini_ker.texi(,3452) 
mini_ker.texi(,3453) To compile the GTLS analysis executable with @command{make} you 
mini_ker.texi(,3454) can do
mini_ker.texi(,3455) @example
mini_ker.texi(,3456) make sltcirc.exe
mini_ker.texi(,3457) @end example
mini_ker.texi(,3458) 
mini_ker.texi(,3459) If you want to have a separate directory for the GTLS analysis, you should copy 
mini_ker.texi(,3460) the sequence @file{dimetaphi.inc} (or make a link to that file) to the
mini_ker.texi(,3461) directory. You should also copy the file @file{Makefile.sltcirc} from the 
mini_ker.texi(,3462) @file{template/} directory in this directory and  rename it @file{Makefile}
mini_ker.texi(Minik,3463) and set the Miniker directory path in the @code{miniker_dir} variable.
mini_ker.texi(,3464) 
mini_ker.texi(,3465) @node GTLS run and output
mini_ker.texi(,3466) @subsection Generalized tangent linear system analysis run and output
mini_ker.texi(,3467) 
mini_ker.texi(,3468) @cindex GTLS run
mini_ker.texi(,3469) @cindex run, GTLS
mini_ker.texi(,3470) @cindex GTLS output
mini_ker.texi(,3471) @cindex output, GTLS
mini_ker.texi(,3472) @cindex @file{sltcirc.exe}
mini_ker.texi(,3473) @cindex @file{title.tex}, GTLS
mini_ker.texi(,3474) @cindex @file{dres.data}, GTLS
mini_ker.texi(,3475) @cindex @file{aspha.data}, GTLS
mini_ker.texi(,3476) 
mini_ker.texi(,3477) The @file{sltcirc.exe} executable generated by the compilation 
mini_ker.texi(,3478) computes the elements of analysis of the system. This program requires 
mini_ker.texi(,3479) @file{title.tex} to
mini_ker.texi(,3480) transmit a title for output and graphics (@pxref{Title file}), 
mini_ker.texi(,3481) @file{aspha.data} to access the
mini_ker.texi(,3482) state matrix and @file{dres.data}, because time-step can be changed along the 
mini_ker.texi(,3483) simulation 
mini_ker.texi(,3484) (@pxref{Simulation and output,,Running a simulation and using the output})
mini_ker.texi(,3485) @footnote{cf our research texts about propagator analyses in
mini_ker.texi(,3486) SLTC, and ``les Gains sur champs (Al1 2003-2004)''}. To get access to these files 
mini_ker.texi(,3487) (in case they are not in the current
mini_ker.texi(,3488) directory) it is possible to make a link to 
mini_ker.texi(,3489) the corresponding files in the model directory. Once it is done 
mini_ker.texi(,3490) the program may be run:
mini_ker.texi(,3491) 
mini_ker.texi(,3492) @example
mini_ker.texi(,3493) ./sltcirc.exe
mini_ker.texi(,3494) @end example
mini_ker.texi(,3495) 
mini_ker.texi(,3496) The following table gives the correspondence between variable name, 
mini_ker.texi(,3497) result file and ntuple number, with a short explanation:
mini_ker.texi(,3498) 
mini_ker.texi(,3499) @multitable {@code{lwr(.,.)}} {@file{wlphit.data}} {ntuple} {eigen factors of @math{w} in the SVD of @math{\Phi}}
mini_ker.texi(,3500) @headitem var @tab file @tab ntuple @tab explanation
mini_ker.texi(,3501) @item @code{p(.,.)} @tab @file{phit.data} @tab 55 @tab propagator from 0 to @math{t}, @math{\Phi(t,0)}
mini_ker.texi(,3502) @item @code{up(.,.)} @tab @file{uphit.data} @tab 50 @tab Left singular vectors @math{U} in the SVD of @math{\Phi}
mini_ker.texi(,3503) @item @code{wp(.)} @tab @file{wphit.data} @tab 51 @tab singulat values @math{w} in the SVD of @math{\Phi}
mini_ker.texi(,3504) @item @code{vp(.,.)} @tab @file{vphit.data} @tab 52 @tab Right Singular Vectors @math{V} in the SVD of @math{\Phi}
mini_ker.texi(,3505) @item @code{wr(.)} @tab @file{wr.data} @tab 53  @tab real part of eigen values of @math{\Phi(t,0)}
mini_ker.texi(,3506) @item @code{wi(.)} @tab @file{wi.data} @tab 54  @tab imaginary part of eigen values of @math{\Phi(t,0)}
mini_ker.texi(,3507) @item @code{lwp(.)} @tab @file{lwphit.data} @tab 67  @tab Lyapunov exponents
mini_ker.texi(,3508) @c @item @code{lwr(.,.)} @tab @file{lwr.data} @tab 68  @tab
mini_ker.texi(,3509) @c @item @code{lwi(.,.)} @tab @file{lwi.data} @tab 69  @tab 
mini_ker.texi(,3510) @c @item @code{} @tab @file{.data} @tab  @tab
mini_ker.texi(,3511) @end multitable
mini_ker.texi(,3512) 
mini_ker.texi(,3541) 
mini_ker.texi(Minik,3542) @node  Advanced use of Miniker with make
mini_ker.texi(Minik,3543) @chapter Advanced use of Miniker with make
mini_ker.texi(,3544) 
mini_ker.texi(,3545) @menu
mini_ker.texi(,3546) * Make variables::
mini_ker.texi(,3547) * Rules::
mini_ker.texi(,3548) * Linking rule::
mini_ker.texi(,3549) @end menu
mini_ker.texi(,3550) 
mini_ker.texi(,3551) @node Make variables
mini_ker.texi(,3552) @section Make variables
mini_ker.texi(,3553) 
mini_ker.texi(,3554) @cindex @file{Makefile.miniker}
mini_ker.texi(,3555) 
mini_ker.texi(,3556) The @file{Makefile.miniker} Makefile provided in the
mini_ker.texi(,3557) distribution should be included as it defines a lot of important 
mini_ker.texi(,3558) variables and rules. 
mini_ker.texi(,3559) 
mini_ker.texi(,3560) The following make variables can be set by the user:
mini_ker.texi(,3561) 
mini_ker.texi(,3562) @table @code
mini_ker.texi(,3563) @item miniker_dir
mini_ker.texi(Minik,3564) that variable should hold the Miniker sources directory. If you installed
mini_ker.texi(Minik,3565) Miniker that variable should be set to @file{$(includedir)/mini_ker}. 
mini_ker.texi(,3566) If you use the sources right from the sources directory it should be set to 
mini_ker.texi(,3567) the sources package directory.
mini_ker.texi(,3568) @item MTNDIRS
mini_ker.texi(,3569) This variable can hold a @samp{:} delimited list of directories that will
mini_ker.texi(,3570) be searched for mortran include files.
mini_ker.texi(,3571) @item CMFDIRS
mini_ker.texi(,3572) This variable can hold a @samp{:} delimited list of directories that will
mini_ker.texi(,3573) be searched for cmz directive include files.
mini_ker.texi(,3574) @item SEL
mini_ker.texi(,3575) This variable holds a @samp{,} delimited list of select flags, for example
mini_ker.texi(,3576) @code{monitor}, @code{grid1d}, @code{debug}.
mini_ker.texi(,3577) @item LDADD
mini_ker.texi(,3578) This variable can be used to add libraries flags and files. It is used in 
mini_ker.texi(,3579) the default linking command/rule.
mini_ker.texi(,3580) @item miniker_user_objects
mini_ker.texi(,3581) This variable should hold a space separated list of additional object files
mini_ker.texi(,3582) to be linked with the model and helper object files.
mini_ker.texi(,3583) @item CAR2TXTFLAGS
mini_ker.texi(,3584) cmz directives preprocessor flag.
mini_ker.texi(,3585) @item kalman
mini_ker.texi(,3586) This variable should be set to 1 if you want to use the kalman filter
mini_ker.texi(,3587) (@pxref{Kalman filter}).
mini_ker.texi(,3588) @item double
mini_ker.texi(,3589) This variable should be set to 1 if you want to have a double precision
mini_ker.texi(,3590) code (@pxref{Double precision}).
mini_ker.texi(,3591) @end table
mini_ker.texi(,3592) 
mini_ker.texi(,3593) The following variables are allready set and may be used
mini_ker.texi(,3594) (some are set by ./configure see @ref{Configuration}):
mini_ker.texi(,3595) 
mini_ker.texi(,3596) @table @code
mini_ker.texi(,3597) @item miniker_principal_objects
mini_ker.texi(,3598) The list of object files needed for the model build, together with some 
mini_ker.texi(,3599) helper object files often used but not strictly required for the linking.
mini_ker.texi(,3600) @item DEPDIR
mini_ker.texi(,3601) The name of a hidden directory containing the dependencies computed
mini_ker.texi(,3602) for the main mortran files.
mini_ker.texi(,3603) @itemx F77
mini_ker.texi(,3604) @itemx FC
mini_ker.texi(,3605) @itemx FFLAGS
mini_ker.texi(,3606) @item LDFLAGS
mini_ker.texi(,3607) Compiler and linker related variables set by ./configure.
mini_ker.texi(,3608) @item LIBS
mini_ker.texi(,3609) This variable should hold the link flags and files required to build 
mini_ker.texi(Minik,3610) Miniker, set by ./configure.
mini_ker.texi(,3611) @item CAR2TXT
mini_ker.texi(,3612) @itemx MORTRAN
mini_ker.texi(,3613) @itemx MTNFLAGS
mini_ker.texi(,3614) @itemx MTNDEPEND
mini_ker.texi(,3615) Preprocessor and preprocessor flags, set by ./configure.
mini_ker.texi(,3616) @end table
mini_ker.texi(,3617) 
mini_ker.texi(,3618) @node Rules
mini_ker.texi(,3619) @section Rules
mini_ker.texi(,3620) 
mini_ker.texi(,3621) The following rules are defined in the @file{Makefile.miniker} file.
mini_ker.texi(,3622) @table @code
mini_ker.texi(,3623) @item miniker-clean
mini_ker.texi(,3624) remove the fortran files generated from the mortran files. Remove 
mini_ker.texi(,3625) the object files.
mini_ker.texi(,3626) @item miniker-mtn-clean
mini_ker.texi(,3627) remove the mortran files generated from the files with cmz directives.
mini_ker.texi(,3628) @item 
mini_ker.texi(,3629) Various rules to preprocess files with cmz directives and mortran files and
mini_ker.texi(,3630) to compile fortran files.
mini_ker.texi(,3631) @end table
mini_ker.texi(,3632) 
mini_ker.texi(,3633) If the user needs a mortran main file, he may take advantage of the rule
mini_ker.texi(,3634) used to compute the dependencies of a mortran file. If the file is called,
mini_ker.texi(,3635) say, @file{mtnfile.mtn} leading to @file{mtnfile.f}, the following include
mini_ker.texi(,3636) should lead to the automatic creation, updating and inclusion of a 
mini_ker.texi(,3637) file describing the dependencies of @file{mtnfile.mtn} in the 
mini_ker.texi(,3638) @file{Makefile}:
mini_ker.texi(,3639) 
mini_ker.texi(,3640) @example
mini_ker.texi(,3641) include $(DEPDIR)/mtnfile.Pf
mini_ker.texi(,3642) @end example
mini_ker.texi(,3643) 
mini_ker.texi(,3644) @node Linking rule
mini_ker.texi(,3645) @section Linking rule
mini_ker.texi(,3646) 
mini_ker.texi(,3647) The rule used for the linking of the model file is not in the 
mini_ker.texi(,3648) @file{Makefile.miniker} file but 
mini_ker.texi(,3649) should be provided in the user @file{Makefile} for more flexibility. 
mini_ker.texi(,3650) The default rule 
mini_ker.texi(,3651) uses the variables @code{miniker_user_objects} for additional object files
mini_ker.texi(,3652) and @code{LDADD} for additionnal linking flags and files, those 
mini_ker.texi(,3653) variables are there to be changed by the user.
mini_ker.texi(,3654) 
mini_ker.texi(Minik,3655) The object files required by the Miniker code are in the make variable
mini_ker.texi(,3656) @code{miniker_principal_objects}, this variable is also used. 
mini_ker.texi(,3657) The value of the variables @code{FC}
mini_ker.texi(,3658) for the Fortran compiler, @code{FFLAGS} for the Fortran compiler
mini_ker.texi(,3659) flags and @code{LDFLAGS} for the linker flags should be set to right
mini_ker.texi(,3660) values; @code{LIBS} should also be right and hold the link flags and link
mini_ker.texi(Minik,3661) files required to compile the Miniker model. These variables are 
mini_ker.texi(,3662) set by by @command{./configure} during configuration (@pxref{Configuration}) 
mini_ker.texi(,3663) and used in the default rule: 
mini_ker.texi(,3664) 
mini_ker.texi(,3665) @verbatim
mini_ker.texi(,3666) $(model_file): $(miniker_user_objects) $(miniker_principal_objects)
mini_ker.texi(,3667) 	$(FC) $(FFLAGS) $(LDFLAGS) $^ $(LDADD) $(LIBS) -o $@
mini_ker.texi(,3668) @end verbatim
mini_ker.texi(,3669) 
mini_ker.texi(,3670) In case this isn't right it may be freely changed. You should certainly 
mini_ker.texi(,3671) refer to the @ref{Top,,Top,make,GNU Make Manual} manual to understand what
mini_ker.texi(,3672) that rule exactly means and make your own.
mini_ker.texi(,3673) 
mini_ker.texi(,3674) 
mini_ker.texi(,3675) @node Concepts index
mini_ker.texi(,3676) @unnumbered Concepts index
mini_ker.texi(,3677) 
mini_ker.texi(,3678) @printindex cp
mini_ker.texi(,3679) 
mini_ker.texi(,3680) @node Variables macros and functions index
mini_ker.texi(,3681) @unnumbered Variables, macros and functions index
mini_ker.texi(,3682) 
mini_ker.texi(,3683) @printindex vr
mini_ker.texi(,3684) 
mini_ker.texi(,3685) @node Installation
mini_ker.texi(,3686) @appendix Installation
mini_ker.texi(,3687) 
mini_ker.texi(,3688) @menu
mini_ker.texi(,3689) * Programming environments::
mini_ker.texi(,3690) * Common requisites::
mini_ker.texi(Minik,3691) * Miniker with cmz::
mini_ker.texi(Minik,3692) * Miniker with make::
mini_ker.texi(,3693) @end menu
mini_ker.texi(,3694) 
mini_ker.texi(,3695) @node Programming environments
mini_ker.texi(,3696) @appendixsec Programming environments
mini_ker.texi(,3697) @cindex Programming environments
mini_ker.texi(,3698) 
mini_ker.texi(Minik,3699) Miniker is not a traditionnal software in that it isn't a library
mini_ker.texi(,3700) or an interpreter but rather a set of source and macro file that 
mini_ker.texi(,3701) combines with the user model code and enable
mini_ker.texi(,3702) to build a binary program corresponding with the model. It
mini_ker.texi(,3703) requires a build environment with a preprocessor, a compiler
mini_ker.texi(,3704) and facilities that automate these steps.
mini_ker.texi(,3705) 
mini_ker.texi(,3706) Two different environment are proposed. One use
mini_ker.texi(,3707) @command{cmz} (@url{http://wwwcmz.web.cern.ch/@/wwwcmz/index.html}),
mini_ker.texi(,3708) while the other is based on @command{make}. Other libraries
mini_ker.texi(,3709) are needed, the CERN Program Library (cernlib) and lapack.
mini_ker.texi(,3710) 
mini_ker.texi(,3711) @node Common requisites
mini_ker.texi(,3712) @appendixsec Common requisites
mini_ker.texi(,3713) 
mini_ker.texi(,3714) @cindex cernlib
mini_ker.texi(,3715) @cindex lapack
mini_ker.texi(,3716) 
mini_ker.texi(,3717) Whatever method is used a fortran 77 compiler is required. The compilers
mini_ker.texi(,3718) that have been used so far are g77, gfortran and the sun solaris compiler.
mini_ker.texi(,3719) 
mini_ker.texi(,3720) When usng CMZ, the CERN Program Library, available at
mini_ker.texi(,3721) @url{http://wwwasd.web.cern.ch/@/wwwasd/cernlib/}, has to be installed.
mini_ker.texi(,3722) With make, internal source files copied from the cernlib may be used instead
mini_ker.texi(,3723) but then some examples won't be available, since they rely on some
mini_ker.texi(,3724) mathematical functions provided by the CERN library.
mini_ker.texi(,3725) On windows, in case you want to use the compiler from the GNU compiler 
mini_ker.texi(,3726) collection with cygwin or MINGW/MSYS you can use the binaries provided at
mini_ker.texi(,3727) @url{http://zyao.home.cern.ch/@/zyao/cernlib.html}.
mini_ker.texi(,3728) On Mac OS X, the cernlib provided by fink (package @code{cernlib-devel})
mini_ker.texi(,3729) can be used.
mini_ker.texi(,3730) 
mini_ker.texi(,3731) You should also have LAPACK, available at @url{http://www.netlib.org/@/lapack/}.
mini_ker.texi(,3732) LAPACK can also be installed as part of the CERN Library or as part of
mini_ker.texi(,3733) the @uref{ATLAS,http://math-atlas.sourceforge.net/} implementation.
mini_ker.texi(,3734) On most linux distributions a lapack package is available.
mini_ker.texi(,3735) On Mac OS X, the ATLAS implementation provided by fink or the frameworks
mini_ker.texi(,3736) from Xcode can be used.
mini_ker.texi(,3737) 
mini_ker.texi(,3738) 
mini_ker.texi(Minik,3739) @node Miniker with cmz
mini_ker.texi(Minik,3740) @appendixsec Miniker with cmz
mini_ker.texi(,3741) 
mini_ker.texi(,3742) @cindex @file{mini_ker.cmz}
mini_ker.texi(,3743) @cindex @file{selseq.kumac}
mini_ker.texi(,3744) 
mini_ker.texi(,3745) First of all you have to get the cmz file @file{mini_ker.cmz} and put it
mini_ker.texi(,3746) in a directory. In that same directory you should create a directory for
mini_ker.texi(,3747) each of your models. In the model directory you should copy the file 
mini_ker.texi(Minik,3748) @file{selseq.kumac} available with Miniker, and create your own cmz 
mini_ker.texi(,3749) file for your model, called for example @file{mymodel.cmz}. You should also 
mini_ker.texi(,3750) have installed the kumac macro files
mini_ker.texi(,3751) handling mortan compilation, the associated shell scripts and the mortran
mini_ker.texi(,3752) preprocessor.
mini_ker.texi(,3753) 
mini_ker.texi(Minik,3754) @node Miniker with make
mini_ker.texi(Minik,3755) @appendixsec Miniker with make
mini_ker.texi(,3756) 
mini_ker.texi(,3757) @menu
mini_ker.texi(,3758) * Additional requirements::
mini_ker.texi(,3759) * Configuration::
mini_ker.texi(,3760) * Installation with make::
mini_ker.texi(,3761) @end menu
mini_ker.texi(,3762) 
mini_ker.texi(,3763) @node Additional requirements
mini_ker.texi(Minik,3764) @appendixsubsec Additional requirements for Miniker with make
mini_ker.texi(,3765) 
mini_ker.texi(,3766) @cindex @command{mortran}, with make
mini_ker.texi(,3767) @cindex requirements, with make
mini_ker.texi(,3768) 
mini_ker.texi(,3769) The package has been tested with GNU @command{make} and solaris
mini_ker.texi(,3770) @command{make}. 
mini_ker.texi(,3771) 
mini_ker.texi(,3772) Suitable preprocessors should also be installed. Two preprocessors are 
mini_ker.texi(,3773) required, one that preprocess the cmz directives, and a mortran 
mini_ker.texi(,3774) preprocessor. A cmz directives processor written in @command{perl},
mini_ker.texi(,3775) is distributed in the @command{car2txt} package available at
mini_ker.texi(,3776) @url{http://www.environnement.ens.fr/@/perso/@/dumas/@/mini_ker/@/software.html}. A @command{mortran}
mini_ker.texi(,3777) package with a command able to preprocess a mortran file given on
mini_ker.texi(,3778) the command line with a syntax similar with the @command{cpp} command line 
mini_ker.texi(,3779) syntax is also required.
mini_ker.texi(,3780) Such a mortran is available at @url{http://www.environnement.ens.fr/@/perso/@/dumas/@/mini_ker/@/software.html}.
mini_ker.texi(,3781) 
mini_ker.texi(,3782) @c All the @command{make} commands are not suitable, for example the distribution
mini_ker.texi(,3783) @c doesn't work with solaris @command{make}. GNU @command{make} works, however,
mini_ker.texi(,3784) @c and should be available on most platforms, often called @command{gmake}.
mini_ker.texi(,3785) 
mini_ker.texi(,3786) 
mini_ker.texi(,3787) @node Configuration
mini_ker.texi(,3788) @appendixsubsec Configuration
mini_ker.texi(,3789) 
mini_ker.texi(,3790) @cindex configuration of source
mini_ker.texi(,3791) 
mini_ker.texi(,3792) The package is available at @url{http://www.environnement.ens.fr/@/perso/@/dumas/@/mini_ker/@/software.html}. It is 
mini_ker.texi(,3793) available as a compresssed tar archive. On UNIX, with GNU @command{tar} it 
mini_ker.texi(,3794) may be unpacked using 
mini_ker.texi(,3795) 
mini_ker.texi(,3796) @example
mini_ker.texi(,3797) $ tar xzvf mini_ker-4.2.tar.gz
mini_ker.texi(,3798) @end example
mini_ker.texi(,3799) 
mini_ker.texi(,3800) The detection of the compiler, the preprocessors (car2txt and mortran), 
mini_ker.texi(,3801) and the libraries are performed by the configure script. This script
mini_ker.texi(,3802) sets the
mini_ker.texi(,3803) apropriate variables in makefiles. It can be run with:
mini_ker.texi(,3804) 
mini_ker.texi(,3805) @example
mini_ker.texi(,3806) $ cd mini_ker-4.2
mini_ker.texi(,3807) $ ./configure
mini_ker.texi(,3808) @end example
mini_ker.texi(,3809) 
mini_ker.texi(,3810) If the output of @command{./configure} doesn't show any error it means that
mini_ker.texi(,3811) all the components are here. It is possible to give @command{./configure}
mini_ker.texi(,3812) switches and also specify environment variables (see also 
mini_ker.texi(,3813) @command{./configure --help}):
mini_ker.texi(,3814) 
mini_ker.texi(,3815) @table @code
mini_ker.texi(,3816) @item --disable-cernlib
mini_ker.texi(,3817) Use the internal cernlib source files, even if a cernlib is detected.
mini_ker.texi(,3818) @item --with-static-cernlib
mini_ker.texi(,3819) This command line switch forces a static linking with the cernlib (or a dynamic linking 
mini_ker.texi(,3820) if set to no).
mini_ker.texi(,3821) @item --with-cernlib
mini_ker.texi(,3822) This command line switch can be used to specify the cernlib location
mini_ker.texi(,3823) (if not detected or you want to use a specific cernlib).
mini_ker.texi(,3824) @item --with-blas
mini_ker.texi(,3825) @itemx --with-lapack
mini_ker.texi(,3826) With this command switch, you can specify the location of the blas and lapack
mini_ker.texi(,3827) libraries.
mini_ker.texi(,3828) 
mini_ker.texi(,3829) For example, on mac OS X this can be used to specify the blas and lapack from 
mini_ker.texi(,3830) the Apple frameworks:
mini_ker.texi(,3831) 
mini_ker.texi(,3832) @example
mini_ker.texi(,3833) ./configure \
mini_ker.texi(,3834) --with-blas=/System/Library/Frameworks/vecLib.framework/versions/A/vecLib \
mini_ker.texi(,3835) --with-lapack=/System/Library/Frameworks/vecLib.framework/versions/A/vecLib
mini_ker.texi(,3836) @end example
mini_ker.texi(,3837) 
mini_ker.texi(,3838) @item F77
mini_ker.texi(,3839) @itemx FC
mini_ker.texi(,3840) @itemx FFLAGS
mini_ker.texi(,3841) @itemx LDFLAGS 
mini_ker.texi(,3842) Classical compiler, compiler flags and linker flags.
mini_ker.texi(,3843) @item MORTRAN
mini_ker.texi(,3844) This environment variable holds the mortran preprocessor command
mini_ker.texi(,3845) (default is @command{mortran}).
mini_ker.texi(,3846) @item MTNFLAGS
mini_ker.texi(,3847) This environment variable holds command line arguments for the mortran
mini_ker.texi(,3848) preprocessor. It is empty in the default case.
mini_ker.texi(,3849) @item MTN
mini_ker.texi(,3850) This environment variable may be used to specify the mortran executable
mini_ker.texi(,3851) name and/or path, it should be used by the @command{mortran} commmand.
mini_ker.texi(,3852) (default is empty, which leads to a mortran executable called @command{mtn}).
mini_ker.texi(,3853) @item MTNDEPEND
mini_ker.texi(,3854) This environment variable may be used to specify the mortran dependencies
mini_ker.texi(,3855) checker executable. It should be used by the @command{mortran} commmand.
mini_ker.texi(,3856) (default is empty, which leads to a mortran dependencies checker 
mini_ker.texi(,3857) called @command{mtndepend}).
mini_ker.texi(,3858) @end table
mini_ker.texi(,3859) 
mini_ker.texi(,3860) After a proper configuration, if @command{make} is run then the example 
mini_ker.texi(,3861) models should be build. You have to perform the configuration only once.
mini_ker.texi(,3862) 
mini_ker.texi(,3863) @node Installation with make
mini_ker.texi(,3864) @appendixsubsec Installation with make
mini_ker.texi(,3865) @cindex installation with make
mini_ker.texi(,3866) 
mini_ker.texi(Minik,3867) Miniker can be installed by running 
mini_ker.texi(,3868) @example
mini_ker.texi(,3869) make install
mini_ker.texi(,3870) @end example
mini_ker.texi(,3871) 
mini_ker.texi(,3872) 
mini_ker.texi(,3873) It should copy the sources 
mini_ker.texi(,3874) and the @file{Makefile.miniker} file in 
mini_ker.texi(,3875) a @file{mini_ker} directory in the @code{$(includedir)} directory, and
mini_ker.texi(,3876) copy the templates in @file{$(datadir)/mini_ker}. The default for
mini_ker.texi(,3877) @code{$(includedir)} is @file{/usr/local/include} and the default for
mini_ker.texi(,3878) @code{$(datadir)} is @file{/usr/local/share}, these defaults may be 
mini_ker.texi(,3879) changed by @command{./configure} switches @samp{--prefix},
mini_ker.texi(,3880) @samp{--includedir}  and @samp{--datadir}. See @command{./configure --help}
mini_ker.texi(,3881) and the @file{INSTALL} file for more informations. The helper script
mini_ker.texi(,3882) @file{start_miniker} should also be installed.
mini_ker.texi(,3883) 
mini_ker.texi(,3884) 
mini_ker.texi(,3885)  
mini_ker.texi(Minik,3886) The installation is not required to use comfortably Miniker. Indeed
mini_ker.texi(,3887) the only thing that changes with the sources and the @file{Makefile.miniker}
mini_ker.texi(,3888) directory location is the @code{miniker_dir} variable in a 
mini_ker.texi(,3889) project @code{Makefile}.
mini_ker.texi(,3890) 
mini_ker.texi(,3891) 
mini_ker.texi(,3892) @node Cmz directives reference
mini_ker.texi(,3893) @appendix Cmz directives reference
mini_ker.texi(,3894) 
mini_ker.texi(,3895) The cmz directives are described together with the other 
mini_ker.texi(,3896) features of cmz in the cmz manual at
mini_ker.texi(,3897) @url{http://wwwcmz.web.cern.ch/wwwcmz/}, the important ones are 
mini_ker.texi(,3898) nevertheless recalled here,
mini_ker.texi(,3899) especially for those that use make and don't need the whole
mini_ker.texi(,3900) features of cmz.
mini_ker.texi(,3901) 
mini_ker.texi(,3902) After the description of the generic features, we turn
mini_ker.texi(,3903) to the cmz directive of interest.
mini_ker.texi(,3904) There are three kinds of cmz directives that are of use
mini_ker.texi(Minik,3905) within Miniker: one kind
mini_ker.texi(,3906) that introduce files, the other for conditionnal compilation and
mini_ker.texi(,3907) the third for sequence inclusion. 
mini_ker.texi(,3908) 
mini_ker.texi(,3909) 
mini_ker.texi(,3910) @menu
mini_ker.texi(,3911) * Cmz directives general syntax::
mini_ker.texi(,3912) * Conditional expressions::
mini_ker.texi(,3913) * File introduction directives::
mini_ker.texi(,3914) * Conditional directives::
mini_ker.texi(,3915) * File inclusion directive::
mini_ker.texi(,3916) * The self directive::
mini_ker.texi(,3917) @end menu
mini_ker.texi(,3918) 
mini_ker.texi(,3919) @node Cmz directives general syntax
mini_ker.texi(,3920) @appendixsec Cmz directives general syntax
mini_ker.texi(,3921) 
mini_ker.texi(,3922) The cmz directives always begin with a @samp{+} in the first column,
mini_ker.texi(,3923) optionnaly followed by any number of @samp{_} that may be used for 
mini_ker.texi(,3924) indentation, then the directive label, case insensitive, followed
mini_ker.texi(,3925) by the directive arguments separated by @samp{,}. The arguments
mini_ker.texi(,3926) are also case insensitive.
mini_ker.texi(,3927) Optional spaces may be around directive arguments. 
mini_ker.texi(,3928) An optionnal @samp{.} ends the directive
mini_ker.texi(,3929) arguments and begin a comment, everything that follows that @samp{.} is 
mini_ker.texi(,3930) ignored.
mini_ker.texi(,3931) 
mini_ker.texi(,3932) @node Conditional expressions
mini_ker.texi(,3933) @appendixsec Conditional expressions
mini_ker.texi(,3934) 
mini_ker.texi(,3935) A directive argument common to all the directives is the conditionnal
mini_ker.texi(,3936) expression. A conditionnal expression may be true or false, it is a 
mini_ker.texi(,3937) combination of select flags. the select flags are combined with 
mini_ker.texi(,3938) logical operators. A
mini_ker.texi(,3939) select flag itself is true if it was selected. A select flag @var{selflag} 
mini_ker.texi(,3940) is selected by using the @code{sel @var{selflag}} instruction in cmz. It is
mini_ker.texi(,3941) selected by passing the @code{-D @var{selflag}} command line switch to
mini_ker.texi(,3942) the call of the cmz directives preprocessor when using make.
mini_ker.texi(,3943) 
mini_ker.texi(,3944) 
mini_ker.texi(,3945) A @samp{-} negates
mini_ker.texi(,3946) the expression that follows. Parenthesis @samp{(} and @samp{)} are used 
mini_ker.texi(,3947) for the grouping of subexpressions. @samp{|} and @samp{,} are for the 
mini_ker.texi(,3948) boolean or: an expression with a or is true
mini_ker.texi(,3949) if the expression on the left or the expression on the right of the or
mini_ker.texi(,3950) is true. 
mini_ker.texi(,3951) @samp{&} is for the boolean and: an expression with an and is true if
mini_ker.texi(,3952) the expression on the left and the expression on the right are true.
mini_ker.texi(,3953) 
mini_ker.texi(,3954) The grouping is left to right when there is no parenthesis, with or and
mini_ker.texi(,3955) @samp{&} having the same precedence. Therefore
mini_ker.texi(,3956) 
mini_ker.texi(,3957) @example
mini_ker.texi(,3958) a&b|c    @equiv{}    (a&b)|c
mini_ker.texi(,3959) a|b&c    @equiv{}    (a|b)&c
mini_ker.texi(,3960) a|b&c  is not  a|(b&c)
mini_ker.texi(,3961) a&b|c  is not  a&(b|c)
mini_ker.texi(,3962) @end example 
mini_ker.texi(,3963) 
mini_ker.texi(,3964) @node File introduction directives
mini_ker.texi(,3965) @appendixsec File introduction directives
mini_ker.texi(,3966) 
mini_ker.texi(,3967) A file (or sequence) introduction directive appears at the beginning
mini_ker.texi(,3968) of the file. There are two different directives, one is @code{DECK}
mini_ker.texi(,3969) for normal files, the other is @code{KEEP} for include files (sequences).
mini_ker.texi(,3970) The first argument is the name of the file. The file name may not be larger
mini_ker.texi(,3971) than 32 characters and is converted to lower case in the general case.
mini_ker.texi(,3972) The optionnal following arguments may be
mini_ker.texi(,3973) of 2 type (and may be mixed, separated by @samp{,}):
mini_ker.texi(,3974) 
mini_ker.texi(,3975) @table @asis
mini_ker.texi(,3976) @item conditional
mini_ker.texi(,3977) A conditionnal is introduced by @code{IF=} followed by a conditionnal 
mini_ker.texi(,3978) expression described in 
mini_ker.texi(,3979) @ref{Conditional expressions}. The 
mini_ker.texi(,3980) file is preprocessed if the conditionnal expression is true.
mini_ker.texi(,3981) @item language specification
mini_ker.texi(,3982) A language specification is introduced by a @code{T=}. The most
mini_ker.texi(,3983) common languages are @samp{mtn} for the mortran, @samp{ftn} for
mini_ker.texi(,3984) fortran not preprocessed, @samp{f77} for preprocessed fortran,
mini_ker.texi(,3985) @samp{c} for the c language and @samp{txt} for text files.
mini_ker.texi(,3986) In general the language of the file determines the name of files 
mini_ker.texi(,3987) the preprocessed file is extracted to, the comment style and
mini_ker.texi(,3988) the command for inclusions.
mini_ker.texi(,3989) @end table
mini_ker.texi(,3990) 
mini_ker.texi(,3991) It is a common practice to have wrong language type in @code{KEEP} 
mini_ker.texi(,3992) as the language may be determined from the @code{DECK} that include
mini_ker.texi(,3993) them with cmz, or from their file name with make. This is not recommended
mini_ker.texi(,3994) and considered a bad practice.
mini_ker.texi(,3995) 
mini_ker.texi(,3996) Such a directive will always appear in cmz, as it is built-in. It
mini_ker.texi(,3997) is recommended to have one when using make too, even though it is not 
mini_ker.texi(,3998) required in most cases. Indeed make uses the file name directly
mini_ker.texi(,3999) and finds the language and file type by looking at the file extension.
mini_ker.texi(,4000) make should then pass the language type with a 
mini_ker.texi(,4001) @code{--lang @var{lang}} command
mini_ker.texi(,4002) line switch when calling the cmz directives preprocessor.
mini_ker.texi(,4003) With make, the convention is to have @samp{cm} added before the normal
mini_ker.texi(,4004) file suffix and after the @samp{.}. The table @ref{tab:cmfile_suffix}
mini_ker.texi(,4005) shows the matching between suffixes, file type and file language.
mini_ker.texi(,4006) 
mini_ker.texi(,4007) For example, a file beginning with
mini_ker.texi(,4008) 
mini_ker.texi(,4009) @verbatim
mini_ker.texi(,4010) +Deck, subroutine_foo, If=monitor&-simple, T=f77. 
mini_ker.texi(,4011) @end verbatim
mini_ker.texi(,4012) 
mini_ker.texi(,4013) is a main preprocessed fortran file that will only be generated if
mini_ker.texi(,4014) @samp{monitor} is selected and @samp{simple} is not selected. The 
mini_ker.texi(,4015) file to be preprocessed by make should have the @samp{.cmF} suffix,
mini_ker.texi(,4016) and be called @file{subroutine_foo.cmF}.
mini_ker.texi(,4017) 
mini_ker.texi(,4018) A file beginning with
mini_ker.texi(,4019) 
mini_ker.texi(,4020) @verbatim
mini_ker.texi(,4021) +KEEP,inc_common,If=monitor|interface,T=mtn
mini_ker.texi(,4022) @end verbatim
mini_ker.texi(,4023) 
mini_ker.texi(,4024) is an mortran include file that should be processed only if @samp{monitor}
mini_ker.texi(,4025) or @samp{interface} is selected. The file to be preprocessed by make
mini_ker.texi(,4026) should have the @samp{cmmti} suffix and be called @file{inc_common.cmmti}.
mini_ker.texi(,4027) The resulting file when make is used will be called @file{inc_common.mti}.
mini_ker.texi(,4028) 
mini_ker.texi(,4029) @node Conditional directives
mini_ker.texi(,4030) @appendixsec Conditional directives
mini_ker.texi(,4031) 
mini_ker.texi(,4032) Conditional directives may be used to conditionnaly skip blocks of
mini_ker.texi(,4033) code. There are 4 conditional directives: @code{if}, @code{elseif},
mini_ker.texi(,4034) @code{else} and @code{endif}. @code{+if} begins a conditional directives
mini_ker.texi(,4035) sequence, with argument a conditional expression. If the expression is
mini_ker.texi(,4036) true the block of code following the @code{+if} is output in the
mini_ker.texi(,4037) resulting file, up to another conditional directive, if it is false
mini_ker.texi(,4038) the code block is skipped. If the 
mini_ker.texi(,4039) expression is false and the following conditional directive is 
mini_ker.texi(,4040) @code{+elseif}, the same procedure is followed with the argument of 
mini_ker.texi(,4041) @code{+elseif} 
mini_ker.texi(,4042) which is also a conditionnal expression. More than one @code{+elseif}
mini_ker.texi(,4043) may follow a @code{+if}. If a @code{+if} or @code{+elseif} expression 
mini_ker.texi(,4044) is true the following
mini_ker.texi(,4045) code block is output and all
mini_ker.texi(,4046) the following @code{+elseif} code blocks are skipped. If all the @code{+if}
mini_ker.texi(,4047) and @code{+elseif} expressions are false and
mini_ker.texi(,4048) the following coditionnal 
mini_ker.texi(,4049) directive is @code{+else} then the block following the 
mini_ker.texi(,4050) @code{+else} is output. If a previous expression was true the 
mini_ker.texi(,4051) code block following the @code{+else} is skipped. The last code block
mini_ker.texi(,4052) is closed by @code{+endif}.
mini_ker.texi(,4053) 
mini_ker.texi(,4054) Conditionnal directives may be nested, a @code{+if} begins a deeper 
mini_ker.texi(,4055) conditionnal sequences directives that is ended by the corresponding 
mini_ker.texi(,4056) @code{+endif}.
mini_ker.texi(,4057) 
mini_ker.texi(,4058) The simplest example is:
mini_ker.texi(,4059) 
mini_ker.texi(,4060) @verbatim
mini_ker.texi(,4061)      some code;
mini_ker.texi(,4062) +IF,monitor
mini_ker.texi(,4063)      code output only if monitor is true;
mini_ker.texi(,4064) +ENDIF
mini_ker.texi(,4065) @end verbatim
mini_ker.texi(,4066) 
mini_ker.texi(,4067) If @samp{monitor} is selected, the @code{+if} block is output, it leads to
mini_ker.texi(,4068) 
mini_ker.texi(,4069) @verbatim
mini_ker.texi(,4070)      some code;
mini_ker.texi(,4071)      code output only if monitor is true;
mini_ker.texi(,4072) @end verbatim
mini_ker.texi(,4073) 
mini_ker.texi(,4074) If @samp{monitor} isn't selected the @code{+if} block is skipped, it leads to
mini_ker.texi(,4075) 
mini_ker.texi(,4076) @verbatim
mini_ker.texi(,4077)      some code;
mini_ker.texi(,4078) @end verbatim
mini_ker.texi(,4079) 
mini_ker.texi(,4080) An example with  @code{+else} may be:
mini_ker.texi(,4081) 
mini_ker.texi(,4082) @verbatim
mini_ker.texi(,4083) +IF,double
mini_ker.texi(,4084)  call dmysub(eta);
mini_ker.texi(,4085) +ELSE
mini_ker.texi(,4086)  call smysub(eta);
mini_ker.texi(,4087) +ENDIF
mini_ker.texi(,4088) @end verbatim
mini_ker.texi(,4089) 
mini_ker.texi(,4090) If @samp{double} is selected the code output is @code{call dmysub(eta);},
mini_ker.texi(,4091) if @samp{double} isn't selected the code output is @code{call dmysub(eta);}.
mini_ker.texi(,4092) 
mini_ker.texi(,4093) Here is a self explanatory example of use of @code{+elseif}:
mini_ker.texi(,4094) 
mini_ker.texi(,4095) @verbatim
mini_ker.texi(,4096) +IF,monitor
mini_ker.texi(,4097)   code used if monitor is selected;
mini_ker.texi(,4098) +ELSEIF,kalman
mini_ker.texi(,4099)   code used if kalman is selected and monitor is not;
mini_ker.texi(,4100) +ELSE
mini_ker.texi(,4101)   code used if kalman and monitor are not selected;
mini_ker.texi(,4102) +ENDIF
mini_ker.texi(,4103) @end verbatim
mini_ker.texi(,4104) 
mini_ker.texi(,4105) And last an example of nested conditional directives:
mini_ker.texi(,4106) 
mini_ker.texi(,4107) @verbatim
mini_ker.texi(,4108) +IF,monitor
mini_ker.texi(,4109)   code used if monitor is selected;
mini_ker.texi(,4110) +_IF,kalman. deep if
mini_ker.texi(,4111)     code used if monitor and kalman are selected;
mini_ker.texi(,4112) +_ELSE. deep else
mini_ker.texi(,4113)     code used if monitor is selected and kalman is not;
mini_ker.texi(,4114) +_ENDIF. end the deep conditionnals sequence
mini_ker.texi(,4115) +ELSE
mini_ker.texi(,4116)   code used if monitor is not selected;
mini_ker.texi(,4117) +_IF,kalman
mini_ker.texi(,4118)     code used if monitor is not selected but kalman is;
mini_ker.texi(,4119) +_ELSE
mini_ker.texi(,4120)     code used if monitor and kalman are not selected;
mini_ker.texi(,4121) +_ENDIF
mini_ker.texi(,4122)   other code used if monitor is not selected;
mini_ker.texi(,4123) +ENDIF
mini_ker.texi(,4124) @end verbatim
mini_ker.texi(,4125) 
mini_ker.texi(,4126) @node File inclusion directive
mini_ker.texi(,4127) @appendixsec File inclusion directive
mini_ker.texi(,4128) 
mini_ker.texi(,4129) The file (sequence) inclusion directive is @code{seq}. The argument of
mini_ker.texi(,4130) @code{seq} is an include files @samp{,} separated list. The include 
mini_ker.texi(,4131) files are @code{Keep} in cmz. The following optional arguments may be
mini_ker.texi(,4132) mixed:
mini_ker.texi(,4133) 
mini_ker.texi(,4134) @table @asis
mini_ker.texi(,4135) @item conditional
mini_ker.texi(,4136) A conditionnal is introduced by @code{IF=} followed by a conditionnal 
mini_ker.texi(,4137) expression described in 
mini_ker.texi(,4138) @ref{Conditional expressions}. The 
mini_ker.texi(,4139) directive is ignored if the conditionnal expression is false.
mini_ker.texi(,4140) @item T=noinclude
mini_ker.texi(,4141) When this argument is present the text of the sequence will 
mini_ker.texi(,4142) always be included in the file where the @code{+seq} appears.
mini_ker.texi(,4143) @end table
mini_ker.texi(,4144) 
mini_ker.texi(,4145) When there is no @code{T=noinclude} argument, the @code{+seq} 
mini_ker.texi(,4146) directive may be replaced with an inclusion command suitable 
mini_ker.texi(,4147) for the language of the file being processed, if such 
mini_ker.texi(,4148) command has been specified.
mini_ker.texi(,4149) 
mini_ker.texi(,4150) For example if we have the following sequence
mini_ker.texi(,4151) @verbatim
mini_ker.texi(,4152) +KEEP,inc,lang=C
mini_ker.texi(,4153) typedef struct incstr {char* msg};
mini_ker.texi(,4154) @end verbatim
mini_ker.texi(,4155) 
mini_ker.texi(,4156) And the following code in the file being processed:
mini_ker.texi(,4157) 
mini_ker.texi(,4158) @verbatim
mini_ker.texi(,4159) +DECK,mainf,lang=C
mini_ker.texi(,4160) +SEQ,inc
mini_ker.texi(,4161) int main (int argc, char* argv) { exit(0); }
mini_ker.texi(,4162) @end verbatim
mini_ker.texi(,4163) 
mini_ker.texi(,4164) the processing of @file{mainf} should lead to the file 
mini_ker.texi(,4165) @file{mainf.c}, containing
mini_ker.texi(,4166) an include command for @file{inc}:
mini_ker.texi(,4167) 
mini_ker.texi(,4168) @verbatim
mini_ker.texi(,4169) #include "inc.h"
mini_ker.texi(,4170) int main (int argc, char* argv) { exit(0); }
mini_ker.texi(,4171) @end verbatim
mini_ker.texi(,4172) 
mini_ker.texi(,4173) In case the @code{+seq} has the @code{T=noinclude}:
mini_ker.texi(,4174) 
mini_ker.texi(,4175) @verbatim
mini_ker.texi(,4176) +DECK,mainf,lang=C
mini_ker.texi(,4177) +SEQ,inc,T=noinclude
mini_ker.texi(,4178) int main (int argc, char* argv) { exit(0); }
mini_ker.texi(,4179) @end verbatim
mini_ker.texi(,4180) 
mini_ker.texi(,4181) The processing of @file{mainf} should lead to the file @file{mainf.c} 
mini_ker.texi(,4182) containing the text of @file{inc}:
mini_ker.texi(,4183) 
mini_ker.texi(,4184) @verbatim
mini_ker.texi(,4185) typedef struct incstr {char* msg};
mini_ker.texi(,4186) int main (int argc, char* argv) { exit(0); }
mini_ker.texi(,4187) @end verbatim
mini_ker.texi(,4188) 
mini_ker.texi(,4189) @node The self directive
mini_ker.texi(,4190) @appendixsec The @samp{self} directive
mini_ker.texi(,4191) 
mini_ker.texi(,4192) The @code{self} directive is an obsolete directive that may be used for
mini_ker.texi(,4193) conditionnal skipping of code. For a better approach see 
mini_ker.texi(,4194) @ref{Conditional directives}. 
mini_ker.texi(,4195) The optionnal argument of @code{+SELF} is @code{If=} followed by
mini_ker.texi(,4196) a conditionnal expression. If the conditionnal expression is true the 
mini_ker.texi(,4197) code following the directive is output, if it is false the code 
mini_ker.texi(,4198) is skipped up to any directive (including another @code{+SELF})
mini_ker.texi(,4199) except @code{+seq}.
mini_ker.texi(,4200) 
mini_ker.texi(,4208) 
mini_ker.texi(,4209) @node Copying This Manual
mini_ker.texi(,4210) @appendix Copying This Manual
mini_ker.texi(,4211) 
mini_ker.texi(,4212) @menu
mini_ker.texi(,4213) * GNU Free Documentation License::  License for copying this manual.
mini_ker.texi(,4214) @end menu
mini_ker.texi(,4215) 
fdl.texi(,1) 
fdl.texi(,2) @node GNU Free Documentation License
fdl.texi(,3) @appendixsec GNU Free Documentation License
fdl.texi(,4) 
fdl.texi(,5) @cindex FDL, GNU Free Documentation License
fdl.texi(,6) @center Version 1.1, March 2000
fdl.texi(,7) 
fdl.texi(,8) @display
fdl.texi(,9) Copyright @copyright{} 2000 Free Software Foundation, Inc.
fdl.texi(,10) 59 Temple Place, Suite 330, Boston, MA  02111-1307, USA
fdl.texi(,11) 
fdl.texi(,12) Everyone is permitted to copy and distribute verbatim copies
fdl.texi(,13) of this license document, but changing it is not allowed.
fdl.texi(,14) @end display
fdl.texi(,15) 
fdl.texi(,16) @enumerate 0
fdl.texi(,17) @item
fdl.texi(,18) PREAMBLE
fdl.texi(,19) 
fdl.texi(,20) The purpose of this License is to make a manual, textbook, or other
fdl.texi(,21) written document @dfn{free} in the sense of freedom: to assure everyone
fdl.texi(,22) the effective freedom to copy and redistribute it, with or without
fdl.texi(,23) modifying it, either commercially or noncommercially.  Secondarily,
fdl.texi(,24) this License preserves for the author and publisher a way to get
fdl.texi(,25) credit for their work, while not being considered responsible for
fdl.texi(,26) modifications made by others.
fdl.texi(,27) 
fdl.texi(,28) This License is a kind of ``copyleft'', which means that derivative
fdl.texi(,29) works of the document must themselves be free in the same sense.  It
fdl.texi(,30) complements the GNU General Public License, which is a copyleft
fdl.texi(,31) license designed for free software.
fdl.texi(,32) 
fdl.texi(,33) We have designed this License in order to use it for manuals for free
fdl.texi(,34) software, because free software needs free documentation: a free
fdl.texi(,35) program should come with manuals providing the same freedoms that the
fdl.texi(,36) software does.  But this License is not limited to software manuals;
fdl.texi(,37) it can be used for any textual work, regardless of subject matter or
fdl.texi(,38) whether it is published as a printed book.  We recommend this License
fdl.texi(,39) principally for works whose purpose is instruction or reference.
fdl.texi(,40) 
fdl.texi(,41) @item
fdl.texi(,42) APPLICABILITY AND DEFINITIONS
fdl.texi(,43) 
fdl.texi(,44) This License applies to any manual or other work that contains a
fdl.texi(,45) notice placed by the copyright holder saying it can be distributed
fdl.texi(,46) under the terms of this License.  The ``Document'', below, refers to any
fdl.texi(,47) such manual or work.  Any member of the public is a licensee, and is
fdl.texi(,48) addressed as ``you''.
fdl.texi(,49) 
fdl.texi(,50) A ``Modified Version'' of the Document means any work containing the
fdl.texi(,51) Document or a portion of it, either copied verbatim, or with
fdl.texi(,52) modifications and/or translated into another language.
fdl.texi(,53) 
fdl.texi(,54) A ``Secondary Section'' is a named appendix or a front-matter section of
fdl.texi(,55) the Document that deals exclusively with the relationship of the
fdl.texi(,56) publishers or authors of the Document to the Document's overall subject
fdl.texi(,57) (or to related matters) and contains nothing that could fall directly
fdl.texi(,58) within that overall subject.  (For example, if the Document is in part a
fdl.texi(,59) textbook of mathematics, a Secondary Section may not explain any
fdl.texi(,60) mathematics.)  The relationship could be a matter of historical
fdl.texi(,61) connection with the subject or with related matters, or of legal,
fdl.texi(,62) commercial, philosophical, ethical or political position regarding
fdl.texi(,63) them.
fdl.texi(,64) 
fdl.texi(,65) The ``Invariant Sections'' are certain Secondary Sections whose titles
fdl.texi(,66) are designated, as being those of Invariant Sections, in the notice
fdl.texi(,67) that says that the Document is released under this License.
fdl.texi(,68) 
fdl.texi(,69) The ``Cover Texts'' are certain short passages of text that are listed,
fdl.texi(,70) as Front-Cover Texts or Back-Cover Texts, in the notice that says that
fdl.texi(,71) the Document is released under this License.
fdl.texi(,72) 
fdl.texi(,73) A ``Transparent'' copy of the Document means a machine-readable copy,
fdl.texi(,74) represented in a format whose specification is available to the
fdl.texi(,75) general public, whose contents can be viewed and edited directly and
fdl.texi(,76) straightforwardly with generic text editors or (for images composed of
fdl.texi(,77) pixels) generic paint programs or (for drawings) some widely available
fdl.texi(,78) drawing editor, and that is suitable for input to text formatters or
fdl.texi(,79) for automatic translation to a variety of formats suitable for input
fdl.texi(,80) to text formatters.  A copy made in an otherwise Transparent file
fdl.texi(,81) format whose markup has been designed to thwart or discourage
fdl.texi(,82) subsequent modification by readers is not Transparent.  A copy that is
fdl.texi(,83) not ``Transparent'' is called ``Opaque''.
fdl.texi(,84) 
fdl.texi(,85) Examples of suitable formats for Transparent copies include plain
fdl.texi(,86) @sc{ascii} without markup, Texinfo input format, La@TeX{} input format,
fdl.texi(,87) @acronym{SGML} or @acronym{XML} using a publicly available
fdl.texi(,88) @acronym{DTD}, and standard-conforming simple @acronym{HTML} designed
fdl.texi(,89) for human modification.  Opaque formats include PostScript,
fdl.texi(,90) @acronym{PDF}, proprietary formats that can be read and edited only by
fdl.texi(,91) proprietary word processors, @acronym{SGML} or @acronym{XML} for which
fdl.texi(,92) the @acronym{DTD} and/or processing tools are not generally available,
fdl.texi(,93) and the machine-generated @acronym{HTML} produced by some word
fdl.texi(,94) processors for output purposes only.
fdl.texi(,95) 
fdl.texi(,96) The ``Title Page'' means, for a printed book, the title page itself,
fdl.texi(,97) plus such following pages as are needed to hold, legibly, the material
fdl.texi(,98) this License requires to appear in the title page.  For works in
fdl.texi(,99) formats which do not have any title page as such, ``Title Page'' means
fdl.texi(,100) the text near the most prominent appearance of the work's title,
fdl.texi(,101) preceding the beginning of the body of the text.
fdl.texi(,102) 
fdl.texi(,103) @item
fdl.texi(,104) VERBATIM COPYING
fdl.texi(,105) 
fdl.texi(,106) You may copy and distribute the Document in any medium, either
fdl.texi(,107) commercially or noncommercially, provided that this License, the
fdl.texi(,108) copyright notices, and the license notice saying this License applies
fdl.texi(,109) to the Document are reproduced in all copies, and that you add no other
fdl.texi(,110) conditions whatsoever to those of this License.  You may not use
fdl.texi(,111) technical measures to obstruct or control the reading or further
fdl.texi(,112) copying of the copies you make or distribute.  However, you may accept
fdl.texi(,113) compensation in exchange for copies.  If you distribute a large enough
fdl.texi(,114) number of copies you must also follow the conditions in section 3.
fdl.texi(,115) 
fdl.texi(,116) You may also lend copies, under the same conditions stated above, and
fdl.texi(,117) you may publicly display copies.
fdl.texi(,118) 
fdl.texi(,119) @item
fdl.texi(,120) COPYING IN QUANTITY
fdl.texi(,121) 
fdl.texi(,122) If you publish printed copies of the Document numbering more than 100,
fdl.texi(,123) and the Document's license notice requires Cover Texts, you must enclose
fdl.texi(,124) the copies in covers that carry, clearly and legibly, all these Cover
fdl.texi(,125) Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
fdl.texi(,126) the back cover.  Both covers must also clearly and legibly identify
fdl.texi(,127) you as the publisher of these copies.  The front cover must present
fdl.texi(,128) the full title with all words of the title equally prominent and
fdl.texi(,129) visible.  You may add other material on the covers in addition.
fdl.texi(,130) Copying with changes limited to the covers, as long as they preserve
fdl.texi(,131) the title of the Document and satisfy these conditions, can be treated
fdl.texi(,132) as verbatim copying in other respects.
fdl.texi(,133) 
fdl.texi(,134) If the required texts for either cover are too voluminous to fit
fdl.texi(,135) legibly, you should put the first ones listed (as many as fit
fdl.texi(,136) reasonably) on the actual cover, and continue the rest onto adjacent
fdl.texi(,137) pages.
fdl.texi(,138) 
fdl.texi(,139) If you publish or distribute Opaque copies of the Document numbering
fdl.texi(,140) more than 100, you must either include a machine-readable Transparent
fdl.texi(,141) copy along with each Opaque copy, or state in or with each Opaque copy
fdl.texi(,142) a publicly-accessible computer-network location containing a complete
fdl.texi(,143) Transparent copy of the Document, free of added material, which the
fdl.texi(,144) general network-using public has access to download anonymously at no
fdl.texi(,145) charge using public-standard network protocols.  If you use the latter
fdl.texi(,146) option, you must take reasonably prudent steps, when you begin
fdl.texi(,147) distribution of Opaque copies in quantity, to ensure that this
fdl.texi(,148) Transparent copy will remain thus accessible at the stated location
fdl.texi(,149) until at least one year after the last time you distribute an Opaque
fdl.texi(,150) copy (directly or through your agents or retailers) of that edition to
fdl.texi(,151) the public.
fdl.texi(,152) 
fdl.texi(,153) It is requested, but not required, that you contact the authors of the
fdl.texi(,154) Document well before redistributing any large number of copies, to give
fdl.texi(,155) them a chance to provide you with an updated version of the Document.
fdl.texi(,156) 
fdl.texi(,157) @item
fdl.texi(,158) MODIFICATIONS
fdl.texi(,159) 
fdl.texi(,160) You may copy and distribute a Modified Version of the Document under
fdl.texi(,161) the conditions of sections 2 and 3 above, provided that you release
fdl.texi(,162) the Modified Version under precisely this License, with the Modified
fdl.texi(,163) Version filling the role of the Document, thus licensing distribution
fdl.texi(,164) and modification of the Modified Version to whoever possesses a copy
fdl.texi(,165) of it.  In addition, you must do these things in the Modified Version:
fdl.texi(,166) 
fdl.texi(,167) @enumerate A
fdl.texi(,168) @item
fdl.texi(,169) Use in the Title Page (and on the covers, if any) a title distinct
fdl.texi(,170) from that of the Document, and from those of previous versions
fdl.texi(,171) (which should, if there were any, be listed in the History section
fdl.texi(,172) of the Document).  You may use the same title as a previous version
fdl.texi(,173) if the original publisher of that version gives permission.
fdl.texi(,174) 
fdl.texi(,175) @item
fdl.texi(,176) List on the Title Page, as authors, one or more persons or entities
fdl.texi(,177) responsible for authorship of the modifications in the Modified
fdl.texi(,178) Version, together with at least five of the principal authors of the
fdl.texi(,179) Document (all of its principal authors, if it has less than five).
fdl.texi(,180) 
fdl.texi(,181) @item
fdl.texi(,182) State on the Title page the name of the publisher of the
fdl.texi(,183) Modified Version, as the publisher.
fdl.texi(,184) 
fdl.texi(,185) @item
fdl.texi(,186) Preserve all the copyright notices of the Document.
fdl.texi(,187) 
fdl.texi(,188) @item
fdl.texi(,189) Add an appropriate copyright notice for your modifications
fdl.texi(,190) adjacent to the other copyright notices.
fdl.texi(,191) 
fdl.texi(,192) @item
fdl.texi(,193) Include, immediately after the copyright notices, a license notice
fdl.texi(,194) giving the public permission to use the Modified Version under the
fdl.texi(,195) terms of this License, in the form shown in the Addendum below.
fdl.texi(,196) 
fdl.texi(,197) @item
fdl.texi(,198) Preserve in that license notice the full lists of Invariant Sections
fdl.texi(,199) and required Cover Texts given in the Document's license notice.
fdl.texi(,200) 
fdl.texi(,201) @item
fdl.texi(,202) Include an unaltered copy of this License.
fdl.texi(,203) 
fdl.texi(,204) @item
fdl.texi(,205) Preserve the section entitled ``History'', and its title, and add to
fdl.texi(,206) it an item stating at least the title, year, new authors, and
fdl.texi(,207) publisher of the Modified Version as given on the Title Page.  If
fdl.texi(,208) there is no section entitled ``History'' in the Document, create one
fdl.texi(,209) stating the title, year, authors, and publisher of the Document as
fdl.texi(,210) given on its Title Page, then add an item describing the Modified
fdl.texi(,211) Version as stated in the previous sentence.
fdl.texi(,212) 
fdl.texi(,213) @item
fdl.texi(,214) Preserve the network location, if any, given in the Document for
fdl.texi(,215) public access to a Transparent copy of the Document, and likewise
fdl.texi(,216) the network locations given in the Document for previous versions
fdl.texi(,217) it was based on.  These may be placed in the ``History'' section.
fdl.texi(,218) You may omit a network location for a work that was published at
fdl.texi(,219) least four years before the Document itself, or if the original
fdl.texi(,220) publisher of the version it refers to gives permission.
fdl.texi(,221) 
fdl.texi(,222) @item
fdl.texi(,223) In any section entitled ``Acknowledgments'' or ``Dedications'',
fdl.texi(,224) preserve the section's title, and preserve in the section all the
fdl.texi(,225) substance and tone of each of the contributor acknowledgments
fdl.texi(,226) and/or dedications given therein.
fdl.texi(,227) 
fdl.texi(,228) @item
fdl.texi(,229) Preserve all the Invariant Sections of the Document,
fdl.texi(,230) unaltered in their text and in their titles.  Section numbers
fdl.texi(,231) or the equivalent are not considered part of the section titles.
fdl.texi(,232) 
fdl.texi(,233) @item
fdl.texi(,234) Delete any section entitled ``Endorsements''.  Such a section
fdl.texi(,235) may not be included in the Modified Version.
fdl.texi(,236) 
fdl.texi(,237) @item
fdl.texi(,238) Do not retitle any existing section as ``Endorsements''
fdl.texi(,239) or to conflict in title with any Invariant Section.
fdl.texi(,240) @end enumerate
fdl.texi(,241) 
fdl.texi(,242) If the Modified Version includes new front-matter sections or
fdl.texi(,243) appendices that qualify as Secondary Sections and contain no material
fdl.texi(,244) copied from the Document, you may at your option designate some or all
fdl.texi(,245) of these sections as invariant.  To do this, add their titles to the
fdl.texi(,246) list of Invariant Sections in the Modified Version's license notice.
fdl.texi(,247) These titles must be distinct from any other section titles.
fdl.texi(,248) 
fdl.texi(,249) You may add a section entitled ``Endorsements'', provided it contains
fdl.texi(,250) nothing but endorsements of your Modified Version by various
fdl.texi(,251) parties---for example, statements of peer review or that the text has
fdl.texi(,252) been approved by an organization as the authoritative definition of a
fdl.texi(,253) standard.
fdl.texi(,254) 
fdl.texi(,255) You may add a passage of up to five words as a Front-Cover Text, and a
fdl.texi(,256) passage of up to 25 words as a Back-Cover Text, to the end of the list
fdl.texi(,257) of Cover Texts in the Modified Version.  Only one passage of
fdl.texi(,258) Front-Cover Text and one of Back-Cover Text may be added by (or
fdl.texi(,259) through arrangements made by) any one entity.  If the Document already
fdl.texi(,260) includes a cover text for the same cover, previously added by you or
fdl.texi(,261) by arrangement made by the same entity you are acting on behalf of,
fdl.texi(,262) you may not add another; but you may replace the old one, on explicit
fdl.texi(,263) permission from the previous publisher that added the old one.
fdl.texi(,264) 
fdl.texi(,265) The author(s) and publisher(s) of the Document do not by this License
fdl.texi(,266) give permission to use their names for publicity for or to assert or
fdl.texi(,267) imply endorsement of any Modified Version.
fdl.texi(,268) 
fdl.texi(,269) @item
fdl.texi(,270) COMBINING DOCUMENTS
fdl.texi(,271) 
fdl.texi(,272) You may combine the Document with other documents released under this
fdl.texi(,273) License, under the terms defined in section 4 above for modified
fdl.texi(,274) versions, provided that you include in the combination all of the
fdl.texi(,275) Invariant Sections of all of the original documents, unmodified, and
fdl.texi(,276) list them all as Invariant Sections of your combined work in its
fdl.texi(,277) license notice.
fdl.texi(,278) 
fdl.texi(,279) The combined work need only contain one copy of this License, and
fdl.texi(,280) multiple identical Invariant Sections may be replaced with a single
fdl.texi(,281) copy.  If there are multiple Invariant Sections with the same name but
fdl.texi(,282) different contents, make the title of each such section unique by
fdl.texi(,283) adding at the end of it, in parentheses, the name of the original
fdl.texi(,284) author or publisher of that section if known, or else a unique number.
fdl.texi(,285) Make the same adjustment to the section titles in the list of
fdl.texi(,286) Invariant Sections in the license notice of the combined work.
fdl.texi(,287) 
fdl.texi(,288) In the combination, you must combine any sections entitled ``History''
fdl.texi(,289) in the various original documents, forming one section entitled
fdl.texi(,290) ``History''; likewise combine any sections entitled ``Acknowledgments'',
fdl.texi(,291) and any sections entitled ``Dedications''.  You must delete all sections
fdl.texi(,292) entitled ``Endorsements.''
fdl.texi(,293) 
fdl.texi(,294) @item
fdl.texi(,295) COLLECTIONS OF DOCUMENTS
fdl.texi(,296) 
fdl.texi(,297) You may make a collection consisting of the Document and other documents
fdl.texi(,298) released under this License, and replace the individual copies of this
fdl.texi(,299) License in the various documents with a single copy that is included in
fdl.texi(,300) the collection, provided that you follow the rules of this License for
fdl.texi(,301) verbatim copying of each of the documents in all other respects.
fdl.texi(,302) 
fdl.texi(,303) You may extract a single document from such a collection, and distribute
fdl.texi(,304) it individually under this License, provided you insert a copy of this
fdl.texi(,305) License into the extracted document, and follow this License in all
fdl.texi(,306) other respects regarding verbatim copying of that document.
fdl.texi(,307) 
fdl.texi(,308) @item
fdl.texi(,309) AGGREGATION WITH INDEPENDENT WORKS
fdl.texi(,310) 
fdl.texi(,311) A compilation of the Document or its derivatives with other separate
fdl.texi(,312) and independent documents or works, in or on a volume of a storage or
fdl.texi(,313) distribution medium, does not as a whole count as a Modified Version
fdl.texi(,314) of the Document, provided no compilation copyright is claimed for the
fdl.texi(,315) compilation.  Such a compilation is called an ``aggregate'', and this
fdl.texi(,316) License does not apply to the other self-contained works thus compiled
fdl.texi(,317) with the Document, on account of their being thus compiled, if they
fdl.texi(,318) are not themselves derivative works of the Document.
fdl.texi(,319) 
fdl.texi(,320) If the Cover Text requirement of section 3 is applicable to these
fdl.texi(,321) copies of the Document, then if the Document is less than one quarter
fdl.texi(,322) of the entire aggregate, the Document's Cover Texts may be placed on
fdl.texi(,323) covers that surround only the Document within the aggregate.
fdl.texi(,324) Otherwise they must appear on covers around the whole aggregate.
fdl.texi(,325) 
fdl.texi(,326) @item
fdl.texi(,327) TRANSLATION
fdl.texi(,328) 
fdl.texi(,329) Translation is considered a kind of modification, so you may
fdl.texi(,330) distribute translations of the Document under the terms of section 4.
fdl.texi(,331) Replacing Invariant Sections with translations requires special
fdl.texi(,332) permission from their copyright holders, but you may include
fdl.texi(,333) translations of some or all Invariant Sections in addition to the
fdl.texi(,334) original versions of these Invariant Sections.  You may include a
fdl.texi(,335) translation of this License provided that you also include the
fdl.texi(,336) original English version of this License.  In case of a disagreement
fdl.texi(,337) between the translation and the original English version of this
fdl.texi(,338) License, the original English version will prevail.
fdl.texi(,339) 
fdl.texi(,340) @item
fdl.texi(,341) TERMINATION
fdl.texi(,342) 
fdl.texi(,343) You may not copy, modify, sublicense, or distribute the Document except
fdl.texi(,344) as expressly provided for under this License.  Any other attempt to
fdl.texi(,345) copy, modify, sublicense or distribute the Document is void, and will
fdl.texi(,346) automatically terminate your rights under this License.  However,
fdl.texi(,347) parties who have received copies, or rights, from you under this
fdl.texi(,348) License will not have their licenses terminated so long as such
fdl.texi(,349) parties remain in full compliance.
fdl.texi(,350) 
fdl.texi(,351) @item
fdl.texi(,352) FUTURE REVISIONS OF THIS LICENSE
fdl.texi(,353) 
fdl.texi(,354) The Free Software Foundation may publish new, revised versions
fdl.texi(,355) of the GNU Free Documentation License from time to time.  Such new
fdl.texi(,356) versions will be similar in spirit to the present version, but may
fdl.texi(,357) differ in detail to address new problems or concerns.  See
fdl.texi(,358) @uref{http://www.gnu.org/copyleft/}.
fdl.texi(,359) 
fdl.texi(,360) Each version of the License is given a distinguishing version number.
fdl.texi(,361) If the Document specifies that a particular numbered version of this
fdl.texi(,362) License ``or any later version'' applies to it, you have the option of
fdl.texi(,363) following the terms and conditions either of that specified version or
fdl.texi(,364) of any later version that has been published (not as a draft) by the
fdl.texi(,365) Free Software Foundation.  If the Document does not specify a version
fdl.texi(,366) number of this License, you may choose any version ever published (not
fdl.texi(,367) as a draft) by the Free Software Foundation.
fdl.texi(,368) @end enumerate
fdl.texi(,369) 
fdl.texi(,370) @page
fdl.texi(,371) @appendixsubsec ADDENDUM: How to use this License for your documents
fdl.texi(,372) 
fdl.texi(,373) To use this License in a document you have written, include a copy of
fdl.texi(,374) the License in the document and put the following copyright and
fdl.texi(,375) license notices just after the title page:
fdl.texi(,376) 
fdl.texi(,377) @smallexample
fdl.texi(,378) @group
fdl.texi(,379)   Copyright (C)  @var{year}  @var{your name}.
fdl.texi(,380)   Permission is granted to copy, distribute and/or modify this document
fdl.texi(,381)   under the terms of the GNU Free Documentation License, Version 1.1
fdl.texi(,382)   or any later version published by the Free Software Foundation;
fdl.texi(,383)   with the Invariant Sections being @var{list their titles}, with the
fdl.texi(,384)   Front-Cover Texts being @var{list}, and with the Back-Cover Texts being @var{list}.
fdl.texi(,385)   A copy of the license is included in the section entitled ``GNU
fdl.texi(,386)   Free Documentation License''.
fdl.texi(,387) @end group
fdl.texi(,388) @end smallexample
fdl.texi(,389) 
fdl.texi(,390) If you have no Invariant Sections, write ``with no Invariant Sections''
fdl.texi(,391) instead of saying which ones are invariant.  If you have no
fdl.texi(,392) Front-Cover Texts, write ``no Front-Cover Texts'' instead of
fdl.texi(,393) ``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts.
fdl.texi(,394) 
fdl.texi(,395) If your document contains nontrivial examples of program code, we
fdl.texi(,396) recommend releasing these examples in parallel under your choice of
fdl.texi(,397) free software license, such as the GNU General Public License,
fdl.texi(,398) to permit their use in free software.
fdl.texi(,399) 
fdl.texi(,400) @c Local Variables:
fdl.texi(,401) @c ispell-local-pdict: "ispell-dict"
fdl.texi(,402) @c End:
fdl.texi(,403) 
mini_ker.texi(,4217) 
mini_ker.texi(,4218) @bye
