C interface (API) to libstfinv

C interface to libstfinv. More...

Files
file	stfinv.h
	C API to library (prototypes)

Classes
struct	CPairs
	Array of waveform pairs.This is used to pass data for a set of synthetic time series, which should 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 time series. More...
struct	CTripleHeader
	Structure to hold header information for a triple of waveforms.Each triple of waveforms reference by e.g. struct CWaveformTriple are associated to a receiver. The coordinates of the receiver as well as of the associated shot location are stored here. Further temporal sampling is defined by this->sampling. More...
struct	CTriples
	Array of waveform triples.This is used to pass data for a complete profile. A profile consists of CTriples::n receivers. For each receiver this struct holds a reference to a struct CWaveformTriple which itself provides a reference to the users workspace for time series. More...
struct	CWaveform
	A struct to store a single waveform. More...
struct	CWaveformHeader
	Temporal sampling for time series data. More...
struct	CWaveformPair
	A struct to store the time series for a pair of waveforms.This struct provides references to the users workspace, where the time series for on receiver are stored. More...
struct	CWaveformTriple
	A struct to store the time series for a waveform triple.This struct provides references to the users workspace, where the time series for on receiver are stored. More...

Typedefs
typedef float	Tvalue
	Value type of samples.All references to time series samples in user workspace are based on this type. More...

Functions
void	freestfinvengine ()
	Free the engine. More...
void	initstfinvengine (struct CTriples triples, struct CWaveform stf, char *parameters)
	Initialize the engine. More...
void	initstfinvenginewithpairs (struct CTriples triples, struct CWaveform stf, struct CPairs pairs, char *parameters)
	Initialize the engine and pass additional time series to be convolved on the fly. More...
void	printengines ()
	List procedures (engines) on stdout. More...
void	printhelp ()
	Print usage summary to stdout. More...
void	printusage (char *id)
	Print detailed description for engine "id" to stdout. More...
void	runstfinvengine ()
	Run the engine. More...

Detailed Description

C interface to libstfinv.

All data structures and function prototypes are presented in stfinv.h

Overview

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 wavelet correction filter will be derived and stored at its place in memory. At the same time the synthetic waveforms are convolved with 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 time series samples as passed to initstfinvengine() become invalid.

Code fragments

All expressions [...] in the code fragments below have to be replaced with proper C expression appropriate for your program.

Consider you like to use this interface in a C program. You have data for nrec receivers each with nsamp samples and dt sampling interval:

usigned int nrec = [...];
usigned int nsamp = [...];
float dt = [...];

Then you have to initialize a reference to your workspace:

struct CTriples data;
data.n=nrec;
data.triples=(struct CWaveformTriple *)malloc(nrec*sizeof(struct CWaveformTriple));
if (data.triples == NULL) { abort(); }

You then have to fill the waveform triple structures with appropriate header information and pointers to your data arrays:

for (usigned int i=0; i<nrec; ++i)
{
  /*
  set pointers to your data workspace; each [...] expression is of type
  float* (i.e. pointer to float)
  */
  data.triples[i].data=[...];
  data.triples[i].synthetics=[...];
  data.triples[i].convolvedsynthetics=[...];
  /*
  add header data
  */
  data.triples[i].header.sx=[...];
  data.triples[i].header.sy=[...];
  data.triples[i].header.sz=[...];
  data.triples[i].header.rx=[...];
  data.triples[i].header.ry=[...];
  data.triples[i].header.rz=[...];
  data.triples[i].header.sampling.n=nsamp;
  data.triples[i].header.sampling.dt=dt;
}

Further prepare a reference to your workspace for the source correction filter wavelet:

struct CWaveform stf;
/* assign pointer to float */
stf.series = [...];
stf.sampling.n=nsamp;
stf.sampling.dt=dt;

The you require a parameter string. For example:

char para[]="fbd:tshift=0.4";

Having prepared all these items, you can initialize the stf engine:

initstfinvengine(data, stf, para);

After having initialized the engine, you can call the engine repeatedly. Upon each call

runstfinvengine();

the engine will read the time series data from the workspace

data.triples[i].data 

and

data.triples[i].synthetics

refer to. 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

data.triples[i].synthetics

will be convolved with this source correction filter wavelet and the resulting time series will be written to the workspace

data.triples[i].convolvedsynthetics

point to. The source correction filter wavelet itself will be written to the workspace referred to by

stf.series

Do not forget to free memory once you do not longer require the stf engine:

freestfinvengine();
free(data.triples);

Using waveform pairs to pass additional time series

The C API offers a second init function:

void initstfinvenginewithpairs(struct CTriples triples,
                               struct CWaveform stf,
                               struct CPairs pairs,
                               char* parameters);

The argument pairs can be used to pass additional time series which will be convolved with the source correction filter wavelet. These time series however are not used in the process of finding the appropriate source wavelet correction filter.

Consider you like to pass npairs time series with nsamp samples each and a sampling interval dt (note: nsamp and dt must be identical to those used for the other time series passed to libstfinv). nsamp and dt are already set. You have to adjust

usigned int npairs = [...];

Then you have to initialize a reference to your workspace:

struct CPairs pairs;
pairs.n=npairs;
pairs.pairs=(struct CWaveformPair *)malloc(npairs*sizeof(struct CWaveformPair));
if (pairs.pairs == NULL) { abort(); }

You then have to fill the waveform pair structures with appropriate header information and pointers to your data arrays:

for (usigned int i=0; i<npairs; ++i)
{
  /*
  set pointers to your data workspace; each [...] expression is of type
  float* (i.e. pointer to float)
  */
  pairs.pairs[i].synthetics=[...];
  pairs.pairs[i].convolvedsynthetics=[...];
  /*
  add header data
  */
  pairs.pairs[i].sampling.n=nsamp;
  pairs.pairs[i].sampling.dt=dt;
}

Having prepared this and all other items, you can initialize the stf engine:

initstfinvenginewithpairs(data, stf, pairs, para);

Additionally to what is dedscribed above, upon each call to

runstfinvengine();

the engine will read the time series from the area addressed by

pairs.pairs[i].synthetics 

will convolve this with the newly derived source correction filter wavelet. The resulting time series will be written to the workspace addressed by

pairs.pairs[i].convolvedsynthetics

Note

Not every engine supports additional wavefrom pairs. See stfinv::STFEngine::initialize() if in doubt.

Date

05.10.2011