Add support for shared config options

[xylar]

This merge adds the capability of sharing a config object across steps and tasks. This allows:

• shared steps like those for creating spherical meshes to have their own config options
• multiple tasks to share the same config options

The capability has been made possible by:

• storing a list of configs in each component
• the modifications to MpasConfigParser in https://github.com/MPAS-Dev/MPAS-Tools/pull/527
• modifying the PolarisConfigParser to include a filepath where it will be written and a list of symlinks that should be created
• adding methods to Task and Step for setting a shared config, which perform error checks, determine the paths for symlinks and add the config to the component
• extensive changes to the setup and run.serial modules to accommodate these other changes

The changes mean that it is now possible to add config files from the polaris package to the config object at initialization, rather than having to use the task's configure() method. Since config objects shared across tasks should ideally not be updated in a given task's configure() method, a setup() method has been added to PolarisConfigParser that can be overridden to perform more complex configuration as needed. So far, this capability is not being used.

Tasks have also been modified to make use of the functionality:

• Baroclinic channel tasks at a given resolution now all share a baroclinic_channel.cfg file in the resolution directory
• Shared icos and qu meshes now have their own config options in the shared step's directory
• Cosine bell task (with and without viz) and steps other than the base mesh all share a single config file. There are separate config files for the icos and qu versions of the tasks and steps.
• Remaining ocean tasks have been simplified to remove configure() methods that are no longer needed.

This merge requires updating to mpas_tools v0.24.0 to bring in the updates to MpasConfigParser.

Checklist

• [x] User's Guide has been updated
• [x] Developer's Guide has been updated
• [x] API documentation in the Developer's Guide (api.md) has any new or modified class, method and/or functions listed
• [x] Documentation has been built locally and changes look as expected
• [x] Testing comment in the PR documents testing used to verify the changes

[xylar]

Testing

I have successfully run all ocean tasks (except RPE at 1 and 4 km) on Chrysalis with Intel and OpenMPI.

I have verified that config files and symlinks appear in the expected locations, and that they retain the "raw" formatting that allows for extended interpolation (e.g. convergence_eval_time = ${cosine_bell:vel_pd}) upon reading them back in.

[xylar]

@cbegeman and @sbrus89, this is ready to review when you have time. The review can be at whatever level you have time for. The main thing I want to make sure of is that you are good with the changes I'm making at a conceptual level:

• Does it make sense to you that each step for making a uniform spherical mesh (e.g. ocean/spherical/icos/base_mesh/60km) has its own config options, and that there are shared config options between all the tasks in ocean/planar/cosine_bell/10km and ocean/spherical/icos/cosine_bell?
• Do the symlinks in each task and step to the relevant config file make it clear (for developers and users alike) what config file is being used?
• Is the process for making a shared config and adding it to test cases and steps clear enough that you would be able to borrow from the examples (baroclinic channel and cosine bell) to make use of it?

As always, suggestions (from broad to nit-picky) are welcome.

[xylar]

I'm running into some issues when I try to change resolutions in the cosine bell tests. Please hold off on reviewing this for now.

[xylar]

With a few more bug fixes, this now works even when I modify the resolutions for cosine bell in a user config file as part of setting up the test cases.

[xylar]

Okay, I finally got the new-new mpas_tools v0.25.0 working and this is ready for review. @cbegeman and @sbrus89, please take a look when you can. I'll continue to work on branches based off of this one in the meantime.

[xylar]

Great, thanks very much @cbegeman! I appreciate you taking the time to review and test!

[xylar]

Since @sbrus89 is away at a workshop this week, I think it would be better to get this merged now with @cbegeman's review. Other work is building on this so it is a little bit urgent.

[sbrus89]

Sorry I didn't get to this sooner @xylar and @cbegeman.