[ < ] [ > ]   [Contents] [Index] [ ? ]

2.3 Setting and running a model

In this section it is assumed that a programming environment has been properly setup. This environment may use either cmz or make to drive the preprocessing and compilation. You can skip the part related with the environment you don’t intend to use.

For instructions regarding the installation, see Installation.


[ < ] [ > ]   [Contents] [Index] [ ? ]

2.3.1 Setup a model and compile with cmz

The user defined sequences are ‘KEEP’ in the cmz world. The most common organization is to have a cmz file in a subdirectory of the directory containing the ‘mini_ker.cmz’ cmz file. In this cmz file there should be a ‘PATCH’ called ‘zinproc’ with the KEEPs within the patch. The KEEP must be called ‘$zinit’.

From within cmz in the directory of your model the source extraction, compilation and linking will be triggered by a mod command. This macro uses the ‘selseq.kumac’ information to find the ‘mini_ker.cmz’ cmz file. mod shall create a directory with the same name than the cmz file, ‘mymodel/’ in our example. In this directory there is another directory ‘cfs/’ containing the sources extracted from the cmz file.

The file ‘mymodel_o.tmp’ contains all the mortran code generated by cmz with the sequences substituted, including the ‘$zinit’. The fortran produced by the preprocessing and splitting of this file is in files with the traditional ‘.f’ suffix. The principal program is in ‘principal.f’. An efficient way of getting familiar with mini_ker methods is looking at the ‘mymodel_o.tmp’ where all sequences and main Mortran instructions are gathered. Symbolic derivation is noted as F_D(expression)(/variable), and the resulting Fortran code is in ‘principal.f’.

mod also triggers compilation and linking. The object files are in the same ‘cfs/’ directory and the executable is in the ‘mymodel/’ directory, with name ‘mymodel.exe’.


[ < ] [ > ]   [Contents] [Index] [ ? ]

2.3.2 Setup a model and compile with make

With make, the sequences are files ending with ‘.mti’ (for mortran include files), called, for example, ‘zinit.mti’. They are included by mortran in other source files. You also need a ‘Makefile’ to drive the compilation of the model.

If you don’t need additional code or libraries to be linked with your model you have two alternatives.

  1. The simplest alternative is to run the start_miniker script with the model file name as argument. It should copy a ‘zinit.mti’ file ready to be edited and a Makefile ready to compile the model. For the predator prey model, for example, you could run
     
    $ start_miniker predator
    
  2. Otherwise you can copy the Makefile from ‘template/Makefile’ in the directory containing the sequences. You should then change the compiled model file name, by changing the value of the model_file_name variable to the name of your choice in the Makefile. It is set to ‘mymodel’ in the template. For the predator-prey model, it could be set like
     
    model_file_name = predator
    

    If you want the executable model file to be built in another directory, you could set

     
    model_file_name = some_dir/predator
    

    The other items set in the default Makefile should be right.

The preprocessing and the compilation are launched with

 
make all

The mortran files are generated by the cmz directive preprocessor from files found in the package source directories. The mortran files end with ‘.mtn’ for the main files and ‘.mti’ for include files. They are output in the current directory. The mortran preprocessor then preprocess these mortran files and includes the sequences. The resulting fortran code is also in the current directory, in files with a ‘.f’ suffix. Some fortran files ending with ‘.F’ may also be created by the cmz directive preprocessor. The object files resulting from the compilation of all the fortran files (generated from mortran or directly from fortran files) are there too.

In case you want to override the default sequences or a subroutine file you just have to create it in your working directory along with the ‘zinit.mti’. For example you could want to create or modify a ‘zsteer.mti’ file (see Executing code at the end of each time step), a ‘zcmd_law.mti’ file (see Control laws), a ‘monitor.f’ file (see Turning the model into a subroutine) to take advantage of features presented later in this manual.

More in-depth discussion of using make to run Miniker is covered in Advanced use of Miniker with make. For example it is also possible to create files that are to be preprocessed by the cmz directive preprocessor and separate source files and generated files. This advanced use is more precisely covered in Programming with cmz directives.


[ < ] [ > ]   [Contents] [Index] [ ? ]

2.3.3 Running a simulation and using the output

Once compiled the model is ready to run, it only has to be executed. On standard output informations about the states, transfers, tangent linear system and other jacobian matrices are printed. For example the predator-prey model could be executed with:

 
./predator > result.lis

The correspondance between the symbolic variables and the basic vectors and functions are printed at run time:

 
  ---------------- Informing on Phi definition -----------------
    Var-name,           Function-name,       index in ff vector
             ff_interact              f_interact  1
  ----------------------------------------------------

  --------------- Informing on Eta definition ------------------
   Var-name,           Function-name,       index in eta vector
                eta_prey               deta_prey  1
                eta_pred               deta_pred  2

A summary of the model equations are in ‘Model.hlp’ file. For the same example:

 
======================= set_Phi                                                                
                                                                                         
    1 ff_interact f_interact           eta_pray*eta_pred
======================= set_Eta                                                                
                                                                                         
    1 eta_pray    deta_pray            apar*eta_pray-apar*ff_interact
    2 eta_pred    deta_pred            -cpar*eta_pred+cpar*ff_interact

when other general functions are specified with f_set, it can appear also in the same help file when replaced by fun_set.

As far as possible, all data printed in the listing are associated with a name related to a variable. Here is an extract:

 
 Gamma :-8.19100E-02-1.42151E-01 3.87150E-02
         eta_courant eta_T_czcx  eta_T_sz   
       ------------------------------------------------
 Omega : 0.00000E+00 0.00000E+00 0.00000E+00 0.00000E+00
         courant_L   T_czcx      Psi_Tczc    Psi_Tsz 
       ------------------------------------------------

for the two known vectors of the system, and:

 
 >ker : Matrice de couplage       4 4 4 4
courant_L Raw(1,j=1,4):   1.000     -9.9010E-03  0.000       0.000    
T_czcx    Raw(2,j=1,4): -2.7972E-02   1.000      0.000      9.9900E-04
Psi_Tczcx Raw(3,j=1,4):  0.1605      9.7359E-02  1.000     -5.7321E-03
Psi_Tsz   Raw(4,j=1,4):   0.000     -0.1376     5.7225E-03   1.000    
          Var-Name      courant_L   T_czcx      Psi_Tczc    Psi_Tsz 
          ----------------------------------------------------------

where the couplage (coupling matrix) is given that corresponds to the matrix coupling the four transfer components after δη has been eliminated from system. It is computed in the subprogram ‘oker’ (for kernel) which solves the system.

Basic results are output in a set of ‘.data’ files. The first line (or two lines) describes the column with a ‘#’ character used to mark the lines as comments (for gnuplot for example). In the ‘.data’ files, the data are simply separated with spaces. Each data file has the time variable values as first column. (2). Following columns give the values of eta(.) in ‘res.data’, dEta(.) in ‘dres.data’ – the step by step variation of eta(.) – and ff(.) in ‘tr.data’.

Along the simulation the TEF Jacobian matrices are computed. A transfer variables elimination process also leads to the definition of the classical state advance matrix of the system (the corresponding array is aspha(.,.) in the code). This matrix is output in the file ‘aspha.data’ that is used to post-run dynamics analyses. The matrix columns are written column wise on each record. See Stability analysis of fastest modes. See Generalized tangent linear system analysis. It is not used in the solving process.

Other ‘.data’ files will be described later.


[ < ] [ > ]   [Contents] [Index] [ ? ]

2.3.4 Doing graphics

Since the data are simply separated with spaces, and comment lines begin with ‘#’, the files can be vizualised with many programs. With gnuplot, for example, to plot eta(n), the gnuplot statement could be:

 
plot "res.data" using 1:(n+1)

The similar one for ff(n):

 
plot "tr.data" using 1:(n+1)

For people using PAW, the CERN graphical computer code, Miniker prepares kumacs that allow to read process the ‘.data’ files in the form of n-tuples (see the PAW manual for more information). In that cas, the flag sel paw has to be gievn in the ‘selsequ.kumac’. The generated n-tuples are ready to use only for vector dimension of at most 10 (including the variable time). These kumacs are overwritten each time the model is run. Usaually, gnuplot has to be preferred, but when using surfaces and histograms, PAW is better. The ‘gains.f’ (and ‘go.xqt’ is provided as an example in the Miniker files.


[Contents] [Index] [ ? ]

This document was generated by a tester on a sunny day using texi2html.