How to Document Computer Results
Matthias K. Gobbert
This class will include programming assignments as part of the homework.
For a numerical class, these assignments are crucial, since you can actually
see the various algorithms at work. The fundamental purpose is always to
verify that a certain algorithm actually works and to see how well it does
so. Under certain conditions it might also fail to work; that should be
predicted by a theorem and could be verified by example in a computer test.
In this spirit, you should always remember that writing a code and solving
a given test problem with it is just half the work. Documenting and
interpreting is the full other half of the overall work involved in programming
assignments! It is this part that actually helps you understand the algorithm
by consciously observing its performance.
As a basic idea, notice that for most test problems on the homework, the true
solution will be known or can be computed easily with pencil and paper; in
such a case, you will want to compare your computed solution to the true one.
Or the computed solution can be tested for correctness or its quality
measured in some other way (see an appropriate theorem for the numerical
method); in this case, this measure should be used. We will discuss this
in more detail in class, but towards the end of the semester, you should
be able to write an appropriate report on your own. As a very good idea,
consider the way the computational examples are presented in the textbook!
The following contains some ideas on how to properly present the solution
to such a programming assignment. Notice that despite the long text here,
such a write-up can be very short with just a few sentences and formulas
for each section. Handwriting is sufficient, what counts is neat organization
with clear headers.
Purpose
You should state here, what type of problem (linear system, nonlinear
equation, etc.) the implemented method is supposed to solve and what
kind of behavior you expect the see. This section should only be a few
sentences and simply answer the question: ``Why am I doing this, and
what results do I expect?'' No mathematical formulas are expected here.
Introduction
This section contains a statement of the problem in mathematical terms
including formulas. For a physical problem, terminology, notation, and units
used would need to be introduced here. This section answers the question:
``What problem do I want to solve?''
The method
Here, you need to state clearly in mathematical terms, what method you
are using to solve the problem above. It should be in mathematical terms
including formulas. This section answers the question ``How do I
solve the problem?''
Implementation
In this section, the mathematical formulation of the algorithm needs to be
translated into a form that can be programmed in a computer. You should
introduce the variables used in your code and match them with the mathematical
variables of the previous section. Usually, a short listing of pseudo code
should be provided for the crucial part of the algorithm.
Fundamentally, this section answers the question ``What did I actually
do?'' It should always specify the language used, the computer the
code was run on, and an explanation of any other computational tools used.
Notice that this section consists of text and not of computer printouts;
those should be included in an appendix, however, you should refer to your
listings here. Specify clearly the input and output of the various functions.
This section would also be the place to mention things that went wrong with
your program or other difficulties that arose.
Results
Here, you should present all pertinent results obtained. Depending on the
problem, tables listing numerical results and/or figures showing various
graphs are appropriate. Make sure that tables and figures have appropriate
headers and labels; it is customary to number them in order to refer to
them in the text.
As appropriate and self-explanatory tables and figures might be for the
problem at hand, they never constitute the results on their own! Rather,
they should always be accompanied by a text that interprets their meaning;
remember in particular to specify clearly all parameters and input variables
used to obtain each result and contrast their outcomes.
In summary, this section answers the question: ``What did actually happen
when running the code?''
Conclusions
This short section draws conclusions from the results in the previous
section. The question to answer is: ``Did the program work? Did it behave
as expected? What did I learn from the experience?'' You might want to
contrast your conclusions to the expectations specified in the first section.
Appendix
You should always include printed listings of all pieces of code written
for the project. It is usually a good idea to highlight the names of the
functions for ease of reading or to add the name of the printed file in
handwriting. Do whatever makes the listings organized and easy to find.
I do not usually read these listings, since your report above should provide
all information needed to grade your project. But these printouts are
required, and you will actually want to have them as documentation for
yourself in the future.
Copyright © 1999 by Matthias K. Gobbert. All Rights Reserved.
This page version 1.3, January 1999.