Skip to content

GitLab

Commit 4e3c31ce authored by thomas.forbriger's avatar thomas.forbriger
Browse files

[MERGE] (master|stf_issue12): Merge branch 'stf_issue12' 

After implementation of full usage information for end-users and ouput of
usage texts in soutifu, modifications are merged into master.
parents 604a0fbd bfef3205
Hide whitespace changes
Inline Side-by-side
src/libs/libstfinv/.gitignore
View file @ 4e3c31ce
......@@ -7,6 +7,8 @@
#
# source code documentation
*.doc
*usage.cc
*usage.h
#
# binary executables of programs in test directory
tooltest
......
src/libs/libstfinv/Makefile
View file @ 4e3c31ce
......@@ -46,6 +46,33 @@ $(LOCLIBDIR)/%: install-include %
/bin/mv -fv $(word 2,$^) $(LOCLIBDIR)
# ============================================================================
# select groups of files
# they are used for editing and to create object file lists and dependencies
# whereever we find a README, we will use it
README=$(filter-out %.bak,$(shell find . -name README\*))
# the frame of doxygen documentation is palced in text files
DOXYTXT=$(shell find . -name doxygen\*.txt)
# C++ and C source code
SOURCEFILES=$(filter-out %usage.h, $(filter-out %usage.cc, \
$(wildcard *.h *.cc *.c tests/*.cc tests/*.c tests/*.inp) \
$(wildcard test*/src/*.c) \
$(wildcard test*/src/*.h) \
$(wildcard test*/src/LEGAL*h)))
# LaTeX formatted documentation
DOCFILES=$(wildcard doc/*.tex doc/Makefile)
# end-user usage information
USAGEFILES=$(wildcard usage/*usage.txt)
# editional files to be edited
EDITFILES=Makefile $(README) \
$(DOXYTXT) $(DOCFILES) $(USAGEFILES) \
$(SOURCEFILES) \
$(wildcard *.cfg) \
$(wildcard test*/src/Makefile) \
COPYING
# ============================================================================
# check for settings expected in the environment
# ----------------------------------------------
#
CHECKVAR=$(if $($(1)),,$(error ERROR: missing variable $(1)))
CHECKVARS=$(foreach var,$(1),$(call CHECKVAR,$(var)))
......@@ -54,9 +81,14 @@ CHECKVARS=$(foreach var,$(1),$(call CHECKVAR,$(var)))
$(call CHECKVARS,LOCINCLUDEDIR LOCLIBDIR LOCBINDIR)
$(call CHECKVARS,TF_BROWSER TF_WWWBASEDIR)
LIBHEADERS=$(filter-out none,$(wildcard *.h))
# ======================================================================
#
LIBHEADERS=$(filter-out none,$(wildcard *.h)) \
$(patsubst usage/%.txt,%.h,$(USAGEFILES))
LIBCCSRC=$(filter-out none,$(wildcard *.cc)) \
$(patsubst usage/%.txt,%.cc,$(USAGEFILES))
LIBCCSRC=$(filter-out none,$(wildcard *.cc))
LIBCSRC=$(filter-out none,$(wildcard *.c))
TESTHEADERS=$(wildcard tests/*.h)
......@@ -73,43 +105,33 @@ LIBINSTALLPATH=$(LOCLIBDIR)
# name of installed (exported) header files
INSTHEADER=$(addprefix $(INCINSTALLPATH)/,$(notdir $(LIBHEADERS)))
# whereever we find a README, we will use it
README=$(shell find . -name README)
# the frame of doxygen documentation is palced in text files
DOXYTXT=$(shell find . -name doxygen\*.txt)
#
# general part
# ------------
#
# compiler flags
# --------------
FLAGS=
FLAGS+=-fPIC $(MYFLAGS)
CXXFLAGS+=-Wall $(FLAGS)
LDFLAGS+=-L$(LOCLIBDIR)
CPPFLAGS+=-I$(LOCINCLUDEDIR) $(FLAGS)
SOURCEFILES=$(wildcard *.h *.cc *.c tests/*.cc tests/*.c tests/*.inp) \
$(wildcard test*/src/*.c) \
$(wildcard test*/src/*.h) \
$(wildcard test*/src/LEGAL*h)
EDITFILES=Makefile $(README) \
$(DOXYTXT) \
$(SOURCEFILES) \
$(wildcard *.cfg) \
test_libstfinv/README \
$(wildcard test*/src/Makefile) \
COPYING
#
# source code editing and directory clean-up
# ------------------------------------------
flist: $(EDITFILES) $(TF_EDIT)
echo $(filter-out $(SOURCEFILES),$(EDITFILES)) \
echo $(filter-out $(DOCFILES) $(SOURCEFILES) \
$(USAGEFILES),$(EDITFILES)) \
| tr ' ' '\n' | sort > $@
echo '----' >> $@
echo $(filter-out test%,$(SOURCEFILES)) | tr ' ' '\n' | sort >> $@
echo '----' >> $@
echo $(USAGEFILES) | tr ' ' '\n' | sort >> $@
echo '----' >> $@
echo $(filter test%,$(SOURCEFILES)) | tr ' ' '\n' | sort >> $@
echo '----' >> $@
echo $(DOCFILES) | tr ' ' '\n' | sort >> $@
echo '----' >> $@
echo $(TF_EDIT) | tr ' ' '\n' | sort >> $@
.PHONY: edit
......@@ -122,6 +144,8 @@ clean: ;
-find . -name \*.d | xargs --no-run-if-empty /bin/rm -v
-find . -name \*.hd | xargs --no-run-if-empty /bin/rm -v
-/bin/rm -vf flist *.a *.so *.xxx $(TESTCBIN) $(TESTCCBIN)
-/bin/rm -fv $(patsubst %.txt,%.h,$(USAGEFILES))
-/bin/rm -fv $(patsubst %.txt,%.cc,$(USAGEFILES))
#======================================================================
# pattern rules
......@@ -174,6 +198,36 @@ reinstall:
$(MAKE) clean-include
$(MAKE) install
# ======================================================================
# source code generators
# ======================
#
# description and online texts
# ----------------------------
# The following rules convert ordinary ASCII text files into C++ source code,
# providing functions to output usage information (online help)
#
# Such text files use names with the pattern *usage.txt
# Automatically generated source code is excluded from editing and versioning
#
%usage.cc %usage.h: usage/%usage.txt
echo "// DO NOT EDIT: this file is automatically derived from $<" \
> $(patsubst usage/%.txt,%.h,$<)
echo "extern char $(patsubst usage/%.txt,%,$<)[];" \
>> $(patsubst usage/%.txt,%.h,$<)
echo "// DO NOT EDIT: this file is automatically derived from $<" \
> $(patsubst usage/%.txt,%.cc,$<)
echo "#include \"$(patsubst usage/%.txt,%.h,$<)\"" \
>> $(patsubst usage/%.txt,%.cc,$<)
echo "char $(patsubst usage/%.txt,%,$<)[]=" \
>> $(patsubst usage/%.txt,%.cc,$<)
echo "{" >> $(patsubst usage/%.txt,%.cc,$<)
cat $< | egrep -v '^#' | sed -e 's/\\/\\\\/g' | sed -e 's/"/\\"/g' \
| sed -e 's/$$/\\n"/' | sed -e 's/^/ "/'\
>> $(patsubst usage/%.txt,%.cc,$<)
echo "};" >> $(patsubst usage/%.txt,%.cc,$<)
#======================================================================
# documentation part
# ------------------
......@@ -201,15 +255,9 @@ DOXYWWWPATH=$(TF_WWWBASEDIR)/libstfinv
doxyclean: ;/bin/rm -rfv $(DOXYWWWPATH) doxydoc.xxx
onlinehelp.xxx: onlinehelp
echo '/*! \page page_help Online help texts' > $@
echo '\verbatim' >> $@
./$< -help 2>&1 >> $@ 2>&1
echo '\endverbatim' >> $@
echo '*/' >> $@
DOXYSRC=$(DOXYTXT) $(LIBCCSRC) $(LIBCSRC) $(LIBHEADERS) $(TESTCCSRC) $(TESTCSRC) \
onlinehelp.xxx Makefile
DOXYSRC=$(DOXYTXT) $(LIBCCSRC) $(LIBCSRC) $(LIBHEADERS)\
$(TESTCCSRC) $(TESTCSRC) \
Makefile
PWD=$(shell env pwd)
# create doxygen intermediate configuration
......@@ -229,35 +277,6 @@ doxydoc: $(DOXYWWWPATH)/html/index.html
doxyview: $(DOXYWWWPATH)/html/index.html
$(TF_BROWSER) file:$< &
#======================================================================
# create package
# --------------
# is delegated to Makefile.packages
ifdef TF_MAKEPKG
.PHONY: package
package: $(TF_MAKEPKG)
$(MAKE) -f $< \
PACKAGE=libstfinv \
PACKAGEEXPORT="trunk/src/libs/libstfinv:src" \
PACKAGETARGETS="src:install: src:doc:-i" \
PACKAGELIBS="-"
.PHONY: srcpackage
srcpackage: $(TF_MAKEPKG)
$(MAKE) -f $< \
PACKAGE=libstfinv \
PACKAGESRCONLY=yes \
PACKAGEEXPORT="trunk/src/libs/libstfinv:src" \
PACKAGETARGETS="src:all:" \
PACKAGELIBS="-"
.PHONY: fullpackage
fullpackage: $(TF_MAKEPKG)
$(MAKE) -f $< \
PACKAGE=libstfinvwithlibs \
PACKAGEEXPORT="trunk/src/libs/libstfinv:src" \
PACKAGETARGETS="src:install: src:doc:-i" \
PACKAGELIBS="libaff libfourier"
endif
#======================================================================
# test code
# ---------
......
src/libs/libstfinv/README
View file @ 4e3c31ce
......@@ -3,23 +3,97 @@ this is <README>
STFINV -- library for determination of source wavelet correction filter
============================================================================
For compilation instructions see README.1st in the root directory of the tar-ball or
http://gpitrsvn.gpi.uni-karlsruhe.de:8000/TFSoftware/wiki/docs/installation
The purpose of this library is to provide methods for the derivation of
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
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.
Purpose
-------
Create and apply a source wavelet correction filter for full-waveform
inversion of field data.
Description
-----------
The purpose of this library (libstfinv) is to provide methods for the
derivation of 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 expected impulse response of the
subsurface) a source wavelet correction filter is obtained by application of a
user-selectable 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 effective time history of the seismic source used in field recordings is
not well known in most cases. This applies in particular to transient sources
(like explosives or hammer blows). The so-called 'source-time-function' might
even vary from shot to shot. For this reason it is not possible to use an
appropriate source-time-function in the initial simulation of synthetic data
in an approach of full-waveform inversion. However, after synthetic data have
been calculated using a generic source-time-function, a correction filter can
be constructed such that an improved source-time-function will reduce the
misfit to the recorded data.
The software library libstfinv provides several constrained and unconstrained
approaches to finding an optimized source-wavelet correction filter. It is
flexible and capable of being extended with further approaches in the future.
The program soutifu supports application directly to seismic time series data
files.
Software library: libstfinv
---------------------------
The library libstfinv provides a C++ API (application programming interface)
as well as a C API to the user of the library. A Fortran API is not yet
implemented but could be constructed on top of the C API without effort. The
library provides several approaches (procedures) to finding an optimized
source wavelet correction filter. Each of the procedures is addressed through
the same API, such that programs using the library could immediately benefit
from a new approach after its implementation and without need to modify
consumer programs. The different procedures are encapsulated in so-called
'engines'. The procedures are fully controllable by the end-user through
configuration string sequences which are passed to the library.
Stand-alone binary executable: soutifu
--------------------------------------
A stand-alone binary executable soutifu is provided as well, which makes use
of this library. It can be applied directly to seismic time series data files
and provides access to all engines and supports a variety of data file
formats.
soutifu is provided in directory src/ts/wf within Seitosh.
Documentation
=============
doxygen source code documentation
---------------------------------
Detailed documentation of concept and implementation is provided in the source
code. doxygen can be used to create appropriate html files. See target
doxydoc in the Makefile. The libraries API is described there.
Introductory texts are provided in doxygen.txt and are used in the doxygen
documentation.
User documentation
------------------
The theory behind the Fourier domain least squares engine is outlined by
Lisa Groos (2013, Appendix F, page 146). She also describes a way to find an
approrpiate water level by application of the L-curve criterion (Groos, 2013,
Appendix G, page 148).
Fragments of a user documentation in LaTeX are propared in subdirectory doc.
Online user documentation to be output by the software itself is provided in
*usage.txt files.
A short descrpition of the library and the accompanying program soutifu is
provided on the OpenTOAST web-page:
http://www.opentoast.de/Data_analysis_code_soutifu_and_libstfinv.php
Lisa Groos. 2013. 2D full waveform inversion of shallow seismic Rayleigh waves.
Dissertation, Karlsruher Institut für Technologie.
http://nbn-resolving.org/urn:nbn:de:swb:90-373206
Installation
------------
environment variables:
============
See README.md and INSTALL.md in the root directory of the repository for
general installation instructions.
environment variables:
LOCINCLUDEDIR Defines the path where header files will be copied for
usage in your own projects. You will pass this path to
the precompiler with the -I option.
......@@ -37,8 +111,4 @@ This library requires code from libaff and libfourierxx.
Am external dependency is fftw3
The testprogram requires libtfxx in addition.
Detailed documentation is provided through doxygen source code. See target
doxydoc in the Makefile.
----- END OF README -----
src/libs/libstfinv/README.files 0 → 100644
View file @ 4e3c31ce
this is <README.files>
============================================================================
description of source files presented in src/libs/libstfinv
-----------------------------------------------------------
Source code and usage texts
===========================
Engine base classes
-------------------
Abstract base class for engines to derive source correction filter
------------------------------------------------------------------
class stfinv::STFBaseEngine
stfinvbase.cc
stfinvbase.h
Source code also contains waveform containers.
Handle-class to access any engine in the library (C++ API)
----------------------------------------------------------
class stfinv::STFEngine
stfinvany.cc
stfinvany.h
Base class for all engines which operate in the Fourier domain
--------------------------------------------------------------
class stfinv::STFFourierDomainEngine
stfinvfourier.cc
stfinvfourier.h
Engines
-------
Fourier domain least squares engine
-----------------------------------
class stfinv::STFEngineFDLeastSquares
stfinvfdleastsquares.cc
stfinvfdleastsquares.h
Engine to find a finite, causal source time-history in time domain
------------------------------------------------------------------
class stfinv::STFEngineFiniteCausal
stfinvfinitecausal.cc
stfinvfinitecausal.h
Engine to provide a fixed wavelet
---------------------------------
class stfinv::STFEngineFixedWavelet
stfinvfixedstf.cc
stfinvfixedstf.h
Engine to apply a scalar factor
-------------------------------
class stfinv::STFEngineIdentity
stfinvidentity.cc
stfinvidentity.h
Normalization engine
--------------------
class stfinv::STFEngineNormalize
stfinvnormalize.cc
stfinvnormalize.h
C API to library
----------------
stfinv.cc
stfinv.h
Internal functions
------------------
fouriertools.cc
fouriertools.h
parameterhandler.cc
parameterhandler.h
tools.cc
tools.h
waveformheader.h
Debugging and error handling
----------------------------
debug.h
error.cc
error.h
C API test programs
-------------------
test_libstfinv/
test_libstfinv_withpairs/
Programs to test internal components of the library
---------------------------------------------------
tests/
Documentation
=============
doc/
doxydoc.cfg
doxygen.txt
doxygen_end_users.txt
doxygen_implementers.txt
doxygen_library_users.txt
end-user usage instructions
---------------------------
summary: more or less just a short list of options or description of purpose
description: a detailed description of theory of operation and all available
parameters; possibly together with examples
description of overall library:
usage/stfinv_summary_usage.txt
usage/stfinv_description_usage.txt
description of prodecure selection and configuration:
usage/stfinvany_description_usage.txt
usage/stfinvany_summary_usage.txt
description of options available for all procedures:
usage/stfinvbase_description_usage.txt
usage/stfinvbase_summary_usage.txt
description of Fourier domain least squares procedure:
usage/stfinvfdleastsquares_description_usage.txt
usage/stfinvfdleastsquares_summary_usage.txt
description of procedure for finite causal filter:
usage/stfinvfinitecausal_description_usage.txt
usage/stfinvfinitecausal_summary_usage.txt
description of procedure for fixed filter:
usage/stfinvfixedstf_description_usage.txt
usage/stfinvfixedstf_summary_usage.txt
description of common options for procedures in the Fourier domain:
usage/stfinvfourier_description_usage.txt
usage/stfinvfourier_summary_usage.txt
description of scaling procedure:
usage/stfinvidentity_description_usage.txt
usage/stfinvidentity_summary_usage.txt
description of normalization procedure:
usage/stfinvnormalize_description_usage.txt
usage/stfinvnormalize_summary_usage.txt
----- END OF README.files -----
src/libs/libstfinv/README.status 0 → 100644
View file @ 4e3c31ce
this is <README.status>
============================================================================
status of the library
=====================
General library
---------------
Both, C++ and C API are implemented and operational.
Currently available engines:
ident: identity: just apply a scalar factor
fix: use fixed wavelet as read from file
fdlsq: least squares in the frequency domain
Fourier domain least squares engine (fdlsq)
-------------------------------------------
class stfinv::STFEngineFDLeastSquares
Operates in the Fourier domain.
Status: Implemented and fully operational.
Engine to find a finite, causal source time-history in time domain
------------------------------------------------------------------
class stfinv::STFEngineFiniteCausal
Status: Not yet implemented
Engine to provide a fixed wavelet (fix)
---------------------------------------
class stfinv::STFEngineFixedWavelet
Status: Not yet implemented
Engine to apply a scalar factor (ident)
---------------------------------------
class stfinv::STFEngineIdentity
Status: Implemented and fully operational.
Normalization engine
--------------------
class stfinv::STFEngineNormalize
Operates in the Fourier domain.
Status: Implemented, not yet tested
----- END OF README.status -----
src/libs/libstfinv/doc/stfinv_base.tex 0 → 100644
View file @ 4e3c31ce
% this is <stfinv_base.tex>
% ----------------------------------------------------------------------------
% $Id: $
%
% Copyright (c) 2014 by Thomas Forbriger (BFO Schiltach)
%
% documentation of base class features
%
% REVISIONS and CHANGES
% 24/02/2014 V1.0 Thomas Forbriger
%
% ============================================================================
%
% ----- END OF stfinv_base.tex -----
src/libs/libstfinv/doc/stfinv_fdbase.tex 0 → 100644
View file @ 4e3c31ce
% this is <stfinv_fdbase.tex>
% ----------------------------------------------------------------------------
% $Id: $
%
% Copyright (c) 2014 by Thomas Forbriger (BFO Schiltach)
%
% documentation of Fourier-domain class features
%
% REVISIONS and CHANGES
% 24/02/2014 V1.0 Thomas Forbriger
%
% ============================================================================
%
% ----- END OF stfinv_fdbase.tex -----
src/libs/libstfinv/doc/stfinv_fdleastsquares.tex 0 → 100644
View file @ 4e3c31ce
% this is <stfinv_fdleastsquares.tex>
% ----------------------------------------------------------------------------
% $Id: $
%
% Copyright (c) 2014 by Thomas Forbriger (BFO Schiltach)
%
% documentation of Fourier-domain least-squares approach
%
% REVISIONS and CHANGES
% 24/02/2014 V1.0 Thomas Forbriger
%
% ============================================================================
%
% ----- END OF stfinv_fdleastsquares.tex -----
src/libs/libstfinv/doc/stfinv_identity.tex 0 → 100644
View file @ 4e3c31ce
% this is <stfinv_identity.tex>
% ----------------------------------------------------------------------------
% $Id: $
%
% Copyright (c) 2014 by Thomas Forbriger (BFO Schiltach)
%
% documentation of STFEngineIdentity
%
% REVISIONS and CHANGES
% 24/02/2014 V1.0 Thomas Forbriger
%
% ============================================================================
%
% ----- END OF stfinv_identity.tex -----
src/libs/libstfinv/doc/stfinv_normalize.tex 0 → 100644
View file @ 4e3c31ce
% this is <stfinv_normalize.tex>
% ----------------------------------------------------------------------------
% $Id: $
%
% Copyright (c) 2014 by Thomas Forbriger (BFO Schiltach)
%
% documentation of STFEngineNormalize
%
% REVISIONS and CHANGES
% 24/02/2014 V1.0 Thomas Forbriger
%
% ============================================================================
%
% ----- END OF stfinv_normalize.tex -----
src/libs/libstfinv/doxydoc.cfg
View file @ 4e3c31ce
......@@ -89,7 +89,7 @@ WARN_LOGFILE =
#---------------------------------------------------------------------------
INPUT = ./
INPUT_ENCODING = UTF-8
FILE_PATTERNS = doxygen*.txt onlinehelp.xxx \
FILE_PATTERNS = doxygen*.txt \
*.h \
*.cc
RECURSIVE = YES
......@@ -97,7 +97,7 @@ EXCLUDE = .svn test_libstfinv
EXCLUDE_SYMLINKS = NO
EXCLUDE_PATTERNS =
EXCLUDE_SYMBOLS =
EXAMPLE_PATH = tests
EXAMPLE_PATH = tests usage
EXAMPLE_PATTERNS =
EXAMPLE_RECURSIVE = NO
IMAGE_PATH =
......
src/libs/libstfinv/doxygen.txt
View file @ 4e3c31ce
......@@ -49,153 +49,32 @@ namespace stfinv {
\author Thomas Forbriger
\since May 2011
\date May 2011
\date October 2015
\version V1.0
Contents of this page:
- \ref main_sec_users
- \ref main_subsec_introduction
- \ref main_subsec_libraries