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