stfinvbase.h 12.9 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
/*! \file stfinvbase.h
 * \brief C++ interface and abstract base class (prototypes)
 * 
 * ----------------------------------------------------------------------------
 * 
 * \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
 *  - 30/09/2011   V1.1   implemented handling of additional time series pairs
33
 *  - 14/10/2015   V1.2   new end-user usage functions
34
35
36
37
38
39
40
41
 * 
 * ============================================================================
 */

// include guard
#ifndef STFINV_STFINVBASE_H_VERSION

#define STFINV_STFINVBASE_H_VERSION \
42
  "STFINV_STFINVBASE_H   V1.2"
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185

#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 pair of time series.
   * \ingroup cxxinterface
  */
  struct WaveformPair {
    /*! \brief Temporal sampling
    */
    CWaveformHeader sampling;
    /*! \brief Time series of synthetic data.
     */
    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 WaveformPair

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

  /*! \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;
    /*! \brief Return source offset of this waveform
     */
    double offset() const;
  }; // class WaveformTriple

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

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

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

  /*! \brief Vector of pairs.
   * \ingroup cxxinterface
   */
  typedef std::vector<stfinv::WaveformPair> Tvectorofpairs;

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

  /*! \brief Vector 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 correction
   * filter
   * \ingroup cxxinterface
   *
   * \par What STFBaseEngine does for you
   * The base class takes care of parameter reading.
   * It parses the parameter string passed to its constructor and provides the
   * values through protected member functions:
   *   - STFBaseEngine::parameter
   *   - STFBaseEngine::parameterisset
   * 
   * \par
   * The funtion STFBaseEngine::run is called by the user and passes execution
   * to the virtual function STFBaseEngine::exec which ensures that the exec()
   * funtion of the appropriate child class is called to initiate processing.
   *
   * \par Initialization of engines
   * The following happens in a sequence, when engines are initialized:
   * -# The desired engine ins initialized either by the user directly
   *    or within the frame of STFEngine.
   * -# The constructor of this engine immediatly calls teh constructor of its
   *    base class.
   *    This again calls the constructor of its base class such passing down
   *    initialization to STFBaseEngine::STFBaseEngine
   * -# The constructor of STFBaseEngine takes the references to the storage
   *    locations for signal data as well as a parameter string.
   *    -# It fills its own references to the data storage locations and checks
   *       the consistency of parameters passed (size of arrays, sampling rates,
   *       etc).
   *    -# It then parses the parameter string and places its contents in the
   *       Mparamap parameter map.
   *    -# Then the base class parameters are set either from defaults or form
   *       values in the parameter map.
   * -# Initialization then continues at the next higher level in the class
   *    hierarchy.
   *    -# In the next level constructor additional workspace can be allocated
   *       based on the already available references to signal data and 
   *       parameter values.
   *    -# Further level specific parameters are set due to defaults or
   *       values passed in the parameter string.
   *
   * \par Handling of parameters
   * See STFBaseEngine::parameter() and STFBaseEngine::parameterisset()
   * for a description on how parameters are handled within engine classes.
   *
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
   * \par Data
   *  - recordings are understood as recorded waveforms.
   *    The number of available traces is returned by nreceivers()
   *  - synthetics are understood as synthetic waveforms generated with a
   *    generic source time function.
   *    For each trace of recordings there must be a matching trace of
   *    synthetics and vice versa.
   *  - convolvedsynthetics are produced from synthetics as a result of the
   *    application of the source wavelet correction filter.
   *  - series are additional synthetic time series, not used to construct the
   *    source-wavelet correction filter. The number of additional series
   *    traces is returned by npairs().
   *  - convolvedseries are produced from series as a result of the
   *    application of the source wavelet correction filter.
   *
201
   * \sa
202
   * \ref page_i_subsec_design_initialization
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
   *
   * \todo
   * The base class should provide a "log to file" option such that applied
   * weights and signal energies could be reported.
   */
  class STFBaseEngine {
    protected:
      /*! \brief Constructor.
       */
      STFBaseEngine(const stfinv::Tvectoroftriples& triples,
                    const stfinv::Waveform& stf,
                    const std::string& parameters);
      /*! \brief Constructor.
       * This constructor additionally takes a vector of time series pairs.
       * In this vector references to synthetic time series data can be
       * passed, which are not used in the process of determining the optimal
       * source correction filter but which are convolved with the new source
       * correction filter on the fly.
       */
      STFBaseEngine(const stfinv::Tvectoroftriples& triples,
                    const stfinv::Waveform& stf,
                    const stfinv::Tvectorofpairs& pairs,
                    const std::string& parameters);
    public:
      //! \brief abstract base requires virtual destructor
      virtual ~STFBaseEngine() { }

      /*! \name Basic interface for users
231
       * \sa \ref page_users
232
233
234
235
236
237
238
239
240
241
       */
      //@{
      //! \brief Start engine and return reference to source correction filter.
      stfinv::Waveform run() 
      {
        this->exec();
        return(Mstf);
      }
      //! \brief print online help
      virtual void help(std::ostream& os=std::cout) const;
242
243
      //! \brief print detailed description
      virtual void usage(std::ostream& os=std::cout) const;
244
245
246
247
      //! \brief return name of engine
      virtual const char* name() const;
      //! \brief print online help
      static void classhelp(std::ostream& os=std::cout);
248
249
      //! \brief print detailed description
      static void classusage(std::ostream& os=std::cout);
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
      //@}
        
      /*! \name Shape query functions
       */
      //@{
      //! \brief return number of samples used in time series
      unsigned int nsamples() const
      { return (Mstf.sampling.n); }
      //! \brief return number of receiver signals in use
      unsigned int nreceivers() const
      { return (Mtriples.size()); }
      //! \brief return number of additional signals to be convolved
      unsigned int npairs() const
      { return (Mpairs.size()); }
      //! \brief return sampling interval
      double dt() const 
      { return (Mstf.sampling.dt); }
      //@}

      /*! \name Data query functions
       */
      //@{
      //! \brief return source correction filter series
      Tseries stf() const 
      { return (Mstf.series); }
      //! \brief return recorded data at receiver \c i
      Tseries::Tcoc recording(const unsigned int& i) const ;
      //! \brief return synthetic data at receiver \c i
      Tseries::Tcoc synthetic(const unsigned int& i) const ;
      //! \brief return synthetic data convolved with stf at receiver \c i
      Tseries convolvedsynthetic(const unsigned int& i) const ;
      //! \brief return synthetic data of pair \c i
      Tseries::Tcoc series(const unsigned int& i) const ;
      //! \brief return synthetic data convolved with stf for pair \c i
      Tseries convolvedseries(const unsigned int& i) const ;
      //@}
        
    protected:
      /*! \name Functions presented to derived classes
       */
      //@{
      //! \brief return the value of a parameters
      std::string parameter(const std::string& key,
                            const std::string& defvalue="false") const;
      //! \brief check is parameter was set by user
      bool parameterisset(const std::string& key) const;
      //! \brief check for vaid receiver index
      void checkreceiverindex(const unsigned int& i) const;
      //! \brief check for vaid index off additional time series pair
      void checkseriesindex(const unsigned int& i) const;
      //! \brief Virtual function to run engine
      virtual void exec() { STFINV_baseillegal; }
      //! \brief return weight for signal at receiver i
      double weight(const unsigned int& i) const 
      { return(Mweights(i)); }
305
306
307
      //! \brief return weights array
      aff::Series<double> weights() const 
      { return(Mweights); }
308
309
310
311
312
313
314
315
      //@}

    private:
      /*! \name Functions implementing base class operation
       */
      //@{
      //! \brief initialize base class
      void initialize(const std::string& parameters);
316
      //! \brief parse parameters and store them in Mparamap
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
      void parseparameters(std::string parameters);
      //! \brief Check consistency of data members.
      void checkconsistency() const;
      //! \brief Set weights according to exponent
      void setweights(const double& k);
      //@}
      
    // member data
    // -----------

    protected:
      // protected members are accessed directly from derived classes
      //! \brief Waveform triples.
      stfinv::Tvectoroftriples Mtriples;
      //! \brief source correction filter.
      stfinv::Waveform Mstf;
      //! \brief Waveform pairs.
      stfinv::Tvectorofpairs Mpairs;
      //! \brief debug level
      int Mdebug;
      //! \brief verbose level
      int Mverbose;
    private:
      /*! \brief Parameter map
       * \note must be declared mutable, since std::map does not provide a
       * const read function.
       */
      mutable stfinv::tools::Tparamap Mparamap;
      //! \brief Weights
      aff::Series<double> Mweights;
  }; // class STFBaseEngine

} // namespace stfinv

#endif // STFINV_STFINVBASE_H_VERSION (includeguard)

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