The Fortran core and its shared library

The project starts from the side that knows nothing about Python: a Fortran module of four functions over arrays of doubles, compiled into a shared library with a C interface. Every decision on this page is about that interface, because it is the only thing the other side will see.

The core

Four functions: the mean, the sample standard deviation, the median and an interpolated quantile. The first three return a value; the fourth takes an output argument and returns a status, because a quantile outside zero to one is a caller mistake and the C convention for that is a return code, not a message on stderr. The median and the quantile sort a copy of the input, so the caller's array is never modified.

The file core/stats.f90:

! The numerical core: plain C functions over double arrays. module stats_core use, intrinsic :: iso_c_binding, only: c_double, c_int implicit none private public :: stats_mean, stats_sd, stats_median, stats_quantile contains pure function stats_mean(x, n) result(m) bind(c, name="stats_mean") integer(c_int), value :: n real(c_double), intent(in) :: x(n) real(c_double) :: m m = sum(x) / real(n, c_double) end function stats_mean pure function stats_sd(x, n) result(s) bind(c, name="stats_sd") integer(c_int), value :: n real(c_double), intent(in) :: x(n) real(c_double) :: s, m m = stats_mean(x, n) s = sqrt(sum((x - m)**2) / real(n - 1, c_double)) end function stats_sd function stats_median(x, n) result(m) bind(c, name="stats_median") integer(c_int), value :: n real(c_double), intent(in) :: x(n) real(c_double) :: m real(c_double) :: w(n) real(c_double) :: key integer :: i, j w = x do i = 2, n key = w(i) j = i - 1 do while (j >= 1) if (w(j) <= key) exit w(j + 1) = w(j) j = j - 1 end do w(j + 1) = key end do if (mod(n, 2) == 1) then m = w((n + 1) / 2) else m = 0.5_c_double * (w(n / 2) + w(n / 2 + 1)) end if end function stats_median function stats_quantile(x, n, q, out) result(status) bind(c, name="stats_quantile") integer(c_int), value :: n real(c_double), intent(in) :: x(n) real(c_double), value :: q real(c_double), intent(out) :: out integer(c_int) :: status real(c_double) :: w(n) real(c_double) :: key, pos integer :: i, j, k status = 1 out = 0.0_c_double if (n < 1 .or. q < 0.0_c_double .or. q > 1.0_c_double) return w = x do i = 2, n key = w(i) j = i - 1 do while (j >= 1) if (w(j) <= key) exit w(j + 1) = w(j) j = j - 1 end do w(j + 1) = key end do pos = 1.0_c_double + q * real(n - 1, c_double) k = int(pos) if (k >= n) then out = w(n) else out = w(k) + (pos - real(k, c_double)) * (w(k + 1) - w(k)) end if status = 0 end function stats_quantile end module stats_core

What BIND(C) decides

BIND(C, NAME="stats_mean") does three things, and all three matter to the other side. It makes the symbol name exactly stats_mean with no __stats_MOD_ prefix, so dlsym finds it. It restricts the argument types to those ISO_C_BINDING defines, so real(c_double) is the only kind a double can meet. And it fixes the calling convention to the platform's C one, so no hidden arguments are passed.

Two details in the signatures are worth reading twice. The length is INTEGER(C_INT), VALUE, because C passes an int by value and a Fortran dummy without VALUE would be a pointer. The array is REAL(C_DOUBLE), INTENT(IN) :: X(N) without VALUE, because a C array is passed as its address. The pair is the idiom: a value scalar, a pointer array.

The quantile is INTEGER(C_INT) as its result, and its output goes through OUT. A C caller sees int stats_quantile(const double *x, int n, double q, double *out). That is the whole interface documentation, and it is worth writing it in the header the C++ caller would use.

The shared library

The build is one command in build.sh:

#!/bin/sh # Build the shared library the Python side loads. set -e cd "$(dirname "$0")" gfortran -Wall -Wextra -std=f2018 -shared -fPIC core/stats.f90 -o libstats.so echo "built libstats.so"

./build.sh
ls -l libstats.so
nm -D libstats.so | grep " T stats"

built libstats.so
-rwxr-xr-x 16624 libstats.so
000000000000161e T stats_mean
00000000000013b9 T stats_median
0000000000001155 T stats_quantile
0000000000001594 T stats_sd

-shared asks for a shared object and -fPIC makes the code position independent, which a shared object has to be. The nm -D output is the useful check: the four names are there, unmangled, and nothing else from the module is exported. A function that lost its BIND(C) would appear as __stats_core_MOD_stats_mean and the Python side would fail with AttributeError rather than a link error, which is worth knowing the first time it happens.

The library is 16,624 bytes and it links against libgfortran and libm. The Python process will load those as well; a machine that has Python but no Fortran runtime cannot load the library, which is the one deployment dependency this shape adds.

The Fortran view of the library

The first test of the library is written in Fortran, because that is the cheapest way to check the arithmetic before a second language is involved. It declares the four functions in an INTERFACE block with BIND(C), exactly as the C header would, and calls them like any other procedures:

The file core/test_core.f90:

! The Fortran side of the test suite: the same core, through its C interface. program test_core use, intrinsic :: iso_c_binding, only: c_double, c_int implicit none interface function stats_mean(x, n) bind(c, name="stats_mean") result(m) import :: c_double, c_int integer(c_int), value :: n real(c_double), intent(in) :: x(n) real(c_double) :: m end function stats_mean function stats_sd(x, n) bind(c, name="stats_sd") result(s) import :: c_double, c_int integer(c_int), value :: n real(c_double), intent(in) :: x(n) real(c_double) :: s end function stats_sd function stats_median(x, n) bind(c, name="stats_median") result(m) import :: c_double, c_int integer(c_int), value :: n real(c_double), intent(in) :: x(n) real(c_double) :: m end function stats_median function stats_quantile(x, n, q, out) bind(c, name="stats_quantile") result(status) import :: c_double, c_int integer(c_int), value :: n real(c_double), intent(in) :: x(n) real(c_double), value :: q real(c_double), intent(out) :: out integer(c_int) :: status end function stats_quantile end interface integer :: checks, failures real(c_double) :: x(4), out integer(c_int) :: status checks = 0 failures = 0 x = [2.0_c_double, 4.0_c_double, 4.0_c_double, 5.0_c_double] call check_near('mean of four values', 3.75_c_double, stats_mean(x, 4_c_int)) call check_near('sd of four values', 1.2583057392117916_c_double, stats_sd(x, 4_c_int)) call check_near('median of four values', 4.0_c_double, stats_median(x, 4_c_int)) status = stats_quantile(x, 4_c_int, 0.5_c_double, out) call check_near('quantile 0.5 of four values', 4.0_c_double, out) call check_int('quantile status is 0', 0, status) status = stats_quantile(x, 4_c_int, 1.5_c_double, out) call check_int('quantile status is 1 for q > 1', 1, status) print '(a,i0,a,i0,a)', '# ', checks, ' checks, ', failures, ' failures' if (failures > 0) error stop 1 contains subroutine check_near(name, expected, actual) character(len=*), intent(in) :: name real(c_double), intent(in) :: expected, actual checks = checks + 1 if (abs(expected - actual) <= 1.0e-12_c_double * max(1.0_c_double, abs(expected))) then print '(a,i0,a,a)', 'ok ', checks, ' - ', name else failures = failures + 1 print '(a,i0,a,a,a,es12.4,a,es12.4)', 'not ok ', checks, ' - ', name, ': expected ', expected, ', got ', actual end if end subroutine check_near subroutine check_int(name, expected, actual) character(len=*), intent(in) :: name integer, intent(in) :: expected, actual checks = checks + 1 if (expected == actual) then print '(a,i0,a,a)', 'ok ', checks, ' - ', name else failures = failures + 1 print '(a,i0,a,a,a,i0,a,i0)', 'not ok ', checks, ' - ', name, ': expected ', expected, ', got ', actual end if end subroutine check_int end program test_core

The names in the interface are the C names, so this program does not USE the module at all: it is a client of the library, like the Python wrapper. That is deliberate. A test that used the module directly would pass even if the exported names were wrong.

The Fortran test

test_core.sh builds the library, builds the test against it and runs it:

#!/bin/sh # Build and run the Fortran tests against the shared library. set -e cd "$(dirname "$0")" ./build.sh gfortran -Wall -Wextra -std=f2018 core/test_core.f90 -L. -lstats -Wl,-rpath,'$ORIGIN' -o test_core ./test_core

./test_core.sh

built libstats.so
ok 1 - mean of four values
ok 2 - sd of four values
ok 3 - median of four values
ok 4 - quantile 0.5 of four values
ok 5 - quantile status is 0
ok 6 - quantile status is 1 for q > 1
# 6 checks, 0 failures

-L. -lstats finds the library at link time and -Wl,-rpath,'$ORIGIN' records the run-time search path as the directory of the executable, so the test finds libstats.so next to itself without an environment variable. A program that copied the binary elsewhere would need LD_LIBRARY_PATH, which is the detail that makes a shared library a deployment decision rather than a link step.

Exercises

  1. Remove BIND(C) from stats_median and run nm -D. What is the symbol called now, and what would the Python side say?
  2. Add stats_range(x, n) returning max minus min. Which two files change, and what does the interface block need?
  3. Build the library with -O2. Does the size change, and do the six test lines still pass bit for bit?
  4. Move the library to a subdirectory and run the test without changing the rpath. What does the loader say, and which of the two variables fixes 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. The library is loaded by Python 3.14.10, which the next page builds on.

Article author: Arthur Isaev