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
- Remove BIND(C) from stats_median and run nm -D. What is the symbol called now, and what would the Python side say?
- Add stats_range(x, n) returning max minus min. Which two files change, and what does the interface block need?
- Build the library with -O2. Does the size change, and do the six test lines still pass bit for bit?
- 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