Commit 7af35d8f authored by thomas.forbriger's avatar thomas.forbriger Committed by thomas.forbriger
Browse files

renamed "source time function" to "source wavelet correction filter"

This is a legacy commit from before 2015-03-01.
It may be incomplete as well as inconsistent.
See COPYING.legacy and README.history for details.
the term "source time function" caused too much confusion, since it is
not the actual source time function which is derived here


SVN Path:     http://gpitrsvn.gpi.uni-karlsruhe.de/repos/TFSoftware/trunk
SVN Revision: 4723
SVN UUID:     67feda4a-a26e-11df-9d6e-31afc202ad0c
parent 5b6131ef
......@@ -4,7 +4,7 @@
#
# Copyright (c) 2011 by Thomas Forbriger (BFO Schiltach)
#
# create library for source time function inversion (libstfinv)
# create library for source wavelet correction filter determination (libstfinv)
#
# ----
# This program is free software; you can redistribute it and/or modify
......
/*! \file libstfinv/README
* \brief STFINV library: inversion for source time function (libstfinv)
* \brief STFINV library: seek source wavelet correction filter (libstfinv)
*
* ----------------------------------------------------------------------------
*
......@@ -7,7 +7,7 @@
*
* Copyright (c) 2011 by Thomas Forbriger (BFO, Schiltach)
*
* STFINV library: inversion for source time function (libstfinv)
* STFINV library: seek source wavelet correction filter (libstfinv)
*
* This file contains:
* - documentation of namespace stfinv
......@@ -53,28 +53,34 @@ $Id$
\subsection main_subsec_introduction Introduction
The purpose of this library is to provide methods for the derivation of
source-time-functions in approaches to full waveform inversion.
source wavelet correction filters
in approaches to full waveform inversion.
Given a set of recorded data and a set of synthetic data (typically,
but not necessarilly the impulse response of the subsurface) a source time
function is obtained due to some optimization citerion.
The synthetic waveforms are convolved with this wavelet and the convolved
but not necessarilly the impulse response of the subsurface) a source
wavelet correction filter
is obtained due to some optimization citerion.
The synthetic waveforms are convolved with this filter
wavelet and the convolved
synthetics as well as the wavelet itself are returned to the user.
The source time wavelet in this context not necessarily is the actual
The source wavelet correction filter
in this context not necessarily is the actual
force time history of the source used in the experiment or a similar
quantity of physical meaning.
The source time wavelet simply is the wavelet which minimizes the misfit
The source wavelet correction filter
simply is the wavelet which minimizes the misfit
between synthetic and recorded waveforms due to some misfit condition, if
the synthetics are concolved with this wavelet.
In particular this implies that the synthetics not necessarily must be the
In particular this implies that the synthetics not necessarily need be the
impulse response (Greens function) of the subsurface, they may simply be
synthetic waveform computed for some generic source wavelet (like a
synthetic waveforms computed for some generic source wavelet (like a
Ricker wavelet).
The derived source time function then have to be understood with respect
The derived source wavelet correction filter
then has to be understood with respect to
this generic wavelet.
The library provides different \ref engines to find an optimal source time
wavelet.
The library provides different \ref engines to find an optimal source
wavelet correction filter.
The basic steps of operation are:
-# Initialize an engine.
In this step pointers to arrays are passed to
......@@ -83,7 +89,8 @@ $Id$
data as well as the synthetics at the inidcated locations in memory.
-# Call the run()-function of the engine.
The engine takes the recorded and synthetic data currently found at
the memory arrays, calculates an optimzed wavelet and returns the
the memory arrays, calculates an optimzed correction filter
wavelet and returns the
wavelet together with the convolved synthetics by copying them to the
memory locations inidicated by the initializer of the engine.
This step is repeated after each computation of synthetic data.
......@@ -128,7 +135,8 @@ $Id$
\par Examples
- To select frequency domain least squares
(stfinv::STFEngineFDLeastSquares) and shift the returned source
time function by 0.4s and switch on verbose mode, pass the following
correction wavelet
by 0.4s and switch on verbose mode, pass the following
parameter string:
\verbatim fdlsq:tshift=0.4:verbose \endverbatim
- To select stfinv::STFEngineIdentity and to switch on debug level 4:
......@@ -153,8 +161,8 @@ $Id$
stfinv::STFBaseEngine.
Most of the framework can simply be copied.
The core function is the virtual function like
stfinv::STFEngineIdentity::exec() which actuall determines the new source
time function.
stfinv::STFEngineIdentity::exec() which actuall determines the source
wavelet correction filter.
For the implementation there are some \ref tools provided in the library.
Do not forget to provide a unique ID like stfinv::STFEngineIdentity::ID
......@@ -210,9 +218,10 @@ engine by calling ::initstfinvengine(). The engine will keep references to
the memory locations where time series samples are stored. You can update
the content of these locations as you like, e.g. by storing a new set of
synthetic seismograms therein. Upon each call to ::runstfinvengine() a new
source time function wavelet will be derived and stored at its place in
source wavelet correction filter
will be derived and stored at its place in
memory. At the same time the synthetic waveforms are convolved with the
source time function and stored at the memory location reserved for the
filter wavelet and stored at the memory location reserved for the
convolved synthetics. It is good style to call ::freestfinvengine() when
you have finished. This will remove the engine from memory. This call
should at least be issued when the pointers to the memory locations for
......@@ -263,7 +272,8 @@ for (usigned int i=0; i<nrec; ++i)
data.triples[i].header.sampling.dt=dt;
}
\endcode
Further prepare a reference to your workspace for the source time function:
Further prepare a reference to your workspace for the source
correction filter wavelet:
\code
struct CWaveform stf;
/* assign pointer to float */
......@@ -294,20 +304,23 @@ and
data.triples[i].synthetics
\endcode
refer to.
It will then calculate a source time function according to the selected
It will then calculate a source wavelet correction filter
according to the selected
strategy and subject to the parameters passed to the engine.
The time series referred to by
\code
data.triples[i].synthetics
\endcode
will be convolved
with this source time function and the resulting time series will be written
with this source correction filter wavelet
and the resulting time series will be written
to the workspace
\code
data.triples[i].convolvedsynthetics
\endcode
point to.
The source time function itself will be written to the workspace referred to
The source correction filter wavelet
itself will be written to the workspace referred to
by
\code
stf.series
......@@ -329,9 +342,9 @@ void initstfinvenginewithpairs(struct CTriples triples,
char* parameters);
\endcode
The argument \p pairs can be used to pass additional time series which will be
convolved with the source time function.
convolved with the source correction filter wavelet.
These time series however are not used in the process of finding the
appropriate source time function.
appropriate source wavelet correction filter.
Consider you like to pass \c npairs time series with \c nsamp samples each and
a sampling interval \c dt (note: \c nsamp and \c dt must be identical to those
......@@ -379,7 +392,8 @@ the engine will read the time series from the area addressed by
\code
pairs.pairs[i].synthetics
\endcode
will convolve this with the newly derived source time function. The resulting
will convolve this with the newly derived source correction filter wavelet.
The resulting
time series will be written to the workspace addressed by
\code
pairs.pairs[i].convolvedsynthetics
......
......@@ -4,7 +4,7 @@
# Project related configuration options
#---------------------------------------------------------------------------
DOXYFILE_ENCODING = UTF-8
PROJECT_NAME = "STFINV library: invert for optimal source time function"
PROJECT_NAME = "STFINV library: seek source wavelet correction filter"
PROJECT_NUMBER =
OUTPUT_DIRECTORY = <OUTPUTDIRECTORY>
CREATE_SUBDIRS = NO
......
......@@ -82,7 +82,7 @@ void initstfinvenginewithpairs(struct CTriples triples,
// convert parameter string
std::string cxxparameters(parameters);
// convert pointer to source time function array
// convert pointer to source correction filter array
stfinv::Waveform cxxstf;
cxxstf.sampling=stf.sampling;
aff::LinearShape shape(0, cxxstf.sampling.n-1, 0);
......
......@@ -89,7 +89,7 @@ struct CWaveformTriple {
* The size of the array is expected to be
* this->header::sampling::n.
* This will contain the synthetic data (this->synthetics) convolved with
* the obtained source time function as a result of a call to the library
* the obtained source correction filter as a result of a call to the library
* functions.
*/
Tvalue* convolvedsynthetics;
......@@ -120,11 +120,11 @@ struct CWaveformPair {
/*! \brief Time series of convolved synthetic data.
* This field actually is a pointer (C array) to the workspace where the
* user wishes to receive the samples of the time series of synthetic data
* as a result of convolution with the source time function.
* as a result of convolution with the source correction filter.
* The size of the array is expected to be
* this->header::sampling::n.
* This will contain the synthetic data (this->synthetics) convolved with
* the obtained source time function as a result of a call to the library
* the obtained source correction filter as a result of a call to the library
* functions.
*/
Tvalue* convolvedsynthetics;
......@@ -136,7 +136,7 @@ struct CWaveformPair {
*
* \ingroup cinterface
*
* This will be used to pass the source time function.
* This will be used to pass the source correction filter.
*/
struct CWaveform {
/*! \brief Temporal sampling.
......@@ -144,7 +144,8 @@ struct CWaveform {
struct CWaveformHeader sampling;
/*! \brief Time series of waveform.
* This field actually is a pointer (C array) to the workspace where the
* user wishes to receive the samples of the obtained source time function.
* user wishes to receive the samples of the obtained source correction
* filter.
* The size of the array is expected to be
* this->sampling::n.
*/
......@@ -179,7 +180,7 @@ struct CTriples {
* \ingroup cinterface
*
* This is used to pass data for a set of synthetic time series, which should
* be convolved with the new source time function on the fly.
* be convolved with the new source correction filter on the fly.
* A collection of time series consists of CPairs::n waveform pairs.
* For each waveform pair this struct holds a reference to a struct
* CWaveformPair which itself provides a reference to the users workspace for
......@@ -209,11 +210,11 @@ struct CPairs {
* workspace for recorded time series as well as synthetic time series.
* These will be used as input.
* As a third set a reference to a workspace for synthetic time series
* convolved with the source time function is expected.
* convolved with the source correction filter is expected.
* The latter will be used as output.
* \param stf
* The struct CWaveform presents a reference to the users work space for the
* source time function time series.
* source correction filter time series.
* It will be used to present the result of the processing to the user.
* \param parameters
* Parameters to select one of the engines as well as to control the engines
......@@ -236,22 +237,23 @@ void initstfinvengine(struct CTriples triples,
* workspace for recorded time series as well as synthetic time series.
* These will be used as input.
* As a third set a reference to a workspace for synthetic time series
* convolved with the source time function is expected.
* convolved with the source correction filter is expected.
* The latter will be used as output.
* \param stf
* The struct CWaveform presents a reference to the users work space for the
* source time function time series.
* source correction filter time series.
* It will be used to present the result of the processing to the user.
* \param pairs
* The struct CPairs presents a reference to the users work space for
* additional synthetic time series.
* These time series will not be used to determine the optimal source time
* function filter, but will be convolved with the obtained source time
* function on the fly.
* This is in useful in particular with forward modelling code which uses a
* These time series will not be used to determine the optimal source
* correction filter filter, but will be convolved with the obtained source
* time function on the fly.
* This is useful in particular with forward modelling code which uses a
* band limited source time function for the initial synthetics already.
* This source time function can be passed through this argument and will
* then be convolved with the optimized source time function, such that the
* then be convolved with the optimized source correction filter,
* such that the
* result of the convolution is appropriate to obtain synthetics which
* provide a reduced misift with respect to the data.
* \param parameters
......
......@@ -190,8 +190,8 @@ namespace stfinv {
os << "\n";
os << "Examples:\n";
os << "- To select Fourier domain least squares and shift\n"
<< " the returned source time function by 0.4s and switch on\n"
<< " verbose mode, pass the following parameter string:\n";
<< " the returned source correction filter wavelet by 0.4s and\n"
<< " switch on verbose mode, pass the following parameter string:\n";
os << " fdlsq:tshift=0.4:verbose\n";
os << "- To select the identity engine and to switch on debug level 4:\n";
os << " ident:DEBUG=4\n";
......
......@@ -65,11 +65,11 @@ namespace stfinv {
* the users workspace for recorded time series as well as synthetic
* time series. These will be used as input.
* As a third set a reference to a workspace for synthetic time series
* convolved with the source time function is expected.
* convolved with the source correction filter is expected.
* The latter will be used as output.
* \param stf
* The Waveform presents a reference to the users work space
* for the source time function time series.
* for the source correction filter time series.
* It will be used to present the result of the processing to the user.
* \param parameters
* Parameters to select one of the engines as well as to control the
......@@ -86,24 +86,24 @@ namespace stfinv {
* the users workspace for recorded time series as well as synthetic
* time series. These will be used as input.
* As a third set a reference to a workspace for synthetic time series
* convolved with the source time function is expected.
* convolved with the source correction filter is expected.
* The latter will be used as output.
* \param stf
* The Waveform presents a reference to the users work space
* for the source time function time series.
* for the source correction filter time series.
* It will be used to present the result of the processing to the user.
* \param pairs
* The vector of pairs presents a reference to the users work space for
* additional synthetic time series. These time series will not be
* used to determine the optimal source time function filter, but will
* be convolved with the obtained source time function on the fly.
* This is in useful in particular with forward modelling code which
* uses a band limited source time function for the initial synthetics
* used to determine the optimal source correction filter, but will
* be convolved with the obtained source correction filter on the fly.
* This is useful in particular with forward modelling code which
* uses a band limited source wavelet for the initial synthetics
* already. This source time function can be passed through this
* argument and will then be convolved with the optimized source time
* function, such that the result of the convolution is appropriate to
* obtain synthetics which provide a reduced misift with respect to
* the data.
* argument and will then be convolved with the optimized source
* correction filter, such that the result of the convolution is
* appropriate to obtain synthetics which provide a reduced misift
* with respect to the data.
* \param parameters
* Parameters to select one of the engines as well as to control the
* engines are passed in a character sequence.
......@@ -117,7 +117,7 @@ namespace stfinv {
~STFEngine();
//! \brief Return actual engine.
stfinv::STFBaseEngine& STFBaseEngine() { return (*Mengine); }
//! \brief Start engine and return source time function.
//! \brief Start engine and return source correction filter.
stfinv::Waveform run() { return(Mengine->run()); }
//! \brief List engines currently recognized
static void help(std::ostream& os=std::cout);
......
......@@ -107,7 +107,7 @@ namespace stfinv {
/*----------------------------------------------------------------------*/
/*! \brief A class to store a single waveform.
* This will be used to pass the source time function.
* This will be used to pass the source correction filter.
* \ingroup cxxinterface
*/
struct Waveform {
......@@ -140,7 +140,8 @@ namespace stfinv {
/*----------------------------------------------------------------------*/
/*! \brief Abstract base class for engines to derive source time functions
/*! \brief Abstract base class for engines to derive source correction
* filter
* \ingroup cxxinterface
*
* \par What STFBaseEngine does for you
......@@ -202,8 +203,8 @@ namespace stfinv {
* 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 time function but which are convolved with the new source time
* function on the fly.
* 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,
......@@ -217,7 +218,7 @@ namespace stfinv {
* \sa \ref main_sec_users
*/
//@{
//! \brief Start engine and return reference to source time function.
//! \brief Start engine and return reference to source correction filter.
stfinv::Waveform run()
{
this->exec();
......@@ -251,7 +252,7 @@ namespace stfinv {
/*! \name Data query functions
*/
//@{
//! \brief return source time function series
//! \brief return source correction filter series
Tseries stf() const
{ return (Mstf.series); }
//! \brief return recorded data at receiver \c i
......@@ -307,7 +308,7 @@ namespace stfinv {
// protected members are accessed directly from derived classes
//! \brief Waveform triples.
stfinv::Tvectoroftriples Mtriples;
//! \brief Source time function.
//! \brief source correction filter.
stfinv::Waveform Mstf;
//! \brief Waveform pairs.
stfinv::Tvectorofpairs Mpairs;
......
......@@ -198,7 +198,8 @@ namespace stfinv {
* It was renamed to fourier domain least squares engine in October 2011.
*
* This engine understands the recorded data as being the synthetic data
* being convoled with the STF (source time function) and having some noise
* being convoled with the STF (source correction filter)
* and having some noise
* added.
* The true impulse response of the subsurface could be obtained by
* deconvolution of the recorded data with the STF.
......
......@@ -123,8 +123,8 @@ namespace stfinv {
<< "fpad=f padding factor (default: 1.5)\n"
<< "fpow2 use power of two\n"
<< "fdiv=d use integer multiple of d\n"
<< "tshift=d delay source time function by \"d\" seconds\n"
<< " in order to expose acausal parts\n"
<< "tshift=d delay source correction filter wavelet by \"d\"\n"
<< " seconds in order to expose acausal parts\n"
<< "These options define the number of samples N used for the FFT.\n"
<< "This should be larger than the number of samples M in the\n"
<< "original series to avoid wrap-around. N=M*f at least. If fpow2\n"
......@@ -371,7 +371,7 @@ namespace stfinv {
void STFFourierDomainEngine::putoutput()
{
// scaling factor for source time function
// scaling factor for source correction filter
double scalingstf=Mfftengineoutput.scale_series(this->dt());
// scaling factor for convolved synthetics
double scalingcs=Mfftengineoutput.scale_spectrum(this->dt())
......
......@@ -58,7 +58,7 @@ namespace stfinv {
* It provides the FFT from input signals to the workspace through a member
* functions as well as the convolution of the synthetic data with a given
* source wavelet Fourier transform and a subsequent FFT to time domain for
* the convolved synthetics as well as the source time function separately.
* the convolved synthetics as well as the source correction filter separately.
*
* \par What STFFourierDomainEngine does for you
* All derived classes call STFFourierDomainEngine::fftinput prior to
......@@ -71,11 +71,11 @@ namespace stfinv {
* \par
* When processing has finished, the derived classes should call
* STFFourierDomainEngine::fftoutput.
* This function convolves the synthetic data with the source time
* function (STFFourierDomainEngine::convolve).
* Then it applies a time shift to the source time function if requested
* This function convolves the synthetic data with the source correction
* filter (STFFourierDomainEngine::convolve).
* Then it applies a time shift to the source correction filter if requested
* (STFFourierDomainEngine::stfshift).
* The convolved synthetics as well as the source time function then are
* The convolved synthetics as well as the source correction filter then are
* transformed to time domain and written to the users workspace
* ((STFFourierDomainEngine::putoutput).
*
......@@ -210,7 +210,7 @@ namespace stfinv {
* </TR>
* <TR>
* <TD> N </TD>
* <TD> source time function </TD>
* <TD> source correction filter </TD>
* </TR>
* <TR>
* <TD> N+1 ... N+M </TD>
......
......@@ -57,11 +57,11 @@ namespace stfinv {
* recorded data and synthetics.
* In cases where it is difficult to minimize the misfit, e.g. when the wave
* propagation properties of the synthetics differ from those of the
* recorded data, the least squares misfit optimum might be a source time
* function equal zero.
* The current approach (stfinv::STFEngineNormalize) seeks a source time
* function such that the average energy as well as the average phase of
* data and synthetics equal.
* recorded data, the least squares misfit optimum might be a
* source correction filter equal zero.
* The current approach (stfinv::STFEngineNormalize) seeks a source
* correction filter such that the average energy as well as the average
* phase of data and synthetics equal.
* This is what you usually want in a early stage of inversion.
*
* \par Concept of this algorithm
......@@ -70,7 +70,7 @@ namespace stfinv {
* \f$f_l\f$ and receiver \f$k\f$ at offset \f$r_k\f$ and
* - \f$s_{lk}\f$ is the Fourier coefficient of the corresponding
* synthetics.
* Then we seek a source time function with Fourier coefficients
* Then we seek a source correction filter with Fourier coefficients
* \f$q_l\f$ such that
* \f[
* \sum\limits_{k}\left|d_{lk}\right|^2
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment