[ < ][]   [Contents][Index]

2.2 Miniker programming illustrated

The general TEF system writes:

∂η(t) = g(η(t),φ(t))
 t
 φ(t) = f(η(t),φ(t))

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 TEF form:

{
  ∂tηprey = aηprey − aφmeet

  ∂tηpred = − cηpred + cφmeet
φmeet = ηpreyηpred

with two cell equations, i.e. state evolution of the prey and predator groups, and one transfer accounting for the meeting of individuals of different group.


[ < ][]   [Contents][Index]

2.2.1 All you need to know about mortran and cmz directives

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’t need to know anything about these directives. They are only usefull if you want to take advantage of advanced features (see Programming with cmz directives).

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:

The following fictious code is legal mortran:

real 
  param;
param = 3.; ff(1) = ff(3)**eta(1);       "a comment"                 
! a line comment
do inode=1,n_node <eta_move(inode)=0.01; eta_speed(inode)=0.0;>;

Thanks to mortran the model code is very simply specified, as you’ll see next.


[ < ][]   [Contents][Index]

2.2.2 Entering model equation and parameters

The model equation and parameters and some Miniker parameters are entered in the ‘zinit’ sequence. The whole layout of the model is given before detailing the keywords.

!%%%%%%%%%%%%%%%%%%%%%%
! Parameters           
!%%%%%%%%%%%%%%%%%%%%%%
  real apar,bpar;        "optional Fortran type declaration"

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

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

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

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

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

set_eta
< var: eta_prey, fun: deta_prey =   apar*eta_prey - apar*ff_interact;
  var: eta_pred, fun: deta_pred = - cpar*eta_pred + cpar*ff_interact;
>;


!%%%%%%%%%%%%%%%%%%%%%%
! Initial states
!%%%%%%%%%%%%%%%%%%%%%%
     eta_prey = 1.;
     eta_pred = 1.;
;
    OPEN(50,FILE='title.tex',STATUS='UNKNOWN');   "title file"
    write(50,5000) apar,cpar;                     
5000;format('Lotka-Volterra par:',2F4.1);

Variables and model parameters

The following variables are mandatory:

dt

The time step.

time

Model time initialisation.

nstep

Number of iterations along the trajectory.

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 modzprint is used to set the frequency of the printout of the model matrix and vectors during the run (see Controlling the printout and data output).

User’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 ‘o’ in the first two symbol characters.

In the predator-prey example there are two model parameters. The fortran variables are called here apar for a and cpar for c. If a Fortan type definition is needed, it should be set at the very beginning of ‘zinit’. The predator-prey code variable initializations finally reads

!%%%%%%%%%%%%%%%%%%%%%%
! Parameters         
!%%%%%%%%%%%%%%%%%%%%%%
  real apar,bpar;        "optional Fortran type declaration"

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

! model parameters
     apar = 1.5;           
     cpar = 0.7;                                                            

     modzprint = 1000;  

Model equations

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 set_eta block, and the transfer equations are entered into a set_phi block.

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 var:, the function is defined with fun:.

In the case of the predator-prey model, the transfer variable associated with φmeet could be called ff_interact and the transfer definition would be given by:

set_Phi
< var: ff_interact, fun: f_interact = eta_prey*eta_pred;
>;

The two cell equations of the predator-prey model, with name eta_prey for the prey ( ηprey) and eta_pred for the predator ( ηpred) are:

set_eta
< var: eta_prey, fun: deta_prey =   apar*eta_prey - apar*ff_interact;
  var: eta_pred, fun: deta_pred = - cpar*eta_pred + cpar*ff_interact;
>;

The ‘;’ at the end of the mortran block is important.

The whole model equations are setup with:

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

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

set_eta
< var: eta_prey, fun: deta_prey =   apar*eta_prey - apar*ff_interact;
  var: eta_pred, fun: deta_pred = - cpar*eta_pred + cpar*ff_interact;
>;

Whenever the user is not concerned with giving a specific name to a function, it is possible to specify the equation only with eqn:. Therefore the user may replace an instruction as:

  var: ff_dump,
  fun: f_dump  = - rd*(eta_speed - eta_speed_limiting);

with:

   eqn: ff_dump = - rd*(eta_speed - eta_speed_limiting);

In that case, the unnamed function will take the name of the defined variable preceded by the ‘$’ sign: $ff_dump.

Starting points

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.

In the predator-prey model the starting points for cells are:

!     initial state
!     -------------
     eta_prey = 1.;
     eta_pred = 1.;

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 φ. 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.

The cell and transfer arrays

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 eta(.) for the cell variables and the fortran array ff(.) for the transfer variables(1).

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 Simulation and output).

The number of cells is in the integer np variable, and the number of transfer is in the integer mp variable.

title file

For some graphics generation, a file with name ‘title.tex’ is required which sets the title. The following instructions take care of that:

    OPEN(50,FILE='title.tex',STATUS='UNKNOWN');
    write(50,5000) apar,cpar;                 
5000;format('Lotka-Volterra par:',2F4.1);

    close(50);

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


Footnotes

(1)

In fact the variables names are transformed into fortran array elements by mortran generated macros, so the symbolic names defined in the mortran blocks never appears in the generated fortran code, they are replaced by the fortran arrays.


[Contents][Index]