File: A-model-description.html

package info (click to toggle)
texi2html 1.82%2Bdfsg1-6
links: PTS
area: main
in suites: bullseye
size: 35,236 kB
sloc: perl: 15,901; xml: 6,075; sh: 3,977; makefile: 501
file content (448 lines) | stat: -rw-r--r-- 18,517 bytes
parent folder | download | duplicates (6)
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
<html>
<!-- Copyright (C) 2004, 2005, 2006, 2007 Alain Lahellec

Copyright (C) 2004, 2005, 2006, 2007 Patrice Dumas

Copyright (C) 2004, Ste'phane Hallegatte

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover text and with no Back-Cover Text.  
A copy of the license is included in the section entitled "GNU Free 
Documentation License."

 -->
<!-- Created on a sunny day by texi2html
texi2html was written by: 
            Lionel Cons <Lionel.Cons@cern.ch> (original author)
            Karl Berry  <karl@freefriends.org>
            Olaf Bachmann <obachman@mathematik.uni-kl.de>
            and many others.
Maintained by: Many creative people.
Send bugs and suggestions to <texi2html-bug@nongnu.org>
-->
<head>
<title>Miniker 102 manual: 2.2 Miniker programming illustrated</title>

<meta name="description" content="Miniker 102 manual: 2.2 Miniker programming illustrated">
<meta name="keywords" content="Miniker 102 manual: 2.2 Miniker programming illustrated">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="texi2html">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<style type="text/css">
<!--
@import "mini_ker_tex4ht_math.css";
@import "mini_ker_tex4ht_tex.css";

a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
pre.display {font-family: serif}
pre.format {font-family: serif}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: serif; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: serif; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.roman {font-family:serif; font-weight:normal;}
span.sansserif {font-family:sans-serif; font-weight:normal;}
ul.toc {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">

<a name="A-model-description"></a>
<ul class="toc"><li><a href="mini_ker.html#Top">Miniker 102 manual</a> </li>
<li><ul class="toc"><li><a href="A-model-with-Miniker.html#A-model-with-Miniker">2. Miniker model programming</a> </li>
</ul></li>
</ul>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="Structure-of-the-code.html#Structure-of-the-code" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#A-note-about-mortran-and-cmz-directives" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="mini_ker.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concepts-index.html#Concepts-index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="mini_ker_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Miniker-programming-illustrated"></a>
<h2 class="section"> 2.2 Miniker programming illustrated </h2>
<ul class="toc">
<li> <a href="#A-note-about-mortran-and-cmz-directives">2.2.1 All you need to know about mortran and cmz directives</a> </li>
<li> <a href="#Model-equation-and-parameters">2.2.2 Entering model equation and parameters</a> </li>
</ul>

<a name="index-TEF-1"></a>

<p>The general <acronym title="Transfer Evolution Formalism">TEF</acronym> system writes:

    <center class="math-display" >
<img 
src="mini_ker_tex4ht_tex3x.png" alt="&#x2202;&#x03B7;(t) = g(&#x03B7;(t),&#x03C6;(t))
 t
 &#x03C6;(t) = f(&#x03B7;(t),&#x03C6;(t))  " class="math-display" ></center>  
</p>
<p>To illustrate the model description in Miniker a simple predator-prey
model of Lotka-Volterra is used.
This model can be written in the following <acronym title="Transfer Evolution Formalism">TEF</acronym> form:
</p>
<p>

    <center class="math-display" >
<img 
src="mini_ker_tex4ht_tex4x.png" alt="{
  &#x2202;t&#x03B7;prey = a&#x03B7;prey - a&#x03C6;meet

  &#x2202;t&#x03B7;pred = - c&#x03B7;pred + c&#x03C6;meet  " class="math-display" ></center>  

    <center class="math-display" >
<img 
src="mini_ker_tex4ht_tex5x.png" alt="&#x03C6;meet = &#x03B7;prey&#x03B7;pred  " class="math-display" ></center>  
</p>
<p>with two cell equations, <i>i.e</i>. state evolution of the prey and predator 
groups, and one transfer accounting for the meeting of individuals of 
different group.
</p>

<hr size="2">
<a name="A-note-about-mortran-and-cmz-directives"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#A-model-description" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="#Model-equation-and-parameters" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="mini_ker.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concepts-index.html#Concepts-index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="mini_ker_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="All-you-need-to-know-about-mortran-and-cmz-directives"></a>
<h3 class="subsection"> 2.2.1 All you need to know about mortran and cmz directives </h3>

<a name="index-mortran-1"></a>

<p>The first stage of code generation consists in cmz directives preprocessing.
Cmz directives are used for conditional selection of features, and sequence 
inclusion. At that point you don&rsquo;t need to know anything about these
directives. They are only usefull if you want to take advantage of advanced 
features 
(see <a href="Programming-with-cmz-directives.html#Programming-with-cmz-directives">Programming with cmz directives</a>).
</p>
<p>The code in sequences is written in Mortran and the second stage of code
generation consists in mortran macro expansion. The mortran language is 
described
in its own manual, here we only explain the very basics which is all you need
to know to use Miniker. Mortran basic instructions are almost Fortran,
the differences are the following:
</p>
<ul>
<li> The code is free-form, and each statement should end with a semi-colon 
<code>;</code>.
</li><li> Comments may be introduced by an exclamation mark <code>!</code> at the 
beginning of a line, or appear within double quotes <code>&quot;</code> in a single line.
</li><li> It is possible to use blocs, for <code>do</code> or <code>if</code> statement 
for example, and they are enclosed within brackets &lsquo;<samp>&lt;</samp>&rsquo; and &lsquo;<samp>&gt;</samp>&rsquo;.
To be in the safe side, a semi-colon <code>;</code> should be added after a 
closng bracket <code>&gt;</code>.
</li></ul>

<p>The following fictious code is legal mortran:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">real 
  param;
param = 3.; ff(1) = ff(3)**eta(1);       &quot;a comment&quot;                 
! a line comment
do inode=1,n_node &lt;eta_move(inode)=0.01; eta_speed(inode)=0.0;&gt;;
</pre></td></tr></table>

<p>Thanks to mortran the model code is very simply specified, as you&rsquo;ll 
see next.
</p>

<hr size="2">
<a name="Model-equation-and-parameters"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#A-note-about-mortran-and-cmz-directives" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="Setting-and-running-a-model.html#Setting-and-running-a-model" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="mini_ker.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concepts-index.html#Concepts-index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="mini_ker_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Entering-model-equation-and-parameters"></a>
<h3 class="subsection"> 2.2.2 Entering model equation and parameters </h3>

<a name="index-zinit"></a>
<a name="index-dt"></a>
<a name="index-time"></a>
<a name="index-nstep"></a>
<a name="index-modzprint"></a>

<p>The model equation and parameters and some Miniker parameters are entered in
the &lsquo;<tt>zinit</tt>&rsquo; sequence. The whole layout of the model is given
before detailing the keywords.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">!%%%%%%%%%%%%%%%%%%%%%%
! Parameters           
!%%%%%%%%%%%%%%%%%%%%%%
  real apar,bpar;        &quot;optional Fortran type declaration&quot;

! required parameters
     dt=.01;             &quot;initial time-step&quot;
     nstep=10 000;       &quot;number of iterations along the trajectory&quot;
     time=0.;            &quot;time initialisation &quot;

! model parameters            
     apar = 1.5;             
     cpar = 0.7;          
                                                  
! misceallaneous parameters
     modzprint = 1000;    &quot;printouts frequency&quot; 

print*,'***************************************';
print*,'Lotka-Volterra model with parameters as:';
z_pr: apar,bpar;
print*,'***************************************';

!%%%%%%%%%%%%%%%%%%%%%%
! Transfer definition
!%%%%%%%%%%%%%%%%%%%%%%
! rencontre (meeting)
set_Phi
&lt; var: ff_interact, fun: f_interact = eta_prey*eta_pred;
&gt;;

!%%%%%%%%%%%%%%%%%%%%%%
! Cell definition
!%%%%%%%%%%%%%%%%%%%%%%

set_eta
&lt; var: eta_prey, fun: deta_prey =   apar*eta_prey - apar*ff_interact;
  var: eta_pred, fun: deta_pred = - cpar*eta_pred + cpar*ff_interact;
&gt;;


!%%%%%%%%%%%%%%%%%%%%%%
! Initial states
!%%%%%%%%%%%%%%%%%%%%%%
     eta_prey = 1.;
     eta_pred = 1.;
;
    OPEN(50,FILE='title.tex',STATUS='UNKNOWN');   &quot;title file&quot;
    write(50,5000) apar,cpar;                     
5000;format('Lotka-Volterra par:',2F4.1);
</pre></td></tr></table>

<a name="Variables-and-model-parameters"></a>
<h4 class="subsubheading"> Variables and model parameters </h4>

<p>The following variables are mandatory:
</p>
<dl compact="compact">
<dt> <code>dt</code></dt>
<dd><p>The time step.
</p></dd>
<dt> <code>time</code></dt>
<dd><p>Model time initialisation.
</p></dd>
<dt> <code>nstep</code></dt>
<dd><p>Number of iterations along the trajectory.
</p></dd>
</dl>

<p>There are no other mandatory variables. Some optional variables are used
to monitor the printout and ouput of results of the code.
As an example, the variable <code>modzprint</code> is used to set
the frequency of the printout of the model matrix and vectors during the
run (see <a href="Controlling-the-run.html#Controlling-the-printout-and-data-output">Controlling the printout and data output</a>).
</p>
<p>User&rsquo;s defined variable and Fortran or Mortran instructions can always be
added for intermediate calculus. To avoid conflict with the variables of the
Miniker code, the rule is that a users symbol must not have characters 
&lsquo;<samp>o</samp>&rsquo; 
in the first two symbol characters.
</p>
<p>In the predator-prey example there are two model parameters. The fortran
variables are called here <code>apar</code> for       a and <code>cpar</code> for       c.
If a Fortan type definition is needed, it should be set at the very beginning
of &lsquo;<tt>zinit</tt>&rsquo;. The predator-prey code variable initializations finally reads
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">!%%%%%%%%%%%%%%%%%%%%%%
! Parameters         
!%%%%%%%%%%%%%%%%%%%%%%
  real apar,bpar;        &quot;optional Fortran type declaration&quot;

     dt=.01;           
     nstep=10 000;    
     time=0.;            

! model parameters
     apar = 1.5;           
     cpar = 0.7;                                                            

     modzprint = 1000;  
</pre></td></tr></table>

<a name="Model-equations-1"></a>
<h4 class="subsubheading"> Model equations </h4>
<p><a name="Model-equations"></a>
</p>
<a name="index-set_005fPhi"></a>
<a name="index-set_005feta"></a>
<a name="index-var_003a"></a>
<a name="index-fun_003a"></a>
<a name="index-eqn_003a"></a>

<p>The model equations for cells and model equations for transferts are 
entered in two mortran blocks, one for the transferts, the other for the
cell components.  The model equations for cells are entered into a 
<code>set_eta</code> block, and the transfer equations are entered into a
<code>set_phi</code> block.
</p>
<p>In each block the couples variable-function are specified. For
transfers the function defines the transfer itself while for cells
the function describes the cell evolution. The variable is specified
with <code>var:</code>, the function is defined with <code>fun:</code>.
</p>
<p>In the case of the predator-prey model, the transfer variable
associated with       &#x03C6;meet could be called <code>ff_interact</code>
and the transfer definition would be given by:
</p><table><tr><td>&nbsp;</td><td><pre class="example">set_Phi
&lt; var: ff_interact, fun: f_interact = eta_prey*eta_pred;
&gt;;
</pre></td></tr></table>

<p>The two cell equations of the predator-prey model, with name
<code>eta_prey</code> for the prey (      &#x03B7;prey) and <code>eta_pred</code> 
for the predator (      &#x03B7;pred) are:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">set_eta
&lt; var: eta_prey, fun: deta_prey =   apar*eta_prey - apar*ff_interact;
  var: eta_pred, fun: deta_pred = - cpar*eta_pred + cpar*ff_interact;
&gt;;
</pre></td></tr></table>

<p>The &lsquo;<samp>;</samp>&rsquo; at the end of the mortran block is important.
</p>

<p>The whole model equations are setup with:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">!%%%%%%%%%%%%%%%%%%%%%%
! Transfer definition
!%%%%%%%%%%%%%%%%%%%%%%
! rencontre (meeting)
set_Phi
&lt; var: ff_interact, fun: f_interact = eta_prey*eta_pred;
&gt;;

!%%%%%%%%%%%%%%%%%%%%%%
! Cell definition
!%%%%%%%%%%%%%%%%%%%%%%

set_eta
&lt; var: eta_prey, fun: deta_prey =   apar*eta_prey - apar*ff_interact;
  var: eta_pred, fun: deta_pred = - cpar*eta_pred + cpar*ff_interact;
&gt;;
</pre></td></tr></table>

<p>Whenever the user is not concerned with giving a specific name to a
function, it is possible to specify the equation only with
<code>eqn:</code>. Therefore the user may replace an instruction as:
</p><table><tr><td>&nbsp;</td><td><pre class="example">  var: ff_dump,
  fun: f_dump  = - rd*(eta_speed - eta_speed_limiting);
</pre></td></tr></table>
<p>with:
</p><table><tr><td>&nbsp;</td><td><pre class="example">   eqn: ff_dump = - rd*(eta_speed - eta_speed_limiting);
</pre></td></tr></table>

<p>In that case, the unnamed function will take the name of the defined
variable preceded by the &lsquo;<samp>$</samp>&rsquo; sign: <code>$ff_dump</code>.
</p>
<a name="Starting-points"></a>
<h4 class="subsubheading"> Starting points </h4>

<a name="index-starting-point"></a>

<p>The cells equations require state initial conditions. In some case, the 
transfers may also need starting points although they are determined from 
the cell values.
</p>
<p>In the predator-prey model the starting points for cells are:
</p><table><tr><td>&nbsp;</td><td><pre class="example">!     initial state
!     -------------
     eta_prey = 1.;
     eta_pred = 1.;
</pre></td></tr></table>

<p>When there is a non trivial implicit relationship between the transfers
in the model, it may be usefull or even necessary to set some
transfers to non-zero values. This difficulty is only relevant for the very
first step of the simulation and will be used as a 
first guess of       &#x03C6;. The uninitialized transfers having 
a default compiler-dependant (often zero) value, an initialization
to another value may help avoiding singular functions or matrix and
ensure convergence in the Newton algorithm used to solve the transfer implicit
equation. 
</p>

<a name="The-cell-and-transfer-arrays"></a>
<h4 class="subsubheading"> The cell and transfer arrays </h4>

<a name="index-eta_0028_002e_0029"></a>
<a name="index-ff_0028_002e_0029"></a>
<a name="index-mp"></a>
<a name="index-np"></a>

<p>Sometime it is easier to iterate over an array than to use the 
cell or transfer variable name. This is possible because there is a
correspondence between the variable names 
and the fortran array <code>eta(.)</code> for the cell variables and
the fortran array <code>ff(.)</code> for the transfer variables<a name="DOCF1" href="mini_ker_fot.html#FOOT1">(1)</a>.
</p>
<p>The index of the variable is determined by the order of appearance in 
the variable definition blocks. It is reminded in the output, as
explained later (see <a href="Setting-and-running-a-model.html#Simulation-and-output">Simulation and output</a>). 
</p>
<p>The number of cells is in the integer <code>np</code> variable, and the
number of transfer is in the integer <code>mp</code> variable.
</p>
<a name="title-file"></a>
<h4 class="subsubheading"> title file </h4>

<p><a name="Title-file"></a>
<a name="index-title-file"></a>
<a name="index-title_002etex"></a>
</p>
<p>For some graphics generation, a file with name &lsquo;<tt>title.tex</tt>&rsquo; is required
which sets the title. The following instructions take care of that:
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">    OPEN(50,FILE='title.tex',STATUS='UNKNOWN');
    write(50,5000) apar,cpar;                 
5000;format('Lotka-Volterra par:',2F4.1);

    close(50);
</pre></td></tr></table>

<p>In that case the parameter values are written down, to differenciate between
different runs. This step is in general not needed.
</p>

<hr size="2">
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="mini_ker.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Concepts-index.html#Concepts-index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="mini_ker_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<p>
 <font size="-1">
  This document was generated by <em>a tester</em> on <em>a sunny day</em> using <a href="http://www.nongnu.org/texi2html/"><em>texi2html</em></a>.
 </font>
 <br>

</p>
</body>
</html>