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 of
Germany (V-Model XT)
Authors
:
N. Greif
e-mail: Norbert.Greif@ptb.de
D. Saborrosch
e-mail: Doris.Saborrosch@ptb.de
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
2
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-todate, 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.
3
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).
4
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.
5
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 processoriented 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.
6
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, productspecific 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 Coordination 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).
7
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 wordprocessing 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."
8
Content of the software documentation
Item
No.
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 program
unit.
1.1.3
Name of variant
Addendum to program name to identify several
program variants with different contents.
1.1.4
Current version
Addendum to the program name or to the name of the
variant 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 program
version.
1.2
Descriptors
Statement of keywords/search words for the program.
9
Content of the software documentation
Item
No.
Title
Description
1.3
Brief description of
program
1.3.1
Program tasks
Brief application-related description of the task to be
solved by the program.
1.3.2
Program content
Brief description of the methods, theories and
computation methods used to solve the task.
1.3.3
Regulations
Reference to important laws, standards, and guidelines
to be complied with.
1.3.4
Special features
Description of
- technical prerequisites or limitations,
- technical application limits (e.g. maximum response
time)
- 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), device
requirements, 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 the
program runs.
10
Content of the software documentation
Item
No.
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 libraries
needed.
1.7
Data organisation
List of all files used (name, purpose, access type,
storage space needed, application limits). Details of
use of a data base operating system.
1.8
Scope of documentation
List of documentation parts available (system
documentation, user documentation, program
development documentation, project management
documentation).
1.9
Responsibilities
Exact details of program author, responsibilities with
respect 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 / boundary conditions / literature
Rough description of the models/methods applied (on
which basis is the task solved?).
11
Content of the software documentation
Item
No.
Title
Description
2.1.3
Units of measurement
List of the physical quantities used, including their
units of measurement.
2.1.4
Regulations
Complete list of the laws, standards and guidelines to
be observed, including list of references. Deviations
are to be noted. Information-technological and
application-related processing regulations.
2.2
Solving of tasks
2.2.1
Hierarchy of functions
Hierarchical structure of tasks and sub-tasks (related to
program structure).
2.2.2
Methods / algorithms
Exact description of solving methods with application
limits (how is the task solved?).
Description of plausibility checks.
2.2.3
Error handling
Statement of the error messages envisaged and of the
measures to be taken.
3
Program layout
3.1
Program modules
Complete list of all sub-programs, procedures,
modules, classes, methods, events, rules, global
variables and constants.
3.2
Program structure
Survey of structure including interfaces, e.g.
graphically as call hierarchy or Jackson diagram
and/or as class hierarchy.
12
Content of the software documentation
Item
No.
Title
Description
3.3
Source code
3.4
Compiling and linking
4
Program flow
4.1
Program flow description
4.2
Use case analysis
4.3
Interaction flow
Exact representation of the interaction flow (representation 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).
List of all steps to be taken to generate an executable
program (e.g. Makefile).
Representation of the internal program flow with cross
references to the source code (program flow chart to
DIN 66001, structure chart to DIN 66261).
Presentation of the external view on system, usage of
UML diagrams (Unified Modeling Language)
13
Content of the software documentation
Item
No.
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 with
instance variables),
- of data which remain to be entered (via keyboards,
input units).
Details of access methods, standard initialisations,
permissible input areas and maximum data quantities
to 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 (entityrelationship model, object-oriented data model,
relation schemes: tables with attributes), name and
version 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 manipulation
protection.
5.6
Data storage
Details of data archiving, safeguarding methods
(retention periods, expiry dates, backup cycles, data
reconstruction, recovery procedures).
14
Content of the software documentation
Item
No.
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 (test
programs, test environment).
6.3
Test cases / test results
Statement of the test data and of the expected and
actual test results. Test coverage achieved.
Benchmarks.
7
Program installation
7.1
Devices needed, hard- and
software
7.2
Installation instructions
7.3
Special features
Precise description of processors, data and process
interfaces, computer networking, data transmission.
Details of device requirements and software needed.
Details of technical restrictions, data protection,
configuration. Hints for set-up and adaptation.
15
Content of the software documentation
Item
No.
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 data
protection and for restarting.
9
Application example
Description of an application example including all
program inputs/outputs.
16
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.
17
Checklist for software documentation
Item Documentation
No.
item
1
Characteristic program data
1.1
Program identification
Necessary?
Weighting
Date of
completion
Remarks
References
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
18
Checklist for software documentation
Item Documentation
No.
item
1.4
Devices needed
1.5
Program size
1.6
Program requirements
Necessary?
Weighting
Date of
completion
Remarks
References
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
19
Checklist for software documentation
Item Documentation
No. item
Necessary?
Weighting
Date of
completion
Remarks
References
2.1.2 Theoretical bases / boundary
conditions / literature
2.1.3 Units of measurement
2.1.4 Regulations
2.2
Solving of tasks
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
20
Checklist for software documentation
Item Documentation
No. item
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
Necessary?
Weighting
Date of
completion
Remarks
References
21
Checklist for software documentation
Item Documentation
No. item
6
Program test
6.1
Test objectives
6.2
Test methods
6.3
Test cases / test results
7
Program installation
7.1
Devices needed, hard- and
software
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
Necessary?
Weighting
Date of
completion
Remarks
References
22
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
Item
No.
Documentation
item
Necessary?
Weighting
Date of
completion
s-docu
u-docu
Remarks
References
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
-----
-----
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
-----
-----
-----
Up to now there
is no release
No relevant
regulations
23
Checklist for software documentation HemEmi
Item
No.
Documentation
Item
Necessary?
Weighting
Date of
completion
s-docu
u-docu
Remarks
References
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
-----
-----
-----
1.7.
Data organisation
yes
-----
23-04-2005
1.8.
Scope of documentation
yes
-----
22-04-2005
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 / boundary
conditions / literature
yes
-----
24-04-2005
References to
literature
2.1.3.
Units of measurement
very brief
-----
24-04-2005
N, K, and P
have no units
2.1.4.
Regulations
-----
-----
-----
No relevant
regulations
2.2.
Solving of tasks
yes
-----
24-04-2005
Other programs
are not necessary
User documentation /
program development
documentation
24
Checklist for software documentation HemEmi
Item
No.
Documentation
item
Necessary?
Weighting
Date of
completion
s-docu
u-docu
Remarks
References
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 source
codes?
-----
02-05-2005
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
IMPORTANT !!!
-----
24-04-2005
5.1.
Input data
In all detail
-----
24-04-2005
5.2.
Output data
In all detail
-----
24-04-2005
Source code as
appendix
25
Checklist for software documentation HemEmi
Item
No.
Documentation
item
Necessary?
Weighting
Date of
completion
s-docu
u-docu
Remarks
References
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 with
literature
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- and
software
Very brief
Very brief
29-04-2005
Not required
7.2.
Installation instructions
Short
information
Short
information
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
-----
-----
-----
8.3.
Interrupt handling
-----
yes
09-05-2005
9.
Application example
-----
yes
09-05-2005
User interface
by interactions
Use first test data file
26
System documentation HemEmi
Table of contents
1 Program specification......................................................................................................................... 28
1.1 Program identification...................................................................................................................... 28
1.1.1 Program name.............................................................................................................................. 28
1.1.4 Current version ............................................................................................................................. 28
1.1.5 Date of release ............................................................................................................................. 28
1.2 Descriptors ...................................................................................................................................... 28
1.3 Brief description of program ............................................................................................................ 28
1.3.1 Program tasks .............................................................................................................................. 28
1.3.2 Program content ........................................................................................................................... 28
1.3.4 Special features............................................................................................................................ 28
1.5 Program size ................................................................................................................................... 28
1.6 Program requirements..................................................................................................................... 28
1.6.1 Operating systems ....................................................................................................................... 28
1.6.2 Programming languages/compiler ............................................................................................... 28
1.7 Data organisation ............................................................................................................................ 29
1.8 Scope of documentation.................................................................................................................. 29
1.9 Responsibilities................................................................................................................................ 29
2 Program function ................................................................................................................................ 29
2.1 Tasks ............................................................................................................................................... 29
2.1.1 Description of tasks ...................................................................................................................... 29
2.1.2 Theoretical bases / boundary conditions / literature .................................................................... 29
2.1.3 Units of measurement .................................................................................................................. 29
2.2 Solving of tasks ............................................................................................................................... 30
2.2.1 Hierarchy of functions................................................................................................................... 30
2.2.2 Methods / algorithms .................................................................................................................... 30
2.2.3 Error handling ............................................................................................................................... 34
3 Program layout ................................................................................................................................... 35
3.1 Program modules ............................................................................................................................ 35
3.2 Program structure............................................................................................................................ 35
3.3 Source code .................................................................................................................................... 36
3.4 Compiling and linking ...................................................................................................................... 36
4 Program flow ...................................................................................................................................... 37
4.1 Program flow description................................................................................................................. 37
4.2 Use case analysis ........................................................................................................................... 37
4.3 Interaction flow ................................................................................................................................ 38
4.4 Description of dialogs ...................................................................................................................... 40
4.5 Data flow description ....................................................................................................................... 42
5 Data organisation ............................................................................................................................... 42
5.1 Input data......................................................................................................................................... 42
5.2 Output data...................................................................................................................................... 43
5.5 Data protection ................................................................................................................................ 44
5.6 Data storage .................................................................................................................................... 44
6 Program test ....................................................................................................................................... 44
6.1 Test objectives................................................................................................................................. 44
6.2 Test methods................................................................................................................................... 44
6.3 Test cases/test results..................................................................................................................... 45
7 Program installation............................................................................................................................ 46
7.1 Devices needed, hard- and software .............................................................................................. 46
7.2 Installation instruction...................................................................................................................... 46
A Appendix ............................................................................................................................................ 47
A.1 Source code .................................................................................................................................... 47
A.1.1 UnitMain.pas ................................................................................................................................ 47
A 1.2 ... .................................................................................................................................................. 47
27
1 Program specification
1.1 Program identification
1.1.1 Program name
The 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 version
The documentation bases on program version 1 of April 29, 2005.
1.1.5 Date of release
The current version is not released yet, because the program is still incomplete. The output
routines are not yet implemented.
1.2 Descriptors
Black emitter, high temperature radiator, emissivity, measurement data logging and
evaluation, Nelder Mead Method, non-linear optimisation, approximation.
1.3 Brief description of program
1.3.1 Program tasks
The program allows to collect and evaluate the measured emissivity of a black emitter in
dependency on angle and to calculate the total emissivity.
1.3.2 Program content
The emissivity Epsilon, which was measured at given angles Theta, is approximated by a
function Epsilon = Epsilon (Theta, N, K, P) in order to obtain a sufficient number of grid
points for an integration over angle Theta. After the evaluation of the parameters N, K, and P
using an optimisation method without constraints (Nelder Mead Method), the total emissivity
will be calculated by numerical integration (Simpson Method).
1.3.4 Special features
10.000 Calculations need about 20 up to 40 minutes at a clock rate of 800 MHz. This
corresponds to a calculation time for one calculation of about 0,1 up to 0,25 seconds.
1.5 Program size
The executable file has a size of approx. 470 Kbytes.
1.6 Program requirements
1.6.1 Operating systems
The program runs on PC under Windows 98/XP.
1.6.2 Programming languages/compiler
The program is written for a Delphi (Borland Delphi 5 Professional) compiler. It should be
usable with a Borland Delphi 5 Standard Compiler, too.
28
1.7 Data organisation
The measured data are entered by the user and saved into a txt file. After evaluation, the
calculated data will be appended to the txt file. Filename and directory for the storage
correspond to the year of the measurement and the number of measurement. The user may
change them.
Beside the txt file with the measurement data and the calculation results, there exists a
configuration file config.ini.
1.8 Scope of documentation
The documentation for the HemEmi program consists of the system documentation here
available and the user documentation.
1.9 Responsibilities
Remarks, notes and suggestions may be sent to the author, Mr. Joe Public (Section Sample of
PTB). Programming was done using the code example of Adam P. Gurson1.
2 Program function
2.1 Tasks
2.1.1 Description of tasks
The total emissivity of a high temperature radiator or black emitter has to be determined. It is
gained through the integration of the emissivity Epsilon (Theta) over the angle Theta. There
are 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 Report
96-4-07, Computing Sciences Research Center Bell Laboratories; Murray Hill, New
Jersey 07974, Revised Version, May 1, 1997
2.1.3 Units of measurement
The 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.
29
2.2 Solving of tasks
2.2.1 Hierarchy of functions
Program to register and evaluate the measured
emission values of a black emitter
Execute
calculation
Read data
Create new data
Change old data
Display results
As text
(Not implemented)
As graphic
(Not implemented)
Figure 1: Functions hierarchy
2.2.2 Methods / algorithms
The 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). An
optimisation with three parameters provides better approximation for the measurement
values, 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 P
Repeat the calculation
If the “standard deviation” is very high (> 5 % when using three parameters) or if the
parameter K is very small (< 0.001 when using three parameters), the optimisation was
probably 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 (Procedure
NMSearch). See below.
Calculate the emission value Epsilon (Theta, N, K, P) for each angle, for which a measured
value exists, and assign the “standard deviation” (Functions Epsilon and Varianz).
Calculate of the total emissivity Phi (Function HemEmission).
30
Procedure NMSearch
The aim function of the optimisation is the difference between the measured and the
calculated 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 and
the 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 Mead
Method 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 a
tetrahedron (= simplex)2.
For each vertex of the tetrahedron the value of the aim function is calculated, i.e. the deviation
between calculated and measured values. The vertex with the greatest value (greatest
deviation) is replaced by a new point. It forms a new tetrahedron, which is displaced in
direction on the (local) minimum. In the further optimisation steps the tetrahedron moves
through the space until a certain stop criterion applies. The motion of the tetrahedron is
roughly 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 the
remaining points. The coefficient Rho = 1 is used.
• Expansion point
The new point is calculated like the reflection point, but is shifted away after reflection
(coefficient Chi = 2). The tetrahedron enlarges.
• Contraction point
The new point is calculated like the reflection point, but is shifted to the centroid after
reflection (coefficient Gamma = ½). The tetrahedron gets smaller.
• Shrinking
All points, excepting the best, are displaced in direction of the best point (coefficient
Sigma = ½ ). The tetrahedron gets extremely smaller.
2
When two parameters are used instead of three, three points (N, K) form a triangle. This triangle is
moved on the surface built-up by the function Abweichung(N, K) until a minimum is reached.
31
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) and
Sigma (for shrinking). The standard values Rho = 1, Chi = 2, Gamma = 0,5 and Sigma = 0,5
are used. Procedure NMSearch.Init.
Initialise the counter NumberOfCalls, which counts the calls of the aim function. Procedure
NMSearch.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 the
tetrahedron is directly built the tuple (N, K, P). The other three vertices are copies of the
first, whereas for each vertex one parameter is varied (increased by around 40 %). Procedure
NMSearch.Init.
Calculation of the aim function (the deviation) for each vertex of the tetrahedron. Procedure
NMSearch.Init and function Abweichung.
Repeat until stop (Procedure NMSearch.StopCalculation):
Find out the worst (greatest deviation), the second worst and the best point of the
tetrahedron. Procedure NMSearch.FindMinMaxIndices.
Calculate the reflection point und its function value (deviation). Procedure
NMSearch.CalculateReflectionPoint.
If reflection point < best point of the body, then
Calculate the expansion point and its function value. Procedure
NMSearch.CalculateExpansionPoint.
If expansion point < reflection point
Replace the worst point of the tetrahedron with the expansion point.
Procedure NMSearch.ReplaceSimplexPoint.
Else
Replace the worst point of the tetrahedron by the reflection point.
If reflection point >= best point and reflection point < second worst point, then
Replace the worst point by the reflection point.
If reflection point > worst point, then
Calculate the inside contraction point. Procedure
NMSearch.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. Procedure
NMSearch.ShrinkSimplex.
Else
Calculate the outside contraction point. Procedure
NMSearch.CalculateOutsideContractionPoint.
If outside contraction point <= reflection point
Replace the worst point by the outside contraction point
Else
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.
32
The
loop
of
optimisation
terminates
for
three
reasons
(Procedure
NMSearch.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 much
earliest.
• An error appears during the calculations of Epsilon or the deviation, shown by the error
variable 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 the
case, if one of the vertices would be a linear combination of the other points. In that case, the
optimisation 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 is
calculated:
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 by
least squares method – as in statistics. Instead, it is found by minimising the sum of
deviations.
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 numerical
integration using the Simpson method. The function
F (Theta, N, K, P) =
π
-- *
90
Epsilon (Theta, N, K, P)
------------------------------ * sin(Theta) cos(Theta)
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)
33
and BB1 = 2 √ (Expression4) * cos(Theta)
and AA2 = Expression3 + sin2(Theta) * tan2(Theta)
and BB2 = 2 √ (Expression4) * sin(Theta) * tan(Theta)
with
and
and
and
Expression1 = N2 – K2 – sin2(Theta)
Expression2 = 4 N2 K2
Expression3 = √ (Expression12 + Expression2)
Expression4 = 0,5 * (Expression3 + Expression1).
2.2.3 Error handling
All users’ inputs are checked immediately after leaving the input field or closing the input
dialog. The work may be continued only, if the wrong inputs are fixed up or the dialog is
cancelled.
During approximation, errors should not appear. Nevertheless, if errors appear, there will be
defects in RAM. The approximation stops and the error is displayed. The user may repeat the
calculation after a restart of the program. He may also use other initial values for N, K, and P.
Error no.
101
102
201
401
402
501
502
503
601
701
901
902
903
904
905
Reason
Call of the function Epsilon with invalid angles (angle < 0degrees or angle >
90degrees).
Call of the function Epsilon with invalid parameter values (one of the
parameters N, K or P is less than 0).
Call of the function HemEmission with invalid parameter values (one of the
parameters N, K or P is less than 0).
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 not
distinct.
Call of the function NMSearch.FindMinMaxIndices with too little vertices.
The number of vertices is less than 3. The second worst point, the worst point
and the best point are not distinct.
Call of the function NMSearch with insufficient number of parameters (< 2).
Call of the function NMSearch with invalid parameter values (one of the
parameters N, K or P is less than 0).
Call of the function NMSearch with insufficient number of data. The number
of data must be at least as big as measurement values as parameters
determines.
Call of the function NMSearch.ReplaceSimplexPoint with wrong index. The
point of the simplex, which should be replaced, does not exist.
The function NMSearch has calculated a wrong reflection point. It is neither
better than the best point of the simplex nor worse than the worst nor is it
located in between.
Call of the function Calculate with wrong number of parameters. The
numbers of parameter may be only 2 or 3.
Call of the function Calculate with too few data. The number of data must be
at least as big as measurement values as parameters determines.
Call of the function Calculate with too much data. At maximum 50 pairs of
measurement values are handled.
Call of the function Calculate with empty pairs of measurement values. The
first two measured angles are not assigned.
Call of the function Calculate with empty pairs of measurement values. The
first two emissivities are not assigned.
Table 1: Error handling
34
3 Program layout
3.1 Program modules
Global variables and types:
TMesRec
Record for a pair or tuple of measurement values. Comprises one real
variable for the angle, one for the measured emissivity Emmi and one for
the calculated emissivity BerechEmmi. The calculated emissivity is
assigned 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 of
receiver, labelling of specimen, labelling of substrate, plating, and comment,
one string for the number of measurement, one variable for the date and one
for the time of the measurement, one integer variable for the number of
pairs/tuples of measurement values, one array of TMesRec for the
pairs/tuples of measurement values, three real variables for the optimised
parameters N, K, and P, and two real variables for the total emissivity and
its “standard deviation”.
TParamRec
Record for the transfer of the three parameters N, K, and P to several
functions.
WorkingDir
Global variable for the last directory used to load or save data.
WorkingSubDir Subdirectory to WorkingDir, it contains the directory of the current year
ORDyyyy\Files.
TXTFileName
Global variable, which contains the read filename for the last calculation.
3.2 Program structure
Module
UnitMain.pas
UnitDirView.pas
UnitFunctions.pas
UnitDateneingabe.pas
UnitDecl.pas
UnitRechnen.pas
UnitStartwerte.pas
Content
Main window fmMain with menu bar, reads the config.ini, displays the information
window.
Dialog fmDirView with displaying and changing the working directory.
Library of help functions: Loading and Saving of txt-files, string handling and other.
Dialog fmDateneingabe with entering, checking and saving of the data, which
belong to a measurement.
Definition of types and global variables.
Calculate functions for approximation, the calculation of the “standard deviation”
and the total emission.
Dialog fmStartwerte for decision between 2 or 3 parameters and entering of initial
values.
Table 2: Program structure
35
fmMain.StartderBerechnung1Click
Ok-Button:
fmStartwerte
fmStartwerte.btnYesClick
StarteBerechnung
ReadDataFromTXTFile
SaveDataToTXTFile
Calculate
NMSearch
Init
CalculateCentroid
CalculateRefl.Pt.
Calculate...
HemEmission
Varianz
StopCalculation
FindMinMaxIndices
ReplaceSimplexPoint
Abweichung
Epsilon
Figure 2: Calling hierarchy “Calculator / Start Calculation”
3.3 Source code
See Appendix
3.4 Compiling and linking
Only the project file HemEmi.dpr must be opened for further development. Compiling and
Linking are done using the appropriate menu items.
36
4 Program flow
4.1 Program flow description
Entering the measurement
data by user
[Change measurement data]
[No change
measurement data]
Changing the measurement
data by user
Calculation
[No successful approximation]
[Successful
approximation]
Changing the initial values
for the parameters
Output of results
Figure 3: Program flow description
4.2 Use case analysis
Creating new files:
- Measurement data from users
+ Entering measurement data
+ Saving measurement data
HemEmi
Modifying old files:
- Measurement data from users
+ Displaying old measurement data
+ Entering new measurement data
+ Saving measurement data
Starting calculation
- Measurement data
- Parameter values
- Algorithm
+ Reading in measurement data
+ Applying algorithm
+ Storing results
Output
- Measurement data
- Results
+ Displaying on monitor
user
user
Changing Path
- Files of configuration
+ Displaying files of configuration
+ Changing data of configuration
+ Saving data of configuration
Figure 4: Use case diagram
37
4.3 Interaction flow
Inputs / New File
2
Entering data record
Close button
pressed
[Ok button pressed]
Checking data record
[No complete data]
1
[Complete data]
No plausible data]
1
[Plausible data]
Entering filename
Cancel button
pressed
[Save button pressed]
Checking filename
[File does not exist]
[File exists]
[Do not overwrite file]
1
[Overwrite file]
Saving file
1
Checking data record
[Data not changed]
[Data changed]
[Do not save data]
[Save data]
2
Figure 5: Activity diagram – “Inputs / New File”
38
Inputs / Change File
Entering filename
Cancel button
pressed
[Open button pressed]
Checking filename
[File does not exist]
[File exists]
Reading data record
“New File”
Figure 6: Activity diagram – “Inputs / Change File”
Calculator / Start Calculation
Dateiname
eingeben
Entering filename
Cancel button
pressed
[Open button pressed]
Checking filename
[File does not exist]
[File exists]
Reading data record
[Wrong data record]
[Right data record]
Entering initial value
Close button
pressed
[Start button pressed]
Calculation
Displaying
data record/results
[Results not plausible]
[Plausible results]
Saving
data record/results
Figure 7: activity diagram – “Calculator / Start Calculation”
39
4.4 Description of dialogs
The two important dialogs are described in the follows. The other dialogs are abstract and are
not 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
Valid range
Remarks
3 digits
Default
value
<blank>
Measurement
number
needed
integer
001 - 999
date
3x2
digits
current
date
day:
01- 31
month:
01 - 12
year:
00 - 99
needed
time
2x2
digits
current
system
time
needed
-
<blank>
-
<blank>
-
Temperature of receiver
optional
integer,
float
integer,
float
text
hour:
00 - 23
minute:
00 - 59
-
Number of measurement It
is using by creating a
filename.
Date of measurement
It must be a valid date.
Do not enter points. The
21st century is attached to
the 2-digit year
specification 00-54, the
20th century to the 2-digit
specification 55-99.
Time of measurement
It must be a valid time. Do
not enter colons.
Date
needed
Time
Temperature of
specimen in °C
Temperature of
receiver in °C
Labelling of
specimen
Substrate
<blank>
-
Notation of specimen
optional
text
max 255
characters
max 255
characters
<blank>
-
Notation of substrate
needed
Temperature of specimen
40
Field
Kind
Type
Length
Default
value
<blank>
Valid range
Remarks
Plating
optional
text
Comment
Angle in °
(line 1 – 3)
optional
needed
text
integer,
float
max 255
characters
-
-
Notation of plating
<blank>
<blank>
[0, 90]
<blank>
[0, 90]
Degree of
needed
integer,
<blank>
emissivity
float
(line 1 – 3)
Degree of
optional
float
<blank>
emissivity
(line 4 – 50)
Table 3: Specification of the several fields in dialog “Data Input”
[0, 1]
Arbitrary, multiline text.
Angle, at which emissivity
was measured. It must be
entered in º (degree).
Angle, at which emissivity
was measured. It must be
entered in º (degree).
Measured emissivity
Angle in °
(line 4 – 50)
optional
float
[0, 1]
Measured emissivity
-
Three pairs of measurement values must be entered at least. 50 pairs can be entered at
maximum.
Button
Active
Condition / Description
Ok
yes
Saving the current data record
Close
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”
Field
Kind
Type
Length
Valid range
Remarks
-
Default
value
10,0
NStart
needed
integer,
float
(0, 10]
integer,
float
-
10,0
(0, 10]
integer,
float
-
0,5
(0, 2]
Initial value for N.
Values ≥ 1,5 are
favourable.
Initial value for K.
Values ≥ 1,5 are
favourable.
Initial value for P.
A value between 0,2 and 1
is favourable.
KStart
needed
PStart
needed
Table 5: Values of the particularly array element in dialog “Initial values”
41
Checkboxes
Determine offset parameter
Active
yes
Condition / Description
If setting the switch, the calculation of the parameters N, K,
and P will be done, otherwise only the parameters N and K
are calculated.
Table 6: Description of the checkboxes in dialog “Initial values”
Button
Active
Condition / Description
Start
yes
Starting the calculation
Close
yes
Closing the dialog
Table 7: Description of the buttons in dialog “Initial values”
4.5 Data flow description
Output to the users
User inputs
Program
Files
Figure 10: SA diagram level 0
Measurement data
from user
Creating
new file
Measurement data
and result files
Changing
old file
Starting
calculation
Output
Config file
Output results
to user
Changing
path
Figure 11: SA diagram level 1
5 Data organisation
5.1 Input data
For each measurement, the user must enter some general data, which are not used for the
calculation, and the pairs of measurement values (Thetai, EpsMessi). Details of the user inputs
can be seen in the table 3.
Besides these inputs for the txt files, the user can also enter new initial values for the
parameters N, K, and P, which will be optimised.
42
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 favourable
Table 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> oC
Temperature of receiver: <Temperature of receiver> oC
Labelling 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 data
The calculation results are registered in the file of input data, too. This is done as soon as the
calculation is finished. The text file can be displayed and changed with an editor. When the
measurement values in the upper part of the file are changed, the results in the lower part
loose their validity. If these changes are made with the help of program HemEmi, the results
are deleted. If the changes are made with the help of an editor, the user should delete the
results to retain consistency.
If calculation was done for a certain file with input data, a section is appended after the
measurement 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>
43
The file config.ini contains the global settings of the program. At the first start of the
program, this file is created, and after that, it is updated casually. Now, only the working
directory is contained in the config.ini-file. User may change this directory by using the menu
item “Files / Change Path”.
<bof>
[WorkingDir]
Dir=<working directory>
<eof>
5.5 Data protection
The txt files with the measurement values and the calculation results are not protected against
overwriting and changing. New or changed data can be stored under an existent filename, if
an appropriate message is confirmed.
It is possible to change the txt files by means of program as well as by means of a normal text
editor. When changing measurement values in the upper part of the file one must obey, that
the results in the lower part loose their validity. When measurement values are changed, the
corresponding calculation results should be deleted. When measurement values are changed
using the program the results will be deleted by the program. In this case, the calculation
should be repeated.
5.6 Data storage
In case files are lost, the data must be entered and stored again. No automatic backups exist.
6 Program test
6.1 Test objectives
The 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 (function
HemEmission) should conform to literature!
6.2 Test methods
a. Test of the general functionality
For 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 for
each menu item. Then each menu item of the program HemEmi will be used and the actual
operation is registered. It should conform to the expectations.
b. Test of plausibility checks
For the verification of the correct implementation for the plausibility checks, a dynamic
program test is used, too. First, a table with the names of each edit field is constructed. This
table registers the valid range of values for each field. After that, each edit field will be
checked separate for accepted and refused inputs. Those edit fields, which are not affected by
test, are filled with valid values. The accepted and refused inputs are written into the table.
44
c. Functional test
For 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 results
are compared with reference values of a computer algebra program with user-defined
numerical resolution (Mathematica).
6.3 Test cases/test results
a. Test of the general functionality
All test cases are ok. The menu items “Output / Output as Text” and “Output / Output as
Graphic” are not yet implemented.
b. Test of plausibility checks
The 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 of
Mathematica 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 of
N = (0,1 .. 2), K = (0,1 .. 2) and for a fix, representative value of P the deviation is smaller
than 2*10-7.
Function Varianz
Some few test cases showed that the results of the function correspond with values, which
were 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 a
way 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 values
laid near the measurement values the merrier. In each case, 25 files with neat, low noised and
highly noised measurement values were used respectively.
45
The tests gave the follow picture:
The value of the coefficient for the expansion (bullet 2) and the stop criterion (bullet 4) have
no effect on the average quality of the approximation. The kind of initialisation (bullet 1) and
the usage of the outside contraction (bullet 5) lead to slight improvements, when configured
as in the Gurson paper. The method to lock the forbidden space for the simplex (bullet 3) is
better configured contrary to the Gurson paper.
Thus, the configuration suggestions of the Gurson paper were all took over except the method
to lock the forbidden space.
7 Program installation
7.1 Devices needed, hard- and software
The program is written for a Borland Delphi 5 Professional Compiler. It should be usable
with the Borland Delphi 5 Standard Compiler, too.
7.2 Installation instruction
The executable program HemEmi.exe can be copied to any destination. There is no
installation procedure. If no config.ini file is available when the program starts the first time,
it will be created.
46
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 ...
47
User documentation HemEmi
Table of contents
1 Characteristic program data ............................................................................................................... 48
1.1 Program identification...................................................................................................................... 48
1.1.1 Program name.............................................................................................................................. 48
1.1.4 Current version ............................................................................................................................. 48
1.3 Brief description of program ............................................................................................................ 48
1.3.1 Program tasks .............................................................................................................................. 48
1.3.2 Program content ........................................................................................................................... 48
1.9 Responsibilities................................................................................................................................ 48
2 Program function ................................................................................................................................ 48
2.2.3 Error handling ............................................................................................................................... 48
7 Program installation............................................................................................................................ 49
7.1 Devices needed, hard- and software .............................................................................................. 49
7.2 Installation instruction...................................................................................................................... 49
8 Program operation.............................................................................................................................. 49
8.1 Operating instructions ..................................................................................................................... 49
8.3 Interrupt handling............................................................................................................................. 50
9 Application example ........................................................................................................................... 50
1 Characteristic program data
1.1 Program identification
1.1.1 Program name
The program name is HemEmi.
1.1.4 Current version
The documentation bases on program version 1 of April 29, 2005.
1.3 Brief description of program
1.3.1 Program tasks
The program allows to collect and evaluate the measured emissivity of a black emitter in
dependency on angle and to calculate the total emissivity.
1.3.2 Program content
The emissivity Epsilon, which was measured at given angles Theta, is approximated by a
function Epsilon = Epsilon (Theta, N, K, P) in order to obtain a sufficient number of grid
points for an integration over angle Theta. After the evaluation of the parameters N, K, and P
using an optimisation method without constraints (Nelder Mead Method), the total emissivity
will be calculated by numerical integration (Simpson Method).
1.9 Responsibilities
Remarks, notes and suggestions may be sent to the author, Mr. Joe Public (Section Sample of
PTB).
2 Program function
2.2.3 Error handling
All user inputs are checked, when the input field is leaved or the input dialog is closed. The
work can be continued only, if the wrong entries will be fixed up or the interaction will be
cancelled.
48
During approximation, errors should not appear. Nevertheless, if errors appear, then there are
defects in RAM. The approximation will stop and the error will display. The user may repeat
the calculation after a restart of the program. He may also use other initial values for N, K,
and P.
7 Program installation
7.1 Devices needed, hard- and software
The program runs on PC under Windows 98/XP.
7.2 Installation instruction
The 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 instructions
The 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 all
functions of the program:
Menu item
File
Change Path
Exit
Inputs
New File
Change File
Calculator
Start Calculation
Output
Save As Text
Save As Graphic
Function
Changing the working directory for the files to be stored. The selected working
directory is saved in the configuration file config.ini.
Finishing program.
Entering measurement data and storing them as txt file.
Loading a txt file, changing and storing the measurement data.
Loading a txt file and calculating the approximated function and the total
emission, storing the results in the txt file.
Displaying the txt file with the measurement values and the results as text.
NOT YET IMPLEMENTED. The intended display is for printing purposes,
too.
Displaying the measurement data and the approximated function as a graphic.
NOT YET IMPLEMENTED. The intended display is for printing purposes,
too.
Help
About
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“. They
are stored using a path and a filename, which are deduced from the measurement number and
the 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 the
measurement data in the file are changed, the measurement results will be deleted. This is
done 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 calculates
those parameter values N, K, and P, which produce the smallest deviation between the
49
approximated function and the measurement values. After that, the program integrates the
approximated function Epsilon to get the total emissivity. The results of the calculation
consists of the parameter values N, K, and P, which give the best approximation, the total
emissivity Phi and it’s "standard deviation". The last value is no standard deviation in the
proper 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 the
original txt file.
If the approximation is not successful an appropriate warning appears. In this case, a
corresponding message appears in the result window and the calculation may be rerun with
other 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 data
und calculation results as text as well as graphic. These displays will be used for a printer
output, too.
User inputs of the program:
Input
Number of measurement
Date of measurement
Time of measurement
Temperature of specimen in ºC
Temperature of receiver in ºC
Labelling of specimen
Substrate
Plating
Comment
Measurement angle in º
Measured emissivity
Initial value for N
Initial value for K
Initial value for P
Table 2: user inputs of the program HemEmi
Type
Valid range
integer, 3 digits
date, 3x2 digits
time, 2x2 digits
integer, float
integer, float
text
text
text
text
integer, float
float
integer, float
integer, float
integer, float
001..999
valid date
valid time
length <= 255 characters
length <= 255 characters
length <= 255 characters
0.. 90
0.. 1
> 0, <= 10
> 0, <= 10
> 0, <= 2
May be
empty?
no
no
no
no
no
yes
yes
yes
yes
no
no
no
no
no
To decimal separator for floating point numbers depends on Windows registration entries.
8.3 Interrupt handling
The program can be interrupted using the Windows Task Manager. If the results are not yet
stored, they will be lost in this case. After program stop, the results in the file may be
incomplete. The program run should be repeated for the current file.
9 Application example
The program is started by calling the file HemEmi.exe
50
Figure 1: HemEmi – Menu item „Inputs / New File“
New data are entered using the menu item „Inputs / New File“. This opens a dialog, which the
user allows to make his inputs.
Figure 2: HemEmi – Dialog „Data Input“
The data will be stored in a file by selecting the button „OK“.
51
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 calculation
is 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 selected
a file:
52
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 appear
in a message window:
Figure 8: HemEmi – Results
In the present example, the parameter K is very small. The user is informed about that and
may 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.
53
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-05
Date: 9.5.2005
Time: 07:53
Temperature of specimen: 125 °C
Temperature of receiver: 25 °C
Labelling of specimen: edLabelling
Substrate: edSubstrate
Plating: edPlating
Comment:
memoComment
Measurement values:
5
15
0,90010
30
0,90110
40
0,90120
50
0,91120
60
0,91230
the new file 001.txt is created in the same directory:
Data of measurement 001-05
Date: 9.5.2005
Time: 07:53
Temperature of specimen: 125 °C
Temperature of receiver: 25 °C
Labelling of specimen: edLabelling
Substrate: edSubstrate
Plating: edPlating
-
54
Comment:
memoComment
Measurement values:
5
15
0,90010
30
0,90110
40
0,90120
50
0,91120
60
0,91230
Measured values:
Parameter N: 1
Parameter K: 1,732E-5
Parameter P: 0,0988
15
0,9012
30
0,9012
40
0,9012
50
0,9012
60
0,9012
Phi: 1
'Std.deviation': 0,01498
55