Matthias K. Gobbert

How to Report on Computer Results

General Purpose of the Reports

On homework as well as on other reports, you are expected to explain clearly and in a professional style what you did and to present and analyze your results. This is actually very simple and basic, but experience shows that it takes time to learn how to do this best. This document attempts to provide some clarification and guidance. Study the computational examples in our textbook; note the way in which computer results are introduced and interpreted there.

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 detailed enough so that a reader of your report has sufficient information to reproduce your results.

Description of All Code Used

Describe the code you use! You should start by stating the mathematical problem that your code solves. Then explain the numerical method that you implement. 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 written, 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 ones.

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 ... ".

Final Notes

A note on order: For each problem, start with a page of text, that introduces the code, tables, figures, etc. on the following pages. Those results should appear in the same order as they are mentioned in the text. Assemble everything in the order, in which you want me to read it! To aid me in grading, please maintain the organization in parts (a), (b), etc., as given in the assignment. Keep all pages together that belong to one problem. Remember in any case: The text of your report must be complete enough such that the reader can understand how results were obtained; I will not read code to find out what you did! However, to deter copying of your work, include your name in the comments of each of your functions; I will not grade code without a name! There should not be any hand-written interpretations on your printouts; those comments should be contained within your text that introduces and interprets the printed results.

A note on style: I strongly urge you to hand-write your reports on the homework. Unless you are very experienced, using any typesetting system will likely limit you in your use of formulas and arrangement. However, your reports should have the style and arrangement, as if they were prepared for professional type-setting using, e.g., proper headers, displayed formulas, etc. Start a new problem on a new sheet of paper. Use only one side of each sheet of paper. Write large and clearly. Leave sufficient margins and other spaces for me to provide comments and feedback to you.

On grading: Preparing the report that documents what you did and analyzes the results is an integral part of the assignment, whether the assignment asks for it explicitly or not. 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: "Based on the information given, could I reproduce your results?" and "Are all pertinent questions about the performance of the numerical method addressed?"