Computer science model documination and best document, Schemes and Mind Maps of Applications of Computer Sciences

Download Computer science model documination and best document and more Schemes and Mind Maps Applications of Computer Sciences in PDF only on Docsity!

. Department bommeree

lonal Bureau tandards

Computer Science

and Technology

NBS Special^ Publication 500-

Computer Model

Documentation

Guide

NATIONAL BUREAU OF STANDARDS

The National Bureau of Standards' was established by an act of Congress (^) on March 3, 1901. The Bureau's overall goal is to strengthen and advance the Nation's (^) science and technology and facilitate their effective application for public benefit. To this end, the (^) Bureau conducts research and provides: (^) (1) a basis for the Nation's physical measurement (^) system, (2) scientific and technological services for industry and government, (^) (3) a technical basis for (^) equity in trade, and (^) (4) technical services to promote public safety. The Bureau's technical (^) work is per- formed by the National Measurement Laboratory, the National Engineering (^) Laboratory, and the Institute^ for^ Computer^ Sciences^ and^ Technology.

THE NATIONAL MEASUREMENT LABORATORY provides^ the national system of physical (^) and chemical and materials measurement; coordinates (^) the system with (^) measurement systems of other nations and furnishes essential services leading to (^) accurate and uniform physical and chemical^ measurement^ throughout^ the^ Nation's^ scientific community, industry, and commerce;^ conducts^ materials^ research^ leading^ to^ improved^ methods^ of^ measurement, standards, and data on the properties of^ materials^ needed by industry, commerce, educational institutions, and Government;^ provides advisory^ and^ research^ services^ to other Government agencies; develops, produces, and distributes Standard Reference Materials; and provides calibration services. The Laboratory consists of the following centers:

Absolute Physical Quantities- —^ Radiation Research —^ Thermodynamics and Molecular Science —^ Analytical Chemistry —^ Materials Science.

THE NATIONAL ENGINEERING LABORATORY provides technology and technical ser- vices to the public and private sectors to address national needs and to solve national problems; conducts research in engineering and applied science in support of these efforts; builds and maintains competence in the necessary disciplines required to carry out this research and technical service; develops engineering data and measurement capabilities; provides engineering measurement traceability services; develops test methods and proposes engineering standards and code changes; develops and proposes new engineering practices; and develops and improves mechanisms to transfer results of its research to the ultimate user. The Laboratory consists of the following centers:

Applied Mathematics —^ Electronics and Electrical Engineering^ —^ Mechanical Engineering and Process Technology- —^ Building Technology —^ Fire Research — Consumer Product Technology —^ Field Methods.

THE INSTITUTE FOR COMPUTER SCIENCES AND TECHNOLOGY conducts research and provides scientific and technical services to aid Federal agencies in the selection, acquisition, application, and use of computer technology to improve effectiveness and economy in Government operations in accordance with Public Law 89-306 (40 U.S.C. 759), relevant Executive Orders, and other directives; carries out this mission by managing the Federal Information Processing Standards Program, developing Federal ADP standards guidelines, and managing Federal participation in ADP voluntary standardization activities; provides scientific and technological advisory services and assistance to Federal agencies; and provides the technical foundation for computer-related policies of the Federal Government. The institute consists of the following centers:

Programming Science and Technology —^ Computer Systems Engineering.

'Headquarters and Laboratories at Gaithersburg, M (^) D, unless otherwise noted; mailing address Washington, DC 20234. Some divisions within the center are located at Boulder, CO 80303.

Reports on Computer Science and Technology

The National Bureau of Standards has a special responsibility within the Federal Government for computer science and technology activities. The programs of the NBS Institute for Computer Sciences and Technology are designed to provide ADP standards, guidelines, and technical advisory services to improve the effectiveness of computer utilization in the Federal sector, and to perform appropriate research and development efforts as foundation for such activities and programs. This publication series will report these NBS efforts^ to the^ Federal^ computer community as well as to interested specialists in the academic and private sectors. Those wishing to receive notices of publications in this series should complete and return the form at the end of this publication.

National Bureau of Standards Special Publication 500- Nat. Bur. Stand, (U.S.), Spec. Publ, 500-73, 56 pages (Jan. 1981) CODEN: XNBSAV

Library of Congress Catalog Card Number: 80-

U.S. GOVERNMENT (^) PRINTING OFFICE WASHINGTON: (^1980)

For (^) sale by the Superintendent (^) of Documents, (^) U.S. Government Printing Office, Washington, D.C. 20402

Price $3. (Add 25 percent (^) for other than U.S. mailing)

PREFACE

This document was prepared for the Institute for Com-

puter Sciences and Technology, National Bureau of Standards,

by the^ Federal^ Computer^ Performance^ Evaluation^ and Simula-

tion Center (FEDSIM).^ It^ is^ based^ on^ a similar^ document

originally prepared for use (^) by the U.S. Air Force in support

of military analyses. That^ document has been rearranged,

examples have been changed, and the document has been made

more generally applicable so that it may be used throughout

the Federal simulation community. Recommendations for im-

provements of these guidelines^ are solicited.^ It^ is^ intend-

ed that after thorough^ reviews^ and trial use this^ document

will be reissued as a Federal Guideline in the^ series^ of

Federal Information Processing Standards (FIPS). All com-

ments should be directed to:

Institute for Computer Sciences and Technology

Programming Science^ Division

Washington, D. C. 20234

r

iii

TABLES

 - 3. Model Description - 4. Description of Routines - 5. Data Base Description - 6. Source Listing - 7. Error Messages - APPENDICES 

• V. GUIDELINES FOR PREPARING AN ANALYST'S MANUAL - 1. Introduction - 2. Functional Description of the Model - 3. Model Input and Output Data - 4. Model Verification and Validation - APPENDICES
• VI. MODEL SUMMARY
• VII. SUMMARY - BIBLIOGRAPHY
  • IV-1 Cross-Ref erenced Data Structure List Sample TABLE
  • IV-2 Sample List of Routines by Overlay Segment
  • IV-3 Cross-Ref erenced Routine List Example

FIGURES

II- l^ Recommended Table of Contents for a Management Summary Manual (^5)

III- l Recommended Table of Contents for a User's Manual 10

III-2 Physical System Highlights Example 12

III-3 Input/Output Schematic 13

III-4 Model Schematic Sample #1 15

III-5 Model Schematic Sample^ #2 16

III-5 Special Procedures Example 19

IV-1 Recommended Table of Contents for a Programmer's

Manual 24

IV-2 Example of a Model Overview Block Diagram 26

IV-3 Sample Overlay Structure Diagram 29

V-1 Recommended Table of Contents for an Analyst's

Manual 36

V-2 Modeled^ System Highlights Example 37

V-3 Input/Output Schematic 39

V-4 Model Functional Flow Example 41

V-5 Comparison of Actual and Simulated Results 44

vi

These guidelines devote a section to each type of manu-

al, i.e.. The Manager's Manual, The User's Manual, The

Programmer's Manual, The Analyst's Manual. Each section be-

gins with a table of contents that lists recommended topics

of interest (^) to users (^) of that manual. Items (^) may be added to

or deleted from this table of contents, however,^ according

to individual requirements. The discussion for each manual

enlarges upon the items required^ in^ each^ of^ the^ sections^ and

subsections, as recommended^ in the table^ of^ contents^ for

that manual. Terms used in each manual should be those

directed toward that manual's audience.

These guidelines are for models that are^ used^ chiefly

in a decision-making environment. Thus, the^ main^ goal^ of^ a

Manager's Manual is to assist managers to make decisions.

To accomplish this, the Manual must describe the model and

its application to managers (including the management that

sponsored the model) who may be interested in^ using^ a

developed capability. The Manual should provide managers

with sufficient information to permit them to accurately as-

sess model input requirements (including time, money, and

other resources), available outputs, and the accuracy and

precision of the results. Managers can use this Manual in

justifying the employment of the model and in evaluating

subsequent results.

A user is assumed to be interested mainly in^ deriving

results from a model for specific applications. The guide-

lines recommend that the User's Manual be organized^ into^ a

section for the user and a section for the data technicians

who will set-up (^) and run the model. To use the model intel- ligently, a user must be aware (^) of its logical structure, the

general simulation approach, and any assumptions and limita-

tions affecting the model's applicability. A user need not

be interested in details of programming or analysis beyond

the preparation of input data and the interpretation of

model results.

Programmers are interested primarily in maintaining^ and

modifying a model. A programmer must correct any errors

discovered during model usage that are not attributable to

user-entered data. Programmers, especially those required

to convert a model to another computer system, need to

understand features of a model that are installation unique.

Thus, the Programmer's Manual must provide all the details

necessary to understand the operation of a model:^ to^ debug

it, to maintain and modify it, and to convert the model to

other computer systems.

-2-

These guidelines assume an analyst to be Interested

primarily In the analytical techniques and algorithms used

in a model. An analyst Is concerned with the equations used

in a model and the methods used for model verification and

validation. An analyst does not need to know user details

such as input and output formats, or programming details in-

volving language syntax.

Decisions about which of these manuals are actually re-

quired, whether or not they should be prepared in separate

volumes, etc., should be made on a case-by-case basis*

Also, a plan should be developed for documentation updates

and maintenance, so that these manuals remain current. Such

issues as these should be dealt with early during the model

planning and development phases, so that documentation re-

quirements actually become part of the development plan,

rather than an afterthought. Further, applicable documenta-

tion produced using programming conventions should be used

in conjunction with these guidelines.

Other guidelines prepared specifically^ to^ support^ com-

puter software documentation are available which may be used

in conjunction with^ this guideline.^ These^ documents^ are:

FIPS PUB 30, Software Summary for Describing Computer Pro-

grams and^ Automated^ Data^ Systems.^ It^ is^ used^ to^ announce

computer programs which are transferable, and have broad ap-

plicability. A standard software summary form is defined

(SF-185), which permits description of the program for iden-

tification, reference and dissemination. This form is used

by the General Services Administration for registry of pro-

grams and for publication of program abstracts in the

Federal Software Exchange Catalog.

FIPS PUB 38, Guidelines for Documentation of Computer Pro-

grams and Automated Data Systems. It provides guidance to

documentation content for the development phase, including

requirements documentation, system specifications, user,

operations and maintenance manuals, and test documentation.

FIPS PUB 64, Guidelines for Documentation of Computer Pro-

grams and Automated Data Systems for the Initiation Phase.

This document provides guidance for project requests, feasi-

bility studies, and cost benefit analyses.

-3-

1. Introduction

2. Model Description

2.1 Capabilities

2.2 Input/Output Classes

2.3 Assumptions and Limitations

3. Model Development and Experimentation

3.1 Development History

3.2 Verification and Validation

3.3 Model Experiments

3.4 Costs and Resource Requirements

4. Current and Additional Applications

4.1 Current Use

4.2 Additional Applications

APPENDICES

A. Project Documentation

B. Bibliography

RECOMMENDED TABLE OF CONTENTS FOR A

MANAGEMENT SUMMARY MANUAL

FIGURE II-l

-5-

2.1 Capabilities

This subsection should briefly summarize the capabili-

ties of the model.^ Include highlights of mathematical and

engineering concepts (but not equations) used as the basis

of the model. Include a statement of the model's primary

purpose. For example, "the model can be used to determine

the daily number of machines in a job shop required to pro-

cess the daily orders." Provide an overview of functional

details that explains how the model accomplishes its stated

purpose. Discuss the general areas of the model's applica-

bility, including the decision making environments. For ex-

ample, describe the types of systems and situations that can

be simulated by the model (possibly with minor changes), in-

cluding the number and kinds of subsystems that can be simu-

lated. (^) For example, if a job shop model includes order pro-

cessing, machine repair, or distribution subsystems, then

their descriptions should be provided. Also include the re-

lationship of this model to any other models (i.e., another

model may prepare input data for this model).

2.2 Input/Output Classes

Provide a short discussion on the different classes^ of

input data required (^) to drive (^) the model and of output data

generated by the model. For example, a job shop^ model^ might

require entering the number of production^ centers,^ the

number of machines per production center, the service rates

of the machines, and the routing of the jobs (orders). Ex-

amples of model output include statistics that show the

utilizations (percent busy time) of the production centers

and the job turnaround (total processing) times. Identify

any special preprocessing required for input data, as well

as all post- processing required on model results.

2.3 Assumptions and Limitations

List assumptions and limitations concerning the appli-

cability of the model. Identify any restrictions on model

usage caused by accuracy limitations of input data and out-

put quantities. Provide comments on levels of detail in the

model that affect the model's applicability. For example,

an analytical representation rather than a detailed simula-

tion of a system component could affect model application.

Also describe any use of random parameters that may affect

the accuracy and use of model output.

-6-

4, Current and Additional Applications

This section should summarize benefits already derived

from the model and recommend other applications for the

model.

A. 1 Current Use

This subsection should briefly describe how the model

has been used by management in its decision-making process.

Provide details of recommendations and conclusions derived

using the model.

4,2 Additional Applications

This subsection should provide details of any addition-

al applications and uses of the model beyond the current

usage. Discuss in general terms any extensions and enhance-

ments to the model which are feasible and could improve its

utility. Identify any extensions which have been scheduled

or planned

.

APPENDICES

Two appendices should be provided as required. Appen-

dix A should reference all other project documentation (in-

cluding the User's Manual, Analyst's Manual, and

Programmer's Manual), including references to the organiza-

tion and person responsible for maintaining the document.

Include references to any documentation of experiments per-

formed using the model. Appendix B should list all applica-

ble documents (excluding project documentation previously

included in Appendix A), including cited and uncited refer-

ences.

-8-

III. GUIDELINES FOR PREPARING A USER'S MANUAL

This section presents a recommended User's Manual or-

ganizational structure and discusses the contents of sec-

tions and subsections to be included therein. A User's

Manual prepared using these guidelines will enable a nonpro-

gramming model user to understand the model's logical struc-

ture, the input data requirements, the results produced by

the model, (^) and the use of model results. Figure III-l

presents a recommended table of contents for a User's Manu-

al. The sections and subsections contained in the figure

cover the general needs of a user interested in a model. In

documenting a particular model, however, sections and sub-

sections may be added to improve clarity, and some subsec- tions may be omitted for simple models. Note that there is

a certain amount of redundance among the various sections of

a User's Manual prepared according to these guidelines.

Nevertheless, the progressively increasing level of detail

dictated by this structure is desirable to satisfy different

levels of user interest in the manual.

1. Introduction

The User's Manual introduction should contain^ the^ back-

ground of the project, the purpose of the model, and an

overview of the remaining sections in the manual. A common

introduction may be used for all the manuals prepared^ for^ a

model, but the specific purpose of the User's Manual should

be included in a statement of the form:

"The purpose of this manual is to provide nonprogram-

ming users of (model name) with the information neces-

sary to use the model effectively."

2. Description of the Model

This section should contain a well-structured presenta-

tion of the logical details of the model. The material here

should be descriptive and include block diagrams and tables

and charts where needed; it should not give details needed

by a data technician to run the model.

2. 1 Overview

This subsection should provide^ sufficient general^ in-

formation about the model to assist a user in determining

the applicability of the model for specific needs.

-9-

2.1.1 Model Identificatio n The Identification should contain

the name of the physical^ system^ being^ simulated,^ name^ of^ the

model (acronym and expansion), programming language(s) used

to Implement the model, computer(s) on which the model may

be run, and relationships. If any, to other models.

2.1.2 Physica l System Highlights. Include a block diagram

that shows the physical system or phenomenon being simulat-

ed. Discuss, at a macro level, the major system elements

shown In the diagram, their relation to each other, and the

flow of control, information, data, and activity between

them, as appropriate. In the case of complex models, pro-

vide in this subsection a first-level block diagram that

shows the major subsystems and their interactions, and post-

pone the details of each of the subsystems until Subsection

2.2.1, Figure III-2 is an example of physical system

highlights depicting the operations of a typical shop model,

2.1.3 Mode 1 Applicability. Discuss the general magnitude of

model applicability. The types of systems or situations

that can be simulated by the model (possibly with minor

changes) and the number of subsystems (e.g., production

centers and machines per production center in a job shop

simulation) that can be handled are examples^ of^ material^ to

be (^) included in this subsection.

2.1.4 Input and Output. Provide a general statement of the

different kinds of input data needed to drive the model, the

output data generated by the model, and uses of model out-

put. For example, a job shop model might require entering

the number of production centers, the number of machines per

production center, the service rates of the machines, and

the routing of the jobs (orders). Examples of model output

include statistics that show the utilizations (percent busy

time) of the production centers and the job turnaround (to-

tal processing) times. The principal model use could be to

determine the number of machines in a job shop required to

process the daily (^) orders.

Highlight any special data collection procedures (e.g.,

run other models or computer programs, extract data from do-

cuments or listings, conduct sampling experiments) required

to (^) produce model input data. List any unique data sources

or other organizations that might have to be contacted to

gather data. Figure III-3 is an example of an input/output

schematic

.

-11-

JOB

ARRIVALS

ROUTE JOBS TO PRODUCTION CENTER

PRODUCTION CENTER^1

QUEUE 1

MACHINE GROUP (^1)

O O

ooo

QUEUE 2

PR(X)UCTION CENTER 2 MACHINE GROUP 2

PRODUCTION CENTER^ N

QUEUE N

^C^CHINE GROUP N

A

A A

JOB.

COMPLETION.'

PHYSICAL SYSTEM HIGHLIGHTS EXAMPLE

FIGURE III-

-12-