Editing Guide to madagascar API (section)

==Fortran-90 interface==

The Fortran-90 clip function is listed below.
<syntaxhighlight lang="fortran">
program Clipit
  use rsf

  implicit none
  type (file)                      :: in, out
  integer                          :: n1, n2, i1, i2
  real                             :: clip
  real, dimension (:), allocatable :: trace

  call sf_init()            ! initialize RSF
  in = rsf_input()
  out = rsf_output()

  if (sf_float /= gettype(in)) call sf_error("Need float type")

  call from_par(in,"n1",n1)
  n2 = filesize(in,1)

  call from_par("clip",clip) ! command-line parameter 

  allocate (trace (n1))

  do i2=1, n2                ! loop over traces
     call rsf_read(in,trace)
     
     where (trace >  clip) trace =  clip
     where (trace < -clip) trace = -clip

     call rsf_write(out,trace)
  end do

  deallocate (trace)

end program Clipit
</syntaxhighlight>

Let us examine it in detail.
<syntaxhighlight lang="fortran">
  use rsf
</syntaxhighlight>

The program starts with importing the <tt>rsf</tt> module.
<syntaxhighlight lang="fortran">
  call sf_init()            ! initialize RSF
</syntaxhighlight>

A call to <tt>sf_init</tt> is needed to initialize the command-line
interface.
<syntaxhighlight lang="fortran">
  in = rsf_input()
  out = rsf_output()
</syntaxhighlight>

The standard input and output files are initialized with
<tt>rsf_input</tt> and <tt>rsf_output</tt> functions. Both functions
accept optional arguments. For example, if the command line contains
<tt>vel=velocity.rsf</tt>, then both
<tt>rsf_input("velocity.rsf")</tt> and <tt>rsf_input("vel")</tt> are
acceptable.
<syntaxhighlight lang="fortran">
  if (sf_float /= gettype(in)) call sf_error("Need float type")

</syntaxhighlight>

A call to <tt>from_par</tt> extracts the "<tt>n1</tt>" parameter
from the input file. Conceptually, the RSF data model is a
multidimensional hypercube.  The <tt>n1</tt> parameter refers to the
fastest axis. If the input dataset is a collection of traces,
<tt>n1</tt> corresponds to the trace length. We could proceed in a
similar fashion, extracting <tt>n2</tt>, <tt>n3</tt>, etc. If we are
interested in the total number of traces, like in the clip example, a
shortcut is to use the <tt>filesize</tt> function.  Calling
<tt>filesize(in)</tt> returns the total number of elements in the
hypercube (the product of <tt>n1</tt>, <tt>n2</tt>, etc.), calling
<tt>filesize(in,1)</tt> returns the number of traces (the product of
<tt>n2</tt>, <tt>n3</tt>, etc.), calling <tt>filesize(in,2)</tt>
returns the product of <tt>n3</tt>, <tt>n4</tt>, etc. By calling
<tt>filesize</tt>, we avoid the need to extract additional parameters
for the hypercube dimensions that we are not interested in.
<syntaxhighlight lang="fortran">
  n2 = filesize(in,1)
</syntaxhighlight>

The clip parameter is read from the command line, where it can be
specified, for example, as <tt>clip=10</tt>. If we knew a good default
value for <tt>clip</tt>, we could specify it with an optional
argument, i.e. <tt>call~from_par("clip",clip,default)</tt>.
<syntaxhighlight lang="fortran">
  allocate (trace (n1))

  do i2=1, n2                ! loop over traces
     call rsf_read(in,trace)
     
     where (trace >  clip) trace =  clip
     where (trace < -clip) trace = -clip

</syntaxhighlight>

Finally, we do the actual work: loop over input traces, reading,
clipping, and writing out each trace.
===Compiling===
To compile the Fortran-90 program, run
<pre>
f90 clip.f90 -I&#36;RSFROOT/include -L&#36;RSFROOT/lib -lrsff90 -lrsf -lm
</pre>
Change <tt>f90</tt> to the Fortran-90 compiler appropriate for your system and
include additional compiler flags if necessary. The flags that RSF typically
uses are in <tt>&#36;RSFROOT/share/madagasacar/etc/config.py</tt>.

The complete specification for the F90 API can be found [[Library_Reference#Fortran_90_API | on the Library Reference page]].