ahay/src/authoring-sf-programs-f90

When to use

Load this skill when writing a new sf<name> main program in Fortran 90. F90 is preferred when:

• The algorithm already exists as Fortran legacy or numerical code and a rewrite would be risky.
• The researcher team works primarily in Fortran and a C translation would lose maintainability.
• Dense array operations benefit from Fortran's natural multi-dimensional array semantics.

The source file naming convention is M<name>.f90, placed inside user/<youruser>/. The M prefix tells the SCons build system that this is a main program; the installed binary will be named sf<name>.

Dependency note: The F90 API requires a Fortran 90 compiler. gfortran is the reference compiler; pgf90 and ifort are also supported (see SConstruct logic). The Madagascar configure step must detect an F90 compiler and set API=f90; if detection fails the librsff90 library is not built and F90 programs cannot be compiled.

For language-agnostic conventions (self-documentation comments, parameter style, build integration, error handling, testing), read the shared skill first:

• skills/authoring-sf-programs/

Skeleton

Minimal F90 program structure, derived from api/f90/Testfile.f90:

! sf<name> — one-line description
!
! Usage: sf<name> < inp.rsf > out.rsf [param=value ...]
program Mname
  use rsf
 
  implicit none
  type(file)                       :: in, out
  integer                          :: n1, n2, i2
  real                             :: d1, o1
  real, dimension(:), allocatable  :: trace
 
  ! 1. Initialise RSF and parse command-line parameters
  call sf_init()
 
  ! 2. Open standard input / output files
  in  = rsf_input()          ! default tag "in"
  out = rsf_output("out")    ! default tag "out"
 
  ! 3. Read axis metadata from input history
  call from_par(in, "n1", n1)          ! fast axis length (required)
  call from_par(in, "d1", d1, 1.0)    ! sampling (optional, default 1)
  call from_par(in, "o1", o1, 0.0)    ! origin  (optional, default 0)
  call from_par(in, "n2", n2, 1)      ! slow axis (optional, default 1)
 
  ! 4. Read user parameter
  ! call from_par("key", val)  -- reads from command line; aborts if missing
  ! call from_par("key", val, default)  -- uses default if absent
 
  ! 5. Propagate / update output history
  call to_par(out, "n1", n1)
  call to_par(out, "n2", n2)
 
  ! 6. Allocate working array
  allocate(trace(n1))
 
  ! 7. Trace loop: read → process → write
  do i2 = 1, n2
     call rsf_read(in,  trace)
     ! ... process trace ...
     call rsf_write(out, trace)
  end do
 
end program Mname

Key structural points:

• use rsf is the only module import needed; it re-exports the entire public API.
• implicit none is mandatory — the module itself uses it, and omitting it in the main program will cause silent type bugs.
• rsf_input() / rsf_output() accept an optional tag argument (default "in" and "out" respectively) that corresponds to the pipe or file descriptor label used on the command line.
• from_par and to_par are generic interfaces; the compiler dispatches on the type of the value argument (integer, real, character, logical, arrays).
• Allocate arrays after reading axis dimensions, never before.

API cheat sheet

All entries are sourced from api/f90/rsf.f90 and api/f90/fortran.c. "Subroutine" means called with call; "function" means used in an expression or assignment.

Type constants declared in rsf.f90: sf_uchar=0, sf_char=1, sf_int=2, sf_float=3, sf_complex=4, sf_short=5.

Seek constants: sf_seek_set=0, sf_seek_cur=1, sf_seek_end=2.

Build integration

The F90 API library is built by api/f90/SConstruct:

1. It checks 'f90' in env.get('API',[]) and 'F90' in env — both must be true, which requires that configure detected a Fortran 90 compiler.
2. It compiles fortran.c (the C-to-Fortran glue) and rsf.f90 into librsff90.a.
3. It installs librsff90.a → lib/ and the compiled module file rsf.mod → include/.
4. Compiler-specific flags are set automatically:

• gfortran / gfc: adds -DGFORTRAN (selects _gfortran_iargc / _gfortran_getarg_i4 symbols in fortran.c).
• pgf90: extra include path only.
• ifort: adds -DINTEL_COMPILER.

For user F90 programs (user/<youruser>/M<name>.f90), follow the same pattern as for C/C++ programs but use the f90 target helpers described in the shared skill. The SCons infrastructure links against librsff90 automatically when it detects a .f90 source file with an M prefix. See the shared skill (skills/authoring-sf-programs/) for the SConstruct snippet and UserSconsTargets.f90 details.

Pointers

Files in api/f90/ (as of this writing):

Shared conventions

All conventions below are defined in the shared skill and apply unchanged to F90 programs:

• Self-documentation comment block at the top of the file (processed by doc/)
• Parameter naming and ordering rules
• Error message style (sf_error with lowercase message, no trailing period)
• Testing via sftour / SConstruct Test targets
• Build file location (user/<youruser>/SConstruct or top-level SConstruct)

See skills/authoring-sf-programs/ for the full reference.