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).
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``).
**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) 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 (e.g., `EU` for European regions or alike, `GR` for Greenland, etc.), 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) 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.
4) 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 2 and wants to produce forcings for September 2010.
5) Go to the folder specified at the end of the command.
* **Important note:** depending on the origin of the data (i.e., which drive it comes from), the folder may not be completely ready when the command ``NST DOM yyyy mm set`` has completed. Check that everything has been copied (and uncompressed, if relevant) into the `./input` subfolder and that a `NSTing.ctr` file is present in the specified folder (this file is copied after the input data).
6) Next, edit the `MARgrd.ctr` file to calibrate your MAR (or nested) domain.
* The MAR mesh size (sixth parameter) gives the resolution you want in km.
* Next, tune the four consecutive longitude and latitude values (second to fifth parameter). The first and third give the longitude and latitude coordinates (in degree east and degree north, respectively) of your center of projection, while the second and fourth give the indices of the pixel in your grid that will correspond to this center of projection.
* Therefore, for the second and fourth values, you need to have a rough idea of the final horizontal dimensions of your MAR domain in grid cells on top of knowing your resolution.
* You can retune this file later if needed (see step 8).
7) Then, modify `src/NSTdim.inc` to calibrate it for both the input (large scale dataset) and output (MAR) domains.
* Modify `mx`, `my` according to the horizontal dimensions of the MAR domain you want. You can keep ``mz=24``.
* Modify `ni`, `nj` , `nk` according to the dimensions of the large scale dataset.
* To check these dimensions, go to `./input` in relation to the set-up folder, use ``ls -l`` to check the .nc files (or ``ls -l ./input`` while remaining in the parent folder), and use a NetCDF utility to review the contents of the file, such as ``ncdump``. Typically, ``ncdump -h my_file.nc`` prints both the dimensions and the list of variables.
* Normally, the other main parameters of `src/NSTdim.inc` (`mzabso`, `nvx`, `nsno`, etc.) can be left as they are, but depending on the region, it's advisable to reread the associated comments to choose the appropriate values (for example, `nvx=3` should be set for a region in Europe).
* 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.
8) 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.
* If your MAR domain needs to be adjusted, simply modify ``MARgrd.ctr`` (cf. step 6) and ``src/NSTdim.inc`` (cf. step 7), then recompile and rerun NESTOR.
9) 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.
10) Return to `~/MAR/bin` to start computing the forcings using NESTOR. Simply repeat the command from step 3 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).
* This command will only prepare the data for the selected month. If the simulation is to cover several months/years, it must be repeated for each month. To make things easier, use the `~/MAR/bin/NST_yr` script, the command line format being ``NST_yr DOM yyyy1 yyyy2`` where `yyyy1` and `yyyy2` are the start and end years.
* Enter the same year twice to do just one year, e.g., ``2011 2011`` for 2011.
* Note this particular script automatically launches NESTOR. If in doubt, use `qstat` or `squeue` (depending on your environment) to check what is running. Don't forget to add the right options to check only your own jobs if relevant, e.g., ``squeue --me`` with SLURM.
* If you modified `NST.ctr` and set ``n08`` (_graphic check file_) to T, the resulting NetCDF file will be placed in the subdirectory `~/MAR/out/DOM/input/NESTOR/YYYY/` (where `YYYY` is the year for which you are building forcings).
11) Wait a few minutes (or longer if several years have been prepared) for all jobs to finish and check that all the files produced are in the `~/MAR/out/DOM/input/NESTOR` folder (one sub-folder per year). You should now be ready to [compile and run MAR](guide-run-mar).
* 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`.
_Parts of this tutorial have been translated from French notes with [DeepL](https://www.deepl.com) and proofread._
