Matlab File Format

Matlab files addressing one research topic should be collected in one folder which will be added under the CREWES folder in the Matlab toolbox. A requirements pertaining to all files is given first. All m-files should contain your name and a legal statement as outlined below. The exact location this text will take in a particular type of m file is described in the subsequent sections.

Copy the following statement verbatim where called for and update the first line.

Note that the empty line befor the BEGIN TERMS OF USE LICENSE header is intentional: the first part should follow your documentation with no intervening empty line, ensuring that it is printed by the Matlab help command together with your text, while the rest stays in the file.

% Y. Name, CREWES Project, U of Calgary, 20xx
% NOTE: It is illegal for you to use this software for a purpose other
% than non-profit education or research UNLESS you are employed by a CREWES
% Project sponsor. By using this software, you are agreeing to the terms
% detailed in this software's Matlab source file.

% This SOFTWARE is maintained by the CREWES Project at the Department
% of Geology and Geophysics of the University of Calgary, Calgary,
% Alberta, Canada.  The copyright and ownership is jointly held by
% its author (identified above) and the CREWES Project.  The CREWES
% project may be contacted via email at:
% The term 'SOFTWARE' refers to the Matlab source code, translations to
% any other computer language, or object code.
% Terms of use of this SOFTWARE
% 1) Use of this SOFTWARE by any for-profit commercial organization is
%    expressly forbidden unless said organization is a CREWES Project
%    Sponsor.
% 2) A CREWES Project sponsor may use this SOFTWARE under the terms of the
%    CREWES Project Sponsorship agreement.
% 3) A student or employee of a non-profit educational institution may
%    use this SOFTWARE subject to the following terms and conditions:
%    - this SOFTWARE is for teaching or research purposes only.
%    - this SOFTWARE may be distributed to other students or researchers
%      provided that these license terms are included.
%    - reselling the SOFTWARE, or including it or any portion of it, in any
%      software that will be resold is expressly forbidden.
%    - transferring the SOFTWARE in any form to a commercial firm or any
%      other for-profit organization is expressly forbidden.

Matlab Folders and the File Contents.m

Each package / folder should contain a file called Contents.m which contains nothing but Matlab-style comment lines describing very briefly what is in the folder. For instance, the command

    help finitediff
will show the contents of Contents.m in the finitediff folder which is part of the CREWES toolbox. The first one or two lines always give a short description on the whole package or toolbox. Here follows the example:
% CREWES finite difference seismic modelling
% Acoustic finite difference modelling toolbox
% Sample scripts
% HIGHV_WEDGE ... model an anticline beneath a high velocity wedge
% VZANTICLINE ... model an anticline beneath a v(z) medium
% CHANNEL ... model a channel beneath a few layers
% Seismograms
% AFD_SHOTREC ... makes finite difference shot records
% AFD_SHOTREC_ALT ... alternate version which inputs the wavelet
%               differently
% AFD_EXPLODE ... makes exploding reflector models
% Simple Models
% CHANNELMODEL ... build a model representing a channel in a stratigraphic seq.
% WEDGEMODEL ... build a simple 2D model of a high-vel. wedge over an anticline
% Utilities
% AFD_VMODEL ... makes simple polygonal velocity models
% AFD_SOURCE ... generates a source array for uses with AFD_SHOTREC
% CHANGE_GRID_SPACING ... example script to interpolate a velocity model
% AFD_REFLECT ... calculate the reflectivity from a velocity model
% AFD_MOVIE ... make movies of wavefield propagation
% Basic time-stepping
% AFD_SNAP ... take one finite difference time step
% AFD_SNAPN ... time steps a wavefield ``n'' steps
% AFD_SNAPN_ALT ... alternate version
% DEL2_5PT ... compute the 5 point Laplacian
% DEL2_9PT ... compute the 9 point Laplacian
% AFD_BC_OUTER ... apply absorbing boundary condition to outer boundary
% AFD_BC_INNER ... apply absorbing BCs to inner boundary

Matlab script files

A script is the topmost file in an automated Matlab run. It contains all input parameters, and calls a few functions which do the work, generally by calling a host of other functions. These files must be changed from case to case and start with a comment which states what the script does, and what the meaning and, perhaps, units of the input parameters are.

Follow your comments immediately with the above license. The blank line in the added text ensures that the help command will not print the whole license along with your explanations.

Matlab Functions

Functions start out wit a fairly rigid format. The first line defines the function in a statement formatted like

    function [OutParam1, op2] = FuncName (InParam1, InParam2, ..., InParamN)

Next comes the comment Matlab will print when the command

    help FuncName

is issued. This internal help section should contain a concise statement of what the function does, and a list of what the parameters are.

Leave a blank line, then follow these comments with the above license. The blank lie ensures that the help command will not print the license along with the explanation of the command and the parameter list.