ahay/src/authoring-sf-programs-julia

When to use

Load this skill when writing a new sf<name> program in Julia. Julia is a good fit when your collaborators already work in that ecosystem, when you want direct access to the Julia numerical stack (FFTW.jl, LinearAlgebra, LoopVectorization, etc.) without a foreign-function call, or when you need seamless FFI to C but prefer Julia syntax over Python.

The source file is named M<name>.jl and lives in user/<youruser>/. The build system handles the rest. Framework support for Julia programs exists via UserSconsTargets.jl (see Build integration). There are no existing M*.jl programs in the tree yet; use api/julia/test/ as templates (especially clip.jl for the core pattern and afdm.jl for a heavier numerical example).

The Julia API (m8r.jl) is a thin wrapper around libdrsf via ccall. All data types map to their C equivalents: Float32, Int32, ComplexF32, Int16, UInt8.

See also: Shared language-agnostic conventions

Skeleton

Modelled on api/julia/test/clip.jl:

#!/usr/bin/env julia
# M<name>.jl — one-sentence description of what this program does.
#
# Additional comments, references, and notes go here.
# (No structured doc-scraper for Julia yet; the comment is for human readers.)
 
import m8r
 
# --- Parameter retrieval (from command line or par= file) ---
clip  = m8r.getfloat("clip")          # required — exits if absent
verb  = m8r.getbool("verb",  false)   # optional — default false
niter = m8r.getint("niter",  100)     # optional — default 100
 
# --- Open standard input / output ---
inp = m8r.input("in")
out = m8r.output("out")
 
# --- Read header fields from inp ---
n1 = m8r.histint(inp, "n1")
n2 = m8r.leftsize(inp, 1)   # total samples / n1; works for any nd array
 
# --- Copy header to output, optionally modifying axes ---
m8r.putint(out,    "n1", n1)
m8r.putfloat(out,  "d1", m8r.histfloat(inp, "d1"))
m8r.putfloat(out,  "o1", m8r.histfloat(inp, "o1"))
m8r.putstring(out, "label1", m8r.histstring(inp, "label1"))
m8r.putstring(out, "unit1",  m8r.histstring(inp, "unit1"))
 
# --- Trace loop ---
trace = Array{Float32}(undef, n1)
for i2 in 1:n2
    m8r.floatread(trace, n1, inp)
 
    # ... process trace ...
    clamp!(trace, -clip, clip)
 
    m8r.floatwrite(trace, n1, out)
end

Key structural points:

• import m8r (not using m8r) keeps the namespace explicit; using m8r is also

valid and exports rsf_read / rsf_write.

• m8r.__init__() is called automatically when the module loads; do not call

sf_init manually.

• m8r.leftsize(file, 1) returns total_samples / n1 — the product of all axes

beyond the first. Use this to drive the outer loop without hard-coding dimensions.

• Auxiliary files: m8r.input("vel") opens the file named by the command-line

argument vel=<path>.

API cheat sheet

Build integration

api/julia/SConstruct installs m8r.jl into $RSFROOT/lib/ at build time. The framework-level dispatch for Julia programs happens in UserSconsTargets.jl (located in the SCons framework tree). To add a Julia main program to your user directory's build:

# user/<youruser>/SConstruct
import sys, os
sys.path.append('../../framework')
import bldutil
# New-style (preferred)
targets = bldutil.UserSconsTargets()
targets.jl = 'myprogram'          # base name only — no M prefix, no .jl suffix
targets.build_all(env, glob_build, srcroot, bindir, libdir, pkgdir)

At configure time, Madagascar's build system checks for a Julia executable. If Julia is not found, targets.jl programs are silently skipped; no error is raised. To verify Julia was detected during configuration, inspect $RSFROOT/include/config.py for a JULIA key, or check env.get('JULIA') inside the SConstruct.

Self-documentation for Julia programs is not yet scraped by framework/rsf/doc.py (no comment['jl'] regex entry); write a clear comment block at the top of your M<name>.jl for human readers, and plan to add sfdoc support manually if needed.

Pointers

Files in api/julia/ and their purpose:

Julia-specific quirks

• Type precision: the API uses Float32 and Int32 throughout (matching the C

API). Passing Float64 arrays to floatwrite requires explicit conversion: m8r.floatwrite(Float32.(vec(arr)), n, out). The high-level rsf_write does this conversion automatically.

• Output type inheritance: m8r.output("out") silently inherits the data type

from the most recent m8r.input("in") call (C API behaviour). For non-float output (complex, int, short) call m8r.setformat(out, "complex") immediately after m8r.output and before any write. The rsf_write(name, arr) variant avoids this pitfall by writing a dummy pipe to force the correct type.

• No `sf_error` in Julia: there is no m8r.error(...) binding. Use error("msg")

(Julia built-in) or throw(...) for fatal errors; the non-zero exit will propagate correctly through Madagascar pipelines.

• Pipe composition: all installed sf* binaries are available as Julia functions

after using m8r. They accept an RSFFile, an array, or no argument, and return an RSFFile pointing to a temporary file. Chain them with |>.

• RSFROOT required: the module reads ENV["RSFROOT"] at load time. If the

environment variable is not set, m8r.RSFROOT is nothing and sf* function generation is skipped; the low-level read/write API still works.

Shared conventions

For file naming, self-documentation, parameter conventions, error handling, testing, and SCons build patterns that apply to all languages, see:

skills/authoring-sf-programs/