In the previous post we improved the output handling of the test runner, making output optional by using an abstract progress printer. Only our assert_equals function, which by the way should also be moved to the test_framework module, still prints directly to stdout:

function assert_equals(expected, actual, epsilon) result(assertion_failed)
   ! ... 
   assertion_failed = .false.

   if (abs(actual - expected) > epsilon) then
      print *, 'Actual: ', actual
      print *, 'Expected: ', expected
      print *, 'Epsilon: ', epsilon
      print *, 'Reals are not equal'
      assertion_failed = .true.
   end if
end function assert_equals

To fix this, we should upgrade the return type. One idea would be to return a message (variable-length string) instead of a logical, but a more flexible, future-proof alternative is to define a custom type for an error. This would allow us to pass more information back to the caller than just the message. A suitable name would be assertion_failed_t:

In the previous post we’ve successfully split the running of the tests and collecting the test results from handling those results by printing the counters and error stop-ping the test program. We still ask each test procedure to print a small description. We do this to assist the programmer when there is some kind of crash during the test run: they need to be able to find out which test caused it.

Maybe we’ve been writing more “generic” code for our custom test program than expected. We have been gradually, and quite safely, extracting code from a simple “check program”. But now that we’re looking at a pretty generic test runner that we’re going to use for all our future unit tests, we inevitably have to address the concern that we’re writing code that isn’t tested itself. Who tests the test framework? Well, the test framework itself has all the ingredients. However, testing the framework requires that we can run its code in isolation: that we can call one of its functions, and assert that it behaves correctly. Unfortunately, that isn’t possible yet. The code still lives in the main block of the tester program, and it doesn’t allow in-memory inspection of the test results, because it only prints them to the terminal, which we can’t unit-test.

In the previous post, we’ve spent some time improving a number of “temporary” tests. We introduced an assertion function to compare two real values, and we prevent failing tests from stopping the entire test program.

Moving tests to their own procedures

The approach of adding tests directly in the main test program block doesn’t really scale, as the saying goes. polyline_length may be a simple function, but for more complicated functions with multiple branches and loops, we’d have to write many of these tests. The test program keeps growing, and eventually it becomes a mess. It doesn’t help that all local variables have to be declared at the top. Even if that wasn’t needed, it isn’t very clear where a test starts or ends. Everything happens in the same scope, potentially becoming a memory management issue too. This also makes it hard to delete tests we no longer want. Removing lines from a big test program likely breaks other tests, or we forget to remove things we no longer need.

How can we know that the function we wrote, works as intended? We could run it, and manually verify its correctness. The simplest way to do this is to call the function in the main program block, print the output, and compare it with what we expect. Say our function calculates the length of a polyline, stored as a two-dimensional array of reals, representing (x,y) coordinates:

pure function polyline_length(coordinates) result(length)
   real(kind=real64), dimension(:, :), intent(in) :: coordinates

   real(kind=real64) :: length

   real(kind=real64) :: distance
   integer :: index

   length = 0.0_real64

   do index = 1, size(coordinates, 1) - 1
      distance = sqrt((coordinates(index, 1) - &
                       coordinates(index + 1, 1))**2 + &
                      (coordinates(index, 2) - &
                       coordinates(index + 1, 2))**2)
      length = length + distance
   end do
end function polyline_length

Temporary test programs

We could modify the main program block of our actual program, but it’s a lot simpler and safer to create a separate “throw-away” test program, with only the code we need. We’d write a short test program that sets up some coordinates, calls the function, then prints the result:

We’ve encountered several ways of designing functions in a way that allows them to fail for some reason, without stopping the program, or making it otherwise risky or awkward to use the function. We introduced the error_t type which is very flexible. It can be used to provide some information to the caller, helping them understand what went wrong and how it can be fixed. By allowing errors to be wrapped inside others, we can create chains of errors that describe the problem at various abstraction levels. It gives back control to the user: how do they want to deal with an error? Would they like to try something else? Or, in the end, should we just stop trying and quit te program?

Parsing an array of strings to a polyline should fail if one of the strings could not be parsed to a string. But it should also fail if the resulting array of points is empty. Or at least, if that makes sense in the application’s domain. You could say that a polyline with no points is still a polyline, just like an empty set is still a set. Similarly, in some scenarios it may be okay for a polyline to have just a single point. For now, let’s skip the mathematical discussion and take this as a practical rule that we want to enforce: a polyline has at least 2 points. The type we currently have can’t give us such a guarantee:

Parsing a string to a point may not be successful, and we were able to communicate that to users of parse_point() by returning a custom type called point_or_error_t.

What if we want to parse not just one point but a set of points, forming a polyline, from a list of strings? The result of parsing each string separately is a point or an error. Only if the list of those point_or_error_t values contains no error at all should we consider turning the points into a polyline. If any of the values is an error, we shouldn’t make a polyline of the other valid points, but instead return an error: “Could not create polyline from strings. Previous error: Could not extract two decimal numbers from …” With this error we communicate what we were trying to do at the highest conceptual level (create a polyline), and what lower-level error caused this to fail.

We looked at optionally returning a value from a function. In the case of average it was an average value, or no value at all. In some more elaborate functions, the “no result” case needs some more explanation to the caller of the function. We may feel the need to communicate what went wrong, or for what reason. This gives the user the opportunity to pass better input next time, or fix some external issue that the program can’t fix itself (e.g. a file not being readable).

In the previous post we introduced an optional_real_t type to be the return value of an average function, because depending on the size of the array of numbers passed to it this function may or may not return a real value.

What if we could just prevent people from calling the average function when they don’t have any numbers? Maybe we’re lagging too far behind if we have to verify the size of the array inside the average function.

In the previous post we’ve looked at several ways to communicate to the user of a function that something could go wrong, or that maybe the function couldn’t produce the result that the user was looking for. In the case of an average function, we’d want to communicate to the user that in some cases the function can’t produce a meaningful result, namely if the array of numbers is empty. This isn’t really an error, it’s just that we don’t have a way to answer the question “what’s the average of this array?”. To communicate that with the function signature, we tried adding a “success” return value, making the calculated average an intent(out) argument. The function modifies the variable passed by the user to contain the average value, but only if the array is not empty:

Fortran doesn’t have exceptions. You can’t jump out of a function when something unexpected happens, then reflect on what happened outside the function, with the help of a try/catch block. As an alternative, intrinsic (built-in) procedures and constructs like write, read and open allow you to pass an integer variable as one of its arguments, to which it will assign a specific value indicating whether an error occurred. For example, when you try to open a file that doesn’t exist, you will get a non-zero value in the variable passed as the argument for iostat:

We’ve implemented filter and map operations. The results of both these operations are new arrays. Yet another common operation on arrays is the so-called reduction operation; we “reduce” multiple values to a single value. The most obvious example is calculating the sum of an array of integers: the input is an array (or list) and the output is a single integer:

pure function sum_all(numbers) result(res)
   integer, dimension(:), intent(in) :: numbers
   integer :: res

   integer :: i

   res = 0

   do i = 1, size(numbers)
      res = res + numbers(i)
   end do
end function sum_all

Just like with filter and map we can imagine a generalization of this process, which involves looping over the array elements and building up a single return value along the way. We start with the existing sum_all function. The first step is to let the user decide what the return value should be, which is the logic that happens inside the do loop. We extract a function for this:

In the previous post we looked at this dream scenario:

list([1, 3, 5, 7]) % filter(divisible_by(3)) % map(square)

As mentioned, we can’t chain function calls like this. But we can put intermediate results in local variables and achieve something similar:

integers = list([1, 3, 5, 7])
divisible_by_3 = integers%filter(divisible_by(3))
squared = divisible_by_3%map(square)

If the intermediate values are all the same type, we can reuse the variable:

integers = list([1, 3, 5, 7])
integers = integers%filter(divisible_by(3))
integers = divisible_by_3%map(square)

To enable this syntax, it’s clear that we need to introduce a derived type for a list of integers that has type-bound procedures filter and map. These functions should each return a new list, so we can call any of these functions again on the new list. Let’s start with an integer_list_t which contains an array of integers. We also provide a generic list interface with a specific procedure create_integer_list for creating the integer_list_t:

We considered the problem of filtering elements in an array, keeping only the ones we want. A decision about that is made by a function we pass as an argument.

A similar problem, but with its own challenges, is when we have an array of values and want to create a new array, with an equal number of elements, but each element has been transformed in some way. For instance, say we have an array of integers and want to square each integer. A procedural approach looks as follows:

We have a reusable filter function to which we pass the name of a procedure that matches a given interface. But can we also do something like this?

filter([1, 2, 3, 4], is_divisible_by(3))

Closures

This is a very common thing in functional programming. It involves something called higher-order functions. This means that a function may itself return a function. In this case, is_divisible_by returns a function that can be passed to filter. This returned function also needs to remember the value 3 that was passed to it. When it’s executed for each value in the integer array, it will check if that value is divisible by 3. In other languages such a function is called a closure; it’s a function that can be passed around as a value. Besides the function itself, it also has the data from the context where it was created - “bound” to it. In “ideal Fortran”, we would write something like this:

We have a working filter function for integers. Now can we generalize it? It would be nice if we could filter other types of arrays, like real arrays.

Generic filtering

As mentioned before, Fortran doesn’t have support for generics, which would allow you to use some kind of “placeholder” for types (e.g. [value_type]):

pure function filter(values, filter_func) result(res)
   [value_type], dimension(:), intent(in) :: values

   interface
      pure function filter_func(value) result(keep)
         implicit none(type, external)

         [value_type], intent(in) :: value
         logical :: keep
      end function filter_func
   end interface

   [value_type], dimension(:), allocatable :: res

   integer :: i

   res = pack(values, [(filter_func(values(i)), i=1, size(values))])
end function filter

You could then use filter on an array with any type of value, and the filter_func’s value argument would have to be of that same type, and the return type would be of that type too.

Once introduced to Fortran, we are left wondering what kind of language it really is. Traditionally, it’s been used as a procedural language, or a “Do this, do that” language as I’d like to call it. You can do some Object-Oriented programming with it, but it’s somewhat clunky, verbose, and not very “idiomatic”. (That’s not to say that you shouldn’t do it!) The same goes for Functional programming. If we’d like to write Fortran code that follows this paradigm, it becomes even more awkward. You’ll need several advanced techniques to make it work, and then there are still many limitations. The inability to chain function calls, the lack of tail call optimization and generic type-support, and the obstacles you have to conquer to get some kind of delayed execution; all of these sound like good reasons for not-even-trying…

In the previous post we properly encapsulated the integer level with a log_level_t derived type, achieving type safety.

Now, let’s consider the following feature request: we want to show the log level in front of the message. We could do it with decoration of course, but in the scope of this article, let’s do it in the log() subroutine directly. In this case we’re “lucky” that we can access the module-private data component level, so we can do a select case on it to determine what string should be printed:

In the previous post we introduced a derived type log_level_t. The type of data passed to the log() procedure is still an integer though:

subroutine log(message, level)
   character(len=*), intent(in) :: message
   integer, intent(in) :: level

   ! ...
end subroutine log

This doesn’t stop anyone from passing a completely meaningless integer value as the level argument to log().

Increasing type-safety

We’d like to increase type-safety and the way to do it is by using a more specific type. In our case, it would be great if we could use log_level_t as the argument type for level:

In the post about decoration we declared log levels as follows:

module logging_base
   ! ...
   integer, parameter, public :: LOG_DEBUG = 0
   integer, parameter, public :: LOG_INFO = 1
   integer, parameter, public :: LOG_WARN = 2
   integer, parameter, public :: LOG_ERROR = 3
   integer, parameter, public :: LOG_FATAL = 4
   ! ...
end module logging_base

This is somewhat useful, but requires a dedicated only mention when importing each of these constants, which isn’t very nice:

program main
   use logging_base, only: log, LOG_DEBUG, LOG_WARN
    
   ! ...
   call log('A debug message', LOG_DEBUG)
    
   ! ...
   call log('A warning', LOG_WARN)
end program main

Although we could live with that, the bigger issue remains: this is not a type-safe solution. Any integer may be passed as an argument for level, and the compiler wouldn’t warn us. For example:

Fortran projects are famous for their large modules. Actually, we may also find very large files in legacy projects written in other languages, like Java, PHP, etc. These projects sometimes have files with thousands of lines of code. Fortran projects suffer more from large files I’d say, because:

• IDE support is not great. It’s often still hard to navigate to definitions or usages. There isn’t any support for automated refactorings, like extract function, move function, add parameter, etc. You often can’t get a clear overview of the structure/outline of a file.
• There are no strict indentation rules, making it easy to create a complete mess. Not everyone uses code formatting tools. Code formatting tools that exist and are used, aren’t always very good or easily configurable.
• Fortran code can be hard to read, partially because a lack of curly braces. It’s hard to visually recognize blocks of code. Another reason is that commonly there’s no distinction in letter casing between type names, function names, variable names, etc. Other languages may use CamelCase for types, CAPS for constants, pascalCase for methods, snake_case for functions, etc. In Fortran code, it’s all snake_case.

If there’s anything we can do to make Fortran code easier to deal with, it’s to split the code into smaller parts. We need to have many more modules, each with distinct topics and concerns, so we can get a quick overview of the application’s domain and capabilities. Additionally, this will help us find the right place when we want to make changes to the code.

In the previous post we saw how to use an abstraction to compose an aggregation of services of that same abstraction. There we simply delegated a call, adding no specific behavior. But we might as well add some new behavior before or after delegating the call.

As an example, let’s try to implement a new feature in the logging module: we want to add a timestamp in front of each message, so the output becomes something like this:

With our new service abstraction logger_t we are able to easily implement more features for our logger. We can do this without affecting current user code, because their code relies only on the abstraction, never on concrete implementations.

A terminal output logger

One thing we can do is define a second logger type, one that prints each message to the terminal output (stdout). Being a logger, it should also extend the abstract logger_t type, and provide an implementation for log():

With the new file_logger_t type we were able to model a logger service as a derived type. Now it’s time to make the service abstract. That is, to leave out the implementation detail that it’s a file logger (not a terminal output logger, etc.). Users should be able to use this abstract service to log any message, to whatever the application has been configured to log to.

An abstract derived type

Allowing a user to depend on an abstract service requires the use of an abstract type. The user can import this abstract type in their module or program. Meanwhile, the factory function for the abstract logger will actually return the concrete file logger, which extends the abstract logger. For object-oriented programmers this may be a familiar approach, but it’s not a very common Fortran practice. In code it looks as follows:

We’ve seen how to define a derived type to represent a point in 2D space. We were able to add a type-bound procedure to it, and finally to make its components private and define a custom constructor for it.

In essence there are two categories of derived types:

1. Derived types that hold some data. Their type-bound procedures are solely dealing with this data, and may produce valuable information with it. The point is an example of such a derived type: we can use its data to make geometrical calculations, or we can combine it together with other points into lines, polygons, etc. This all happens in memory. In typical business applications you would consider entities, value objects and data transfer objects (DTOs) to be in this first category.
2. Derived types that can perform some task that deals with things external to the application, like a file, the terminal, a network connection, etc. Such a type doesn’t hold data inside. It is able to fetch data, or send/store data. In business applications such a type is often called a service.

In object-oriented programming, service types usually offer an abstraction. This allows the client to decouple from its specific implementation details. For example, take a logger service; it’s often beneficial for the user that they don’t have to be concerned about where the logs are written to (file, screen, log aggregation server, etc.). The user only wants to call a simple log() function to log something to whatever has been configured at some higher level. Introducing a logger abstraction will take a few posts from here, but it’s good to know that service abstraction is the goal.

In the previous post we have worked on the point_t derived type, turning the module procedure distance into a type-bound procedure:

module geometry
   ! ...

   type :: point_t
      real :: x
      real :: y
   contains
      procedure :: distance => point_distance
   end type point_t

contains

   pure function point_distance(point_1, point_2) result(the_distance)
      class(point_t), intent(in) :: point_1
      
      ! ...
   end function point_distance

end module geometry

Private data components

Type-bound procedures can help us tie relevant behaviors (procedures) to derived types. It also allows us to let the derived type keep its data to itself. This is often called data hiding, or encapsulation of state. Nothing outside the module where the derived type is defined will have (read or write) access to its data components. This can be accomplished by adding the attribute private to each data component:

In the previous post we defined a derived type point_t with real data components x and y, to represent a point in 2D space. We also wrote a function to calculate the distance between two such points:

module geometry
   implicit none(type, external)

   private
   public :: point_t
   public :: distance

   type :: point_t
      real :: x
      real :: y
   end type point_t

contains

   pure function distance(point_1, point_2) result(the_distance)
      type(point_t), intent(in) :: point_1
      type(point_t), intent(in) :: point_2
      real :: the_distance

      the_distance = sqrt((point_2%x - point_1%x)**2 + &
                          (point_2%y - point_1%y)**2)
   end function distance

end module geometry

This allowed us to pass point_t instances as function arguments to distance, in another module or in the program:

We’ve seen types and variables and functions and subroutines. Now we can get to the next level and combine both variables and procedures in a so-called derived type.

Declaring a derived type and its data components

Object-oriented programming languages have classes. It took me some time to understand that classes can be seen as “extensions of the type system”. There are often primitive types like strings, integers, etc. and we can group them as properties of a class. Thereby, the class becomes some kind of advanced, composite type.

So far we’ve put code inside the main program block of our application. Soon the need arises to move blocks of code to a better place: a procedure with a proper name living inside a module which groups related procedures by topic.

Fortran has two types of procedures:

• Functions, with arguments and a return value
• Subroutines, which are functions without a return value

Subroutines

Let’s define a new subroutine in a module:

We’ve looked at the program and module blocks that can hold our code. Now we’ll find out where to put our data.

Declaration comes first

In Fortran, every time we want to store some value in a variable, we have to explicitly declare the type and the name of the variable first. This has to happen before any other executable statement, but after imports and other declarations like the implicit none statement:

We have a basic Fortran application and a working environment to edit, compile and run it, thanks to FPM, IFX and Visual Studio Code. Let’s take a look at the structure of our very basic application.

The program keyword

The minimum amount of code for a Fortran executable is this:

program the_program
    ! Do something here
end program the_program

Comment lines start with !. To write a multi-line comment, just repeat ! at the beginning of every line.

program hello_world
   implicit none(type, external)

   print *, 'Hello, world!'
end program hello_world

Since January 2024 I’m working with a smart group of programmers at Deltares. They create and maintain software in the complex “business” domains of hydrodynamics, morphology, water quality and ecology. Their software is used to understand and predict all kinds of phenomena related to water, by which they “Enable Delta life”. And that’s not just for the Netherlands (many of us here live below sea level or close to rivers); the software is used around the world, by governments and businesses.