|
| 1 | +--- |
| 2 | +title: "Testing parallel code" |
| 3 | +teaching: |
| 4 | +exercises: |
| 5 | +--- |
| 6 | + |
| 7 | +:::::::::::::::::::::::::::::::::::::: questions |
| 8 | + |
| 9 | +- How do I unit test a procedure which makes MPI calls? |
| 10 | +- How do I easily test different numbers of MPI ranks? |
| 11 | +- How do I test a procedure which uses OMP directives? |
| 12 | +- How do I easily test different numbers of OMP threads? |
| 13 | + |
| 14 | +:::::::::::::::::::::::::::::::::::::::::::::::: |
| 15 | + |
| 16 | +::::::::::::::::::::::::::::::::::::: objectives |
| 17 | + |
| 18 | +- Understand what is different when testing parallel vs serial code. |
| 19 | + |
| 20 | +:::::::::::::::::::::::::::::::::::::::::::::::: |
| 21 | + |
| 22 | +## What's the difference? |
| 23 | + |
| 24 | +Depending on the parallelisation tool and strategy employed, the implementation of parallel code can be very different |
| 25 | +to that of serial code. This is especially true for code which utilises the message passing interface (MPI). These codes |
| 26 | +almost always contain some functionality in which processes, or ranks, communicate by exchanging messages. This message |
| 27 | +passing is often complex and will always benefit from testing. |
| 28 | + |
| 29 | +There is added complexity when testing MPI code compared to serial as the logical path through the code is changed |
| 30 | +depending on the number of ranks with which the code is executed. Therefore, it is important that we test for a range |
| 31 | +of numbers of ranks. This will require controlling the number of ranks running the src and is not something we want |
| 32 | +to implement ourselves. This limits the tools available to us. pFUnit is currently the only tool which supports |
| 33 | +testing MPI code. Therefore, we will be focusing on pFUnit for this section. |
| 34 | + |
| 35 | +## Tips for writing testable MPI code |
| 36 | + |
| 37 | +### Where possible, separate calls to the MPI library into units (subroutines or functions). |
| 38 | + |
| 39 | +If a procedure does not contain any calls to the MPI library, then it can be tested with a serial unit test. Therefore, |
| 40 | +separating MPI calls into their own units makes for a simpler test suite for most of your logic. Only, procedures with |
| 41 | +MPI library calls will require the more complex parallel pFUnit tests. |
| 42 | + |
| 43 | +### Pass the MPI communicator information into each procedure to be tested. |
| 44 | + |
| 45 | +If we pass the MPI communicator into a procedure, we can define this to be whatever we wish in our tests. This allows us |
| 46 | +to use the communicator provided by pFUnit or some other communicator specific to our problem. |
| 47 | + |
| 48 | +Creating types to wrap this information along with any other MPI specific information (neighbour ranks, etc) can be a |
| 49 | +convenient approach. |
| 50 | + |
| 51 | +## Syntax of writing MPI enabled pFUnit tests |
| 52 | + |
| 53 | +Firstly, we must change how we define our test parameters: |
| 54 | + |
| 55 | +- We now use `MPITestParameter` instead of `AbstractTestParameter`. |
| 56 | + - `MPITestParameter` inherits from `AbstractTestParameter` and provides an additional parameter in its constructor which |
| 57 | + corresponds to the number of processors for which a particular test should be ran. |
| 58 | +- We can't know for certain the rank of each process for the pFUnit communicator until the test case runs. Therefore, we |
| 59 | + now need to build arrays of input parameters with the rank of a process matching the index of the parameter array. For |
| 60 | + example, rank 0 would access index 1 of the input array during testing, rank 1 would access index 2 and so on. See below |
| 61 | + for an example. |
| 62 | + |
| 63 | +```F90 |
| 64 | +@testParameter(constructor=new_exchange_boundaries_test_params) |
| 65 | +type, extends(MPITestParameter) :: my_test_params |
| 66 | + integer, allocatable :: input(:), expected_output(:) |
| 67 | +contains |
| 68 | + procedure :: toString => my_test_params_toString |
| 69 | +end type my_test_params |
| 70 | +``` |
| 71 | + |
| 72 | +We therefore need to update how we populate our test parameters to take into account the rank indexing: |
| 73 | + |
| 74 | +```F90 |
| 75 | +function my_test_suite() result(params) |
| 76 | + type(my_test_params), allocatable :: params(:) |
| 77 | + integer, allocatable :: input(:), expected_output(:) |
| 78 | + integer, max_number_of_ranks |
| 79 | +
|
| 80 | + max_number_of_ranks = 2 |
| 81 | + allocate(params(max_number_of_ranks)) |
| 82 | + allocate(input(max_number_of_ranks)) |
| 83 | + allocate(expected_output(max_number_of_ranks)) |
| 84 | +
|
| 85 | + ! Tests with one rank |
| 86 | + input(1) = 1 |
| 87 | + expected_output(1) = 2 |
| 88 | + params(1) = my_test_params(1, input, expected_output) |
| 89 | +
|
| 90 | + ! Tests with two ranks |
| 91 | + ! rank 0 |
| 92 | + input(1) = 1 |
| 93 | + expected_output(1) = 1 |
| 94 | + ! rank 1 |
| 95 | + input(2) = 1 |
| 96 | + expected_output(2) = 1 |
| 97 | + params(2) = my_test_params(2, input, expected_output) |
| 98 | +end function my_test_suite |
| 99 | +``` |
| 100 | + |
| 101 | +We also need to change how we define our test case: |
| 102 | + |
| 103 | +- We now use `MPITestCase` instead of `ParameterizedTestCase` |
| 104 | + - `MPITestCase` provides several helpful methods for us to use whilst testing |
| 105 | + - `getProcessRank()` returns the rank of the current process allowing per rank selection of inputs and expected outputs. |
| 106 | + - `getMpiCommunicator()` returns the MPI communicator created by pFUnit to control the number of ranks per test. |
| 107 | + - `getNumProcesses()` returns the number of MPI ranks for the current test. |
| 108 | + |
| 109 | +```F90 |
| 110 | +@TestCase(testParameters={my_test_suite()}, constructor=my_test_params_to_my_test_case) |
| 111 | +type, extends(MPITestCase) :: my_test_case |
| 112 | + type(my_test_params) :: params |
| 113 | +end type my_test_case |
| 114 | +``` |
| 115 | + |
| 116 | +Finally, we ensure each process accesses the correct rank index parameters during the test |
| 117 | + |
| 118 | +```F90 |
| 119 | +@Test |
| 120 | +subroutine TestMySrcProcedure(this) |
| 121 | + class (my_test_case), intent(inout) :: this |
| 122 | +
|
| 123 | + integer :: actual_output, rank_index |
| 124 | +
|
| 125 | + rank_index = this%getProcessRank() + 1 |
| 126 | +
|
| 127 | + call my_src_procedure(this%params%input(rank_index), actual_output) |
| 128 | +
|
| 129 | + @assertEqual(this%params%expected_output(rank_index), actual_output, "Unexpected output from my_src_procedure") |
| 130 | +end subroutine TestMySrcProcedure |
| 131 | +``` |
| 132 | + |
| 133 | +::::::::::::::::::::::::::::::::::::: challenge |
| 134 | + |
| 135 | +### Challenge 1: Testing MPI parallel code |
| 136 | + |
| 137 | +Take a look at [5-testing-parallel-code/challenge](https://github.com/UCL-ARC/fortran-unit-testing-exercises/tree/main/episodes/5-testing-parallel-code/challenge) in the exercises repository. |
| 138 | + |
| 139 | +:::::::::::::::::::::::::::::::: solution |
| 140 | + |
| 141 | +A solution is provided in [5-testing-parallel-code/solution](https://github.com/UCL-ARC/fortran-unit-testing-exercises/tree/main/episodes/5-testing-parallel-code/solution). |
| 142 | + |
| 143 | +::::::::::::::::::::::::::::::::::::::::: |
| 144 | +:::::::::::::::::::::::::::::::::::::::::::::::: |
0 commit comments