[WP] (stf_issue12): add description of basic operation of toy examples

src/ts/wf/testcases/Makefile

@@ -58,7 +58,7 @@ clean: ;
 soutifu%: Makefile.soutifu ; $(MAKE) -f $< $@
 
 # soutifu test cases
-SOUTIFUCASES=1 1_add 2a 2b 3a 3b 3c
+SOUTIFUCASES=1 1_add 2a 2b 2c 3a 3b 3c
 SOUTIFURESULTS=$(addprefix soutifu,$(addsuffix _report,$(SOUTIFUCASES)))
 soutifutests: 
 	$(MAKE) clean

src/ts/wf/testcases/Makefile.soutifu

@@ -47,9 +47,9 @@ all:
 clean: 
 	-/bin/rm -vf flist *.xxx *.xxx.* *.sff *.TZ *.TR *.grn *.su
 
-.PHONY: simulclean
-simulclean:
-	-/bin/rm -vf *.sff *.su stf.fil.xxx
+.PHONY: soutifuclean
+soutifuclean:
+	-/bin/rm -vf soutifu* *.sff *.su stf.fil.xxx
 
 #
 # ======================================================================
@@ -123,7 +123,7 @@ seismo.TZ seismo.TR: refmetmain.xxx
 # Plot waveform data
 # ------------------
 # Create a graphical display of waveform data used for testcases.
-basewaveform.ps: 2lay.TZ 2layb.TZ
+soutifubasewaveform.ps: 2lay.TZ 2layb.TZ
 	refract -d $@/cps -C -Tt "Basic synthetic time series" \
 	  -Sm 2 -Se 2.3 -Sc 5. -Sa 3.5 -Eg -St 0.,1. $^
 
@@ -139,11 +139,11 @@ basewaveform.ps: 2lay.TZ 2layb.TZ
 #
 #   Fourier-Bessel expansion coefficients for models 2lay and 2layb:
 #
-#     make -f Makefile.soutifu 2laysyggrn.ps 2laybsyggrn.ps
+#     make -f Makefile.soutifu soutifu2laysyggrn.ps soutifu2laybsyggrn.ps
 #
 #   Difference in Fourier-Bessel expansion coeffcients for both models:
 #
-#     make -f Makefile.soutifu diffgrn.ps
+#     make -f Makefile.soutifu soutifudiffgrn.ps
 
 # syg
 # ---
@@ -157,7 +157,7 @@ diff.grn: 2laysyg.grn 2laybsyg.grn; rm -fv $@; gredi $^ $@
 # grepg
 # -----
 # Create Postscript plot of Fourier-Bessel coefficients
-%grn.ps: %.grn
+soutifu%grn.ps: %.grn
 	grepg $< -W -d $@/ps -p 0.8 -s -f 10 -i -g
 
 # ======================================================================
@@ -190,18 +190,7 @@ synthetic2lay.sff synthetic2layb.sff syntheticseismo.sff:
 	$(MAKE) new$@ -f Makefile.soutifu
 	/bin/cp -vpd new$@ $@
 
-# 3b. Add noise
-# -------------
-# As a first step to simulate recorded data, white Gaussian noise can be added
-# to the synthetic waveforms.
-#
-# The rms-amplitude of noise is specified by variable NOISEAMP
-# a reasonable value to start with is NOISEAMP=1.e-5
-NOISEAMP=0.
-noisy%.sff: synthetic%.sff 
-	printf "noi  $(NOISEAMP)\nend\n" | tidofi -v -o -cs $@ $<
-
-# 3c. Apply a filter, simulating a source time function
+# 3b. Apply a filter, simulating a source time function
 # -----------------------------------------------------
 # As a second step to simulate recorded data, a filter is applied to the
 # waveform data, which simulates a source time function or the response of a
@@ -216,18 +205,29 @@ STFFAC=2.5
 # Trigger advance
 STFDELAY=0.03
 stf.fil.xxx: ; printf "lpb  $(STFPER),4\ndel  $(STFDELAY)\nfac  $(STFFAC)\nend\n" > $@
-data%.sff: noisy%.sff stf.fil.xxx
+filtered%.sff: synthetic%.sff stf.fil.xxx
 	tidofi -v -o -cf $(word 2,$^) $@ $<
 
+# 3c. Add noise
+# -------------
+# As a first step to simulate recorded data, white Gaussian noise can be added
+# to the synthetic waveforms.
+#
+# The rms-amplitude of noise is specified by variable NOISEAMP
+# a reasonable value to start with is NOISEAMP=1.e-5
+NOISEAMP=0.
+data%.sff: filtered%.sff 
+	printf "noi  $(NOISEAMP)\nend\n" | tidofi -v -o -cs $@ $<
+
 # Display waveforms
 # -----------------
 # Display waveform data as provided for tests. This way different settings for
 # the source time function simulation and data noise can be tested.
 #
-# syntheticplot.ps
-# noisyplot.ps
-# dataplot.ps
-%plot.ps: %2lay.sff %2layb.sff
+# soutifusyntheticplot.ps
+# soutifunoisyplot.ps
+# soutifudataplot.ps
+soutifu%plot.ps: %2lay.sff %2layb.sff
 	refract -d $@/cps -C -Tt "Synthetic time series" \
 	  -Sm 2 -Se 2.3 -Sc 5. -Sa 3.5 -Eg -St 0.,1. $^
 

src/ts/wf/testcases/README.soutifu

@@ -3,6 +3,84 @@ this is <README.soutifu>
 soutifu toy example - step by step
 ==================================
 
-The
+Purpose and basic usage
+-----------------------
+src/ts/wf/testcases/Makefile.soutifu contains the definition of test cases for
+soutifu. Change directory to src/ts/wf/testcases and execute
+
+  make soutifutests
+
+This will run all tests as defined in Makefile.soutifu The results will be
+presented in PDF files:
+
+  soutifu1_add_report.pdf  soutifu2b_report.pdf  soutifu3b_report.pdf
+  soutifu1_report.pdf      soutifu2c_report.pdf  soutifu3c_report.pdf
+  soutifu2a_report.pdf     soutifu3a_report.pdf
+
+These reports contain descriptive texts and waveform displays. They serve as a
+quick test for proper operation and should be useful as a first approach to
+soutifu operation. The setup of the test cases can be controlled through make
+variables passed on the command line. This way they can serve as toy examples.
+
+Principle of operation for test cases and toy examples
+------------------------------------------------------
+The test cases are applied to simulated recordings and corresponding
+synthetics. Both are computed with the reflectivity algorithm as implemented
+in the program refmet.
+
+A plot of the waveform data all other components are based on, can be produced
+by
+
+  make soutifubasewaveform.pdf
+
+To study the surface wave propagation properties, plots of Fourier-Bessel
+expansion coefficients are provided too. Additionally a plot of the difference
+between expansion coefficients for both subsurface models (2lay and 2layb) ㄞs
+provided:
+
+  make soutifu2laysyggrn.pdf soutifu2laybsyggrn.pdf
+  make soutifudiffgrn.pdf
+
+To simulate recordings a low-pass filter, a time delay, and a scaling factor
+are applied to the seismograms. Additionally noise can be added. This results
+in two sets of data. On the one hand there are the simulated recorded data and
+on the other hand there are the corresponding synthetics. A plot of simulated
+observations can be produced by
+
+  make soutifudataplot.pdf
+
+The corresponding synthetics are display by
+
+  make soutifusyntheticplot.pdf
+
+When adding noise to the simulated observations, a plot of waveform amplitudes
+can be helpful:
+
+  make soutifuamp.pdf
+
+The data simulation can be controlled by the following make variables:
+
+SRCDUR      source wavelet duration
+SRCDEPTH    source depth
+NOISEAMP    noise rms-amplitude
+STFPER      low-pass eigenperiod (in seconds) for source time function 
+STFFAC      scaling factor for source time function simulation
+STFDELAY    delay (in seconds) to simulate a trigger advance
+
+To start a new test case from scratch (without recalculation of the
+reflectivity run) first execute
+
+  make soutifuclean
+
+For example the effect of a larger delay, a smaller low-pass period and
+additional noise can be studied by
+
+  make soutifuclean soutifudataplot.pdf NOISEAMP=7.e-6 STFPER=0.001 STFDELAY=0.3
+
+The noise amplitude can be adjusted by
+
+  make soutifuclean soutifuamp.pdf NOISEAMP=2.e-5
+
+and varying the value of NOISEAMP.
 
 ----- END OF README.soutifu -----