How to Document Computer Results

Matthias K. Gobbert


How to Document Computer Results

You are expected to explain and document what you did and what you found. This is actually very simple and basic, but experience shows that many students have trouble with it. This document attempts to provide some clarification and guidance.

Possibly, you have trouble getting the level right, because it might feel like restating the obvious to you, if you think of me as the intended reader. Rather visualize as reader a fellow student, who has missed class several times. That is, you may assume that your reader has the assignment as well as the textbook available to him or her. However, you may not assume that he or she has any lecture notes or hints from any source available. Given these assumptions, you must provide a report that is sufficiently detailed so that a reader of your report has sufficient information to reproduce your results.

Description of the Code Used

Describe the code you implemented! You should start by stating the mathematical problem that your code solves. Then explain the numerical method that you implemented. It will usually be based on mathematical formulas, so state them and introduce all required notation. Give the source of your algorithm sufficiently precisely, e.g., a formula or a page in the textbook. If you wish to use an algorithm as presented in the lecture, you should restate it. Always incorporate the name of your function and the software package or computer language it is written for. Finally, state how and where you used your code. This should in particular include the computer, operating system, and version number of the software or language used. Include all information that might be pertinent, which often will include also the amount of memory or processor speed.

Let me be clear about some aspects of this description: While you are required to include the actual source code of all code used as appendix, only the key part of your code needs to be described in detail, i.e., the algorithm that we are studying in the particular assignment. The code should be well-written in structure and show helpful short comments to find everything, but I will usually only look at it to try to help you fix some bug, if I find your results in error; this is not a programming course. Remember that your description should be sufficient to understand what you did without actually reading the listing of your code. I usually find that it pays to rewrite the mathematical equations in such a way that it becomes easy to write a code that resembles them. Then, it is also very easy to describe the code, in particular if you choose variable names that resemble the mathematical variables.

Example: We wish to compute the definite integral of f(x) from a to b. The composite trapezoidal rule is used to approximate the integral, as given in (5.1.5) on page 253 of Atkinson. The Matlab function trap.m was programmed to implement the rule. It accepts as input a function handle fname for f(x), double-precision numbers a and b for a and b, and a positive integer n for the number of subintervals. It returns the numerical integral approximation In. Matlab's feval function is used to evaluate f(x) at all points x needed. Then the sum function is used to perform the summation in (5.1.5). The code was run on a Linux-PC using Matlab 6.1 (R12.1).

Description of the Results

Present your results in well-organized form using computer-generated tables and figures. All tables and figures need to be introduced with text stating how they were produced and what is shown in them. They should always include pertinent information that distinguishes them, if there are several ones. There should not be any interpretation in these first sentences; just state what you did and what is shown! Introduce appropriate mathematical notation to help yourself discuss the results. Then, follow up with a critical discussion: Compare your result to any pertinent theorem that we might have discussed, contrast different results with each other and with your past experience, etc. Be precise about telling your reader where to look for the data from which you are drawing your conclusions. For instance, do not just say ``the table shows ...'', but rather ``the last column in the table shows ... ''. Or for instance regarding a figure, do not say ``the figure shows ...'', but ``the slope of the curve in the figure indicates ... ''.

Example: The trapezoidal rule was applied to f(x) = x sin(x) on [a, b] = [0, 1]. The table shows results for n = 2k with k = 1, 2, 3, ... . Since we can compute the true solution I, the true error En = I - In is computed as well as the ratio Rn of the errors En/2 and En. Each row in the table lists n, the approximation In, the error En, and the ratio Rn. We observe that the error gets smaller as the number of subintervals increases, hence the method appears to converge. More precisely, since the ratio Rn tends to 4, as n gets larger, we can conclude that the method converges with order 2, similar as in Table 5.1 in the textbook and as predicted by Theorem 5.1.

Final Notes

A note on order: Any sensible order is fine with me in principle. But in order to help me find everything, please maintain the organization in parts (a), (b), etc. as given in the assignment. For each part, start with a new page of text, followed by tables and figures in the same order as they are mentioned in the text. All code should be collected and be included at the end of the problem as an appendix. You may want to add hand-written notes to the printed pages to help identify and distinguish them. Remember in any case: Your presentation must always start with text, not tables, figures, or code!

Final note: In my examples above, I was limited by the facts that I needed to be as brief as possible and that I was writing this in HTML. Therefore, no formulas were included in my examples. You may notice how unclear the description to anyone but an expert! Let this serve as a pointer: Do not be too brief, and include as many formulas as necessary to be clear!

On grading: Preparing the report is an integral part of the assignment. Complete and correct computer results will never count more than half of the score for the problem. When grading the reports, I will be guided by the questions: ``Are all pertinent questions about the performance of the numerical method addressed?'' and ``Based on the information given, can I reproduce the results?''


Copyright © 2001 by Matthias K. Gobbert. All Rights Reserved.
This page version 1.1, August 2001.