Proposed LoggingEnsemble addition

[pavlis]

I encountered a fundamental problem when I was redesigning and implementing a mspass version of the pwstack program. Ian, you know this algorithm well but Weiming the jargon would be mystery to you. The redisgn of pwstack for mspass, I am 100% sure, is a function that takes an input SeismogramEnsemble object and emits a different SeismogramEnsemble (the plane wave decomposition estimate from the input ensemble).

This revealed a fundamental flaw in handling this case. There is no easy way with the current Ensemble container to:

1. Log any error messages that are a common problem for the entire ensemble and not just the atomic members (e.g. a required missing ensemble metadata attribute).
2. There is no way to return a dead ensemble except an empty one, but an empty one has no way to clarify why it is empty.

For that reason I sat down this morning and wrote the following template class I propose we add to Ensemble.h. Note I haven't begun to test this so it may contain syntax errors. Template syntax is a good example of modern computer languages being an "incantation". Point for now is to put this up discussion. Note there are a few other sentences after the lengthy code block below:

#ifndef _LOGGING_ENSEMBLE_H_
#define _LOGGING_ENSEMBLE_H_
#include "mspass/utility/ErrorLogger.h"
#include "mspass/seismic/Ensemble.h"
/*! \brief Template class that extends Ensemble to include an error log and live tests.

This class extends the Ensemble class defined in MsPASS for bundling
collections of data that can be pushed to an std::vector container.  The
class is actually very generic, but mspass defines it for TimeSeries and
Seismogram objects.   This class is a necessary extension for an algorithm
that take ensembles in and emits a different ensemble.  In that situation
we need a way to indicate the entire ensemble is invalid and not be to used
and post error messages that give an explanation of why the output is invalid.
This class provides that mechanism by adding a mspass::utility::ErrorLogger
and a (private) boolean defining if the ensemble has valid data.  That makes
the API to a LoggingEnsemble a hybrid with the atomic Seismogram and
TimeSeries objects (adds the dna of ErrorLogger and live/dead concept).

A secondary fundamental reason this class can be needed is to parallelize
algorithms that emit an ensemble (regardless of inputs).  The live/dead
tests and error logger make the handlers consistent with the atomic objects
of mspass.
*/
template <typename T> LoggingEnsemble : mspass::seismic::Ensemble<T>
{
public:
  /*! Standard mspass container for holding error logs. */
  mspass::utility::ErrorLogger elog;
  /*! Default constructor.   Initializes all pieces with default constructor
  and marks the ensemble dead.*/
  LoggingEnsemble<T>(): mspass::seismic::Ensemble(), elog()
  {
    ensemble_is_live=false;
  };
  /*! Standard copy constructor.   */
  LoggingEnsemble<T>(const LoggingEnsemble<T>& parent);
  /*! Clone from a base class Ensemble.  */
  LoggingEnsemble<T>(const mspass::seismic::Ensemble& parent);
  /*! Markt the entire ensemble bad. */
  void kill(){ensemble_is_live=false;};
  /*! Getter to test if the ensemble has any valid data. */
  bool live(){return ensemble_is_live;};
  /*! Complement to live method - returns true if there are no valid data members. */
  bool dead(){return !ensemble_is_live;};
  /*! Check to see if ensemble has any live data.

  In processing once can occasionally (not rare but not common either)
  end up with enemble full of data marked dead.  This is a convenience
  method to check all members.  If it finds any live member it will immediately
  return true (ok).  If after a search of the entire ensemble no live members
  are found it will return false AND then mark the entire ensemble bad. */
  bool validate();
  /*! Standard assignment operator. */
  LoggingEnsemble<T>& operator=(const LoggingEnsemble<T>& parent);
private:
  bool ensemble_is_live;
};

template <typename T> LoggingEnsemble::LoggingEnsemble
   (const LoggingEnsemble& parent) : mspass::seismic::Ensemble(parent),elog(parent.elog)
{
  ensemble_is_live=parent.ensemble_is_live;
}
template <typename T> LoggingEnsemble::LoggingEnsemble
   (const mspass::seismic::Ensemble& parent)
       : mspass::seismic::Ensemble(parent),elog()
{
  ensemble_is_live=true;
}
template <typename T> bool LoggingEnsemble:<T>:validate()
{
  for(auto dptr=this->member.begin();dptr!=this->member.end();++dptr)
  {
    if(dptr->live()) return true;
  }
  return false;
}
template <typename T> operator=(const LoggingEnsemble<T>& parent)
{
  if(&parent != this)
  {
    this->Ensemble<T>operator=(parent);
    elog=parent.elog;
    ensemble_is_live=parent.ensemble_is_live;
  }
}
#endif

Note if we decide to include this I would advise:

1. Change the name of the current "Ensemble" to "CoreEnsemble" and make this subclass be "Ensemble". That will make the name usage consistent with Seismogram and TimeSeries.
2. Redefine SeismogramEnsemble and TimeSeriesEnsemble to be instances of "LoggingEnsemble" defined above instead of the current Ensembles with specific member types.

I think these changes can be done with little to no change to the existing python code base. It will, however, require some changes to the pybind11 code for sure.