[MERGE] (lisousi): rework documentation, add examples

Merge branch 'issue5lisousi', remote-tracking branch 'origin/exampleslisousi'

Rework the online documentation of lisousi. Properply refer to Forbriger et
al. (2014, doi:10.1093/gji/ggu199). Use the appropriate terms to characterize
the approaches offered by lisousi and give the correct definition of theory of
operation and filters to be applied.

Provide the set of Makefiles and configuration files used in the production of
figures for the paper by Forbriger et al. (2014, doi:10.1093/gji/ggu199).
These can be used as toy examples or simply to test lisousi.

src/ts/lisousi/examples/.gitignore

+*.bin
+*.coe
+*.dmod

src/ts/lisousi/examples/Makefile

@@ -10,8 +10,12 @@
 # 
 # ============================================================================
 #
+# plots used by Forbriger et al. (2014, doi:10.1093/gji/ggu199):
+PUBPLOTS=bietZ bietR bietCZ bietCR fullspace bietmod \
+         bietZpcol bietRpcol fullspacecol bietmodcol
 
-all:
+.PHONY: all
+all: $(addsuffix .pdf,$(PUBPLOTS))
 
 # Makefiles containing rules
 MAKEFILES=$(filter-out %.bak,$(wildcard Makefile*))
@@ -25,8 +29,11 @@ REFMETMOD=$(wildcard *.mod)
 REFMETSRC=$(wildcard *.src)
 #  receiver definition
 REFMETRCV=$(wildcard *.rcv)
+#  traveltime picks
+PICKS=$(wildcard *.pck)
 
-flist: README $(MAKEFILES) $(REFMETMAIN) $(REFMETMOD) $(REFMETSRC) $(REFMETRCV)
+flist: README $(MAKEFILES) $(REFMETMAIN) $(REFMETMOD) $(REFMETSRC) \
+  $(REFMETRCV) $(PICKS)
 	echo README | tr ' ' '\n' | sort > $@
 	echo '----' >> $@
 	echo $(MAKEFILES) | tr ' ' '\n' | sort >> $@
@@ -38,6 +45,8 @@ flist: README $(MAKEFILES) $(REFMETMAIN) $(REFMETMOD) $(REFMETSRC) $(REFMETRCV)
 	echo $(REFMETSRC) | tr ' ' '\n' | sort >> $@
 	echo '----' >> $@
 	echo $(REFMETRCV) | tr ' ' '\n' | sort >> $@
+	echo '----' >> $@
+	echo $(PICKS) | tr ' ' '\n' | sort >> $@
 
 .PHONY: edit
 edit: flist; vim $<
@@ -80,10 +89,4 @@ include Makefile.plots
 %.pde: %.pdf; evince -w $<; /bin/rm -fv $<
 %.pdp: %.pdf; acroread $<; /bin/rm -fv $<
 
-#======================================================================
-# figures section
-# ---------------
-PSFIGBASE=bietZ bietR bietCZ bietCR fullspace bietmod \
-          bietZpcol bietRpcol fullspacecol bietmodcol
-
 # ----- END OF Makefile ----- 

src/ts/lisousi/examples/Makefile.synthetics

@@ -10,6 +10,11 @@
 # 
 # ============================================================================
 #
+# TODO: for other configurations (smaller number of receivers) template
+# configurations files are prepared. They cut be modified by application of
+# sed to contain appropriate references to receiver or source configuration
+# files.
+#
 #----------------------------------------------------------------------
 # produce synthetic waveforms
 # ---------------------------

src/ts/lisousi/examples/README

@@ -18,6 +18,20 @@ as described by Forbriger (2003a,b)
 In order to produce results for the test cases, other programs from Seitosh
 are required as well.
 
+The plots used by Forbriger et al. (2014) can be reproduced by
+
+  make all
+
+Their names are defined in the Makefile variable PUBPLOTS:
+  bietCR.pdf bietCZ.pdf bietmodcol.pdf bietmod.pdf bietRpcol.pdf bietR.pdf
+  bietZpcol.pdf bietZ.pdf fullspacecol.pdf fullspace.pdf
+
+As simple test cases they are quite inefficient. A huge amount of receivers
+(500 receivers per profile) are simulated in order to provide an appropriate
+dataset for the Fourier Bessel transformation. Since lisousi applies
+transformations to each receiver seperately, a significantly smaller amount of
+receivers would be sufficient to test ist operation.
+
 References
 ----------
 

src/ts/lisousi/examples/bietgeneric.main

-Generic control file for case Bietigheim
+Generic control file for case Bietigheim (not yet implemented in Makefile)
 
 Model taken from
 <MODEL>

src/ts/lisousi/examples/fsgeneric.main

-Generic control file for homogeneous full space
+Generic control file for homogeneous full space (not yet implemented in Makefile)
 
 Model taken from
 <MODEL>

src/ts/lisousi/examples/lzline.pck

+REFRACT   V4.9   REFRACTion seismics - data interpretation                                          
+    2
+   0.1700000   0.1000000
+   0.2000000   0.1010000