View source for Tutorial

'''This page is currently under revision!''' [today:2014/09/08].

If you haven't already, read through the [[Getting_started]] page.  Skip the 
[[Getting_started#Compiling_libraries]] section if someone has set up the libraries and <tt>Makefile</tt> for you.

The following assumes that the code has been downloaded ([[Main_Page#Download]]), and that libraries have been correctly installed 
([[Getting_started#Compiling_libraries]]), so that the command '<tt>make</tt>'
does not exit with an error.

=== Where to start from - initial conditions and the main.info file ===

The best input initial condition is usually the output state from another run, preferably from a run with similar parameter settings.
Output state files are named <tt>state0000.cdf.dat, state0001.cdf.dat, state0002.cdf.dat,</tt> and so on.  Any of these could be used as a potential initial condition.  If resolution parameters do not match, then they automatically interpolated or truncated to the new resolution (the resolution selected at compile time).

Download the following file from the Database: [[File:Re2400a1.25.tgz]]
Extract the contents:
 > tar -xvvzf Re2400a1.25.tgz
This should produce a directory <tt>Re2400a1.25/</tt> containing an output state file <tt>state0010.cdf.dat</tt> and a <tt>main.info</tt> file.  The [[main.info]] file is a record of parameter settings that were used when compiling the executable that produced the state file.

=== Set your parameters ===

We will assume serial use (for parallel use see [[Getting_started#Typical_usage]]).

The number of cores is set in <tt>parallel.h</tt>.  Ensure that the number beside <tt>_Np</tt> is 1:
 > head parallel.h
   ...
   #define _Np 1
   ...

If not, edit with your favourite text editor, e.g.
 > nano parallel.h   [OR]
 > pico parallel.h   [OR]
 > gedit parallel.h

In another terminal window, take a look at the main.info downloaded a moment ago
 > less Re2400a1.25/main.info

Edit the current parameters so that they are the same
 > nano program/parameters.f90
You may/should ignore from i_KL onwards.

=== Compile and setup a job directory ===

After setting the parameters, we need to create an executable that will run with the settings we've chosen.  To '''compile''' the code with the current parameter settings
 > make 
 > make install
If an error is produced, go back to the top and check that libraries and <tt>Makefile</tt> are set up correctly.
The second command creates the directory <tt>install/</tt> and a new [[main.info]] file.  Optionally, you could check for 
any differences between the new and given parameters
 > diff install/main.info Re2400a1.25/main.info

We'll create a new job directory with an initial condition in there ready for the new run
 > cp Re2400a1.25/state0010.cdf.dat install/state.cdf.in
 > mkdir ~/runs/
 > mv install ~/runs/job0001
 > cd ~/runs/job0001
 > ls -l
       main.info
       main.out
       state.cdf.in

=== Starting the run ===

* Next an '''initial condition''' <tt>state.cdf.in</tt> is needed. '''NOTE''': Any output state, e.g. state0012.cdf.dat can be copied to <tt>state.cdf.in</tt> to be used as an initial condition. If resolutions do not match, they are '''automatically interpolated or truncated'''. 
<pre>&gt; mv install ~/runs/job0001
&gt; cd ~/runs/job0001/
&gt; cp .../state0012.cdf.dat state.cdf.in</pre>

* '''To start''' the run (good to first double-check in [[main.info]] that the executable was compiled with correct parameters)
<pre>&gt; nohup ./main.out &gt; OUT 2&gt; OUT.err &amp;</pre>
After a few moments, press enter again to see if main.out stopped prematurely.  If it has stopped there will be a message e.g. '[1]+ Done nohup...'; check <tt>OUT.err</tt> or <tt>OUT</tt> for clues why.

* '''To end''' the run, type
<pre>&gt; rm RUNNING</pre>
and press enter.  This signals to the job to terminate (cleanly).  
Wait a few seconds then press enter again. There should be a message like,
'[1]+ Done nohup...', to say that the job has has ended.


* '''NOTE''': I generate almost all initial conditions by taking a state from a run with similar parameters. If there is a mismatch in <tt>i_Mp</tt>, use the utility [[changeMp.f90]].

=== Monitoring a run ===

Immediately after starting a job, it’s a good idea to check for any warnings

<pre>&gt; less OUT</pre>
To find out number of timesteps completed, or for possible diagnosis of an early exit,

<pre>&gt; tail OUT</pre>
The code outputs timeseries data and snapshot data, the latter has a 4-digit number e.g. <tt>state0012.cdf.dat</tt>.

To see when the in the run each state was saved,

<pre>&gt; grep state OUT | less   [OR]
&gt; head -n 1 vel_spec* | less</pre>
I often monitor progress with <tt>tail vel_energy.dat</tt> or

<pre>&gt; gnuplot
&gt; plot 'vel_energy.dat' w l</pre>
Use <tt>rm RUNNING</tt> to end the job.

=== Making a util ===

The core code in <tt>program/</tt> rarely needs to be changed. Almost anything can be done by creating a utility instead.
There are many examples in <tt>utils/</tt>. Further information can be found on the [[Utilities]] page.

In <tt>Makefile</tt>, set <tt>UTIL = prim2matlab</tt>.  In the <tt>utils/</tt> directory there is a corresponding file
<tt>prim2matlab.f90</tt>.
 > make
 > make install
 > make util
Really, only the last command is necessary, which creates the executable <tt>prim2matlab.out</tt>.
It is good practice, however, to do the previous commands to generate a [[main.info]] file to keep alongside the executable.