Quantitative experiments: Part 5
Hello and welcome to this video series
about conducting a quantitative experiment with Ariane.
We will see how and why to stop all particles at the same integration time.
To do this, we will use a function available in the Ariane source code
via a criterion named 'criter 1'.
We will then see the functions associated with 'criter 1' and 'criter 0'
to influence the choice and evolution of the particles.
Our objective is to make our results more statistically robust.
We will start our presentation with this slide.
It shows a previous quantitative experiment in which
we positioned a number of sections.
In the previous video we removed the particles
that did not reach an interception section.
These particles were called 'lost particles'.
If you remember, our Namelist file had 21 years of data
from 1980 to 2000 (these are monthly data).
We asked Ariane to seed the first year
setting 'lmin=1' and 'lmax=12' (12 months).
We asked Ariane to integrate the trajectory of our particles in the forward (positive) direction.
What will our results look like?
If a particle is launched at the very beginning of our time series,
here on 1 January 1980,
and it is integrated over our entire dataset,
it will have an integration time of 21 years.
If we have a particle that is seeded on 31 December 1980,
it will only have 20 years of integration time.
Therefore, we do not have the same integration time for all particles.
From a statistical point of view, this is a problem.
So our goal in this video
will be to integrate the particles over the same duration
and this duration will be the shorter of the two.
Here, a particle launched on 31 December 1980 will be integrated for 20 years.
Therefore, we want all particles
to be stopped after 20 years of integration.
For example, our particle launched on 1 January 1980
will be stopped at midnight on 31 December 1999,
providing it is not stopped before that date by an interception section.
To do this, we will have to modify the Ariane source code.
This requires some knowledge of Fortran.
Later in this video we will modify the 'mod_criter1.f90' file.
This file can be found in several places in your file tree.
The place to change it is in the Ariane source code directory.
Reminder: Ariane source code is located in /Ariane/ (with a capital A).
Then, we have a folder named 'ariane-x.x.x_xx', which is Ariane's version number.
Then, we have a /src/ directory, which corresponds to the Ariane source code
and the main Ariane directory.
Changes have to be made to the 'mod_criter1.f90' file.
Be careful, this file is also present in other directories, such as 'bin'
and your experiment directories ('Expx').
Please do not modify the 'mod_criter1' file in the 'bin' directory or in your 'Expx' directory!
Only modify the file located in the specified directory.
If we edit the 'mod_criter1.f90' file (which we will do in a short while),
we will see there is a variable 'criter1', which is a logical variable.
This type of variable can take the values 'TRUE' or 'FALSE'.
By default, this value is set to 'FALSE'.
That is, when the particle is integrated over time, it is not stopped.
However, if at any time this logical variable changes to 'TRUE',
then Ariane will stop the particle.
The same happens when the particle is stopped by a geographic section.
So, if you edit your 'mod_criter11.f90' file,
you should find the line where 'criter1' is set to FALSE.
In our experiment, we want to stop our particles after 20 years.
To do this, the initialization command line
will be of the type 'criter1 = logic test'
This logic test will be as follows: [current date and time of particle integration]
minus [date and time of particle initialization]
and we will check if this date difference is less than or more than 20 years.
That is, superior or equal to 240,
240 being the number of months in 20 years (12 x 20).
If this date difference is greater than 20 years,
'criter1' will take the value 'TRUE',
and in this case, the particle will be stopped.
Conversely, if this date difference is less than 20 years
'criter1' will take the value FALSE
and our particle will not be stopped.
We see that 'criter1' behaves like an interception section,
but instead of being a geographic one,
like the ones we positioned in the 'sections.txt' file,
'criter1' will behave as a 'temporal' interception section.
We can take this idea a step further by creating sections based on different criteria.
In 'advanced mode' I can create
interception sections based, for example, on temperature.
If my temperature is below 10.5°C, then I will stop my particle.
I can also create a criterion based on salinity
or a slightly more complex criterion based on density.
For example, we can calculate the density at a specific depth (e.g. 2000 m)
from the temperatures and salinities in our program.
So, in Ariane, with the 'mod_criter1.f90' file,
it is possible to 'program' a particle interception according to any criterion.
There is no limit, you can write whatever you want in the code.
You can even use a relatively complex function
that will intercept a particle according to your chosen criteria.
In our experiment, we will simply use an interception
that is quite common in quantitative experiments:
a temporal interception.
One very important point to remember:
since you have modified the source code,
you must recompile and reinstall Ariane,
so the change is taken into account when you run your experiment.
In the directory where you have edited the 'mod_criter1.f90' file,
simply use the 'make install' command, which will recompile and reinstall the Ariane application.
Let's see this in more detail.
Here we are in the directory of Ariane source code:
'/Ariane/ariane-2.3.0_03/'
Let's go into the directory where 'mod_criter1.f90' is located.
I enter the command 'cd src/ariane'
and search for 'mod_criter1.f90'; here it is.
We will use an editor.
I will use 'vi', but you can use any editor,
to display the Ariane source code.
In this source code, we see the declaration
of our 'criter1' variable, which is of logical type.
A little further down in the code we find this command line,
which initializes the 'criter1' variable as 'FALSE'.
By default 'criter1' is always set to 'FALSE'.
That is, my particle is never intercepted
during the integration time of my experiment.
What I want to put here is a temporal interception.
I'm going to reuse an example.
There are many examples shown here.
I'm going to use an example of a temporal interception
that we will now describe together.
I'm just going to change the time
and set it to '240', that's it.
So, what is this command line made up of?
'hl' is the current integration time of the particle.
Further up, we have a description of these variables.
'hi', 'hj', 'hk' and 'hl' are the current positions of our particle.
'hi', 'hj' and 'hk' are the current geographic positions of the particle
and 'hl' is the current position of our particle in time.
The variables 'fi', 'fj', 'fk' and 'fl'
are the initial positions of our particle, geographically and temporally.
We will be able to find the difference,
as we showed in the earlier slide,
between the current integration time of our particle
and its initial position in time.
This is what we have coded here.
To make sure the value is positive,
we reinforce our difference with an absolute value.
Here we want 'criter1' to be 'greater than or equal to' 240.
Remember that 240 = 12 months * 20 years.
Thus, if this difference is less than 240,
'criter1' is set to FALSE and our particle continues to be integrated.
If our time difference is greater than 240 (> 20 years),
then 'criter1' becomes TRUE
and our particle will be intercepted.
This is the only change to make in the source code.
I now close the editor.
Now, one very important thing that you must not forget,
is to recompile and reinstall Ariane.
This can be done easily with a single line of command
directly in the directory
in which the 'mod_criter1' file is located.
Ariane recompiles my 'mod_criter1.f90' file.
It reobtains a link edit to get the Ariane executable
and then installs it in the 'bin' directory
to put my new executable where it belongs.
Now I'm going back to my 'Exp1' quantitative experiments directory.
Remember, we had 'Exp1_nolost' in our previous video.
We will create a new directory,
still with 'nolost' but adding 'criter1'.
We will call this directory 'Exp1_nolost_criter1'.
We will go into this directory.
We see a number of files,
either to be created through link editing,
or to be copied to be able to restart our experiment.
We are going to edit the link to our Ariane executable.
This was in /home/ariane/Ariane/bin/ariane.
Now, the new executable takes into account
our modification in 'mod_criter1.f90'.
This is very important.
We will copy the Namelist file from 'Exp1_nolost'.
We will copy 'sections.txt',
which is very important in a quantitative experiment.
We will copy the 'region_limits' file.
We need to copy the 'subset' file as well,
which is the file that will only include the particles
that are not lost in the domain.
And let's not forget to do some edit the links
to the 'Exp1' directory, in which we have
the results of the initial positions of our particles.
We now have in our directory
all the files needed to carry out our experiment,
taking into account the particles that are lost in our domain
and removed using 'subset.txt'.
And we have our new executable, which takes into account
the changes we made in 'mod_criter1.f90'.
Now, we just have to submit our experiment
to obtain our results.
Ariane has now finished running.
We will edit the output files.
The first file we need to look at is the 'stats.txt' file.
Let's open it to see if 'criter1' has been taken into account.
You will find the same results as in the 'nolost' experiment.
But this time, something new has appeared:
a new interception section.
I remind you that this is a temporal interception section
in which a small part of the transport has been intercepted: 0.0736 Sv.
If we go further down in our file,
we can see the exact number of particles
that have gone past the integration time of 20 years.
Here, 37 particles have been intercepted beyond the 20 years.
We managed to make our results more robust
as all the particles had a 20-year integration window.
This means all the particles had a 20-year integration opportunity
and all the particles that went beyond 20 years were stopped,
and removed from our statistics
because they did not reach an interception section.
I will show you a slightly more advanced mode.
If we look in our directory,
we see that we have 'mod_criter1.f90' plus two other similar files.
So we are going to check that we have
the changes made to our Ariane executable.
Indeed, 'criter1' has been taken into account
in our experiment to stop particles after 20 years.
We now also have the 'mod_criter2' and 'mod_criter0' files.
'mod_criter2' has become obsolete, you will never use it.
'mod_criter0', however, can be used.
I'm going to explain what it is.
This is a criterion that you might use, but this is done an 'advanced' mode.
Let's see more about this on a slide.
'criter0' has an action
on particle selection on the initial section(s).
It is a logical variable
found in the 'mod_criter0' file, in the same directory
as where 'mod_criter1.f90' is located,
in the Ariane source code.
On the one hand, when 'criter0' takes the default TRUE value,
then all the particles seeded by Ariane
on the initial section will be kept.
There will be no selection among the particles.
On the other hand, as with 'criter1', if you set a conditional statement
that sets 'criter1' to FALSE,
then the particles seeded by Ariane
will be removed and will not be taken into account.
I will quickly illustrate one example of this criterion
with seeding from an initial section and 'criter0 = TRUE'.
We see that Ariane has positioned a number of particles
in relation to the transport passing through the initial section
(transport = blues lines, particles = red stars).
If we change our 'criter0',
e.g. by setting a conditional statement for temperature,
i.e. if the temperature where our particle is positioned
is higher than a certain temperature, we keep the particle.
However, if the temperature on the initial section
where our particle is positioned is below a certain value (x),
then this particle is not taken into account.
That is, on the initial section, Ariane will seed particles,
but will also remove some particles according to our chosen criterion.
The result can be seen on the slide,
the particles and the transport remain unchanged.
However, we have an isoline
that will separate temperatures above x and below x.
All particles located below this isoline
have been removed and won't be taken into account
in the integration of our Ariane experiment.
With the 'criter0' mode, it is possible,
for example, to select particular water veins
according to a temperature, a position or a density
on the initial section.
Ariane instruments with respect to the transport
and you add a layer of selection of your particles
according to your chosen criterion,
There is no limit, anything is possible.
I'm going to emphasize an important point.
When you are about to move, say from 'Exp1' to 'Exp2',
you must reset 'mod_criter1' and 'mod_criter0' that were changed.
This is important because your code was compiled and reinstalled.
If you saved changes in a previous experiment,
these changes will also apply in the new experiment.
So don't forget to check the values for 'mod_criter1' and 'mod_criter0'.
This is why we usually copy these files over
and you can then check if any of the changes made
for your experiment are there.
In this video, we learned how to standardise the particle integration time:
here, 20 years.
To do this, we modified the 'criter1' function in the Ariane source code,
and we recompiled and reinstalled Ariane.
We have seen that 'criter1' can be used to set up other interception criteria.
Another criterion, 'criter0', handles the seeding control of the initial section.
In the next videos, we will learn to understand and to interpret the statistical results
of the 'ariane_statistics_quantitative.nc' file.
Thanks, see you soon!