Editing Guide to madagascar programs (section)

==sfdottest==
{| class="wikitable" align="center" cellspacing="0" border="1"
! colspan="4" style="background:#ffdead;" | Generic dot-product test for linear operators with adjoints 
|-
! colspan="4" | sfdottest mod=mod.rsf dat=dat.rsf > pip.rsf
|-
| ''file   '' || '''dat=''' ||   || 	auxiliary input file name
|-
| ''file   '' || '''mod=''' ||   || 	auxiliary input file name
|}

<tt>sfdottest</tt> is a generic dot-product test program for testing
linear operators. Suppose there is an executable program
<tt><prog></tt> that takes an RSF file from the standard input and
produces an RSF file in the standard output. It may take any number of
additional parameters but one of them must be <tt>adj=</tt> that sets
the forward (<tt>adj=0</tt>) or adjoint (<tt>adj=1</tt>) operations.
The program <tt><prog></tt> is typically an RSF program but it could
be anything (a script, a multiprocessor MPI program, etc.) as long as
it implements a linear operator <math>\mathbf{L}</math> and its adjoint
<math>\mathbf{L}^T</math>. The <tt>sfdottest</tt> program is testing the equality
<center><math>
d^T\,L\,m = m^T\,L^T\,d
</math></center>
by using random vectors <math>\mathbf{m}</math> and <math>\mathbf{d}</math>. You can invoke it with
<pre>
bash$ sfdottest <prog> [optional aruments] mod=mod.rsf dat=dat.rsf
</pre>
where <tt>mod.rsf</tt> and <tt>dat.rsf</tt> are RSF files that
represent vectors from the model and data spaces. Pay attention to the 
dimensions and size of these vectors! If the program does not respond
for a very long time, the dimension and size
of the vectors may be inconsistent with the requirement of the program to be
tested. <tt>sfdottest</tt>
does not create any temporary files and has no restrictive
limitations on the size of the vectors.
Here is an example. We first create a vector with 100 elements using
<tt>sfspike</tt> and then run <tt>sfdottest</tt> to test the
<tt>sfcausint</tt> program. <tt>sfcausint</tt> implements a linear operator of causal integration and its adjoint, the anti-causal
integration.
<pre>
bash$ sfspike n1=100 > vec.rsf
bash$ sfdottest sfcausint mod=vec.rsf dat=vec.rsf
sfdottest:  L[m]*d=1410.2
sfdottest: L'[d]*m=1410.2
bash$ sfdottest sfcausint mod=vec.rsf dat=vec.rsf
sfdottest:  L[m]*d=1165.87
sfdottest: L'[d]*m=1165.87
</pre>
The numbers are different on subsequent runs because of changing
seed in the random number generator.
Here is a somewhat more complicated example. The <tt>sfhelicon</tt>
program implements Claerbout's multidimensional helical filtering
(Claerbout, 1998<ref>Claerbout, J.,  1998, Multidimensional recursive filters via a helix:  Geophysics, '''63''', 1532--1541.</ref>). It requires a filter to be specified in
addition to the input and output vectors. We create a helical 
2-D filter using the Unix <tt>echo</tt> command.
<pre>
bash$ echo 1 19 20 n1=3 n=20,20 data_format=ascii_int in=lag.rsf > lag.rsf
bash$ echo 1 1 1 a0=-3 n1=3 data_format=ascii_float in=flt.rsf > flt.rsf
</pre>
Next, we create an example 2-D model and data vector with <tt>sfspike</tt>.
<pre>
bash$ sfspike n1=50 n2=50 > vec.rsf
</pre>
Now the <tt>sfdottest</tt> program can perform the dot product test.
<pre>
bash$ sfdottest sfhelicon filt=flt.rsf lag=lag.rsf \
> mod=vec.rsf dat=vec.rsf
sfdottest:  L[m]*d=8.97375
sfdottest: L'[d]*m=8.97375
</pre>
Here is the same program tested in the inverse filtering mode:
<pre>
bash$ sfdottest sfhelicon filt=flt.rsf lag=lag.rsf \
> mod=vec.rsf dat=vec.rsf div=y
sfdottest:  L[m]*d=15.0222
sfdottest: L'[d]*m=15.0222
</pre>