Guideline for Software Documentation - Springerextras.springer.com/2009/978-0-8176-4592-2/A.1.2... · operating systems or database system software thus is not an object of this guideline

PTB-RSE-D3.0E

2005-09-12

Title : Information Technology - Guidelines for Software Development –

Guideline for Software Documentation

Version : PTB-RSE-D3.0E

Date : 2005-09-12

References : Development Standard for IT Systems of the Federal Republic ofGermany (V-Model XT)

Authors : N. Greif e-mail: [email protected]

D. Saborrosch e-mail: [email protected]

2

Guideline for Software Documentation

Content: Page:

1 Introduction 3

2 Scope 4

3 Content of the guideline 4

4 Functions and types of software documentation 5

5 General recommendations for the development of a software documentation 7

6 Content of the software documentation 8

7 Checklist for the software documentation 17

8 Documentation example 23

3

1 Introduction

Although computer programs and the associated documentation are inseparable parts of the

software, the documentation is often neglected in software development and in many cases is

lacking completely . It is, however, a prerequisite for the smooth application and maintenance

(updates, upgradings) of a software that the documentation is complete, neatly structured,

intelligible to its users and in agreement with the functionality of the program. In practice,

documentations often show the following deficiencies:

• They are written in a technical language and therefore difficult to understand and to read.

• When a software is altered, the documentation is not updated accordingly (it is not up-to-

date, not complete, not consistent).

• The documentation is not neatly structured (it is poorly composed and does not contain a

keyword list).

Such deficiencies can have serious consequences, e.g. :

• New staff members will have difficulties in familiarising themselves with their new work.

• A job already carried out is repeated unnecessarily in subsequent phases of the project.

• Software maintenance requires extra work or is not possible.

• Legal consequences in the wake of software problems (product liability).

To rule out such deficiencies and consequences, the aims and function of the software

documentation are to be defined (see section 4) and included in an appropriate guideline. By

prescribing a uniform structure for all documentations and uniform use of the terms and

concepts, such a guideline ensures the completeness and comparability of all documentations.

4

2 Scope

This guideline serves to assure the quality of software development. It is also a basis for the

drafting of the contract documents when software development commissions are placed with

third parties.

This guideline is to be applied for the software development at the PTB

• if the software will be used or is intended for use in the regulated area and/or in

connection with other services to and from third parties;

• if the software is not exclusively used or envisaged to be used by the developer(s) in a

project and/or a laboratory.

When software development commissions are placed with third parties, this guideline is, as a

matter of principle, to be applied as an integral part of the contract.

Application of this guideline is also recommended for any further software development

• if the size of the software exceeds 500 source code lines (without comment) or

• if it is intended to be used for at least one year.

3 Content of the guideline

The application of a guideline for software documentation will enhance the completeness and

comparability of the program data important for use and maintenance. This is achieved in

particular by prescribing a uniform structure and checklist, the use of uniform terms and

concepts and an exemplary representation of individual documentation parts.

The software documentation guideline is structured as follows:

• general recommendations for drawing up a software documentation (section 5),

• content of the software documentation (section 6),

• checklist for the selection and weighting of the documentation elements (Section 7),

• documentation example (section 8).

5

The bullets of the software documentation in section 6 were selected according to appropriate

standards in this field. Such standards are:

(1) ISO/IEC 6592: 2000, Information Technology - Guidelines for the Documentation of

Computer-based Application Systems.

(2) ISO/IEC FCD 9127: 2005, Software Engineering – User Documentation and Cover

Information for Consumer Software Packages.

(3) ISO/IEC 18019: 2004, Software and System Engineering – Guidelines for the Design

and Preparation of User Documentation for Application Software.

It has been adjusted to the needs of a documentation of scientific and technical software (e.g.

programs for processing measured values, simulation programs). The documentation for

operating systems or database system software thus is not an object of this guideline.

4 Functions and types of software documentation

In essence, the software documentation shall fulfill the following main functions:

1: Instruction function

It shall serve as:

• a basis for decisions on the purchase and use of software,

• operating instructions,

• working instructions (e.g. error and interrupt handling, data archiving),

• a working basis to avoid duplication of work,

• a working basis for software maintenance (e.g. updates, upgradings, troubleshooting),

• a basis for brief instruction and training of new staff members; simple training courses.

2: Checking and objective evidence function

• related to internal and external auditors (product liability, ISO 9001 certification),

• in the context of project progress monitoring.

6

3: Communication function

• Uniform communication basis for

• all persons involved in the software development,

• contractors/customers,

• purchasers/sellers,

• increased software re-usability,

• increased transparency/comparability of the programs which are available on the software

market.

When devising the content of the software documentation, these different documentation

functions must be taken into account. Depending on the intended use of the documentation

(and consequently on the target group), the different documentation parts and/or items of the

documentation can be weighted differently. Whilst the system documentation relates to

technical data which are necessary for the installation, operation and maintenance (updates

and upgrades) of a program, the user documentation describes the meaningful application of

the program for special user groups in an easily intelligible way.

In the broader sense, software documentation also encompasses the project management

documentation (covering the entire project flow including time and cost aspects) as well as

the program development documentation. The latter describes the methods and results of the

individual development steps in the software life cycle (requirements specifications, technical

concepts, design specifications, programs, test methods and results). These two process-

oriented document types are not, however, considered in the guideline which is rather

focussed on the documentation of software as a product, here divided into two parts and

named system documentation and user documentation, respectively.

7

5 General recommendations for the development of a software documentation

In the following, we will explain some principles of appropriate and time-saving

documentation:

5.1 Software documentation parallel to the software development

Software development or software maintenance processes must also be seen as documentation

processes. Preparing the documentation for a software parallel to the software development

(or to a software project) spares expensive documentation work at a later stage when program

creation has already been terminated. The basis for this is provided by process models (phase

models) for software development. Parts of the documentation containing complete or partial

results from single phases of the program development (see section 4, program development

documentation) are compiled according to the specified structure and, if necessary, product-

specific aspects are added.

In public institutions and in many companies, the Development Standard for IT Systems of

the Federal Republic of Germany, dated 2005-08-01, is used as the life cycle process model.

It is known as V model XT release 1.1. On 2004-11-04, the inter-ministerial agency (IMKA)

has recommended the usage of the V model XT to the administration of the Federal

Government in cases of newly developed software systems. The V model XT can be

downloaded from the web site www.kbst.bund.de of the KBSt (The Federal Government Co-

ordination and Advisory Agency for IT in the Federal Administration).

5.2 User orientation of the documentation

The software documentation must be adapted to its specific purposes and thus be tailored to

the needs of different groups of users. This can be achieved in accordance with section 4

which furnishes a distinction between system documentation and user documentation. The

items listed in section 6 must be assigned accordingly.

5.3 Program comments

It is absolutely necessary not only to provide a complete software documentation but also a

meaningful comment in the source code of the program (see section 8, para. 3.3).

8

5.4 Graphical means of illustration

When conceiving the software documentation, preference is always to be given to graphical

representations. Call trees, program flow charts or structure charts, data flow charts and

interaction flow charts enhance clarity and intelligibility of the documentation (see section 8).

The logical structure of databases can be shown e.g. by entity-relationship diagrams.

5.5 Auxiliary means of documentation

To reduce the time and labour necessary, it is advisable to use the form sheets of a word-

processing program or of literate programming systems such as WEB.

5.6 Notes on how to conceive the documentation

The documentation should be suitably structured and include by all means a list of keywords

as well as references. Summaries and examples enhance the intelligibility.

6 Content of the software documentation

On the following pages, a structure for the documentation of technical and scientific software

is given on the basis of the standards mentioned in section 3. The different columns of the

table contain information on the specific item (No.) and title (Title) within the structure and,

for further explanation, the content (Description). Depending on the purpose and user group

of the documentation, it is possible to leave out items of the structure while others can be

emphasised more strongly. In the case of programs with database applications, for example,

the item "data organisation" must be dealt with in more detail than in the case of programs

with simple input and output files.

According to section 4 and para. 5.2, a distinction is to be made between system

documentation and user documentation. A user documentation can, for example, be derived

from a system documentation by leaving out such items as program structure, program flow

and test (i.e. items concerning internal program matters) as well as by adding the item

"application example."

9

Content of the software documentation

ItemNo.

Title Description

1 Characteristic program data Brief survey of program.

1.1 Program identification

1.1.1 Program name Designation for program identification.

1.1.2 System assignment Name of the parent program in case of a child programunit.

1.1.3 Name of variant Addendum to program name to identify severalprogram variants with different contents.

1.1.4 Current version Addendum to the program name or to the name of thevariant to identify the currently valid program version(e.g. number, date).

1.1.5 Date of release Date of release of the first and of the current programversion.

1.2 Descriptors Statement of keywords/search words for the program.

10


ItemNo.

Title Description

1.3 Brief description ofprogram

1.3.1 Program tasks Brief application-related description of the task to besolved by the program.

1.3.2 Program content Brief description of the methods, theories andcomputation methods used to solve the task.

1.3.3 Regulations Reference to important laws, standards, and guidelinesto be complied with.

1.3.4 Special features Description of- technical prerequisites or limitations,- technical application limits (e.g. maximum responsetime)

- contractual information (copyright, licenses,conditions of use, warranty questions).

1.4 Devices needed List of devices needed for program execution(processors, data interfaces, process interfaces), devicerequirements, device restrictions.

1.5 Program size Maximum storage space needed (in Kbytes).

1.6 Program requirements

1.6.1 Operating systems Statement of operating systems under which theprogram runs.

11


ItemNo.

Title Description

1.6.2 Programming languages /compiler

Exact details of language and compiler version.

1.6.3 Other programs List of auxiliary programs and/or program librariesneeded.

1.7 Data organisation List of all files used (name, purpose, access type,storage space needed, application limits). Details ofuse of a data base operating system.

1.8 Scope of documentation List of documentation parts available (systemdocumentation, user documentation, programdevelopment documentation, project managementdocumentation).

1.9 Responsibilities Exact details of program author, responsibilities withrespect to program maintenance, debugging, sales.

2 Program function

2.1 Tasks

2.1.1 Description of tasks Detailed description of the task to be solved(overview, relationships, what is to be solved?).

2.1.2 Theoretical bases / bound-ary conditions / literature

Rough description of the models/methods applied (onwhich basis is the task solved?).

12


ItemNo.

Title Description

2.1.3 Units of measurement List of the physical quantities used, including theirunits of measurement.

2.1.4 Regulations Complete list of the laws, standards and guidelines tobe observed, including list of references. Deviationsare to be noted. Information-technological andapplication-related processing regulations.

2.2 Solving of tasks

2.2.1 Hierarchy of functions Hierarchical structure of tasks and sub-tasks (related toprogram structure).

2.2.2 Methods / algorithms Exact description of solving methods with applicationlimits (how is the task solved?).Description of plausibility checks.

2.2.3 Error handling Statement of the error messages envisaged and of themeasures to be taken.

3 Program layout

3.1 Program modules Complete list of all sub-programs, procedures,modules, classes, methods, events, rules, globalvariables and constants.

3.2 Program structure Survey of structure including interfaces, e.g.graphically as call hierarchy or Jackson diagramand/or as class hierarchy.

13


ItemNo.

Title Description

3.3 Source code

3.4 Compiling and linking List of all steps to be taken to generate an executableprogram (e.g. Makefile).

4 Program flow

4.1 Program flow description Representation of the internal program flow with crossreferences to the source code (program flow chart toDIN 66001, structure chart to DIN 66261).

4.2 Use case analysis Presentation of the external view on system, usage ofUML diagrams (Unified Modeling Language)

4.3 Interaction flow Exact representation of the interaction flow (represen-tation of the conditions leading to interaction dialogs).

4.4 Description of dialogs Detailed description of the individual screen layouts.

4.5 Data flow description Representation of the data flow to DIN 66001,Structured Analysis method (SA).

14


ItemNo.

Title Description

5 Data organisation

5.1 Input data Description of the structures- of data which have already been stored (files with

data fields, tables with attributes, classes withinstance variables),

- of data which remain to be entered (via keyboards,input units).

Details of access methods, standard initialisations,permissible input areas and maximum data quantitiesto be processed.

5.2 Output data Description of data base entries, printer outputs,display outputs, device controls, output data in files.Details of data quantities.

5.3 Data base application Description of the logical database structure (entity-relationship model, object-oriented data model,relation schemes: tables with attributes), name andversion of the database management system used,compilation of the database queries and entries.

5.4 Temporary files Brief description if temporary data are available.

5.5 Data protection Description of access rules (authorisation to access,password protection). Measures for manipulationprotection.

5.6 Data storage Details of data archiving, safeguarding methods(retention periods, expiry dates, backup cycles, datareconstruction, recovery procedures).

15


ItemNo.

Title Description

6 Program test

6.1 Test objectives Application e.g. of module test, integration test,acceptance test or test for conformity with standards.Required test coverage.

6.2 Test methods Description of the test methods and test tools used (testprograms, test environment).

6.3 Test cases / test results Statement of the test data and of the expected andactual test results. Test coverage achieved.Benchmarks.

7 Program installation

7.1 Devices needed, hard- andsoftware

Precise description of processors, data and processinterfaces, computer networking, data transmission.Details of device requirements and software needed.

7.2 Installation instructions

7.3 Special features Details of technical restrictions, data protection,configuration. Hints for set-up and adaptation.

16


ItemNo.

Title Description

8 Program operation

8.1 Operating instructions Details of- preparation of peripheral devices,- program control,- program monitoring,- data protection, archiving, password protection.

8.2 Program messages Reasons and measures to be taken.

8.3 Interrupt handling Instructions for normal and emergency interruption.Measures to be taken in case of crash, for dataprotection and for restarting.

9 Application example Description of an application example including allprogram inputs/outputs.

17

7 Checklist for the software documentation

The proposed checklist serves to

• select and weight the items of the software documentation,

• check whether the individual items have been completed,

• adhere to the completion date,

• enter remarks and notes with respect to the documentation process,

• enter references for example to parts of the documentation which have already been

completed.

The first two columns of the table below list all items of the software documentation

according to section 6 (item number, documentation item). The other three columns contain:

• data referring to the selection and weighting of items,

• date on which the documentation item will be completed,

• remarks and references.

18

Checklist for software documentation

ItemNo.

Documentationitem

Necessary?Weighting

Date ofcompletion

RemarksReferences

1 Characteristic program data


1.1.1 Program name

1.1.2 System assignment

1.1.3 Name of variant

1.1.4 Current version

1.1.5 Date of release

1.2 Descriptors

1.3 Brief description of program

1.3.1 Program tasks

1.3.2 Program content

1.3.3 Regulations

1.3.4 Special features

19


ItemNo.

Documentationitem

Necessary?Weighting

Date ofcompletion

RemarksReferences

1.4 Devices needed

1.5 Program size


1.6.1 Operating systems

1.6.2 Programming languages /compiler

1.6.3 Other programs

1.7 Data organisation

1.8 Scope of documentation

1.9 Responsibilities

2 Program function

2.1 Tasks

2.1.1 Description of tasks

20


ItemNo.

Documentationitem

Necessary?Weighting

Date ofcompletion

RemarksReferences

2.1.2 Theoretical bases / boundaryconditions / literature

2.1.3 Units of measurement

2.1.4 Regulations


2.2.1 Hierarchy of functions

2.2.2 Methods / algorithms

2.2.3 Error handling

3 Program layout

3.1 Program modules

3.2 Program structure

3.3 Source code

3.4 Compiling and linking

21


ItemNo.

Documentationitem

Necessary?Weighting

Date ofcompletion

RemarksReferences

4 Program flow

4.1 Program flow description

4.2 Use case analysis

4.3 Interaction flow

4.4 Description of dialogs

4.5 Data flow description

5 Data organisation

5.1 Input data

5.2 Output data

5.3 Data base application

5.4 Temporary files

5.5 Data protection

5.6 Data storage

22


ItemNo.

Documentationitem

Necessary?Weighting

Date ofcompletion

RemarksReferences

6 Program test

6.1 Test objectives

6.2 Test methods

6.3 Test cases / test results


7.1 Devices needed, hard- andsoftware

7.2 Installation instructions

7.3 Special features

8 Program operation

8.1 Operating instructions

8.2 Program messages

8.3 Interrupt handling

9 Application example

23

8 Documentation example

In the following, we will demonstrate by an example how a software documentation could

look like. For better illustration, this example will be more detailed than would be necessary

in many cases. The documentation was subdivided into a system documentation (s-docu) and

an user documentation (u-docu). The diagrams were created using UML (Unified Modeling

Language) 2.0. The program used in the example is called HemEmi and was written in

Delphi.

Checklist for software documentation HemEmi

ItemNo.

Documentationitem

Necessary?Weighting

Date ofcompletion

RemarksReferences

s-docu u-docu

1. Characteristic program data yes yes 22-04-2005

1.1. Program identification yes yes 22-04-2005

1.1.1. Program name yes yes 22-04-2005

1.1.2. System assignment ----- ----- ----- separate program

1.1.3. Name of variant ----- ----- ----- no variants

1.1.4. Current version yes yes 30-04-2005

1.1.5. Date of release yes ----- ----- Up to now thereis no release

1.2. Descriptors yes ----- 22-04-2005

1.3. Brief description of program yes yes 23-04-2005

1.3.1. Program tasks yes yes 23-04-2005

1.3.2. Program content yes yes 23-04-2005

1.3.3. Regulations ----- ----- ----- No relevantregulations

24


ItemNo.

DocumentationItem

Necessary?Weighting

Date ofcompletion

RemarksReferences

s-docu u-docu

1.3.4. Special features yes ----- 22-04-2005 Calculation time

1.4. Devices needed ----- ----- ----- none, only PC

1.5. Program size yes ----- 29-04-2005

1.6. Program requirements yes ----- 23-04-2005

1.6.1. Operating systems yes ----- 23-04-2005

1.6.2. Programming languages /compiler yes ----- 23-04-2005

1.6.3. Other programs ----- ----- ----- Other programsare not necessary

1.7. Data organisation yes ----- 23-04-2005

1.8. Scope of documentation yes ----- 22-04-2005User documentation /program development

documentation

1.9. Responsibilities yes yes 23-04-2005

2. Program function yes yes 24-04-2005

2.1. Tasks yes ----- 24-04-2005

2.1.1. Description of tasks yes ----- 24-04-2005

2.1.2. Theoretical bases / boundaryconditions / literature yes ----- 24-04-2005 References to

literature

2.1.3. Units of measurement very brief ----- 24-04-2005 N, K, and Phave no units

2.1.4. Regulations ----- ----- ----- No relevantregulations

2.2. Solving of tasks yes ----- 24-04-2005

25


ItemNo.

Documentationitem

Necessary?Weighting

Date ofcompletion

RemarksReferences

s-docu u-docu

2.2.1. Hierarchy of functions yes ----- 24-04-2005

2.2.2. Methods / algorithms In all detail! ----- 24-04-2005

2.2.3. Error handling yes yes 24-04-2005

3. Program layout yes ----- 27.04.2005

3.1. Program modules yes ----- 27.04.2005

3.2. Program structure yes ----- 27-04-2005

3.3. Source code All sourcecodes? ----- 02-05-2005 Source code as

appendix

3.4. Compiling and linking Very brief ----- 22-04-2005

4. Program flow yes ----- 22-04-2005

4.1. Program flow description Very brief ----- 22-04-2005 Pick out editor

4.2. Use case analysis yes ----- 22-04-2005 Use case diagram

4.3. Interaction flow yes ----- 23-04-2005 Activity diagrams

4.4. Description of dialogs yes ----- 11-05-2005 With required fields,default values, etc.

4.5. Data flow description yes ----- 23-04-2005 Only short

5. Data organisation IMPOR-TANT !!! ----- 24-04-2005

5.1. Input data In all detail ----- 24-04-2005

5.2. Output data In all detail ----- 24-04-2005

26


ItemNo.

Documentationitem

Necessary?Weighting

Date ofcompletion

RemarksReferences

s-docu u-docu

5.3. Data base application ----- ----- ----- No data base

5.4. Temporary files ----- ----- ----- No temporary files

5.5. Data protection yes ----- 02-05-2005

5.6. Data storage yes ----- 02-05-2005

6. Program test yes ----- 02-05-2005

6.1. Test objectives yes ----- 02-05-2005

6.2. Test methods yes ----- 02-05-2005 Comparison withliterature

6.3. Test cases / test results yes ----- 02-05-2005 Summary

7. Program installation Very brief Very brief 29-04-2005

7.1. Devices needed, hard- andsoftware Very brief Very brief 29-04-2005 Not required

7.2. Installation instructions Shortinformation

Shortinformation 29-04-2005 No installation

necessary

7.3. Special features ----- ----- -----

8. Program operation ----- yes 29-04-2005

8.1. Operating instructions ----- In detail 27-04-2005

8.2. Program messages ----- ----- ----- User interfaceby interactions

8.3. Interrupt handling ----- yes 09-05-2005

9. Application example ----- yes 09-05-2005 Use first test data file

27

System documentation HemEmi

Table of contents

1 Program specification......................................................................................................................... 281.1 Program identification...................................................................................................................... 281.1.1 Program name.............................................................................................................................. 281.1.4 Current version............................................................................................................................. 281.1.5 Date of release ............................................................................................................................. 281.2 Descriptors ...................................................................................................................................... 281.3 Brief description of program ............................................................................................................ 281.3.1 Program tasks .............................................................................................................................. 281.3.2 Program content ........................................................................................................................... 281.3.4 Special features............................................................................................................................ 281.5 Program size ................................................................................................................................... 281.6 Program requirements..................................................................................................................... 281.6.1 Operating systems ....................................................................................................................... 281.6.2 Programming languages/compiler ............................................................................................... 281.7 Data organisation ............................................................................................................................ 291.8 Scope of documentation.................................................................................................................. 291.9 Responsibilities................................................................................................................................ 292 Program function ................................................................................................................................ 292.1 Tasks ............................................................................................................................................... 292.1.1 Description of tasks ...................................................................................................................... 292.1.2 Theoretical bases / boundary conditions / literature .................................................................... 292.1.3 Units of measurement .................................................................................................................. 292.2 Solving of tasks ............................................................................................................................... 302.2.1 Hierarchy of functions................................................................................................................... 302.2.2 Methods / algorithms .................................................................................................................... 302.2.3 Error handling............................................................................................................................... 343 Program layout ................................................................................................................................... 353.1 Program modules ............................................................................................................................ 353.2 Program structure............................................................................................................................ 353.3 Source code .................................................................................................................................... 363.4 Compiling and linking ...................................................................................................................... 364 Program flow ...................................................................................................................................... 374.1 Program flow description................................................................................................................. 374.2 Use case analysis ........................................................................................................................... 374.3 Interaction flow ................................................................................................................................ 384.4 Description of dialogs ...................................................................................................................... 404.5 Data flow description ....................................................................................................................... 425 Data organisation ............................................................................................................................... 425.1 Input data......................................................................................................................................... 425.2 Output data...................................................................................................................................... 435.5 Data protection ................................................................................................................................ 445.6 Data storage .................................................................................................................................... 446 Program test ....................................................................................................................................... 446.1 Test objectives................................................................................................................................. 446.2 Test methods................................................................................................................................... 446.3 Test cases/test results..................................................................................................................... 457 Program installation............................................................................................................................ 467.1 Devices needed, hard- and software .............................................................................................. 467.2 Installation instruction...................................................................................................................... 46A Appendix ............................................................................................................................................ 47A.1 Source code .................................................................................................................................... 47A.1.1 UnitMain.pas ................................................................................................................................ 47A 1.2 ... .................................................................................................................................................. 47

28

1 Program specification


1.1.1 Program nameThe program name is HemEmi. The source code comprises the files UnitMain.pas,UnitRechnen.pas, UnitStartewerte.pas, UnitWinkel.pas, UnitFunctions.pas, UnitDirView.pas,UnitDecl.pas, and UnitDateneingabe.pas.

1.1.4 Current versionThe documentation bases on program version 1 of April 29, 2005.

1.1.5 Date of releaseThe current version is not released yet, because the program is still incomplete. The outputroutines are not yet implemented.

1.2 DescriptorsBlack emitter, high temperature radiator, emissivity, measurement data logging andevaluation, Nelder Mead Method, non-linear optimisation, approximation.


1.3.1 Program tasksThe program allows to collect and evaluate the measured emissivity of a black emitter independency on angle and to calculate the total emissivity.

1.3.2 Program contentThe emissivity Epsilon, which was measured at given angles Theta, is approximated by afunction Epsilon = Epsilon (Theta, N, K, P) in order to obtain a sufficient number of gridpoints for an integration over angle Theta. After the evaluation of the parameters N, K, and Pusing an optimisation method without constraints (Nelder Mead Method), the total emissivitywill be calculated by numerical integration (Simpson Method).

1.3.4 Special features10.000 Calculations need about 20 up to 40 minutes at a clock rate of 800 MHz. Thiscorresponds to a calculation time for one calculation of about 0,1 up to 0,25 seconds.

1.5 Program sizeThe executable file has a size of approx. 470 Kbytes.


1.6.1 Operating systemsThe program runs on PC under Windows 98/XP.

1.6.2 Programming languages/compilerThe program is written for a Delphi (Borland Delphi 5 Professional) compiler. It should beusable with a Borland Delphi 5 Standard Compiler, too.

29

1.7 Data organisationThe measured data are entered by the user and saved into a txt file. After evaluation, thecalculated data will be appended to the txt file. Filename and directory for the storagecorrespond to the year of the measurement and the number of measurement. The user maychange them.

Beside the txt file with the measurement data and the calculation results, there exists aconfiguration file config.ini.

1.8 Scope of documentationThe documentation for the HemEmi program consists of the system documentation hereavailable and the user documentation.

1.9 ResponsibilitiesRemarks, notes and suggestions may be sent to the author, Mr. Joe Public (Section Sample ofPTB). Programming was done using the code example of Adam P. Gurson1.

2 Program function

2.1 Tasks

2.1.1 Description of tasksThe total emissivity of a high temperature radiator or black emitter has to be determined. It isgained through the integration of the emissivity Epsilon (Theta) over the angle Theta. Thereare only a few measured values available for the emissivity Epsilon (Theta).

2.1.2 Theoretical bases / boundary conditions / literature• Siegel & Howell, Thermal Radiation Heat Transfer, Taylor & Francis Publishers, Third

Edition 1992, Page 55 – 63• Adam P. Gurson, Simplex Search Behavior in Nonlinear Optimization, BSc-Thesis

College of William & Mary, Virginia, 2000• Jeffrey C. Lagarias, James A. Reeds, Margaret H. Wright, Paul E. Wright, Convergence

Properties of the Nelder-Mead Simplex Algorithm in Low Dimensions, Technical Report96-4-07, Computing Sciences Research Center Bell Laboratories; Murray Hill, NewJersey 07974, Revised Version, May 1, 1997

2.1.3 Units of measurementThe following units of measurement apply:• The temperature of sample has the unit °C.• The temperature of receiver has the unit °C.• The angle of radiation has the unit °.• The emissivity and the parameters N, K, and P have no unit.

1 Adam P. Gurson, Simplex Search Behavior in Nonlinear Optimization, BSc-Thesis College of William &Mary, Virginia, 2000.

30


2.2.1 Hierarchy of functions

Figure 1: Functions hierarchy

2.2.2 Methods / algorithmsThe calculation will be kicked off using the menu item “Calculator / Start Calculation”(Procedure TfmMain.StartderBerechnung1Click).

Menu item “Start Calculation”

Selection of a txt file with measured values by user.Selection between optimisation with two (N, K) or three parameters (N, K, and P). Anoptimisation with three parameters provides better approximation for the measurementvalues, but prohibits a physical interpretation of the parameters N and K.Call of the calculation procedure Calculate. See below.Presentation of the results; optimised parameters N, K, and P, total emissivity Phi and“standard deviation” of the total emissivity. Warnings may appear.Storage of the results into the txt file with the measured values.If warnings appeared, then

Change the initial values for parameters N, K, and PRepeat the calculation

If the “standard deviation” is very high (> 5 % when using three parameters) or if theparameter K is very small (< 0.001 when using three parameters), the optimisation wasprobably not successful. The calculation should be repeated with different initial values for N,K, and P.

Procedure Calculate

Determination of the optimal parameter N, K, and P by Nelder Mead Method (ProcedureNMSearch). See below.Calculate the emission value Epsilon (Theta, N, K, P) for each angle, for which a measuredvalue exists, and assign the “standard deviation” (Functions Epsilon and Varianz).Calculate of the total emissivity Phi (Function HemEmission).

Program to register and evaluate the measuredemission values of a black emitter

Read data Executecalculation Display results

Create new data Change old data As text(Not implemented)

As graphic(Not implemented)

31

Procedure NMSearch

The aim function of the optimisation is the difference between the measured and thecalculated values. More precisely the relative differences in percent are accumulated.

Abweichung (N, K, P) = Σ | 100 * (EpsMessi - EpsBeri) / EpsMessi |

The measured values EpsMessi are the values, which are measured at a specific angle Thetai.The calculated values EpsBeri are the values, which are calculated with the angles Thetai andthe parameters N, K, and P:

EpsBeri = Epsilon (Thetai, N, K, P)

(in program: Thetai --> Results.arMeasData[i].Winkel; EpsMessi --> Results.arMeasData[i].Emmi; EpsBeri --> Results.arMeasData[i].BerechEmmi; N --> Results.N; K --> Results.K; P --> Results.P.)

N, K, and P are varied, until the aim function is minimal. The program uses the Nelder MeadMethod in the version of Adam P. Gurson (slightly changed) for optimisation.

The optimisation starts with an initial point (= vertex) (N, K, P) in a three-dimensional space.From this initial point, three more points are generated. The four points together form atetrahedron (= simplex)2.

For each vertex of the tetrahedron the value of the aim function is calculated, i.e. the deviationbetween calculated and measured values. The vertex with the greatest value (greatestdeviation) is replaced by a new point. It forms a new tetrahedron, which is displaced indirection on the (local) minimum. In the further optimisation steps the tetrahedron movesthrough the space until a certain stop criterion applies. The motion of the tetrahedron isroughly directed to the (local) minimum.

For the calculation of a new point, which replaces the worst point, four methods exist:• Reflection point

The new point is calculated through reflection of the worst point at the centroid of theremaining points. The coefficient Rho = 1 is used.

• Expansion pointThe new point is calculated like the reflection point, but is shifted away after reflection(coefficient Chi = 2). The tetrahedron enlarges.

• Contraction pointThe new point is calculated like the reflection point, but is shifted to the centroid afterreflection (coefficient Gamma = ½). The tetrahedron gets smaller.

• ShrinkingAll points, excepting the best, are displaced in direction of the best point (coefficientSigma = ½ ). The tetrahedron gets extremely smaller.

2 When two parameters are used instead of three, three points (N, K) form a triangle. This triangle ismoved on the surface built-up by the function Abweichung(N, K) until a minimum is reached.

32

Sequence(P1 < P2 means: point 1 is better, that is point 1 has a smaller deviation than point 2.)

Set the values Tolerance and (Max)NumberOfCalls, which are needed for the stop criterion.Set the coefficients Rho (for reflection), Chi (for expansion), Gamma (for contraction) andSigma (for shrinking). The standard values Rho = 1, Chi = 2, Gamma = 0,5 and Sigma = 0,5are used. Procedure NMSearch.Init.Initialise the counter NumberOfCalls, which counts the calls of the aim function. ProcedureNMSearch.Init.Initialise all internal variables, which are needed. Procedure NMSearch.Init.Calculate the start tetrahedron from the initial values of N, K, and P. The first vertex of thetetrahedron is directly built the tuple (N, K, P). The other three vertices are copies of thefirst, whereas for each vertex one parameter is varied (increased by around 40 %). ProcedureNMSearch.Init.Calculation of the aim function (the deviation) for each vertex of the tetrahedron. ProcedureNMSearch.Init and function Abweichung.Repeat until stop (Procedure NMSearch.StopCalculation):

Find out the worst (greatest deviation), the second worst and the best point of thetetrahedron. Procedure NMSearch.FindMinMaxIndices.Calculate the reflection point und its function value (deviation). ProcedureNMSearch.CalculateReflectionPoint.If reflection point < best point of the body, then

Calculate the expansion point and its function value. ProcedureNMSearch.CalculateExpansionPoint.If expansion point < reflection point

Replace the worst point of the tetrahedron with the expansion point.Procedure NMSearch.ReplaceSimplexPoint.

ElseReplace the worst point of the tetrahedron by the reflection point.

If reflection point >= best point and reflection point < second worst point, thenReplace the worst point by the reflection point.

If reflection point > worst point, thenCalculate the inside contraction point. ProcedureNMSearch.CalculateInsideContractionPoint.If inside contraction point < worst point

Replace the worst point by the inside contraction point.Else

Reduce (shrink) the tetrahedron in direction to the best point. ProcedureNMSearch.ShrinkSimplex.

ElseCalculate the outside contraction point. ProcedureNMSearch.CalculateOutsideContractionPoint.If outside contraction point <= reflection point

Replace the worst point by the outside contraction pointElse

Reduce (shrink) the tetrahedron in direction to the best point.Take over the coordinates of the best point of the tetrahedron as parameter N, K, and P.

33

The loop of optimisation terminates for three reasons (ProcedureNMSearch.StopCalculation):• The function values (the deviations) for the points of the tetrahedron differs from each

other by less than a given limit. The optimisation is considered adequate and is finished.• The maximal number of aim function calls (deviation) is accomplished. This is an

emergency measure to avoid infinite loops. Normally, the optimisation finishes muchearliest.

• An error appears during the calculations of Epsilon or the deviation, shown by the errorvariable ErrorNumber. The optimisation will be broken off.

The control is not implemented, whether the body degenerates in the course of optimisation(the tetrahedron to the triangle and the triangle to the line, respectively). That would be thecase, if one of the vertices would be a linear combination of the other points. In that case, theoptimisation had to be cancelled, too. In literature, there are no recommendations to do so.

Function Varianz

The procedure Varianz computes value, which is comparable with the variance in statistics.The sum of all deviation squares between the calculated and measured emissivity values iscalculated:

Varianz (N, K, P) = Σ ( EpsMessi - EpsBeri )2

The value is denoted as “standard deviation” = √ (Varianz).

It must be pointed out, that the estimated values EpsBeri for the true values are not found byleast squares method – as in statistics. Instead, it is found by minimising the sum ofdeviations.

Function HemEmission

After the evaluation of the optimised parameters N, K, and P, the emissivity Epsilon (Theta,N, K, P) can be calculated for each desired angle. The total emissivity is found by numericalintegration using the Simpson method. The function

π Epsilon (Theta, N, K, P)F (Theta, N, K, P) = -- * ------------------------------ * sin(Theta) cos(Theta)

90 Epsilon (0, N, K, P)

is integrated in the range from 0 to 90 degrees.

Function Epsilon

The function Epsilon calculates the following term:

Epsilon = 1 – (PhiPar + PhiSenk)/2 – P

with PhiSenk = (AA1 – BB1) / (AA1 + BB1)

and PhiPar = (AA2 – BB2) / (AA2 + BB2) * PhiSenk

with AA1 = Expression3 + cos2(Theta)

34

and BB1 = 2 √ (Expression4) * cos(Theta)and AA2 = Expression3 + sin2(Theta) * tan2(Theta)and BB2 = 2 √ (Expression4) * sin(Theta) * tan(Theta)

with Expression1 = N2 – K2 – sin2(Theta)and Expression2 = 4 N2 K2

and Expression3 = √ (Expression12 + Expression2)and Expression4 = 0,5 * (Expression3 + Expression1).

2.2.3 Error handlingAll users’ inputs are checked immediately after leaving the input field or closing the inputdialog. The work may be continued only, if the wrong inputs are fixed up or the dialog iscancelled.During approximation, errors should not appear. Nevertheless, if errors appear, there will bedefects in RAM. The approximation stops and the error is displayed. The user may repeat thecalculation after a restart of the program. He may also use other initial values for N, K, and P.

Error no. Reason101 Call of the function Epsilon with invalid angles (angle < 0degrees or angle >

90degrees).102 Call of the function Epsilon with invalid parameter values (one of the

parameters N, K or P is less than 0).201 Call of the function HemEmission with invalid parameter values (one of the

parameters N, K or P is less than 0).401 Call of the function NMSearch.FindMinMaxIndices with too little vertices.

The number of vertices is less than 2. The best and the worst point are notdistinct.

402 Call of the function NMSearch.FindMinMaxIndices with too little vertices.The number of vertices is less than 3. The second worst point, the worst pointand the best point are not distinct.

501 Call of the function NMSearch with insufficient number of parameters (< 2).502 Call of the function NMSearch with invalid parameter values (one of the

parameters N, K or P is less than 0).503 Call of the function NMSearch with insufficient number of data. The number

of data must be at least as big as measurement values as parametersdetermines.

601 Call of the function NMSearch.ReplaceSimplexPoint with wrong index. Thepoint of the simplex, which should be replaced, does not exist.

701 The function NMSearch has calculated a wrong reflection point. It is neitherbetter than the best point of the simplex nor worse than the worst nor is itlocated in between.

901 Call of the function Calculate with wrong number of parameters. Thenumbers of parameter may be only 2 or 3.

902 Call of the function Calculate with too few data. The number of data must beat least as big as measurement values as parameters determines.

903 Call of the function Calculate with too much data. At maximum 50 pairs ofmeasurement values are handled.

904 Call of the function Calculate with empty pairs of measurement values. Thefirst two measured angles are not assigned.

905 Call of the function Calculate with empty pairs of measurement values. Thefirst two emissivities are not assigned.

Table 1: Error handling

35

3 Program layout

3.1 Program modulesGlobal variables and types:

TMesRec Record for a pair or tuple of measurement values. Comprises one realvariable for the angle, one for the measured emissivity Emmi and one forthe calculated emissivity BerechEmmi. The calculated emissivity isassigned when the calculation finished. Up to them, it is empty.

TMesRecArray Array with 50 elements of type TMesRec.

TDataRec Record for the summary of all data which belong to a measurement.Comprises text variables for the temperature of specimen, temperature ofreceiver, labelling of specimen, labelling of substrate, plating, and comment,one string for the number of measurement, one variable for the date and onefor the time of the measurement, one integer variable for the number ofpairs/tuples of measurement values, one array of TMesRec for thepairs/tuples of measurement values, three real variables for the optimisedparameters N, K, and P, and two real variables for the total emissivity andits “standard deviation”.

TParamRec Record for the transfer of the three parameters N, K, and P to severalfunctions.

WorkingDir Global variable for the last directory used to load or save data.

WorkingSubDir Subdirectory to WorkingDir, it contains the directory of the current yearORDyyyy\Files.

TXTFileName Global variable, which contains the read filename for the last calculation.

3.2 Program structure

Module ContentUnitMain.pas Main window fmMain with menu bar, reads the config.ini, displays the information

window.UnitDirView.pas Dialog fmDirView with displaying and changing the working directory.UnitFunctions.pas Library of help functions: Loading and Saving of txt-files, string handling and other.UnitDateneingabe.pas Dialog fmDateneingabe with entering, checking and saving of the data, which

belong to a measurement.UnitDecl.pas Definition of types and global variables.UnitRechnen.pas Calculate functions for approximation, the calculation of the “standard deviation”

and the total emission.UnitStartwerte.pas Dialog fmStartwerte for decision between 2 or 3 parameters and entering of initial

values.Table 2: Program structure

36

Figure 2: Calling hierarchy “Calculator / Start Calculation”

3.3 Source codeSee Appendix

3.4 Compiling and linkingOnly the project file HemEmi.dpr must be opened for further development. Compiling andLinking are done using the appropriate menu items.

fmMain.StartderBerechnung1Click

fmStartwerte fmStartwerte.btnYesClick

StarteBerechnung

ReadDataFromTXTFile Calculate SaveDataToTXTFile

Ok-Button:

NMSearch HemEmission Varianz

Init CalculateCentroidCalculateRefl.Pt.

Calculate...

StopCalculation

FindMinMaxIndices ReplaceSimplexPoint

Abweichung

Epsilon

37

4 Program flow

4.1 Program flow description

Figure 3: Program flow description

4.2 Use case analysis

Figure 4: Use case diagram

useruser

HemEmiCreating new files:- Measurement data from users+ Entering measurement data+ Saving measurement data

Starting calculation- Measurement data- Parameter values- Algorithm+ Reading in measurement data+ Applying algorithm+ Storing results

Changing Path- Files of configuration+ Displaying files of configuration+ Changing data of configuration+ Saving data of configuration

Output- Measurement data- Results+ Displaying on monitor

Modifying old files:- Measurement data from users+ Displaying old measurement data+ Entering new measurement data+ Saving measurement data

[No successful approximation]

[No change measurement data]

[Change measurement data]

Entering the measurement data by user

Changing the measurementdata by user

Calculation

Output of results

Changing the initial valuesfor the parameters [Successful

approximation]

38

4.3 Interaction flow

Figure 5: Activity diagram – “Inputs / New File”

Inputs / New File

Entering data record

Checking data record

[Complete data]

[No complete data]

Close buttonpressed

[Ok button pressed]

[Plausible data]

Entering filename

Checking filename

[File exists]

[File does not exist]

Cancel buttonpressed[Save button pressed]

[Overwrite file]

1

1

1

No plausible data]1

Checking data record

[Data changed]

[Data not changed]

[Save data]

[Do not save data]

2

2

[Do not overwrite file]

Saving file

39

Figure 6: Activity diagram – “Inputs / Change File”

Figure 7: activity diagram – “Calculator / Start Calculation”

Dateiname eingeben

Reading data record

[Wrong data record]

[Right data record]

Entering initial value

Calculation

Displayingdata record/results

[Start button pressed]

[Results not plausible]

[Plausible results]

Calculator / Start Calculation

Entering filename

Checking filename

Cancel buttonpressed[Open button pressed]

[File exists]


Close buttonpressed

Savingdata record/results

Inputs / Change File

Entering filename

Checking filename

Reading data record

[File exists]


“New File”

Cancel buttonpressed[Open button pressed]

40

4.4 Description of dialogsThe two important dialogs are described in the follows. The other dialogs are abstract and arenot explained here. These are generic dialogs as used in other programs, too, for example,“Save as” or “Open”.

The following dialog “Data Input” appears after calling the menu item “Inputs / New File”:

Figure 8: HemEmi – Dialog “Data Input”

Field Kind Type Length Defaultvalue

Valid range Remarks

Measurementnumber

needed integer 3 digits <blank> 001 - 999 Number of measurement Itis using by creating a

filename.Date needed date 3 x 2

digitscurrent

dateday:

01- 31month:01 - 12year:

00 - 99

Date of measurementIt must be a valid date.

Do not enter points. The21st century is attached to

the 2-digit yearspecification 00-54, the

20th century to the 2-digitspecification 55-99.

Time needed time 2 x 2digits

currentsystemtime

hour:00 - 23minute:00 - 59

Time of measurementIt must be a valid time. Do

not enter colons.

Temperature ofspecimen in °C

needed integer,float

- <blank> - Temperature of specimen

Temperature ofreceiver in °C


- <blank> - Temperature of receiver

Labelling ofspecimen

optional text max 255characters

<blank> - Notation of specimen

Substrate optional text max 255characters

<blank> - Notation of substrate

41


Valid range Remarks

Plating optional text max 255characters

<blank> - Notation of plating

Comment optional text - <blank> - Arbitrary, multiline text.Angle in °(line 1 – 3)


- <blank> [0, 90] Angle, at which emissivitywas measured. It must be

entered in º (degree).Angle in °

(line 4 – 50)optional float - <blank> [0, 90] Angle, at which emissivity

was measured. It must beentered in º (degree).

Degree ofemissivity(line 1 – 3)


- <blank> [0, 1] Measured emissivity

Degree ofemissivity

(line 4 – 50)

optional float - <blank> [0, 1] Measured emissivity

Table 3: Specification of the several fields in dialog “Data Input”

Three pairs of measurement values must be entered at least. 50 pairs can be entered atmaximum.

Button Active Condition / DescriptionOk yes Saving the current data recordClose yes Closing the dialog without saving the data record

Table 4: Description of the buttons in dialog “Data Input”

After calling the menu item “Calculator / Start Calculation” the dialog “Initial values”appears:

Figure 9: HemEmi – Dialog “Initial values”


Valid range Remarks

NStart needed integer,float

- 10,0 (0, 10] Initial value for N.Values ≥ 1,5 are

favourable.KStart needed integer,

float- 10,0 (0, 10] Initial value for K.

Values ≥ 1,5 arefavourable.

PStart needed integer,float

- 0,5 (0, 2] Initial value for P.A value between 0,2 and 1

is favourable.Table 5: Values of the particularly array element in dialog “Initial values”

42

Checkboxes Active Condition / DescriptionDetermine offset parameter yes If setting the switch, the calculation of the parameters N, K,

and P will be done, otherwise only the parameters N and Kare calculated.

Table 6: Description of the checkboxes in dialog “Initial values”

Button Active Condition / DescriptionStart yes Starting the calculationClose yes Closing the dialog

Table 7: Description of the buttons in dialog “Initial values”

4.5 Data flow description

Figure 10: SA diagram level 0

Figure 11: SA diagram level 1

5 Data organisation

5.1 Input dataFor each measurement, the user must enter some general data, which are not used for thecalculation, and the pairs of measurement values (Thetai, EpsMessi). Details of the user inputscan be seen in the table 3.

Besides these inputs for the txt files, the user can also enter new initial values for theparameters N, K, and P, which will be optimised.

Measurement datafrom user

Output resultsto user

Config file Changingpath

Output

Startingcalculation

Changingold file

Creatingnew file

Measurement dataand result files

User inputs Output to the users

Files

Program

43

Initial values for parameters:N, K Integer or float numbers, real positive, range (0, 10]. Zero is not allowed. Values bigger

or equal than 1,5 are favourable.P Integer or float numbers, real positive, range (0, 2]. Zero is not allowed. Values between

0,2 and 1 are favourableTable 8: Initial values for parameters N, K, and P

The user input (general data and measurement values) are saved into a simple text file.

Format of the txt files:<bof>Data of measurement <Measurement number>Date: <Date>Time: <Time>-Temperature of specimen: <Temperature of specimen> oCTemperature of receiver: <Temperature of receiver> oCLabelling of specimen: <Text>Substrate: <Text>Plating: <Text>-Comment:<Text>...-Measurement values:<Number of pairs of measurement values><Angle1><Emissivity1><Angle2><Emissivity2>...<eof>

5.2 Output dataThe calculation results are registered in the file of input data, too. This is done as soon as thecalculation is finished. The text file can be displayed and changed with an editor. When themeasurement values in the upper part of the file are changed, the results in the lower partloose their validity. If these changes are made with the help of program HemEmi, the resultsare deleted. If the changes are made with the help of an editor, the user should delete theresults to retain consistency.

If calculation was done for a certain file with input data, a section is appended after themeasurement values.

...<Emissivity n>-Calculated values:Parameter N: <N>Parameter K: <K>Parameter P: <P><Angle1><Epsilon(Angle1, N, K, P)><Angle2><Epsilon(Angle2, N, K, P)>...Phi: <Total emissivity>'Std.deviation': <Sum of the deviation squares><eof>

44

The file config.ini contains the global settings of the program. At the first start of theprogram, this file is created, and after that, it is updated casually. Now, only the workingdirectory is contained in the config.ini-file. User may change this directory by using the menuitem “Files / Change Path”.

<bof>[WorkingDir]Dir=<working directory><eof>

5.5 Data protectionThe txt files with the measurement values and the calculation results are not protected againstoverwriting and changing. New or changed data can be stored under an existent filename, ifan appropriate message is confirmed.

It is possible to change the txt files by means of program as well as by means of a normal texteditor. When changing measurement values in the upper part of the file one must obey, thatthe results in the lower part loose their validity. When measurement values are changed, thecorresponding calculation results should be deleted. When measurement values are changedusing the program the results will be deleted by the program. In this case, the calculationshould be repeated.

5.6 Data storageIn case files are lost, the data must be entered and stored again. No automatic backups exist.

6 Program test

6.1 Test objectivesThe test of the program has the following aims:a. To verify, that the planned functionality is implemented.b. To verify, that the program accepts and processes only valid user inputs.c. To verify, that the program provides correct and reliable calculation results. The functions

for the calculation of the emissivity (function Epsilon) and the total emissivity (functionHemEmission) should conform to literature!

6.2 Test methods

a. Test of the general functionalityFor the verification of the functionality of the program, a dynamic program test is used. First,a table with the menu items is constructed. This table also registers the nominal operation foreach menu item. Then each menu item of the program HemEmi will be used and the actualoperation is registered. It should conform to the expectations.

b. Test of plausibility checksFor the verification of the correct implementation for the plausibility checks, a dynamicprogram test is used, too. First, a table with the names of each edit field is constructed. Thistable registers the valid range of values for each field. After that, each edit field will bechecked separate for accepted and refused inputs. Those edit fields, which are not affected bytest, are filled with valid values. The accepted and refused inputs are written into the table.

45

c. Functional testFor the verification of the correct und reliable calculations, dynamic function tests are used.

Several functions of the implementation are called in a separate test environment. The resultsare compared with reference values of a computer algebra program with user-definednumerical resolution (Mathematica).

6.3 Test cases/test results

a. Test of the general functionalityAll test cases are ok. The menu items “Output / Output as Text” and “Output / Output asGraphic” are not yet implemented.

b. Test of plausibility checksThe valid ranges of values for the several fields are checked successful. All test cases are ok.

c. Functional test

Function Epsilon

The function Epsilon was checked at random points. A comparison with the results ofMathematica shows, that the deviation is smaller than 10-11.

Function HemEmission

The results of the Simpson rule (implemented in HemEmi) and the correct integration results(calculated with Mathematica) were compared at several random points. In the interval ofN = (0,1 .. 2), K = (0,1 .. 2) and for a fix, representative value of P the deviation is smallerthan 2*10-7.

Function Varianz

Some few test cases showed that the results of the function correspond with values, whichwere calculated with a pocket calculator.

Function NMSearch

The implementation differs from the Gurson paper at the following points:• Kind of initialisation for the points of the initial simplex,• Value of coefficients for the expansion,• Measure to avoid motion of the simplex into prohibited space (parameter N, K, and P

negative),• Stop criterion,• Usage the outside contraction.

The function NMSearch was embedded into a special test environment and configured in away that it could behave like described in the Gurson paper or otherwise.

It was checked, which combination of features delivered the best results. Criterion was the"standard deviation" of the calculated Epsilon values. The density the approximated valueslaid near the measurement values the merrier. In each case, 25 files with neat, low noised andhighly noised measurement values were used respectively.

46

The tests gave the follow picture:

The value of the coefficient for the expansion (bullet 2) and the stop criterion (bullet 4) haveno effect on the average quality of the approximation. The kind of initialisation (bullet 1) andthe usage of the outside contraction (bullet 5) lead to slight improvements, when configuredas in the Gurson paper. The method to lock the forbidden space for the simplex (bullet 3) isbetter configured contrary to the Gurson paper.

Thus, the configuration suggestions of the Gurson paper were all took over except the methodto lock the forbidden space.


7.1 Devices needed, hard- and softwareThe program is written for a Borland Delphi 5 Professional Compiler. It should be usablewith the Borland Delphi 5 Standard Compiler, too.

7.2 Installation instructionThe executable program HemEmi.exe can be copied to any destination. There is noinstallation procedure. If no config.ini file is available when the program starts the first time,it will be created.

47

A Appendix

A.1 Source code

A.1.1 UnitMain.pas

{ ========================================================================================== }{ Unit UnitMain}{ Die Unit enthält alle Funktionen, die direkt zum Formular fmMain gehören }{ ========================================================================================== }unit UnitMain;

interface

uses Windows, Messages, SysUtils, Classes, Graphics, Controls, Forms, Dialogs, StdCtrls, IniFiles, Menus, ComCtrls, FileCtrl, UnitDirView, UnitDateneingabe, UnitDecl, UnitFunctions, UnitRechnen, UnitStartwerte;

type TfmMain = class(TForm) MainMenu1: TMainMenu; Datei1: TMenuItem; Beenden1: TMenuItem; Pfadeinstellen1: TMenuItem; Hilfe1: TMenuItem; ber1: TMenuItem; Bearbeiten1: TMenuItem; OpenDialog1: TOpenDialog; NeueDateierzeugen1: TMenuItem; AlteDateindern1: TMenuItem; Berechnungen1: TMenuItem; StartderBerechnung1: TMenuItem; Ausgabe1: TMenuItem; Text1: TMenuItem; Grafik1: TMenuItem; SaveDialog1: TSaveDialog; procedure Beenden1Click(Sender: TObject); procedure Pfadeinstellen1Click(Sender: TObject); procedure FormCreate(Sender: TObject); procedure NeueDateierzeugen1Click(Sender: TObject); procedure AlteDateindern1Click(Sender: TObject); procedure StartderBerechnung1Click(Sender: TObject); procedure ber1Click(Sender: TObject); procedure FillIn(rDataSet: TDataRec); private { Private-Deklarationen } public { Public-Deklarationen } end;

var fmMain: TfmMain;

implementation

{$R *.DFM}

//------------------------------------------------------------------------------//Hauptfenster schließen, Programm beenden//------------------------------------------------------------------------------procedure TfmMain.Beenden1Click(Sender: TObject);begin close;end;

…

A 1.2 ...

48

User documentation HemEmi

Table of contents

1 Characteristic program data ............................................................................................................... 481.1 Program identification...................................................................................................................... 481.1.1 Program name.............................................................................................................................. 481.1.4 Current version............................................................................................................................. 481.3 Brief description of program ............................................................................................................ 481.3.1 Program tasks .............................................................................................................................. 481.3.2 Program content ........................................................................................................................... 481.9 Responsibilities................................................................................................................................ 482 Program function ................................................................................................................................ 482.2.3 Error handling............................................................................................................................... 487 Program installation............................................................................................................................ 497.1 Devices needed, hard- and software .............................................................................................. 497.2 Installation instruction...................................................................................................................... 498 Program operation.............................................................................................................................. 498.1 Operating instructions ..................................................................................................................... 498.3 Interrupt handling............................................................................................................................. 509 Application example ........................................................................................................................... 50

1 Characteristic program data


1.1.1 Program nameThe program name is HemEmi.

1.1.4 Current versionThe documentation bases on program version 1 of April 29, 2005.


1.3.1 Program tasksThe program allows to collect and evaluate the measured emissivity of a black emitter independency on angle and to calculate the total emissivity.

1.3.2 Program contentThe emissivity Epsilon, which was measured at given angles Theta, is approximated by afunction Epsilon = Epsilon (Theta, N, K, P) in order to obtain a sufficient number of gridpoints for an integration over angle Theta. After the evaluation of the parameters N, K, and Pusing an optimisation method without constraints (Nelder Mead Method), the total emissivitywill be calculated by numerical integration (Simpson Method).

1.9 ResponsibilitiesRemarks, notes and suggestions may be sent to the author, Mr. Joe Public (Section Sample ofPTB).

2 Program function

2.2.3 Error handlingAll user inputs are checked, when the input field is leaved or the input dialog is closed. Thework can be continued only, if the wrong entries will be fixed up or the interaction will becancelled.

49

During approximation, errors should not appear. Nevertheless, if errors appear, then there aredefects in RAM. The approximation will stop and the error will display. The user may repeatthe calculation after a restart of the program. He may also use other initial values for N, K,and P.


7.1 Devices needed, hard- and softwareThe program runs on PC under Windows 98/XP.

7.2 Installation instructionThe executable program HemEmi.exe can be copied. There is no installation procedure.If no config.ini file is available at first start of the program, it will create a new one.

8 Program operation

8.1 Operating instructionsThe program is started with double-click on the program name HemEmi.exe.

The program starts with an (empty) main window and a menu bar. Menu items call allfunctions of the program:

Menu item FunctionFile

Change Path Changing the working directory for the files to be stored. The selected workingdirectory is saved in the configuration file config.ini.

Exit Finishing program.Inputs

New File Entering measurement data and storing them as txt file.Change File Loading a txt file, changing and storing the measurement data.

CalculatorStart Calculation Loading a txt file and calculating the approximated function and the total

emission, storing the results in the txt file.Output

Save As Text Displaying the txt file with the measurement values and the results as text.NOT YET IMPLEMENTED. The intended display is for printing purposes,too.

Save As Graphic Displaying the measurement data and the approximated function as a graphic.NOT YET IMPLEMENTED. The intended display is for printing purposes,too.

HelpAbout Displaying the program name, version, and author.

Table 1: menu items of the program HemEmi

The data of a new measurement are entered using the menu item „Inputs / New File“. Theyare stored using a path and a filename, which are deduced from the measurement number andthe year of measurement. User can change path and filename before using them for storage.

The stored data can be changed later on using the menu item „Inputs / Change File“. If themeasurement data in the file are changed, the measurement results will be deleted. This isdone to preserve consistency between the measurement data und the calculation results.

After entering and storing the measurement data, they can be evaluated using the menu item„Calculator / Start Calculation“. The program tries to approximate the measurement data(Theta, Epsilon) by a function Epsilon = Epsilon (Theta, N, K, P). The program calculatesthose parameter values N, K, and P, which produce the smallest deviation between the

50

approximated function and the measurement values. After that, the program integrates theapproximated function Epsilon to get the total emissivity. The results of the calculationconsists of the parameter values N, K, and P, which give the best approximation, the totalemissivity Phi and it’s "standard deviation". The last value is no standard deviation in theproper meaning of the word, but it may be used to evaluate the success of the approximation.The results appear in a message window. The measurement results can be stored into theoriginal txt file.

If the approximation is not successful an appropriate warning appears. In this case, acorresponding message appears in the result window and the calculation may be rerun withother initial values for parameters N, K, and P.

It is planned, but up to now not implemented, to display the txt file with the measurement dataund calculation results as text as well as graphic. These displays will be used for a printeroutput, too.

User inputs of the program:

Input Type Valid range May beempty?

Number of measurement integer, 3 digits 001..999 noDate of measurement date, 3x2 digits valid date noTime of measurement time, 2x2 digits valid time noTemperature of specimen in ºC integer, float - noTemperature of receiver in ºC integer, float - noLabelling of specimen text length <= 255 characters yesSubstrate text length <= 255 characters yesPlating text length <= 255 characters yesComment text - yesMeasurement angle in º integer, float 0.. 90 noMeasured emissivity float 0.. 1 noInitial value for N integer, float > 0, <= 10 noInitial value for K integer, float > 0, <= 10 noInitial value for P integer, float > 0, <= 2 no

Table 2: user inputs of the program HemEmiTo decimal separator for floating point numbers depends on Windows registration entries.

8.3 Interrupt handlingThe program can be interrupted using the Windows Task Manager. If the results are not yetstored, they will be lost in this case. After program stop, the results in the file may beincomplete. The program run should be repeated for the current file.

9 Application exampleThe program is started by calling the file HemEmi.exe

51

Figure 1: HemEmi – Menu item „Inputs / New File“

New data are entered using the menu item „Inputs / New File“. This opens a dialog, which theuser allows to make his inputs.

Figure 2: HemEmi – Dialog „Data Input“

The data will be stored in a file by selecting the button „OK“.

52

Figure 3: HemEmi – Dialog „Save As“

The user is informed by a message window, that his data are saved correctly.

Figure 4: HemEmi – Message window

After that, the dialog „Data Input“ has to be closed using the button „Close“. The calculationis initiated by selecting the menu item „Calculator / Start Calculation“:

Figure 5: HemEmi – Menu item „Calculator / Start Calculation“

The initial values for the parameters N, K, and P must be specified, after the user has selecteda file:

53

Figure 6: HemEmi – Dialog „Open“

Figure 7: HemEmi –Dialog „Initial Values“

The calculation will be started after selecting the button „Start“. After that, the results appearin a message window:

Figure 8: HemEmi – Results

In the present example, the parameter K is very small. The user is informed about that andmay decide whether to store the results or not.

Figure 9: HemEmi – Question

If he answers the question with „Yes“, the results will be stored in the original file. After this,the user has the chance to repeat the calculation with new initial values for N, K, and P.

54

Figure 10: HemEmi – Message window

The calculation routine will be left, if the button „Close“ is selected.

The program is finished selecting the menu item „File / Exit“:

Figure 11: HemEmi – Menu item „File / Exit“

From the following, file 001.txt:Data of measurement 001-05Date: 9.5.2005Time: 07:53-Temperature of specimen: 125 °CTemperature of receiver: 25 °CLabelling of specimen: edLabellingSubstrate: edSubstratePlating: edPlating-Comment:memoComment-Measurement values:5150,90010300,90110400,90120500,91120600,91230

the new file 001.txt is created in the same directory:Data of measurement 001-05Date: 9.5.2005Time: 07:53-Temperature of specimen: 125 °CTemperature of receiver: 25 °CLabelling of specimen: edLabellingSubstrate: edSubstratePlating: edPlating-

55

Comment:memoComment

-Measurement values:5150,90010300,90110400,90120500,91120600,91230

-Measured values:Parameter N: 1Parameter K: 1,732E-5Parameter P: 0,0988150,9012300,9012400,9012500,9012600,9012Phi: 1'Std.deviation': 0,01498

Documents

Guideline for Software Documentation - Springerextras.springer.com/2009/978-0-8176-4592-2/A.1.2... · operating systems or database system software thus is not an object of this guideline