/*! \file stfinvbase.h
 * \brief C++ interface and abstract base class (prototypes)
 * 
 * ----------------------------------------------------------------------------
 * 
 * $Id$
 * \author Thomas Forbriger
 * \date 06/05/2011
 * 
 * C++ interface and abstract base class (prototypes)
 * 
 * Copyright (c) 2011 by Thomas Forbriger (BFO Schiltach) 
 *
 * ----
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version. 
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 * ----
 *
 * 
 * REVISIONS and CHANGES 
 *  - 06/05/2011   V1.0   Thomas Forbriger
 * 
 * ============================================================================
 */

// include guard
#ifndef STFINV_STFINVBASE_H_VERSION

#define STFINV_STFINVBASE_H_VERSION \
  "STFINV_STFINVBASE_H   V1.0   "
#define STFINV_STFINVBASE_H_CVSID \
  "$Id$"

#include<stfinv/waveformheader.h>
#include<stfinv/parameterhandler.h>
#include<stfinv/error.h>
#include<aff/series.h>
#include<iostream>
#include<vector>

namespace stfinv {

  /*! \brief Type of sample values.
   * \ingroup cxxinterface
   */
  typedef aff::Series<Tvalue> Tseries;

  /*----------------------------------------------------------------------*/

  /*! \brief A class to store the time series for a waveform triple.
   * \ingroup cxxinterface
  */
  struct WaveformTriple {
    /*! \brief The header is expected to be the same for all three time series.
     * In particular the number of samples must be appropriate for the memory
     * allocated for all three time series arrays.
     */
    CTripleHeader header;
    /*! \brief Time series of recorded data.
    */
    Tseries::Tcoc data;
    /*! \brief Time series of synthetic data.
     * This is understood as the impulse response of the subsurface.
     */
    Tseries::Tcoc synthetics;
    /*! \brief Time series of convolved synthetic data.
     * This will contain the synthetic data convolved with the obtained source
     * time function as a result of a call to the library functions.
     */
    Tseries convolvedsynthetics;
  }; // class WaveformTriple

  /*----------------------------------------------------------------------*/

  /*! \brief A class to store a single waveform.
   * This will be used to pass the source time function.
   * \ingroup cxxinterface
   */
  struct Waveform {
    /*! \brief Temporal sampling
    */
    CWaveformHeader sampling;
    /*! \brief Time series of waveform.
    */
    Tseries series;
  }; // class Waveform

  /*----------------------------------------------------------------------*/

  /*! \brief List of triples.
   * \ingroup cxxinterface
   */
  typedef std::vector<stfinv::WaveformTriple> Tvectoroftriples;

  /*----------------------------------------------------------------------*/

//! \brief Abort upon illegal call of base class function.
#define STFINV_baseillegal STFINV_abort("illegal call to abstract base class!")

  /*----------------------------------------------------------------------*/

  /*! \brief Abstract base class for engines to derive source time functions
   * \ingroup cxxinterface
   *
   * \sa
   * \ref sec_page_design_initialization
   */
  class STFBaseEngine {
    protected:
      /*! \brief Constructor.
       */
      STFBaseEngine(const stfinv::Tvectoroftriples& triples,
                    const stfinv::Waveform& stf,
                    const std::string& parameters)
      : Mtriples(triples), Mstf(stf)
      {
        this->checkconsistency();
        this->parseparameters(parameters);
      }
    public:
      //! \brief abstract base requires virtual destructor
      virtual ~STFBaseEngine() { }
      //! \brief Start engine and return source time function.
      virtual stfinv::Waveform run() { STFINV_baseillegal; }
      //! \brief print online help
      virtual void help(std::ostream& os=std::cout) const;
      //! \brief return name of engine
      virtual const char* name() const;
    protected:
      //! \brief return the value of a parameters
      std::string parameter(const std::string& key,
                            const std::string& defvalue="false") const;
    private:
      //! \brief parse parameters in Mparameters
      void parseparameters(std::string parameters);
      //! \brief Check consistency of data members.
      void checkconsistency() const;
      
    protected:
      // protected members are accessed directly from derived classes
      //! \brief Waveform triples.
      stfinv::Tvectoroftriples Mtriples;
      //! \brief Source time function.
      stfinv::Waveform Mstf;
    private:
      //! \brief Parameter map
      stfinv::tools::Tparamap Mparamap;
  }; // class STFBaseEngine

} // namespace stfinv

#endif // STFINV_STFINVBASE_H_VERSION (includeguard)

/* ----- END OF stfinvbase.h ----- */