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.
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 state0000.cdf.dat, state0001.cdf.dat, state0002.cdf.dat, 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 Re2400a1.25/ containing an output state file state0010.cdf.dat and a main.info 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 parallel.h. Ensure that the number beside _Np 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
In the previous terminal window, edit the parameters so that they are the same as in the given main.info file
> nano program/parameters.f90
You 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 Makefile are set up correctly. The second command creates the directory install/ 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
Start the run
To start the run
> nohup ./main.out > OUT 2> OUT.err &
'&' puts the job in the background. 'nohup' allows you to logout from the terminal window without 'hangup' - otherwise, a forced closure of the window could kill the job. Output and errors normally sent to the terminal window are redirected to the OUT files.
A few seconds after starting the job, press enter again. If there is a message like
'[1]+ Done nohup...'
then it is likely that there was an error. In that case, try
> less OUT > less OUT.err
If there is a message about MPI libraries, and earlier you changed _Np from another value to 1, then you could try running instead with
> mpirun -np 1 ./main.out > OUT 2> OUT.err &
You might need to include a path to mpirun; search your Makefile for the mpirun command.
Monitor the run
> 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
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.
Make 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.
Visualise
TO DO