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

  1. Add OPERATOR(-) and OPERATOR(==). What does the second one have to compare, and what does it return?
  2. Write FROM_ARRAY so that its list is read row by row instead of column by column. Which element of the output changes first?
  3. Make ADD_MATRIX PURE again and delete the check. What does the program do when the shapes differ, with and without -fcheck=all?
  4. 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.

  1. What does the matrix type hold?

    Answer

    An allocatable rank-two array, and a bound TRACE

    The storage belongs to the value.

  2. Why does A + B print what looks like the transpose of the list?

    Answer

    RESHAPE fills column by column

    Fortran is column-major.

  3. Why can the operators not be PURE?

    Answer

    ERROR STOP is not allowed in a pure function

    A pure function cannot stop the program.

  4. What does the multiplication check?

    Answer

    The inner dimensions, before calling MATMUL

    The message says which sizes differ.

  5. What does A * B return when B is the identity?

    Answer

    A itself

    The output is the same three rows.

  6. What is trace(A) for the matrix of the page?

    Answer

    16

    1 + 5 + 10.

  7. What is the first element of A * A?

    Answer

    30

    1*1 + 4*2 + 7*3.

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

  9. Which intrinsic does the multiplication use?

    Answer

    MATMUL

    Four times faster than three loops at -O2.

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