1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
|
<!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.3 Setting and running a model</title>
<meta name="description" content="Miniker 102 manual: 2.3 Setting and running a model">
<meta name="keywords" content="Miniker 102 manual: 2.3 Setting and running a model">
<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="Setting-and-running-a-model"></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="A-model-description.html#Model-equation-and-parameters" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Setting-up-a-model-with-cmz" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </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="Setting-and-running-a-model-1"></a>
<h2 class="section"> 2.3 Setting and running a model </h2>
<ul class="toc">
<li> <a href="#Setting-up-a-model-with-cmz">2.3.1 Setup a model and compile with cmz</a> </li>
<li> <a href="#Setting-up-a-model-with-make">2.3.2 Setup a model and compile with make</a> </li>
<li> <a href="#Simulation-and-output">2.3.3 Running a simulation and using the output</a> </li>
<li> <a href="#Graphics">2.3.4 Doing graphics</a> </li>
</ul>
<p>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.
</p>
<p>For instructions regarding the
installation, see <a href="Installation.html#Installation">Installation</a>.
</p>
<hr size="2">
<a name="Setting-up-a-model-with-cmz"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Setting-and-running-a-model" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Setting-up-a-model-with-make" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </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="Setup-a-model-and-compile-with-cmz"></a>
<h3 class="subsection"> 2.3.1 Setup a model and compile with cmz </h3>
<a name="index-mod"></a>
<a name="index-_0024zinit"></a>
<a name="index-_0024dimetaphi"></a>
<p>The user defined sequences are ‘<samp>KEEP</samp>’ in the
cmz world. The most common organization is to have a cmz file in a
subdirectory of the directory containing the ‘<tt>mini_ker.cmz</tt>’
cmz file. In this
cmz file there should be a ‘<samp>PATCH</samp>’ called ‘<samp>zinproc</samp>’
with the KEEPs within the patch. The KEEP must be called ‘<tt>$zinit</tt>’.
</p>
<p>From within cmz in the directory of your model the source extraction,
compilation and linking will be triggered by a <code>mod</code> command. This macro
uses the ‘<tt>selseq.kumac</tt>’ information to find the ‘<tt>mini_ker.cmz</tt>’
cmz file.
<code>mod</code>
shall create a directory with the same name than the cmz file,
‘<tt>mymodel/</tt>’ in our example. In this directory there is another
directory ‘<tt>cfs/</tt>’ containing the sources extracted from the cmz file.
</p>
<p>The file ‘<tt>mymodel_o.tmp</tt>’ contains all the mortran code generated
by cmz with the sequences substituted, including the ‘<tt>$zinit</tt>’. The fortran produced by the preprocessing and
splitting of this file is in files with the traditional ‘<samp>.f</samp>’ suffix.
The principal program is in ‘<tt>principal.f</tt>’. An efficient way of getting
familiar with mini_ker methods is looking at the ‘<tt>mymodel_o.tmp</tt>’ where
all sequences and main Mortran instructions are gathered. Symbolic derivation
is noted as <code>F_D(expression)(/variable)</code>, and the resulting Fortran code
is in ‘<tt>principal.f</tt>’.
</p>
<p><code>mod</code> also triggers compilation and linking. The object files are in
the same ‘<tt>cfs/</tt>’ directory and the executable is in the ‘<tt>mymodel/</tt>’
directory, with name ‘<tt>mymodel.exe</tt>’.
</p>
<hr size="2">
<a name="Setting-up-a-model-with-make"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Setting-up-a-model-with-cmz" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Simulation-and-output" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </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="Setup-a-model-and-compile-with-make"></a>
<h3 class="subsection"> 2.3.2 Setup a model and compile with make </h3>
<a name="index-compilation"></a>
<a name="index-zinit_002emti"></a>
<a name="index-model_005ffile_005fname"></a>
<p>With make, the sequences are files ending with ‘<samp>.mti</samp>’ (for
mortran include files),
called, for example, ‘<tt>zinit.mti</tt>’.
They are included by
<code>mortran</code> in other source files. You also need a ‘<tt>Makefile</tt>’
to drive the compilation of the model.
</p>
<p>If you don’t need additional code or libraries to be linked with your
model you have two alternatives.
</p>
<ol>
<li>
The simplest alternative is to run
the <code>start_miniker</code> script with the model file name as argument.
It should copy a ‘<tt>zinit.mti</tt>’ file
ready to be edited and a Makefile ready to compile the model. For
the predator prey model, for example, you could run
<table><tr><td> </td><td><pre class="example">$ start_miniker predator
</pre></td></tr></table>
</li><li>
Otherwise you can copy the Makefile from ‘<tt>template/Makefile</tt>’
in the directory containing the sequences. You should then change the compiled
model file name, by changing the value of the
<code>model_file_name</code> variable to the name of your choice
in the Makefile. It is set to ‘<tt>mymodel</tt>’ in the template. For the
predator-prey model, it could be set like
<table><tr><td> </td><td><pre class="example">model_file_name = predator
</pre></td></tr></table>
<p>If you want the executable model file to be built in another directory, you could
set
</p>
<table><tr><td> </td><td><pre class="example">model_file_name = some_dir/predator
</pre></td></tr></table>
<p>The other items set in the default Makefile should be right.
</p></li></ol>
<p>The preprocessing and the compilation are launched with
</p>
<table><tr><td> </td><td><pre class="example">make all
</pre></td></tr></table>
<p>The mortran files are generated by the cmz directive preprocessor
from files found in the package source directories. The mortran files
end with ‘<samp>.mtn</samp>’ for the main files and ‘<samp>.mti</samp>’ 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 ‘<samp>.f</samp>’ suffix.
Some fortran files ending with ‘<samp>.F</samp>’ 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.
</p>
<p>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
‘<tt>zinit.mti</tt>’. For example you could want to
create or modify a ‘<tt>zsteer.mti</tt>’ file (see <a href="Controlling-the-run.html#End-of-time-step">Executing code at the end of each time step</a>), a ‘<tt>zcmd_law.mti</tt>’ file
(see <a href="Adjoint-model-and-optimisation.html#Control-laws">Control laws</a>), a ‘<tt>monitor.f</tt>’ file
(see <a href="Calling-the-model-code.html#Turning-the-model-into-a-subroutine">Turning the model into a subroutine</a>) to take advantage of
features presented later in this manual.
</p>
<p>More in-depth discussion of using make to run Miniker is covered in
<a href="Advanced-use-of-Miniker-with-make.html#Advanced-use-of-Miniker-with-make">Advanced use of Miniker with make</a>.
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
<a href="Programming-with-cmz-directives.html#Programming-with-cmz-directives">Programming with cmz directives</a>.
</p>
<hr size="2">
<a name="Simulation-and-output"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Setting-up-a-model-with-make" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Graphics" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </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="Running-a-simulation-and-using-the-output"></a>
<h3 class="subsection"> 2.3.3 Running a simulation and using the output </h3>
<a name="index-running-model"></a>
<p>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:
</p>
<table><tr><td> </td><td><pre class="example">./predator > result.lis
</pre></td></tr></table>
<a name="index-output-file"></a>
<a name="index-dEta_0028_002e_0029"></a>
<a name="index-res_002edata"></a>
<a name="index-dres_002edata"></a>
<a name="index-tr_002edata"></a>
<a name="index-aspha_002edata"></a>
<a name="index-Model_002ehlp"></a>
<p>The correspondance
between the symbolic variables and the basic vectors and functions
are printed at run time:
</p>
<table><tr><td> </td><td><pre class="example"> ---------------- 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
</pre></td></tr></table>
<p>A summary of the model equations are in ‘<tt>Model.hlp</tt>’ file. For
the same example:
</p>
<table><tr><td> </td><td><pre class="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
</pre></td></tr></table>
<p>when other general functions are specified with <code>f_set</code>, it can appear
also in the same help file when replaced by <code>fun_set</code>.
</p>
<p>As far as possible, all data printed in the listing are associated
with a name related to a variable. Here is an extract:
</p>
<table><tr><td> </td><td><pre class="example"> 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
------------------------------------------------
</pre></td></tr></table>
<p>for the two known vectors of the system, and:
</p><table><tr><td> </td><td><pre class="example"> >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
----------------------------------------------------------
</pre></td></tr></table>
<p>where the <code>couplage</code> (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
‘<tt>oker</tt>’ (for kernel) which solves the system.
</p>
<p>Basic results are output in a set of ‘<samp>.data</samp>’ files.
The first line (or two lines) describes the column with a ‘<samp>#</samp>’
character used to mark the lines as comments (for <code>gnuplot</code>
for example).
In the ‘<samp>.data</samp>’ files, the data are simply separated with spaces.
Each data file has the <code>time</code> variable values as first column.
<a name="DOCF2" href="mini_ker_fot.html#FOOT2">(2)</a>.
Following columns give the values of <code>eta(.)</code> in ‘<tt>res.data</tt>’,
<code>dEta(.)</code> in ‘<tt>dres.data</tt>’ – the step by step variation of
<code>eta(.)</code> – and <code>ff(.)</code> in ‘<tt>tr.data</tt>’.
</p>
<p>Along the simulation the <acronym title="Transfer Evolution Formalism">TEF</acronym> 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 <code>aspha(.,.)</code> in the code).
This matrix is output in the file ‘<tt>aspha.data</tt>’ that is used to
post-run dynamics analyses. The matrix columns are written column wise on each
record.
See <a href="Stability-of-fastest-modes.html#Stability-of-fastest-modes">Stability analysis of fastest modes</a>.
See <a href="Generalized-TLS.html#Generalized-TLS">Generalized tangent linear system analysis</a>. It is not used in the solving process.
</p>
<p>Other ‘<samp>.data</samp>’ files will be described later.
</p>
<hr size="2">
<a name="Graphics"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Simulation-and-output" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="Controlling-the-run.html#Controlling-the-run" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </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="Doing-graphics"></a>
<h3 class="subsection"> 2.3.4 Doing graphics </h3>
<a name="index-graphics"></a>
<a name="index-graphics-with-gnuplot"></a>
<a name="index-graphics-with-PAW"></a>
<p>Since the data are simply separated with spaces, and comment lines
begin with ‘<samp>#</samp>’, the
files can be vizualised with many programs.
With <code>gnuplot</code>, for example, to plot <code>eta(<var>n</var>)</code>,
the <code>gnuplot</code> statement could be:
</p>
<table><tr><td> </td><td><pre class="example">plot "res.data" using 1:(<var>n</var>+1)
</pre></td></tr></table>
<p>The similar one for <code>ff(<var>n</var>)</code>:
</p><table><tr><td> </td><td><pre class="example">plot "tr.data" using 1:(<var>n</var>+1)
</pre></td></tr></table>
<p>For people using <code>PAW</code>, the CERN graphical computer code,
Miniker prepares
kumacs that allow to read process the ‘<samp>.data</samp>’ files in the form of
<em>n-tuples</em> (see the <cite>PAW manual</cite> for more information).
In that cas, the flag <code>sel paw</code> has to be gievn in the ‘<tt>selsequ.kumac</tt>’.
The generated n-tuples are ready to use only
for vector dimension of at most 10 (including the variable <code>time</code>).
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 ‘<tt>gains.f</tt>’ (and ‘<tt>go.xqt</tt>’ is provided as an example in the
Miniker files.
</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>
|
