Policy for the documentation of non-U.S. Geological Survey computer programs used for analysis in ground-water projects



In Reply Refer To:                                August 14, 1991
Mail Stop 411



OFFICE OF GROUND WATER TECHNICAL MEMORANDUM NO. 91.04

SUBJECT:  Policy for the documentation of non-U.S. Geological
          Survey computer programs used for analysis in ground-
          water projects

The purpose of this memorandum is to define policy for the
documentation of computer programs that will be used or cited in
ground-water project reports that receive Director's approval.
The long-standing policy of the U.S. Geological Survey (USGS) is
that a program written by USGS employees to perform other than
routine tasks must be documented (either in a separately
approved report or in a report that makes use of the program)
before it can be cited or used in a USGS report (see Office of
Ground Water Technical Memorandum No. 79.04).  However, no clear
policy has been defined for required documentation of programs
written by outside sources.  The proliferation of programs from
non-USGS sources makes it important that guidelines be
established for use of these programs in USGS investigations.

The two classifications for computer programs written outside of
USGS are:  (1) public domain and (2) proprietary.  Public-domain
programs are not copyrighted.  Common sources of public-domain
programs are universities and other government agencies.
Proprietary programs are developed by businesses or
organizations in order to sell them to customers and are
copyrighted.

Public-domain programs are held to the same requirements as in-
house programs.  The policy for use of a public-domain computer
programs is:

1. The program must be documented in a published report.

2. The documentation must describe both the theoretical basis
for the calculations performed by the program and the
implementation of the theory.  This documentation should show
that the program functions as described, and if not shown,
independent checks must be undertaken by the user.  The results
of any testing should be placed in the project files and made
available to reviewers of project reports.

3. The source code for the program must be included in the
documentation or be available from a formal distribution center.
Proprietary computer programs cause policy difficulties due to
the secrecy that vendors require in order to protect their
products.  Complete documentation as described above is
generally not provided for proprietary programs; in particular,
the source code is usually not available.

The broad purpose of the requirements for documentation of in-
house programs is to ensure a high probability that the programs
function correctly, ensure that the theoretical basis is
explained and defensible, allow others to learn from our work,
and allow others to reproduce and evaluate our work.  In order
to attain the same purpose without requiring disclosure of
source code, the following policy has been adopted for the use
of proprietary computer programs in USGS reports.

1. The proprietary program must be available for purchase by
anyone.

2. The vendor must provide documentation with the program that
describes how to use the program and the theoretical basis for
calculations.  If the standard documentation provided by the
vendor does not contain an adequate description of the
theoretical basis, then the user must contact the vendor to
obtain the theoretical basis and must reference or describe this
theory in the reports that use the program.

3. The user of a proprietary program must make tests by
comparing results from the program to known solutions to show
that the program functions as claimed by the vendor and as used
in their project work.  Users should retest new versions of a
program to make sure errors have not been introduced.  The
results of the testing should be placed in the project files and
made available to reviewers of project reports.

This policy is intended to insure the reliability and
reproducibility of our work.

Any question regarding this policy and the applicability to
specific software should be clarified in the early stages of a
project by contacting the Office of Ground Water.



                              Thomas E. Reilly
                              Acting Chief, Office
                              Ground Water

Distribution:  A, B, S, FO, PO

cc:  OGW File/Chron--MS 411

WGS:WRD:AWHarbaugh:ves:7/22/91
Dir:  vestockd/harbaugh/10.doc
File Code:  Tech MM. 91