Module Standards

Version Date: Feb. 26, 1999

The tables below list ``Standards" and ``Goals". The ``Standards'' described below will be enforced for the modules submitted to the library; whereas, ``Goals'' are strongly encouraged and may become future standards for the module library.

Standard: Provide source code for each physics module or code.

Standard: Provide test case(s) with driver program(s) with input and output data and their documentation.

Standard: Provide script to compile and link (e.g., makefile). The script should make at least some provision for portability to multiple brands of Unix (at minimum). Provide clear documentation (possibly in the README file) on how to use the script or makefile.

Standard: Provide a README file giving (a) the name of the module and its authors, (b) the location and form of general module documentation, and (c) information (or pointer to more detailed documentation) enabling a user to build binaries from the source code.

Standard: Provide documentation about how the module should be used, for example, whether the module needs to be initialized or used sequentially. Important usability issues, such as the existence of state information in COMMON or other static memory, which persists between calls, must be described.

Standard: Eliminate graphics calls embedded in physics modules.

Standard: The source code files (e.g., *.f, *.c or *.cpp files) should be submitted rather than requiring extraction from another file.

Standard: Authors may upgrade their modules with approval of the current chairperson of the NTCC modules committee. If the upgrade is extensive, the chairperson can require that the upgrade be subject to a full review.

Goal: Portability (code should run on multiple platforms and under different operating systems).

Goal: Offer single and double precision versions or offer user control of precision at compile time.

Goal: Multi-platform (code should run on different computers).

Goal: Provide error checking (but not stops).

Goal: Minimize external dependencies that cost money (i.e., avoid using expensive proprietary licenses).

Standard: Supply warnings in the documentation when the above goal has not been met.

Goal: Arrays should be dynamically allocated.

Standard: The characteristics of the I/O should be clearly documented (i.e., the implementation I/O unit numbers, if any).

Goal: Avoid using hard-wired I/O unit numbers. Allow informational output to be switched on or off. Provide a method for rerouting warning or error message output to a user specified file or I/O unit number. Standard:

Standard: Provide Name of contact person for support.

Standard: Provide Date of last revision.

Standard: Provide at least comments describing module or code, citations to publications (if any), and range of validity.

Standard: Specify the precision of floating point calculations.

Standard: Provide index of input-output variables for each module (include type of variable, dimensions, units).

Standard: List dependencies -- names of external routines called.

Standard: Provide statement of known bugs.

Goal: Index of modules, routines, variables.

Goal: Publication of code or module in journal (such as Computer Physics Communications).

Goal: Online hyper-text reference documentation.

Goal: Interactive online help menus. Standard:

Goal: Provide interface routines to data.

Goal: Use self-describing data files (such as NetCDF).

Goal: Use public domain, portable, available and well-documented data file formats.

Goal: Establish standards for variable names, units, dimensions, independent variables and grid descriptions as they appear in the module interfaces. Standard:

Standard: Users of NTCC codes and modules must acknowledge the author(s) and any modifications made when publishing or presenting results.

Standard: Users who find bugs in NTCC codes or modules must report back to the contact person first.

Standard: Users who make improvements to a module's source code, makefile, or documentation, will submit these improvements to the module's author or support person, who may choose to incorporate these improvements in a future release of the module.

 
• About this document ...