ASTM E1472-92(1998)
(Guide)Standard Guide for Documenting Computer Software for Fire Models
Standard Guide for Documenting Computer Software for Fire Models
SCOPE
1.1 This guide provides information that should be in documentation for computer software prepared for scientific and engineering computations in fire models and other areas of fire protection engineering.
1.2 The guidelines are presented in terms of three types of documentation:(1) technical document; (2) user's manual; and (3) installation, maintenance, and programming manual.
1.3 This standard does not purport to address all of the safety problems, if any, associated with its use. It is the responsibility of the user of this standard to establish appropriate safety and health practices and determine the applicability of regulatory limitations prior to use.
General Information
Relations
Standards Content (Sample)
NOTICE: This standard has either been superceded and replaced by a new version or discontinued.
Contact ASTM International (www.astm.org) for the latest information.
Designation: E 1472 – 92 (Reapproved 1998) An American National Standard
Standard Guide for
Documenting Computer Software for Fire Models
This standard is issued under the fixed designation E 1472; the number immediately following the designation indicates the year of
original adoption or, in the case of revision, the year of last revision. A number in parentheses indicates the year of last reapproval. A
superscript epsilon (e) indicates an editorial change since the last revision or reapproval.
1. Scope 3. Terminology
1.1 This guide provides information that should be in 3.1 Definitions—Definitions used in this guide are in accor-
documentation for computer software prepared for scientific dance with Terminologies E 176 and E 1013, unless otherwise
and engineering computations in fire models and other areas of indicated. ANSI X3/TR-1 and ANSI/IEEE 729 include defini-
fire protection engineering. tions of some technical terms used in this guide.
1.2 The guidelines are presented in terms of three types of
4. Significance and Use
documentation: (1) technical document; (2) user’s manual; and
(3) installation, maintenance, and programming manual. 4.1 This guide provides recommendations for writers of
user’s manuals and other documents for computer software
1.3 This standard does not purport to address all of the
safety concerns, if any, associated with its use. It is the prepared for scientific and engineering computations in fire
models and other areas of fire protection engineering. The
responsibility of the user of this standard to establish appro-
priate safety and health practices and determine the applica- guide provides information that can be included in terms of
three types of documents.
bility of regulatory limitations prior to use.
4.2 This guide is intended to assist in the understanding,
2. Referenced Documents
usage, transfer, conversion, and modification of computer
2.1 ASTM Standards: software. If the options and instructions contained in this guide
E 176 Terminology Relating to Fire Standards are considered when documentation is prepared, the software
E 919 Specification for Software Documentation for a should be used more readily for its intended purposes.
Computerized System 4.3 The use of fire models currently extends beyond the fire
E 1013 Terminology Relating to Computerized Systems research laboratory and into the engineering, fire service, and
E 1355 Guide for Evaluating the Predictive Capability of legal communities. Sufficient documentation of computer soft-
Fire Models ware for fire models is necessary to ensure that users can judge
2.2 ANSI Standards: the adequacy of the scientific and technical basis for the
ANSI X3/TR-1 American National Dictionary for Informa- models, select the appropriate computer operating environ-
tion Processing ment, and use the software effectively within the specified
ANSI/X3.88 American National Standard for Computer limitations. Adequate documentation will help prevent the
Program Abstracts unintentional misuse of fire models.
ANSI/ANS 10.2 Recommended Programming Practices to 4.4 Specification E 919 is a standard specification for the
Facilitate the Portability of Scientific and Engineering documentation of computer software. It can be used to specify
Computer Programs the minimum computer program documentation that shall be
ANSI/ANS 10.3 Guidelines for the Documentation of Digi- provided by the supplier of software to the purchaser.
tal Computer Programs 4.5 Additional guidelines on documentation can be found in
ANSI/ANS 10.5 Guidelines for Considering User Needs in ANSI/ANS 10.3 and ANSI/IEEE 1063.
Computer Program Development 4.6 ANSI/ANS 10.2 and 10.5 provide guidelines for pro-
ANSI/IEEE 729 IEEE Standard Glossary of Software En- gramming to ease the portability of the software and meet user
gineering Terminology needs.
ANSI/IEEE 1063 Software User Documentation
5. Types of Documents
5.1 General:
This guide is under the jurisdiction of ASTM Committee E-5 on Fire Standards
5.1.1 There are many levels of desirable documentation,
and is the direct responsibility of Subcommittee E05.33 on Fire Safety Engineering.
ranging from that needed by the user who wants only to run the
Current edition approved May 20, 1992. Published June 1992.
programs, to documentation needed by the user who intends to
Annual Book of ASTM Standards, Vol 04.07.
Annual Book of ASTM Standards, Vol 14.01. make extensive modifications or additions to the programs.
Available from American National Standards Institute, 11 West 42nd Street,
5.1.2 This guide provides suggestions for items to include in
13th Floor, New York, NY 10036.
Copyright © ASTM, 100 Barr Harbor Drive, West Conshohocken, PA 19428-2959, United States.
NOTICE: This standard has either been superceded and replaced by a new version or discontinued.
Contact ASTM International (www.astm.org) for the latest information.
E 1472
three types of documents: (1) technical document; (2) user’s lines on the contents of computer program abstracts.
manual; and (3) installation, maintenance, and programming
7. Contents of the Technical Document
manual. The items suggested for these manuals can be com-
7.1 Problem or Function:
bined into a single document.
5.1.3 The documents should be written and organized to 7.1.1 Define the fire problem modeled or function per-
formed by the program, for example, calculation of fire growth,
reflect the expected sophistication of the user.
5.2 Technical Document—This type of document is in- smoke spread, people movement, etc.
7.1.2 Describe the total fire problem environment. General
tended for use by the individual interested in an in-depth
block or flow diagrams may be included here.
explanation of the scientific basis for the model. Articles in
7.1.3 Include any desirable background information, such as
scientific or engineering journals are examples of this type of
feasibility studies or justification statements.
document.
7.2 Technical Description:
5.3 User’s Manual—This self-contained manual is directed
7.2.1 Convey a thorough understanding of the theoretical
to the prospective user of the fire model. With this type of
and mathematical foundations, referencing the open literature
manual, the user of the model should be able to understand the
where appropriate.
model application and methodology, reproduce the computer
7.2.2 Theoretical Foundation:
operating environment and the results of sample problems
7.2.2.1 Describe the theoretical basis of the phenomenon
included in the manual, modify data inputs, and run the
and the physical laws on which the model is based.
program for specified ranges of parameters and extreme cases.
7.2.2.2 Present the governing equations and the mathemati-
The manual should be concise enough to serve as a reference
document for the preparation of input data and the interpreta- cal model employed.
7.2.2.3 Identify the major assumptions on which the fire
tion of results.
5.4 Installation, Maintenance, and Programming Manual— model is based and any simplifying assumptions.
7.2.3 Mathematical Foundation:
This type manual is for the individual responsible for imple-
menting the program on a computer, modifying or extending it 7.2.3.1 Describe the mathematical techniques, procedures,
and computational algorithms employed to obtain numerical
to meet local needs, converting it to a different computer
environment, or revising it to reflect technological progress. solutions.
7.2.3.2 Provide references to the algorithms and numerical
This type of manual is recommended if the source code is to be
techniques.
made available.
7.2.3.3 Present the mathematical equations in conventional
6. Items Common to All Documents
terminology and show how they are implemented in the code.
6.1 Program Identification:
7.2.3.4 Discuss the precision of the results obtained by
6.1.1 Provide the name of the program or model, a descrip- important algorithms and any known dependence on the
tive title, and any information necessary to define the version
particular computer facility.
uniquely.
7.2.3.5 For iterative solutions, discuss the use and interpre-
6.1.2 Identify any acronyms or short titles for name of the
tation of convergence tests, and recommend a range of values
model.
for convergence criteria. For probabilistic solutions, discuss the
6.1.3 Note any legal restrictions on use and reproduction.
precision of the results having a statistical variance.
6.1.4 Describe any relationships to other models.
7.2.3.6 Identify the limitations of the model based on the
6.2 Changes in the Program:
algorithms and numerical techniques.
6.2.1 Provide the name, full identification, and version of
7.3 Program Description:
the program to be changed.
7.3.1 Describe the program.
6.2.2 Identify the equivalent version of the program, with
7.3.2 List any auxiliary programs or external data files
the changes made.
required for utilization of this program.
6.2.3 Identify the section(s) changed, and provide the rea-
7.4 Data Libraries—Provide background information on
son(s) for the changes.
the source, contents, and use of data libraries.
6.3 Authors and Responsibility for Assistance:
7.5 Validation—Provide the results of efforts to evaluate the
6.3.1 Provide instructions for obtaining more detailed infor-
predictive capabilities of the model for a specific use, employ-
mation, or include the position, title, name, telephone number,
ing the methodologies outlines in the Guide E 1355.
and mailing address of the individual responsible for providing
8. Contents of the User’s Manual
assistance.
6.3.2 Describe the history of the model’s development and 8.1 Technical Document—Include or summarize the techni-
the names and addresses of the individual(s) and organiza- cal document (Section 7).
tion(s) responsible. 8.2 Program Description:
6.3.3 Identify current location(s) of the model. 8.2.1 Include a comprehensive self-contained description of
6.4 Available Material—List the contents and costs of any the program.
program package and the procedure for obtaining this material. 8.2.2 Define the basic processing tasks performed, and
6.5 Computer Software Abstract—Summarize the capabili- describe the methods and procedures employed. A schematic
ties of the program and the minimum hardware requirements display of the flow of the calculations is useful.
for implementation. ANSI/X3.88 provides additional guide- 8.2.3 On-line information (prompts and helps, etc.) can
NOTICE: This standard has either been superceded and replaced by a new version or discontinued.
Contact ASTM International (www.astm.org) for the latest information.
E 1472
supplement a printed user manual. quired to execute the program.
8.3 Operating and Installation Information: 8.7.1.2 Include a complete set of the program’s prompts,
8.3.1 Provide instructions for installing the program in the with the ranges of appropriate responses.
target system. If appropriate, include examples of typical 8.7.2 Describe how the inputs interact with data files.
dialogue with the system and test data. 8.7.3 Describe how to interrupt the program.
8.3.2 Identify the computer(s) on which the program has 8.7.3.1 For each stage in the program (input, execution, and
been executed successfully and any required peripherals, output), describe how to perform the following functions:
including memory requirements and tapes. (1) Temporarily halt the program, then resume; and
8.3.3 Identify the programming languages and versions in (2) Halt and exit from the program.
use. 8.7.3.2 Describe the status of files and data after the
8.3.4 Identify the software operating system and versions in interruption.
use, including library routines. 8.8 Output Information:
8.4 Program Considerations: 8.8.1 Describe the program output.
8.4.1 Describe the function of each major option available 8.8.2 Relate the edited output to input options.
for solving various problems, pay special attention to the 8.8.3 Relate the output to appropriate equations.
effects of combinations of options. 8.8.4 Describe any normalization of results and list associ-
8.4.2 Describe alternate paths that may be dynamically
ated dimensional units.
selected by the program from tests on calculated results. 8.8.5 Identify any special forms of output, for example,
8.4.3 Describe the relationship between input and output graphics display and plots.
items for programs that reformat information.
8.9 Personnel and Program Requirements:
8.4.4 Describe the method and technical basis for decisions 8.9.1 State the typical personnel time and set-up time to
in programs that perform logical operations.
perform a typical run.
8.4.5 Describe the basis for the operations that occur in the
8.9.2 Identify the types of skills required to execute typical
program. runs.
8.5 Input Data:
8.9.3 Provide information to enable a user to estimate the
8.5.1 General Considerations: computer execution time on applicable computer systems for a
8.5.1.1 Describe the source of input information, for ex- typical application.
ample, handbooks, journals, research reports, standard tests,
8.10 Sample Problems:
experiments, etc. 8.10.1 Provide sample data files with associated outputs, to
8.5.1.2 Describe special input techniques and requirements, allow the user to verify the correct operation of the program.
for example, format, blank field treatment, order of items, and
8.10.2 Describe the physical problem and associated data
field delineation. files.
8.5.1.3 Describe the handling of consecutive cases. Give the
8.10.3 Consider the following factors in selecting sample
conditions of data retention or reinitialization for the next case. problems:
8.5.1.4 Provide the default values or the general conven- (1) Choose a benchmark problem or a well-defined ex-
tions governing those values.
ample;
8.5.1.5 Identify the limits on input based on stability, (2) Exercise a large portion of the available programmed
accuracy, and practicality, as well as their resulting limitations
options; and
to output.
(3) Use only a reasonable amount of computer time.
8.5.1.6 When property values are defined within the pro- 8.10.4 Include the following information in presenting the
gram, list the properties and the assigned values.
edited output:
8.5.2 Specific Considerations for Each Input Variable:
(1) The results of key items in concise forms;
8.5.2.1 Provide the name of the variable. (2) The precision of the results; and
8.5.2.2 Give a description or definition.
(3) The output parameters, especially the relevance of the
8.5.2.3 Give the dimensional units.
order of magnitude of the output.
8.5.2.4 Give the default value, if appropriate. 8.10.5 Provide an order of magnitude of computer execu-
8.5.2.5 Give the source, if not widely available. tio
...
Questions, Comments and Discussion
Ask us and Technical Secretary will try to provide an answer. You can facilitate discussion about the standard in here.