====== Tlab quick start guide ======

First things first - download the code from GitHub:
<code>
git clone https://github.com/turbulencia/tlab.git
</code>

This should have created a directory called ''tlab''. Go into the directory ''tlab'' and run the shell script ''configure.sh'':
<code>
./configure.sh
</code>
This will generate various build environments where you can compile the source code. If you type <code> ls </code> you will see four new directories have been created: ''build_BIG'', ''build_LITTLE'', ''build_PARALLEL'' and ''build_DEBUG''. For the purposes of running the code on an MPI PC, you only need ''build_BIG'' (MPI PCs use [[https://en.wikipedia.org/wiki/Endianness|big-endian format]]). 

Go into the directory ''build_BIG'' and type: <code> make -j </code> This will compile the code, running as many jobs simultaneously as possible. 

Now that the code is compiled, we can start to run one of the example cases! Change to the directory ''tlab/examples'' and list the files. You'll see there is a ''README'' file which starts off with a list of preprocessing, simulation and postprocessing tools. That list is organised into three columns. The first column tells you the name of the executable, the second column tells you the files you need to run that executable and the third column tells you the output of the executable. Below that there is a list of different cases you can run. For simplicity, let's take Case 23: [[https://en.wikipedia.org/wiki/Rayleigh%E2%80%93B%C3%A9nard_convection|Rayleigh-Benard convection]] with Dirichlet boundary conditions. This system is relatively straightforward as it only consists of the velocity field and one scalar field: the buoyancy. 

Change directory into Case23 and list the files. The ''dns.ini'' file contains all the parameters that define the system and the grid (see the manual for more details). The first thing we need to do is to generate the grid. Type:
<code>
~/tlab/build_BIG/inigrid.x
</code>
You should now have two new files: a ''grid'' file and a ''grid.sts'' file. Type <code> cat grid.sts </code> to see the details of the grid.

The next step is to create a small random perturbation to all fields. Type:
<code>
~/tlab/build_BIG/inirand.x
</code>
This will create the files ''flow.rand.*'' and ''scal.rand.1''.

Now we need to initialise the flow and scalar fields. Type:
<code>
~/tlab/build_BIG/iniflow.x
~/tlab/build_BIG/iniscal.x
</code>
This will have created the initial conditions for the velocity components: ''flow.ics.*'' and for the scalar field: ''scal.ics.1''. Rename these files:
<code>
mmv '*ics*' '#1\0#2'
</code>

Now we're ready to run a simulation! Type <code> vi dns.ini </code> to edit the dns.ini file. Under the heading ''[Iteration]'' set the parameters as follows:
<code>
Start=0
End=1000
Restart=100
Statistics=100
IteraLog=10
</code>
This tells the code to start at iteration number 0, run 1000 iterations, saving flow and scalar fields every 100 iterations, saving statistics every 100 iterations and outputting information to the log file ''dns.out'' every 10 iterations. Exit the ''dns.ini'' file. 

If you now type: <code> ~/tlab/build_BIG/dns.x &</code>
the code will run in the background. You can watch its progress with the command: <code> tail dns.out </code>