Documentation:system/main

From Madagascar
Jump to navigation Jump to search

Let us improve self-documentation of Madagascar programs!

Listed below are selfdocs for programs in system/main (generated with sfdoc). Please edit the descriptions to make them more complete and/or easier to understand.

sfadd

Add, multiply, or divide RSF datasets.
sfadd > out.rsf scale= add= sqrt= abs= log= exp= mode= [< file0.rsf] file1.rsf file2.rsf ...
The various operations, if selected, occur in the following order:

(1) Take absolute value, abs=
(2) Add a scalar, add=
(3) Take the natural logarithm, log=
(4) Take the square root, sqrt=
(5) Multiply by a scalar, scale=
(6) Compute the base-e exponential, exp=
(7) Add, multiply, or divide the data sets, mode=

sfadd operates on integer, float, or complex data, but all the input
and output files must be of the same data type.

An alternative to sfadd is sfmath, which is more versatile, but may be
less efficient.
bools abs= If true take absolute value [nin]
floats add= Scalar values to add to each dataset [nin]
bools exp= If true compute exponential [nin]
bools log= If true take logarithm [nin]
string mode= 'a' means add (default),
'p' or 'm' means multiply,
'd' means divide
floats scale= Scalar values to multiply each dataset with [nin]
bools sqrt= If true take square root [nin]

sfattr

Display dataset attributes.
sfattr < in.rsf lval=2 want=

Sample output from "sfspike n1=100 | sfbandpass fhi=60 | sfattr"
*******************************************
rms = 0.992354
mean = 0.987576
2-norm = 9.92354
variance = 0.00955481
std dev = 0.0977487
max = 1.12735 at 97
min = 0.151392 at 100
nonzero samples = 100
total samples = 100
*******************************************

rms = sqrt[ sum(data^2) / n ]
mean = sum(data) / n
norm = sum(abs(data)^lval)^(1/lval)
variance = [ sum(data^2) - n*mean^2 ] / [ n-1 ]
standard deviation = sqrt [ variance ]
int lval=2 norm option, lval is a non-negative integer, computes the vector lval-norm
string want= 'all'(default), 'rms', 'mean', 'norm', 'var',
'std', 'max', 'min', 'nonzero', 'samples', 'short'
want= 'rms' displays the root mean square
want= 'norm' displays the square norm, otherwise specified by lval.
want= 'var' displays the variance
want= 'std' displays the standard deviation
want= 'nonzero' displays number of nonzero samples
want= 'samples' displays total number of samples
want= 'short' displays a short one-line version

sfcat

Concatenate datasets.
sfcat > out.rsf order= space= axis=3 nspace=(int) (ni/(20*nin) + 1) o= d= [<file0.rsf] file1.rsf file2.rsf ...
sfmerge inserts additional space between merged data.
int axis=3 Axis being merged
float d= axis sampling
int nspace=(int) (ni/(20*nin) + 1) if space=y, number of traces to insert
float o= axis origin
ints order= concatenation order [nin]
bool space= [y/n] Insert additional space.
y is default for sfmerge, n is default for sfcat

sfcconjgrad

Generic conjugate-gradient solver for linear inversion with complex data
sfcconjgrad < dat.rsf mod=mod.rsf > to.rsf < from.rsf > out.rsf niter=1
file mod= auxiliary input file name
int niter=1 number of iterations

sfcdottest

Generic dot-product test for complex linear operators with adjoints
sfcdottest mod=mod.rsf dat=dat.rsf > pip.rsf
file dat= auxiliary input file name
file mod= auxiliary input file name

sfcmplx

Create a complex dataset from its real and imaginary parts.
sfcmplx < real.rsf > cmplx.rsf real.rsf imag.rsf
There has to be only two input files specified and no additional parameters.

sfconjgrad

Generic conjugate-gradient solver for linear inversion
sfconjgrad < dat.rsf mod=mod.rsf > to.rsf < from.rsf > out.rsf niter=1
file mod= auxiliary input file name
int niter=1 number of iterations

sfcp

Copy or move a dataset.
sfcp < in.rsf > out.rsf in.rsf out.rsf
sfcp - copy, sfmv - move.
Mimics standard Unix commands.

sfcut

Zero a portion of the dataset.
sfcut < in.rsf > out.rsf verb=n j#=(1,...) d#=(d1,d2,...) f#=(0,...) min#=(o1,o2,,...) n#=(0,...) max#=(o1+(n1-1)*d1,o2+(n1-1)*d2,,...)

Reverse of window.
float d#=(d1,d2,...) sampling in #-th dimension
largeint f#=(0,...) window start in #-th dimension
int j#=(1,...) jump in #-th dimension
float max#=(o1+(n1-1)*d1,o2+(n1-1)*d2,,...) maximum in #-th dimension
float min#=(o1,o2,,...) minimum in #-th dimension
int n#=(0,...) window size in #-th dimension
bool verb=n [y/n] Verbosity flag

sfdd

Convert between different formats.
sfdd < in.rsf > out.rsf trunc=n line=8 ibm=n form= type= format=
string form= ascii, native, xdr
string format= Element format (for conversion to ASCII)
bool ibm=n [y/n] Special case - assume integers actually represent IBM floats
int line=8 Number of numbers per line (for conversion to ASCII)
bool trunc=n [y/n] Truncate or round to nearest when converting from float to int/short
string type= int, float, complex, short

sfdisfil

Print out data values.
sfdisfil < in.rsf number=y col=0 format= header= trailer=

Alternatively, use sfdd and convert to ASCII form.
int col=0 Number of columns.
The default depends on the data type:
10 for int and char,
5 for float,
3 for complex
string format= Format for numbers (printf-style).
The default depends on the data type:
"%4d " for int and char,
"%13.4g" for float,
"%10.4g,%10.4gi" for complex
string header= Optional header string to output before data
bool number=y [y/n] If number the elements
string trailer= Optional trailer string to output after data

sfdottest

Generic dot-product test for linear operators with adjoints
sfdottest mod=mod.rsf dat=dat.rsf > pip.rsf
file dat= auxiliary input file name
file mod= auxiliary input file name

sfget

Output parameters from the header.
sfget parform=y all=n par1 par2 ...
bool all=n [y/n] If output all values.
bool parform=y [y/n] If y, print out parameter=value. If n, print out value.

sfheadercut

Zero a portion of a dataset based on a header mask.
sfheadercut mask=head.rsf < in.rsf > out.rsf

The input data is a collection of traces n1xn2,
mask is an integer array of size n2.
file mask= auxiliary input file name

sfheadersort

Sort a dataset according to a header key.
sfheadersort < in.rsf > out.rsf head=
string head= header file

sfheaderwindow

Window a dataset based on a header mask.
sfheaderwindow mask=head.rsf < in.rsf > out.rsf

The input data is a collection of traces n1xn2,
mask is an integer array os size n2, windowed is n1xm2,
where m2 is the number of nonzero elements in mask.
file mask= auxiliary input file name

sfin

Display basic information about RSF files.
sfin info=y check=2. trail=y [<file0.rsf] file1.rsf file2.rsf ...
n1,n2,... are data dimensions
o1,o2,... are axis origins
d1,d2,... are axis sampling intervals
label1,label2,... are axis labels
unit1,unit2,... are axis units
float check=2. Portion of the data (in Mb) to check for zero values.
bool info=y [y/n] If n, only display the name of the data file.
bool trail=y [y/n] If n, skip trailing dimensions of one

sfinterleave

Combine several datasets by interleaving.
sfinterleave > out.rsf axis=3 [< file0.rsf] file1.rsf file2.rsf ...
int axis=3 Axis for interleaving

sfmask

Create a mask.
sfmask < in.rsf > out.rsf min= max= min= max=

Mask is an integer data with ones and zeros.
Ones correspond to input values between min and max.

The output can be used with sfheaderwindow.
int max= maximum header value
int min= minimum header value

sfmath

Mathematical operations on data files.
sfmath > out.rsf n#= d#=(1,1,...) o#=(0,0,...) label#= unit#= type= label= unit= output=

Known functions:
cos, sin, tan, acos, asin, atan,
cosh, sinh, tanh, acosh, asinh, atanh,
exp, log, sqrt, abs,
erf, erfc (for float data),
arg, conj, real, imag (for complex data).

sfmath will work on float or complex data, but all the input and output
files must be of the same data type.

An alternative to sfmath is sfadd, which may be more efficient, but is
less versatile.

Examples:

sfmath x=file1.rsf y=file2.rsf power=file3.rsf output='sin((x+2*y)^power)' > out.rsf
sfmath < file1.rsf tau=file2.rsf output='exp(tau*input)' > out.rsf
sfmath n1=100 type=complex output="exp(I*x1)" > out.rsf

Arguments which are not treated as variables in mathematical expressions:
datapath=, type=, out=

See also: sfheadermath.
float d#=(1,1,...) sampling on #-th axis
string label= data label
string label#= label on #-th axis
largeint n#= size of #-th axis
float o#=(0,0,...) origin on #-th axis
string output= Mathematical description of the output
string type= output data type [float,complex]
string unit= data unit
string unit#= unit on #-th axis

sfmpi

MPI wrapper for embarassingly parallel jobs.
sfmpi input=inp.rsf output=out.rsf split=ndim join=axis
string input= auxiliary input file name
int join=axis axis to join
file output= auxiliary output file name
int split=ndim axis to split

sfomp

OpenMP wrapper for embarassingly parallel jobs.
sfomp < inp.rsf > out.rsf split=ndim join=axis
int join=axis axis to join
int split=ndim axis to split

sfpad

Pad a dataset with zeros.
sfpad < in.rsf > out.rsf beg#=0 end#=0 n#=

n#out is equivalent to n#, both of them overwrite end#.
int beg#=0 the number of zeros to add before the beginning of #-th axis
int end#=0 the number of zeros to add after the end of #-th axis
int n#= the output length of #-th axis - padding at the end

sfput

Input parameters into a header.
sfput < in.rsf > out.rsf [parameter=value list]

sfreal

Extract real (sfreal) or imaginary (sfimag) part of a complex dataset.
sfreal < cmplx.rsf > real.rsf

sfreverse

Reverse one or more axes in the data hypercube.
sfreverse < in.rsf > out.rsf which=-1 verb=n memsize=sf_memsize() opt=
int memsize=sf_memsize() Max amount of RAM (in Mb) to be used
string opt= If y, change o and d parameters on the reversed axis;
if i, don't change o and d
bool verb=n [y/n] Verbosity flag
int which=-1 Which axis to reverse.
To reverse a given axis, start with 0,
add 1 to number to reverse n1 dimension,
add 2 to number to reverse n2 dimension,
add 4 to number to reverse n3 dimension, etc.
Thus, which=7 would reverse the first three dimensions,
which=5 just n1 and n3, etc.
which=0 will just pass the input on through unchanged.

sfrm

Remove RSF files together with their data.
sfrm file1.rsf [file2.rsf ...] [-i] [-v] [-f]
Mimics the standard Unix rm command.

See also: sfmv, sfcp.

sfrotate

Rotate a portion of one or more axes in the data hypercube.
sfrotate < in.rsf > out.rsf verb=n memsize=sf_memsize() rot#=(0,0,...)
int memsize=sf_memsize() Max amount of RAM (in Mb) to be used
int rot#=(0,0,...) length of #-th axis that is moved to the end
bool verb=n [y/n] Verbosity flag

sfrtoc

Convert real data to complex (by adding zero imaginary part).
sfrtoc < real.rsf > cmplx.rsf pair=n

See also: sfcmplx
bool pair=n [y/n] y - use odd elements for real part and even ones for imaginary part

sfscale

Scale data.
sfscale < in.rsf > out.rsf axis=0 rscale=0. dscale=1.

To scale by a constant factor, you can also use sfmath.
int axis=0 Scale by maximum in the dimensions up to this axis.
float dscale=1. Scale by this factor (works if rscale=0)
float rscale=0. Scale by this factor.

sfspike

Generate simple data: spikes, boxes, planes, constants.
sfspike < in.rsf > spike.rsf mag= nsp=1 k#=[0,...] l#=[k1,k2,...] p#=[0,...] n#= o#=[0,0,...] d#=[0.004,0.1,0.1,...] label#=[Time,Distance,Distance,...] unit#=[s,km,km,...] title=

Spike positioning is given in samples and starts with 1.
float d#=[0.004,0.1,0.1,...] sampling on #-th axis
ints k#=[0,...] spike starting position [nsp]
ints l#=[k1,k2,...] spike ending position [nsp]
string label#=[Time,Distance,Distance,...] label on #-th axis
floats mag= spike magnitudes [nsp]
int n#= size of #-th axis
int nsp=1 Number of spikes
float o#=[0,0,...] origin on #-th axis
floats p#=[0,...] spike inclination (in samples) [nsp]
string title= title for plots
string unit#=[s,km,km,...] unit on #-th axis

sfspray

Extend a dataset by duplicating in the specified axis dimension.
sfspray < in.rsf > out.rsf axis=2 n= d= o= label= unit=
This operation is adjoint to sfstack.
int axis=2 which axis to spray
float d= Sampling of the newly created dimension
string label= Label of the newly created dimension
int n= Size of the newly created dimension
float o= Origin of the newly created dimension
string unit= Units of the newly created dimension

sfstack

Stack a dataset over one of the dimensions.
sfstack < in.rsf > out.rsf scale= axis=2 rms=n norm=y min=n max=n prod=n

This operation is adjoint to sfspray.
int axis=2 which axis to stack
bool max=n [y/n] If y, find maximum instead of stack. Ignores rms and norm.
bool min=n [y/n] If y, find minimum instead of stack. Ignores rms and norm.
bool norm=y [y/n] If y, normalize by fold.
bool prod=n [y/n] If y, find product instead of stack. Ignores rms and norm.
bool rms=n [y/n] If y, compute the root-mean-square instead of stack.
floats scale= optionally scale before stacking [n2]

sftransp

Transpose two axes in a dataset.
sftransp < in.rsf > out.rsf memsize=sf_memsize() plane=

If you get a "Cannot allocate memory" error, give the program a
memsize=1 command-line parameter to force out-of-core operation.
int memsize=sf_memsize() Max amount of RAM (in Mb) to be used
int plane= Two-digit number with axes to transpose. The default is 12

sfwindow

Window a portion of a dataset.
sfwindow < in.rsf > out.rsf verb=n squeeze=y j#=(1,...) d#=(d1,d2,...) f#=(0,...) min#=(o1,o2,,...) n#=(0,...) max#=(o1+(n1-1)*d1,o2+(n1-1)*d2,,...)
float d#=(d1,d2,...) sampling in #-th dimension
largeint f#=(0,...) window start in #-th dimension
int j#=(1,...) jump in #-th dimension
float max#=(o1+(n1-1)*d1,o2+(n1-1)*d2,,...) maximum in #-th dimension
float min#=(o1,o2,,...) minimum in #-th dimension
largeint n#=(0,...) window size in #-th dimension
bool squeeze=y [y/n] if y, squeeze dimensions equal to 1 to the end
bool verb=n [y/n] Verbosity flag
Retrieved from "https://www.reproducibility.org/wiki2020/index.php?title=Documentation:system/main&oldid=2452"