Qualitative experiment: Setup
Hello and welcome.
We are going to set up a qualitative experiment.
A qualitative experiment consists of calculating,
from initial particle positions that you define,
the trajectory of these particles over time,
using a dataset of currents
from an ocean model
and from the Ariane program.
For more information on this type of diagnostic
please see the videos
on the theory behind Ariane.
We suppose that at this point you know how to create:
- an Ariane executable file;
- a Namelist file;
- a file 'initial_positions.txt'.
If this is not the case, please refer to
the earlier videos that cover these points.
Using a dataset provided in Ariane
and a configured Namelist file
we will calculate the trajectories of some particles
in the forward time direction.
We will first open a terminal
and go into the Ariane directory
which should be present on your computer.
If I list the contents of this directory
I should find the Ariane package, here in red,
and the directory containing the source code
we used for configuration,
compilation and installation
of the Ariane executable file,
which is found in 'bin'.
We will create a new directory
in which we will put
our qualitative experiments.
Let's go into in this directory.
As we are going to do several experiments,
we will create a directory for each of them.
We go into in this directory.
We will first check
the data from the ocean circulation model.
Here we will use the data available in Ariane package.
Let's look at the available files in this directory,
in particular the NetCDF files:
'reduc_4Dfields.nc'
and 'reduc_meshmask.nc'.
We will analyse their contents using the 'ncdump' command
and the '-h' option
for the file containing the current components.
In the header of the file we have the dimensions
which are 36 points in longitude,
30 points in latitude,
31 vertical levels,
and only 2 temporal recordings.
The available variables are:
- the zonal component of the current,
- the meridional component of the current,
- the vertical component of the current,
as well as tracers like
temperature, salinity and density.
In this example we will not use these
but it is possible to use them.
The second file of interest is the fine description
of the grid of our model.
We use the 'ncdump -h' command again
to see its contents.
We find the same dimensions as before.
And we also have information about
longitudes at points 'T', 'U', 'V',
as well as at point 'F'.
We have latitude information
at points 'T', 'U', 'V' and 'F'.
We also have information on the depths
at point 'T' and point 'W' on our grid.
We also have a very important piece of information,
which is the fine description for each mesh
of our scale factors.
This will allow us to calculate the transport
from our currents
for each dimension
until the vertical dimension with 'e3w'.
Finally, we have a 3D mask
which distinguishes the 'land' points from the 'ocean' points
setting '0' for land and '1' for ocean.
I'll go back into the directory
where I want to do my experiment,
and I see that it is empty.
The first thing to do
is to have an Ariane executable.
In the video on 'configuring and installing an Ariane executable'
you will see that I prefer
the use of a symbolic link
to point to the Ariane executable file.
Here I know that my executable file
is in the 'bin' directory
and that it is called 'Ariane'.
So now in my directory I have
a pointer to the Ariane executable file.
The second file I need for my experiment
is the Namelist file.
For this I use a tool
available on the Ariane web page.
I open a browser
and go to the official Ariane web page.
I go down the page a little
and I click on 'Ariane Namelist Assistant'.
I go to this page.
I remind you that I am using a NEMO model here.
So I click on 'NEMO-OPA'.
The dimensions of the model are:
longitude: 36 points,
latitude: 30 points
31 vertical levels,
and 2 temporal recordings.
I don't have any periodicity in longitude
or in latitude.
I simply extracted a sub-region
from my model, which was global.
I see that the 'W' component is available
so I don't ask Ariane to recalculate it.
The other important thing to know according to the model
is that partial steps are not used
so I put 'FALSE' here.
I also need to know
what each temporal recording
in my data file
from my model represents.
Here, each recording represents 6 months
of a year consisting of 360 days.
So each recording represents 180 days.
180 * 86,400 (the number of seconds in a day)
this is 180 days, expressed in seconds as Ariane needs.
I leave 'tcyc' = 0.
I will read my data sequentially.
This is what is generally recommended.
I'm asking for a qualitative diagnostic.
So I have to specify
what points along my trajectory
I want to record
in a NetCDF output file.
Here, the frequency I want
is every 30 days
one point along the trajectory
of the particles, which I will define.
So we saw that there are 2 recordings,
each representing 180 days,
making a total of 360 days.
So the maximum number of outputs,
if I put a particle at the very beginning
of my time series, will be 12.
12 * 30 days = 360 days.
I leave 'key_region' set to 'FALSE'.
I'll set the initial positions
in 'initial_positions.txt'
so I select 'nobin'.
I'm not starting from an old experiment,
I'm starting a new qualitative experiment
in which I manually enter in a text file
the initial positions of my particles.
Here I'll reduce the maximum number
of particles (less than 20).
I'll integrate the particle trajectories
in the forward time direction, so I leave 'forward' here.
I then need to indicate where to find
my ocean model data.
I go back to the directory
where my data are.
I see that the data are in this directory.
Here I have to enter the absolute link (I know it's in 'home').
I copy the information ... '/data'.
Here I have to enter the name of the NetCDF file.
There is only one, which makes things easier.
This is the name,
and I'm going to put it here.
There's no need to fill in the other fields
since there is only one file.
However, I saw that the name of my variable
for the zonal component of the current is 'U' (upper case).
So I type 'U' here.
There is no 'eddy induced velocity' for 'U',
or for 'V', so I leave 'NONE'.
There is no 'missing value' either
so I also put 'NONE' here.
I'll do the same thing
for the meridional component of the current.
I fill in the file name.
This is the same as for the zonal component,
but we could have had two different files.
There's no need to fill in these fields,
but the name of the variable
NetCDF is 'V' (upper case),
and there are no missing values.
The last (vertical) component of the current
is in the same file.
I use the same file name.
With only one file, there's no need to fill in the other fields.
Simply enter the name of the variable: 'W' (upper case).
There's no missing values here either
so I put 'NONE'.
We have seen that in this file
we have different tracers,
particularly temperature and salinity.
We could have put 'TRUE' here
and, for each tracer, fill in
the name of the variable, its file, etc.,
but for the sake of simplicity
I'll leave this value as 'FALSE'.
A final important point
is to fill in the fine description
of the grid of our model.
This time the file is different.
I'm going back to my terminal.
I go down to the description I had.
I see my file was called 'reduc_meshmask.nc'.
which I copy here.
We're in the same directory but the file name is different.
Here I need to fill in the longitude at point 'T'.
I see the name of my longitude is 'xt'.
So I'm putting 'xt' here
instead of the default name.
The name of the longitude at point 'U' is 'xu'.
The name of the latitude at point 'T' is 'yt'.
The name of the latitude at point 'V' is 'yv'.
For the vertical levels (depth)
the name of the variable is 'zw'.
For scale factors,
the variable names do not change.
If I examine the contents of my file:
'e1u', 'e2v', 'e1t', 'e2t', are also found here.
On the other hand, for the mask file
which is at the very end,
we have the name 'mt3d'
which I will have to transfer here:
'mt3d'.
Here it is zero that represents
values on land
so I leave these values at zero.
I can now click on
'Print on screen a beautiful Ariane Namelist'
and I get the contents of a Namelist file
That I will need to paste into a file.
I select all the information
that I obtained here.
I return to the directory
of my experiment.
I choose to use a text editor:
here 'gedit', but you can use another one.
'namelist' is the name of the file,
and I paste my data into it.
Here is the Namelist file created with the ANA tool
available on the Ariane web page.
Now I save it.
I use 'bg' to restore my screen availability.
If I look at what's in my directory:
I have an Ariane executable file,
I have a Namelist file…
To set up my execution,
the only thing missing is the file containing
the initial positions of the particles.
I create a new file
where I will put these initial positions.
Remember that in Ariane, the particle positions
are not given in longitudes and latitudes
but in grid point indices,
and these indices can be real
to allow exact placement
where we want in a cell.
The method I use
is to go back to the directory
where the model data are.
I find my model data.
I use the file with a fine description
of the model, particularly the 'land' mask
and I use the 'ncview' tool
to display this mask file.
'ncview' opens a window.
I'm going to ask it to represent
the 'land/ocean' mask
with ncview.
I click on an option here to
make the grid larger and more readable.
Here, we're on the surface
but you can display each of the
vertical levels of our model.
We can see the bathymetry changing.
I'll come back to the surface.
What's interesting is that when I
run my mouse over the grid,
I see the indices
changing according to 'i' and 'j'.
It's these indices 'i' and 'j'
that I will copy to my 'initial_positions.txt' file
to position my particles.
Here we have a part of the north
of the South Atlantic.
Here we see the east coast of South America
and the west coast of Africa.
I decide to position a particle here, for example.
These are the points 17 and 23.
Beware, in ncview, the points
go from 0 to n, so if you want
to use the same coordinates
you have to put 18.5 and 24.5.
I'm at the surface so it's 1.5.
If I want to position myself exactly
at the beginning of my first time series,
I put 0.5 as the temporal position.
I remind you to put 1.0 at the end,
even if this has no effect
in a qualitative experiment (nobin).
I can now position
a second particle a little further south,
for example 14.
So that's 18.5, 15.5,
I stay on the surface so 1.5, 0.5.
My particle starts at the first time step,
and I set 1.0 for transport.
I can add as many particles as I want,
but the number of particles must be <= 20
as indicated in my Namelist file
in the variable 'nmax'.
So I can't put more than 20 particles
and I already have two.
I'm going to put two more,
but at different levels:
I'll put one here at (28, 21),
so 29.5, 22.5 here;
a little deeper, so I'll put the level at 10.5;
0.5 for the temporal position,
and I leave the transport at 1.0.
And I'll put another point, for example,
here (11, 13) so that's 12.5, 14.5
I'll position it at a different level:
4.5 for example; I'll need to check
what depth this corresponds to.
And I position it at the beginning
of the second time step, so I put 1.5.
The particle will be positioned at the beginning
of the second recording.
And the transport will be 1.0.
So I've positioned four particles
in my model and I save this information.
The file name is 'initial_positions.txt'.
I can now close
my graphical representation with ncview.
I'm going back into the directory
where I'm doing my qualitative experiment.
I list my files.
I have an Ariane executable,
I have a Namelist file,
and I have an 'initial_positions.txt' file.
I also have a dataset available
in the directory as we saw earlier (/data).
So I'm ready to start my Ariane experiment.
I type './ariane' to start the experiment.
Since this is a very simple example,
with very little data,
it goes very fast.
I had hardly entered the command
and the program ran completely.
Let's go back to the start
because there's a lot of information.
I'll describe it quickly.
I ran the Ariane command.
So you have a reminder of the URL of the website,
the version of Ariane you are using,
the fact there's a licence,
information about the computer used,
the entire set of Namelist parameters:
the ones you defined,
but also all those used
in Ariane (so you'll see many more).
You can check all the information you entered.
There's a reminder that this is a qualitative experiment,
rather than a quantitative one.
Then there's some information
that I won't go over here.
Then there's a reading of the grid
and information about the grid:
longitudes and latitudes,
so you can check they correspond to your model.
Here are the depths.
We can see that the 'W' levels
start at almost zero on the surface
and go down to 5000 m depth.
The scale factors (in meters) that allow you
to recalculate a transport from the currents.
Here we have the mask file
whose values are 1 or 0,
depending on whether you are on land or ocean.
You are in a qualitative experience.
We start at the first recording.
Ariane will calculate 4 trajectories
since we had defined 4 particles.
The number of outputs is 12+1.
Ariane saves the initial position
of your particles + 12 recordings.
That's why we have 13 outputs rather than 12.
All information is saved
in the file 'ariane_trajectories_qualitative.nc'.
Here it writes everything in the NetCDF file.
From there, Ariane starts
to calculate the trajectory of the particle.
It says there are four particles.
Ariane reads the first recording,
tells us which file it is in,
gives some statistics on the zonal component,
the meridional component,
and on the vertical component.
This is where you need to check if there is
a good reading of your currents.
If you have outliers,
there is probably a problem
in the reading of your currents.
Then Ariane moves on to the second recording,
which is necessary
for the calculation of the rest of the trajectory.
You may get this message (highlighted)
if you are using a non-global region,
or where a particle can leave the domain.
Here the particle #4
whose initial position is displayed here
has left the domain.
You can see that it left in terms of latitude.
It went south and came out of the domain.
That's not a problem.
If your region is limited
and the borders are open,
then some particles can escape from the domain
and in this case they are stopped.
This was the case for this particle 4.
We will leave the calculation of the trajectories
as we have gone through the essential points of interest.
Ariane writes all this information
in a NetCDF file.
It tells us how much memory is used
and ends by reminding us of
the URL of the Ariane web page.
I'll stop here for this video.
In the following videos we'll see
the description of the Ariane output files
which are listed here.
We will also see
how to graphically represent
the trajectory of a particle.
To sum up, in this video:
- We set up a qualitative experiment.
- We checked the outputs of an
ocean circulation model (the content of the files).
- We pointed to the Ariane executable
after creating a directory
in which we completed
our qualitative experiment.
- We created a Namelist file
using the tool available
on the Ariane web page.
- We created a text file
in which we filled in
the initial position of our particles.
- Finally, we ran our Ariane experiment
and looked in detail at the output
of Ariane's execution on the screen.
Thank you very much. See you soon!