Ariane

Ariane is a particle tracking software that can be applied to NEMO and ROMS model NetCDF results files to trace the source of water masses (running backward in time) or to calculate where the water packet goes to (running forward in time).

Ariane can be run in two modes: quantitative and qualitative. In quantitative mode, you release particles and end up with a distribution function for each grid cell quantifying where your particles end up and the mass transfer, while in qualitative mode you specify each of the particles that you release and trace their exact track. For the rest of the documentation below, we are running in qualitative mode.

References

Getting Ariane

The MOAD group maintains our own Git repository on GitHub of the Ariane code base; this repository is accessible only by members of the MOAD group so as to respect the sign-up requirement of the upstream Ariane repository. The general Ariane code is available via the Ariane website . Modifications made by the MOAD group to the Ariane source code can be found on GitHub. To download the MOAD Ariane code base, clone the repository from GitHub to your $PROJECT space:

cd /ocean/$USER/$PROJECT/
git clone git@github.com:UBC-MOAD/ariane-2.3.0_03.git

Installing on salish

Configure the installation by going to the folder of your clone of the MOAD Ariane repo:

cd /ocean/$USER/$PROJECT/ariane-2.3.0_03
./configure --prefix=$PWD

The prefix argument overwrites the default install directory into a customized directory.

Make and install Ariane (you will need to do this every time you make changes to the code):

cd /ocean/$USER/$PROJECT/ariane-2.3.0_03
make
make check
make install

Add the path for the Ariane executable to your PATH environment variable:

export PATH=$PWD/bin:$PATH

Now you can run Ariane from any directory by typing ariane.

Testing Ariane installation

To test that you have everything set up correctly, run one of the Ariane examples. For instance, try:

cd /ocean/$USER/$PROJECT/ariane-2.3.0_03/examples/qualitative
ariane

You should notice several new files, such as results/ariane_trajectories_qualitative.nc and validation/traj.txt. These files contain the trajectory information.

  • results/ariane_trajectories_qualitative.nc contains the particle positions at each time step and the initial positions

  • validation/traj.txt gives a general idea of what the resulting trajectory coordinates look like or to check if the simulation ran properly

Configuring your run

intitial_positions.txt

The initial_positions.txt file specifies the initial positions and release times of the particles that you are tracking. This file consists of 5 columns and a row for each particle that you are running.

Note

Ariane uses FORTAN indexing, which counts starting at 1. If you used Python to look up initial positions, you should add 1 to your initial positions.

Within this file, the first three columns represent the initial X, Y, and Z coordinate point of your particle. A negative Z coordinate tells Ariane to confine the particle to its original depth throughout the trajectory. Note that these coordinate points should not be at the exact grid point coordinate, but rather offset by a little bit, otherwise Ariane may struggle at the boundaries between two grid boxes. The fourth column is the time index (use 0.5 if you want to start at NEMO time 00:00, if 0.0 it will interpolate between your data files), note that if you are running backwards, the time index here should be your end time step (so if you have a total of 330 time steps, you should release the particles at 329.5). The last column parameter is always set to 1.0. Here is an example initial_positions.txt file:

310.01 360.01 5.0  0.5 1.0
310.01 360.01 10.0 0.5 1.0
310.01 400.01 5.0  0.5 1.0
310.01 400.01 10.0 0.5 1.0
310.01 400.01 15.0 0.5 1.0

namelist

The namelist file specifies a variety of the run settings. The general Ariane parameters can be specified within Ariane; the main ones that you are likely to change are:

Parameter

Description

forback

Operate Ariane ‘forward’ or ‘backward’

nmax

Number of particles that you trace

tunit

Unit of time of your model files (sec)

ntfic

Number of tunit in each time step

The parameters of your model run are specified in OPAPARAM:

Parameter

Description

imt, jmt, kmt

x, y, and z dimensions of your model domain

lmt

Time dimension (total number of time steps)

In qualitative mode, the frequency of calculation of the trajectory and of writing to the output file is set within QUALITATIVE:

Parameter

Description

delta_t

Time step size (seconds)

frequency

Number of delta_t to calculate

nb_output

Number of output time steps ( in units of delta_t x frequency)

The parameters for reading in the U, V, and W velocity files are indicated in ZONALCRT, MERIDCRT, and VERTICRT. The parameters are roughly the same, for example in the ZONALCRT section:

Parameter

Description

c_dir_zo

Directory where data is stored

c_prefix_zo

NetCDF file name with velocity data

nc_var_zo

Variable name for velocity component

ind0_zo

First number of file to read

indn_zo

Last number of file to read

maxsize_zo | Maximum number of integers in file name number

Note that even in backwards mode, the first and last number of the files to read are in the forwards direction, i.e. from 1 to your last file number. Of course this is not a comprehensive list of all the parameters you can set in the namelist. More information can be found in the references listed at the start.

Analyzing output

The NetCDF file that contains the particle tracks is named ariane_trajectories_qualitative.nc. The variables in this file include the initial and final x, y, z, and time for the particles. It is a good idea to double check that these agree with the locations you listed in initial_positions.txt. To plot and analyze the output, you read in traj_lon, traj_lat, traj_depth, and traj_time. These variables have the shape (number of particles, positions in time).

If you would like to see some examples of particle tracking, feel free to look at the following notebooks: