MPAS tutorial runner

    Run a subset of the MPAS-Atmosphere tutorial exercises


Objective

    The purpose of this repo is to provide software packagers of the
    MPAS-Atmosphere (MPAS-A) numerical model with a simple "test" for
    validation of MPAS-A builds and packages. Assuming no knowledge of
    meteorology, the code simply automates the execution of a subset of MPAS-A
    tutorial exercises presented by NCAR in their annual tutorials documented
    at

    https://www2.mmm.ucar.edu/projects/mpas/tutorial/index.html

    and plot some results. At the time of writing (Oct. 2026), only the
    execution of the experiments (and optionally plotting) is automated. The
    "validation" of the results is not automated. Instead, the resulting
    figures have to be visually inspected and compared to the ones presented by
    NCAR on the tutorial webpage (link above). Originally the code was written
    to to quickly try out Guix packages of MPAS-A.


Disclaimer

    * the author has no background in meteorology
    * this "test" is qualitative at best, it's just to check if
      some of the tutorial exercises work as expected


Prerequisits

    * a build or installation of MPAS-Atmosphere (MPAS-A)
	see `src/versions.sh` for supported versions
    * bash
    * curl
    * git
    * sed
    * patch
    * python-netcdf4

    for plotting (to omit plotting, uncomment the `$PLOT` commands in
    `run_all.sh`):

    * python-matplotlib

    see the tutorial website for other software used


Run the test

    >> cd mpas_tutorial_runner
    # after setting the environment variables in env_vars.sh:
    >> source env_vars.sh
    >> ./run_all.sh
    # compare the figures with the ones presented in the NCAR tutorial
    >> find . -name *.png


Issues

    * At least when downloading from Europe, the gdex.ucar.edu server seems to
      be highly unreliable (503 Service Temporarily Unavailable).
    * The `run_all.sh` script executes a sequence of individual tests by
      calling `run_individual.sh` with different environment variables. The
      user might want to run only a single individual test, but currently this
      will likely fail if the the downloads/outputs from preceeding tests are
      not available.
    * The `model_integration` run creates a time-series of kinetic energy
      plots. These are not displayed in the tutorial, therefore we cannot know
      if they look correct. A general guideline may be that if the plots are
      viewed in chronological order, they should yield plausible general
      circulation patterns. This may be difficult to assess for software
      packagers unfamiliar with meteorology.
    * The tutorial contains only a subset of the tutorial exercises. Note that
      idealized experiments may seem attractive for tests, but may not read in
      any netCDF files, and therefore may be insufficient for testing the
      complete I/O stack.
    * With the evolution of the model, many task will become version-specific
      and require a more modular code design. For example, version pinning of
      dependencies may be required (e.g. `era5_to_int`) or `physics_wrf` files
      may no longer be required.
    * Do not use sed to parse xml, it may work here but seems to be generally
      bad practice.
    * How to test the I/O stack more thoroughly, in particular the `io_type`
      options documented in the MPAS-A user manual? We have used `fatrace` to
      check how many processes are writing to the history files. Using 8 mpi
      processes, `config_pio_num_iotasks=0` and `config_pio_stride=1`, fatrace
      reports `CWO` and `O` access from all processes, but then only one
      process makes write (`W`) accesses. Perhaps it makes no sense to test
      this using a single node? If two or more nodes are needed, would NFS be
      sufficient or do we need a real parallel filesystem like Lustre or
      Beegfs? `config_pio_num_iotasks=1` and `config_pio_stride=8` seems
      to work as expected, i.e. there is only a single process writing to the
      file. `config_pio_num_iotasks=2` and `config_pio_stride=4` seems to
      work at least partly as expected, in the sense that there are 2 processes
      writing, but the access patterns shown in `fatrace` seems to be
      confusing. The Ekin figures don't look wrong. Use `fatrace
      2>/dev/null|grep history.2014-09-10_00.00.00.nc` and wait for write
      access.


Changelog

    2026/10/26 readme.txt: update issues regarding `io_type`
