1、Designation: D6171 97 (Reapproved 2010)Standard Guide forDocumenting a Ground-Water Modeling Code1This standard is issued under the fixed designation D6171; the number immediately following the designation indicates the year oforiginal adoption or, in the case of revision, the year of last revision.
2、 A number in parentheses indicates the year of last reapproval. Asuperscript epsilon () indicates an editorial change since the last revision or reapproval.1. Scope1.1 This guide covers suggested components of the docu-mentation of a ground-water modeling code. Documentation ofa ground-water modelin
3、g code consists of textual and graphicalinformation recorded during its design, development, andmaintenance regarding its capabilities, development history,theoretical foundation, operation, and verification. It is theprincipal instrument for those involved in its development anduse, such as code de
4、velopment and maintenance staff, networkmanagers, code users, and project managers, to communicateregarding all aspects of the software.1.2 This guide presents the major steps in preparing thedocumentation of a ground-water modeling code. It discussesthe various documentation audiences and addresses
5、 the role ofprinted documentation versus documentation in electronicform.1.3 This guide is one of a series of guides on ground-watermodeling codes and their applications, such as Guides D5447,D5490, D5609, D5610, D5611, and D5718.1.4 This guide is not intended to be all inclusive. If offers aseries
6、of options and considerations, but does not specify acourse of action. Documenting certain codes may requiresupplemental information or replacement of documentationsections by more appropriate elements. This guide should notbe used as a sole criterion or basis of comparison, and does notreplace or r
7、elieve professional judgement in preparing orevaluating documentation of ground-water modeling software.1.5 This standard does not purport to address all of thesafety concerns, if any, associated with its use. It is theresponsibility of the user of this standard to establish appro-priate safety and
8、health practices and determine the applica-bility of regulatory limitations prior to its use.1.6 This guide offers an organized collection of informationor a series of options and does not recommend a specificcourse of action. This guide cannot replace education orexperience and should be used in co
9、njunction with professionaljudgment. Not all aspects of this guide may be applicable in allcircumstances. This guide is not intended to represent orreplace the standard of care by which the adequacy of a givenprofessional service must be judged, nor should this guide beapplied without consideration
10、of a projects many uniqueaspects. The word “Standard” in the title of this documentmeans only that the document has been approved through theASTM consensus process.2. Referenced Documents2.1 ASTM Standards:2D653 Terminology Relating to Soil, Rock, and ContainedFluidsD5447 Guide for Application of a
11、Ground-Water FlowModel to a Site-Specific ProblemD5490 Guide for Comparing Ground-Water Flow ModelSimulations to Site-Specific InformationD5609 Guide for Defining Boundary Conditions in Ground-Water Flow ModelingD5610 Guide for Defining Initial Conditions in Ground-Water Flow ModelingD5611 Guide for
12、 Conducting a Sensitivity Analysis for aGround-Water Flow Model ApplicationD5718 Guide for Documenting a Ground-Water FlowModel Application3. Terminology3.1 Definitions of Terms Specific to This Standard:3.1.1 computer code (computer program)the assembly ofnumerical techniques, bookkeeping, and cont
13、rol language thatrepresents the model from acceptance of input data andinstructions to delivery of output.3.1.2 functionalityof a ground-water modeling code, theset of functions and features the code offers the user in terms ofmodel framework geometry, simulated processes, boundaryconditions, and an
14、alytical and operational capabilities.3.1.3 ground-water modeling codethe non-parameterizedcomputer code used in ground-water modeling to represent a1This guide is under the jurisdiction ofASTM Committee D18 on Soil and Rockand is the direct responsibility of Subcommittee D18.21 on Ground Water andV
15、adose Zone Investigations.Current edition approved July 1, 2010. Published September 2010. Originallyapproved in 1997. Last previous edition approved in 2004 as D617197(2004).DOI: 10.1520/D6171-97R10.2For referenced ASTM standards, visit the ASTM website, www.astm.org, orcontact ASTM Customer Servic
16、e at serviceastm.org. For Annual Book of ASTMStandards volume information, refer to the standards Document Summary page onthe ASTM website.1Copyright ASTM International, 100 Barr Harbor Drive, PO Box C700, West Conshohocken, PA 19428-2959, United States.non-unique, simplified mathematical descriptio
17、n of the physi-cal framework, geometry, active processes, and boundaryconditions present in a reference subsurface hydrologic system.3.2 For definitions of other terms used in this guide, seeTerminology D653.4. Significance and Use4.1 Ground-water modeling has become an important meth-odology in sup
18、port of the planning and decision-makingprocesses involved in ground-water management. Ground-water models provide an analytical framework for obtaining anunderstanding of the mechanisms and controls of ground-watersystems and the processes that influence their quality, espe-cially those caused by h
19、uman intervention in such systems.Increasingly, models are an integral part of water resourcesassessment, protection, and restoration studies and provideessential and cost-effective support for planning and screeningof alternative policies, regulations, and engineering designsaffecting ground-water
20、(1).34.2 Successful ground-water management requires that de-cisions be based on the use of technically and scientificallysound methods for data collection, information processing, andinterpretation, and that these methods are properly integrated.As computer codes are essential building blocks of mo
21、deling-based management, it is crucial that before such codes are usedas planning and decision-making tools, their performancecharacteristics are established and their theoretical foundation,capabilities, and use documented.4.3 Good code documentation ensures scientific rigor andimplementational qua
22、lity in the development of a code (2).Complete and well-written documentation shortens the learn-ing curve for new users, provides answers to questions fromproject managers, and supports efficient code selection. Well-structured and indexed documentation provides rapid answersfor initiated users. Th
23、is guide is intended to encourage com-prehensive and consistent documentation of a ground-watermodeling code.4.4 Earlier surveys of computer models and assessment ofspecific models indicate that the documents that are supposedto describe and explain these models and their use are lackingin detail, i
24、nconsistent in their contents, incomplete with respectto user instructions, inefficient with respect to indexing andstructure, and often difficult to obtain (3). This still applies tothe documentation of many of the ground-water modelingprograms recently released or frequently used (4).5. Code Devel
25、opment Process in Ground-Water Modeling5.1 In ground-water modeling, code development consistsof the following: definition of design criteria and determiningapplicable software standards and practices; the developmentof algorithms and program structure; computer programming;preparation of documentat
26、ion; code testing; and independentreview of scientific principles, mathematical framework, soft-ware, and documentation (1, 4).5.2 The development of a specific ground-water modelingcode may be part of a research or development project, basedon an existing mathematical model, or derived from an exis
27、tingset of modeling codes.5.3 Code testing is an integral part of code development.During the programming phase, testing is focused on indi-vidual algorithms, subroutines, functions, and other programelements.At the end of the initial programming phase, the codeis extensively tested.5.4 The preparat
28、ion of the program documentation starts atthe beginning of the code development process and is integralto all stages of code development. Specifically, documentationof theoretical foundation, code design, capabilities and pro-gram structure are best prepared and evaluated during thedesign and progra
29、mming phases of the project. Documentationregarding the operation and performance of the code are bestprepared before and during initial testing by code developers.5.5 The final step in code development is independentreview and testing.6. Code Documentation Requirements6.1 Following are the main pur
30、poses of software documen-tation (3): to record technical information that enables systemand program changes to be made quickly and effectively; toassist the (potential) users in understanding what the programis about and what it can do, so that they can determine whetherit serves their needs; to en
31、able code users to effectively applythe program to their project(s); to facilitate auditing andverification of program operations, that is, code evaluation; toenable programmers and system analysts, other than softwareoriginators, to work on the programs; to provide softwaredevelopment managers with
32、 information to review at signifi-cant developmental milestones so that they may determine thatproject requirements have been met and that resources shouldcontinue to be expended; to reduce the disruptive effects ofpersonnel turnover during development and use of the soft-ware; and to facilitate und
33、erstanding among developers, usersand project managers by providing information about mainte-nance (that is, required software modifications), training, andoperation of the software.6.2 Documentation of a ground-water modeling code maybe comprised of several elements such as internal or publishedrep
34、orts, published articles, textbooks, electronic texts, andsoftware help systems. If a programs documentation consistsof more than one such element, it is recommended to includea section referencing all elements that constitutes the codesdocumentation.6.3 Documentation of a ground-water modeling code
35、 shouldbe informative, well-structured (that is, specific topics are easyto find), and well-written (that is, topics are easy to under-stand).6.4 Documentation of a ground-water modeling code shouldinclude sections on the following (5): development purpose;theoretical framework; mathematical/logic m
36、ethods and com-puter algorithms employed; model construction and site-specific data required to control the code; analysis of thesensitivity of computed variables for variations in modelparameters; verification conducted and operational evaluationsperformed; example applications and demonstration te
37、st cases;3The boldface number given in parentheses refer to a list of references at the endof the text.D6171 97 (2010)2installation, input preparation, and code execution instructions;and methods to review input data and results. A summary ofcode capabilities (that is, an overview of the codes funct
38、ion-ality), a description of the development history, a trouble-shooting guide, and a detailed index are also useful elements ofcode documentation.6.5 Comprehensive software documentation typically con-sists of four types of manuals providing information aimed atproject managers, software users, (pr
39、oblem) analysts, andprogrammers, respectively (6). In ground-water modeling,such information is often included in a single document,containing specific sections for the different audiences; fre-quently, the program user is the same as the problem analyst(that is, the hydrogeologist).6.5.1 Project ma
40、nagers find important information in asummary section containing a general description, a discussionof code development history, a testing report, and a discussionof current and future applications.6.5.2 The users instructions section, sometimes publishedas a separate users manual, contains a compre
41、hensive descrip-tion of code functions and capabilities, code input data require-ments and format, types of output and output controls, codeexecution details, sample runs, and a trouble-shooting guide,and code verification and performance evaluation information.6.5.3 An effective users manual enable
42、s the (non-programmer) user to perform the following (2, 3): thoroughlyunderstand the inner workings of the code; accurately formu-late a problem in terms of code input required; prepare the datafor code input (data requirements, data preparation, descriptionof input formats, array dimensions, and p
43、roblem size limita-tions); run the code to obtain desired output (for example,discussion of execution and output control parameters, selec-tion of data units and corresponding file requirements, listingof computer requirements and installation instructions, discus-sion of numerical precision of the
44、code and accuracy ofresults), and provide information for interpretation of output.Such a users manual includes a complete set of operatinginstructions, as well as instructions with respect to modelconstruction.6.5.3.1 General DescriptionA comprehensive descriptionof what the model is supposed to do
45、 (typically called “codefunctions and capabilities” or “code functionality”), why it hasbeen developed, what its intended use is, and the generalmagnitude of its applicability in terms of major assumptionsand limitations. This section is also the appropriate place todescribe the relationship to othe
46、r software required for itspreparation, operation, or output analysis.6.5.3.2 Theoretical Foundation/MethodologyA detaileddescription of how the model accomplishes its intended pur-pose. These details are preferably provided in the sequence inwhich they are performed in the code. It includes the the
47、oreti-cal model and the underlying assumptions, as well as themathematical representation (that is, the mathematical model).The mathematical description should include the simplifica-tions made to the theoretical model, the mathematical expres-sions (that is, governing equations, boundary conditions
48、, andsolution methods), the logic of the model, and the computeralgorithms. In many instances, it will be useful to include aflow chart of the general workings of the program.6.5.3.3 Model ConstructionAdescription of ground-watermodel construction requirements and considerations, that is,considerati
49、ons in translating a user problem into a codes inputformat (for example, grid design and accuracy, boundary andinitial conditions, time step selection and accuracy, and appli-cation limitations).6.5.3.4 Specific Data RequirementsA description of thetype of information required by the program, including adescription of spatial and temporal distribution, the overall datastructure, the data media, general data limitations, and specificinput parameters (that is, their meaning, typical range, and usein the code, including restrictions or bounds on the values). Itshould add
