Configure a Lagrangian diagnostic: The Namelist file part 1/4
Hello and welcome to this module.
Its objective is to learn how to configure
a Lagrangian diagnostic
with Ariane.
To do this, we are going to set parameters
in a very important file: the ‘Namelist’ file.
At this stage, we assume that the Ariane program
has been compiled, configured and is running on your computer.
Now we are going to have to tell Ariane
what type of diagnostic we want to do.
In earlier videos on the theory behind Ariane
you will have seen that
Ariane can do many things.
For this, we are going to use a key file: Namelist.
This file is interesting because it's a text file,
which makes it easy to fill out
and compatible with Fortran.
We are going to enter the parameters and variables
that allow us to use Ariane for our scientific needs.
So, we need to know how to fill out this Namelist file
Here is how we construct this file.
On the right-hand side of this slide
there are three name groups,
shown here in green, orange and purple.
The first group contains a certain number of variables,
and so on for the second and third groups.
This is how a Namelist file is organised:
by groups of variables.
Each group has a name
that starts with an '&' and finishes with a '/'.
Between these two characters
we will define variables,
which can be of various types:
e.g. 'real',
'integer',
'string',
or 'logic'.
We can also add comments,
which should be delimited with the "!" sign
that defines comments in Fortran.
Why do we have these different groups?
When you choose a variable in the first group, for example,
this variable may influence the running of Ariane,
which is going to read (or not) another group
according to which model it is currently running:
the NEMO model or ROMS model for instance.
Then Ariane will read another group with other variables, etc.,
each model being specific.
Another important point is that each variable
is already defined in Ariane
and has a default value.
For example, in group 2,
we see that 'var23' is not used.
It is thus not necessary to enter each and every variable.
Only those that are necessary in our experiment.
Undefined variables take the default values defined in Ariane,
but some variables must absolutely be defined.
For example, the name of the folder where model data are found.
Another point:
case is unimportant.
You may type in UPPER CASE or lower case.
Like in Fortran, this makes no difference.
We are going to learn how to fill in the Namelist file in Ariane.
There are several ways to do this.
The easiest is to go to the Ariane website.
On the main page you will find
here in this green box
the 'Online tool to create Ariane namelist file!'
with the possibility to click
on the link to start the Ariane Namelist Assistant (ANA).
Now let's look at this now.
Clicking on the link will bring you to this web page.
Tip: when you mouseover any word,
a box appears, giving you further information,
such as definitions or possible values for a variable.
For example, here this the meaning of a title.
Here it gives the purpose of the assistant, etc.
We are then going to look at a series of variables
that will have to be defined.
Finally, we click 'Print on screen a beautiful Ariane Namelist'
This will display the full content of the Namelist file
that you will need to copy into your Ariane Namelist file.
Let's start with the model.
Ariane accepts various types of models for input.
The two main models are the NEMO-OPA model
and the CROCO/ROMS model.
ROMS comes in a number of configurations, displayed here.
Ariane accepts other models,
but they are not available in this assistant.
When you click on the NEMO model,
empty fields are automatically displayed.
I have chosen 'NEMO'.
Here, you need to enter the dimensions of your model.
'imt' is the variable commonly used for this,
which you will find in your model output
when you use the ncdump -h command on a NetCDF file.
'imt' is the number of longitude points,
'jmt' is the number of latitude points,
'kmt' is the number of points on the vertical axis,
and ‘lmt’, importantly,
is the total number of all
the recordings output from your model.
I will stress one point:
this means adding together ALL of the recordings
that are available in ALL of the NetCDF files output from your model.
For example, if I have 2 model outputs each week
and 7 recordings in each of the files.
The ‘lmt’ I put here will be 7 + 7 = 14.
I emphasise that this is the total number of recordings.
Two other key parameters that are important,
especially if you are using the ORCA configuration, which is global:
there may be periodicity depending on the longitude.
If this is the case, click on TRUE.
Otherwise, click on FALSE.
You may also have a periodicity
especially with the ORCA configuration
where there is a bipolar system in the north
which creates a 'folding' in the northern hemisphere.
If this is the case, click on TRUE.
Otherwise, click on FALSE.
In the case of TRUE, you will be able to choose between two pivots.
On a type C grid, you can have a pivot following point F,
which is located in the angle of your cell if it is centred on T,
or on point T.
This depends on the model you use.
In general for ORCA 4, 2, 0.25 and 1 degree models
it is the T point that you choose (this is why I put it as default).
Let's choose 'FALSE' here to remove this information.
Here you have the opportunity to give Ariane
the vertical component of the current
or let Ariane recalculate it.
How does Ariane recalculate the vertical component of the current?
It takes into account that your model is non-divergent.
In other words, Ariane will recalculate the vertical speed
starting from the bottom of your model.
In this case you need to provide the entire water column of your model,
if you decide that Ariane must recalculate the vertical component of the current.
Then, thanks to the criterion of non-divergence,
it recalculates the first vertical velocity of the first bottom cell.
and so on up to the surface.
If the vertical component of the current is available in a NetCDF file,
click on FALSE here.
A little later, you will need to specify
the location of the netCDF file in Namelist.
With NEMO-OPA, there is also what we call 'partialsteps'.
At the final level, at the bottom of the ocean,
you can have a mesh that has different vertical heights.
Remember that we use the NEMO model with z coordinates.
and that, in 'partialsteps' mode, depth can take different values.
If this is the case, click on TRUE, otherwise click on FALSE.
You'll have to fill in some other information later.
Now let’s look at the case of the CROCO/ROMS model.
As with the NEMO model, we need to enter the model dimensions.
'xi_rho' is the number of points in longitude.
'eta_rho' is the number of points in latitude.
's_w' represents the number of points on the vertical.
But pay attention here, it is the number of points on the vertical
for the W grid points.
Warning: these are not the points centred on T but on W.
You will find this by doing an ‘ncdump’ at the output of the model.
Again, as for the NEMO model,
'time' is the total number of recordings
in ALL available NetCDF files that needs to be put here.
The TOTAL number of recordings.
Now we’ve entered the type of model and its dimensions,
we will explain to Ariane the meaning of a recording in time.
At the output of a model, you can make averages
hourly, daily, weekly, monthly, annually...
You choose the type of average you want from your model.
You now need to enter the information in Ariane.
This is what we will see in this section.
The unit we will use is the second.
The first parameter ('tunit') will, therefore, be in seconds.
Here, 86,400 seconds make one day.
Then, this figure is multiplied by a second variable: 'ntfic'.
‘ntfic x tunit’ represents the size of a recording.
If you have a recording of a day,
you just need to put ‘ntfic = 1’.
1 * 86,400 = 86,400 seconds = one day.
If you have monthly fields (30 days),
then you will need to put 30 * 86,400.
Now let's imagine that we have an hourly output.
We will change unit and put 3600 seconds.
Careful, it's a real number, that's why I put a point at the end.
So one hour = 3600 seconds and I put ‘ntfic = 1’.
‘ntfic * tunit’ represents an hour in seconds.
If I take the case where we save our recordings every 7 hours,
I am going to enter the number 7 here.
7 * 3600 seconds = 7 hours in seconds.
The last parameter, 'tcyc',
it is better to leave at 0 (the default) if you don't know it.
This parameter allows Ariane to normalise the time scale.
In your Ariane outputs you will have a NetCDF file,
and information along a trajectory as well as the age of the particles.
The age will be between 0 and 1.
By changing the 'tcyc' parameter,
you have the option to display it in days, weeks, months, as you prefer.
By default, leave it at 0 if you don't know how to use it.
In the next section, we will explain how to read Ariane's data
and how Ariane manages this data in the computer's memory.
In the 1990s, when Ariane was developed,
the tool was used on one-year climatological outputs
So we had 12 monthly fields
that were easily entered in the computer's memory.
Ariane would read these 12 fields and store them in the memory,
taking particle #1 and integrating it for as long as necessary.
This is the example shown on the main page of the Ariane website,
where a particle was integrated for more than 400 or 500 years.
Then particle #2 was integrated and so on.
It was very quick and simple, everything was in the memory.
Over the years the models have become more complex,
their resolution has increased, they are more realistic,
and they have high frequency outputs.
This represents large volumes of data
that can no longer be stored in computer memory.
So we had to change Ariane's strategy,
for this particular variable.
Now, with 'key_sequential', we can ask Ariane,
instead of putting everything in memory,
to read each of the recordings sequentially.
So Ariane will read a recording,
take all the particles, make them evolve
throughout the duration of this recording
(a duration like we specified above),
overwrite this recording with the next one,
integrate all the particles again
over the duration of this new recording,
and so on.
So you see that there are two strategies.
By default, you can use TRUE in all cases.
If you have a small dataset that fits in the memory,
you can use FALSE.
But by default, use TRUE.
It's quite fast and efficient.
When you select TRUE,
a new field appears: 'maxcycles'.
In the past, we put everything in the memory
and the temporal periodicity was calculated automatically.
We took 12 climatological fields,
and the particle was integrated for as long as necessary,
depending on the result we wanted.
When reading a more realistic series,
for example, if I have monthly fields from 2000 to 2020,
we can decide whether or not
to 'cycle' through this 20-year period of data.
This is a possibility offered here.
By default, the series is not cycled, i.e. it is read only once.
But,if you have chosen to cycle from the year 2020,
return to the beginning of the year 2000,
and integrate the particles again on that series,
it is possible to make this information evolve.
Here I put '2'.
This is an important point. By default put ‘1’,
but it is possible to cycle through your time series.
As you can see, there are many configuration parameters.
I suggest we take a break,
and continue with the explanations
in the following video. Thank you!