Library Reference
If you are programming with Madagascar, please use the utilities described below instead of creating your own equivalents. The RSF library is written in C, and all facilities offered by it are available directly to the C API via inclusion of header files and linking with the library. Other APIs only have access to a limited set of functions from the library. The ultimate guide to what the libraries provide is the file RSFSRC/filt/lib/SConstruct, which contains the instructions for building the RSF library in C and the interfaces to it for the various APIs.
Contents
C API
Macros
The following useful macros are accessible through the C and C++ APIs:
Functions | ||
---|---|---|
Name | Value | Meaning |
SF_ABS(a) | (a) >= 0 ? (a) : (-(a)) | Absolute value |
SF_MAX(a,b) | (a) < (b) ? (b) : (a) | Maximum of two values |
SF_MIN(a,b) | (a) < (b) ? (a) : (b) | Minimum of two values |
SF_SIG(a) | (a) >= 0 ? 1 : -1 | Sign function |
General constants | ||
---|---|---|
Name | Value | Meaning |
SF_EOL | '\014' | End-of-line character |
SF_EOT | '\004' | End-of-tape (?) character |
SF_EPS | FLT_EPSILON | The smallest X of type float such that 1.0 + X != 1.0. From float.h |
SF_HUGE | FLT_MAX | The largest finite representable value of type float. From float.h |
SF_MAX_DIM | 9 | Maximum number of dimensions in a RSF file |
SF_PI | 3.141592653589793 | The number pi |
SEG-Y-related constants | ||
---|---|---|
Name | Value | Meaning |
SF_SEGY_FORMAT | 24 | Byte position in SEG-Y binary reel header, where info on encoding of data samples is kept (format parameter in sfsegyread) |
SF_SEGY_NS | 20 | Byte position in SEG-Y binary reel header, where info on nr of samples in one trace is kept (ns parameter in sfsegyread) |
SF_SEGY_DT | 16 | Byte position in SEG-Y binary reel header, where info on time sampling is kept |
SF_EBCBYTES | 3200 | Bytes in the SEG-Y EBCDIC reel header |
SF_BNYBYTES | 400 | Bytes in the SEG-Y binary reel header |
SF_HDRBYTES | 240 | Bytes in each individual SEG-Y trace header |
SF_NKEYS | 71 | Number of mandated header fields |
SF_BHKEYS | 27 | Number of mandated binary fields |
These macros were found with: <bash>grep '# define SF_' $RSFROOT/include/rsf.h</bash>
Data types
Functions
- sf_input (needs to be followed by a call to sf_fileclose at the end of the program)
- sf_fileclose
Function wrappers
These programs make the respective function callable from the command line, so that it can be used directly with files/other programs through "metaprograms" (shell/Python scripts). This allows the user to get the best of all worlds -- fast development in Python, all of Madagascar's visualization tools for debugging, and the speed of code written in C. This allows fast prototyping, followed by writing a production version in C calling the functions used.
Library function | Program |
---|---|
sf_filedims | filedims |
sf_leftsize | leftsize |
sf_quantile | quantile |
C++ API
Macros
Same as for the C API.
Fortran 77 API
Fortran 90 API
The interface is accessed by including a use rsf statement in your program. The source code for the rsf module can be viewed in the repository. A (G) means that the entity was featured in the Guide to API.
Constants
For use with gettype and settype:
- sf_char=1
- sf_complex=4
- sf_float=3 (G)
- sf_int=2
- sf_short=5
- sf_uchar=0
For use with sf_seek:
- sf_seek_set=0
- sf_seek_cur=1
- sf_seek_end=2
Data types
All procedures in Madagascar's F90 API act upon or take as input one of the following data types:
- axa: Holds some info about a hypercube axis (integer::n; real::o,d)
- file: Simply an interface to the sf_file type described in the C library.
Functions
Data types are indicated in italics and intent in bold italics. In the Wrapper for column, procedure names with no other description belong to the C library. The G? heading means "Demo-ed in the Guide to the F90 API?".
Name | Arguments | Result | What it does | Wrapper for | G? |
axisname | integer in i, optional character in mystring | character mystringi | Given a string mystring and a positive number i, this function will return the concatenation of the string and the number converted to string (mystringi). In practice, mystring will probably be "n", "o", "d", "label" or "unit", in preparation for writing to a header file. Default value for mystring is "n". | Verbose string operations in F90 | N |
dimension | file in tag, integer out dims | integer n | Returns number of dimensions of already-open file handle tag in n, and the dimension values in dims | sf_filedims | N |
filesize | file in tag, optional integer in n | integer nr_elements | Computes number of n-dimensional subcubes in file hypercube. When n is absent, default is zero and the number of elements in file. | sf_filesize, sf_leftsize. | Y |
gettype | file in tag | integer type | Reads the binary data type from the already-open file handle tag. The type constant should be then compared in the user-written code with one of the six type constants provided by the F90 interface | sf_gettype | Y |
rsf_input | optional character in filename | file tag | Opens filename for reading and returns file handle tag. The default is filename="in", which corresponds to the standard input stream | sf_input | Y |
rsf_output | optional character in filename | file tag | Opens filename for writing and returns file handle tag. The default is filename="out", which corresponds to the standard output stream | sf_input | Y |
Subroutines
Because subroutine names are preceded by a call statement, it is easy to find occurrences of them being used by typing: <bash>grep "call subroutine_name" {filt,user}/*/*.f90 user/*/*/*.f90</bash> in RSFSRC.
Below, data types are indicated in italics and intent in bold italics. The type multi means that multiple data types can be used (subroutine is overloaded). In the Wrapper for column, procedure names with no other description belong to the C library. The G? heading means "Demo-ed in the Guide to the F90 API?".
Name | Arguments | What it does | Wrapper for | G? |
from_either | file in tag, character in name, multi out value, optional multi in default | This subroutine looks for the real or integer variable name first in the history file, then in the parameter table. If it it is not found and default is present, it assigns it to value, otherwise it terminates the program. | sf_histint, sf_getint | N |
from_par | optional file in tag, character in name, multi out value, optional multi in default | If already-opened file handle tag is supplied, then it reads into value a parameter designated by name from a history file. Else, it reads it from the parameter table. If the parameter is not found and a default is present, then that is used, else ends with failure. It can read from both history files and parameter tables the following types: integer, integer array, real. Strings can be read only from the history file, and not from the parameter table. Real arrays, logicals and logical arrays can be read only from the parameter table. | sf_histint, sf_getint, sf_histints, sf_getints, sf_histfloat, sf_getfloat, sf_histstring, sf_getfloats, sf_getbool, sf_getbools | Y |
iaxa | file in tag, axa out axisname, integer in axisnr | Read axis with number axisnr as axis axisname from the already-open file header indicated by tag | Multiple calls to F90 API's from_par | N |
oaxa | file in tag, axa in axisname, integer in axisnr | Write axis axisname (i.e. its n, o, d) as axis with number axisnr to the already-open file header indicated by tag | Multiple calls to F90 API's from_par | N |
raxa | axa in axisname | unformatted write to I/O unit nr. 0 (usually stdout, but system-dependent) of the contents of the axisname structure (n, o, d) | F90 write statement | N |
rsf_read | file in tag, multi out array, optional integer in n | If n is specified, the real or complex array must be 1-D and n elements will be read into it from an already-opened file specified by tag. If n is not specified, reads enough to fill the array, and the array can be 1-D, 2-D, 3-D, 4-D or 5-D. | sf_floatread, sf_complexread | Y |
rsf_write | file in tag, multi in array, optional integer in n | If n is specified, real or complex array must be 1-D and n elements will be written to an already-opened file specified by tag. If n is not specified, writes to file the entire contents of the array, and the array can be 1-D, 2-D, 3-D, 4-D or 5-D | sf_floatwrite, sf_complexwrite | Y |
settype | file in tag, integer in file_type | Write a type for the binary data to the already-open file header indicated by tag. Data type constants are also provided by the F90 API. | sf_settype | N |
to_par | file in tag, character in name, multi in value | Writes name=value to already-opened file specified by tag. Value can be integer, integer array, real or character. | sf_putint, sf_putints, sf_putfloat, sf_putstring | N |
Functions from the C library
Functions from the C library for which an interface has been defined at the end of RSFSRC/api/f90/fortran.c can be called directly from Madagascar F90 programs. The programmer must know, however, that an argument type mismatch will result in a silent failure, with no informative errors. There may be other sources of problems as well. Caution therefore must be advised when calling these functions. The reason for these issues is that if a FORTRAN90 routine needs to pass a scalar parameter to a C routine, there is no standard way to ensure that a value is passed rather than an address. The success rate of calling C from Fortran is compiler-dependent and special types may have to be defined for portability. If you do have to call a C function from F90, follow the examples of the functions below. Use the C library reference to find argument and output types. A C-to-F90 data type dictionary follows:
C | F90 |
---|---|
RSFFILE | type(file) |
INT | integer |
OFFSETT | integer(kind=OFFKIND) |
Void-output functions callable as subroutines
These can be treated as subroutines, and accessed with a call statement. Follow
- sf_error (G)
- sf_init (G) (Can it also be called in subroutines if we want to isolate I/O operations there?)
- sf_seek
Non-void-output functions
It is a good idea to declare in your program the function output type and use the keyword external, i.e.:
real, external :: sf_dosomething
Alternately, you may define a F90 interface block for the procedure(s).
Several examples can be found in RSFSRC/filt/lib/rsf.f90, but they are not enumerated here because F90 wrappers exist for them and they should be used instead of the direct calls to the C library functions.
Matlab API
Data types are indicated in italics and intent in bold italics. In the Wrapper for column, procedure names with no other description belong to the C library. The G? heading means: "Demo-ed in the Guide to the Matlab API?"
Name | Arguments | What it does | Wrapper for | G? |
rsf_create | Arg 1: string (row vector) in new_file_name; Arg 2: string (row vector) in old_file_name, or double (column vector) in new_file_cube_dims |
Writes to disk RSF header of native_float hypercube of desired dimensions. Takes as input the name of the new file and either the name of another file with a cube of the same size, or a column with cube dimensions | sf_fileflush, or sf_putint and sf_setformat | Y |
rsf_dim | Arguments | What it does | sf_filedims | Y |
rsf_par | Arguments | What it does | Wrapper for | N |
rsf_read | Arguments | What it does | Wrapper for | Y |
rsf_write | Arguments | What it does | Wrapper for | Y |
Octave API
Python API
To use the python api, you need to import the rsf package via:
import rsf
The rsf package has the following members:
Class | Use | Constructor | Example | Available Methods |
---|---|---|---|---|
File | ||||
Filter | ||||
Movie | ||||
Input | Provides a basic way to read rsf files. | file = rsf.Input(name) | input = rsf.Input(name); n1 = input.int('n1') | read(data), data is a numpy array to be read into. |
close() | ||||
float(key, default=None), key is a string to be extracted, e.g. 'n1'. | ||||
int(key, default=None), key is a string to be extracted. | ||||
ints(key, num, default=None), key is a string, num is the number of ints. | ||||
put(key, val), key is a string to set the value for, val is a numerical value (int or float). | ||||
... and more, type help(rsf.Input) on a python interactive session for more information. | ||||
Output | Provides a way to output numpy arrays to rsf files. | file = rsf.Output(name) | output=rsf.Output(name); output.write(data) | |
OverUnder | ||||
Overlay | ||||
Par | Provides a method for accessing rsf parameters passed from the command line. | par = rsf.Par() | par = rsf.Par(); velname = par.string('vel') | |
SideBySide | ||||
Temp | ||||
Vplot | View vplot graphics files from within python. | plot = rsf.Vplot(name) | plot = rsf.Vplot(name); plot.show() | |
Vppen |
SCons custom methods
Custom builders
Name | Implemented in | What it does |
RSF_Include | RSFSRC/configure.py, function: Header | |
RSF_Place | RSFSRC/configure.py, function: Place | |
RSF_Pycompile | RSFSRC/configure.py, function:Pycompile | |
RSF_Docmerge | RSFSRC/configure.py, function: Docmerge |
more stuff in RSFSRC/framework/rsfproj.py