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.