Tutorial: Difference between revisions

From openpipeflow.org
Jump to navigation Jump to search
mNo edit summary
mNo edit summary
Line 1: Line 1:
There is quite a bit of useful guidance in sections 6-8 on the [[Getting_started]] page.
'''This page is currently under revision!''' [today:2014/09/08].


An expanded tutorial will appear here soon [today:2014/09/04].
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.
 
 
== Setting parameters, starting and ending a run ==
 
* For serial use set <tt>_Np</tt> to <tt>1</tt> in <tt>parallel.h</tt> (no MPI required).  The compiler in <tt>Makefile</tt> might need altering if switching between parallel and serial use, or call <tt>mpirun -np 1 ...</tt>.
 
* Set the '''parameters''' in <tt>program/parameters.f90</tt>.
 
* Compile
<pre>&gt; make
&gt; make install  </pre>
The second command creates the directory <tt>install/</tt> and a text file [[main.info]], which is a record of settings at compile time.
 
* 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.

Revision as of 06:44, 8 September 2014

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 Makefile 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 'make' does not exit with an error.


Setting parameters, starting and ending a run

  • For serial use set _Np to 1 in parallel.h (no MPI required). The compiler in Makefile might need altering if switching between parallel and serial use, or call mpirun -np 1 ....
  • Set the parameters in program/parameters.f90.
  • Compile
> make
> make install  

The second command creates the directory install/ and a text file main.info, which is a record of settings at compile time.

  • Next an initial condition state.cdf.in is needed. NOTE: Any output state, e.g. state0012.cdf.dat can be copied to state.cdf.in to be used as an initial condition. If resolutions do not match, they are automatically interpolated or truncated.
> mv install ~/runs/job0001
> cd ~/runs/job0001/
> cp .../state0012.cdf.dat state.cdf.in
  • To start the run (good to first double-check in main.info that the executable was compiled with correct parameters)
> nohup ./main.out > OUT 2> OUT.err &

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 OUT.err or OUT for clues why.

  • To end the run, type
> rm RUNNING

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 i_Mp, use the utility changeMp.f90.

Monitoring a run

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

> less OUT

To find out number of timesteps completed, or for possible diagnosis of an early exit,

> tail OUT

The code outputs timeseries data and snapshot data, the latter has a 4-digit number e.g. state0012.cdf.dat.

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

> grep state OUT | less   [OR]
> head -n 1 vel_spec* | less

I often monitor progress with tail vel_energy.dat or

> gnuplot
> plot 'vel_energy.dat' w l

Use rm RUNNING to end the job.

Making a util

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

In Makefile, set UTIL = prim2matlab. In the utils/ directory there is a corresponding file prim2matlab.f90.

> make
> make install
> make util

Really, only the last command is necessary, which creates the executable prim2matlab.out. It is good practice, however, to do the previous commands to generate a main.info file to keep alongside the executable.