ahay/src/authoring-sf-programs-matlab

When to use

Use this skill when a researcher already has MATLAB installed (licensed) and wants to write an sf<name> program as a .m script, leveraging existing MATLAB toolboxes (e.g. Signal Processing Toolbox, Optimization Toolbox) that would be cumbersome to replicate in C or Python.

File naming: the MATLAB main script must be named M<name>.m — same M prefix convention used by all Madagascar languages. There is no sf prefix in the source file; the installed binary is called sf<name>.

Important — compile-time requirement: the MEX backing library (rsf_create.mex*, rsf_read.mex*, etc.) is compiled at scons configure time only when MATLAB is detected on the build host. See api/matlab/SConstruct: the entire MEX build is gated on 'matlab' in env.get('API',[]). Without a licensed MATLAB on the build machine the API produces nothing and MATLAB programs cannot run.

Octave overlap: the .m extension is shared with Octave. The build system selects Matlab vs. Octave at configure time via the API variable; they are mutually exclusive at build time. For Octave programs see authoring-sf-programs-octave/SKILL.md.

Always load the shared skill alongside this one: `skills/authoring-sf-programs/` — file naming, self-documentation, parameter conventions, error handling, and testing conventions that apply to every sf-program regardless of language.

Skeleton

The canonical pattern is taken from api/matlab/test/clip.m. A MATLAB sf-program is a plain function (not a script) that receives RSF filenames as arguments:

function M<name>(in, out, param1)
%<NAME>  One-sentence synopsis (appears in sfdoc output).
%
% par1=default  description of parameter
 
% 1. Query dimensions of the input file.
dims = rsf_dim(in);          % returns column vector [n1; n2; ...]
n1   = dims(1);
n2   = prod(dims(2:end));
 
% 2. Read a named parameter from the input header.
clip = rsf_par(in, 'clip', 'f', 1.0);  % type 'f'=float, 'i'=int, 'b'=bool
 
% 3. Create output header, inheriting geometry from input.
rsf_create(out, in);         % copy header: rsf_create(outfile, infile)
% -- OR, specify sizes explicitly:
% rsf_create(out, [n1; n2]);
 
% 4. Allocate a trace-length working buffer.
trace = zeros(1, n1);
 
% 5. Loop over traces, reading and writing sequentially.
for i2 = 1:n2
    rsf_read(trace, in, 'same');          % read next n1 samples
    % ... process trace ...
    trace(trace >  clip) =  clip;
    trace(trace < -clip) = -clip;
    rsf_write(trace, out, 'same');        % write next n1 samples
end

The 'same' flag on rsf_read / rsf_write advances an internal file pointer so successive calls walk through the binary data sequentially — essential for loop-based trace processing.

For single-call whole-file I/O, prefer rsf_read_all / rsf_write_all (see cheat sheet below).

API cheat sheet

All functions are MEX-compiled C entry points. nrhs = number of right-hand side (input) arguments; nlhs = number of left-hand side (output) arguments.

Type details for `rsf_par`: type string first character selects the branch — 'f' or 'r' → float, 'i' or 'd' → integer, 'l' or 'b' → logical. The return value is always a double scalar.

Complex data: rsf_read / rsf_write handle SF_COMPLEX files automatically when buf / data is a MATLAB complex array (mxIsComplex).

`m8r` MEX (m8r.c → m8r.mex*): exposes rsf_filter(cmd, data, deltas, origins, labels, units) — runs an arbitrary Madagascar binary as a filter on MATLAB data via temp files. Useful for calling existing sf* programs from within a MATLAB session.

Build integration

The MEX binaries are built by api/matlab/SConstruct, which is invoked automatically by the top-level Madagascar scons when MATLAB is present:

# api/matlab/SConstruct (excerpt)
if 'matlab' in env.get('API',[]):
    mex = env.get('MEX')          # path to mex compiler, detected at configure time
    suffix = env.get('MEXSUFFIX') # platform suffix, e.g. .mexa64 / .mexmaci64
    if mex:
        mexcom = mex + " CC=$CC CFLAGS='$CFLAGS $_CCCOMCOM -fPIC' ..."
        for inp in Split('m8r par dim read_header read read_all write write_all create'):
            ...
            mfile = env.Command(cfile+suffix, cfile+'.c', mexcom)
            if root:
                install = env.Install(libdir, mfile)

MATLAB must be detectable by the configure step for this block to execute. If MATLAB is not installed, env.get('API',[]) will not contain 'matlab' and the entire block is skipped — no MEX files are produced and MATLAB programs will fail with "undefined function" errors at runtime.

No `UserSconsTargets` for MATLAB: the bldutil.UserSconsTargets() helper in framework/bldutil.py supports .c, .f90, .py, and .jl attributes — not .m. MATLAB programs are not automatically discovered or compiled by the standard user directory SConstruct machinery.

Deploying a new MATLAB program: place M<name>.m somewhere on MATLAB's path (or in the current directory) and ensure that the MEX binaries installed to libdir are also on MATLAB's path. The simplest approach:

addpath('/path/to/madagascar/lib')   % directory containing rsf_*.mex* files
addpath('/path/to/your/Mname.m')
M<name>(input_rsf, output_rsf, ...)

There is no automated install target for .m main programs analogous to the C or Python install targets.

Pointers

Files in api/matlab/ with one-line descriptions:

Shared conventions

All Madagascar sf-programs — regardless of language — follow the same conventions for file naming, self-documentation comments, parameter style, error handling, and testing. See `skills/authoring-sf-programs/` for the full shared reference.