0% found this document useful (0 votes)

148 views376 pages

Manual PDF

This document provides a reference manual for programming in Madagascar, an open source software for seismic wave analysis. It covers topics like data types, input preparation, operations on file formats, linear operators, data analysis techniques, filtering, solvers, interpolation, smoothing, ray tracing, general tools, geometry, and miscellaneous functions. The document contains code examples and explanations for over 150 C functions and libraries for working with seismic wave data.

Uploaded by

Carlos Alberto Hinojosa

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

148 views376 pages

Manual PDF

Uploaded by

Carlos Alberto Hinojosa

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 376

Madagascar Programming Reference Manual

KAUST

Mohammad Akbar Zuberi

Tariq Alkhalifah
Christos Saragoitis

Seismic Wave Analysis Group

http://swag.kaust.edu.sa
2
Contents

Contents 7

Preface 9

1 Introduction 11

2 An example: Finite-Difference modeling 13

2.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.2 C program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.3 Explanation of the code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

3 Data types 25
3.1 Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

4 Preparing for input 31

4.1 Convenience allocation programs (alloc.c) . . . . . . . . . . . . . . . . . . . 31
4.2 Simbol Table for parameters (simtab.c) . . . . . . . . . . . . . . . . . . . . 52
4.3 Parameter handling (getpar.c) . . . . . . . . . . . . . . . . . . . . . . . . . . 64

5 Operations with RSF files 79

5.1 Main operations with RSF files (file.c) . . . . . . . . . . . . . . . . . . . . . 79
5.2 Additional operations with RSF files (files.c) . . . . . . . . . . . . . . . . . 113

3
4 CONTENTS

5.3 Complex number operations (komplex.c) . . . . . . . . . . . . . . . . . . . . 120

6 Error handling 149

6.1 Handling warning and error messages (error.c) . . . . . . . . . . . . . . . . 149

7 Linear operators 153

7.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
7.2 Adjoint zeroing (adjnull.c) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
7.3 Identity operator (copy.c) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
7.4 Identity operator (complex data) (ccopy.c) . . . . . . . . . . . . . . . . . . . 160
7.5 Simple mask operator (mask.c) . . . . . . . . . . . . . . . . . . . . . . . . . 161
7.6 Simple weight operator (weight.c) . . . . . . . . . . . . . . . . . . . . . . . . 163
7.7 1-D finite difference (igrad1.c) . . . . . . . . . . . . . . . . . . . . . . . . . . 167
7.8 Causal integration (causint.c) . . . . . . . . . . . . . . . . . . . . . . . . . . 168
7.9 Chaining linear operators (chain.c) . . . . . . . . . . . . . . . . . . . . . . . 169
7.10 Dot product test for linear operators (dottest.c) . . . . . . . . . . . . . . . . 175

8 Data analysis 177

8.1 FFT (kiss fftr.c) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
8.2 Cosine window weighting function (tent2.c) . . . . . . . . . . . . . . . . . . 179
8.3 Anisotropic diffusion, 2-D (impl2.c) . . . . . . . . . . . . . . . . . . . . . . . 180

9 Filtering 185
9.1 Frequency-domain filtering (freqfilt.c) . . . . . . . . . . . . . . . . . . . . . 185
9.2 Frequency-domain filtering in 2-D (freqfilt.c) . . . . . . . . . . . . . . . . . 189
9.3 Helical convolution (helicon.c) . . . . . . . . . . . . . . . . . . . . . . . . . . 192
9.4 Helical filter definition and allocation (helix.c) . . . . . . . . . . . . . . . . . 193
9.5 Recursive convolution (polynomial division) (recfilt.c) . . . . . . . . . . . . 195
9.6 Cosine Fourier transform (cosft.c) . . . . . . . . . . . . . . . . . . . . . . . . 197
CONTENTS 5

10 Solvers 201
10.1 Banded matrix solver (banded.c) . . . . . . . . . . . . . . . . . . . . . . . . 201
10.2 Claerbout’s conjugate-gradient iteration (cgstep.c) . . . . . . . . . . . . . . 205
10.3 Conjugate-gradient with shaping regularization (conjgrad.c) . . . . . . . . . 206
10.4 CG with preconditioning (conjprec.c) . . . . . . . . . . . . . . . . . . . . . . 209
10.5 CG iteration (complex data) (cgstep.c) . . . . . . . . . . . . . . . . . . . . . 211
10.6 Conjugate-gradient with shaping regularization for complex numbers (cconj-
grad.c) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
10.7 Conjugate-direction iteration (cdstep.c) . . . . . . . . . . . . . . . . . . . . 216
10.8 Linked list for use in conjugate-direction-type methods (llist.c) . . . . . . . 219
10.9 Conjugate-direction iteration for complex numbers (ccdstep.c) . . . . . . . . 223
10.10Linked list for CD-type methods (complex data) (clist.c) . . . . . . . . . . . 227
10.11Solving quadratic equations (quadratic.c) . . . . . . . . . . . . . . . . . . . 231
10.12Zero finder (fzero.c) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
10.13Runge-Kutta ODE solvers (runge.c) . . . . . . . . . . . . . . . . . . . . . . 233
10.14Solver function for iterative least-squares optimization (tinysolver.c) . . . . 236
10.15Solver functions for iterative least-squares optimization (bigsolver.c) . . . . 237
10.16Weighting for iteratively-reweighted least squares (irls.c) . . . . . . . . . . . 247
10.17Tridiagonal matrix solver (tridiagonal.c) . . . . . . . . . . . . . . . . . . . . 249

11 Interpolation 255
11.1 1-D interpolation (int1.c) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
11.2 2-D interpolation (int2.c) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
11.3 3-D interpolation (int3.c) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
11.4 Basic interpolation functions (interp.c) . . . . . . . . . . . . . . . . . . . . . 262
11.5 Convert data to B-spline coefficients by fast B-spline transform (prefilter.c) 265
11.6 B-spline interpolation (spline.c) . . . . . . . . . . . . . . . . . . . . . . . . . 267
11.7 Inverse linear interpolation (stretch.c) . . . . . . . . . . . . . . . . . . . . . 271
6 CONTENTS

11.8 1-D ENO interpolation (eno.c) . . . . . . . . . . . . . . . . . . . . . . . . . 274

11.9 ENO interpolation in 2-D (eno2.c) . . . . . . . . . . . . . . . . . . . . . . . 277
11.101-D ENO power-p interpolation (pweno.c) . . . . . . . . . . . . . . . . . . . 280

12 Smoothing 285
12.1 1-D triangle smoothing as a linear operator (triangle1.c) . . . . . . . . . . . 285
12.2 2-D triangle smoothing as a linear operator (triangle2.c) . . . . . . . . . . . 287
12.3 Triangle smoothing (triangle.c) . . . . . . . . . . . . . . . . . . . . . . . . . 289
12.4 Smooth gradient operations (edge.c) . . . . . . . . . . . . . . . . . . . . . . 296

13 Ray tracing 301

13.1 Cell ray tracing (celltrace.c) . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
13.2 Cell ray tracing (cell.c) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303

14 General tools 313

14.1 First derivative FIR filter (deriv.c) . . . . . . . . . . . . . . . . . . . . . . . 313
14.2 Computing quantiles by Hoare’s algorithm (quantile.c) . . . . . . . . . . . . 315
14.3 Pseudo-random numbers: uniform and normally distributed (randn.c) . . . 316
14.4 Evaluating mathematical expressions (math1.c) . . . . . . . . . . . . . . . . 317

15 Geometry 323
15.1 Construction of points (point.c) . . . . . . . . . . . . . . . . . . . . . . . . . 323
15.2 Construction of vectors (vector.c) . . . . . . . . . . . . . . . . . . . . . . . . 334
15.3 Conversion between line and Cartesian coordinates of a vector (decart.c) . . 342
15.4 Axes (axa.c) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

16 Miscellaneous 357
16.1 sharpening (sharpen.c) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
16.2 Sharpening inversion added Bregman iteration (sharpinv.c) . . . . . . . . . 359
CONTENTS 7

17 System 363
17.1 Priority queue (heap sorting) (pqueue.c) . . . . . . . . . . . . . . . . . . . . 363
17.2 Simplified system command (system.c) . . . . . . . . . . . . . . . . . . . . . 367
17.3 Generic stack (FILO) structure operations (stack.c) . . . . . . . . . . . . . 368

Index 376
8 CONTENTS
Preface

This document is a contribution to the Madagascar developers community and it is meant

to help out with Programming in Madagascar. It also came out of our selfish need to learn
more about the libraries described in Madagascar. This document specifically lists and
describes the RSF API functions supported by Madagascar for C.
The first chapter is an introduction, summarizing the key information needed to under-
stand Madagascar and its history. In the second chapter there is an example program with
explanation for every line of the code. The example program is a finite difference modeling
code.
The RSF Function Library starts from Chapter 3, which is a description of the data
types used in Madagascar. Some data types are defined in Madagascar and some are from
the standard C library headers.
The subsequent chapters group different subroutines (the .c files) which are used for a
particular task. Chapter 4 lists the .c files which have the functions used in the preparation
for input, such as sf alloc, which allocates the required space.
Chapter 5 is related to the handling of the .rsf files, for example file input/output,
extracting or inserting a parameter from a file.
Chapter 6 is for the error handling subroutines. It lists the functions which print the
required error messages.
Chapter 7 lists the linear operators. There is a detailed introduction in the beginning
of the chapter.
Chapter 8 is for data analysis subroutines, for example kiss fftr.c for the Fourier
inverse and forward transform of real time signals.
Chapter 9 lists the subroutines for the filtering and convolution.
Chapter 10 lists the solvers. It has the subroutines for tasks like solving a first order
ODE using the Runge-Kutta solver. There are subroutines in this chapter which perform

9
10 CONTENTS

the iterations for the conjugate gradient method for real and complex data. Some other
functions include the root finder and tridagonal matrix solver.
Chapter 11 is for the interpolation subroutines. It has subroutines for 1D, 2D and
3D interpolation. There are functions for B-Spline interpolation, calculation for B-spline
coefficients, ENO and ENO power-p interpolation.
Chapter 12 has the subroutines for of smoothing and edge detection. It has functions
for 1D and 2D triangle smoothing.
Chapter 13 lists the Ray Tracing functions.
Chapter 14 has some general purpose tools like functions for evaluating a mathematical
expression and generating random numbers.
Chapter 15 is concerned with the geometry. It has the functions which define vectors
and points which can be used to define the source and receiver coordinates. It also has the
axa.c file which defines the functions for creating and operating on axes.
Chapter 16 is for the miscellaneous functions.
Chapter 17 lists the function which are system specific for example system.c file defines
functions which can run a given command on the terminal from within the program.
Chapter 1

Introduction

Madagascar provides interfaces for programming in C and optionally in C++ and For-
tran90, etc. The C API is installed automatically during the installation of the Madagascar
package. The other interfaces should be installed separately, if necessary, as explained in
the installation guide.
Programming using a language for which an API (Applications Programming Interface)
is provided by Madagascar allows the user to operate on RSF files and also use some
predefined functions from the RSF library. These library files are located in the directories
api and build/api in the source directory.
A guide to Madagascar programming interface can be found at the Madagascar website

11
12 CHAPTER 1. INTRODUCTION
Chapter 2

An example: Finite-Difference
modeling

To demonstrate the use of the RSF library, a time-domain finite-difference modeling pro-
gram is explained in detail.

2.1 Introduction

This section presents time-domain finite-difference modeling [1] written with the RSF li-
brary. The program is demonstrated with the C, C++ and Fortran 90 interfaces. The
acoustic wave-equation

1 ∂2U
∆U − = f (t)
v 2 ∂t2

can be written as

∂2U
|∆U − f (t)|v 2 = ,
∂t2
where ∆ is the Laplacian symbol, f (t) is the source wavelet, v is the velocity, and U is a
scalar wavefield. A discrete time-step involves the following computations:

Ui+1 = [∆U − f (t)]v 2 ∆t2 + 2Ui − Ui−1 ,

where Ui?1 , Ui and Ui+1 represent the propagating wavefield at various time steps. In this
exercise we shall use a discrete Laplacian accurate up to the fourth order and the second
derivative of time is accurate up to the second order.

13
14 CHAPTER 2. AN EXAMPLE: FINITE-DIFFERENCE MODELING

2.2 C program

1 /* time-domain acoustic FD modeling */

2 #include <rsf.h>
3
4 int main(int argc, char* argv[])
5 {
6 /* Laplacian coefficients */
7 float c0=-30./12.,c1=+16./12.,c2=- 1./12.;
8
9 bool verb; /* verbose flag */
10 sf_file Fw=NULL,Fv=NULL,Fr=NULL,Fo=NULL; /* I/O files */
11 sf_axis at,az,ax; /* cube axes */
12 int it,iz,ix; /* index variables */
13 int nt,nz,nx;
14 float dt,dz,dx,idx,idz,dt2;
15
16 float *ww,**vv,**rr; /* I/O arrays*/
17 float **um,**uo,**up,**ud;/* tmp arrays */
18
19 sf_init(argc,argv);
20 if(! sf_getbool("verb",&verb)) verb=0;
21
22 /* setup I/O files */
23 Fw = sf_input ("in" );
24 Fo = sf_output("out");
25 Fv = sf_input ("vel");
26 Fr = sf_input ("ref");
27
28 /* Read/Write axes */
29 at = sf_iaxa(Fw,1); nt = sf_n(at); dt = sf_d(at);
30 az = sf_iaxa(Fv,1); nz = sf_n(az); dz = sf_d(az);
31 ax = sf_iaxa(Fv,2); nx = sf_n(ax); dx = sf_d(ax);
32
33 sf_oaxa(Fo,az,1);
34 sf_oaxa(Fo,ax,2);
35 sf_oaxa(Fo,at,3);
36
37 dt2 = dt*dt;
38 idz = 1/(dz*dz);
2.2. C PROGRAM 15

39 idx = 1/(dx*dx);
40
41 /* read wavelet, velocity & reflectivity */
42 ww = sf_floatalloc(nt); sf_floatread(ww ,nt ,Fw);
43 vv = sf_floatalloc2(nz,nx); sf_floatread(vv[0],nz*nx,Fv);
44 rr = sf_floatalloc2(nz,nx); sf_floatread(rr[0],nz*nx,Fr);
45
46 /* allocate temporary arrays */
47 um = sf_floatalloc2(nz,nx);
48 uo = sf_floatalloc2(nz,nx);
49 up = sf_floatalloc2(nz,nx);
50 ud = sf_floatalloc2(nz,nx);
51
52 for (iz=0; iz<nz; iz++) {
53 for (ix=0; ix<nx; ix++) {
54 um[ix][iz]=0;
55 uo[ix][iz]=0;
56 up[ix][iz]=0;
57 ud[ix][iz]=0;
58 }
59 }
60
61 /* MAIN LOOP */
62 if(verb) fprintf(stderr,"\n");
63 for (it=0; it<nt; it++) {
64 if(verb) fprintf(stderr,"\b\b\b\b\b%d",it);
65
66 /* 4th order laplacian */
67 for (iz=2; iz<nz-2; iz++) {
68 for (ix=2; ix<nx-2; ix++) {
69 ud[ix][iz] =
70 c0* uo[ix ][iz ] * (idx+idz) +
71 c1*(uo[ix-1][iz ] + uo[ix+1][iz ])*idx +
72 c2*(uo[ix-2][iz ] + uo[ix+2][iz ])*idx +
73 c1*(uo[ix ][iz-1] + uo[ix ][iz+1])*idz +
74 c2*(uo[ix ][iz-2] + uo[ix ][iz+2])*idz;
75 }
76 }
77
78 /* inject wavelet */
79 for (iz=0; iz<nz; iz++) {
16 CHAPTER 2. AN EXAMPLE: FINITE-DIFFERENCE MODELING

80 for (ix=0; ix<nx; ix++) {

81 ud[ix][iz] -= ww[it] * rr[ix][iz];
82 }
83 }
84
85 /* scale by velocity */
86 for (iz=0; iz<nz; iz++) {
87 for (ix=0; ix<nx; ix++) {
88 ud[ix][iz] *= vv[ix][iz]*vv[ix][iz];
89 }
90 }
91
92 /* time step */
93 for (iz=0; iz<nz; iz++) {
94 for (ix=0; ix<nx; ix++) {
95 up[ix][iz] = 2*uo[ix][iz]
96 - um[ix][iz]
97 + ud[ix][iz] * dt2;
98
99 um[ix][iz] = uo[ix][iz];
100 uo[ix][iz] = up[ix][iz];
101 }
102 }
103
104 /* write wavefield to output */
105 sf_floatwrite(uo[0],nz*nx,Fo);
106 }
107 if(verb) fprintf(stderr,"\n");
108 sf_close()
109 exit(0);
110 }

2.3 Explanation of the code

2-4: 2 #include <rsf.h>

3
4 int main(int argc, char* argv[])
Line 2 is a preprocessor directive to include the rsf.h header file which contains the
RSF library functions.
2.3. EXPLANATION OF THE CODE 17

Line 4 has parameters in the main function. This is to enable the program to take
command line arguments. char* argv[] defines the pointer to the array of type
char and int argc is the length of that array.

7: 7 float c0=-30./12.,c1=+16./12.,c2=- 1./12.;

As was mentioned earlier, the Laplacian is being evaluated with an accuracy of up to
the fourth order. These coefficients arise as a result of using five terms in the discrete
form of the Laplacian.

9-14: 9 bool verb; /* verbose flag */

10 sf_file Fw=NULL,Fv=NULL,Fr=NULL,Fo=NULL; /* I/O files */
11 sf_axis at,az,ax; /* cube axes */
12 int it,iz,ix; /* index variables */
13 int nt,nz,nx;
14 float dt,dz,dx,idx,idz,dt2;
Line 9 defines a variable verb of type bool. This variable will be used in the program
to check for verbosity flag. Lines 10-11 define the variables of the abstract data type
provided by the RSF API. These will be used to store the input and output files.
Lines 12-14 are the variables of integer and float type defined to be used as running
variables (it, iz, ix) for the main loop, length of the axes (nt, nz, nx), the sampling
of the axes (dt, dx, dz) and the squares and inverse squares of the samples (dt2, idz,
idx).

16-17: 16 float ww,vv,rr; / I/O arrays*/

17 float **um,**uo,**up,**ud;/* tmp arrays */

Lines 16-17 define pointers to the arrays, which will be used for input (*ww , **vv
, **rr) and for temporary storage (**um,**uo,**up,**ud).

19-20: 19 sf_init(argc,argv);
20 if(! sf_getbool("verb",&verb)) verb=0;
Line 19 initializes the symbol tables used to store the argument from the command
line.
Line 20 tests the verbosity flag specified in the command line arguments. If the
verbosity flag in the command line is set to n, the variable verb (of type bool) is set
to zero. This would allow the verbose output to be printed only if the user set the
verbosity flag to y in the command line.

22-26: 22 /* setup I/O files */

23 Fw = sf_input ("in" );
24 Fo = sf_output("out");
18 CHAPTER 2. AN EXAMPLE: FINITE-DIFFERENCE MODELING

25 Fv = sf_input ("vel");
26 Fr = sf_input ("ref");
In these lines we use the sf input (see p. 80) and sf output (see p. 80) functions
of the RSF API. These functions take a string as argument and return a variable of
type sf file, we had already defined this type of variables earlier in the program.
28-32: 28 /* Read/Write axes */
29 at = sf_iaxa(Fw,1); nt = sf_n(at); dt = sf_d(at);
30 az = sf_iaxa(Fv,1); nz = sf_n(az); dz = sf_d(az);
31 ax = sf_iaxa(Fv,2); nx = sf_n(ax); dx = sf_d(ax);
Here we input axes (at, az, ax) using sf iaxa (p. 348 of the RSF API. sf iaxa
accepts a variables of type sf file (RSF API) and an integer. The first argument
in sf iaxa is the input file and the second is the axis which we want to input. In the
second column we use sf n (p. 350)from RSF API to get the lengths of the respective
axes.
In the third column we use sf d (p. 351) of the RSF API to get the sampling interval
of the respective axes.
33-35: 33 sf_oaxa(Fo,az,1);
34 sf_oaxa(Fo,ax,2);
35 sf_oaxa(Fo,at,3);
Here we output axes (at, az, ax) using sf oaxa (p. 349) of the RSF API. sf oaxa
accepts variables of type sf file (RSF API), sf axis (RSF API) and an integer.
First argument is the output file, second argument is the name of the axis which we
want to output and the third is the number of the axis in the output file (n1 is the
fastest axis).
37-39: 37 dt2 = dt*dt;
38 idz = 1/(dz*dz);
39 idx = 1/(dx*dx);
These lines define the square of the time sampling interval(dt2) and the inverse
squares of the sampling interval of the spatial axes.
41-44: 41 /* read wavelet, velocity & reflectivity */
42 ww = sf_floatalloc(nt); sf_floatread(ww ,nt ,Fw);
43 vv = sf_floatalloc2(nz,nx); sf_floatread(vv[0],nz*nx,Fv);
44 rr = sf_floatalloc2(nz,nx); sf_floatread(rr[0],nz*nx,Fr);
In the first column we allocate the memory required to hold the input wavelet, veloc-
ity and reflectivity. This is done using sf floatalloc (p. 36) and sf floatalloc2
(p. 42) of the RSF API. sf floatalloc takes integers as arguments and from these in-
tegers it calculates an allocates a block of memory of appropriate size. sf floatalloc2
2.3. EXPLANATION OF THE CODE 19

is the same as sf floatalloc except for the fact that the former allocates an array
of two dimensions, size of the memory block assigned in this case is the product of
the two integers given as arguments (e.g. nz*nx in this case).
Then sf floatread (p. 109) of the RSF API is used to read the data from the
files into the allocated memory blocks (arrays). The sf floatread takes the arrays,
integers and files as arguments and returns arrays filled with the data from the files.

46-50: 46 /* allocate temporary arrays */

47 um = sf_floatalloc2(nz,nx);
48 uo = sf_floatalloc2(nz,nx);
49 up = sf_floatalloc2(nz,nx);
50 ud = sf_floatalloc2(nz,nx);
Just like the memory blocks were allocated for input files to be read in to, we now
allocate memory for the temporary arrays which will be used just for the calculation,
using sf floatalloc2 (p. 42).

52-59: 52 for (iz=0; iz<nz; iz++) {

53 for (ix=0; ix<nx; ix++) {
54 um[ix][iz]=0;
55 uo[ix][iz]=0;
56 up[ix][iz]=0;
57 ud[ix][iz]=0;
58 }
59 }
Lines 52-59 initialize the temporary arrays by assigning 0 to each element of every
array.

61-64: 61 /* MAIN LOOP */

62 if(verb) fprintf(stderr,"\n");
63 for (it=0; it<nt; it++) {
64 if(verb) fprintf(stderr,"\b\b\b\b\b%d",it);
Now the main loop starts. The if condition in line 61 prints the message specified
in the fprintf argument. The stderr is a stream in C which is used to direct the
output to the screen. In this case the input is just an escape sequence
n, which will bring the cursor to the next line if the user opted y or 1 to verbose flag
in the command line (verb=y of verb=1).
Then the loop over time starts. Right after the for statement (within the body of
the loop) there is another if condition like the first one but this time it prints the the
current value of it. This has escape sequence occurring several times. This is when
¯
the loop starts the value of it which is 0, is printed on the screen, when the loop
20 CHAPTER 2. AN EXAMPLE: FINITE-DIFFERENCE MODELING

returns to the start the new value of it is 1, so

b (backspace) removes the previous value 0, which is already on the screen, and puts
1 instead.
66-76: 66 /* 4th order laplacian */
67 for (iz=2; iz<nz-2; iz++) {
68 for (ix=2; ix<nx-2; ix++) {
69 ud[ix][iz] =
70 c0* uo[ix ][iz ] * (idx+idz) +
71 c1*(uo[ix-1][iz ] + uo[ix+1][iz ])*idx +
72 c2*(uo[ix-2][iz ] + uo[ix+2][iz ])*idx +
73 c1*(uo[ix ][iz-1] + uo[ix ][iz+1])*idz +
74 c2*(uo[ix ][iz-2] + uo[ix ][iz+2])*idz;
75 }
76 }
This is the calculation for the fourth order laplacian. By the term “4th order” we
mean the order of the approximation not the order of the PDE itself which of course
is a second order PDE. A second order partial derivative discretized to second order
approximation is written as:
∂2U Ui+1 + 2Ui + Ui−1
2
=
∂x ∆x2
This is the central difference formula for the second order partial derivative with
pivot at i−th value of U .Similarly for the z direction we have:
∂2U Ui+1 + 2Ui + Ui−1
2
=
∂z ∆z 2
By adding these two we get the central difference formula accurate to the second
order for the Laplacian. But we are using a central difference accurate up to the
fourth order so for that we have:
∂2U

1 1 16 30 16 1
= − Ui+2 + Ui+1 − Ui + Ui−i − Ui−2
∂x2 ∆x2 12 12 12 12 12

By writing down a similar equation for z and adding the two we get the fourth order
approximation of the Laplacian or as we refer to it here “4th order laplacian”.
Now returning back to the code, the first line is the start of the loop in the z direction.
Within the body of the z loop there is another loop which runs through all the values
of x for one value of z. The second line is start of the for-loop for the x direction.
Then in the body of the loop for x direction we use the 2 × 2 arrays which we defined
earlier. This is just the equation of the Laplacian accurate up to the fourth order, as
2.3. EXPLANATION OF THE CODE 21

discussed above, with the common coefficients factored out. Note that the loops for
x and z start two units after 0 and end two units before nx and nz. This is because
to evaluate the Laplacian at a particular point (x, z) the farthest values which we
are using are two units behind and two units ahead of the current point (x, z) if we
include the points iz=0,1 ; iz=nz-1, nz and ix=0,1;ix=nx-1,nx we will run out
of bounds. To fill these we will need a boundary condition which we will get from
the next loop for inserting the wavelet.

78-83: 78 /* inject wavelet */

79 for (iz=0; iz<nz; iz++) {
80 for (ix=0; ix<nx; ix++) {
81 ud[ix][iz] -= ww[it] * rr[ix][iz];
82 }
83 }
These lines insert the wavelet, which means evaluating the expression ∆U −f (t). ∆U
was already calculated in the previous loop and is stored as the array ud. ww is the
array of the wavelet but before subtracting it form the Laplacian (ud) we multiply
the wavelet amplitude at current time with the reflectivity at every point in space
(x, z). This amounts to an initial condition:

f (x, z, 0) = g(x, z) = ww(0)rr(x, z),

and thus serves the purpose of filling the values at ix,iz=0 and ix-2,ix-1=0 and
iz-2,iz-1=0.
But the source wavelet is not an ideal impulse so it has amplitudes at future times so
for each time the wavelet will be multiplied by the reflectivity at every point (x, z).
Why multiply the wavelet with reflectivity? Well, this model assumes a hypothetical
situation that the source was set off at each and every point in space (x, z) under
consideration and scaled by the reflectivity at that point (x, z). What this means is
that the source was set off at all the points where there is a change in the acoustic
impedance (because reflectivity is the ratio of the difference and sum of the acoustic
impedances across an interface).

85-90: 85 /* scale by velocity */

86 for (iz=0; iz<nz; iz++) {
87 for (ix=0; ix<nx; ix++) {
88 ud[ix][iz] *= vv[ix][iz]*vv[ix][iz];
89 }
90 }
Here we just multiply ∆U − f (t) by the velocity, that is, we evaluate (∆U − f (t))v 2
22 CHAPTER 2. AN EXAMPLE: FINITE-DIFFERENCE MODELING

92-102 92 /* time step */

93 for (iz=0; iz<nz; iz++) {
94 for (ix=0; ix<nx; ix++) {
95 up[ix][iz] = 2*uo[ix][iz]
96 - um[ix][iz]
97 + ud[ix][iz] * dt2;
98
99 um[ix][iz] = uo[ix][iz];
100 uo[ix][iz] = up[ix][iz];
101 }
102 }
Here we calculate the time step, that is,

Ui+1 = [∆U − f (t)]v 2 ∆t2 + 2Ui − Ui−1 .

The first for-loop is for the z direction and within the body of this loop is another
for-loop for the x direction. up is the array which holds the amplitude of the wave at
the current time in the time loop. uo is the array which contains the amplitude at a
time one unit before the current time and the array um holds the amplitude two units
before. ud is the array we calculated earlier in the program, now it gets multiplied
by ∆t2 (dt2) and included in the final equation. This completes the calculation for
one value of it. Now the arrays need to be updated to represent the next time step.
This is done in the last two: The first one says Ui−1 → Ui and the second one says
Ui → Ui+1 , that is, the array um is updated by uo and then the array uo itself gets
updated by up.

104-106: 104 /* write wavefield to output */

105 sf_floatwrite(uo[0],nz*nx,Fo);
106 }
After the calculations for one time step are complete we write the array uo (remember
that uo was made equal to up, which is the current time step, in the previous line).
To write the array in the output file we use sf floatwrite (p. 109) exactly the same
way we used sf floatread to read in from the input files, only difference is that the
array given as the argument is written into the file given in the last argument. The
bracket close is for the time loop, after this the time loop will start all over again for
the next time value.

107-109: 107 if(verb) fprintf(stderr,"\n");

108 sf_close()
109 exit(0);
110 }
2.3. EXPLANATION OF THE CODE 23

The first line puts the cursor in the new line on the screen after the time loop has
run through all the time values.
The second line uses sf close (p. 113) from RSF API to remove the temporary files.
The third line uses the exit() function in C language to close the streams and
return the control to the host environment. The 0 in the argument indicates normal
termination of the program. The last bracket closes the main function.
24 CHAPTER 2. AN EXAMPLE: FINITE-DIFFERENCE MODELING
Chapter 3

Data types

3.1 Data types

This chapter contains the descriptions of the data types used in the RSF API.

3.1.1 Complex numbers and FFT

This section lists the data types for the complex numbers and FFT.

kiss fft scalar

This is a data type, which defines a scalar real value for the data type kiss fft cpx for
complex numbers. It can be either of type short or float. Default is float.

kiss fft cpx

This is a data type (a C structure), which defines a complex number. It has the real and
imaginary parts of the complex numbers defined to be of type kiss fft scalar.

kiss fft cfg

This is an object of type kiss fft state (which is a C data structure).

25
26 CHAPTER 3. DATA TYPES

kiss fft state

The kiss fft state is a data type which defines the required variables for the Fourier
transform and allocates the required space. For example the variable inverse of type int
indicates whether the transform needs to be an inverse or forward.

kiss fftr cfg

This is an object of type kiss fftr state (which is a C data structure).

kiss fftr state

The kiss fftr state is a data type which defines the required variables for the Fourier
transform and allocates the required space. This has the same purpose as kiss fft state
but for the Fourier transform of the real signals.

sf complex

This is an object of type kiss fft cfg (which is an object of C data structure).

sf double complex

This is a C data structure for complex numbers. It uses the type double for the real and
imaginary parts of the complex numbers.

3.1.2 Files

This section lists the data types used to define the .rsf file structure.

sf file

This is an object of type sf File. sf File is a data structure which defines the variables
required for creating a .rsf file in Madagascar. It is defined in file.c.
3.1. DATA TYPES 27

sf datatype

This is a C enumeration, which means that it contains new data types, which are not the
fundamental types like int, float, sf file etc. This data type is used in sf File data
structure to set the type of a .rsf file, for example SF CHAR, SF INT etc. It is defined
in file.c.

sf dataform

This is a C enumeration, which means that it contains new data types, which are not the
fundamental types like int, float, sf file etc. This data type is used in sf File data
structure to set the format of an .rsf file, for example SF ASCII, SF XDR and SF NATIVE.
It is defined in file.c.

3.1.3 Operators

This section lists the data types used to define linear operators.

sf triangle

This is an object of an abstract C datatype type sf Triangle. The sf triangle data type
defines the variables of relevant types to store information about the triangle smoothing
filter. It is defined in triangle.c.

sf operator

This is a C data type of type void. It is also a pointer to a function which takes the
input parameters precisely as (bool, bool, int, int, float*, float*). It is defined
in solver.h.

sf solverstep

This is a C data type of type void. It is also a pointer to a function which takes the in-
put parameters precisely as (bool, bool, int, int, float*, const float*, float*,
const float*). It is defined in solver.h.
28 CHAPTER 3. DATA TYPES

sf weight

This is a C data type of type void. It is also a pointer to a function which takes the
input parameters precisely as (int, int, const sf complex*, float*). It is defined in
solver.h.

sf coperator

This is a C data type of type void. It is also a pointer to a function which takes the input
parameters precisely as (bool bool, int, int, sf complex*, sf complex*). It works
just like sf operator but does it for complex numbers. It is defined in solver.h.

sf csolverstep

This is a C data type of type void. It is also a pointer to a function which takes the input pa-
rameters precisely as (bool, bool, int, int, sf complex*, const sf complex*, sf complex*,
const sf complex*). It works just like sf solverstep but does it for complex numbers.
It is defined in solver.h.

sf cweight

This is a C data type of type void. It is also a pointer to a function which takes the
input parameters precisely as (int, int, const sf complex*, float*). It works just
like sf weight but does it for the complex numbers. It is defined in solver.h.

sf eno

This is a C data structure, which contains the required variables for 1D ENO (Essentially
Non Oscillatory) interpolation. It is defined in eno.c.

sf eno2

This is a C data structure, which contains the required variables for 2D ENO (Essentially
Non Oscillatory) interpolation. It is defined in eno2.c.
3.1. DATA TYPES 29

sf bands

This is a C data structure, which contains the required variables for storing a banded
matrix. It is defined in banded.c.

3.1.4 Geometry

This section lists the data types used to define the geometry of the seismic data.

sf axa

This is a C data structure which contains the variables of type int and float to store the
length origin and sampling of the axis. It is defined in axa.c.

pt2d

This is a C data structure which contains the variables of type double and float to store
the location and value of a 2D point. It is defined in point.c.

pt3d

This is a C data structure which contains the variables of type double and float to store
the location and value of a 3D point. It is defined in point.c.

vc2d

This is a C data structure which contains the variables of type double to store the compo-
nents of a 2D vector. It is defined in vector.c.

vc3d

This is a C data structure which contains the variables of type double to store the compo-
nents of a 3D vector. It is defined in vector.c.

3.1.5 Lists

This section describes the data types used to create and operate on lists.
30 CHAPTER 3. DATA TYPES

sf list

This is a C data structure, which contains the required variables for storing the information
about the list, for example . It uses another C data structure Entry. It is defined in llist.c.

Entry

This is a C data structure, which contains the required variables for storing the elements
and moving the pointer in the list. It is defined in llist.c.

3.1.6 sys/types.h

This section describes some of the data types used from the C header file sys/types.h.

off t

This is a data type defined in the sys/types.h header file (of fundamental type unsigned
long) and is used to measure the file offset in bytes from the beginning of the file. It is
defined as a signed, 32-bit integer, but if the programming environment enables large files
off t is defined to be a signed, 64-bit integer.

size t

This is a data type defined in the sys/types.h header (of fundamental type unsigned
int) and is used to measure the file size in units of character. It is used to hold the result
of the sizeof operator in C, for example sizeof(int)=4, sizeof(char)=1, etc.
Chapter 4

Preparing for input

4.1 Convenience allocation programs (alloc.c)

4.1.1 sf alloc

Checks whether the requested size for memory allocation is valid and if so it returns a
pointer of void type, pointing to the allocated memory block. It takes the ’number of
elements’ and ’size of one element’ as input arguments. Both arguments have to be of the
of type size t.

Call

sf_alloc (n, size);

Definition

void sf_alloc (size_t n / number of elements */,

size_t size /* size of one element */)
/*< output-checking allocation >*/
{
...
}

31
32 CHAPTER 4. PREPARING FOR INPUT

Input parameters

n number of elements (size t).

size size of each element, for example sizeof(float) (size t).

Output

ptr a void pointer pointing to the allocated block of memory.

4.1.2 sf realloc

The same as sf alloc but it allocates new memory such that it appends the block previ-
ously assigned by sf alloc. It takes three parameters, first one is a void pointer to the old
memory block. Second and third parameters are the same as for sf alloc but are used
to determine the new block, which is to be appended. sf realloc returns a void pointer
pointing to the whole memory block (new + old).

Call

sf_realloc (ptr, n, size);

Definition

void sf_realloc (void ptr /* previous data */,

size_t n /* number of elements */,
size_t size /* size of one element */)
/*< output-checking reallocation >*/
{
...
}

Input parameters

ptr pointer to the previously assigned memory block.

n number of elements (size t).

Output

ptr a void pointer pointing to the allocated block of memory.

4.1.10 sf complexalloc2

Allocates a 2D array in the memory for the sf complex type. It works just like sf complexalloc
but does it for two dimensions. This is done by making a pointer point to another pointer,
38 CHAPTER 4. PREPARING FOR INPUT

which in turn points to a particular column (or row) of an allocated 2D block of memory
of size n1*n2. n1 is the fastest dimension.

Call

ptr = sf_complexalloc2 (n1, n2);

Definition

sf_complex **sf_complexalloc2 (size_t n1 /* fast dimension */,

size_t n2 /* slow dimension */)
/*< complex 2-D allocation, out[0] points to a contiguous array >*/
{
...
}

Input parameters

n1 number of elements in the fastest dimension (size t).

n2 number of elements in the slower dimension (size t).

Output

ptr a void pointer pointing to the allocated block of memory.

4.1.11 sf complexalloc3

Allocates a 3D array in the memory for the sf complex type. It works just like sf complexalloc2
but does it for three dimensions. This is done by extending the same argument as
for sf complexalloc2 this time making a pointer such that Pointer2 -> Pointer1 ->
Pointer. n1 is the fastest dimension.

Call

ptr = sf_complexalloc3 (n1, n2, n3);

4.1. CONVENIENCE ALLOCATION PROGRAMS (ALLOC.C) 39

Definition

sf_complex ***sf_complexalloc3 (size_t n1 /* fast dimension */,

size_t n2 /* slower dimension */,
size_t n3 /* slowest dimension */)
/*< complex 3-D allocation, out[0][0] points to a contiguous array >*/
{
...
}

Input parameters

n1 number of elements in the fastest dimension (size t).

n2 number of elements in the slower dimension (size t).
n3 number of elements in the slower dimension (size t).

Output

ptr a void pointer pointing to the allocated block of memory.

4.1.12 sf complexalloc4

Allocates a 4D array in the memory for the sf complex type. It works just like sf complexalloc2
but does it for four dimensions. This is done by extending the same argument as for
sf complexalloc2 but this time making a pointer such that Pointer3 -> Pointer2 ->
Pointer1 -> Pointer. n1 is the fastest dimension.

4.1.15 sf boolalloc3

Allocates a 3D array in the memory for the bool type. It works just like sf boolalloc2
but does it for three dimensions. This is done by extending the same argument as for
42 CHAPTER 4. PREPARING FOR INPUT

sf boolalloc2 but this time making a pointer such that Pointer2 -> Pointer1 ->
Pointer. n1 is the fastest dimension.

Call

ptr = sf_boolalloc3 (n1, n2, n3);

Definition

bool ***sf_boolalloc3 (size_t n1 /* fast dimension */,

size_t n2 /* slower dimension */,
size_t n3 /* slowest dimension */)
/*< bool 3-D allocation, out[0][0] points to a contiguous array >*/
{
...
}

Input parameters

n1 number of elements in the fastest dimension (size t).

n2 number of elements in the slower dimension (size t).
n3 number of elements in the slower dimension (size t).

Output

ptr a void pointer pointing to the allocated block of memory.

4.1.16 sf floatalloc2

Allocates a 2D array in the memory for the float type. It works just like sf floatalloc
but does it for two dimensions. This is done by making a pointer point to another pointer,
which in turn points to a particular column (or row) of an allocated 2D block of memory
of size n1*n2. n1 is the fastest dimension.

Call

ptr = sf_floatalloc2 (n1, n2);

4.1. CONVENIENCE ALLOCATION PROGRAMS (ALLOC.C) 43

Definition

float **sf_floatalloc2 (size_t n1 /* fast dimension */,

size_t n2 /* slow dimension */)
/*< float 2-D allocation, out[0] points to a contiguous array >*/
{
...
}

Input parameters

n1 number of elements in the fastest dimension (size t).

n2 number of elements in the slower dimension (size t).

Output

ptr a void pointer pointing to the allocated block of memory.

4.1.17 sf floatalloc3

Allocates a 3D array in the memory for the float type. It works just like sf floatalloc2
but does it for three dimensions. This is done by extending the same argument as for
sf floatalloc2 but this time making a pointer such that Pointer2 -> Pointer1 ->
Pointer. n1 is the fastest dimension.

Call

ptr = sf_floatalloc3 (n1, n2, n3);

Definition

float ***sf_floatalloc3 (size_t n1 /* fast dimension */,

size_t n2 /* slower dimension */,
size_t n3 /* slowest dimension */)
/*< float 3-D allocation, out[0][0] points to a contiguous array >*/
{
...
}
44 CHAPTER 4. PREPARING FOR INPUT

Input parameters

n1 number of elements in the fastest dimension (size t).

n2 number of elements in the slower dimension (size t).
n3 number of elements in the slower dimension (size t).

Output

ptr a void pointer pointing to the allocated block of memory.

4.1.18 sf floatalloc4

Allocates a 4D array in the memory for the float type. It works just like sf floatalloc2
but does it for four dimensions. This is done by extending the same argument as for
sf floatalloc2 but this time making a pointer such that Pointer3 -> Pointer2 ->
Pointer1 -> Pointer. n1 is the fastest dimension.

Call

ptr = sf_floatalloc4 (n1, n2, n3, n4);

Definition

float ****sf_floatalloc4 (size_t n1 /* fast dimension */,

size_t n2 /* slower dimension */,
size_t n3 /* slower dimension */,
size_t n4 /* slowest dimension */)
/*< float 4-D allocation, out[0][0][0] points to a contiguous array >*/
{
...
}

Input parameters

n1 number of elements in the fastest dimension (size t).

n2 number of elements in the slower dimension (size t).
n3 number of elements in the slower dimension (size t).
4.1. CONVENIENCE ALLOCATION PROGRAMS (ALLOC.C) 45

n4 number of elements in the slower dimension (size t).

Output

ptr a void pointer pointing to the allocated block of memory.

4.1.19 sf floatalloc5

Allocates a 5D array in the memory for the float type. It works just like sf floatalloc2
but does it for four dimensions. This is done by extending the same argument as for
sf floatalloc2 but this time making a pointer such that Pointer4 -> Pointer3 ->
Pointer2 -> Pointer1 -> Pointer. n1 is the fastest dimension.

Call

ptr = sf_floatalloc5 (n1, n2, n3, n4, n5);

Definition

float *****sf_floatalloc5 (size_t n1 /* fast dimension */,

size_t n2 /* slower dimension */,
size_t n3 /* slower dimension */,
size_t n4 /* slower dimension */,
size_t n5 /* slowest dimension */)
/*< float 5-D allocation, out[0][0][0][0] points to a contiguous array >*/
{
...
}

Input parameters

n1 number of elements in the fastest dimension (size t).

n2 number of elements in the slower dimension (size t).
n3 number of elements in the slower dimension (size t).
n4 number of elements in the slower dimension (size t).
n5 number of elements in the slower dimension (size t).
46 CHAPTER 4. PREPARING FOR INPUT

Output

ptr a void pointer pointing to the allocated block of memory.

4.1.20 sf floatalloc6

Allocates a 6D array in the memory for the float type. It works just like sf floatalloc2
but does it for four dimensions. This is done by extending the same argument as for
sf floatalloc2 but this time making a pointer such that Pointer5 -> Pointer4 ->
Pointer3 -> Pointer2 -> Pointer1 -> Pointer. n1 is the fastest dimension.

Call

ptr = sf_floatalloc6 (n1, n2, n3, n4, n5, n6);

Definition

float ******sf_floatalloc6 (size_t n1 /* fast dimension */,

size_t n2 /* slower dimension */,
size_t n3 /* slower dimension */,
size_t n4 /* slower dimension */,
size_t n5 /* slower dimension */,
size_t n6 /* slowest dimension */)
/*< float 6-D allocation, out[0][0][0][0][0] points to a contiguous array >*/
{
...
}

Input parameters

n1 number of elements in the fastest dimension (size t).

Output

ptr a void pointer pointing to the allocated block of memory.

4.1.21 sf intalloc2

Allocates a 2D array in the memory for the float type. It works just like sf intalloc but
does it for two dimensions. This is done by making a pointer point to another pointer,
which in turn points to a particular column (or row) of an allocated 2D block of memory
of size n1*n2. n1 is the fastest dimension.

Call

ptr = sf_intalloc2 (n1, n2);

Definition

int **sf_intalloc2 (size_t n1 /* fast dimension */,

size_t n2 /* slow dimension */)
/*< float 2-D allocation, out[0] points to a contiguous array >*/
{
...
}

Input parameters

n1 number of elements in the fastest dimension (size t).

n2 number of elements in the slower dimension (size t).

Output

ptr a void pointer pointing to the allocated block of memory.

4.1.22 sf intalloc3

Allocates a 3D array in the memory for the float type. It works just like sf intalloc2
but does it for three dimensions. This is done by extending the same argument as for
48 CHAPTER 4. PREPARING FOR INPUT

sf intalloc2 this time making a pointer such that Pointer2 -> Pointer1 -> Pointer.
n1 is the fastest dimension.

Call

ptr = sf_intalloc3 (n1, n2, n3);

Definition

int ***sf_intalloc3 (size_t n1 /* fast dimension */,

size_t n2 /* slower dimension */,
size_t n3 /* slowest dimension */)
/*< int 3-D allocation, out[0][0] points to a contiguous array >*/
{
...
}

Input parameters

n1 number of elements in the fastest dimension (size t).

n2 number of elements in the slower dimension (size t).
n3 number of elements in the slower dimension (size t).

Output

ptr a void pointer pointing to the allocated block of memory.

4.1.23 sf intalloc4

Allocates a 4D array in the memory for the float type. It works just like sf intalloc2
but does it for four dimensions. This is done by extending the same argument as for
sf intalloc2 but this time making a pointer such that Pointer3 -> Pointer2 -> Pointer1
-> Pointer. n1 is the fastest dimension.

Call

ptr = sf_intalloc4 (n1, n2, n3, n4);

4.1. CONVENIENCE ALLOCATION PROGRAMS (ALLOC.C) 49

Definition

int ****sf_intalloc4 (size_t n1 /* fast dimension */,

size_t n2 /* slower dimension */,
size_t n3 /* slower dimension */,
size_t n4 /* slowest dimension */ )
/*< int 4-D allocation, out[0][0][0] points to a contiguous array >*/
{
...
}

Input parameters

n1 number of elements in the fastest dimension (size t).

n2 number of elements in the slower dimension (size t).
n3 number of elements in the slower dimension (size t).
n4 number of elements in the slower dimension (size t).

Output

ptr a void pointer pointing to the allocated block of memory.

4.1.24 sf charalloc2

Allocates a 2D array in the memory for the float type. It works just like sf charalloc
but does it for two dimensions. This is done by making a pointer point to another pointer,
which in turn points to a particular column (or row) of an allocated 2D block of memory
of size n1*n2. n1 is the fastest dimension.

Call

ptr = sf_charalloc2 (n1, n2);

Definition

char **sf_charalloc2 (size_t n1 /* fast dimension */,

size_t n2 /* slow dimension */)
50 CHAPTER 4. PREPARING FOR INPUT

/< char 2-D allocation, out[0] points to a contiguous array >/

{
...
}

Input parameters

n1 number of elements in the fastest dimension (size t).

n2 number of elements in the slower dimension (size t).

Output

ptr a void pointer pointing to the allocated block of memory.

4.1.25 sf uncharalloc2

Allocates a 2D array in the memory for the float type. It works just like sf uncharalloc
but does it for two dimensions. This is done by making a pointer point to another pointer,
which in turn points to a particular column (or row) of an allocated 2D block of memory
of size n1*n2. n1 is the fastest dimension.

Call

ptr = sf_ucharalloc2 (n1, n2);

Definition

unsigned char **sf_ucharalloc2 (size_t n1 /* fast dimension */,

size_t n2 /* slow dimension */)
/*< unsigned char 2-D allocation, out[0] points to a contiguous array >*/
{
...
}

Input parameters

n1 number of elements in the fastest dimension (size t).

4.1. CONVENIENCE ALLOCATION PROGRAMS (ALLOC.C) 51

n2 number of elements in the slower dimension (size t).

Output

ptr a void pointer pointing to the allocated block of memory.

4.1.26 sf uncharalloc3

Allocates a 3D array in the memory for the float type. It works just like sf uncharalloc2
but does it for three dimensions. This is done by extending the same argument as for
sf uncharalloc2 but this time making a pointer such that Pointer2 -> Pointer1 ->
Pointer. n1 is the fastest dimension.

Call

ptr = sf_ucharalloc3 (n1, n2, n3);

Definition

unsigned char ***sf_ucharalloc3 (size_t n1 /* fast dimension */,

size_t n2 /* slower dimension */,
size_t n3 /* slowest dimension */)
/*< unsigned char 3-D allocation, out[0][0] points to a contiguous array >*/
{
...
}

Input parameters

n1 number of elements in the fastest dimension (size t).

n2 number of elements in the slower dimension (size t).
n3 number of elements in the slower dimension (size t).

Output

ptr a void pointer pointing to the allocated block of memory.

52 CHAPTER 4. PREPARING FOR INPUT

4.2 Simbol Table for parameters (simtab.c)

4.2.1 sf simtab init

Creates a table to store the parameters input either from command line or a file. It takes
the required size (type int) of the table as input. The output is a pointer to the allocated
table and it is of the defined data type sf simtab.

call

table = sf_simtab_init(size);

Definition

sf_simtab sf_simtab_init(int size)

/*< Create simbol table. >*/
{
...
}

Input parameters

size size of the table to be allocated (int).

Output

table a pointer of type sf simtab pointing to the allocated block of memory for the
symbol table.

4.2.2 sf simtab close

Frees the allocated space for the table.

Call

sf_simtab_close(table);
4.2. SIMBOL TABLE FOR PARAMETERS (SIMTAB.C) 53

Definition

void sf_simtab_close(sf_simtab table)

/*< Free allocated memory >*/
{
...
}

Input parameters

table the table whose allocated memory has to be deleted. Must be of type sf simtab.

4.2.3 sf simtab enter

Enters a value in the table, which was created by sf simtab init. In the input it must
be told which table to enter the value in, this is the first input argument and is of type
sf simtab. The second and the third arguments are the pointers of const char* type.
The first one points to key, which would be the name of the argument from command line
or file. Second argument is the pointer to the value to be input.

Call

sf_simtab_enter(table, key, val);

Definition

void sf_simtab_enter(sf_simtab table, const char key, const char val)

/*< Add an entry key=val to the table >*/
{
...
}

success = sf_simtab_getfloats (table, key, par, n);

Call

success = sf_simtab_getstrings (table, key, par, n);

62 CHAPTER 4. PREPARING FOR INPUT

Definition

bool sf_simtab_getstrings (sf_simtab table, const char* key,

/*@out@*/ char **par,size_t n)
/*< extract a string array parameter from the table >*/
{
...
}

Input parameters

table the table from which the vale has to be extracted. Must be of type sf simtab.
key the name of the string array which has to be extracted (const char*).
par pointer to the pointer to array of integer type value variable where the extracted
value is to be copied.
n size of the array to be extracted. Must be of size t.

Output

success a boolean value. It is true, if the extraction was successful and false other-
wise.

4.2.15 sf simtab put

Writes a new key together with its value to the symbol table. The new entry must be in
the form key=val and must be of the const char* type, that is, this function must be
given a pointer to key=val. Since the type of the pointer is const char* this can be a
direct input from the command line and in that case the pointer will be acgv[n] where n
specifies the position in the command line.

Call

4.3.1 sf stdin

Checks whether there is an input in the command line, if not it returns a false. It reads
the first character in the file: if it is an EOF, false is returned and if not, then true is the
return value. It takes no input parameters and returns a boolean value.

Call

hasinp sf_stdin();
4.3. PARAMETER HANDLING (GETPAR.C) 65

Definition

bool sf_stdin(void)
/*< returns true if there is an input in stdin >*/
{
...
}

4.3.2 sf init

Initializes a parameter table which is created using sf simtab init. The input arguments
are same as used in the main function in c when there is some arguments are to be input
from the command line.

Input parameters

argc size of the table to be allocated (int).

Definition

char* sf_getuser (void)

/*< returns user name >*/
{
...
}

Output

user pointer to an array which contains the user name (char).

key the name of the entry which has to be extracted (const char*).
par pointer to the integer variable where the extracted value is to be copied.

Output

success a boolean value. It is true, if the extraction was successful and false other-
wise.

4.3.10 sf getlargeint

Extracts a large integer from the command line. If the extraction is successful, it returns
a true, otherwise a false. It uses sf simtab getlargeint.
70 CHAPTER 4. PREPARING FOR INPUT

Call

sf_getlargeint (key, par);

Definition

bool sf_getlargeint (const char* key,/@out@/ off_t* par)

/*< get a large int parameter from the command line >*/
{
...
}

Input parameters

key the name of the entry which has to be extracted (const char*).
par pointer to the large integer variable where the extracted value is to be copied. Must
be of type off t which is defined in the header <sys/types.h>.

Output

success a boolean value. It is true, if the extraction was successful and false other-
wise.

4.3.11 sf getints

Extracts an array of integer values from the command line. If the extraction is successful,
it returns a true, otherwise a false.

Call

success = sf_getints (key, par, n);

Definition

bool sf_getints (const char* key,/@out@/ int* par,size_t n)

/*< get an int array parameter (comma-separated) from the command line >*/
{
4.3. PARAMETER HANDLING (GETPAR.C) 71

...
}

Input parameters

key the name of the integer array which has to be extracted (const char*).
par pointer to the array of integer type value variable where the extracted value id to
be copied.
n size of the array to be extracted. Must be of size t.

Output

success a boolean value. It is true, if the extraction was successful and false other-
wise.

4.3.12 sf getfloat

Extracts a float value from the command line. If the extraction is successful, it returns a
true, otherwise a false.

Call

success = sf_getfloat (key, par);

Definition

bool sf_getfloat (const char* key,/@out@/ float* par)

/*< get a float parameter from the command line >*/
{
...
}

Input parameters

key the name of the entry which has to be extracted (const char*).
par pointer to the float type value variable where the extracted value is to be copied.
72 CHAPTER 4. PREPARING FOR INPUT

Output

success a boolean value. It is true, if the extraction was successful and false other-
wise.

4.3.13 sf getdouble

Extracts a double type value from the command line. If the extraction is successful, it
returns a true, otherwise a false.

Call

success = sf_getdouble (key, par);

Definition

bool sf_getdouble (const char* key,/@out@/ double* par)

/*< get a double parameter from the command line >*/
{
...
}

Input parameters

Output

success a boolean value. It is true, if the extraction was successful and false other-
wise.

4.3.14 sf getfloats

Extracts an array of float values from the command line. If the extraction is successful, it
returns a true, otherwise a false. It uses sf simtab getfloats.
4.3. PARAMETER HANDLING (GETPAR.C) 73

Call

success = sf_getfloats (key, n);

Definition

bool sf_getfloats (const char* key,/@out@/ float* par,size_t n)

/*< get a float array parameter from the command line >*/
{
...
}

Input parameters

key the name of the float array which has to be extracted (const char*).
par pointer to the array of float type value variable where the extracted value id to be
copied.
n size of the array to be extracted (size t).

Output

success a boolean value. It is true, if the extraction was successful and false other-
wise.

4.3.15 sf getstring

Extracts a string pointed by the input key from the command line. If the value is NULL
it will return NULL, otherwise it will allocate a new block of memory of char type and
copy the memory block from the table to the new block and return a pointer to the newly
allocated block of memory. It uses sf simtab getstring.

Call

string = sf_getstring (key);

74 CHAPTER 4. PREPARING FOR INPUT

Definition

char* sf_getstring (const char* key)

/*< get a string parameter from the command line >*/
{
...
}

Input parameters

key the name of the string which has to be extracted (const char*).

Output

string a pointer to allocated block of memory containing a string of characters.

4.3.16 sf getstrings

Extracts an array of strings from the command line. If the extraction is successful, it
returns a true, otherwise a false.

Call

success = sf_getstrings (key, par, n);

Definition

bool sf_getstrings (const char* key,/@out@/ char** par,size_t n)

/*< get a string array parameter from the command line >*/
{
...
}

sf_simtab sf_getpars (void)

/*< provide access to the parameter table >*/
{
...
}

Output

pars a pointer to the parameter table.

78 CHAPTER 4. PREPARING FOR INPUT
Chapter 5

Operations with RSF files

5.1 Main operations with RSF files (file.c)

5.1.1 sf file error

Sets an error on opening files. It sets the value of error (a static variable of type bool).
This variable is used in the sf input error as an if-condition.

Call

sf_file_error(err);

Definition

void sf_file_error(bool err)

/*< set error on opening files >*/
{
...
}

Input parameters

err value of type bool which is to be assigned to the static variable error.

79
80 CHAPTER 5. OPERATIONS WITH RSF FILES

5.1.2 sf error

Outputs an error message to the stderr (usually the screen) if the file cannot be opened.
The ’:’ after the format specifiers in the call to sf error ensures that any system errors
are also included in the output.

Call

sf_input_error(file, message, name);

Definition

static void sf_input_error(sf_file file, const char* message, const char* name)
{
...
}

Input parameters

file pointer to the input file structure (sf file).

message the error message to be output to stderr.
name name of the file which was to be opened.

5.1.3 sf input

Creates an input file structure and returns a pointer to that file structure. It will create
the symbol table, input parameters to the table and write them in a temporary file and
check for any errors in the input of the parameters. It will also set the format of the file
and then return a pointer to the file structure.

Call

file = sf_input(tag);
5.1. MAIN OPERATIONS WITH RSF FILES (FILE.C) 81

Definition

sf_file sf_input (/@null@/ const char* tag)

/*< Create an input file structure >*/
{
...
}

Input parameters

tag a tag for the input file (const char*).

Output

file a pointer to the input file structure.

5.1.4 sf output

Creates an output file structure and returns a pointer to that file structure. It will create
the symbol table, a header file and put the path of the data file in the header with the key
”in”.

Call

file = sf_output(tag);

Definition

sf_file sf_output (/@null@/ const char* tag)

/*< Create an output file structure.
---
Should do output after sf_input. >*/
{
...
}
82 CHAPTER 5. OPERATIONS WITH RSF FILES

Input parameters

tag a tag for the output file (const char*).

Output

file a pointer to the input file structure.

5.1.5 sf gettype

Returns the type of the file, e.g. SF INT, SF FLOAT, SF COMPLEX etc.

Call

type = sf_gettype (file);

Definition

sf_datatype sf_gettype (sf_file file)

/*< return file type >*/
{
...
}

Input parameters

file a pointer to the file structure whose type is required (sf file).

Output

file->type type of the file structure.

5.1.6 sf getform

Returns the file form, e.g. SF ASCII, SF XDR.

5.1. MAIN OPERATIONS WITH RSF FILES (FILE.C) 83

Call

form = sf_getform (file);

Definition

sf_dataform sf_getform (sf_file file)

/*< return file form >*/
{
...
}

Input parameters

file a pointer to the file structure whose type is required (sf file).

Output

file->form form of the file structure.

5.1.7 sf esize

Returns the size of the element type of the file, e.g. SF INT, SF FLOAT, SF COMPLEX etc.

Call

size = sf_esize(file);

Definition

size_t sf_esize(sf_file file)

/*< return element size >*/
{
...
}
84 CHAPTER 5. OPERATIONS WITH RSF FILES

Input parameters

/*< return buffer size for efficient I/O >*/
{
...
}

Input parameters

file a pointer to the file structure whose buffer size is required (sf file).

Output

bufsiz size of the buffer of the file structure.

86 CHAPTER 5. OPERATIONS WITH RSF FILES

5.1.11 sf setform

Sets the form of the file, i.e. SF ASCII, SF XDR, SF NATIVE.

Call

sf_setform (file, form);

Definition

void sf_setform (sf_file file, sf_dataform form)

/*< set file form >*/
{
...
}

Input parameters

file a pointer to the file structure whose form is to be set (sf file).
form the type to be set. Must be of type sf datatype, e.g. SF ASCII.

5.1.12 sf setformat

Sets the format of the file, e.g. SF INT, SF FLOAT, SF COMPLEX etc. Format is the combina-
tion of file form and its type, e.g. ASCII INT.

Call

sf_setformat (file, format);

Definition

void sf_setformat (sf_file file, const char* format)

/*< Set file format.
---
format has a form "form_type", i.e. native_float, ascii_int, etc.
>*/
5.1. MAIN OPERATIONS WITH RSF FILES (FILE.C) 87

{
...
}

Input parameters

file a pointer to the file structure whose format is to be set (sf file).
format the type to be set (const char*).

5.1.13 sf getfilename

Returns a boolean value (true or false), depending on whether it was able to find the
filename of an open file or not. The search is based on finding the file descriptor of an open
file, if it is found the return value is true, otherwise false. Once the file name is found
it is copied to the value pointed by the pointer filename which is given as input and is
already defined in the sf input.

Call

success = getfilename (fp, filename);

Definition

static bool getfilename (FILE* fp, char *filename)

/* Finds filename of an open file from the file descriptor.

Unix-specific and probably non-portable. */

{
...
}

Input parameters

fp a pointer to the file structure whose file name is required (FILE*).

filename pointer to the parameter on which the found file name is to be stored.
88 CHAPTER 5. OPERATIONS WITH RSF FILES

Output

success a boolean value which is true if the filename is found otherwise false.

Output

success a boolean value which is true if the filename is found otherwise false.

5.1.17 sf fileclose

Closes the file and frees any allocated space, like the temporary file and buffer.

Call

sf_fileclose (file);

Definition

void sf_fileclose (sf_file file)

/*< close a file and free allocated space >*/
{
...
}

Input parameters

file the file which is to be closed (sf file).

5.1.18 sf histint

Extracts an integer from the file. If the extraction is successful, it returns a true, otherwise
a false. It uses sf simtab getint.
5.1. MAIN OPERATIONS WITH RSF FILES (FILE.C) 91

Call

success = sf_histint (file, key, par);

Definition

bool sf_histint (sf_file file, const char* key,/@out@/ int* par)

/*< read an int parameter from file >*/
{
...
}

Input parameters

file file from which an integer is to be extracted (sf file).

key the name of the entry which has to be extracted (const char*).
par pointer to the integer variable where the extracted value is to be copied.

Output

success a boolean value. It is true, if the extraction was successful and false other-
wise.

5.1.19 sf histints

Extracts an array of integer values from the file. If the extraction is successful, it returns
a true, otherwise a false.

Call

success = sf_histints (file, key, par, n);

Definition

bool sf_histints (sf_file file, const char* key,/@out@/ int* par,size_t n)

/*< read an int array of size n parameter from file >*/
92 CHAPTER 5. OPERATIONS WITH RSF FILES

{
...
}

Input parameters

file file from which an integer array is to be extracted (sf file).

key the name of the integer array which has to be extracted (const char*).
par pointer to the array of integer type value variable where the extracted value is to
be copied.
n size of the array to be extracted. Must be of size t.

Output

success a boolean value. It is true, if the extraction was successful and false other-
wise.

5.1.20 sf histlargeint

Extracts a large integer from the file. If the extraction is successful, it returns a true,
otherwise a false. It uses sf simtab getlargeint.

Call

success = sf_histlargeint ( file, key, par);

Definition

bool sf_histlargeint (sf_file file, const char* key,/@out@/ off_t* par)

/*< read a sf_largeint parameter from file >*/
{
...
}
5.1. MAIN OPERATIONS WITH RSF FILES (FILE.C) 93

/*@out@*/ float* par, size_t n)
/*< read a float array of size n parameter from file >*/
{
...
}

Input parameters

file file from which a float type array is to be extracted (sf file).
key the name of the float array which has to be extracted (const char*).
par pointer to the array of float type value variable where the extracted value is to be
copied.
n size of the array to be extracted (size t).

5.1.24 sf histbool

Extracts a boolean value from the file. If the extraction is successful, it returns a true,
otherwise a false.

Call

success = sf_histbool(file, key, par);

96 CHAPTER 5. OPERATIONS WITH RSF FILES

Definition

bool sf_histbool (sf_file file, const char* key,/@out@/ bool* par)

/*< read a bool parameter from file >*/
{
...
}

Input parameters

file file from which a bool type value is to be extracted (sf file).
key the name of the entry which has to be extracted (const char*).
par pointer to the bool variable where the extracted value is to be copied.

Output

success a boolean value. It is true, if the extraction was successful and false other-
wise.

5.1.25 sf histtbools

Extracts an array of bool values from the file. If the extraction is successful, it returns a
true, otherwise a false.It uses sf simtab getbools.

Call

success = sf_histbools(file, key, par, n);

Definition

bool sf_histbools (sf_file file, const char* key,

/*@out@*/ bool* par, size_t n)
/*< read a bool array of size n parameter from file >*/
{
...
}
5.1. MAIN OPERATIONS WITH RSF FILES (FILE.C) 97

Input parameters

file file from which an array of bool value is to be extracted (sf file).
key the name of the bool array which has to be extracted (const char*).
par pointer to the array of bool type value variable where the extracted value is to be
copied.
n size of the array to be extracted. Must be of size t.

Output

success a boolean value. It is true, if the extraction was successful and false other-
wise.

5.1.26 sf histstring

Extracts a string pointed by the input key from the file. If the value is NULL it will return
NULL, otherwise it will allocate a new block of memory of char type and copy the memory
block from the table to the new block and return a pointer to the newly allocated block of
memory. It uses sf simtab getstring.

Call

string = sf_histstring(file, key);

Definition

char* sf_histstring (sf_file file, const char* key)

/*< read a string parameter from file (returns NULL on failure) >*/
{
...
}

Input parameters

file file from which a string is to be extracted (sf file).

key the name of the string which has to be extracted (const char*).
98 CHAPTER 5. OPERATIONS WITH RSF FILES

Output

string a pointer to allocated block of memory containing a string of characters.

5.1.27 sf fileflush

Outputs the parameters from source file to the output file. It sets the data format in the
output file and prepares the file for writing binary data.

Call

sf_fileflush( file, src);

Definition

void sf_fileflush (sf_file file, sf_file src)

/*< outputs parameter to a file (initially from source src)
---
Prepares file for writing binary data >*/
{
...
}

Input parameters

file pointer to the output file (sf file).

src a pointer to the input file structure (sf file).

5.1.28 sf putint

Enters an integer value in the file. It uses sf simtab enter.

Call

sf_putint (file, key, par);

5.1. MAIN OPERATIONS WITH RSF FILES (FILE.C) 99

Definition

void sf_putint (sf_file file, const char* key, int par)

/*< put an int parameter to a file >*/
{
...
}

Input parameters

file the file in which the the key value is to be stored (sf file).
key pointer to the name of the key value to be input (const char*).
par integer parameter which is to be written.

5.1.29 sf putints

Enters an array of integer values in the file. It uses sf simtab enter.

Call

sf_putints (file, key, par, n);

Definition

void sf_putints (sf_file file, const char* key, const int* par, size_t n)
/*< put an int array of size n parameter to a file >*/
{
...
}

Input parameters

file the file in which the the key value is to be stored (sf file).
key pointer to the name of the key value to be input (const char*).
par pointer to integer parameter array which is to be written.
n size of the array to be written (size t).
100 CHAPTER 5. OPERATIONS WITH RSF FILES

5.1.30 sf putlargeint

Enters a long integer value in the file. It uses sf simtab enter.

Call

sf_putlargeint (file, key, par);

Definition

void sf_putlargeint (sf_file file, const char* key, off_t par)

/*< put a sf_largeint parameter to a file >*/
{
...
}

Input parameters

file the file in which the the key value is to be stored (sf file).
key pointer to the name of the key value to be input (const char*).
par integer parameter which is to be written.

5.1.31 sf putfloat

Enters a float value in the file. It uses sf simtab enter.

void sf_putstring (sf_file file, const char* key,const char* par)

/*< put a string parameter to a file >*/
{
...
}

Input parameters

file the file in which the key value is to be stored (sf file).
key pointer to the name of the key value to be input (const char*).
par pointer to the string parameter which is to be written.
102 CHAPTER 5. OPERATIONS WITH RSF FILES

5.1.33 sf putline

Enters a string line in to the file.

Call

sf_putline (file, line);

Definition

void sf_putline (sf_file file, const char* line)

/*< put a string line to a file >*/
{
...
}

Input parameters

file the file in which the string line is to be stored (sf file).
line pointer to the which is to be written.

5.1.34 sf setaformat

Sets number format specifiers for ASCII output. This can be used in sf complexwrite,
for example.

Call

sf_setaformat (format, line);

Definition

void sf_setaformat (const char* format /* number format (.i.e "%5g") */,
int line /* numbers in line */ )
/*< Set format for ascii output >*/
{
...
5.1. MAIN OPERATIONS WITH RSF FILES (FILE.C) 103

Input parameters

format a number format, e.g. %5g.

line numbers in the ASCII line.

5.1.35 sf complexwrite

Writes a complex array to the file, according to the value of the form of the file, i.e. SF ASCII,
SF XDR or SF NATIVE.

Call

sf_complexwrite (arr, size, file);

Definition

void sf_complexwrite (sf_complex* arr, size_t size, sf_file file)

/*< write a complex array arr[size] to file >*/
{
...
}

size size of the array (size t).
file a file in which the array is to be written (sf file).

5.1.38 sf uncharwrite

Writes a unsigned character array to the file, according to the value of the form of the file,
i.e. SF ASCII, SF XDR or SF NATIVE.

Call

sf_ucharwrite (arr, size, file);

Definition

void sf_ucharwrite (unsigned char* arr, size_t size, sf_file file)

/*< write an unsigned char array arr[size] to file >*/
{
...
}

Input parameters

arr a pointer to the array which is to be written (sf complex).

size size of the array (size t).
file a file in which the array is to be written (sf file).

5.1.39 sf charread

Reads a character array from the file, according to the value of the form of the file,
i.e. SF ASCII, SF XDR or SF NATIVE.

Call

sf_charread (arr, size, file);

106 CHAPTER 5. OPERATIONS WITH RSF FILES

Definition

void sf_charread (/@out@/ char* arr, size_t size, sf_file file)

/*< read a char array arr[size] from file >*/
{
...
}

Input parameters

arr a pointer to the array to which the array from the file is to be copied (sf complex).
size size of the array (size t).
file a file in which the array is to be written (sf file).

5.1.40 sf uncharread

Reads an unsigned character array from the file, according to the value of the form of the
file, i.e. SF ASCII, SF XDR or SF NATIVE.

Call

sf_ucharread (arr, size, file);

Definition

void sf_ucharread (/*@out@*/ unsigned char* arr, size_t size, sf_file file)
/*< read a uchar array arr[size] from file >*/
{
...
}

Input parameters

Definition

void sf_shortread (/@out@/ short* arr, size_t size, sf_file file)

/*< read a short array arr[size] from file >*/
{
...
}

Input parameters

arr a pointer to the array to which the array from the file is to be copied (sf complex).
size size of the array (size t).
file a file in which the array is to be written (sf file).

5.1.44 sf shortwrite

Writes an short array to the file, according to the value of the form of the file, i.e. SF ASCII,
SF XDR or SF NATIVE.

Call

sf_shortwrite (arr, size, file);

Definition

void sf_shortwrite (short* arr, size_t size, sf_file file)

/*< write a short array arr[size] to file >*/
5.1. MAIN OPERATIONS WITH RSF FILES (FILE.C) 109

{
...
}

Input parameters

arr a pointer to the array which is to be written (sf complex).

size size of the array (size t).
file a file in which the array is to be written (sf file).

5.1.45 sf floatwrite

Writes an float array to the file, according to the value of the form of the file, i.e. SF ASCII,
SF XDR or SF NATIVE.

Call

sf_floatwrite (arr, size, file);

Definition

void sf_floatwrite (float* arr, size_t size, sf_file file)

/*< write a float array arr[size] to file >*/
{
...
}

Input parameters

arr a pointer to the array which is to be written (sf complex).

size size of the array (size t).
file a file in which the array is to be written (sf file).

5.1.46 sf floatread

Reads a float array from the file, according to the value of the form of the file, i.e. SF ASCII,
SF XDR or SF NATIVE.
110 CHAPTER 5. OPERATIONS WITH RSF FILES

Call

sf_floatread (arr, size, file);

Definition

void sf_floatread (/@out@/ float* arr, size_t size, sf_file file)

/*< read a float array arr[size] from file >*/
{
...
}

Input parameters

arr a pointer to the array to which the array from the file is to be copied (sf complex).
size size of the array (size t).
file a file in which the array is to be written (sf file).

5.1.47 sf bytes

Returns the size of the file in bytes.

Call

size = sf_bytes (file);

Definition

off_t sf_bytes (sf_file file)

/*< Count the file data size (in bytes) >*/
{
...
}

Input parameters

file a pointer to the file structure whose size is required (sf file).
5.1. MAIN OPERATIONS WITH RSF FILES (FILE.C) 111

Output

size the size of the file structure in bytes.

5.1.48 sf tell

Returns the current value of the position indicator of the file.

Call

val = sf_tell (file);

Definition

off_t sf_tell (sf_file file)

/*< Find position in file >*/
{
...
}

Input parameters

file a pointer to the file structure the value of whose position indicator required
(sf file).

Output

Current value of the position indicator of the file. It is of type off t.

5.1.49 sf tempfile

Creates a temporary file with a unique file name.

Input parameters

file a pointer to the file structure which is to be unpiped (sf file).

5.1.52 sf close

Removes temporary files.

Call

sf_close();

Definition

void sf_close(void)
/*< Remove temporary files >*/
{
...
}

5.2 Additional operations with RSF files (files.c)

5.2.1 sf filedims

Returns the dimensions of the file.

114 CHAPTER 5. OPERATIONS WITH RSF FILES

Call

dim = sf_filedims (file, n);

Definition

int sf_filedims (sf_file file, /@out@/ int *n)

/*< Find file dimensions.
---
Outputs the number of dimensions dim and a dimension array n[dim] >*/
{
...
}

Input parameters

file a pointer to the file structure whose dimensions are required (sf file).
n an array where the dimensions will be stored (int).

Output

dim number of dimensions in the file (int).

n[dim] the array of dimensions (int).

5.2.2 sf largefiledims

Returns the dimensions of the file. It is exactly like sf filedims but n in the input is the
offset in bytes in the input file (type off t) rather than just an integer.

Call

dim = sf_largefiledims (file, n);

Definition

int sf_largefiledims (sf_file file, /@out@/ off_t *n)

5.2. ADDITIONAL OPERATIONS WITH RSF FILES (FILES.C) 115

/*< Find file dimensions.

---
Outputs the number of dimensions dim and a dimension array n[dim] >*/
{
...
}

Input parameters

file a pointer to the file structure whose dimensions are required (sf file).
n an array where the dimensions will be stored (off t).

Output

dim number of dimensions in the file (off t).

n[dim] the array of dimensions (off t).

5.2.3 sf memsize

Returns the memory size defined in the environment variable RSFMEMSIZE. If there is an
invalid value the function will print an error message an assign a default value of 100
Mbytes.

Call

memsize = sf_memsize();

Definition

int sf_memsize()
/*< Returns memory size by:
1. checking RSFMEMSIZE environmental variable
2. using hard-coded "def" constant
>*/
{

...
116 CHAPTER 5. OPERATIONS WITH RSF FILES

return memsize;
}

5.2.4 sf filesize

Returns the size of the file, that is, the product of the dimensions. It uses the function
sf leftsize.

Call

size = sf_filesize (file);

Definition

off_t sf_filesize (sf_file file)

/*< Find file size (product of all dimensions) >*/
{
...
}

Input parameters

file a pointer to the file structure whose size is required (sf file).

Output

size product of dimensions in the file (off t).

5.2.5 sf leftsize

Returns the size of the file, that is, the product of the dimensions but only for the dimen-
sions greater than the input integer dim. It uses the function sf leftsize.

Call

size = sf_leftsize (file, dim);

5.2. ADDITIONAL OPERATIONS WITH RSF FILES (FILES.C) 117

Definition

off_t sf_leftsize (sf_file file, int dim)

/*< Find file size for dimensions greater than dim >*/
{
...
}

Input parameters

file the file whose size is required (sf file).

dim a pointer to the file structure whose size is required (sf file).

Output

size product of dimensions greater than dim in the file (off t).

5.2.6 sf cp

Copies the input file in to the output file out.

Call

sf_cp (in, out);

Definition

void sf_cp(sf_file in, sf_file out)

/*< Copy file in to file out >*/
{
...
}

Input parameters

in the file which is to be copied (sf file).

out the file to which in file is to be copied (sf file).
118 CHAPTER 5. OPERATIONS WITH RSF FILES

5.2.7 sf rm

Removes the RSF file. There are options to force removal (files are deleted even if pro-
tected), to inquire before removing a file and whether or to require verbose output.

Call

sf_rm (filename, force, verb, inquire);

Definition

void sf_rm(const char* filename, bool force, bool verb, bool inquire)
/*< Remove an RSF file.
---
force, verb, and inquire flags should behave similar to the corresponding flags
in the Unix "rm" command. >*/
{
...
}

Input parameters

filename name of the file which is to be removed (sf file).

force remove forcefully or not (sf file).
inquire ask before removing or not (sf file).

5.2.8 sf shiftdim

Shifts the grid by one dimension after the axis defined in the input parameters (axis).

Call

n3 = sf_shiftdim(in, out, axis);

5.2. ADDITIONAL OPERATIONS WITH RSF FILES (FILES.C) 119

Definition

off_t sf_shiftdim(sf_file in, sf_file out, int axis)

/*< shift grid after axis by one dimension forward >*/
{
...
}

Input parameters

in a pointer to the input file structure (sf file).

out a pointer to the output file structure (sf file).
axis the axis after which the grid is to be shifted (sf file).

Output

n3 the file size (product of dimensions) after the shift (off t).

5.2.9 sf unshiftdim

Shifts the grid backward by one dimension after the axis defined in the input parameters
(axis).

Call

n3 = sf_unshiftdim (in, out, axis);

Definition

off_t sf_unshiftdim(sf_file in, sf_file out, int axis)

/*< shift grid after axis by one dimension backward >*/
{
...
}
120 CHAPTER 5. OPERATIONS WITH RSF FILES

Input parameters

in a pointer to the input file structure (sf file).

out a pointer to the output file structure (sf file).
axis the axis after which the grid is to be shifted (sf file).

Output

n3 the file size (product of dimensions) after the backward shift (off t).

5.2.10 sf endian

Returns true if the machine is little endian.

Definition

little_endian = sf_endian ();

Definition

bool sf_endian (void)

/*< Endianness test, returns true for little-endian machines >*/
{
...
}

Output

little endian a boolean parameter which is true if the machine is little endian.

5.3 Complex number operations (komplex.c)

5.3.1 creal

Returns the real part of the complex number.

Adds two complex numbers.

5.3.7 dccmul

Multiplies two complex number. Its output type and one of the input parameters is of type
kiss fft cpx.

Call

c = sf_dccmul(a, b);

Definition

kiss_fft_cpx sf_dccmul(sf_double_complex a, kiss_fft_cpx b)

/*< complex multiplication >*/
{
...
}

Input parameters

a a complex number. Must be of type sf double complex.

b a complex number. Must be of type kiss fft cpx.

Output

c the product ab. It is of type sf double complex.

5.3.8 dcdmul

Multiplies two complex number. One of the input parameters is kiss fft cpx. This means
that it should only be used if complex.h header is not used.

Call

c = sf_dcdmul(a, b);
126 CHAPTER 5. OPERATIONS WITH RSF FILES

Definition

sf_double_complex sf_dcdmul(sf_double_complex a, kiss_fft_cpx b)

/*< complex multiplication >*/
{
...
}

Input parameters

a a complex number. Must be of type sf double complex.

b a complex number. Must be of type kiss fft cpx.

Output

c product ab of the two complex numbers a and b. It is of type sf double complex.

5.3.9 dcrmul

Multiplies a complex number with a real number of type double.

Call

c = sf_dcrmul(a, b);

Definition

sf_double_complex sf_dcrmul(sf_double_complex a, double b)

/*< complex by real multiplication >*/
{
...
}

Input parameters

a a complex number. Must be of type sf double complex.

b a real number (double).
5.3. COMPLEX NUMBER OPERATIONS (KOMPLEX.C) 127

Output

c product of the complex number a and the real number b. It is of type sf double complex.

5.3.10 dcdiv

Divides two complex numbers.

Call

c = sf_dcdiv(a, b);

Definition

sf_double_complex sf_dcdiv(sf_double_complex a, sf_double_complex b)

/*< complex division >*/
{
...
}

Input parameters

a a complex number. Must be of type sf double complex.

b a complex number. Must be of type sf double complex.

Output
a
c b. It is of type sf double complex.

5.3.11 cabs

Returns the absolute value (magnitude) of a complex number. It uses the hypot function
from the C library.

Call

a = sf_cabs(z);
128 CHAPTER 5. OPERATIONS WITH RSF FILES

Definition

double sf_cabs(sf_double_complex z)
/*< replacement for cabsf >*/
{
...
}

Input parameters

z a complex number. Must be of type sf double complex.

Output

hypot(z.r,z.i) absolute value of the complex number.

5.3.12 cabs

Returns the argument of a complex number. It uses the atan2 function from the C library.

Call

u = sf_carg(z);

Definition

double sf_carg(sf_double_complex z)
/*< replacement for cargf >*/
{
...
}

Input parameters

z a complex number. Must be of type sf double complex.

5.3. COMPLEX NUMBER OPERATIONS (KOMPLEX.C) 129

Output

atan2(z.r,z.i) argument of the complex number.

5.3.13 crealf

Returns the real part of the complex number.

Call

r = sf_crealf(c);

Definition

float sf_crealf(kiss_fft_cpx c)
/*< real part >*/
{
...
}

Input parameters

c a complex number. Must be of type kiss fft cpx.

Output

r real part of the complex number. It is of type float.

5.3.14 cimagf

Returns the imaginary part of the complex number.

Call

im = sf_cimagf(c);
130 CHAPTER 5. OPERATIONS WITH RSF FILES

Definition

float sf_cimagf(kiss_fft_cpx c)
/*< imaginary part >*/
{
...
}

Input parameters

c a complex number. Must be of type kiss fft cpx.

Output

im imaginary part of the complex number. It is of type float.

5.3.15 cprint

Prints the complex number on the screen. This is done using the sf warning.

Call

cprint(c);

Definition

void cprint (sf_complex c)

/*< print a complex number (for debugging purposes) >*/
{
...
}

Input parameters

c a complex number (sf complex).

5.3. COMPLEX NUMBER OPERATIONS (KOMPLEX.C) 131

5.3.16 cadd

Adds two complex numbers. The output is of type kiss fft cpx.

Call

c = sf_cadd(a, b);

Definition

kiss_fft_cpx sf_cadd(kiss_fft_cpx a, kiss_fft_cpx b)

/*< complex addition >*/
{
...
}

Input parameters

a a complex number. Must be of type kiss fft cpx.

b a complex number. Must be of type kiss fft cpx.

Output

c the sum a + b of the two complex numbers a, b. It is of type kiss fft cpx.

5.3.17 csub

Subtracts two complex numbers. The output is of type kiss fft cpx.

Call

/*< complex division >*/
{
...
}

Input parameters

a a complex number. Must be of type sf double complex.

b a complex number. Must be of type sf double complex.

Output
a
c b. It is of type kiss fft cpx.

5.3.20 cmul

Multiplies two complex numbers. The output is of type kiss fft cpx.

Call

c = sf_cmul(a, b);
134 CHAPTER 5. OPERATIONS WITH RSF FILES

Definition

kiss_fft_cpx sf_cmul(kiss_fft_cpx a, kiss_fft_cpx b)

/*< complex multiplication >*/
{
...
}

Input parameters

a a complex number. Must be of type sf double complex.

b a complex number. Must be of type sf double complex.

Output

c product of the two complex numbers a and b. It is of type kiss fft cpx.

5.3.21 crmul

Multiplies a complex number with a real number. The output is of type kiss fft cpx.

Call

c = sf_crmul(a, b);

Definition

kiss_fft_cpx sf_crmul(kiss_fft_cpx a, float b)

/*< complex by real multiplication >*/
{
...
}

Input parameters

a a complex number. Must be of type sf double complex.

b a real number (float).
5.3. COMPLEX NUMBER OPERATIONS (KOMPLEX.C) 135

Output

c the product ab of a complex number a and real number b. It is of type kiss fft cpx.

5.3. COMPLEX NUMBER OPERATIONS (KOMPLEX.C) 141

5.3. COMPLEX NUMBER OPERATIONS (KOMPLEX.C) 143

z a complex number. Must be of type kiss fft cpx.

5.3. COMPLEX NUMBER OPERATIONS (KOMPLEX.C) 147

Output

w hyperbolic arccosine of a complex number. It is of type kiss fft cpx.

5.3.40 cpowf

Returns the complex base a raised to complex power b.

Call

c = sf_cpowf(a, b);

Definition

kiss_fft_cpx sf_cpowf(kiss_fft_cpx a, kiss_fft_cpx b)

/*< complex power >*/
{
...
}

Input parameters

a a complex number. Must be of type kiss fft cpx.

b a complex number. Must be of type kiss fft cpx.

Output

c ab . It is a complex number of type kiss fft cpx.

148 CHAPTER 5. OPERATIONS WITH RSF FILES
Chapter 6

Error handling

6.1 Handling warning and error messages (error.c)

6.1.1 sf error

Outputs an error message to stderr, which is usually the screen. It uses sf getprog to
get the name of the program which is causing the error and print it on the screen. Uses
vfprintf, which can take a variable number of arguments initialized by va list. This
gives the user flexibility in choosing the number of arguments.
If there is a ’:’ at the end of format, information about the system errors is printed,
this is done by using strerror to interpret the last error number errno in the system.
Also, if there is a ’;’ at the end of a format the command prompt will not go to the next
line.

Call

sf_error (format, ...);

Definition

void sf_error( const char *format, ... )

/*< Outputs an error message to stderr and terminates the program.
---
Format and variable arguments follow printf convention. Additionally, a ’:’ at
the end of format adds system information for system errors. >*/

149
150 CHAPTER 6. ERROR HANDLING

{
...
}

Input parameters

format a string of type const char* containing the format specifiers for the arguments
to be input from the next commands.
... variable number of arguments, which are to replace the format specifiers in the
format.

Output

An error message output to sterr (usually printed on screen).

6.1.2 sf warning

Outputs a warning message to stderr which is usually the screen. It uses sf getprog to
get the name of the program which is causing the error and print it on the screen. Uses
vfprintf, which can take a variable number of arguments initialized by va list. This
gives the user flexibility in choosing the number of arguments. If there is a ’:’ at the end
of format, information about the system errors is printed, this is done by using strerror
to interpret the last error number errno in the system. Also, if there is a ’;’ at the end of
a format the command prompt will not go to the next line.

Call

sf_warning (format, ... );

Definition

void sf_warning( const char *format, ... )

/*< Outputs a warning message to stderr.
---
Format and variable arguments follow printf convention. Additionally, a ’:’ at
the end of format adds system information for system errors. >*/
{
6.1. HANDLING WARNING AND ERROR MESSAGES (ERROR.C) 151

...
}

Input parameters

Output

A warning message output to sterr ( usually printed on screen).

152 CHAPTER 6. ERROR HANDLING
Chapter 7

Linear operators

7.1 Introduction

This section contains a bunch of programs that implement operators. Therefore a short
introduction on operators is in order.

7.1.1 Definition of operators

Mathematically speaking an operator is a function of a function, i.e. a rule (or mapping)

according to which a function f is transformed into another function g. We use the notation
g = R[f ] or simply g = Rf , where R denotes the operator. Examples of operators are the
derivative, the integral, convolution (with a specific function), multiplication by a scalar
and others. Note that in general the domains of f and g are not necessarily the same. For
example, in the case of the derivative, the domain of g = Rf is the subset of the domain
of f , in which f is smooth. In particular if f = |x|, x ∈ [−1, 1], then the domain of g is
(−1, 0) ∪ (0, 1).
An important class of operators are the linear operators. An operator L is linear if
for any two functions f1 , f2 and any two scalars a1 , a2 , L[a1 f1 + a1 f2 ] = a1 Lf1 + a2 Lf2 .
The derivative, integral, convolution and multiplication by scalar are all linear operators.
In the discrete world, operators act on vectors and linear operators are in fact matrices,
with which the vectors are multiplied. (Multiplication by a matrix is a linear operation,
since M(a1 x1 + a2 x2 ) = a1 Mx1 + a2 Mx2 ). In fact many of the calculations performed
routinely in science and engineering are essentially matrix multiplications in disguise. For
example assume a vector x = [x1 x2 . . . xn ]T with length n (superscript T denotes trans-

153
154 CHAPTER 7. LINEAR OPERATORS

pose). Padding this vector with m zeros, produces another vector y with
 
x1
 x2 
 
 .. 
 . 
  x
y= xn  = 0 ,

0
 
 .. 
 . 
0

where 0 is the zero vector of length m. One

can readily verify that zero padding is a linear
I
operation with operator matrix L = , where I is the n × n identity matrix and O is
O
the m × n zero matrix, since

I x
y = Lx = x= .
O 0

Note that as in the case of functions, the domains of x and y are different: x ∈ Rn (or
more generally x ∈ Cn ), while y ∈ Rn+m (or Cn+m ).
Similarly, one can define convolution of x with a = [a1 a2 . . . am ]T as the multiplication
of x with
 
a1 0 0 · · · 0 0
a2 a1 0 · · · 0 0 
 
a3 a2 a1 · · · 0 0 
 
A =  ... .. .. . . .. ..  .

 . . . . . 
 0 0 0 · · · am−1 am−2 
 
 0 0 0 ··· am am−1 
0 0 0 ··· 0 am
and many other operations as matrix multiplications. Other operators are the identity
operator is the identity matrix I and is implemented by copy.c and ccopy.c and the
null operator (or zero matrix O), which is implemented by adjnull.c. For the rest of
this introduction, the boldface notation will imply specifically discrete operators, while the
normal fonts will imply operators on either continuous or discrete mathematical entities.

7.1.2 Products of operators

The result of an operation on a function is another function, therefore we can naturally

apply an operator on another operator. In other words, if L1 , L2 are two operators,
7.1. INTRODUCTION 155

then we can define L1 L2 as L1 L2 [x] = L1 [L2 [x]], provided that L1 [L2 [x]] makes sense
mathematically. This is called the composition of the operators L1 and L2 . Because in
the discrete case the composition of operators is in fact the multiplication L1 L2 of the two
matrices L1 , L2 the operator composition is usually referred to as operator product and
denoted by L1 L2 is used. The composition of operators can be naturally extended to any
finite product L1 · · · Ln−1 Ln . The product of up to 3 operators is implemented in chain.c.

7.1.3 Adjoint operators

A very important notion in data processing is the adjoint operator1 L∗ of an operator L.

In the discrete world, the adjoint operator of L is its (conjugate) transpose, i.e. L∗ = LH .
From this definition of the adjoint it is evident that the adjoint of the adjoint is the original
operator (since (L∗ )∗ = (LH )H = L). Consider a vector y = [y1 y2 , . . . , yn+m ]T and the
T
∗ I
H = I OT . Then

adjoint of the zero-padding operator, L = L =
O
 
y1
 y2   
y1
 
 .. 
 .   
y2 
L∗ y = I O T y = I O T 
 
yn
= . .
 yn+1   .. 
  

yn
 
 .. 
 . 
yn+m

We conclude that the adjoint of data zero-padding is data truncation. It is also easy (but
tedious) to verify that the adjoint operation of the convolution between a and x is the
crosscorrelation of a with yH . One may also notice that for the specific zero-padding
operator, L∗ Lx = x, i.e. in this case the adjoint neutralizes the effect of the operator. It
is tempting to say that the adjoint operation is the inverse operation, however this is not
the case: it is not always the case that L∗ L = LL∗ . In fact such an equality is meaningless
mathematically if L is not a square matrix (if L is a n × m matrix, then LL∗ is n × n,
while L∗ L is m × m). L∗ is not even the left inverse of L: notice that in the case of the
zero padding operator, (L∗ )∗ L∗ y = LL∗ y = ỹ 6= y (the last m elements of ỹ are zero).
However it is often the case that the adjoint is an adequate. It is the case though quite
often that the adjoint is adequate approximation to the inverse (sometimes within a scaling
factor) and it is also quite probable that the adjoint will do a better job than the inverse in
inverse problems. This is because the adjoint operator tolerates data imperfections, which
the inverse does not.
1
The adjoint operator should not be confused with the (classical) adjoint or adjucate or adjunct matrix
of a square matrix. The adjugate matrix of an invertible matrix is the inverse multiplied by its determinant.
156 CHAPTER 7. LINEAR OPERATORS

From the definition of the adjoint operation as the left multiplication the complex
conjugate matrix, it follows that the adjoint of the product of two linear operators equals
the product of the adjoints in reverse order, i.e. (L1 L2 )∗ = L∗2 L∗1 . This is naturally extended
to the product of any finite product of operators, i.e. (L1 L2 · · · Ln )∗ = L∗n L∗n−1 · · · L∗1 . The
adjoint of the product is also implemented in chain.c.

7.1.4 The dot-product test

The dot-product test is a valuable checkpoint, which can tell us whether the implementation
of the adjoint operator is wrong (however it cannot guarantee that it is indeed correct).
The concept is the following: Assuming that we have coded an operator L and its adjoint
L∗ . Then for any two vectors or functions a and b,

ha, Lbi = h(L∗ a)∗ , bi (7.1)

where h , i denotes the dot product. Remember that the dot product of two functions
f, g ∈ L2 is f g ∗ dt while the dot product of two vectors x and y is xH y. Notice that for
R

vectors eq. (7.1) becomes xH Ly = (LH y)H y which is obviously true. The lhs of eq. (7.1)
is computed using L, while the rhs is computed using the adjoint L∗ . For the dot-product
test, one just needs to load the vectors x and y with random numbers and perform the
two computations. If the two results are not equal (within machine precision), then the
computation of either L or L∗ is erroneous. Note that truncation errors have identical
effects on both operators, so the two results should be almost equal. The dot-product test
(for real operators only) is implemented by sf dot test.

7.1.5 Implementation of operators

It should be evident by now that the implementation of an operator L should have at least
four arguments: a variable x from which the operand (entity on which L is applied) x is
read along with its length nx, and the variable y in which the result y = Lx is stored and
its length ny .
Also, since every operator comes along with its adjoint, the implementation of the linear
operators described later in this chapter, gives also the possibility to compute the adjoint
operator. This is done through the boolean adj input argument. When adj is true, the
adjoint operator L∗ computed. As discussed before, the domains of x and Lx are in general
different, therefore L∗ cannot be applied on x. However it can always be applied on Lx or
some y, which has the same domain as Lx. For this reason, when adj is true, the operand
is y and the result is x and thus, y is used as input and the result is stored in x. As an
example if sf copy lop (the identity operator) is called, then the result is that y ← x.
7.2. ADJOINT ZEROING (ADJNULL.C) 157

However if additionally adj is true, then the result will be x ← y. If adjnull (the null
operator) is called, then the result is that y ← 0. However if additionally adj is true, then
the result will be x ← 0.
Finally, it is often the case that we need to compute y ← Lx but y ← y + Lx. For this
reason another boolean argument, namely add is defined. If add is true, then y ← y + Lx.
Considering the same example with the identity operator, if sf copy lop is called with
add being true, then y ← y +x. If additionally adj is true, then x ← y +x. Or if adjnull
is called with add being true, if adj is false, y ← y and if adj is true, then x ← x (so
in essence, if add is true, no matter what the value of adj, nothing happens).
As a conclusion, the linear operators described in this chapter have all the following
form:

oper(adj, add, nx, ny, x, y),

where adj and add are boolean, nx and ny are integers and x and y are pointers of various
but the same data type. Table 7.1 summarizes the effect of the adj and add variables.

Table 7.1: Returned values for linear operations.

adj add description returns
0 0 normal operation y ← Lx
0 1 normal operation with addition y ← y + Lx
1 0 adjoint operation x ← L∗ y
1 1 adjoint operation with addition x ← x + L∗ y

7.2 Adjoint zeroing (adjnull.c)

The null operator is defined by

y = 0x = 0, with yt ← 0.

Its adjoint is

x = 0∗ y = 0, with xt ← 0.

7.2.1 sf adjnull

Call

sf_adjnull(adj, add, nx, ny, x, y);

158 CHAPTER 7. LINEAR OPERATORS

Definition

void sf_adjnull (bool adj /* adjoint flag */,

bool add /* addition flag */,
int nx /* size of \texttt{x} */,
int ny /* size of \texttt{y} */,
float* x,
float* y)
/*< Zeros out the output (unless add is true).
Useful first step for any linear operator. >*/
{
...
}

Input parameters

adj adjoint flag (bool). If true, then the adjoint is computed, i.e. x ← 0∗ y or x ←
x + 0∗ y.
add addition flag (bool). If true, then y ← y + 0x or x ← x + 0∗ y.
nx size of x (int).
ny size of y (int).
x input data or output (float*).
y output or input data (float*).

7.2.2 sf cadjnull

The same as sf adjnull but for complex data.

Call

sf_cadjnull(adj, add, nx, ny, x, y);

Definition

void sf_cadjnull (bool adj /* adjoint flag */,

bool add /* addition flag */,
int nx /* size of \texttt{x} */,
7.3. IDENTITY OPERATOR (COPY.C) 159

int ny /* size of \texttt{y} */,

sf_complex* x,
sf_complex* y)
/*< adjnull version for complex data. >*/
{
...
}

Input parameters

7.3 Simple identity (copy) operator (copy.c)

The identity operator is defined by

y = 1x = x, with yt ← xt .

Its adjoint is

x = 1∗ y = y, with xt ← yt .

7.3.1 sf copy lop

Call

sf_copy_lop (adj, add, nx, ny, x, y);

160 CHAPTER 7. LINEAR OPERATORS

Definition

void sf_copy_lop (bool adj, bool add, int nx, int ny, float* xx, float* yy)
/*< linear operator >*/
{
...
}

Input parameters

adj adjoint flag (bool). If true, then the adjoint is computed, i.e. x ← 1∗ y or x ←
x + 1∗ y.
add addition flag (bool). If true, then y ← y + 1x or x ← x + 1∗ y.
nx size of x (int). nx must equal ny.
ny size of y (int). ny must equal nx.
x input data or output (float*).
y output or input data (float*).

7.4 Simple identity (copy) operator for complex data (ccopy.c)

This is the same operator as sf copy lop but for complex data. In particular, the identity
operator is defined by

y = 1x = x, with yt ← xt .

Its adjoint is

x = 1∗ y = y, with xt ← yt .

7.4.1 sf ccopy lop

Call

sf_ccopy_lop (adj, add, nx, ny, x, y);

7.5. SIMPLE MASK OPERATOR (MASK.C) 161

Definition

void sf_ccopy_lop (bool adj, bool add, int nx, int ny,
sf_complex* xx, sf_complex* yy)
/*< linear operator >*/
{
...
}

Input parameters

7.5 Simple mask operator (mask.c)

This mask operator is defined by

y = Lm x = mx, with yt ← mt xt ,

where mt takes binary values, i.e. mt = 0 or 1. Its adjoint is

x = L∗m y = my, with xt ← mt yt ,

7.5.1 sf mask init

Initializes the static variable m with boolean values, to be used in the sf mask lop or
sf cmask lop.

Call

sf_mask_init (m);
162 CHAPTER 7. LINEAR OPERATORS

Definition

void sf_mask_init(const bool *m)

/*< initialize with mask >*/
{
...
}

Input parameters

m a pointer to boolean values (const bool*).

7.5.2 sf mask lop

Call

sf_mask_lop (adj, add, nx, ny, x, y);

Definition

void sf_mask_lop(bool adj, bool add, int nx, int ny, float *x, float *y)
/*< linear operator >*/
{
...
}

Input parameters

adj adjoint flag (bool). If true, then the adjoint is computed, i.e. x ← L∗m y or x ←
x + L∗m y.
add addition flag (bool). If true, then y ← y + Lm x or x ← x + L∗m y.
nx size of x (int). nx must equal ny.
ny size of y (int). ny must equal nx.
x input data or output (float*).
y output or input data (float*).
7.6. SIMPLE WEIGHT OPERATOR (WEIGHT.C) 163

7.5.3 sf cmask lop

The same as sf mask lop but for complex data.

Call

sf_cmask_lop (adj, add, nx, ny, x, y);

Definition

void sf_cmask_lop(bool adj, bool add, int nx, int ny,

sf_complex *x, sf_complex *y)
/*< linear operator >*/
{
...
}

Input parameters

adj adjoint flag (bool). If true, then the adjoint is computed, i.e. x ← L∗m y or x ←
x + L∗m y.
add addition flag (bool). If true, then y ← y + Lm x or x ← x + L∗m y.
nx size of x (int). nx must equal ny.
ny size of y (int). ny must equal nx.
x input data or output (sf complex*).
y output or input data (sf complex*).

7.6 Simple weight operator (weight.c)

This weight operator is defined by

y = Lw x = wx, with yt ← wt xt .

Its adjoint is

x = L∗w y = wy, with xt ← wt yt .

164 CHAPTER 7. LINEAR OPERATORS

Note that for complex data the weight w must still be real.
There is also an in-place (x ← Lw x) version of the operator, which multiplies the input
data with the square of w i.e.

x = Lw x = w2 x, with xt ← wt2 xt .

7.6.1 sf weight init

Initializes the weights to be applied as linear operator, by assigning value to a static

parameter.

Call

sf_weight_init(w);

Definition

void sf_weight_init(float *w1)

/*< initialize >*/
{
..
}

Input parameters

w values of the weights (float*).

7.6.2 sf weight lop

Applies the linear operator with the weights initialized by sf weight init.

Call

sf_weight_lop (adj, add, nx, ny, x, y);

7.6. SIMPLE WEIGHT OPERATOR (WEIGHT.C) 165

Definition

void sf_weight_lop (bool adj, bool add, int nx, int ny, float* xx, float* yy)
/*< linear operator >*/
{
...
}

Input parameters

adj adjoint flag (bool). If true, then the adjoint is computed, i.e. x ← L∗w y or x ←
x + L∗w y.
add addition flag (bool). If true, then y ← y + Lw x or x ← x + L∗w y.
nx size of x (int). nx must equal ny.
ny size of y (int). ny must equal nx.
x input data or output (float*).
y output or input data (float*).

7.6.3 sf cweight lop

Its adjoint is

x = D∗ y, with xt ← −(yt − yt−1 ), x0 = −y0 .

7.7.1 sf igrad1 lop

Call

sf_igrad1_lop(adj, add, nx, ny, x, y);

Definition

void sf_igrad1_lop(bool adj, bool add,

int nx, int ny, float *xx, float *yy)
168 CHAPTER 7. LINEAR OPERATORS

/< linear operator >/

{
...
}

Input parameters

adj adjoint flag (bool). If true, then the adjoint is computed, i.e. x ← D∗ y or x ←
x + D∗ y.
add addition flag (bool). If true, then y ← y + Dx or x ← x + D∗ y.
nx size of x (int).
ny size of y (int).
x input data or output (float*).
y output or input data (float*).

7.8 Causal integration (causint.c)

This causal integration operator is defined by

t
X
y = Lx, with yt ← xτ .
τ =0

Its adjoint is

T
X −1
x = L∗ y, with xt ← yτ ,
τ =t

where T is the total number of samples of x.

7.8.1 sf causint lop

Call

sf_causint_lop (adj, add, nx, ny, x, y);

7.9. CHAINING LINEAR OPERATORS (CHAIN.C) 169

Defintion

sf_causint_lop (adj, add, nx, ny, x, y)

/*< linear operator >*/
{
...
}

Input parameters

adj adjoint flag (bool). If true, then the adjoint is computed, i.e. x ← L∗ y or x ←
x + L∗ y.
add addition flag (bool). If true, then y ← y + Lx or x ← x + L∗ y.
nx size of x (int).
ny size of y (int).
x input data or output (float*).
y output or input data (float*).

7.9 Chaining linear operators (chain.c)

Calculates products of operators.

7.9.1 sf chain

Chains two operators L1 and L2 :

d = (L2 L1 )m.

Its adjoint is

m = (L2 L1 )∗ d = L∗1 L∗2 d.

Call

sf_chain (oper1,oper2, adj,add, nm,nd,nt, mod,dat,tmp);

170 CHAPTER 7. LINEAR OPERATORS

Definition

void sf_chain( sf_operator oper1 /* outer operator */,

sf_operator oper2 /* inner operator */,
bool adj /* adjoint flag */,
bool add /* addition flag */,
int nm /* model size */,
int nd /* data size */,
int nt /* intermediate size */,
/*@out@*/ float* mod /* [nm] model */,
/*@out@*/ float* dat /* [nd] data */,
float* tmp /* [nt] intermediate */)
/*< Chains two operators, computing oper1{oper2{mod}}
or its adjoint. The tmp array is used for temporary storage. >*/
{
...
}

Input parameters

oper1 outer operator, L1 (sf operator).

oper2 inner operator, L2 (sf operator).
adj adjoint flag (bool). If true, then the adjoint is computed, i.e. m ← (L2 L1 )∗ d or
m ← m + (L2 L1 )∗ d.
add addition flag (bool). If true, then d ← d + (L2 L1 )m or m ← m + (L2 L1 )∗ d is
computed.
nm size of the model mod (int).
nd size of the data dat (int).
nt size of the intermediate result tmp (int).
mod the model, m (float*).
dat the data, d (float*).
tmp intermediate result (float*).

7.9.2 sf cchain

The same as sf chain but for complex data.

7.9. CHAINING LINEAR OPERATORS (CHAIN.C) 171

Call

sf_cchain (oper1,oper2, adj,add, nm,nd,nt, mod, dat, tmp);

Definition

void sf_cchain( sf_coperator oper1 /* outer operator */,

sf_coperator oper2 /* inner operator */,
bool adj /* adjoint flag */,
bool add /* addition flag */,
int nm /* model size */,
int nd /* data size */,
int nt /* intermediate size */,
/*@out@*/ sf_complex* mod /* [nm] model */,
/*@out@*/ sf_complex* dat /* [nd] data */,
sf_complex* tmp /* [nt] intermediate */)
/*< Chains two complex operators, computing oper1{oper2{mod}}
or its adjoint. The tmp array is used for temporary storage. >*/
{
...
}

Input parameters

oper1 outer operator, L1 (sf coperator).

oper2 inner operator, L2 (sf coperator).
adj adjoint flag (bool). If true, then the adjoint is computed, i.e. m ← (L2 L1 )∗ d or
m ← m + (L2 L1 )∗ d.
add addition flag (bool). If true, then d ← d + (L2 L1 )m or m ← m + (L2 L1 )∗ d is
computed.
nm size of the model mod (int).
nd size of the data dat (int).
nt size of the intermediate result tmp (int).
mod the model, m (sf complex*).
dat the data, d (sf complex*).
tmp intermediate result (sf complex*).
tmp the intermediate storage (sf complex*).
172 CHAPTER 7. LINEAR OPERATORS

7.9.3 sf array

For two operators L1 and L2 , it calculates:

d = Lm,

or its adjoint

m = L∗ d,

where

L d
L= 1 and d = 1
L2 d2

Call

sf_array (oper1,oper2, adj,add, nm,nd1,nd2, mod,dat1,dat2);

Definition

void sf_array( sf_operator oper1 /* top operator */,

sf_operator oper2 /* bottom operator */,
bool adj /* adjoint flag */,
bool add /* addition flag */,
int nm /* model size */,
int nd1 /* top data size */,
int nd2 /* bottom data size */,
/*@out@*/ float* mod /* [nm] model */,
/*@out@*/ float* dat1 /* [nd1] top data */,
/*@out@*/ float* dat2 /* [nd2] bottom data */)
/*< Constructs an array of two operators,
computing {oper1{mod},oper2{mod}} or its adjoint. >*/
{
...
}

Input parameters

oper1 top operator, L1 (sf operator).

7.9. CHAINING LINEAR OPERATORS (CHAIN.C) 173

oper2 bottom operator, L2 (sf operator).

adj adjoint flag (bool). If true, then the adjoint is computed, i.e. m ← L∗ d or
m ← m + L∗ d.
add addition flag (bool). If true, then d ← d + Lm or m ← m + L∗ d is computed.
nm size of the model, mod (int).
nd1 size of the top data, dat1 dat1 (int).
nd2 size of the bottom data, dat2 (int).
mod the model, m (float*).
dat1 the top data, d1 (float*).
dat2 the bottom data, d2 (float*).

7.9.4 sf normal

Applies a normal operator (self-adjoint) to the model, i.e. it calculates

d = LL∗ m.

Call

sf_normal (oper, add, nm,nd, mod,dat,tmp);

Definition

void sf_normal (sf_operator oper /* operator */,

bool add /* addition flag */,
int nm /* model size */,
int nd /* data size */,
float *mod /* [nd] model */,
float *dat /* [nd] data */,
float *tmp /* [nm] intermediate */)
/*< Applies a normal operator (self-adjoint) >*/
{
...
}
174 CHAPTER 7. LINEAR OPERATORS

Input parameters

oper the operator, L (sf operator).

add addition flag (bool). If true, then d ← d + LL∗ m.
nm size of the model, mod (int).
nd size of the data, dat (int).
mod the model, m (float*).
dat the data, d (float*).
tmp the intermediate result (float*).

7.9.5 sf chain3

Chains three operators L1 , L2 and L3 :

d = (L3 L2 L1 )m.

Its adjoint is

m = (L3 L2 L1 )∗ d = L∗1 L∗2 L∗3 d.

Call

sf_chain3 (oper1,oper2,oper3, adj,add, nm,nt1,nt2,nd, mod,dat,tmp1,tmp2);

Definition

void sf_chain3 (sf_operator oper1 /* outer operator */,

sf_operator oper2 /* middle operator */,
sf_operator oper3 /* inner operator */,
bool adj /* adjoint flag */,
bool add /* addition flag */,
int nm /* model size */,
int nt1 /* inner intermediate size */,
int nt2 /* outer intermediate size */,
int nd /* data size */,
float* mod /* [nm] model */,
float* dat /* [nd] data */,
7.10. DOT PRODUCT TEST FOR LINEAR OPERATORS (DOTTEST.C) 175

float* tmp1 /* [nt1] inner intermediate */,

float* tmp2 /* [nt2] outer intermediate */)
/*< Chains three operators, computing oper1{oper2{poer3{{mod}}} or its adjoint.
The tmp1 and tmp2 arrays are used for temporary storage. >*/
{
...
}

Input parameters

oper1 outer operator (sf operator).

oper2 middle operator (sf operator).
oper3 inner operator (sf operator).
adj adjoint flag (bool). If true, then the adjoint is computed, i.e. m ← L∗1 L∗2 L∗3 d or
m ← m + L∗1 L∗2 L∗3 d.
add addition flag (bool). If true, then d ← d + L3 L2 L1 m or m ← m + L∗1 L∗2 L∗3 d.
nm size of the model, mod (int).
nt1 inner intermediate size (int).
nt2 outer intermediate size (int).
ny size of the data, dat (int).
mod the model, x (float*).
dat the data, d (float*).
tmp1 the inner intermediate result (float*).
tmp2 the outer intermediate result (float*).

7.10 Dot product test for linear operators (dottest.c)

Performs the dot product test (see p. 156), to check whether the adjoint of the operator is
coded incorrectly. Coding is incorrect if any of
hLm1 , d2 i = hm1 , L∗ d2 i or hd1 + Lm1 , d2 i = hm1 , m2 + L∗ d2 i
does not hold (within machine precision). m1 and d2 are random vectors.

7.10.1 sf dot test

dot1[0] must equal dot1[1] and dot2[0] must equal dot2[1] for the test to pass.
176 CHAPTER 7. LINEAR OPERATORS

Call

sf_dot_test (oper, nm, nd, dot1, dot2);

Definition

void sf_dot_test(sf_operator oper /* linear operator */,

int nm /* model size */,
int nd /* data size */,
float* dot1 /* first output */,
float* dot2 /* second output */)
{
...
}

Input parameters

oper the linear operator, whose adjoint is to be tested (sf operator).

nm size of the models (int).
nd size of the data (int).
dot1 first output dot product (float*).
dot2 second output dot product (float*).
Chapter 8

Data analysis

8.1 FFT (kiss fftr.c)

8.1.1 sf kiss fftr alloc

Allocates the memory for the FFT and returns an object of type kiss fftr cfg.

Call

kiss_fftr_alloc(nfft, inverse_fft, mem, lenmem);

Definition

kiss_fftr_cfg kiss_fftr_alloc(int nfft,int inverse_fft,void * mem,size_t * lenmem)

{
...
}

Input parameters

nfft length of the forward FFT (int).

inverse fft length of the inverse FFT (int).
mem pointer to the memory allocated for FFT (void*).
lenmem size of the allocated memory (size t).

177
178 CHAPTER 8. DATA ANALYSIS

Input parameters

st an object for FFT (kiss fftr cfg).

8.1.2 kiss fftr

Performs the forward FFT on the input timedata which is real, and stores the transformed
complex freqdata in the location specified in the input.

Call

kiss_fftr( st, timedata, freqdata)

Definition

void kiss_fftr(kiss_fftr_cfg st,const kiss_fft_scalar timedata,kiss_fft_cpx fr

eqdata)
{
/* input buffer timedata is stored row-wise */

/* The real part of the DC element of the frequency spectrum in st->tmpbuf

* contains the sum of the even-numbered elements of the input time sequence
* The imag part is the sum of the odd-numbered elements
*
* The sum of tdc.r and tdc.i is the sum of the input time sequence.
* yielding DC of input time sequence
* The difference of tdc.r - tdc.i is the sum of the input (dot product) [1,-1,1,-1.
* yielding Nyquist bin of input time sequence
*/

...
}

Input parameters

st an object for the forward FFT (kiss fftr cfg).

timedata time data which is to be transformed (const kiss fft scalar*).
freqdata location where the transformed data is to be stored (kiss fft cpx*).
8.2. COSINE WINDOW WEIGHTING FUNCTION (TENT2.C) 179

8.1.3 kiss fftri

Performs the inverse FFT on the input timedata which is real, and stores the transformed
complex freqdata in the location specified in the input.

Call

kiss_fftri(st, freqdata, timedata);

Definition

void kiss_fftri(kiss_fftr_cfg st,const kiss_fft_cpx freqdata,kiss_fft_scalar t

imedata)
/* input buffer timedata is stored row-wise */
{
...
}

Input parameters

st an object for the inverse FFT (kiss fftr cfg).

timedata location where the inverse time data is to be stored (const kiss fft scalar*).
freqdata complex frequency data which is to be inverse transformed (kiss fft cpx*).

8.2 Cosine window weighting function (tent2.c)

8.2.1 sf tent2

Sets the weights for the windows defined for each dimension.

Call

sf_tent2 (dim, nwind, windwt);

180 CHAPTER 8. DATA ANALYSIS

Definition

void sf_tent2 (int dim /* number of dimensions */,

const int* nwind /* window size [dim] */,
float* windwt /* window weight */)
/*< define window weight >*/
{
...
}

Input parameters

dim number of dimensions (int).

nwind window size [dim] (const int).
windwt window weight (const int).

8.3 Anisotropic diffusion, 2-D (impl2.c)

8.3.1 sf impl2 init

Initializes the required variables and allocates the required space for the anisotropic diffu-
sion.

Call

void sf_impl2_init (r1,r2, n1_in,n2_in, tau, pclip,

up_in, verb_in, dist_in, nsnap_in, snap_in);

8.3.3 sf impl2 set

Computes the weighting function for the anisotropic diffusion.

Call

sf_impl2_set(x);

Definition

void sf_impl2_set(float ** x)
/*< compute weighting function >*/
{
...
}

Input parameters

x data (float**).

8.3.4 sf impl2 set

Applies the anisotropic diffusion.

Call

sf_impl2_apply (x, set, adj);

Definition

void sf_impl2_apply (float **x, bool set, bool adj)

/*< apply diffusion >*/
{
...
}
8.3. ANISOTROPIC DIFFUSION, 2-D (IMPL2.C) 183

Input parameters

x data (float*).
set whether the weighting function needs to be computed (bool).
adj whether the weighting function needs to be applied (bool).

8.3.5 sf impl2 lop

Applies either x or y as linear operator to y or x and output x or y, depending on whether

adj is true or false.

Call

sf_impl2_lop (adj, add, nx, ny, x, y);

Definition

void sf_impl2_lop (bool adj, bool add, int nx, int ny, float* x, float* y)
/*< linear operator >*/
{
...
}

Input parameters

adj a parameter to determine whether the output is y or x (bool).

add a parameter to determine whether the input needs to be zeroed (bool).
nx size of x (int).
ny size of y (int).
x data or operator, depending on whether adj is true or false (sf complex*).
y data or operator, depending on whether adj is true or false (sf complex*).
184 CHAPTER 8. DATA ANALYSIS
Chapter 9

Filtering

9.1 Frequency-domain filtering (freqfilt.c)

9.1.1 sf freqfilt init

Initializes the required variables and allocates the required space for frequency filtering.

Call

sf_freqfilt_init(nfft1, nw1);

Definition

void sf_freqfilt_init(int nfft1 /* time samples (possibly padded) */,

int nw1 /* frequency samples */)
/*< Initialize >*/
{
...
}

Input parameters

nfft1 number of time samples (int).

nw1 number of frequency samples (int).

185
186 CHAPTER 9. FILTERING

9.1.2 sf freqfilt set

Initializes a zero phase filter.

Call

sf_freqfilt_set(filt);

Definition

void sf_freqfilt_set(float filt / frequency filter [nw] */)

/*< Initialize filter (zero-phase) >*/
{
...
}

Input parameters

filt the frequency filter (float*).

9.1.3 sf freqfilt cset

Initializes a non-zero phase filter (filter with complex values).

Call

sf_freqfilt_cset (filt);

Definition

void sf_freqfilt_cset(kiss_fft_cpx filt / frequency filter [nw] */)

/*< Initialize filter >*/
{
...
}
9.1. FREQUENCY-DOMAIN FILTERING (FREQFILT.C) 187

Input parameters

filt the frequency filter. Must be of type kiss fft cpx*.

9.1.4 sf freqfilt close

Frees the space allocated by sf freqfilt init.

Call

sf_freqfilt_close();

Definition

void sf_freqfilt_close(void)
/*< Free allocated storage >*/
{
...
}

9.1.5 sf freqfilt

Applies the frequency filtering to the input data.

Call

sf_freqfilt(nx, x);

Definition

void sf_freqfilt(int nx, float* x)

/*< Filtering in place >*/
{
...
}
188 CHAPTER 9. FILTERING

Input parameters

nx data length (int).

x the data (float*).

9.1.6 sf freqfilt lop

Applies the frequency filtering to either y or x, depending on whether adj is true of false
and then applies the result to x or y as a linear operator.

Call

sf_freqfilt_lop (adj, add, nx, ny, x, y);

Definition

void sf_freqfilt_lop (bool adj, bool add, int nx, int ny, float* x, float* y)
/*< Filtering as linear operator >*/
{
...
}

Input parameters

adj a parameter to determine whether frequency filter applied to y or x. Must be of

type bool.
add a parameter to determine whether the input needs to be zeroed (bool).
nx size of x (int).
ny size of y (int).
x data or operator, depending on whether adj is true or false (float*).
y data or operator, depending on whether adj is true or false (float*).
9.2. FREQUENCY-DOMAIN FILTERING IN 2-D (FREQFILT.C) 189

9.2 Frequency-domain filtering in 2-D (freqfilt.c)

9.2.1 sf freqfilt2 init

Initializes the required variables and allocates the required space for frequency filtering for
2D data.

Call

sf_freqfilt2_init (n1, n2, nw1);

Definition

void sf_freqfilt2_init(int n1, int n2 /* data dimensions */,

int nw1 /* number of frequencies */)
/*< initialize >*/
{
...
}

Input parameters

n1 number of time samples in first dimension (int).

n2 number of time samples in second dimension (int).
nw1 number of frequencies (int).

9.2.2 sf freqfilt2 set

Initializes a zero phase filter.

Call

sf_freqfilt2_set (filt);

Input parameters

filt the frequency filter (float**).

190 CHAPTER 9. FILTERING

Definition

void sf_freqfilt2_set(float **filt)

/*< set the filter >*/
{
...
}

9.2.3 sf freqfilt2 close

Frees the space allocated by sf freqfilt2 init.

Call

sf_freqfilt2_close();

Definition

void sf_freqfilt2_close(void)
/*< free allocated storage >*/
{
...
}

9.2.4 sf freqfilt2 spec

This function 2D spectrum of the input data.

Call

sf_freqfilt2_spec (x, y);

Definition

void sf_freqfilt2_spec (const float* x /* input */, float** y /* spectrum */)

/*< compute 2-D spectrum >*/
{
9.2. FREQUENCY-DOMAIN FILTERING IN 2-D (FREQFILT.C) 191

...
}

Input parameters

x the data (const float*).

y the data (float**).

9.2.5 sf freqfilt2 lop

Applies the frequency filtering to either y or x, depending on whether adj is true of false
and then applies the result to x or y as a linear operator.

Call

sf_freqfilt2_lop (adj, add, nx, ny, x, y);

Definition

void sf_freqfilt2_lop (bool adj, bool add, int nx, int ny, float* x, float* y)
/*< linear filtering operator >*/
{
...
}

Input parameters

adj a parameter to determine whether frequency filter applied to y or x (bool).

add a parameter to determine whether the input needs to be zeroed (bool).
nx size of x (int).
ny size of y (int).
x data or operator, depending on whether adj is true or false (float*).
y data or operator, depending on whether adj is true or false (float*).
192 CHAPTER 9. FILTERING

9.3 Helical convolution (helicon.c)

9.3.1 sf helicon init

Initializes an object of type sf filter to be used in the linear operator function.

Call

sf_helicon_init(bb);

Definition

void sf_helicon_init (sf_filter bb)

/*< Initialized with the filter. >*/
{
...
}

Input parameters

bb the filter object (sf filter).

9.3.2 sf helicon lop

Does the helical convolution. It applies the filter to either yy or xx, depending on whether
adj is true of false and then applies the result to xx or yy as a linear operator.

Call

sf_helicon_lop (adj, add, nx, ny, xx, yy);

Definition

void sf_helicon_lop( bool adj, bool add,

int nx, int ny, float* xx, float*yy)
9.4. HELICAL FILTER DEFINITION AND ALLOCATION (HELIX.C) 193

/< linear operator >/

{
...
}

Input parameters

adj a parameter to determine whether the filter is applied to yy or xx (bool).

add a parameter to determine whether the input needs to be zeroed (bool).
nx size of xx (int).
ny size of yy (int).
xx data or operator, depending on whether adj is true or false (float*).
yy data or operator, depending on whether adj is true or false (float*).

9.4 Helical filter definition and allocation (helix.c)

9.4.1 sf allocatehelix

Initializes the filter.

Call

aa = sf_allocatehelix(nh);

Definition

sf_filter sf_allocatehelix( int nh)

/*< allocation >*/
{
...
}

Input parameters

nh filter length (int).

194 CHAPTER 9. FILTERING

Output

aa object for helix filter. It is of type sf filter.

9.4.2 sf deallocatehelix

Frees the space allocated by sf allocatehelix for the filter.

Definition

sf_deallocatehelix (aa);

Call

void sf_deallocatehelix( sf_filter aa)

/*< deallocation >*/
{
...
}

Input parameters

aa the filter (sf filter).

9.4.3 sf displayhelix

Displays the filter.

Call

sf_displayhelix(aa);

Definition

void sf_displayhelix (sf_filter aa)

/*< display filter >*/
9.5. RECURSIVE CONVOLUTION (POLYNOMIAL DIVISION) (RECFILT.C) 195

{
...
}

Input parameters

aa the filter (sf filter).

9.5 Recursive convolution (polynomial division) (recfilt.c)

9.5.1 sf recfilt init

Initializes the linear filter by allocating the required space and initializing the required
variables.

Call

sf_recfilt_init(nd, nb, bb);

Definition

void sf_recfilt_init( int nd /* data size */,

int nb /* filter size */,
float* bb /* filter [nb] */)
/*< initialize >*/
{
...
}

Input parameters

nd size of the data which is to be filtered (int).

nb size of the filter (int).
bb filter which is to be applied (float*).
196 CHAPTER 9. FILTERING

9.5.2 sf recfilt lop

Applies the linear operator to xx (or yy) and the result is applied to yy (or xx), depending
on whether adj is false or true, with the operator initialized by sf recfilt init.

Call

sf_recfilt_lop (adj, add, nx, ny, xx, yy);

Definition

void sf_recfilt_lop( bool adj, bool add, int nx, int ny, float* xx, float*yy)
/*< linear operator >*/
{
...
}

Input parameters

adj a parameter to determine whether filter is applied to yy or xx (bool).

9.5.3 sf recfilt close

Frees the space allocated by sf recfilt init.

Call

sf_recfilt_close ();
9.6. COSINE FOURIER TRANSFORM (COSFT.C) 197

Definition

void sf_recfilt_close (void)

/*< free allocated storage >*/
{
...
}

9.6 Cosine Fourier transform (cosft.c)

9.6.1 sf cosft

Makes preparations for the cosine Fourier transform, by allocating the required spaces.

Call

sf_cosft_init(n1);

Definition

void sf_cosft_init(int n1)

/*< initialize >*/
{
...
}

Input parameters

n1 in length of the input (int).

9.6.2 sf cosft close

Frees the allocated space.

Call

sf_cosft_close();
198 CHAPTER 9. FILTERING

Definition

void sf_cosft_close(void)
/*< free allocated storage >*/
{
...
}

9.6.3 sf cosft frw

This function performs the forward cosine Fourier transform.

Call

sf_cosft_frw (q, o1, d1);

Definition

void sf_cosft_frw (float q / data */,

int o1 /* first sample */,
int d1 /* step */)
/*< forward transform >*/
{
...
}

Input parameters

q input data (float).

o1 first sample of the input data (int).
d1 step size (int).

9.6.4 sf cosft inv

This function performs the forward cosine Fourier transform.

9.6. COSINE FOURIER TRANSFORM (COSFT.C) 199

Call

sf_cosft_inv (q, o1, d1);

Definition

void sf_cosft_inv (float q / data */,

int o1 /* first sample */,
int d1 /* step */)
/*< inverse transform >*/
{
...
}

Input parameters

q input data (float).

o1 first sample of the input data (int).
d1 step size (int).
200 CHAPTER 9. FILTERING
Chapter 10

Solvers

10.1 Banded matrix solver (banded.c)

10.1.1 sf banded init

Initializes an object of type sf bands for the banded matrix, that is, it allocates the
required spaces and defines initializes the variables.

Call

slv = sf_banded_init (n, band);

Definition

sf_bands sf_banded_init (int n /* matrix size */,

int band /* band size */)
/*< initialize >*/
{
...
}

Input parameters

n size of the banded matrix (int).

band size of the band (int).

201
202 CHAPTER 10. SOLVERS

Output

slv an object of type sf bands.

10.1.2 sf banded define

Defines the banded matrix.

void sf_banded_const_define_reflect (sf_bands slv,

float diag /* diagonal */,
const float* offd /* off-diagonal [band] */)
/*< define matrix with constant diagonal coefficients
and reflecting b.c. >*/
{
...
}
204 CHAPTER 10. SOLVERS

Input parameters

slv an object of type sf bands.

diag diagonal entries in the matrix (float**).
offd off-diagonal entries in the matrix (float**).

10.1.5 sf banded solve

Inverts the banded matrix.

Call

sf_banded_solve (slv, b);

Definition

void sf_banded_solve (const sf_bands slv, float* b)

/*< invert (in place) >*/
{
...
}

Input parameters

slv an object of type sf bands. Must be of type const sf bands

b the inverted matrix values (float*).

10.1.6 sf banded close

Frees the space allocated for the sf bands object.

Call

sf_banded_close (slv);
10.2. CLAERBOUT’S CONJUGATE-GRADIENT ITERATION (CGSTEP.C) 205

Definition

void sf_banded_close (sf_bands slv)

/*< free allocated storage >*/
{
...
}

Input parameters

slv an object of type sf stack.

10.2 Claerbout’s conjugate-gradient iteration (cgstep.c)

10.2.1 sf cgstep

Evaluates one step of the conjugate gradient method iteration.

Call

sf_cgstep(forget, nx, ny, x, g, rr, gg);

Definition

void sf_cgstep( bool forget /* restart flag */,

int nx, int ny /* model size, data size */,
float* x /* current model [nx] */,
const float* g /* gradient [nx] */,
float* rr /* data residual [ny] */,
const float* gg /* conjugate gradient [ny] */)
/*< Step of conjugate-gradient iteration. >*/
{
...
}

Input parameters

forget restart flag (bool).

206 CHAPTER 10. SOLVERS

nx size of the model (int).

ny size of the data (int).
g the gradient (const float*).
rr the data residual (float*).
gg the conjugate gradient (const float*).

Output

c.r real part of the complex number. It is of type double.

10.2.2 sf cgstep close

Frees the space allocated for the conjugate gradient step calculation.

Call

sf_cgstep_close ();

Definition

void sf_cgstep_close (void)

/*< Free allocated space. >*/
{
...
}

10.3 Conjugate-gradient with shaping regularization (conjgrad.c)

10.3.1 sf conjgrad init

Initializes the conjugate gradient solver by initializing the required variables and allocating
the required space.

Call

sf_conjgrad_init (np, nx, nd, nr, eps, tol, verb, hasp0);

10.3. CONJUGATE-GRADIENT WITH SHAPING REGULARIZATION (CONJGRAD.C)207

Definition

void sf_conjgrad_init(int np1 /* preconditioned size */,

int nx1 /* model size */,
int nd1 /* data size */,
int nr1 /* residual size */,
float eps1 /* scaling */,
float tol1 /* tolerance */,
bool verb1 /* verbosity flag */,
bool hasp01 /* if has initial model */)
/*< solver constructor >*/
{
...
}

Input parameters

np1 the size of the preconditioned data (int).

nx1 size of the model (int).
nd1 size of the data (int).
nr1 size of the residual (int).
eps1 the scaling parameter (float).
tol1 tolerance to the error in the solution (float).
verb1 verbosity flag (bool).
hasp01 if there is a initial model (bool).

10.3.2 sf conjgrad close

Frees the space allocated for the conjugate gradient solver by sf conjgrad init.

Definition

sf_conjgrad_close();
208 CHAPTER 10. SOLVERS

Definition

void sf_conjgrad_close(void)
/*< Free allocated space >*/
{
...
}

10.3.3 sf conjgrad

Applies the conjugate gradient solver with the shaping filter to the input data.

Definition

sf_conjgrad (prec, oper, shape, p, x, dat, niter);

Definition

void sf_conjgrad(sf_operator prec /* data preconditioning */,

sf_operator oper /* linear operator */,
sf_operator shape /* shaping operator */,
float* p /* preconditioned model */,
float* x /* estimated model */,
float* dat /* data */,
int niter /* number of iterations */)
/*< Conjugate gradient solver with shaping >*/
{
...
}

Input parameters

prec preconditioning operator (sf operator).

oper the operator (sf operator).
shape the shaping operator (sf operator).
p the preconditioned model (float*).
x estimated model (float*).
10.4. CG WITH PRECONDITIONING (CONJPREC.C) 209

dat the data (float*).

niter number of iterations (int).

10.4 Conjugate-gradient with preconditioning (conjprec.c)

10.4.1 sf conjprec init

Initializes the conjugate gradient solver, that is, it sets the required variables and allocates
the required memory.

Call

sf_conjprec_init(int nx, nr, eps, tol, verb, hasp0;

Definition

void sf_conjprec_init(int nx /* preconditioned size */,

int nr /* residual size */,
float eps /* scaling */,
float tol /* tolerance */,
bool verb /* verbosity flag */,
bool hasp0 /* if has initial model */)
/*< solver constructor >*/
{
...
}

Input parameters

nx1 the size of the preconditioned data (int).

nr1 size of the residual (int).
eps the scaling parameter (float).
tol1 tolerance to the error in the solution (float).
verb1 verbosity flag (bool).
hasp01 if there is a initial model (bool).
210 CHAPTER 10. SOLVERS

10.4.2 sf conjprec close

Frees the allocated space for the conjugate gradient solver.

Call

sf_conjprec_close();

Definition

void sf_conjprec_close(void)
/*< Free allocated space >*/
{
...
}

10.4.3 sf conjprec

Applies the conjugate gradient method after preconditioning to the input data.

Call

void sf_conjprec(oper, prec, p, x, dat, niter);

Definition

void sf_conjprec(sf_operator oper /* linear operator */,

sf_operator2 prec /* preconditioning */,
float* p /* preconditioned */,
float* x /* model */,
const float* dat /* data */,
int niter /* number of iterations */)
/*< Conjugate gradient solver with preconditioning >*/
{
...
}
10.5. CG ITERATION (COMPLEX DATA) (CGSTEP.C) 211

Input parameters

oper the operator (sf operator).

prec preconditioning operator (sf operator2).
p the preconditioned data (float*).
x model (float*).
dat the data (const float*).
niter number of iterations (int).

10.5 Claerbout’s conjugate-gradient iteration for complex numbers (cg-

step.c)

10.5.1 sf ccgstep

Evaluates one step of the Claerbout’s conjugate-gradient iteration for complex numbers.

Call

sf_ccgstep(forget, nx, ny, x, g, rr, gg);

Definition

void sf_ccgstep( bool forget /* restart flag */,

int nx /* model size */,
int ny /* data size */,
sf_complex* x /* current model [nx] */,
const sf_complex* g /* gradient [nx] */,
sf_complex* rr /* data residual [ny] */,
const sf_complex* gg /* conjugate gradient [ny] */)
/*< Step of Claerbout’s conjugate-gradient iteration for complex operators.
The data residual is rr = A x - dat
>*/
{
...
}
212 CHAPTER 10. SOLVERS

Input parameters

forget restart flag (bool).

nx size of the model (int).
ny size of the data (int).
x current model (sf complex*).
g the gradient. Must be of type const sf complex*.
rr the data residual (sf complex*).
gg the conjugate gradient. Must be of type const sf complex*.

10.5.2 sf ccgstep close

Frees the space allocated for sf ccgstep.

Call

sf_ccgstep_close();

Definition

void sf_ccgstep_close (void)

/*< Free allocated space. >*/
{
...
}

10.5.3 dotprod

Returns the dot product of two complex numbers or the sum of the dot products if the are
two arrays of complex numbers.

Call

prod = dotprod (n, x, y);

void sf_cconjgrad_close(void)
/*< Free allocated space >*/
{
...
}

10.6.4 sf cconjgrad

Applies the complex conjugate gradient solver with the shaping filter to the input data.

Definition

sf_cconjgrad (prec, oper, shape, p, x, dat, niter);

216 CHAPTER 10. SOLVERS

Definition

void sf_cconjgrad(sf_coperator prec /* data preconditioning */,

sf_coperator oper /* linear operator */,
sf_coperator shape /* shaping operator */,
sf_complex* p /* preconditioned model */,
sf_complex* x /* estimated model */,
const sf_complex* dat /* data */,
int niter /* number of iterations */)
/*< Conjugate gradient solver with shaping >*/
{
...
}

Input parameters

prec preconditioning operator (sf coperator).

oper the operator (sf coperator).
shape the shaping operator (sf coperator).
p the preconditioned model (sf complex*).
x estimated model (sf complex*).
dat the data (sf complex*).
niter number of iterations (int).

10.7 Conjugate-direction iteration (cdstep.c)

10.7.1 sf cdstep init

Creates a list for internal storage.

Call

sf_cdstep_init();
10.7. CONJUGATE-DIRECTION ITERATION (CDSTEP.C) 217

Definition

void sf_cdstep_init(void)
/*< initialize internal storage >*/
{
...
}

10.7.2 sf cdstep close

Frees the space allocated for internal storage by sf cdstep init.

Call

sf_cdstep_close();

Definition

void sf_cdstep_close(void)
/*< free internal storage >*/
{
...
}

10.7.3 sf cdstep

Calculates one step for the conjugate direction iteration, that is, it calculates the new
conjugate gradient for the new line search direction.

Call

int sf_llist_depth(sf_list l)
/*< return list depth >*/
{
...
}

Input parameters

l a list (sf list).

Output

l->depth depth (length) of the list (int).

10.8.4 sf llist add

Adds an entry to the list.

Call

sf_llist_add(l, g, gn);

Definition

void sf_llist_add(sf_list l, float *g, double gn)

/*< add an entry in the list >*/
{
...
}
222 CHAPTER 10. SOLVERS

Input parameters

l a list (sf list).

g value which is to be entered in the list (float*).
gn name or key of the value which is to be entered in the list (double).

10.8.5 sf llist down

Extracts an entry from the list.

Call

sf_llist_down(l, g, gn);

Definition

void sf_llist_down(sf_list l, float **g, double *gn)

/*< extract and entry from the list >*/
{
...
}

Input parameters

l a list (sf list).

g location where extracted value is to be stored (float**).
gn location where the name or key of the value is to be stored (double).

10.8.6 sf llist close

Frees the space allocated for the sf list object (list).

Call

sf_ccdstep_close();

Definition

void sf_ccdstep_close(void)
/*< free internal storage >*/
{
...
}

10.9.3 sf ccdstep

Calculates one step for the conjugate direction iteration, that is, it calculates the new
conjugate gradient for the new line search direction. It works like sf cdstep but for
complex numbers.

Call

sf_ccdstep (forget, nx, ny, x, g, rr, gg);

10.9. CONJUGATE-DIRECTION ITERATION FOR COMPLEX NUMBERS (CCDSTEP.C)225

Definition

void sf_ccdstep(bool forget /* restart flag */,

int nx /* model size */,
int ny /* data size */,
sf_complex* x /* current model [nx] */,
const sf_complex* g /* gradient [nx] */,
sf_complex* rr /* data residual [ny] */,
const sf_complex* gg /* conjugate gradient [ny] */)
/*< Step of conjugate-direction iteration.
The data residual is rr = A x - dat>*/
{
...
}

Input parameters

forget restart flag (bool).

nx model size (int).
ny data size (int).
x current model (sf complex*).
g gradient. Must be of type const sf complex*.
rr data residual (sf complex*).
gg conjugate gradient. Must be of type const sf complex*.

10.9.4 saxpy

Multiplies a given complex number with an array of complex numbers and stores the
cumulative products in another array.

Call

saxpy (n, a, x, y);

l an empty list. Must be of type sf clist.

10.10.2 sf clist rewind

Rewinds the list, that is, it makes the pointer to the current position equal to the first
entry position.

Call

sf_clist_rewind(l);
228 CHAPTER 10. SOLVERS

Definition

void sf_clist_rewind(sf_clist l)
/*< return to the start >*/
{
...
}

Input parameters

l a list. Must be of type sf clist.

10.10.3 sf clist depth

Returns the depth (length) of the list.

Input parameters

l a list. Must be of type sf clist.

Output

l->depth depth (length) of the list (int).

10.10.4 sf clist add

Adds an entry to the list.

Call

sf_clist_depth(l);

Definition

int sf_clist_depth(sf_clist l)
/*< return list depth >*/
{
10.10. LINKED LIST FOR CD-TYPE METHODS (COMPLEX DATA) (CLIST.C) 229

...
}

Call

sf_clist_add(l, g, gn);

Definition

void sf_clist_add(sf_clist l, sf_complex *g, double gn)

/*< add an entry in the list >*/
{
...
}

Input parameters

l a list. Must be of type sf clist.

g value which is to be entered in the list. Must be of type extttsf complex*.
gn name or key of the value which is to be entered in the list (double).

10.10.5 sf llist down

Extracts an entry from the list.

Call

sf_clist_down(l, g, gn);

Definition

void sf_clist_down(sf_clist l, sf_complex **g, double *gn)

/*< extract and entry from the list >*/
{
...
}
230 CHAPTER 10. SOLVERS

Input parameters

l a list. Must be of type sf clist.

g location where extracted value is to be stored (sf complex**).
gn location where the name or key of the value is to be stored (double*).

10.10.6 sf clist close

Frees the space allocated for the sf clist object (list).

Call

sf_clist_close(l);

Definition

void sf_clist_close(sf_clist l)
/*< free allocated storage >*/
{
...
}

Input parameters

l a list. Must be of type sf clist.

10.10.7 sf clist chop

Removes the first entry from the list.

Call

sf_clist_chop(l);
10.11. SOLVING QUADRATIC EQUATIONS (QUADRATIC.C) 231

Definition

void sf_clist_chop(sf_clist l)
/*< free the top entry from the list >*/
{
...
}

Input parameters

l a list. Must be of type sf clist.

10.11 Solving quadratic equations (quadratic.c)

Solves the equation ax2 + 2bx + c = 0 and returns the smallest positive root.

10.11.1 sf quadratic solve

Call

x1 = sf_quadratic_solve (a, b, c);

Definition

float sf_quadratic_solve (float a, float b, float c)

/*< solves a x^2 + 2 b x + c == 0 for smallest positive x >*/
{
...
}

Input parameters

a coefficient of x2 (float).
b coefficient of x (float).
c constant term (float).
232 CHAPTER 10. SOLVERS

Output

x1 solution of the quadratic equation (float).

10.12 Zero finder (fzero.c)

10.12.1 sf zero

Returns the zero (root) of the input function, f (x) in a specified interval [a, b].

Call

b = sf_zero ((*func)(float), a, b, fa, fb, toler, verb);

Definition

float sf_zero (float (func)(float) / function f(x) */,

float a, float b /* interval */,
float fa, float fb /* f(a) and f(b) */,
float toler /* tolerance */,
bool verb /* verbosity flag */)
/*< Return c such that f(c)=0 (within tolerance).
fa and fb should have different signs. >*/
{
float c, fc, m, s, p, q, r, e, d;
char method[256];

...
return b;
}

Input parameters

(*func)(float) function, the root of which is required. Must be of type sf double complex.
a lower limit of the interval (float).
b upper limit of the interval (float).
fa function value at the lower limit (float).
10.13. RUNGE-KUTTA ODE SOLVERS (RUNGE.C) 233

fb function value at the upper limit (float).

toler error tolerance (float).
verb verbosity flag (bool).

Output

b root of the input function. It is of type float.

10.13 Runge-Kutta ODE solvers (runge.c)

10.13.1 sf runge init

Initializes the required variables and allocates the required space for the ODE solver for
raytracing.

Call

sf_runge_init(dim1, n1, d1);

Definition

void sf_runge_init(int dim1 /* dimensionality */,

int n1 /* number of ray tracing steps */,
float d1 /* step in time */)
/*< initialize >*/
{
...
}

\subsubsection*{Input parameters}
\begin{desclist}{\tt }{\quad}[\tt dim1]
\setlength\itemsep{0pt}
\item[dim1] dimension of the ODE (\texttt{int}).
\item[n1] number of steps for performing the raytracing (\texttt{int}).
\item[d1] number of time steps for performing the raytracing (\texttt{int}).
\end{desclist}
234 CHAPTER 10. SOLVERS

\subsection{{sf\_runge\_close\_init}}
Frees all allocated memory.

\subsubsection*{Call}
\begin{verbatim}sf_runge_close();

Definition

void sf_runge_close(void)
/*< free allocated storage >*/
{
...
}

10.13.2 sf ode23

This function solves a first order ODE to calculate the travel time by raytracing.

Call

f = sf_ode23 (float t, tol, y, par,

(*rhs)(void*,float*,float*), (*term)(void*,float*));

Definition

float sf_ode23 (float t /* time integration */,

float* tol /* error tolerance */,
float* y /* [dim] solution */,
void* par /* parameters for function evaluation */,
void (*rhs)(void*,float*,float*)
/* RHS function */,
int (*term)(void*,float*)
/* function returning 1 if the ray needs to terminate */)
/*< ODE solver for dy/dt = f where f comes from rhs(par,y,f)
Note: Value of y is changed inside the function.>*/
{
10.13. RUNGE-KUTTA ODE SOLVERS (RUNGE.C) 235

...
}

Input parameters

t total time for integration (float).

tol error tolerance (float*).
y the solution, of dimension dim (float*).
par parameters to evaluate the rhs function (void*).
(*rhs)(void*,float*,float*) function which evaluates the rhs of the ODE. Its inputs
the parameters, the solution and the k’s in Runge-
Kutta scheme. Output is the rhs function f of the
ODE (void*).
(*term)(void*,float*) a function which returns 1 if the ray is to be terminated
(int).

Output

t1 total travel time for the ray. It is of type float.

10.13.3 sf ode23 step

Solves a first order ODE and returns trajectory calculated by raytracing.

Call

it = sf_ode23_step (y, par, (rhs)(void,float,float), (term)(void,float*), traj);

Definition

int sf_ode23_step (float* y /* [dim] solution */,

void* par /* parameters for function evaluation */,
void (*rhs)(void*,float*,float*)
/* RHS function */,
int (*term)(void*,float*)
/* function returning 1 if the ray needs to terminate */,
236 CHAPTER 10. SOLVERS

float** traj /* [nt+1][dim] - ray trajectory (output) */)

/*< ODE solver for dy/dt = f where f comes from rhs(par,y,f)
Note:
1. Value of y is changed inside the function.
2. The output code for it = ode23_step(...)
it=0 - ray traced to the end without termination
it>0 - ray terminated
The total traveltime along the ray is
nt*dt if (it = 0); it*dt otherwise
>*/
{
...
}

Input parameters

y the solution, of dimension dim (float*).

par parameters to evaluate the rhs function (void*).
(*rhs)(void*,float*,float*) function which evaluates the rhs of the ODE. Its inputs
the parameters, the solution and the k’s in Runge-
Kutta scheme. Output is the rhs function f of the
ODE (void*).
(*term)(void*,float*) a function which returns 1 if the ray is to be terminated
(int).
traj location where the output ray trajectory is to be stored
(float**).

Output

t1 total travel time for the ray. It is of type int.

10.14 Solver function for iterative least-squares optimization (tinysolver.c)

10.14.1 sf tinysolver

Performs the linear inversion for equations of the type Lx = y to compute the model x.
10.15. SOLVER FUNCTIONS FOR ITERATIVE LEAST-SQUARES OPTIMIZATION (BIGSOLVER.C)237

Call

sf_tinysolver (Fop, stepper, nm, nd, m, m0, d, niter);

Definition

void sf_tinysolver (sf_operator Fop /* linear operator */,

sf_solverstep stepper /* stepping function */,
int nm /* size of model */,
int nd /* size of data */,
float* m /* estimated model */,
const float* m0 /* starting model */,
const float* d /* data */,
int niter /* iterations */)
/*< Generic linear solver. Solves oper{x} =~ dat >*/
{
...
}

Input parameters

Fop a linear operator applied to the model x. Must be of type sf operator.

stepper a stepping function to perform updates on the initial model (sf solverstep).
nm size of the model (int).
nd size of the data (int).
m estimated model (int).
mo initial model (const float).
d data (const float).
niter number of iterations (int).

10.15 Solver functions for iterative least-squares optimization (bigsolver.c)

10.15.1 sf solver prec

Applies solves generic linear equations after preconditioning the data.

238 CHAPTER 10. SOLVERS

Call

sf_solver_prec (oper, solv, prec, nprec, nx, ny,

x, dat, niter, eps, "x0",x0, ..., "end");

Definition

void sf_solver_prec (sf_operator oper /* linear operator */,

sf_solverstep solv /* stepping function */,
sf_operator prec /* preconditioning operator */,
int nprec /* size of p */,
int nx /* size of x */,
int ny /* size of dat */,
float* x /* estimated model */,
const float* dat /* data */,
int niter /* number of iterations */,
float eps /* regularization parameter */,
... /* variable number of arguments */)
/*< Generic preconditioned linear solver.
---
Solves
oper{x} =~ dat
eps p =~ 0
where x = prec{p}
---
The last parameter in the call to this function should be "end".
Example:
---
sf_solver_prec (oper_lop,sf_cgstep,prec_lop,
np,nx,ny,x,y,100,1.0,"x0",x0,"end");
---
Parameters in ...:
...
"wt": float*: weight
"wght": sf_weight wght: weighting function
"x0": float*: initial model
"nloper": sf_operator: nonlinear operator
"mwt": float*: model weight
"verb": bool: verbosity flag
"known": bool*: known model mask
10.15. SOLVER FUNCTIONS FOR ITERATIVE LEAST-SQUARES OPTIMIZATION (BIGSOLVER.C)239

"nmem": int: iteration memory

"nfreq": int: periodic restart
"xmov": float**: model iteration
"rmov": float**: residual iteration
"err": float*: final error
"res": float*: final residual
"xp": float*: preconditioned model
>*/
{
...
}

Input parameters

oper the operator. Must be of type sf operator

solv the stepping function (sf solverstep).
prec preconditioning operator (sf operator).
nprec size of the preconditioned data (int).
nx size of the estimated model (int).
ny size of the data (int).
x estimated model (float*).
dat the data (const float*).
niter number of iterations (int).
eps regularization parameter (float).
... variable number of arguments.

10.15.2 sf csolver prec

Applies solves generic linear equations for complex data after preconditioning the data.

Call

sf_csolver_prec (oper, solv, prec, nprec, nx, ny,

x, dat, niter, eps, "x0",x0, ..., "end");
240 CHAPTER 10. SOLVERS

Definition

sf_csolver_prec (oper, solv, prec, nprec, nx, ny,

x, dat, niter, eps, niter, eps, "x0",x0, ..., "end");

Input parameters

oper the operator (sf coperator).

solv the stepping function (sf csolverstep).
prec preconditioning operator (sf coperator).
nprec size of the preconditioned data (int).
nx size of the estimated model (int).
ny size of the data (int).
x estimated model (sf complex*).
dat the data. Must be of type const sf complex*.
niter number of iterations (int).
eps regularization parameter (float).
... variable number of arguments.

10.15.3 sf solver reg

Applies solves generic linear equations after regularizing the data.

Call

sf_solver_reg (oper, solv, reg, nreg, nx, ny,

x, y, niter, eps, "x0",x0, ..., "end");

Definition

void sf_solver_reg (sf_operator oper /* linear operator */,

sf_solverstep solv /* stepping function */,
sf_operator reg /* regularization operator */,
int nreg /* size of reg{x} */,
int nx /* size of x */,
10.15. SOLVER FUNCTIONS FOR ITERATIVE LEAST-SQUARES OPTIMIZATION (BIGSOLVER.C)241

int ny /* size of dat */,

float* x /* estimated model */,
const float* dat /* data */,
int niter /* number of iterations */,
float eps /* regularization parameter */,
... /* variable number of arguments */)
/*< Generic regularized linear solver.
---
Solves
oper{x} =~ dat
eps reg{x} =~ 0
---
The last parameter in the call to this function should be "end".
Example:
---
sf_solver_reg (oper_lop,sf_cgstep,reg_lop,
np,nx,ny,x,y,100,1.0,"x0",x0,"end");
---
Parameters in ...:

"wt": float*: weight

"wght": sf_weight wght: weighting function
"x0": float*: initial model
"nloper": sf_operator: nonlinear operator
"nlreg": sf_operator: nonlinear regularization operator
"verb": bool: verbosity flag
"known": bool*: known model mask
"nmem": int: iteration memory
"nfreq": int: periodic restart
"xmov": float**: model iteration
"rmov": float**: residual iteration
"err": float*: final error
"res": float*: final residual
"resm": float*: final model residual
>*/
{
...
}
242 CHAPTER 10. SOLVERS

Input parameters

oper the linear operator (sf operator).

solv the stepping function (sf solverstep).
prec regularization operator (sf operator).
nreg size of the regularized data (int).
nx size of the estimated model (int).
ny size of the data (int).
x estimated model (float*).
dat the data (const float*).
niter number of iterations (int).
eps regularization parameter (float).
... variable number of arguments.

10.15.4 sf solver

Solves generic linear equations.

Call

sf_solver (oper, solv, nx, ny, x, dat, niter, "x0",x0, ..., "end");

Definition

void sf_solver (sf_operator oper /* linear operator */,

sf_solverstep solv /* stepping function */,
int nx /* size of x */,
int ny /* size of dat */,
float* x /* estimated model */,
const float* dat /* data */,
int niter /* number of iterations */,
... /* variable number of arguments */)
/*< Generic linear solver.
---
Solves
oper{x} =~ dat
10.15. SOLVER FUNCTIONS FOR ITERATIVE LEAST-SQUARES OPTIMIZATION (BIGSOLVER.C)243

---
The last parameter in the call to this function should be "end".
Example:
---
sf_solver (oper_lop,sf_cgstep,nx,ny,x,y,100,"x0",x0,"end");
---
Parameters in ...:
---
"wt": float*: weight
"wght": sf_weight wght: weighting function
"x0": float*: initial model
"nloper": sf_operator: nonlinear operator
"mwt": float*: model weight
"verb": bool: verbosity flag
"known": bool*: known model mask
"nmem": int: iteration memory
"nfreq": int: periodic restart
"xmov": float**: model iteration
"rmov": float**: residual iteration
"err": float*: final error
"res": float*: final residual
>*/
{
...
}

Input parameters

oper the operator (sf operator).

solv the stepping function (sf solverstep).
nx size of the estimated model (int).
ny size of the data (int).
x estimated model (float*).
dat the data (const float*).
niter number of iterations (int).
eps regularization parameter (float).
... variable number of arguments.
244 CHAPTER 10. SOLVERS

10.15.5 sf left solver

Solves generic linear equations for non-symmetric operators.

Call

sf_left_solver (oper, solv, nx, x, dat, niter, "x0",x0, ..., "end");

Definition

void sf_left_solver (sf_operator oper /* linear operator */,

sf_solverstep solv /* stepping function */,
int nx /* size of \texttt{x} and dat */,
float* x /* estimated model */,
const float* dat /* data */,
int niter /* number of iterations */,
... /* variable number of arguments */)
/*< Generic linear solver for non-symmetric operators.
---
Solves
oper{x} =~ dat
---
The last parameter in the call to this function should be "end".
Example:
---
sf_left_solver (oper_lop,sf_cdstep,nx,ny,x,y,100,"x0",x0,"end");
---
Parameters in ...:
---
"wt": float*: weight
"wght": sf_weight wght: weighting function
"x0": float*: initial model
"nloper": sf_operator: nonlinear operator
"mwt": float*: model weight
"verb": bool: verbosity flag
"known": bool*: known model mask
"nmem": int: iteration memory
"nfreq": int: periodic restart
"xmov": float**: model iteration
10.15. SOLVER FUNCTIONS FOR ITERATIVE LEAST-SQUARES OPTIMIZATION (BIGSOLVER.C)245

"rmov": float**: residual iteration

"err": float*: final error
"res": float*: final residual
>*/
{
...
}

Input parameters

oper the operator (sf operator).

solv the stepping function (sf solverstep).
nx size of the estimated model (int).
x estimated model (float*).
dat the data (const float*).
niter number of iterations (int).
eps regularization parameter (float).
... variable number of arguments.

10.15.6 sf csolver

Solves generic linear equations for complex data.

Call

sf_csolver (oper, solv, nx, ny, x, dat, niter, "x0",x0, ..., "end");

Definition

void sf_csolver (sf_coperator oper /* linear operator */,

sf_csolverstep solv /* stepping function */,
int nx /* size of x */,
int ny /* size of dat */,
sf_complex* x /* estimated model */,
const sf_complex* dat /* data */,
int niter /* number of iterations */,
246 CHAPTER 10. SOLVERS

... /* variable number of arguments */)

/*< Generic linear solver for complex data.
---
Solves
oper{x} =~ dat
---
The last parameter in the call to this function should be "end".
Example:
---
sf_csolver (oper_lop,sf_cgstep,nx,ny,x,y,100,"x0",x0,"end");
---
Parameters in ...:
---
"wt": float*: weight
"wght": sf_cweight wght: weighting function
"x0": sf_complex*: initial model
"nloper": sf_coperator: nonlinear operator
"verb": bool: verbosity flag
"known": bool*: known model mask
"nmem": int: iteration memory
"nfreq": int: periodic restart
"xmov": sf_complex**: model iteration
"rmov": sf_complex**: residual iteration
"err": float*: final error
"res": sf_complex*: final residual
>*/
{
...
}

Input parameters

oper the operator (sf coperator).

solv the stepping function (sf csolverstep).
nx size of the estimated model (int).
ny size of the data (int).
x estimated model (sf complex*).
dat the data. Must be of type const sf complex*.
niter number of iterations (int).
10.16. WEIGHTING FOR ITERATIVELY-REWEIGHTED LEAST SQUARES (IRLS.C)247

eps regularization parameter (float).

... variable number of arguments.

10.16 Weighting for iteratively-reweighted least squares (irls.c)

10.16.1 sf irls init

Allocates the space equal to the data size for iteratively-reweighted least squares.

Call

sf_irls_init(n);

Definition

void sf_irls_init(int n)
/*< Initialize with data size >*/
{
...
}

Input parameters

n size of the data (int).

10.16.2 sf irls close

Frees the space allocated for the iteratively-reweighted least squares by sf irls init.

Call

sf_irls_close();
248 CHAPTER 10. SOLVERS

Definition

void sf_irls_close(void)
/*< free allocated storage >*/
{
...
}

10.16.3 sf l1

Calculates the weights for L1 norm.

Call

sf_l1 (n, res, weight);

Definition

void sf_l1 (int n, const float res, float weight)

/*< weighting for L1 norm >*/
{
...
}

Input parameters

n size of the data (int).

res data (const float*).
weight weights for L1 norm (float*).

10.16.4 sf cauchy

Calculates the weights for Cauchy norm.

Call

sf_cauchy (n, res, weight);

10.17. TRIDIAGONAL MATRIX SOLVER (TRIDIAGONAL.C) 249

Definition

void sf_cauchy (int n, const float res, float weight)

/*< weighting for Cauchy norm >*/
{
...
}

Input parameters

n size of the data (int).

res data (const float*).
weight weights for Cauchy norm (float*).

10.17 Tridiagonal matrix solver (tridiagonal.c)

10.17.1 sf tridiagonal init

Initializes the object of the abstract data of type sf tris, which contains a matrix of size
n with separate variables for the diagonal and off-diagonal entries and also for the solution
to the matrix equation which it will be used to solve.

Call

slv = sf_tridiagonal_init (n);

Definition

sf_tris sf_tridiagonal_init (int n /* matrix size */)

/*< initialize >*/
{
...
}

Input parameters

n size of the matrix (int).

250 CHAPTER 10. SOLVERS

Output

slv the tridiagonal solver. It is of type sf tris.

10.17.2 sf tridiagonal define

Fills in the diagonal and off-diagonal entries in the tridiagonal solver based on the input
entries diag and offd.

Call

sf_tridiagonal_define (slv, diag, offd);

Definition

void sf_tridiagonal_define (sf_tris slv /* solver object */,

float* diag /* diagonal */,
float* offd /* off-diagonal */)
/*< fill the matrix >*/
{
...
}

Input parameters

slv the solver object (sf tris).

diag the diagonal (float*).
offd the off-diagonal (float*).

10.17.3 sf tridiagonal const define

Fills in the diagonal and off diagonal entries in the tridiagonal solver based on the input
entries diag and offd. It works like sf tridiagonal define but for the special case where
the matrix is Toeplitz.
10.17. TRIDIAGONAL MATRIX SOLVER (TRIDIAGONAL.C) 251

Call

sf_tridiagonal_const_define (slv, diag, offd, damp);

Definition

void sf_tridiagonal_const_define (sf_tris slv /* solver object */,

float diag /* diagonal */,
float offd /* off-diagonal */,
bool damp /* damping */)
/*< fill the matrix for the Toeplitz case >*/
{
...
}

Input parameters

slv the solver object. Must be of type sf tris.

diag the diagonal (float*).
offd the off-diagonal (float*).
damp damping (bool).

10.17.4 sf tridiagonal solve

Solves the matrix equation (like La = b, where b is the input for the solve function, a is the
output and L is the matrix defined by sf tridiagonal define) and stores the solution in
the space allocated by the variable x in the slv object.

Call

sf_tridiagonal_solve (sf_tris slv, b);

Definition

void sf_tridiagonal_solve (sf_tris slv /* solver object */,

float* b /* in - right-hand side, out - solution */)
/*< invert the matrix >*/
252 CHAPTER 10. SOLVERS

{
...
}

Input parameters

slv the solver object. Must be of type sf tris.

b right hand side of the matrix equation La = b (float*).

Definition

void sf_tridiagonal_solve (sf_tris slv /* solver object */,

float* b /* in - right-hand side, out - solution */)
/*< invert the matrix >*/
{
int k;
...
}

10.17.5 sf tridiagonal close

This function frees the allocated space for the slv object.

Call

sf_tridiagonal_close (slv);

Definition

void sf_tridiagonal_close (sf_tris slv)

/*< free allocated storage >*/
{
...
}
10.17. TRIDIAGONAL MATRIX SOLVER (TRIDIAGONAL.C) 253

Input parameters

slv the solver object. Must be of type sf tris.

254 CHAPTER 10. SOLVERS
Chapter 11

Interpolation

11.1 1-D interpolation (int1.c)

adj a parameter to determine whether the output is x or ord (bool).

add a parameter to determine whether the input needs to be zeroed (bool).
nm size of x (int).
ny size of ord (int).
x output or operator, depending on whether adj is true or false (sf complex*).
ord output or operator, depending on whether adj is true or false (sf complex*).

11.1.4 sf int1 close

Frees the space allocated for 1D interpolation by sf int1 init.

Call

sf_int1_close ();
258 CHAPTER 11. INTERPOLATION

Definition

void sf_int1_close (void)

/*< free allocated storage >*/
{
...
}

11.2 2-D interpolation (int2.c)

11.2.1 sf int2 init

Initializes the required variables and allocates the required space for 2D interpolation.

Call

sf_int2_init (coord, o1, o2, d1, d2, n1, n2, interp, nf_in, nd_in);

Definition

void sf_int2_init (float** coord /* coordinates [nd][2] */,

float o1, float o2,
float d1, float d2,
int n1, int n2 /* axes */,
sf_interpolator interp /* interpolation function */,
int nf_in /* interpolator length */,
int nd_in /* number of data points */)
/*< initialize >*/
{
...
}

Input parameters

coord coordinates (float**).

o1 origin of the first axis (float).
o2 origin of the second axis (float).
11.2. 2-D INTERPOLATION (INT2.C) 259

d1 sampling of the first axis (float).

d2 sampling of the second axis (float).
n1 length of the first axis (float).
n2 length of the second axis (float).
interp interpolation function (sf interpolator).
nf in interpolator length (int).
nd in number of data points (int).

11.2.2 sf int2 lop

sf_int3_init (coord, o1,o2,o3, d1,d2,d3,

n1,n2,n3, interp, nf_in, nd_in);

Definition

void sf_int3_init (float** coord /* coordinates [nd][3] */,

float o1, float o2, float o3,
float d1, float d2, float d3,
int n1, int n2, int n3 /* axes */,
sf_interpolator interp /* interpolation function */,
int nf_in /* interpolator length */,
int nd_in /* number of data points */)
/*< initialize >*/
11.3. 3-D INTERPOLATION (INT3.C) 261

{
...
}

Input parameters

coord coordinates (float**).

o1 origin of the first axis (float).
o2 origin of the second axis (float).
o3 origin of the third axis (float).
d1 sampling of the first axis (float).
d2 sampling of the second axis (float).
d3 sampling of the third axis (float).
n1 length of the first axis (float).
n2 length of the second axis (float).
n3 length of the third axis (float).
interp interpolation function (sf interpolator).
nf in interpolator length (int).
nd in number of data points (int).

11.3.2 sf int3 lop

Applies the linear operator for 3D interpolation.

Call

sf_int3_lop (adj, add, nm, ny, mm, dd);

Definition

void sf_int3_lop (bool adj, bool add, int nm, int ny, float* mm, float* dd)
/*< linear operator >*/
{
...
}
262 CHAPTER 11. INTERPOLATION

Input parameters

adj a parameter to determine whether the output is x or ord (bool).

11.3.3 sf int3 close

Frees the space allocated for 3D interpolation by sf int3 init.

Call

int3_close ();

Definition

void int3_close (void)

/*< free allocated storage >*/
{
...
}

11.4 Basic interpolation functions (interp.c)

11.4.1 sf bin int

Computes the nearest neighbor interpolation function coefficients.

Call

sf_bin_int (x, n, w);

11.4. BASIC INTERPOLATION FUNCTIONS (INTERP.C) 263

Definition

void sf_taylor (float x, int n, float* w)

/*< Taylor >*/
{
...
}
11.5. CONVERT DATA TO B-SPLINE COEFFICIENTS BY FAST B-SPLINE TRANSFORM (PREFILTER.C)2

int* n /* data size [dim] */,
float* dat /* in - data, out - coefficients */)
/*< Convert N-D data to spline coefficients >*/
{
...
}
11.6. B-SPLINE INTERPOLATION (SPLINE.C) 267

Input parameters

dim number of dimensions in the input data (int).

n size of the input data (int*).
dat the input data, which is converted to spline coefficients as output (float*).

11.5.4 sf prefilter close

Frees the space allocated for the pre-filer by sf prefilter init.

Call

sf_prefilter_close();

Definition

void sf_prefilter_close( void)

/*< free allocated storage >*/
{
...
}

11.6 B-spline interpolation (spline.c)

11.6.1 sf spline init

Initializes and defines a banded matrix for spline interpolation.

Call

slv = sf_spline_init (nw, nd);

Definition

sf_bands sf_spline_init (int nw /* interpolator length */,

int nd /* data length */)
268 CHAPTER 11. INTERPOLATION

/< initialize a banded matrix >/

{
...
}

Input parameters

nw length of the interpolator (int).

nd length of the data (int).

Output

slv an object of type sf band. It is of type sf band.

11.6.2 sf spline4 init

Initializes and defines a tridiagonal matrix for cubic spline interpolation.

Call

slv = sf_spline4_init(nd);

Definition

sf_tris sf_spline4_init (int nd /* data length */)

/*< initialize a tridiagonal matrix for cubic splines >*/
{
...
}

Input parameters

nd length of the data (int).

Output

slv an object of type sf tri. It is of type sf tri.

11.6. B-SPLINE INTERPOLATION (SPLINE.C) 269

11.6.3 sf spline4 post

Performs the cubic spline post filtering.

Call

sf_spline4_post (n, n1, n2, inp, out);

Definition

void sf_spline4_post (int n /* total trace length */,

int n1 /* start point */,
int n2 /* end point */,
const float* inp /* spline coefficients */,
float* out /* function values */)
/*< cubic spline post-filtering >*/
{
...
}

Input parameters

n total length of the trace (int).

n1 start point (int).
n2 end point (int).
inp spline coefficients (const float*).
out function values (float*).

11.6.4 sf spline post

Performs the post filtering to convert spline coefficients to model.

Call

sf_spline_post(nw, o, d, n, modl, datr);

270 CHAPTER 11. INTERPOLATION

Definition

void sf_spline_post (int nw, int o, int d, int n,

const float *modl, float *datr)
/*< post-filtering to convert spline coefficients to model >*/
{
...
}

Input parameters

nw length of the interpolator (int).

o start point (int).
d step size (int).
n total length of the trace (int).
modl spline coefficients, which have to be converted to model coefficients. Must be of
type const float*.
datr model, it is the output (float*).

11.6.5 sf spline2

Performs pre-filtering for spline interpolation for 2D data.

call

sf_spline2 (slv1, slv2, n1, n2, dat, tmp);

Definition

void sf_spline2 (sf_bands slv1, sf_bands slv2,

int n1, int n2, float** dat, float* tmp)
/*< 2-D spline pre-filtering >*/
{
...
}
11.7. INVERSE LINEAR INTERPOLATION (STRETCH.C) 271

Input parameters

slv1 first banded matrix. Must be of type sf band.

slv2 second banded matrix. Must be of type sf band.
n1 data length on the first axis (int).
n2 data length on the second axis (int).
dat 2D data. Must be of type const float**.
tmp temporary arrays for calculation (float*).

11.7 Inverse linear interpolation (stretch.c)

11.7.1 sf stretch init

Initializes the object of the abstract data of type sf map, which will be used to define and
transform (stretch) coordinates.

Call

sf_map sf_stretch_init (n1, o1, d1, nd, eps, narrow);

Definition

sf_map sf_stretch_init (int n1, float o1, float d1 /* regular axis */,
int nd /* data length */,
float eps /* regularization */,
bool narrow /* if zero boundary */)
/*< initialize >*/
{
...
}

Input parameters

n1 axis (int).
o1 first sample on the axis (int).
d1 step length to access the sample on the same axis (int).
272 CHAPTER 11. INTERPOLATION

eps regularizaton (float).

narrow is boundary value zero or not (bool).

Output

274 CHAPTER 11. INTERPOLATION

ord input ordinates (const float*).

mod model (const float*).

11.7.5 sf stretch close

This function frees the allocated space for the sf map object.

Call

sf_stretch_close (str);

Definition

void sf_stretch_close (sf_map str)

/*< free allocated storage >*/
{
...
}

Input parameters

str the sf map object. Must be of type sf map.

11.8 1-D ENO interpolation (eno.c)

11.8.1 sf eno init

Initializes an object of type sf eno for interpolation.

Call

ent = sf_eno_init (order, n);

11.8. 1-D ENO INTERPOLATION (ENO.C) 275

Definition

sf_eno sf_eno_init (int order /* interpolation order */,

int n /* data size */)
/*< Initialize interpolation object. >*/
{
...
}

Input parameters

order order of interpolation (int).

n size of the data (int).

Output

ent an object for interpolation. It is of type sf eno.

11.8.2 sf eno close

Frees the space allocated for the internal storage by sf eno init.

Call

sf_eno_close (ent);

Definition

void sf_eno_close (sf_eno ent)

/*< Free internal storage >*/
{
...
}

11.8.3 sf eno set

Creates a table for interpolation.

276 CHAPTER 11. INTERPOLATION

Call

sf_eno_set (ent, c);

Definition

void sf_eno_set (sf_eno ent, float* c /* data [n] */)

/*< Set the interpolation table. c can be changed or freed afterwords >*/
{
...
}

Input parameters

ent an object for interpolation. It is of type sf eno.

c the data which is to be interpolated (float*).

11.8.4 sf eno apply

Interpolates the data.

Call

sf_eno_apply (ent, i, x, f, f1, what);

Definition

void sf_eno_apply (sf_eno ent,

int i /* grid location */,
float x /* offset from grid */,
float *f /* output data value */,
float *f1 /* output derivative */,
der what /* flag of what to compute */)
/*< Apply interpolation >*/
{
...
}
11.9. ENO INTERPOLATION IN 2-D (ENO2.C) 277

Input parameters

ent an object for interpolation. It is of type sf eno.

i location of the grid (int).
x offset from the grid (float).
f output data value (float*).
f1 output derivative (float*).
what whether the function value or the derivative is required. Must be of type der.

11.9 ENO interpolation in 2-D (eno2.c)

11.9.1 sf eno2 init

Initializes an object of type sf eno2 for interpolation of 2D data.

Call

pnt = sf_eno2_init (order, n1, n2);

Definition

sf_eno2 sf_eno2_init (int order /* interpolation order */,

int n1, int n2 /* data dimensions */)
/*< Initialize interpolation object >*/
{
sf_eno2 pnt;
int i2;

...
return pnt;
}

Input parameters

order interpolation order (int).

n1 first dimension of the data (int).
278 CHAPTER 11. INTERPOLATION

n2 second dimension of the data (int).

Output

pnt object for interpolation. It is of type sf eno2.

11.9.2 sf eno2 set

Sets the interpolation table for the 2D data in a 2D array.

Call

sf_eno2_set (pnt, c);

Definition

void sf_eno2_set (sf_eno2 pnt, float** c /* data [n2][n1] */)

/*< Set the interpolation table. c can be changed or freed afterwords. >*/
{
...
}

Input parameters

pnt object for interpolation. It is of type sf eno2.

c the data (float**).

11.9.3 sf eno2 set1

Sets the interpolation table for the 2D data in a 1D array, which is of size n1*n2.

Call

sf_eno2_set1 (pnt, c);

11.9. ENO INTERPOLATION IN 2-D (ENO2.C) 279

Definition

void sf_eno2_set1 (sf_eno2 pnt, float* c /* data [n2n1] /)

/*< Set the interpolation table. c can be changed or freed afterwords. >*/
{
...
}

Input parameters

pnt object for interpolation. It is of type sf eno2.

c the data (float*).

11.9.4 sf eno2 close

Frees the space allocated for the internal storage by sf eno2 init.

Call

sf_eno2_close (pnt);

Definition

void sf_eno2_close (sf_eno2 pnt)

11.10.3 powerpeno

Calculates the Power-p limiter for eno method using the input numbers x and y.

Call

power = powerpeno (x, y, p);

Definition

float powerpeno (float x, float y, int p /* power order */)

/*< Limiter power-p eno >*/
{
...
}

Input parameters

x an input number (float).

y an input number (float).
p power order (int).

Output

mins * power limiter power-p. It is of type float.

11.10.4 sf pweno set

Sets the interpolation undivided difference table.

Call

void sf_pweno_set (sf_pweno ent, float* c /* data [n] */, int p);
11.10. 1-D ENO POWER-P INTERPOLATION (PWENO.C) 283

Definition

void sf_pweno_set (sf_pweno ent, float* c /* data [n] */, int p /* power order */)
/*< Set the interpolation undivided difference table. c can be changed or freed
afterwards >*/
{
...
}

Input parameters

ent the interpolation object. Must be of type sf pweno.

c input data (float*).
p power order (int).

11.10.5 sf pweno apply

Applies the interpolation.

Call

sf_pweno_apply (ent, i, x, f, f1, what);

Definition

void sf_pweno_apply (sf_pweno ent,

int i /* grid location */,
float x /* offset from grid */,
float *f /* output data value */,
float *f1 /* output derivative */,
derr what /* flag of what to compute */)
/*< Apply interpolation >*/
{
...
}
284 CHAPTER 11. INTERPOLATION

Input parameters

i location of the grid (int).

x offset from the grid (float).
f output data value (float*).
f1 output derivative (float*).
what flag of what to compute. Must be of type derr.
Chapter 12

Smoothing

12.1 1-D triangle smoothing as a linear operator (triangle1.c)

12.1.1 sf triangle1 init

Initializes the triangle filter.

Call

sf_triangle1_init (nbox, ndat);

Definition

void sf_triangle1_init (int nbox /* triangle size */,

int ndat /* data size */)
/*< initialize >*/
{
...
}

Input parameters

inbox size of the triangle filter (int).

ndat size of the data (int).

285
286 CHAPTER 12. SMOOTHING

12.1.2 sf triangle1 lop

Applies the triangle smoothing to one of the input data and applies the smoothed data to
the unsmoothed one as a linear operator.

Call

sf_triangle1_lop (adj, add, nx, ny, x, y);

Definition

void sf_triangle1_lop (bool adj, bool add, int nx, int ny, float* x, float* y)
/*< linear operator >*/
{
...
}

Input parameters

adj a parameter to determine whether weights are applied to yy or xx (bool).

add a parameter to determine whether the input needs to be zeroed (bool).
nx size of x (int).
ny size of y (int).
x data or operator, depending on whether adj is true or false (float).
y data or operator, depending on whether adj is true or false. Must be of type float.

Output

x or y the output depending on whether adj is true or false (float).

12.1.3 sf triangle1 close

Frees the space allocated for the triangle smoothing filter.

12.2. 2-D TRIANGLE SMOOTHING AS A LINEAR OPERATOR (TRIANGLE2.C)287

Call

sf_triangle1_close();

Definition

void sf_triangle1_close(void)
/*< free allocated storage >*/
{
...
}

12.2 2-D triangle smoothing as a linear operator (triangle2.c)

12.2.1 sf triangle2 init

Initializes the triangle filter.

Call

sf_triangle2_init (nbox1,nbox2, ndat1,ndat2, nrep);

Definition

void sf_triangle2_init (int nbox1, int nbox2 /* triangle size */,

int ndat1, int ndat2 /* data size */,
int nrep /* repeat smoothing */)
/*< initialize >*/
{
...
}

Input parameters

inbox1 size of the triangle filter (int).

inbox2 size of the second triangle filter (int).
ndat1 size of the data (int).
288 CHAPTER 12. SMOOTHING

ndat2 size of the second data set (int).

nrep number of times the smoothing is to be repeated (int).

12.2.2 sf triangle2 lop

Applies the triangle smoothing to one of the input data and applies the smoothed data to
the unsmoothed one as a linear operator. This is just like sf triangle1 lop but with two
triangle filters instead of one.

Call

sf_triangle2_lop (adj, add, nx, ny, x, y);

Definition

void sf_triangle2_lop (bool adj, bool add, int nx, int ny, float* x, float* y)
/*< linear operator >*/
{
...
}

Input parameters

adj a parameter to determine whether weights are applied to yy or xx (bool).

Output

x or y the output depending on whether adj is true or false (float).

12.3. TRIANGLE SMOOTHING (TRIANGLE.C) 289

12.2.3 sf triangle2 close

Frees the space allocated for the triangle smoothing filters.

Call

sf_triangle2_close();

Definition

void sf_triangle2_close(void)
/*< free allocated storage >*/
{
...
}

12.3 Triangle smoothing (triangle.c)

12.3.1 sf triangle init

Initializes the triangle smoothing filter.

Call

tr = sf_triangle_init (nbox, ndat);

Definition

sf_triangle sf_triangle_init (int nbox /* triangle length */,

int ndat /* data length */)
/*< initialize >*/
{
...
}
290 CHAPTER 12. SMOOTHING

Input parameters

nbox an integer which specifies the length of the filter (int).

ndat an integer which specifies the length of the data (int).

Output

tr the triangle smoothing filter. It is of type sf triangle.

12.3.2 fold

Folds the edges of the smoothed data, because when the data is convolved with the data,
the length of the data increases and in most cases it is required that the smoothed data is
of the same length as the input data.

Call

fold (o, d, nx, nb, np, x, tmp);

Definition

static void fold (int o, int d, int nx, int nb, int np,
const float *x, float* tmp)
{
...
}

Input parameters

o first indices of the input data (int).

d step size (int).
nx data length (int).
nb filter length (int).
np length of the tmp array in the sf Triangle data structure (int).
x a pointer to the input data (const float).
tmp a pointer to an array in the sf Triangle data structure. Must be of type float
12.3. TRIANGLE SMOOTHING (TRIANGLE.C) 291

12.3.3 fold2

Is the same as fold except for the fact that it copies from tmp to data, unlike the fold
which does it the other way round.

Call

fold2 (o, d, nx, nb, np, x, tmp);

Definition

static void fold2 (int o, int d, int nx, int nb, int np,
float *x, const float* tmp)
{
...
}

Input parameters

o first indices of the input data (int).

d step size (int).
nx data length (int).
nb filter length (int).
np length of the tmp array in the sf Triangle data structure. Must be of type int
x a pointer to the input data (const float).
tmp a pointer to an array in the sf Triangle data structure (float).

12.3.4 doubint

Integrates the input data first in the backward direction and then if the input variable der
is true it integrates the result forward.

Call

doubint (nx, xx, der);

292 CHAPTER 12. SMOOTHING

Definition

static void doubint (int nx, float *xx, bool der)

{
...
}

Input parameters

nx data length (int).

Definition

static void triple2 (int o, int d, int nx, int nb,

const float* x, float* tmp, bool box)
{
...
}

Input parameters

o first indices of the input data (int).

12.3.8 sf smooth

Smoothes the input data by first applying the fold function then doubint and then triple.

Call

sf_smooth (tr, o, d, der, box, x);

Definition

void sf_smooth (sf_triangle tr /* smoothing object */,

int o, int d /* trace sampling */,
bool der /* if derivative */,
bool box /* if box filter */,
float *x /* data (smoothed in place) */)
/*< apply triangle smoothing >*/
{
12.3. TRIANGLE SMOOTHING (TRIANGLE.C) 295

...
}

Input parameters

tr an object (filter) used for smoothing, box or triangle. Must be of type sf triangle.
o first indices of the input data (int).
d step size (int).
der a parameter to specify whether forward integration in doubint is required or not
(const float).
x a pointer to the input data (float).
box a parameter to specify whether a box filter is required (bool).

12.3.9 sf smooth2

Smoothes the input data by first applying the triple2 function then doubint2 and then
fold2.

Call

sf_smooth2 (tr, o, d, der, box, x);

Definition

void sf_smooth2 (sf_triangle tr /* smoothing object */,

int o, int d /* trace sampling */,
bool der /* if derivative */,
bool box /* if box filter */,
float *x /* data (smoothed in place) */)
/*< apply adjoint triangle smoothing >*/
{
...
}
296 CHAPTER 12. SMOOTHING

Input parameters

12.3.10 sf triangle close

Frees the space allocated for the triangle smoothing filter.

Call

sf_triangle_close(tr);

Definition

void sf_triangle_close(sf_triangle tr)

/*< free allocated storage >*/
{
...
}

Input parameters

tr the triangle smoothing filter. Must be of type sf triangle.

12.4 Smooth gradient operations (edge.c)

12.4.4 sf sobel32

Calculates the Sobel’s gradient squared for a 3D image. It works like sf sobel but outputs
the gradient squared for 3D data.

Call

sf_sobel32 (n1, n2, n3, x, w);

Definition

void sf_sobel32 (int n1, int n2, int n3 /* data size */,
float ***x /* input data [n3][n2][n1] */,
float ***w /* output gradient squared */)
/*< Sobel’s gradient squared in 3-D>*/
{
...
}

Input parameters

n1 size of the data, first axis (int).

n2 size of the data, second axis (int).
n3 size of the data, third axis (int).
x 3D input data (const float***).
w output gradient squared (float***).
300 CHAPTER 12. SMOOTHING
Chapter 13

Ray tracing

13.1 Cell ray tracing (celltrace.c)

13.1.1 sf celltrace init

Initializes the object sf celltrace for ray tracing by initializing the required variables
and allocating the required space.

Call

ct = sf_celltrace_init (order, nt, nz, nx, dz, dx, z0, x0, slow);

Definition

sf_celltrace sf_celltrace_init (int order /* interpolation accuracy */,

int nt /* maximum time steps */,
int nz /* depth samples */,
int nx /* lateral samples */,
float dz /* depth sampling */,
float dx /* lateral sampling */,
float z0 /* depth origin */,
float x0 /* lateral origin */,
float* slow /* slowness [nz*nx] */)
/*< Initialize ray tracing object >*/
{

301
302 CHAPTER 13. RAY TRACING

...
}

Input parameters

order accuracy of the interpolation (int).

nt maximum number of time steps (int).
nz number of depth samples (int).
nx number of lateral samples (int).
dz depth sampling interval (float).
dx lateral sampling interval (float).
z0 depth origin (float).
x0 lateral origin (float).
slow slowness (float*).

Output

ct the ray tracing object. It is of type sf celltrace.

13.1.2 sf celltrace close

Frees the space allocated for the sf celltrace object by sf celltrace init.

Call

sf_celltrace_close (ct);

Definition

void sf_celltrace_close (sf_celltrace ct)

/*< Free allocated storage >*/
{
...
}
13.2. CELL RAY TRACING (CELL.C) 303

13.1.3 sf cell trace

Traces the ray with the ray parameter specified in the input.

Call

t = sf_cell_trace (ct, xp, p, it, traj);

Definition

float sf_cell_trace (sf_celltrace ct,

float* xp /* position */,
float* p /* ray parameter */,
int* it /* steps till boundary */,
float** traj /* trajectory */)
/*< ray trace >*/
{
...
}

Input parameters

ct the ray tracing object. It is of type sf celltrace.

xp position (float*).
p ray parameters (float*).
it number steps till the boundary (int*).
traj trajectory of the ray (float**).

Output

t the travel time obtained by the ray tracing. It is of type float.

13.2 Cell ray tracing (cell.c)

13.2.1 sf cell1 intersect

Intersects a straight ray with the cell boundary.

304 CHAPTER 13. RAY TRACING

Call

sf_cell1_intersect (a, x, dy, p, sx, jx);

Definition

void sf_cell1_intersect (float a, float x, float dy, float p,

float *sx, int *jx)
/*< intersecting a straight ray with cell boundaries >*/
{
...
}

Input parameters

a gradient of slowness (float).

x non-integer part of the position in the grid relative to grid origin. It is of type float.
dy depth or lateral sampling divided by slowness. It is of type float.
p the ray parameter. It is of type float.
sx distance traveled in the medium (cell) times the velocity of the medium (equivalent
to the optical path length in optics). It is of type float*.
jx the direction of the ray. It is of type int*.

13.2.2 sf cell1 update1

Performs the first step of the first order symplectic method for ray tracing.

Call

tt = sf_cell1_update1 (dim, s, v, p, g);

Definition

float sf_cell1_update1 (int dim, float s, float v, float *p, const float *g)
/*< symplectic first-order: step 1 >*/
{
13.2. CELL RAY TRACING (CELL.C) 305

...
}

Input parameters

dim dimension (int).

s σ (float).
v slowness. It is of type float.
p direction. It is of type float*.
g slowness gradient. It is of type const float*.

Output

0.5vv*s(1. + spg) travel time. It is of type float.

13.2.3 sf cell1 update2

Performs the second step of the first order symplectic method for ray tracing.

Call

tt = sf_cell1_update2 (dim, s, v, p, g);

Definition

float sf_cell1_update2 (int dim, float s, float v, float *p, const float *g)
/*< symplectic first-order: step 2 >*/
{
...
}

Input parameters

dim dimension (int).

s σ (float).
306 CHAPTER 13. RAY TRACING

v slowness. It is of type float.

p direction. It is of type float*.
g slowness gradient. It is of type const float*.

Output

0.5vv*s(1. - spg) travel time. It is of type float.

13.2.4 sf cell11 intersect2

Intersects a straight ray with the cell boundary.

Call

sf_cell11_intersect2 (a, da, p, g, sp, jp);

Definition

void sf_cell11_intersect2 (float a, float da,

const float* p, const float* g,
float *sp, int *jp)
/*< intersecting a straight ray with cell boundaries >*/
{
...
}

Input parameters

a position in the grid (float).

da grid spacing. It is of type float.
p the ray parameter. It is of type const float*.
g gradient of slowness (const float*).
sp distance traveled in the medium (cell) times the velocity of the medium (equivalent
to the optical path length in optics). It is of type float*.
jp the direction of the ray. It is of type int*.
13.2. CELL RAY TRACING (CELL.C) 307

13.2.5 sf cell11 update1

Performs the first step of the first order non-symplectic method for ray tracing.

Call

tt = sf_cell11_update1 (dim, s, v, p, g);

Definition

float sf_cell11_update1 (int dim, float s, float v, float *p, const float *g)
/*< nonsymplectic first-order: step 1 >*/
{
...
}

Input parameters

dim dimension (int).

s σ (float).
v slowness. It is of type float.
p direction. It is of type float*.
g slowness gradient. It is of type const float*.

Output

0.5vv*s(1. + spg) travel time. It is of type float.

13.2.6 sf cell11 update2

Performs the second step of the first order non-symplectic method for ray tracing.

Call

tt = sf_cell11_update2 (dim, s, v, p, g);

308 CHAPTER 13. RAY TRACING

Definition

float sf_cell11_update2 (int dim, float s, float v, float *p, const float *g)
/*< nonsymplectic first-order: step 2 >*/
{
...
}

Input parameters

dim dimension (int).

s σ (float).
v slowness. It is of type float.
p direction. It is of type float*.
g slowness gradient. It is of type const float*.

Output

0.5vv*s(1. - spg) travel time. It is of type float.

13.2.7 sf cell intersect

Intersects a parabolic ray with the cell boundary.

Call

sf_cell_intersect (a, x, dy, p, sx, jx);

Definition

void sf_cell_intersect (float a, float x, float dy, float p,

float *sx, int *jx)
/*< intersecting a parabolic ray with cell boundaries >*/
{
...
}
13.2. CELL RAY TRACING (CELL.C) 309

Input parameters

a gradient of slowness (float).

13.2.8 sf cell snap

0.5vv*s(1. + spg) travel time. It is of type float.

13.2.10 sf cell update2

Performs the second step of the second order symplectic method for ray tracing.

Call

tt = sf_cell_update2 (dim, s, v, p, g);

13.2. CELL RAY TRACING (CELL.C) 311

Definition

float sf_cell_update2 (int dim /* number of dimensions */,

float s /* sigma */,
float v /* slowness */,
float *p /* in - ?, out - direction */,
const float *g /* slowness gradient */)
/*< symplectic second-order: step 2 >*/
{
...
}

Input parameters

dim dimension (int).

s σ (float).
v slowness. It is of type float.
p direction. It is of type float*.
g slowness gradient. It is of type const float*.

Output

0.5vv*s(1. - spg) travel time. It is of type float.

13.2.11 sf cell p2a

Converts the ray parameter to an angle.

Call

a = sf_cell_p2a (p);

Definition

float sf_cell_p2a (float* p)

/*< convert ray parameter to angle >*/
312 CHAPTER 13. RAY TRACING

{
...
}

Input parameters

p the ray parameter (float*).

Output

a angle of the ray. It is of type float*.

Chapter 14

General tools

14.1 First derivative FIR filter (deriv.c)

14.1.1 sf deriv init

Initializes the derivative calculation of the input trace, that is, it sets the required param-
eters and allocates the required space.

Call

sf_deriv_init (nt1, n1, c1);

Definition

void sf_deriv_init(int nt1 /* transform length */,

int n1 /* trace length */,
float c1 /* filter parameter */)
{
...
}

Input parameters

nt1 length of the transform (derivative) (int).

313
314 CHAPTER 14. GENERAL TOOLS

n1 length of the trace (int).

c1 filter parameter (float).

14.1.2 sf deriv free

Frees the temporary space allocated for the derivative operator.

Call

sf_deriv_free ();

Definition

void sf_deriv_free(void)
{
...
}

14.1.3 sf deriv

Calculates the derivative of the input trace (trace) and outputs it to trace2.

Definition

sf_deriv (trace, trace2);

Definition

void sf_deriv (const float* trace, float* trace2)

/*< derivative operator >*/
{
...
}
14.2. COMPUTING QUANTILES BY HOARE’S ALGORITHM (QUANTILE.C) 315

Input parameters

trace input trace whose derivative is required (float*).

trace2 location where the derivative is to be stored (float*).

14.2 Computing quantiles by Hoare’s algorithm (quantile.c)

14.2.1 sf quantile

Returns the quantile - which is specified in the input - for the input array.

Call

k = sf_quantile(q, n, a);

Definition

float sf_quantile(int q /* quantile */,

int n /* array length */,
float* a /* array [n] */)
/*< find quantile (caution: a is changed) >*/
{
...
}

Input parameters

q the required quantile (int).

n length of the input array (int).
a the input array for which the quantile is required (float*).

Output

*k the quantile. It is of type float.

316 CHAPTER 14. GENERAL TOOLS

14.3 Pseudo-random numbers: uniform and normally distributed (randn.c)

14.3.1 sf randn1

Generates a normally distributed random number using the Box-Muller method.

Call

vset = sf_randn_one_bm ();

Definition

float sf_randn_one_bm (void)

/*< return a random number (normally distributed, Box-Muller method) >*/
{
...
}

Output

vset the random number. It is of type float.

14.3.2 sf randn

Fills an array with normally distributed random numbers.

Call

sf_randn (nr, r);

Definition

void sf_randn (int nr, float r / [nr] */)

/*< fill an array with normally distributed numbers >*/
{
...
}
14.4. EVALUATING MATHEMATICAL EXPRESSIONS (MATH1.C) 317

Input parameters

nr size of the array where the random numbers are to be stored (int).
r the array where the random numbers are to be stored (float*).

14.3.3 sf random

Fills an array with uniformly distributed random numbers.

Call

sf_random (nr, r)

Definition

void sf_random (int nr, float r / [nr] */)

/*< fill an array with uniformly distributed numbers >*/
{
...
}

Input parameters

nr size of the array where the random numbers are to be stored (int).
nr the array where the random numbers are to be stored (float*).

14.4 Evaluating mathematical expressions (math1.c)

14.4.1 myabs

Returns a complex number with zero imaginary value and the real non-zero real part is
the absolute value of the input complex number.

Call

c = sf_complex myabs(c);
318 CHAPTER 14. GENERAL TOOLS

Definition

static sf_complex myabs(sf_complex c)

{
...
}

Input parameters

c a complex number (sf complex).

Output

c a complex number with real part = absolute value of the input complex number and
imaginary part = zero. It is of type static sf complex.

14.4.2 myconj

Returns the complex conjugate of the input complex number.

Call

c = myconj(sf_complex c);

Definition

len length of the stack (int).

nbuf length of the buffer (int).
fbuf buffers for floating point numbers (float**).
fst the stack (float**).

14.4.5 sf complex math evaluate

Applies a mathematical function to the input stack. For example it could evaluate the
exponents of the samples in the stack, It works like sf math evaluate but does it for
complex numbers.

Call

sf_complex_math_evaluate(len, nbuf, cbuf, cst);

Definition

void sf_complex_math_evaluate (int len /* stack length */,

int nbuf /* buffer length */,
sf_complex** cbuf /* number buffers */,
sf_complex** cst /* stack */)
/*< Evaluate a mathematical expression from stack (complex numbers) >*/
{
...
}
14.4. EVALUATING MATHEMATICAL EXPRESSIONS (MATH1.C) 321

Call

sf_complex_math_evaluate(len, nbuf, cbuf, cst)

Definition

void sf_complex_math_evaluate (int len /* stack length */,

int nbuf /* buffer length */,
sf_complex** cbuf /* number buffers */,
sf_complex** cst /* stack */)
/*< Evaluate a mathematical expression from stack (complex numbers) >*/
{
...
}

Input parameters

len length of the stack (int).

nbuf length of the buffer (int).
fbuf buffers for floating point numbers (sf complex**).
fst the stack (sf complex**).

14.4.6 sf math parse

Parses the mathematical expression and returns the stack length.

P a point (position vector) (pt3d).

323
324 CHAPTER 15. GEOMETRY

15.1.2 printpt3d

Prints the value and location of a 3D point (position vector).

Call

printpt3d(P);

Definition

void printpt3d(pt3d P)
/*< print point3d info >*/
{
...
}

Input parameters

Definition

void pt2dread1(sf_file F, pt2d *v, size_t n1, int k)

/*< input point2d 1-D vector >*/
{
...
}

Input parameters

/*< input point3d 2-D vector >*/
{
...
}
330 CHAPTER 15. GEOMETRY

Input parameters

File a file from which the 2D array of 3D points is to be read (sf file).
v an array of 2D points which is to be read (pt3d).
n1 size of one axis of the 2D array (size t).
n2 size of the other axis of the 2D array (size t).
k a number, which if equal to 4, indicates that the value of the 3D points must also
be included (int).

15.1.11 pt2dalloc1

Allocates memory for 1D array of 2D points.

Call

ptr = pt2dalloc1(n1);

Definition

pt2d* pt2dalloc1( size_t n1)

/*< alloc point2d 1-D vector >*/
{
...
}

Input parameters

n1 size of the array (size t).

Output

ptr pointer to memory (pt2d*).

15.1.12 pt2dalloc2

Allocates memory for 2D array of 2D points.

15.1. CONSTRUCTION OF POINTS (POINT.C) 331

Call

ptr = pt2dalloc2(n1,n2);

Definition

pt2d** pt2dalloc2( size_t n1, size_t n2)

/*< alloc point2d 2-D vector >*/
{
...
}

Input parameters

n1 size one axis of the 2D array (size t).

n2 size of the other axis of the 2D array (size t).

Output

ptr pointer to memory (pt2d**).

15.1.13 pt2dalloc3

Allocates memory for 3D array of 2D points.

Call

pt2d*** pt2dalloc3(n1, n2, n3);

Definition

pt2d*** pt2dalloc3(size_t n1, size_t n2, size_t n3)

/*< alloc point2d 3-D vector >*/
{
...
}
332 CHAPTER 15. GEOMETRY

Input parameters

n1 size of first axis of the 3D array (size t).

n2 size of the second axis of the 3D array (size t).
n3 size of the third axis of the 3D array (size t).

Output

ptr pointer to memory (pt2d***).

15.1.14 pt3dalloc1

Allocates memory for 1D array of 3D points.

Call

ptr = pt3dalloc1(n1);

Definition

pt3d* pt3dalloc1( size_t n1)

/*< alloc point3d 1-D vector >*/
{
...
}

Input parameters

n1 size of the array (size t).

Output

ptr pointer to memory (pt3d*).

15.1.15 pt3dalloc2

Allocates memory for 2D array of 3D points.

15.1. CONSTRUCTION OF POINTS (POINT.C) 333

Call

ptr = pt3dalloc2(n1,n2);

Definition

pt3d** pt3dalloc2( size_t n1, size_t n2)

/*< alloc point3d 2-D vector >*/
{
...
}

Input parameters

n1 size of one axis of the 2D array (size t).

n2 size of the other axis of the 2D array (size t).

Output

ptr pointer to memory (pt3d**).

15.1.16 pt3dalloc3

Allocates memory for 3D array of 3D points.

Call

ptr = pt3dalloc3(n1, n2, n3);

Definition

pt3d*** pt3dalloc3(size_t n1, size_t n2, size_t n3)

/*< alloc point3d 3-D vector >*/
{
...
}
334 CHAPTER 15. GEOMETRY

Input parameters

n1 size of first axis of the 3D array (size t).

n2 size of the second axis of the 3D array (size t).
n3 size of the third axis of the 3D array (size t).

Output

ptr pointer to memory (pt3d***).

15.2 Construction of vectors (vector.c)

15.2.1 det3

The determinant of a 3 × 3 matrix.

Call

d = det3(m);

Definition

double det3(double *m)

{
...
}

Input parameters

m a 3 × 3 matrix (double).

Output

d the determinant (double).

15.2. CONSTRUCTION OF VECTORS (VECTOR.C) 335

15.2.2 det2

The determinant of a 2 × 2 matrix.

Call

d = det2(m);

Definition

double det2(double *m)

{
...
}

Input parameters

m a 2 × 2 matrix (double).

Output

d the determinant (double).

15.2.3 jac3d

Returns a 3D jacobian.

Call

r = jac3d(C, T, P, Q);

Definition

double jac3d(pt3d C, pt3d T, pt3d P, pt3d Q)

/*< 3D jacobian >*/
{
336 CHAPTER 15. GEOMETRY

...
}

Input parameters

c a complex number. Must be of type sf double complex.

Output

c.r real part of the complex number. It is of type double.

15.2.4 vec3d

Builds a 3D vector. The components of the vector returned are the difference of the
respective components of the two input points (position vectors). The first input vector is
the origin.

Call

V = vec3d(O, A);

Definition

vc3d vec3d(pt3d* O, pt3d* A)

/*< build 3D vector >*/
{
...
}

Input parameters

O a 3D point, this serves as the origin (pt3d).

A a 3D point (pt3d).

Output

V the 3D vector. It is of type vc3d.

15.2. CONSTRUCTION OF VECTORS (VECTOR.C) 337

15.2.5 axa3d

Builds a 3D unit vector. The components of the vector returned are zero except for the
one indicated in the input argument n, which is equal to one. If n=1 the z axis is 1, if n=2
the x axis is 1 and if n=3 the y axis is 1.

W the normalized 3D vector. It is of type vc3d.

15.2.10 ang3d

Returns the angle between the input 3D vectors.

Call

a = ang3d(U, V);

Definition

double ang3d(vc3d* U, vc3d* V)

/*< angle between 3D vectors >*/
{
...
}

Input parameters

U the input 3D vector. It is of type vc3d.

V the input 3D vector. It is of type vc3d.
15.2. CONSTRUCTION OF VECTORS (VECTOR.C) 341

Output

a the angle between the two input 3D vectors. It is of type double.

15.2.11 tip3d

Returns the tip of a 3D vector. The components of the vector returned are the sum of
the respective components of the two input points (position vectors). Unlike the sf vc3d
where the first input vector was the origin, in sf tip3d the origin is zero. This means that
the vector returned is a position vector or simply a point, which is of type pt3d.

Call

A = tip3d(O, V);

Definition

pt3d tip3d(pt3d* O, vc3d* V)

/*< tip of a 3D vector >*/
{
...
}

Input parameters

O a 3D point (pt3d).
V a 3D point (pt3d).

Output

V the 3D vector. It is of type vc3d.

15.2.12 scl3d

Scales a 3D vector, that is, it multiplies it by a scalar. The components of the vector
returned are the product of the components of the input vector and the input scalar.
342 CHAPTER 15. GEOMETRY

Call

W = scl3d(V, s);

Definition

vc3d scl3d(vc3d* V, float s)

/*< scale a 3D vector >*/
{
...
}

Input parameters

V a 3D point (pt3d).
s a scalar which is to be multiplied by every component of the input vector (float).

Output

W the scaled 3D vector. It is of type vc3d.

15.3 Conversion between line and Cartesian coordinates of a vector (de-

cart.c)

15.3.1 sf line2cart

Converts the line coordinates to Cartesian coordinates.

Call

sf_line2cart(dim, nn, i, ii);

Definition

void sf_line2cart(int dim /* number of dimensions */,

const int* nn /* box size [dim] */,
15.3. CONVERSION BETWEEN LINE AND CARTESIAN COORDINATES OF A VECTOR (DECART.C)343

int i /* line coordinate */,

int* ii /* cartesian coordinates [dim] */)
/*< Convert line to Cartesian >*/
{
...
}

Input parameters

dim number of dimensions (int).

nn box size (size of the data file) (const int*).
i the line coordinate (int).
ii the Cartesian coordinates (int*).

15.3.2 sf cart2line

Converts the Cartesian coordinates to line coordinate.

Call

int sf_cart2line(dim, nn, ii);

Definition

int sf_cart2line(int dim /* number of dimensions */,

const int* nn /* box size [dim] */,
const int* ii /* cartesian coordinates [dim] */)
/*< Convert Cartesian to line >*/
{
...
}

Input parameters

dim number of dimensions (int).

nn box size (size of the data file) (const int*).
ii the Cartesian coordinates (int*).
344 CHAPTER 15. GEOMETRY

Output

i line coordinate. It is of type int.

15.3.3 sf first index

Returns the first index for a particular dimension.

Call

sf_first_index (i, j, dim, n, s);

Definition

int sf_first_index (int i /* dimension [0...dim-1] */,

int j /* line coordinate */,
int dim /* number of dimensions */,
const int *n /* box size [dim] */,
const int *s /* step [dim] */)
/*< Find first index for multidimensional transforms >*/
{
...
}

Input parameters

i the dimension (int).

j the line coordinate (int).
dim number of dimensions (int).
n box size (size of the data file) (const int*).
s the step size (const int*).

Output

i0 first index for the given dimension. It is of type int.

15.3. CONVERSION BETWEEN LINE AND CARTESIAN COORDINATES OF A VECTOR (DECART.C)345

15.3.4 sf large line2cart

Converts the line coordinate to Cartesian coordinates. It works exactly like sf line2cart
but in this one the line and Cartesian coordinates are of type off t, which means that
they are given in terms of the offset in bytes in the data file.

Call

sf_large_line2cart(dim, nn, i, ii);

Definition

void sf_large_line2cart(int dim /* number of dimensions */,

const off_t* nn /* box size [dim] */,
off_t i /* line coordinate */,
off_t* ii /* cartesian coordinates [dim] */)
/*< Convert line to Cartesian >*/
{
...
}

Input parameters

dim number of dimensions (int).

nn box size (size of the data file) (const off t*).
i the line coordinate (off t).
ii the Cartesian coordinates (off t*).

15.3.5 sf large cart2line

Converts the Cartesian coordinates to line coordinate. It works exactly like sf line2cart
but in this one the line and Cartesian coordinates are of type off t, which means that
they are given in terms of the offset in bytes in the data file.

Call

sf_large_cart2line(int, nn, ii);

346 CHAPTER 15. GEOMETRY

Definition

off_t sf_large_cart2line(int dim /* number of dimensions */,

const off_t* nn /* box size [dim] */,
const off_t* ii /* cartesian coordinates [dim] */)
/*< Convert Cartesian to line >*/
{
...
}

Input parameters

dim number of dimensions (int).

nn box size (size of the data file) (const off t*).
ii the Cartesian coordinates (const off t*).

Output

i line coordinate. It is of type off t.

15.3.6 sf large first index

Returns the first index for a particular dimension. It works exactly like sf first index
but in this one the line coordinate, box size, step size and the first index are of type off t,
which means that they are given in terms of the offset in bytes in the data file.

Call

sf_large_first_index (i, j, dim, n, s);

Definition

off_t sf_large_first_index (int i /* dimension [0...dim-1] */,

off_t j /* line coordinate */,
int dim /* number of dimensions */,
const off_t *n /* box size [dim] */,
const off_t *s /* step [dim] */)
15.4. AXES (AXA.C) 347

/< Find first index for multidimensional transforms >/

{
...
}

Input parameters

i the dimension (int).

j the line coordinate (off t).
dim number of dimensions (int).
n box size (size of the data file) (const off t*).
s the step size (const off t*).

Output

i0 first index for the given dimension. It is of type int.

15.4 Axes (axa.c)

15.4.1 sf maxa

Creates a simple axis.

Call

AA = sf_maxa(n, o, d);

Definition

sf_axis sf_maxa(int n /* length */,

float o /* origin */,
float d /* sampling */)
/*< make a simple axis >*/
{
...
}
348 CHAPTER 15. GEOMETRY

Input parameters

n length of the axis (int).

o origin of the axis (float).
d sampling of the axis (float).

Output

AA the axis. It is of type sf axis.

15.4.2 sf iaxa

Reads an axis from the file which is given in the input.

Call

AA = sf_iaxa(FF, i);

Definition

sf_axis sf_iaxa(sf_file FF, int i)

/*< read axis i >*/
{
...
}

Input parameters

FF the file from which the axis is to be read (sf file).

i a number which specified which axis is to be read, for example n1, n2, n3 etc (int).

Output

AA location where the axis is stored. It is of type sf axis.

15.4. AXES (AXA.C) 349

15.4.3 sf oaxa

Writes an axis, from the input location, to the file, which is also given in the input.

Call

sf_oaxa(FF, AA, i);

Definition

void sf_oaxa(sf_file FF, const sf_axis AA, int i)

/*< write axis i >*/
{
...
}

Input parameters

FF the file in which the axis is to be written (sf file).

AA the location from where the axis is to be read. Must be of type const sf axis.
i a number which specified which axis is to be read, for example n1, n2, n3 etc (int).

15.4.4 sf raxa

Prints the information about the axis on the screen.

Call

sf_raxa(AA);

Definition

void sf_raxa(const sf_axis AA)

/*< report information on axis AA >*/
{
...
}
350 CHAPTER 15. GEOMETRY

352 CHAPTER 15. GEOMETRY

Output

AA->d length of the axis. It is of type float.

15.4.8 sf nod

Copies the length, origin and sampling of the input axis to another place which is also an
object of type sf axis.

Call

BB = sf_nod(AA);

Definition

sf_axa sf_nod(const sf_axis AA)

/*< access length, origin, and sampling >*/
{
...
}

Input parameters

AA the axis whose length, origin and sampling is to be accessed. Must be of type const
sf axis.

Output

BB the location where the length, origin and sampling are copied. It is of type sf axis.

15.4.9 sf setn

Changes the length of the axis.

Call

AA->n = sf_setn(AA, n);

15.4. AXES (AXA.C) 353

Definition

void sf_setn(sf_axis AA, int n)

/*< change axis length >*/
{ AA->n=n; }

Input parameters

AA the axis whose length is to be changed (sf axis).

n the new length which is to be set (int).

15.4.10 sf seto

Changes the origin of the axis.

Call

AA->o = sf_seto(AA, o);

Definition

void sf_seto(sf_axis AA, float o)

/*< change axis origin >*/
{
...
}

Input parameters

AA the axis whose origin is to be changed (sf axis).

o the new origin which is to be set (float).

15.4.11 sf setd

Changes the sampling of the axis.

354 CHAPTER 15. GEOMETRY

16.1.1 sf sharpen init

Initializes the sharpening operator by allocating the required and initializing the required
operators.

Call

sf_sharpen_init(n1, perc);

Definition

void sf_sharpen_init(int n1 /* data size */,

float perc /* quantile percentage */)
/*< initialize >*/
{
...
}

Input parameters

n1 size of the data (int).

perc the quantile percentage (float).

357
358 CHAPTER 16. MISCELLANEOUS

16.1.2 sf sharpen close

Frees the allocated memory for the sharpening calculation.

Call

sf_sharpen_close();

Definition

void sf_sharpen_close(void)
/*< free allocated storage >*/
{
...
}

16.1.3 sf sharpen

Computes the weights for the sharpening regularization.

Call

wp = sf_sharpen(pp);

Definition

float sf_sharpen(const float *pp)

/*< compute weight for sharpening regularization >*/
{
...
}

Input parameters

pp an array for which the weights are to be calculated (const float*).

16.2. SHARPENING INVERSION ADDED BREGMAN ITERATION (SHARPINV.C)359

Output

scale extra operator scaling (float).
niter number of outer iterations (int).
ncycle number of iterations (int).
perc sharpening percentage (float).
verb verbosity flag (bool).
nq size of the model (int).
np size of the data (int).
qq the model (float*).
pp the data (float*).
362 CHAPTER 16. MISCELLANEOUS
Chapter 17

System

17.1 Priority queue (heap sorting) (pqueue.c)

17.1.1 sf pqueue init

Initializes the heap with the maximum size given in the input.

Call

sf_pqueue_init (n);

Definition

void sf_pqueue_init (int n)

/*< Initialize heap with the maximum size >*/
{
...
}

Input parameters

n maximum size of the heap (int).

363
364 CHAPTER 17. SYSTEM

17.1.2 sf pqueue start

Sets the starting values for the queue.

Call

sf_pqueue_start ();

Definition

void sf_pqueue_start (void)

/*< Set starting values >*/
{
...
}

17.1.3 sf pqueue close

Frees the space allocated by sf pqueue init.

Call

sf_pqueue_close();

Definition

void sf_pqueue_close (void)

/*< Free the allocated storage >*/
{
...
}

17.1.4 sf pqueue insert

Inserts an element in the queue. The smallest element goes first.

17.1. PRIORITY QUEUE (HEAP SORTING) (PQUEUE.C) 365

Call

sf_pqueue_insert (v);

Definition

void sf_pqueue_insert (float* v)

/*< Insert an element (smallest first) >*/
{
...
}

Input parameters

v element to be inserted, smallest first (float*).

17.1.5 sf pqueue insert2

Inserts an element in the queue. The largest element goes first.

Call

sf_pqueue_insert2 (v);

Definition

void sf_pqueue_insert2 (float* v)

/*< Insert an element (largest first) >*/
{
...
}

Input parameters

v element to be inserted, largest first (float*).

v elements to be inserted, largest first (float**).

17.2 Simplified system command (system.c)

17.2.1 sf system

Runs a system command given to it as an input.

Call

sf_system(command);
368 CHAPTER 17. SYSTEM

Definition

void sf_system(const char *command)

/*< System command >*/
{
...
}

Input parameters

command the command which is to be run on the system (const char).

17.3 Generic stack (FILO) structure operations (stack.c)

17.3.1 sf stack init

Initializes the object of type sf stack, that is, it allocates the required memory for the
data and also sets the size of the stack.

Call

s = sf_stack_init (size_t size);

Definition

sf_stack sf_stack_init (size_t size)

/*< create a stack >*/
{
...
}

Input parameters

size size of the stack (size t).

17.3. GENERIC STACK (FILO) STRUCTURE OPERATIONS (STACK.C) 369

Output

s a stack (an object of type sf stack). It is of type sf stack.

17.3.2 sf stack print

Prints the information about the stack on the screen. This may be used for debugging.

Call

sf_stack_print(s);

Definition

void sf_stack_print (sf_stack s)

/*< print out a stack (for debugging) >*/
{
...
}

Input parameters

s a stack (an object of type sf stack). It is of type sf stack.

17.3.3 sf stack get

Extracts the length of the stack.

Call

l = sf_stack_get(s);

Definition

int sf_stack_get (sf_stack s)

/*< extract stack length >*/
370 CHAPTER 17. SYSTEM

{
...
}

Call

sf_stack_set(s, pos);

Definition

void sf_stack_set (sf_stack s, int pos)

/*< set stack position >*/
{
...
}

Input parameters

s a stack (an object of type sf stack). It is of type sf stack.

Output

s->top - s->entry length of the stack. It is of type int.

17.3.4 sf stack set

Sets the position of the pointer in the stack to the specified in the input pos.

sf_stack_set (s, pos);

void sf_stack_set (sf_stack s, int pos)

/*< set stack position >*/
{
...
}
17.3. GENERIC STACK (FILO) STRUCTURE OPERATIONS (STACK.C) 371

Input parameters

s a stack (an object of type sf stack). It is of type sf stack.

pos desired position of the pointer in the stack. It is of type int.

17.3.5 sf push

Inserts the data into the stack.

Call

sf_push(s, data, type);

Definition

void sf_push(sf_stack s, void *data, int type)

/*< push data into stack (requires unique data for each push) >*/
{
...
}

Input parameters

s a stack (an object of type sf stack). It is of type sf stack.

data data which is to be written into the stack. It is of type void*.
type type of the data. It is of type int.

17.3.6 sf pop

Extracts the data from the stack.

Call

dat = sf_pop(s);
372 CHAPTER 17. SYSTEM

Definition

void* sf_pop(sf_stack s)
/*< pop data from stack >*/
{
...
}

Input parameters

s a stack (an object of type sf stack). It is of type sf stack.

Output

old->data extracted data from the stack. It is of type void*.

17.3.7 sf full

Tests whether the stack is full or not.

Call

isfull = sf_full(s);

Definition

bool sf_full (sf_stack s)

/*< test if the stack is full >*/
{
...
}

Input parameters

s a stack (an object of type sf stack). It is of type sf stack.

17.3. GENERIC STACK (FILO) STRUCTURE OPERATIONS (STACK.C) 373

Output

s->top >= s->entry true, if the stack is full, false otherwise. It is of type bool.

17.3.8 sf top

Returns the data type of the top entry of the stack.

Call

typ = sf_top(s);

Definition

int sf_top(sf_stack s)
/*< return the top type >*/
{
...
}

Input parameters

s a stack (an object of type sf stack). It is of type sf stack.

Output

s->top->type type of the top entry. It is of type int.

17.3.9 sf stack close

Frees the space allocated for the stack.

Call

sf_stack_close(s);
374 CHAPTER 17. SYSTEM

Definition

void sf_stack_close(sf_stack s)
/*< free allocated memory >*/
{
...
}

Input parameters

s a stack (an object of type sf stack). It is of type sf stack.

Index

adjoint, 151 truncation, 151

zero padding, 150
conjugate direction method
complex data, 219 product
real data, 212 of operators, 151
conjugate gradient
solver, 202 truncation operator, 151
with preconditioning, 206
zero-padding operator, 150
convolution operator, 150
crosscorrelation operation, 151

dot product
Hermitian, 222

filtering
frequency domain, 181, 185

identity operator, 150

interpolation
1D, 251
2D, 254
3D, 256
complex data, 253
nearest neighbor, 258

null operator, 150

operator
adjoint, 151
convolution, 150
crosscorrelation, 151
identity, 150
linear, 149
null, 150
product, 151

375
376 INDEX

The Elements of Quantitative Investing
From Everand
The Elements of Quantitative Investing
Giuseppe A. Paleologo
No ratings yet
Super Founders What Data Reveals About Billion Dollar Startups 1541768426 9781541768420
No ratings yet
Super Founders What Data Reveals About Billion Dollar Startups 1541768426 9781541768420
279 pages
Java Micro-Project
No ratings yet
Java Micro-Project
26 pages
Modern C++ Programming
From Everand
Modern C++ Programming
Orhan Gazi
No ratings yet
Artificial Intelligence Programming with Python: From Zero to Hero
From Everand
Artificial Intelligence Programming with Python: From Zero to Hero
Perry Xiao
4/5 (1)
Computational Physics
No ratings yet
Computational Physics
165 pages
C-Manual
No ratings yet
C-Manual
122 pages
Matlab
No ratings yet
Matlab
87 pages
Notes Computing
No ratings yet
Notes Computing
201 pages
Matlab Tutor
No ratings yet
Matlab Tutor
86 pages
Notes
No ratings yet
Notes
215 pages
Notes On Engineering Computing
No ratings yet
Notes On Engineering Computing
215 pages
Notes
No ratings yet
Notes
215 pages
Front Matter
No ratings yet
Front Matter
10 pages
MatlabCC Compiler4
No ratings yet
MatlabCC Compiler4
335 pages
Matlab Guide 3ed Toc
No ratings yet
Matlab Guide 3ed Toc
5 pages
Zero To Matlab
No ratings yet
Zero To Matlab
151 pages
Introduction To Matlab
100% (24)
Introduction To Matlab
68 pages
bookAdomaitisAppliedMath4ChE 19utf81 PDF
No ratings yet
bookAdomaitisAppliedMath4ChE 19utf81 PDF
216 pages
Fis Comp
No ratings yet
Fis Comp
99 pages
Gerson J. Ferreira: Introduction To Computational Physics
No ratings yet
Gerson J. Ferreira: Introduction To Computational Physics
99 pages
Data 1010
No ratings yet
Data 1010
130 pages
MatlabOutline PDF
No ratings yet
MatlabOutline PDF
42 pages
Matlab Manual
No ratings yet
Matlab Manual
62 pages
Introduction To Programming Using Matlab
No ratings yet
Introduction To Programming Using Matlab
41 pages
A First Course in Electrical and Computer Eng. L.scharf PDF
No ratings yet
A First Course in Electrical and Computer Eng. L.scharf PDF
321 pages
Haoudout1 4
0% (1)
Haoudout1 4
243 pages
Introduction Matlab
No ratings yet
Introduction Matlab
8 pages
Matlab Finite Element Modeling For Materials Engineers Using MATLAB
No ratings yet
Matlab Finite Element Modeling For Materials Engineers Using MATLAB
74 pages
Advanced Multiplayer Game Development with Ureal Engine 5: A Comprehensive Guide to C++ Scripting
From Everand
Advanced Multiplayer Game Development with Ureal Engine 5: A Comprehensive Guide to C++ Scripting
Vladimir Kiselev
No ratings yet
ADVANCED COLLEGE ALGEBRA STUDY GUIDE
From Everand
ADVANCED COLLEGE ALGEBRA STUDY GUIDE
Harrison K Cook
No ratings yet
Advanced college algebra study guide
From Everand
Advanced college algebra study guide
Harrison Cook
No ratings yet
Gray Hat Hacking the Ethical Hacker's
From Everand
Gray Hat Hacking the Ethical Hacker's
Çağatay Şanlı
5/5 (1)
Securing ChatGPT: Best Practices for Protecting Sensitive Data in AI Language Models
From Everand
Securing ChatGPT: Best Practices for Protecting Sensitive Data in AI Language Models
Matthew C. Smith
No ratings yet
Generative AI for Trading and Asset Management
From Everand
Generative AI for Trading and Asset Management
Hamlet Jesse Medina Ruiz
No ratings yet
ChatGPT for Business: Strategies for Success
From Everand
ChatGPT for Business: Strategies for Success
Matthew C. Smith
No ratings yet
Unlocking Statistics for the Social Sciences
From Everand
Unlocking Statistics for the Social Sciences
Norma Sinclair
No ratings yet
Plain JavaScript: Learning the Front-End
From Everand
Plain JavaScript: Learning the Front-End
Roger Beans-Rivet
No ratings yet
Vulkan Expert: Mastering High-Performance Graphics: Vulcan Fundamentals
From Everand
Vulkan Expert: Mastering High-Performance Graphics: Vulcan Fundamentals
Kameron Hussain
No ratings yet
Content Creation Revolution with chatGPT
From Everand
Content Creation Revolution with chatGPT
Maria Cowen
No ratings yet
Mathematics N4: FET College Nated, #6
From Everand
Mathematics N4: FET College Nated, #6
Efetobo Emede
No ratings yet
Multicore DSP: From Algorithms to Real-time Implementation on the TMS320C66x SoC
From Everand
Multicore DSP: From Algorithms to Real-time Implementation on the TMS320C66x SoC
Naim Dahnoun
No ratings yet
Time-dependent Behaviour and Design of Composite Steel-concrete Structures
From Everand
Time-dependent Behaviour and Design of Composite Steel-concrete Structures
Massimiliano Bocciarelli
No ratings yet
OpenGL Deep Dive: Expert Techniques and Performance Optimization: OpenGL
From Everand
OpenGL Deep Dive: Expert Techniques and Performance Optimization: OpenGL
Kameron Hussain
No ratings yet
The Linux Terminal for Advanced Users - The Command Line Made Easy: First Edition
From Everand
The Linux Terminal for Advanced Users - The Command Line Made Easy: First Edition
Michael Basler
No ratings yet
Foundations of Image Science
From Everand
Foundations of Image Science
Harrison H. Barrett
No ratings yet
Mastering AUTOSAR: A Comprehensive Guide for Automotive Engineers
From Everand
Mastering AUTOSAR: A Comprehensive Guide for Automotive Engineers
Mohamad Charara
No ratings yet
C Programming for the Pc the Mac and the Arduino Microcontroller System
From Everand
C Programming for the Pc the Mac and the Arduino Microcontroller System
Peter D Minns
No ratings yet
Systems Engineering Principles and Practice
From Everand
Systems Engineering Principles and Practice
Alexander Kossiakoff
3.5/5 (4)
Modern C++ Programming: Including the recent standards C++11, C++17, C++20, C++23
From Everand
Modern C++ Programming: Including the recent standards C++11, C++17, C++20, C++23
Orhan Gazi
No ratings yet
Stack Computers: The New Wave
From Everand
Stack Computers: The New Wave
Philip Koopman
No ratings yet
Computer Aided Design of Electrical Machines
From Everand
Computer Aided Design of Electrical Machines
K.M. Vishnu Murthy
No ratings yet
A Discourse Analysis of 1 Peter
From Everand
A Discourse Analysis of 1 Peter
Ervin Ray Starwalt
No ratings yet
Mastering OpenGL: From Basics to Advanced Rendering Techniques: OpenGL
From Everand
Mastering OpenGL: From Basics to Advanced Rendering Techniques: OpenGL
Kameron Hussain
No ratings yet
Agri-Adapt Climate & Biotech Solutions: agriculture, #1
From Everand
Agri-Adapt Climate & Biotech Solutions: agriculture, #1
mohd raheeluddin
No ratings yet
Small Unmanned Fixed-wing Aircraft Design: A Practical Approach
From Everand
Small Unmanned Fixed-wing Aircraft Design: A Practical Approach
Andrew J. Keane
No ratings yet
Data Science Using Python and R
From Everand
Data Science Using Python and R
Chantal D. Larose
No ratings yet
Beginning Software Engineering
From Everand
Beginning Software Engineering
Rod Stephens
4.5/5 (2)
Programmable Logic Controllers: A Practical Approach to IEC 61131-3 using CoDeSys
From Everand
Programmable Logic Controllers: A Practical Approach to IEC 61131-3 using CoDeSys
Dag H. Hanssen
No ratings yet
Mechanical Characterization of Materials and Wave Dispersion: Instrumentation and Experiment Interpretation
From Everand
Mechanical Characterization of Materials and Wave Dispersion: Instrumentation and Experiment Interpretation
Yvon Chevalier
No ratings yet
Cybersecurity for Executives: A Guide to Protecting Your Business
From Everand
Cybersecurity for Executives: A Guide to Protecting Your Business
Matthew C. Smith
No ratings yet
Kellory the Warlock
From Everand
Kellory the Warlock
Lin Carter
No ratings yet
DLL ENG8 1stQ 2nd Week Checked
100% (5)
DLL ENG8 1stQ 2nd Week Checked
5 pages
Application Letter
No ratings yet
Application Letter
2 pages
Rough Estimate
No ratings yet
Rough Estimate
3 pages
Controlling of Cooling Tower Return Temperature and Energy Saving
No ratings yet
Controlling of Cooling Tower Return Temperature and Energy Saving
6 pages
Department of Education: Ikatlong Markahan Unang Sumatibong Pagsusulit Sining 1
No ratings yet
Department of Education: Ikatlong Markahan Unang Sumatibong Pagsusulit Sining 1
2 pages
Chapter 9
No ratings yet
Chapter 9
6 pages
(Translated Texts for Historians, 42) Magnus Aurelius Cassiodorus Senator, Mark Vessey, James W. Halporn (Transl.) - Institutions of Divine and Secular Learning and on the Soul-Liverpool University Pr
No ratings yet
(Translated Texts for Historians, 42) Magnus Aurelius Cassiodorus Senator, Mark Vessey, James W. Halporn (Transl.) - Institutions of Divine and Secular Learning and on the Soul-Liverpool University Pr
328 pages
Chapter 3-3
No ratings yet
Chapter 3-3
12 pages
A Little Princess - Act 3 (Scene 1 Only)
No ratings yet
A Little Princess - Act 3 (Scene 1 Only)
4 pages
Dungeon Dice Monsters Rules
No ratings yet
Dungeon Dice Monsters Rules
5 pages
Class X CH-6 (BBQ, TBQ)
No ratings yet
Class X CH-6 (BBQ, TBQ)
5 pages
Síntesis de Calix (4) Pirrol
100% (1)
Síntesis de Calix (4) Pirrol
5 pages
Airport Conversation Topics Dialogs Games Information Gap PDF
No ratings yet
Airport Conversation Topics Dialogs Games Information Gap PDF
45 pages
Middle Grade Mania Activity Kit
No ratings yet
Middle Grade Mania Activity Kit
10 pages
Plumbing Design Criteria Water Supply Demand Calculation Reference Code UPC - 2009
No ratings yet
Plumbing Design Criteria Water Supply Demand Calculation Reference Code UPC - 2009
18 pages
PROGRESSION SHEETS Form 1,2,3,4, and 5
No ratings yet
PROGRESSION SHEETS Form 1,2,3,4, and 5
18 pages
Schedule of Sicbas-2023 Edit Satu Halaman
No ratings yet
Schedule of Sicbas-2023 Edit Satu Halaman
1 page
Newsletter 042013
No ratings yet
Newsletter 042013
8 pages
Geomembrane Materials For Potable Water Applications: AWWA Standard
No ratings yet
Geomembrane Materials For Potable Water Applications: AWWA Standard
24 pages
General English A1 - Imran B. Ibrahim
No ratings yet
General English A1 - Imran B. Ibrahim
30 pages
STD.X Social Science Geography
No ratings yet
STD.X Social Science Geography
3 pages
Technical Data CSDM Baumann - JWE-Baumann GmbH
No ratings yet
Technical Data CSDM Baumann - JWE-Baumann GmbH
8 pages
Letourneau-Cara-Goudreau_evaluation MHSI
No ratings yet
Letourneau-Cara-Goudreau_evaluation MHSI
14 pages
Organisms and Population Short Notes - Astha Singh.pdf
No ratings yet
Organisms and Population Short Notes - Astha Singh.pdf
7 pages
KJO2086
No ratings yet
KJO2086
13 pages
Resume Iim Nsy
No ratings yet
Resume Iim Nsy
18 pages
Chapter 1 Business Economics
No ratings yet
Chapter 1 Business Economics
71 pages

Manual PDF

Uploaded by

Manual PDF

Uploaded by

Madagascar Programming Reference Manual

Mohammad Akbar Zuberi

Seismic Wave Analysis Group

2 An example: Finite-Difference modeling 13

4 Preparing for input 31

5 Operations with RSF files 79

5.3 Complex number operations (komplex.c) . . . . . . . . . . . . . . . . . . . . 120

6 Error handling 149

7 Linear operators 153

8 Data analysis 177

11.8 1-D ENO interpolation (eno.c) . . . . . . . . . . . . . . . . . . . . . . . . . 274

13 Ray tracing 301

14 General tools 313

This document is a contribution to the Madagascar developers community and it is meant

Ui+1 = [∆U − f (t)]v 2 ∆t2 + 2Ui − Ui−1 ,

1 /* time-domain acoustic FD modeling */

80 for (ix=0; ix<nx; ix++) {

2.3 Explanation of the code

2-4: 2 #include <rsf.h>

7: 7 float c0=-30./12.,c1=+16./12.,c2=- 1./12.;

9-14: 9 bool verb; /* verbose flag */

16-17: 16 float *ww,**vv,**rr; /* I/O arrays*/

22-26: 22 /* setup I/O files */

46-50: 46 /* allocate temporary arrays */

52-59: 52 for (iz=0; iz<nz; iz++) {

61-64: 61 /* MAIN LOOP */

returns to the start the new value of it is 1, so

78-83: 78 /* inject wavelet */

f (x, z, 0) = g(x, z) = ww(0)rr(x, z),

85-90: 85 /* scale by velocity */

92-102 92 /* time step */

Ui+1 = [∆U − f (t)]v 2 ∆t2 + 2Ui − Ui−1 .

104-106: 104 /* write wavefield to output */

107-109: 107 if(verb) fprintf(stderr,"\n");

3.1 Data types

3.1.1 Complex numbers and FFT

kiss fft scalar

kiss fft cpx

kiss fft cfg

This is an object of type kiss fft state (which is a C data structure).

kiss fft state

kiss fftr cfg

This is an object of type kiss fftr state (which is a C data structure).

kiss fftr state

Preparing for input

4.1 Convenience allocation programs (alloc.c)

sf_alloc (n, size);

void *sf_alloc (size_t n /* number of elements */,

n number of elements (size t).

ptr a void pointer pointing to the allocated block of memory.

sf_realloc (ptr, n, size);

void *sf_realloc (void* ptr /* previous data */,

ptr pointer to the previously assigned memory block.

ptr pointer to the new aggregate block.

ptr = sf_charalloc (n);

char *sf_charalloc (size_t n /* number of elements */)

n number of elements (size t).

ptr a void pointer pointing to the allocated block of memory.

ptr = sf_ucharalloc (n);

unsigned char *sf_ucharalloc (size_t n /* number of elements */)

n number of elements (size t).

ptr a void pointer pointing to the allocated block of memory.

ptr = sf_shortalloc (n);

short *sf_shortalloc (size_t n /* number of elements */)

n number of elements (size t).

ptr a void pointer pointing to the allocated block of memory.

ptr = sf_intalloc (n);

int *sf_intalloc (size_t n /* number of elements */)

n number of elements (size t).

ptr a void pointer pointing to the allocated block of memory.

ptr = sf_largeintalloc (n);

off_t *sf_largeintalloc (size_t n /* number of elements */)

n number of elements (size t).

ptr a void pointer pointing to the allocated block of memory.

ptr = sf_floatalloc (n);

float *sf_floatalloc (size_t n /* number of elements */)

16-17: 16 float ww,vv,rr; / I/O arrays*/

void sf_alloc (size_t n / number of elements */,

void sf_realloc (void ptr /* previous data */,

char sf_charalloc (size_t n / number of elements */)

unsigned char sf_ucharalloc (size_t n / number of elements */)

short sf_shortalloc (size_t n / number of elements */)

int sf_intalloc (size_t n / number of elements */)

off_t sf_largeintalloc (size_t n / number of elements */)

float sf_floatalloc (size_t n / number of elements */)

sf_complex sf_complexalloc (size_t n / number of elements */)

/< complex 4-D allocation, out[0][0][0] points to a contiguous array >/

bool sf_boolalloc (size_t n / number of elements */)

/< char 2-D allocation, out[0] points to a contiguous array >/