Add an example of observing depth to water table

[ecoon]

Add an example that observes depth-to-water table, both in Vis and through Observations, at a point and averaged across the domain.

[ecoon]

This will be helped by, but is not blocked by amanzi/amanzi#622

[ecoon]

Email discussion to remind the assignee why and what needs to be done:

Vis saves all Fields in State. A Field must be created (and its metadata set) and updated. An Evaluator does both of these jobs -- the former upon construction and the latter one lazily when the Evaluator's Update() method is called (and its dependencies have changed, but let's ignore that half of the equation and assume they have).

Currently, adding water table to the list of evaluators alone will not trigger construction of the Evaluator or calling of the Update method. Only three things currently construct evaluators -- PKs, Observations, and other Evaluators (e.g. dependencies of things required by the PK or Observation). And those same three things call Update() when needed -- the PKs and Evaluators when the dependency graph is queried and the Observation when the observation is measured and written.

So, adding an entry to the field evaluators list for: "surface-depth_to_water_table" will do nothing on its own. And no PKs require it, and no other evaluators depend upon it, so currently the only way to get it constructed is to create an Observation that observes it.

So, in addition to putting it in the evaluators list, we also need to observe it to force its creation, and we should make that observation have the same times-start-period-stop as the vis to make sure that its Update() is called at the right times (otherwise, Vis does NOT trigger Update() being called, and since no one else is using it, it will not be correct!)

ASIDE: I think we should add the ability for Vis to also construct evaluators and call their Update() method at vis time when requested by the user, much like observations currently do, to get around this issue!

Now, how do we make that observation? This depends upon field, region, component, and "integration function." The field is obvious -- "surface-depth_to_water_table." Set this to be component "cell" and region equal to a 2D box/point/labeled set/whatever you want to observe depth to water table. This will create the Field "surface-depth_to_water_table", on all CELLS of mesh "surface", and will require an evaluator. That Evaluator will then get constructed based on the input spec, and its update will get called every time the observation is made. That evaluator is hard-coded over all CELLs, and depends upon the "saturation_liquid" field, which is a volumetric quantity. It loops over all surface cells, uses the build_columns() option, and iterates over the column's (subsurface) cells, starting from the top, to find the first saturated cell. It then uses that z to calculate the depth (relative to the surface cell's z coordinate), and stores it in the (surface cell) Field.

So the region should be on the 2D mesh. Likely it is a point measurement, but you could conceivably calculate e.g. the average depth to water table over the whole surface domain if you wanted, by using region="surface domain", component="cell", field="surface-depth_to_water_table", functional="average".

If someone does this, please add it to a demo and commit. If no one does this, make a ticket and eventually I'll get around to it or have @jbeisman do it.

[jbeisman]

I can look into this next week if it hasn't been addressed by then.