mspass::seismic::LoggingEnsemble< T > Class Template Reference

Template class that extends Ensemble to include an error log and live tests. More...

#include <Ensemble.h>

Inheritance diagram for mspass::seismic::LoggingEnsemble< T >:

Public Member Functions
	LoggingEnsemble ()
	LoggingEnsemble (const size_t n)
	LoggingEnsemble (const mspass::utility::Metadata &md, const size_t n)
	LoggingEnsemble (const mspass::utility::Metadata &md, const mspass::utility::ErrorLogger &elogin, const size_t ndata)
	LoggingEnsemble (const LoggingEnsemble< T > &parent)
	LoggingEnsemble (const Ensemble< T > &parent)
void	kill ()
bool	live () const
bool	dead () const
bool	validate ()
bool	set_live ()
LoggingEnsemble< T > &	operator= (const LoggingEnsemble< T > &parent)
size_t	memory_use () const
Public Member Functions inherited from mspass::seismic::Ensemble< T >
	Ensemble ()
	Ensemble (const size_t n)
	Reserve space but build empty ensemble. More...
	Ensemble (const mspass::utility::Metadata &md, const size_t n)
	Ensemble (const Ensemble &parent)
Ensemble &	operator= (const Ensemble &parent)
T &	operator[] (const size_t n) const try
	catch (...)
	catch (...)
void	update_metadata (const mspass::utility::Metadata &newmd) try
	updates ensemble header (Metadata). More...
void	sync_metadata ()
	copy ensemble metadata to all members. More...
void	sync_metadata (std::vector< std::string > exclude)
	copy ensemble metadata to all members except for the ones excluded.
Public Member Functions inherited from mspass::utility::Metadata
	Metadata ()
	Metadata (std::ifstream &ifs, const std::string form=std::string("pf"))
	Metadata (const Metadata &mdold)
virtual	~Metadata ()
Metadata &	operator= (const Metadata &mdold)
Metadata &	operator+= (const Metadata &rhs) noexcept
const Metadata	operator+ (const Metadata &other) const
double	get_double (const std::string key) const override
int	get_int (const std::string key) const override
long	get_long (const std::string key) const
std::string	get_string (const std::string key) const override
bool	get_bool (const std::string key) const override
template<typename T >
T	get (const std::string key) const
template<typename T >
T	get (const char *key) const
	Generic get interface for C char array. More...
boost::any	get_any (const std::string key) const
std::string	type (const std::string key) const
template<typename T >
void	put (const std::string key, T val) noexcept
template<typename T >
void	put (const char *key, T val) noexcept
void	put (const std::string key, const double val) override
void	put (const std::string key, const int val) override
void	put (const std::string key, const bool val) override
void	put (const std::string key, const std::string val) override
void	put (const char *key, const char *val)
void	put (std::string key, const char *val)
void	put_object (const std::string key, const pybind11::object val)
void	put_int (const std::string key, const int val)
void	put_string (const std::string key, const std::string val)
void	put_bool (const std::string key, const bool val)
void	put_double (const std::string key, const double val)
void	put_long (const std::string key, const long val)
void	append_chain (const std::string key, const std::string val, const std::string separator=std::string(":"))
std::set< std::string >	modified () const
void	clear_modified ()
	Mark all data as unmodified. More...
std::set< std::string >	keys () const noexcept
bool	is_defined (const std::string key) const noexcept
void	erase (const std::string key)
std::size_t	size () const noexcept
std::map< std::string, boost::any >::const_iterator	begin () const noexcept
std::map< std::string, boost::any >::const_iterator	end () const noexcept
void	change_key (const std::string oldkey, const std::string newkey)
	Change the keyword to access an attribute. More...

Public Attributes
mspass::utility::ErrorLogger	elog
Public Attributes inherited from mspass::seismic::Ensemble< T >
std::vector< T >	member
	Container holding data objects. More...

Additional Inherited Members
Protected Attributes inherited from mspass::utility::Metadata
std::map< std::string, boost::any >	md
std::set< std::string >	changed_or_set

Detailed Description

template<typename T>
class mspass::seismic::LoggingEnsemble< T >

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.

Constructor & Destructor Documentation

LoggingEnsemble() [1/6]

template<typename T >

mspass::seismic::LoggingEnsemble< T >::LoggingEnsemble ( )

inline

Default constructor. Initializes all pieces with default constructor and marks the ensemble dead.

                   : Ensemble<T>(), elog()
  {
    ensemble_is_live=false;
  };

LoggingEnsemble() [2/6]

template<typename T >

mspass::seismic::LoggingEnsemble< T >::LoggingEnsemble ( const size_t  n )

inline

Reserve slots but otherwise create and empty ensemble marked dead.

This constructor is a minor variant from the default constructor that calls reserve to set aside n slotes for the data. Use this one when you know the size of the ensemble you want to create. Note after the ensemble, like the default constructor, is marked initially as dead. The user must call the set_live method of this ensemble after loading data or downstream processors may drop the data.

                                  : Ensemble<T>(n),elog()
  {
    ensemble_is_live=false;
  }

LoggingEnsemble() [3/6]

template<typename T >

mspass::seismic::LoggingEnsemble< T >::LoggingEnsemble ( const mspass::utility::Metadata &  md, const size_t  n  )

inline

Construct a framework for the ensemble with metadata.

This constructor loads the metadata received into the ensmeble area and reserves n slots to be added. Be warned it marks the ensemble dead. Once valid data are loaded the user should call the set_live method for the ensemble to prevent the data from being ignored downstream.

    : Ensemble<T>(md,n),elog()
  {
    /* Might be advised to set this true, but since an object created by
    this method has only slots but no data validate would return false.*/
    ensemble_is_live=false;
  }

LoggingEnsemble() [4/6]

template<typename T >

mspass::seismic::LoggingEnsemble< T >::LoggingEnsemble ( const mspass::utility::Metadata &  md, const mspass::utility::ErrorLogger &  elogin, const size_t  ndata  )

inline

Construct from all pieces.

This constructor was added for the python interface. It is a helpful construct for the pickle interface. It is unlikely to be of interest in a C++ application. Calls reserve only for member vector but but does not insert data - detail of the pickle implementation

      : Ensemble<T>(md,ndata),elog(elogin)
  {
  };

LoggingEnsemble() [5/6]

template<typename T >

mspass::seismic::LoggingEnsemble< T >::LoggingEnsemble ( const LoggingEnsemble< T > &  parent )

inline

Standard copy constructor.

          : Ensemble<T>(parent),elog(parent.elog)
  {
    ensemble_is_live=parent.ensemble_is_live;
  };

LoggingEnsemble() [6/6]

template<typename T >

mspass::seismic::LoggingEnsemble< T >::LoggingEnsemble ( const Ensemble< T > &  parent )

inline

Clone from a base class Ensemble. Initializes error null and sets live.

          : Ensemble<T>(parent),elog()
 {
   ensemble_is_live=true;
 };

Member Function Documentation

dead()

template<typename T >

bool mspass::seismic::LoggingEnsemble< T >::dead ( ) const

inline

Complement to live method - returns true if there are no valid data members.

{return !ensemble_is_live;};

kill()

template<typename T >

void mspass::seismic::LoggingEnsemble< T >::kill ( )

inline

Markt the entire ensemble bad.

{ensemble_is_live=false;};

live()

template<typename T >

bool mspass::seismic::LoggingEnsemble< T >::live ( ) const

inline

Getter to test if the ensemble has any valid data.

{return ensemble_is_live;};

operator=()

template<typename T >

LoggingEnsemble<T>& mspass::seismic::LoggingEnsemble< T >::operator= ( const LoggingEnsemble< T > &  parent )

inline

Standard assignment operator.

  {
    if(&parent != this)
    {
      this->mspass::utility::Metadata::operator=(parent);
      this->member.reserve(parent.member.size());
      this->member=parent.member;
      elog=parent.elog;
      ensemble_is_live=parent.ensemble_is_live;
    }
    return *this;
  };

References mspass::seismic::LoggingEnsemble< T >::elog, mspass::seismic::Ensemble< Tdata >::member, and mspass::utility::Metadata::operator=().

set_live()

template<typename T >

bool mspass::seismic::LoggingEnsemble< T >::set_live ( )

inline

Force, with care, the ensemble to be marked live.

This extension of CoreEnsemble adds a boolean that is used to test if an entire ensemble should be treated as dead or alive. It first runs the validate method. If validate is false it refuses to set the state live and returns false. If validate returns true it will return true.

                 {
    if(this->validate())
    {
      ensemble_is_live=true;
      return true;
    }
    else
      return false;
  };

References mspass::seismic::LoggingEnsemble< T >::validate().

validate()

template<typename T >

bool mspass::seismic::LoggingEnsemble< T >::validate

Check to see if ensemble has any live data.

In processing one 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.

{
  for(auto dptr=this->member.begin();dptr!=this->member.end();++dptr)
  {
    if(dptr->live()) return true;
  }
  return false;
}

Member Data Documentation

elog

template<typename T >

mspass::utility::ErrorLogger mspass::seismic::LoggingEnsemble< T >::elog

Standard mspass container for holding error logs.

---

The documentation for this class was generated from the following file:

• /home/runner/work/mspass/mspass/cxx/include/mspass/seismic/Ensemble.h