Feature/scripts-849-nf

[guilhermeltm]

Summary

This pull request adds the following features to the MONAN workflow:

1) Personalized mesh generation

This has been added as an (optional) second step in the MONAN workflow (2.create_mesh.bash). The main idea here is that, if needed, one can readily create a global or regional mesh with or without refinement, with all mesh characteristics set by the user according to the requirements of the experiment of interest. If one instead prefers to use a publicly available mesh (e.g. created by NCAR), this is also possible. The control over which mesh is used is set by the parameter MESH in 0.run_all.bash, which now substitutes the previous RES parameter, which indicated the number of cells of the mesh, but was only applicable to the particular case of NCAR meshes (following their standard naming x1.${RES}.grid.nc).

As hinted at above, the personalized mesh is generated by executing 2.create_mesh.bash. The characteristics of the mesh are set in mesh_input_file.txt.

The source code for this mesh generation step uses jigsaw (https://github.com/dengwirda/jigsaw) and adaptations from vtx-mpas-meshes (https://github.com/marta-gil/vtx-mpas-meshes) and MPAS-Limited-Area (https://github.com/MPAS-Dev/MPAS-Limited-Area). Since these adaptations are not available in the original repositories, I added them directly to sources/.

2) Option for running global or regional simulation

The previous workflow allowed only for global simulations. Now it is also possible to run regional simulations. A regional mesh can be directly created (without the need for separately cutting the mesh) by the mesh functionality explained above. The regional simulation then follows by setting parameters REGIONAL (flag to choose between regional and global simulation) and LBCINT (variable indicating the interval in seconds separating each update of lateral boundary conditions in the regional run) in 0.run_all.bash. Once REGIONALis set to Y, the workflow automatically generates by 3.pre_processing.bashthe initial and lateral boundary conditions needed for the simulation.

3) Option for running simulations with GFS or ERA5 data

In the previous workflow it was only possible to run simulations with GFS data. Now one can also use ERA5 data. To choose which data to use, one just needs to set EXP=GFSor EXP=ERA5 in 0.run_all.bash. Both options work both for global and for regional simulation setups.

4) Option for running standard idealized test cases for dynamics evaluation

For testing purely the dynamical core of MONAN it may be useful to run idealized simulations where all physics parameterizations are switched off. We now have the possibility of running standard dynamics test cases following the MPAS user guide (se https://www2.mmm.ucar.edu/projects/mpas/mpas_atmosphere_users_guide_8.2.0.pdf; section 7.1). At the moment the only test case completely implemented is the Jablonowski and Williamson baroclinic wave, with initial perturbation (number 2 in the user guide), but with the current setup this can easily be extended to the remaining test cases. Running this test case is basically a matter of choosing EXP=IDEALIZED2 in 0.run_all.bash.

5) Postprocessing on native MPAS grid (grid plotting, scalar field plotting and animation)

Now it is possible to plot both the generated MPAS grid and scalar fields from simulations directly on the native grid. Plotting the grid is achieved by plot_mpas_grid.bash, while plotting scalar fields on the native grid can be done via the new (optional) step 5 5.run_post_on_mpas_grid.bash. The source code in Python for these plots can be found under sources/CGFD-USP-Post-Proc. Using the source code one can also make animations by running mpas_animate.py, but no bash script is at the moment available for such animations under scripts/.

6) Script for automatically downloading ERA5 data

The python script download_era5_data.py in scripts allows for automatically downloading raw ERA5 data, either global or regional. All the setting for the download is done directly in download_era5_data.py, and the download itself is achieved by running python download_era5_data.py after activating our vtx_envconda environment (see remark 1 below).

Tutorials for testing

For learning how to use and testing these new features, 5 tutorials were created (see docs/):

1. tutorial1-meshes.md: generating your first personalized meshes
2. tutorial2-ideal-case.md: running a global simulation with idealized initial conditions and no physics parametrizations
3. tutorial3-real-case-global.md: running a global simulation with ERA5 data
4. tutorial4-real-case-regional-ERA5.md: running a regional simulation with ERA5 data
5. tutorial5-real-case-regional-GFS.md: running a regional simulation with GFS data

Remarks

1. The conda environment needed to run many of the scripts above is installed in the shared directory prepared for the WMO course under /pesq; how to use it is explained in the tutorials.
2. The directory where ERA5 data are saved needs to be adjusted (I didn't have the permissions to open a directory similar to that prepared for GFS data in EGEON).
3. Although implementation was performed both for ERA5 and GFS data, tests were more thoroughly performed for ERA5 (tutorials 3 and 4). For GFS I only tested if the whole workflow runs properly following tutorial 5.
4. Regional tests with ERA5 (tutorial 4) and GFS (tutorial 5) data worked for all preprocessing steps of the model. The runs themselves failed for MONAN, but worked for MPAS (I succesfully ran tutorials 4 and 5 using the preprocessed data generated by MONAN but using the MPAS code from our USP repository to perform the simualtions), so the preprocessing must be correct, but there seems to be an issue with the MONAN core_atmosphereregional configuration. Please have a look at this.
5. I haven't thoroughly worked on sanity checks and error messages for the new features. Please feel free to adapt the existing code as needed.

Acknowledgements

The code implemented here benefited from the work of many people:
Pedro S. Peixoto, Danilo C. de Souza, Felipe A. V. B. Alves, Guilherme L. Torres Mendonça (USP) - CGFD-USP: https://github.com/CGFD-USP
Darren Engwirda (CSIRO) - jigsaw: https://github.com/dengwirda/jigsaw
Marta G. Bardají (Vortex) - vtx-mpas-meshes: https://github.com/marta-gil/vtx-mpas-meshes
MPAS-Limited-Area team: https://github.com/MPAS-Dev/MPAS-Limited-Area
MPAS-Tools team: https://mpas-dev.github.io/MPAS-Tools/master/authors.html