Capstone 2: a matrix type and its operations
The second capstone is a small linear algebra library: a type that holds a matrix, the operations on it, an LU factorisation and a solver, and a test program that checks the whole thing against systems whose answers are known. This lesson builds the type and the operations. It is a small piece of code with three design decisions in it, and each of them shows a part of Fortran that a numerical program cannot avoid: an allocatable component, an overloaded operator that has to check its arguments, and a type-bound procedure.
The matrix type
The type has one component, an allocatable rank-two array. That single line is what makes the type useful: the storage belongs to the value, so an assignment copies the elements and a deallocation frees them, with no pointer and no memory management in the user code. Lesson 079 is the long version of that statement; here it is the reason the type can be passed by value, returned from a function and put in an array.
type :: matrix
real(dp), allocatable :: a(:,:)
contains
procedure :: trace
end type matrix
The component is public and the type is not: a user of the module writes m%a and gets the array, which is what a numerical library wants for the fast path. A stricter design would keep it private and offer get and set; the capstone chooses the open one and says so.
Constructors
FROM_ARRAY takes the elements as a flat list and a shape, and RESHAPE fills the matrix column by column. That is the whole reason the output below looks transposed to a reader who reads the list row by row: the nine values are the columns of the matrix, not its rows, which is the column-major rule of lesson 045 in the constructor.
IDENTITY allocates and fills the diagonal in a loop, which is the one place a loop is clearer than an array expression. Both are PURE functions that return the type: the result is a value with its own storage, and the caller can assign it, pass it on or let it fall out of scope.
Operators with a shape check
OPERATOR(+) and OPERATOR(*) are generic interfaces over two module procedures, and both check the shapes before they compute. The checks are the interesting part, because they force a decision: ERROR STOP is not allowed in a PURE function, so a function that validates its arguments cannot be pure, and a function that stays pure cannot report a bad shape except through a wrong answer or a run-time check.
The capstone chooses the check. A library that is called from a program that cannot recover from a shape error is better off stopping with a message than computing on memory that does not belong to it, and the message names the operation. The alternative, returning a status component in the result, is what a library that has to continue would do, and it costs a test at every call site.
The multiplication checks the inner dimensions and calls MATMUL, which is the intrinsic of lesson 041 and, at -O2, about four times faster than the three loops of lesson 121. Writing the loop by hand would be a step backwards; the type adds the shape check and the syntax, not the arithmetic.
A type-bound function
TRACE is the one procedure bound to the type, and it is there to show the form: CLASS(MATRIX) as the passed-object dummy, so a value of a type that extends MATRIX could call it too, and a call written a%trace() that reads like a property. It sums the diagonal up to the smaller dimension, so a rectangular matrix has a trace rather than an error.
The other procedures are module procedures called by their plain names. A library usually mixes the two: what reads like a property of the value is bound, and what reads like an operation on two values is an operator or a function. Lesson 073 covers the binding rules, including PASS and NOPASS.
The run
The file matrix.f90, the module and a program that builds a matrix and an identity and prints six results:
module matrix_mod
use, intrinsic :: iso_fortran_env, only: dp => real64
implicit none
private
public :: matrix, from_array, identity, print_matrix, operator(+), operator(*)
type :: matrix
real(dp), allocatable :: a(:,:)
contains
procedure :: trace
end type matrix
interface operator(+)
module procedure add_matrix
end interface
interface operator(*)
module procedure mul_matrix
end interface
contains
pure function from_array(values, nrows, ncols) result(m)
real(dp), intent(in) :: values(:)
integer, intent(in) :: nrows, ncols
type(matrix) :: m
m%a = reshape(values, [nrows, ncols])
end function from_array
pure function identity(n) result(m)
integer, intent(in) :: n
type(matrix) :: m
integer :: i
allocate(m%a(n, n))
m%a = 0.0_dp
do i = 1, n
m%a(i, i) = 1.0_dp
end do
end function identity
function add_matrix(x, y) result(z)
type(matrix), intent(in) :: x, y
type(matrix) :: z
if (any(shape(x%a) /= shape(y%a))) error stop 'add: shapes differ'
z%a = x%a + y%a
end function add_matrix
function mul_matrix(x, y) result(z)
type(matrix), intent(in) :: x, y
type(matrix) :: z
if (size(x%a, 2) /= size(y%a, 1)) error stop 'mul: inner sizes differ'
z%a = matmul(x%a, y%a)
end function mul_matrix
pure function trace(self) result(t)
class(matrix), intent(in) :: self
real(dp) :: t
integer :: i
t = 0.0_dp
do i = 1, min(size(self%a, 1), size(self%a, 2))
t = t + self%a(i, i)
end do
end function trace
subroutine print_matrix(name, m)
character(len=*), intent(in) :: name
type(matrix), intent(in) :: m
integer :: i, j
print '(a,a,i0,a,i0,a)', trim(name), ' (', size(m%a, 1), ' x ', size(m%a, 2), ')'
do i = 1, size(m%a, 1)
print '(10f8.2)', (m%a(i, j), j = 1, size(m%a, 2))
end do
end subroutine print_matrix
end module matrix_mod
program matrix_demo
use matrix_mod
use, intrinsic :: iso_fortran_env, only: dp => real64
implicit none
type(matrix) :: a, b
a = from_array([1.0_dp, 2.0_dp, 3.0_dp, 4.0_dp, 5.0_dp, 6.0_dp, 7.0_dp, 8.0_dp, 10.0_dp], 3, 3)
b = identity(3)
call print_matrix('A', a)
call print_matrix('B', b)
print '(a,f6.2)', 'trace(A) = ', a%trace()
call print_matrix('A + B', a + b)
call print_matrix('A * B', a * b)
call print_matrix('A * A', a * a)
end program matrix_demo
gfortran -Wall -Wextra -std=f2018 matrix.f90 -o matrix
./matrix
A (3 x 3)
1.00 4.00 7.00
2.00 5.00 8.00
3.00 6.00 10.00
B (3 x 3)
1.00 0.00 0.00
0.00 1.00 0.00
0.00 0.00 1.00
trace(A) = 16.00
A + B (3 x 3)
2.00 4.00 7.00
2.00 6.00 8.00
3.00 6.00 11.00
A * B (3 x 3)
1.00 4.00 7.00
2.00 5.00 8.00
3.00 6.00 10.00
A * A (3 x 3)
30.00 66.00 109.00
36.00 81.00 134.00
45.00 102.00 169.00
The trace is 1 + 5 + 10 = 16, and A * B is A because B is the identity. A * A is the product a reader can check by hand: its first column is the first column of A multiplied by each row of A, 1*1 + 4*2 + 7*3 = 30.
What the type does not do
The type does not own its shape. A matrix that has never been allocated has SIZE(a) of zero in a conforming program and a nonsense number in gfortran 15.2.0 if the component is read before it is allocated, so the constructors are the only way to make one and every procedure assumes an allocated component. A library would add an ALLOCATED test in the operators and a constructor that takes a shape and no values.
The type also does not check the subscript when the caller reads m%a(i,j) directly, which is the price of the public component. The next lesson adds the factorisation and the solver, where the operations on the storage are the point, and the one after that is the test program that checks every one of them against a known answer.
Exercises
- Add OPERATOR(-) and OPERATOR(==). What does the second one have to compare, and what does it return?
- Write FROM_ARRAY so that its list is read row by row instead of column by column. Which element of the output changes first?
- Make ADD_MATRIX PURE again and delete the check. What does the program do when the shapes differ, with and without -fcheck=all?
- Add a TRANSPOSE function. Why does it have to return a new value rather than a view?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What does the matrix type hold?
Answer
An allocatable rank-two array, and a bound TRACE
The storage belongs to the value.
-
Why does
A + Bprint what looks like the transpose of the list?Answer
RESHAPE fills column by column
Fortran is column-major.
-
Why can the operators not be PURE?
Answer
ERROR STOP is not allowed in a pure function
A pure function cannot stop the program.
-
What does the multiplication check?
Answer
The inner dimensions, before calling MATMUL
The message says which sizes differ.
-
What does
A * Breturn when B is the identity?Answer
A itself
The output is the same three rows.
-
What is
trace(A)for the matrix of the page?Answer
16
1 + 5 + 10.
-
What is the first element of A * A?
Answer
30
1*1 + 4*2 + 7*3.
-
Why is the component public?
Answer
A numerical library wants the fast path to the array
The price is no bounds check on direct access.
-
Which intrinsic does the multiplication use?
Answer
MATMUL
Four times faster than three loops at -O2.
-
What does TRACE sum?
Answer
The diagonal, up to the smaller dimension
A rectangular matrix still has a trace.
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