A numerical report with a table
A numerical result is a number and a text, and the text is what a reader uses. A table whose columns do not line up is a table a reader misreads, and a table without a header on its second page is a table a reader cannot use at all. This lesson writes the report around the trapezoid table of lesson 093: a title, the exact value, a header built from the same field widths as the data, a header that repeats every four rows, and a column that stays blank until there is a ratio to put in it.
The report
The program integrates exp(x) again and prints one row per n, doubling n each time. The numbers are the ones of lesson 093; the subject here is the shape of the output, which is why the integration is a local function and the report is the program.
The file report.f90:
program report
implicit none
integer :: n, rows_per_page, row
real :: h, value, exact, err, prev, ratio
character(len=10) :: ratio_col
exact = exp(1.0) - 1.0
rows_per_page = 4
row = 0
print '(a)', 'Numerical integration of exp(x) on [0, 1]'
print '(a,f10.7)', 'exact value: ', exact
print '(a)', ''
n = 4
prev = 0.0
do while (n <= 256)
if (mod(row, rows_per_page) == 0) then
call header()
end if
h = 1.0 / real(n)
value = trapezoid(n)
err = abs(value - exact)
if (prev > 0.0) then
ratio = prev / err
write (ratio_col, '(f8.2)') ratio
else
ratio_col = ' '
end if
print '(i5,f10.5,f14.7,es15.4,a10)', n, h, value, err, ratio_col
row = row + 1
prev = err
n = 2 * n
end do
print '(a)', ''
print '(a)', 'End of report.'
contains
subroutine header()
print '(a5,a10,a14,a15,a10)', 'n', 'h', 'value', 'abs error', 'ratio'
print '(a5,a10,a14,a15,a10)', '-----', '----------', '--------------', '---------------', '----------'
end subroutine header
function trapezoid(n) result(s)
integer, intent(in) :: n
real :: s, h
integer :: i
h = 1.0 / real(n)
s = 0.5 * (exp(0.0) + exp(1.0))
do i = 1, n - 1
s = s + exp(real(i) * h)
end do
s = s * h
end function trapezoid
end program report
gfortran -Wall -Wextra -std=f2018 report.f90 -o report
./report
Numerical integration of exp(x) on [0, 1]
exact value: 1.7182817
n h value abs error ratio
------------------------------------------------------
4 0.25000 1.7272218 8.9401E-03
8 0.12500 1.7205185 2.2367E-03 4.00
16 0.06250 1.7188411 5.5933E-04 4.00
32 0.03125 1.7184218 1.4007E-04 3.99
n h value abs error ratio
------------------------------------------------------
64 0.01562 1.7183169 3.5167E-05 3.98
128 0.00781 1.7182903 8.5831E-06 4.10
256 0.00391 1.7182840 2.2650E-06 3.79
End of report.
Columns that line up
A column lines up when the header and the data use the same width. The header is printed with (a5,a10,a14,a15,a10) and the data with (i5,f10.5,f14.7,es15.4,a10): the same five widths, counted out. Writing the header as one long literal with spaces between the words works until somebody changes a format by one character, and then the table is off by one for ever.
f10.5 for h prints five decimals, which is enough to see the halving; f14.7 for the value keeps seven; es15.4 for the error puts it in one column whatever its size, because an exponent keeps the width fixed. That last choice is the important one: a fixed-point format would push the error column right as the error grows, and a table that moves is not a table.
A header that repeats
if (mod(row, rows_per_page) == 0) call header() prints the header again every four rows. On a screen a reader scrolls; on paper a table crosses a page boundary; in either case a row without a header is a row a reader has to count back to. A real report library also repeats a footer and breaks at a page height the caller chooses, and the mechanism is this one line.
The first row has no ratio, so the column is left blank rather than filled with a zero. A zero would be a lie: the ratio of the first error to nothing is not defined, and a reader who sees 0.00 in a convergence column concludes that the method did not converge.
A column that may be blank
ratio_col is a ten-character buffer, and an internal write fills it before the row is printed. That is the smallest use of lesson 048: a number becomes a right-aligned string, and an empty string of the same width keeps the column. The alternative is a second format string for the first row, which is two formats to keep in step instead of one.
The buffer is fixed length on purpose. An internal write to a character(len=:), allocatable buffer fails at run time in this build with a message about end of file, which is why the course uses a fixed length wherever the width is known.
A format that does not match
A format is checked against the item list when the statement runs, and the wrong descriptor stops the program with a message that names the item:
program badfmt
implicit none
integer :: n
real :: h
n = 8
h = 0.125
print '(i5,i10)', n, h
end program badfmt
gfortran -Wall -Wextra -std=f2018 badfmt.f90 -o badfmt
GFORTRAN_ERROR_BACKTRACE=0 ./badfmt
At line 8 of file badfmt.f90 (unit = 6, file = 'stdout')
Fortran runtime error: Expected INTEGER or UNSIGNED for item 2 in formatted transfer, got REAL
(i5,i10)
^
The caret marks the descriptor that failed, the second i10, and the run stops with exit status 2. The command sets the backtrace variable to zero, which suppresses the addresses after these lines; the message itself is the same either way.
The compiler accepts the statement because a format can be a variable, so the check is a run-time one. That is the one class of error a report program has that nothing else does: a row prints wrong or stops, and only a run of the program finds it.
Rules for a report
Give every column a width and use it in the header, the rule and the data. Use an exponent format for a quantity whose size changes. Repeat the header at a page height the caller can change. Leave a column blank rather than filling it with a plausible number, and print the units in the title rather than in every row.
The report is also where a test can read the result back: a table written to a file and parsed by another program is the interface of a batch job, and the format is then an API. Part 14 uses exactly that for the third capstone, and the columns of this page are its format.
Exercises
- Change rows_per_page to two and rerun. How many headers does the table print?
- Put the ratio in a wider column of twelve characters and widen the header by the same amount. Which lines change?
- Print the first row with a ratio of 0.00 and see how it reads. Why is blank better?
- Write the same table to a file with open and write of lesson 053. What has to change in the program, and what stays the same?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
Why is the header printed with the same widths as the data?
Answer
So the columns line up whatever the values are
Two formats with one set of widths stay in step.
-
Why use
es15.4for the error column?Answer
An exponent keeps the column width fixed as the error changes
A fixed-point column would move as the error shrinks.
-
What does this program print?
program p implicit none integer :: i do i = 1, 2 write (*, "(a,i2)") "row ", i end do end program pAnswer
row 1 and row 2
Each WRITE ends the record; i2 pads to two characters.
-
Why is the first ratio column left blank?
Answer
There is no previous error, so the ratio does not exist
A zero would be a plausible lie.
-
How is the header repeated?
Answer
A test of the row counter against a page height
MOD(row, rows_per_page) == 0 calls the header.
-
What does the internal write into ratio_col do?
Answer
Turns the number into a right-aligned string of fixed width
It is the smallest use of an internal file.
-
When is a format string checked against its items?
Answer
When the statement runs, if the format is not a constant
A format may be a variable, so the check is a run-time one.
-
What does gfortran report for
print '(i5,i10)', n, hwith a real h?Answer
Fortran runtime error: expected INTEGER or UNSIGNED for item 2
The run stops with exit status 2 and names the descriptor.
-
Why is a fixed-length character buffer used for the column?
Answer
An internal write to an allocatable buffer fails at run time in this build
Fixed width is what a column needs anyway.
-
Why does the report matter beyond printing?
Answer
A table written to a file is an interface another program parses
The format then is an API, and part 14 uses it.
The programs on this page were built with GNU Fortran (Alpine 15.2.0) 15.2.0 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev