Allow user to override library option defaults

[johnomotani]

In STORM we've started doing something like this to change the defaults for options (e.g. boundary conditions) that should always be set a certain way for a certain physics model, so that we don't have to have so many things in the input file

opt["n"]["bndry_xin"] = opt["n"]["bndry_xin"].withDefault("neumann_o2");

This PR is intended to allow this to be done for more options, by adding a static method PhysicsModel::setDefaults() that user physics model can override. This method is called in BOUTMAIN just after the options are read, and before Mesh, etc. are created. Also adds a convenience method for overriding defaults. So with this PR we can do something like

class MyPhysicsModel {
  static void setDefaults() {
    auto& options = Options::root();
    options["mesh"]["staggergrids"].overrideDefault(true);
  }
};

to make mesh:staggergrids default to true rather than false.

Comments on the design very welcome!

Note: it is important to use a reference auto& options rather than a copy so the options that are changed are changed in the global options. I thought about removing the copy constructor from Options so auto options = Options::root() would be an error and prevent this mistake - it seems to me like it would be nice but unfortunately std::map uses std::pair and std::pair requires a copy constructor, although this might change in C++17 https://stackoverflow.com/questions/23723744/stdpair-too-restrictive-constructor

[ZedThree]

Looks useful but I'm not terribly comfortable adding functionality to PhysicsModel in 4.3.0. Happy for it to go into next though, where we'll have more time to iterate on it if needed!

[johnomotani]

I wonder if there's an alternative design for this kind of feature, where the user could put some code to 'register' a default for an option, a bit like REGISTER_DERIVATIVE. If there's a way of doing this it would have the advantage of being more specific than the setDefaults() method proposed here, where the user could insert arbitrary code into BOUT++'s initialisation.

[ZedThree]

Ah, yes! Can probably be done if overrideDefault returned a value:

// Inside anonymous namespace because we don't want it to be a real global value
namespace {
const auto mydefault = Options::root()["mesh"]["staggergrids"].overrideDefault(true);
}

Putting that outside of main should be sufficient as it would initialise mydefault before calling main and I believe Options doesn't need anything else set up first (could be wrong). Could be wrapped up in a macro to make it easier to spell, and to take care of making a unique name for it:

#define BOUT_USER_OVERRIDE_DEFAULT_OPTION(option, value) \
  namespace { const auto user_default ## __FILE__ ## __LINE__ = \
    Options::root() option .overrideDefault(value) }

BOUT_USER_OVERRIDE_DEFAULT_OPTION(["mesh"]["staggergrids"], true)

(note: completely untested and also horrible)

The gross thing there is the option has to be passed in as indexing, which would be super easy to break. Could be done if we could make Options handle ["mesh:staggergrids"] as well. Not sure if that's a good idea or not.

[johnomotani]

Making Options handle ["mesh:staggergrids"] turned out to be straightforward, only 4 lines of code in two places, so that seems like a good way to go to me (unit test included).

I've added a macro as @ZedThree suggested to override defaults, and reverted the changes to BoutInitialise and PhysicsModel. If the new version looks good, I think it would be good to rebase this PR to get rid of any commits touching bout.hxx/bout.cxx/physicsmodel.hxx. Also to remove the change to make.config.in, which is a change that is in master, but I'd added by mistake to the first commit of this PR.

I've also added the "mesh:staggered" support, and BOUT_OVERRIDE_DEFAULT_OPTION to the manual.

[ZedThree]

Looks good! Please could you also add a unit test for overrideDefault?

[ZedThree]

Please could you change "testkey" and 1. here? I get nervous when test values could potentially clash!

[ZedThree]

Comment is out of date