The library 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::exec() which actuall determines the source wavelet correction filter. For the implementation there are some tools provided in the library.

Do not forget to provide a 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().

See the stfinv::STFBaseEngine, where we explain how the initialization takes place.

See Design considerations for details on the engine design.

See Introduction for a general introduction and description of the libraries workflow.

The C application programming interface (API)

The library provides a C interface (API) to libstfinv. Examples for using the C interface (API) to libstfinv are given in the section Detailed Description of the documentation for the C interface (API) to libstfinv.

The C++ application programming interface (API)

The library provides a C++ interface (API) to libstfinv. Examples for using the C++ interface (API) to libstfinv are given in the section Detailed Description of the documentation for the C++ interface (API) to libstfinv.

Design considerations

Initialization of classes

It would have been nice to implement the classes in a way that default parameters are collected automatically and that the constructors care about parameter key values not matching a default parameter. Without tests for matching key values typos by the user may remain unnoticed.

Default values either must be provided in a static data structure or must be collected in a top down manner beginning at the child class proceeding to the parents. Collection of default parameters must be finished before passing the actual parameters to the parameter map stfinv::STFBaseEngine::Mparamap. The sequence in which the constructors are called is the other way round. Constructor processing naturally starts at the base class and proceeds in direction of the children. At the same time a base class constructor is not able to call a virtual function of the child, since the child not actually is constructed at this time.

Implementing a check for default parameter matches cannot easily be implemented within the constructors. A second sequence of initializing member function would be necessary. The constructor of the derived class would have to initiate this process thus ultimately terminating the chain of inheritance.

Since all other initialization takes place in the order starting at the base class, I do not check the key values and prefer the simple and straight forward way of implementation.

The handling of stfinv::STFBaseEngine::Mparamap is entirely encapsulated in the base class. For this reason it should be possible to implement parameter keyword checks in the future is desired with relatively small effort.

Date: 10.05.2011

Documentation of the library

Addressees of documentation

End-users: These are end-users of the software. They are not concerned with the libraries API (application programming interface). They just apply a software which uses libstfinv to seismic data. End-users require information on how to select one of the provided engines and how to control these engines by parameter values.

Users: Users of the library use libstfinv within their own software project. They required detailed information regarding the API and its parameters. Questions to be addressed are: How are waveform data transferred to and from the library? How can user selected parameters be passed to the library?

Implementers: They aim to implement new features in libstfinv or to fix bugs. Such new features could be a new engine or just new functionality for an existing engine. Information required concerns the general design of the library, how classes interact and derive from each other. Implementers must be pointed to locations, where base classes must receive new lines to address a newly implemented class.

Locations of documentation

Source code: Within the C++ source code files all software modules and in particular their implementation are described. Apart from the actual classes, functions, and parameters this comprises also the theory of operation and mathematics of the implemented approaches. These more fundamental information typically if given in the "Detailed Description" sections of the class documentation.

doxygen text files: Files matching name pattern doxygen*.txt contain documentation text with format commands appropriate for doxygen. They are processed in the creation of the html documentation of libstfinv. These files contain general considerations for end-users, library users and implementers.

usage text files: Files matching name pattern *usage.txt in subdirectory usage contain usage documentation addressing end-users. End-users are not concerned with programming and library API. They use software, which is linked against libstfinv and apply those programs to their time series files. This documentation should contain all relevant information on how to select an engine and how to control the actual processing by passing parameters to the engine. Contents of these files will be processed to C++ source code and will be provided through help-functions of the software modules.

: summary_usage.txt files provide a short summary of the implemented approach and a summary of available parameters.

: description_usage.txt files provide a detailed description of theory of operation and detailed information regarding control parameters.

Usage text files shall be output in two different ways:

The summary for all available engines is output together with a summary for the overall library. The summary for engine bases like stfinv::STFFourierDomainEngine is output exactly once and after the list of operational engines. This is controlled by the API. It is implemented in stfinv::STFEngine::help() and called by stfinv::help().
The detailed description for one selected engine is output together with detailed description for the overall library. This is delegated by the API to static member functions of operational engine classes. stfinv::STFEngine::usage(const std::string& id, std::ostream& os=std::cout) prints the detailed description of the general part of the library and then calls the static member function usage of the engine selected through string id. The usage function of the engine class prints its detailed usage information and, if appropriate, calls the usage function of the base class. Function stfinv::usage() is provided in the C interface (API) to libstfinv and calls stfinv::STFEngine::usage.

LaTeX files: In subdirectory doc a set of LaTeX files is created. These files may contain extended end-user documentation including relevant mathematics.

Date: 4.10.2015