GEOPHYSICS Software and Algorithms
submission / review Q+A

All papers in the journal GEOPHYSICS must meet certain criteria to be acceptable. The criteria for software and algorithms (S+A) papers are somewhat unique. If you are reviewing or submitting an S+A paper, please read the following.

GEOPHYSICS contributions must be ``novel''. What does that mean for an S+A paper?

GEOPHYSICS papers must represent ``novel contributions''. In the case of S+A papers, that does not mean that the algorithm itself must be newly invented. If the combination of the algorithm description and source code is novel, or the application of the algorithm to a geophysical problem is novel, that is sufficient.

What can an S+A paper be about?

The focus of a software and algorithms paper should be on the algorithm. It is not necessary (and often not advisable) to attempt to also include a case study or extensive mathematical derivations, except for those that pertain to the derivation and explanation of the algorithm. If you have such a paper, consider breaking it into two: one paper for the science, and one paper for the algorithm.

What should a software and algorithms paper look like?

An ideal contribution might look something like a chapter section from Numerical Recipes: an explanatory text describing the problem being solved and presenting an algorithm to solve it, coupled with well documented source code demonstrating a working implementation of the algorithm. Refer to the sample paper in the Sept-Oct 2005 GEOPHYSICS.

Is code required?

Yes! Source code must be submitted along with the paper. The submission must also include sufficient supporting files to allow computer-literate readers to run the code, along with test input and output that can be used to verify the code's correct operation. If possible, the test dataset should be the exact same dataset that is used to make a figure in the paper. The easiest way to achieve this requirement is to include a documented script that reproduces a result in the paper when run.

What types of code are acceptable?

The source code must be readable and reviewable, and consist of plain ASCII text with English comments. There will be no other formal restrictions on the type of source code. The software may be standalone, or may be a module that fits into a widely available software environment. The definition of ``widely available'' is simply ``can the associate editor find reviewers able to run it''.

What is ``readable and reviewable'' source code?

Reviewers must be able to understand the code and successfully run and test it, ideally reproducing an example from the paper. The authors should include all necessary supporting files to allow the reviewers (and readers) to accomplish this. Authors should try to make the job of reviewing the code as straightforward as possible. Generally authors should provide a README that lists and describes the various files included in the distribution and what they are for. Included among those files should be documented scripts to compile the code (if applicable), and to run the code on a test example.

Submitted software should be of sufficient quality that someone 25 years hence may still find perusing the descriptive text and the accompanying source code useful, despite the changes in language and coding practice that are certain to have accumulated over such an interval. Refer to Reginald Beardsley's Oct 2005 TLE article for suggestions on how to properly document source code. You might also consider using agile programming methods, so that your code structure is itself documentation.

Each routine should contain a comment block at the beginning briefly describing its function and usage. This should generally include an enumeration of the purpose of all passed variables, and whether they are for input, output, or both. Also include a description of the routine's return values and exit codes, if any. Variables stored in memory that is shared between multiple source files are strongly discouraged: ideally, each subroutine should be an independently reusable programming unit.

The source code and accompanying paper are a joint submission, and should both be written in such a way that it is clear how the code and algorithm description in the paper go together. For example, comments in the source code could refer to corresponding equations in the accompanying paper text, or the paper text could refer to named subroutines within the source code.

Remember, the source code and its accompanying documentation are just as important as the paper text! Read your documentation and the comments in your source code. Ask yourself: are those up to the same writing quality as your paper? If not, then you need to fix that before submitting. If you needed help with your English in writing and proofreading your paper, then you almost certainly also need help with your English in writing and proofreading your code documentation and source-code comments.

Supporting data files should either be plain ASCII, or conform to widely recognized binary standards such as SEG-Y or an N-dimensional cube of IEEE floats. Generally proprietary or architecture-specific binary data formats will not be acceptable, unless you can also include an ASCII or IEEE version of that data. In that case you will also need to provide an open-source program to convert that version to the proprietary format. It is also acceptable to provide a script that relies on standard conversion programs (i.e., ones that are well known parts of the same software environment that your contribution already relies on).

Will the source code appear in print?

Generally not. However, the source code may be included in the publication in whole or in part in some cases, at the editor's discretion. In any case, upon publication the complete source code will be archived and available for download as a computer file on software.seg.org.

Can the code or algorithm be copyrighted or patented?

The SEG will request transfer of copyright for the source code, but will explicitly allow the author to retain redistribution rights, just as it currently does for traditional publications. If the author does not have the right to transfer copyright, the SEG will require at a minimum the right to freely redistribute the code, and to include it in future SEG publications and software distributions.

Obviously, the computer files cannot contain any material with copyrights or security restrictions that might prevent its widespread distribution. (For example, subroutines from ``Numerical Recipes'' are copyrighted, and cannot be included in freely distributed source code.) If any part of the algorithm implemented by the code is patented, that fact must clearly be documented both in the paper text and in the source code comments, along with the algorithm's terms of use. If the terms are excessively limiting, that may constitute grounds for rejection.

How do I submit?

Technical articles should be submitted to GEOPHYSICS in the usual way. Once on the GEOPHYSICS manuscript central web site, choose the ``Software and Algorithms'' category. In addition to uploading the usual paper text, supplementary computer files must also accompany the submission. These should be uploaded as ``files for review'', just like the paper's text. Preferably, the source code, makefiles, test scripts, sample input and output, etc, should be packaged using a standard archive format (Unix tarball or Windows zip) before upload. Authors should include a short description of the purpose of the source code that the editor can use when soliciting code reviewers.

Please don't use ``rar'' as an archive format as many reviewers don't have the necessary software to unpack it. The Manuscript Central web site may refuse to upload a zip file in a misguided attempt to avoid a ``virus threat''. Just change the file suffix to something else like ``zpp'', and include a note saying that's what you did so the reviewers know how to unpack the file.

Any pitfalls to watch out for?

Here I am collecting comments / advice pertaining to particular software packages.



An example subroutine-interface documentation block at the start of a subroutine:

/*
 * function ti_distance:
 * Find the nearest VTI medium to an elastic stiffness matrix.
 *
 * Input:
 *      cc1 is an input 6x6 elastic stiffness matrix in Voigt notation.
 *
 * Output:
 *      cc2 is then the nearest VTI matrix (transversely isotropic with a
 *      Z axis of symmetry) to cc1.
 *
 * Return value: the distance between the VTI matrix cc2 and
 *      the input matrix cc1.
 *
 * Author Joe Dellinger, Amoco TTC, 19 Feb 1997.
 */
float ti_distance (float *cc2, float *cc1)


An example copyright and modification-history header (to go at the top of each source file upon acceptance):

/*
 * Copyright (c) 2005 by the Society of Exploration Geophysicists.
 * For more information, go to http://software.seg.org/2005/0001 .
 * You must read and accept usage terms at:
 * http://software.seg.org/disclaimer.txt before use.
 *
 * Revision history:
 * Original SEG version by Joe Dellinger, BP EPTG, July 2005.
 */


Reginald Beardsley's Oct 2005 TLE article on comments:

A Few Comments on Comments and Other Matters of Style

Reginald H. Beardsley
Exploration Software Consultants Inc.

There is a common failure among both novice and experienced programmers to recognize the importance of the human reader when writing software. The following guidelines are based upon the professional experience of 15 years reading over 2 million lines of other people's software in a variety of languages. Their brevity is a consequence of the desire to avoid language-specific issues.

The human reader is more important than the machine. Give him or her the respect they deserve. The machine is a simple slave.

Comments are strategy. The executable statements are tactics. Tactics may win battles, but strategy wins the campaign.

Comments should not attempt to displace formal presentation but rather should reference it with equation numbers as appropriate.

In a well written program the comments are sufficient to allow a knowledgable person to recreate the program in any language. The executable statements are merely a convenience.

Presentation matters. Comments should be easily distinguished from executable statements. This allows the reader to focus on whichever is of most concern without distraction.

Use indentation to make the logical structure of the algorithm apparent from the layout of the executable statements. Loops and conditionals should be obvious without close inspection.

Follow the relevant language standard. Don't depend only on successful results. It is very embarrassing to publish an incorrect method whose success was accidental.

Variable names matter. If poorly chosen they are hard to remember. If too long the equations are hard to read. A good middle ground is to use the initial letters of a short descriptive phrase supplied as a comment to the declaration.

Any language feature that merely saves typing is an abomination that in the end will confuse both reader and writer alike.

Do not underestimate how obscure even a two-page program can become a few months later. The most impeccable programming style without proper description of strategy and motive will soon become a source of great frustration.



This URL has been set up for use by an outside organization.

If you have questions, please contact the SEG Web Group, and the page maintainer, Joe Dellinger.

Return to the GEOPHYSICS source-code archive home page.