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.
You must provide a report that is detailed enough so that a reader
with the background of a fellow student has sufficient information
to reproduce your results.
Description of All Code Used
Describe the code you use! You should start by stating the
problem your code solves. Then explain the
method 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 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.
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!
Include your name in the comments of each of your functions;
I will not accept code without your 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?"
Copyright © 2001-2005 by Matthias K. Gobbert. All Rights Reserved.
This page version 3.1, May 2005.