Qualitative experiments: the 'initial_positions.txt' file
Hello, in this module we will learn
how to position particles in space and time
to initiate a qualitative experiment with Ariane
and put this information in a text file.
Remember that a qualitative experiment
consists of placing 'by hand'
in the 3D grid of a model
one or more particles
and asking Ariane to calculate
their trajectory over a chosen period.
The files needed
for a qualitative experiment are:
- an output dataset of a model
like NEMO or ROMS,
- a description of the grid,
- an Ariane binary executable file,
- a Namelist text file
with the parameters of the experiment,
- a text file with the initial positions of the particles.
This is the context of this video.
We need to create a text file
in which each line describes
the initial positionof a particle.
To define the initial position of a particle
we need five parameters:
'gi', 'gj', 'gk', 'gl' and 'gt'.
The first four parameters are used to place
the particle in space and time.
The last parameter ('gt') in a qualitative experiment,
is a dummy parameter
that represents the transport
and is always positioned at 1.0.
We will see how to fill in this information
in 'gi', 'gk' and 'gl'.
Here we have a 3D schema of
a cell in the C grid
defined by Arakawa
centred at point 'T'.
Let's look at the horizontal plane first.
Here we find
the zonal components of the current 'U',
the meridional components of the current 'V',
and the point 'T' where temperature
and salinity are usually stored.
By default, one could imagine that we'd use
longitude and latitude to define
the position of a particle in Ariane
on the horizontal plane.
Instead, Ariane uses a different convention.
We use the indices
of the grid for each of the parameters.
Here these indices are represented
for the zonal component on the 'i' axis,
which corresponds to the longitude axis,
we have 'iu1'.
For the next component:
'iu2' = 'iu1' + 1.
We have the meridional components of the current
and the values of the tracers positioned in 'T'
whose index is also equal to 'iu1' + 1.
On the 'j' axis (latitude axis),
we have the 'j' components
referenced 'jv1' with regard to the meridional current.
The following component (or index)
is 'jv1' + 1, that is 'jv2'.
For the zonal component and the tracers
we also have 'jv1' + 1.
How do we position a particle in our cell?
We use the indices in the array,
but with real values
with 'gj' and 'gi' following the rules:
'gi' must be greater than or equal to 'iu1'
but strictly less than 'iu2'.
'gj' must be greater than or equal to 'jv1'
but strictly less than 'jv2'.
Let's take a sub-grid as an example
represented with four elements following 'i'
and four elements following 'j'.
We'll position a particle
in a particular mesh
and we'll take its position in 'gi':
here 'gi' = 2.85
and its position in 'gj', here 1.45.
Let's move on
to the position of the particle
on the vertical axis (here in black).
The convention for indices in Ariane
is 1 on the surface
and to increase the indices to the bottom of the model.
The 'W' points represent the vertical speed of the current
at level 'kw1' and, at greater depth, at 'kw2'
which is equal to 'kw1' + 1,
and the tracer point 'kt', which is equal to 'kw1'.
Here you can see the direction
of the indices according to depth.
In the same way as for latitudes and longitudes
the depth in meters is not given.
We always refer to the indices
of the array in relation to the depth.
When positioning a particle 'gk'
it will be given a value
greater than or equal to 'kw1'
but strictly less than 'kw2'.
Let's take an example.
I represent the surface with 'W1' = 1
and go down to 'Wn' for the ocean floor.
(I cut here as I don't have space for everything).
I have positioned two particles:
one particle at the exact depth
of the tracer point with 'gk' = 1.5
and another particle in the mesh
between depth 3 and depth 4
at 'gk' = 3.25.
An important recommendation:
do not place particles
in the corners of the cell,
i.e. take a real value
that would be the same as an integer value.
If you want to place your particle
in a corner of a cell,
take an integer value
and remove an epsilon value.
Then, your particle will be very close to a corner
but will not cause any problems
when running Ariane.
Now let's see how to position
the particle in time.
At the bottom of this diagram,
we have the model output recordings.
Here we have five recordings:
1, 2, 3, 4, 5,
which are in one or more NetCDF files.
In Ariane, like for the indices in space,
we have indices in time.
If you want to position your particle
exactly at the beginning of the first recording,
you should set 'gl' = 0.5.
To place it in the middle of the first recording,
you should set 'gl' = 1.
Here we position 'gl' at a point
in the first recording, between
the middle and the end.
Let's look at some concrete cases.
In the case where a recording
archived in a NetCDF file
corresponds to 1 day.
So we have day 1, day 2, day 3, day 4, day 5...
If you want to position a particle exactly
at 0:00 (midnight) at the beginning of the first recording,
you should set 'gl' = 0.5.
To position it in the middle of the recording at 12:00
you should set 'gl' = 1.0.
If recordings represent months
and each of these months represents 30 days,
here January, February, ... May...
if we set 'gl' = 0.5, we position
our particle at the very beginning of January.
If 'gl' = 2,
we are in the middle of February.
I remind you that there are 30 days in our example.
So this corresponds to the 15th day
of the month of February at 0:00.
In the module where we filled in a Namelist file
we looked at the 'Key_sequential' parameter
which allows us, in some cases,
to apply a periodicity
in time to our time series.
Here we have five recordings,
but, as we will apply a periodicity,
we can extend the integration in time.
How can we position a particle
beyond these five recordings?
Just extend the indexing
by adding + 1 etc.
For example, if I want to position my particle
in the middle of the 7th recording,
I put 'gl' = 7.
We have seen how to set 'gi',
'gj', 'gk', 'gl' and 'gt', which is always 1.0
in the case of a qualitative experiment.
Remember that it is vital to position
your particle in an 'ocean' (sea) cell.
If you place it on a 'land' cell,
you will get an error message ('default start')
when running Ariane.
The number of particles you can write
in your text file 'initial_positions.txt'
depends on the capacity of your computer:
from one line, to millions of lines/positions.
It depends on your computer's memory space.
If you want to position a large number of particles,
it is better to create a script manually.
We will look at this in later videos.
I remind you that it is possible
with Ariane, which is offline software,
to integrate the particles either forwards
or backwards in time.
In this case, you need to position
the particles accordingly.
Let's see an example of this:
how we should write this information
in a text file: 'initial_positions.txt'.
Let's go back to the directory
where we unarchived the Ariane package.
We find the Ariane package,
as when we compiled and installed the program,
in the 'bin' directory.
The instructions are in the 'doc' directory,
and the examples in the 'examples' directory.
Let's create a directory
in which we will archive our qualitative experiments.
We go into this directory.
Here, because we will do
several qualitative experiments,
we'll create a specific directory for our first experiment.
We go into in this directory.
We open a text file
with the command 'vi'.
We'll fill in the position of a particle.
We are going to simplify our example
by taking a model with
four dimensions along 'i' (longitudes),
four dimensions along 'j' (latitudes)
and two depths.
We will position a particle
at a fictitious location in our mesh.
I will choose a value for 'gi':
2.67, for example,
and a value for 'gj':
1.34.
I'll decide to place my particle
at the point 't' of my mesh: 1.5
of my first layer.
And I'll put my particle at the beginning
of my time series: 0.5.
I'll associate a transport that's always equal to 1.0.
I save this information.
If I want to add a second particle
to my model, I have to add
a second line, re-specifying
'gi', 'gj', 'gk', 'gl', and 'gt' for transport.
I have copied the first line
and I'm going to change it.
If I want to put my particle exactly
at point 'T' of mesh 1,
then I put 1.5.
Then I position it exactly
at point 'T', I put 1.5.
I'll go now to the 2nd layer,
with the value 2.5
and I decide to position it
at the second time recording.
Here, I just gave the description
of a 2nd particle in a 2nd mesh
at a 2nd time point.
If I want to add a third point
with a different depth,
I copy the line
and I simply change the depth
by placing it in the 1st layer for example.
If I want to add another particle
at the same place but at a different time,
I just have to adjust the time.
If I want to place it on the 5th recording
then I put 5, etc.
This allows us to fill in as many
positions of particles as we wish.
What have we seen in this video?
- We've seen how to position particles in space and time
so as to initiate a qualitative experiment in Ariane.
- We've seen how to put this information
in a text file: 'initial_positions.txt'.
In the following videos
we will see concrete applications
with the NEMO and ROMS models
of qualitative experiments.
Thanks and see you soon!