1、Designation: D 6171 97 (Reapproved 2004)Standard Guide forDocumenting a Ground-Water Modeling Code1This standard is issued under the fixed designation D 6171; the number immediately following the designation indicates the year oforiginal adoption or, in the case of revision, the year of last revisio
2、n. A number in parentheses indicates the year of last reapproval. Asuperscript epsilon (e) 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 mode
3、ling 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
4、 development 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 addres
5、ses 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 D 5447,D 5490, D 5609, D 5610, D 5611, and D 5718.1.4 This guide is not intended to be all inclusive. If offers
6、 aseries 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 notrep
7、lace or relieve 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 sa
8、fety and 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 u
9、sed in conjunction 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 consi
10、deration 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:2D 653 Terminology Relating to Soil, Rock, and ContainedFluidsD 5447 Guide for Applic
11、ation of a Ground-Water FlowModel to a Site-Specific Problem3D 5490 Guide for Comparing Ground-Water Flow ModelSimulations to Site-Specific InformationD 5609 Guide for Defining Boundary Conditions inGround-Water Flow ModelingD 5610 Guide for Defining Initial Conditions in Ground-Water Flow ModelingD
12、 5611 Guide for Conducting a Sensitivity Analysis for aGround-Water Flow Model ApplicationD 5718 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, bookk
13、eeping, and control 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, boundaryco
14、nditions, and analytical and operational capabilities.3.1.3 ground-water modeling codethe non-parameterizedcomputer code used in ground-water modeling to represent anon-unique, simplified mathematical description of the physi-cal framework, geometry, active processes, and boundaryconditions present
15、in a reference subsurface hydrologic system.1This guide is under the jurisdiction of ASTM Committee D18 on Soil and Rockand is the direct responsibility of Subcommittee D18.21 on Ground Water andVadose Zone Investigations.Current edition approved May 1, 2004. Published June 2004. Originallyapproved
16、in 1997. Last previous edition approved in 1997 as D 6171 - 97e1.2For referenced ASTM standards, visit the ASTM website, www.astm.org, orcontact ASTM Customer Service at serviceastm.org. For Annual Book of ASTMStandards volume information, refer to the standards Document Summary page onthe ASTM webs
17、ite.3Withdrawn.1Copyright ASTM International, 100 Barr Harbor Drive, PO Box C700, West Conshohocken, PA 19428-2959, United States.3.2 For definitions of other terms used in this guide, seeTerminology D 653.4. Significance and Use4.1 Ground-water modeling has become an important meth-odology in suppo
18、rt 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 hum
19、an 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 (1
20、).44.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 mode
21、ling-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 quali
22、ty 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. This
23、 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, inc
24、onsistent 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 Develop
25、ment 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 documentatio
26、n; 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 existi
27、ngset 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 preparati
28、on 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 program
29、ming 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 purp
30、oses 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 ena
31、ble 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 unde
33、rstanding 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 publishedrepo
34、rts, 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 me
36、thods 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 tes
37、t cases;installation, input preparation, and code execution instructions;and methods to review input data and results. A summary of4The boldface number given in parentheses refer to a list of references at the endof the text.D 6171 97 (2004)2code 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 ConstructionA description of ground-watermodel construction requirements and considerations, that is,considerat
49、ions 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 addr
