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

added some frontpage documentation

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.

SVN Path:     http://gpitrsvn.gpi.uni-karlsruhe.de/repos/TFSoftware/trunk
SVN Revision: 3923
SVN UUID:     67feda4a-a26e-11df-9d6e-31afc202ad0c
parent 200488b3
......@@ -36,54 +36,131 @@ namespace stfinv {
$Id$
Contents of this page:
- \ref sec_concept
\date 05.05.2011
- \ref main_sec_users
- \ref main_subsec_cusers
- \ref main_subsec_cxxusers
- \ref main_sec_implementers
\section main_sec_users The libraray libstfinv for users
The purpose of this library is to provide methods for the derivation of
source-time-functions 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
synthetics as well as the wavelet itself are returned to the user.
The source time wavelet 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
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
impulse response (Greens function) of the subsurface, they may simply be
synthetic waveform computed for some generic source wavelet (like a
Ricker wavelet).
The derived source time function then have to be understood with respect
this generic wavelet.
The library provides different \ref engines to find an optimal source time
wavelet.
The basic steps of operation are:
-# Initialize an engine.
In this step pointers to arrays are passed to
the engine together with some header information.
The engines memorizes these pointers and expects to find the recorded
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
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.
-# Remove the engine once you terminate the iteration of inversion.
\subsection main_subsec_cusers The C application programming interface (API)
The library provides a \ref cinterface.
\subsection main_subsec_cxxusers The C++ application programming interface (API)
The library provides a \ref cxxinterface.
\section main_sec_implementers The libraray libstfinv for implementers
Implementers of new engines should copy files like stfinvidentity.h and
stfinvidentity.cc and implement a new class which inherits from
stfinv::STFBaseEngine.
Most of the framework can simply be copied.
The core function is the virtual function like
stfinv::STFEngineIdentity::run() which actuall determines the new source
time function.
For the implementation there are some \ref tools provided in the library.
Do not forget to provide an unique ID like stfinv::STFEngineIdentity::ID
and a short description like in stfinv::STFEngineIdentity::description.
Further an online help text like produced by
stfinv::STFEngineIdentity::classhelp() are recommended.
After having successfully implemented the engine, it must be made
available through
stfinv::STFEngine::STFEngine().
Online help is made available through stfinv::STFEngine::help() and
stfinv::help().
\date 08.05.2011
*/
/*======================================================================*/
/*! \brief C interface to libstfinv
*
* \defgroup cinterface C interface (API) to libstfinv
*
* When using libstfinv from a C program, the first step is to initialize the
* 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
* memory. At the same time the synthetic waveforms are convolved with the
* source time function 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
* time series samples as passed to ::initstfinvengine() become invalid.
\defgroup cinterface C interface (API) to libstfinv
When using libstfinv from a C program, the first step is to initialize the
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
memory. At the same time the synthetic waveforms are convolved with the
source time function 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
time series samples as passed to ::initstfinvengine() become invalid.
\date 05.05.2011
*/
/*======================================================================*/
/*! \brief C++ interface to libstfinv
*
* \defgroup cxxinterface C++ interface (API) to libstfinv
*
\defgroup cxxinterface C++ interface (API) to libstfinv
\date 05.05.2011
*/
/*======================================================================*/
/*! \brief Engines implemented in libstfinv
*
* \defgroup engines libstfinv engines
*
\defgroup engines Engines
\date 05.05.2011
*/
/*======================================================================*/
/*! \brief Tools and utilities used by the libstfinv engines
*
* \defgroup tools libstfinv internal tools and utilities
*
\defgroup tools Internal tools and utilities
\date 05.05.2011
*/
// ----- END OF README -----
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