To set-up a MAR experiment over a given area (or domain) and time period, you need first large scale datasets providing at the very least temperature, humidity and U- and V-wind speeds on vertical levels spanning from the surface to the low stratosphere, the exact coordinates of each grid cell (longitude, latitude and pressure) being required as well. These variables should also be provided for every six hours (0, 6, 12, 18 o'clock) in a day for the target time period.
The step-by-step initialization of a MAR domain given below will not work in the absence of such files. Specific environments, such as climato\.be at ULiège, already provide such files natively (`~/MAR/bin/NST` is, in fact, tailored for climato\.be).
The step-by-step initialization of a MAR domain given below will not work in the absence of such files. Specific environments, such as climato\.be at ULiège, already provide such files natively (`~/MAR/bin/NST` is, in fact, tailored mostly for climato\.be).
Future tutorials will describe how to set up large scale datasets for NESTOR, complete with sample datasets. In the meantime, the following step-by-step initialization can be followed notably by ULiège members having access to climato\.be.
## Initializing a MAR domain with NESTOR, step by step
1) Log in to your favorite lab machine or cluster and go to `~/MAR/bin` (i.e., ``cd ~/MAR/bin``).
**Opening remark:** depending on the cluster, you may need to prepend MAR commands (`INI`, `NST`, `MAR`, etc.) with `./` (e.g., on the CNCCI cluster). This is unnecessary on climato\.be.
1) Log in to your favorite lab machine or cluster and go to `~/MAR/bin` with the `cd` command (i.e., ``cd ~/MAR/bin``).
**Note for climato\.be users:** it's essential to also connect to a server (e.g., srv7), otherwise the `NST` script will perform the set-up on your personal folder of climato\.be, where disk space per account is limited. On a server, the set-up folder will be placed in its `/scratch`, where there should be sufficient space.
2) Open `INI.ctr` and check the value of the `WLDreg` variable early in the script. Depending on your target region, you will have to set a specific overarching world region: `GR` for Greenland, `EU` for Europe, `WA` for West Africa, `AN` for Antartica, etc. If your target area is not encompassed by one of the given regions, you may choose the most similar region (e.g., for New Zealand, `EU` would be the most similar).
2) Open `INI.ctr`with your preferred text editor (e.g., `vi` or `gedit`) and check the value of the `WLDreg` variable early in the script. Depending on your target region, you will have to set a specific overarching world region: `GR` for Greenland, `EU` for Europe, `WA` for Africa, `AN` for Antartica, etc. If your target area is not encompassed by one of the given regions, you may choose the most similar region (e.g., for New Zealand, `EU` would be the most similar).
3) Type ``INI DOM`` where `DOM` is the name of your new MAR domain in three letters. By convention, the first two letters should be uppercase and refer to the overarching area of your domain selected at step 2, while the third should be lowercase and be specific to your new domain. E.g., `EUf` is a MAR domain in Europe identified by letter `f`.
3) Type ``INI DOM`` where `DOM` is the name of your new MAR domain in three letters. By convention, the first two letters should be uppercase and refer to the overarching area of your domain selected at step 2, while the third should be lowercase and be specific to your new domain. E.g., `EUf` is a MAR domain in Europe identified by letter `f`. The letter to use can be freely chosen.
4) Take a look at `~/MAR/bin/NST.ctr` to check the large scale (LSC) dataset you will use to compute MAR lateral boundary forcings. This boils down to checking ``n03=``. E.g., for ERA5 data on climato\.be, you may use ``n03=ER5``.
* This `NST.ctr` file describes the configuration that will later appear in the `NSTing.ctr` file (actual control file of NESTOR) in the work directory of NESTOR.
* Most other options do not have to be edited, because they already come with typical values to set up a MAR domain correctly. E.g., you can keep ``n04=MAR`` (nest the large scale dataset into a MAR domain) and ``n05="06"`` (boundary forcings every six hours).
* If you wish to always get a NetCDF equivalent of NESTOR forcings, you may set ``n08=T`` (``n08=F`` by default). Be wary that such files can get quite large and waste disk space, especially as MAR does not actually use them.
***For CNCCI users,** the default `NST.ctr` file can be kept as is, as it's already set for the large-scale forcings currently available on the CNCCI cluster and Africa. This said, it's good to check this file (with `cat` or a text editor) to learn its purpose.
5) Next, type ``NST DOM yyyy mm set``, where `DOM`, `yyyy` and `mm` are the MAR domain, year and month of your choice. For example, use ``NST EUf 2010 09 set`` if you typed ``INI EUf`` at step 3 and wants to produce forcings for September 2010.
...
...
@@ -50,14 +50,14 @@ Future tutorials will describe how to set up large scale datasets for NESTOR, co
* If you end up using a different data source than the one chosen via `NST.ctr`, you can correct the setup by copying a single NetCDF file to the setup folder in `./input`. Don't forget, of course, to check the dimensions with the command ``ncdump -h my_file.nc``.
***WARNING!** If you need to modify NESTOR source files to bring custom adjustments, such as topographical corrections (with or without a side NetCDF file), this is the right time to do that.
9) In the set-up folder on `/scratch`, recompile NESTOR with ``./Compile.exe`` and run it once with ``./NESTOR.exe`` to check that everything is working. In this case, for the purpose of the setup, NESTOR only runs for one day and always produce a NetCDF file, placed in the `./output` folder (w.r.t. NESTOR work directory). Use your preferred NetCDF viewing tool, and ensure the MAR domain matches your expectations, notably by consulting the SOL (surface type), TEX (soil texture) and SH (altitude) variables.
9) In the set-up folder on `/scratch`, recompile NESTOR with ``./Compile.bash`` and run it once with ``./NESTOR.exe`` to check that everything is working. In this case, for the purpose of the setup, NESTOR only runs for one day and always produce a NetCDF file, placed in the `./output` folder (w.r.t. NESTOR work directory). Use your preferred NetCDF viewing tool, and ensure the MAR domain matches your expectations, notably by consulting the SOL (surface type), TEX (soil texture) and SH (altitude) variables.
* Don't forget to check carefully the longitude and latitude extents (e.g., on `ferret`, use `shade TEX,LON,LAT`), especially after removing the relaxation zone or the so-called "sponge" of MAR (still in `ferret`, `shade/i=11:89/j=11:89 TEX,LON,LAT` for a 100 by 100 domain with a 10-pixel sponge). Your target area should be fully included in the MAR grid **after** removing the sponge.
* If your MAR domain needs to be adjusted, simply modify ``MARgrd.ctr`` (cf. step 7) and ``src/NSTdim.inc`` (cf. step 8), then recompile and rerun NESTOR.
10) Once you are satisfied with your MAR domain, from the set-up folder, run ``./dont_forget_to_copy_files_after.bash``.
* This script will copy the files from the setup folder (at least the relevant ones, such as the NESTOR code, `MARgrd.ctr`, `NSTing.ctr`, `NST*.nc` files, etc.) to `~/MAR/sim/DOM/input/NESTOR`. This is the folder you need to tweak if you ever need to redo the forcing later.
* This script will copy the files from the setup folder (at least the relevant ones, such as the NESTOR code, `MARgrd.ctr`, `NSTing.ctr`, `NST*.nc` files, etc.) to `~/MAR/sim/DOM/input/NESTOR`. This is the folder you need to modify if you ever need to redo the forcing later.
11) Return to `~/MAR/bin` to start computing the forcings using NESTOR. Simply repeat the command from step 5 without the ``set``, e.g., ``NST EUf 2010 09``, and submit the resulting script (given at the end) to your local job scheduler (e.g., `qsub path/to/script.cmd` on climato\.be).
...
...
@@ -70,4 +70,6 @@ Future tutorials will describe how to set up large scale datasets for NESTOR, co
* Note the `~/MAR/sim/DOM/input/NESTOR/output` folder will remain empty, but this is normal, as all NESTOR/MAR outputs are meant to be found in `~/MAR/out`.
By the end of this tutorial, your forcings for running MAR are ready ! You can move to the [Compiling and running MAR](guide-run-mar) tutorial.
_Parts of this tutorial have been translated from French notes with [DeepL](https://www.deepl.com) and proofread._
