Move the solution method 'select case' block to the base class

[billsacks]

NOTE: This PR was originally created in the temporary CTSM repository by @billsacks, Sep 12, 2017, where it was NCAR/clm-ctsm#15. I am moving over the comments from there.

Original comment from @billsacks Sep 12, 2017

(Note that the setMetadata method is never called here: a full
implementation would need to call that in initialization for each
flux that builds on computeFlux_type.)

The purpose of this change was to remove what would presumably become
duplication of this select case statement throughout the code
base. However, I'm not very happy with how this change turned out. The
particular challenge here was handling the fact that different fluxes
would provide a different set of solution methods. This led me to put
stub methods in the base class that die at runtime if they are not
overridden, but I feel this makes the use of the base class less obvious
and more error-prone. (But I couldn't see a better way to do this - at
least, not with introducing a lot of extra complexity.)

Whether this extra step is worthwhile depends on how many instances of
this select case statement are sprinkled throughout the code, and how
much this is cluttering up the code. But overall, given that we
potentially have a different set of allowed methods for each flux, I'd
prefer not to go with the changes here - instead having some partial
duplication of the select case statements. Or we could go with the
solution suggested here
ea15490#r26526545
of having function pointers, which would allow moving these select case
statements to initialization (even though that would still involve many
partially-duplicated select case statements throughout the code).

Another problem with the changes here is that there will be some
performance overhead with the additional subroutine calls -
specifically, one extra call to 'solveForFlux' rather than having that
inlined. This is likely very bad with the current implementation -
point-by-point. With an array implementation, this cost is amortized
over all array elements, but may still be non-trivial - and will still
be a high cost for single-point runs.

--

In some ways, this could be clearer & simpler if we kept
computeFlux_type as it was in pondedWater/alternativeSolutions_oo, and
instead introduced a separate class to handle the selection between
methods. That separate class would have the stub implementations of the
various computeFlux methods. Then a flux would be required to provide
(some) implementations of the computeFlux* methods, but it would only
need to provide an implementation of computeFlux_type (i.e., the getFlux
method) if it wanted to call a solution method that required it (like
implicitEuler). The instance of the new class would then need to contain
an instance of the computeFlux child type, so that it can be referenced
by things like comuteFluxImplicitEuler.

The main advantage of this would be to provide a more clear signal about
whether a given flux can be plugged into things like implicitEuler,
which expects an implementation of a particular interface.

However, downsides are:

• Requires more boilerplate to set up the (now) two classes for a given
  flux
• I think there would be some awkwardness / duplication in terms of the
  internal variables that are stored in the class: I think these would
  now be needed in both the computeFlux child class and the new child
  class. (Though there may be some way to get the computeFlux class to
  reference things in the new class, e.g., by having a pointer to an
  object of the new class.)

One possible compromise is: keep the computeFlux_type as it was in
pondedWater/alternativeSolutions_oo, and make that a base class for the
new type. This would provide a more clear signal regarding what's needed
in implicitEuler, and a cleaner mechanism to plug a flux into
implicitEuler even if it doesn't want to extend the new class (because
you could extend computeFlux_type without extending the new class). The
new class would provide a default implementation of getFlux, which just
calls endrun. Then specific flux implementations would extend the new
class, and could then provide implementations for whatever computeFlux*
methods they want, as well as possibly providing an implementation for
getFlux (if needed).

• i.e., the inheritance chain would be: computeFlux_type (abstract
  interface of getFlux) -> some new class (provides stub implementations
  for getFlux and various computeFlux* methods) -> specific flux class
  (provides actual implementations as needed)
• But I'm not sure that buys us much relative to what we had in
  pondedWater/alternativeSolutions_oo: It does make it easier to use
  implicitEuler (for fluxes that don't want the functionalities of the
  new class – i.e., the selection between calculation mechanisms), but
  at the cost of introducing a new class into the design. This could be
  worth doing if this benefit would be useful in practice.

--

Another possibility would be to replace the 'select case' for the
solution method with polymorphism. However, this would require having a
separate class for each solution method for each flux, which feels like
a lot of coding overhead.

In this case, stuff shared between the different solution methods – such
as data that need to be set initially and the getFlux method – could be
in a base class for that flux, and then each solution method would
extend that base class, providing a computeFlux method.

But I think this is too much overhead. I think a better solution than
that would be to ditch the whole select case and solution_method stuff,
and go back to my earlier branch (pondedWater/alternativeSolutions_oo as
referenced in #192), and go with the
idea of using function pointers, as suggested by
ea15490#r26526545

[billsacks]

Comment from @billsacks Sep 12, 2017

I created this PR to record a solution that I had tried to prototype. But I don't like how it turned out, so I'm closing it - I really just wanted to use the PR mechanism to record this in case I want to come back to it later.