- Miniker 102 manual
- - 2 Miniker model programming

## 2.3 Setting and running a model

- 2.3.1 Setup a model and compile with cmz
- 2.3.2 Setup a model and compile with make
- 2.3.3 Running a simulation and using the output
- 2.3.4 Doing graphics

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.

### 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`’.

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

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

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

### Footnotes

### (2)

‘`dres.data`’ has another time related variable as second column: `dt`, the time step that can vary in the course of a simulation.