Add kernel API (#272)

Adds C and Fortran headers for the kernels in *-kernels/api subdirectories. Kernel headers are tested for consistency against Fortran front-end.

Changes the makefiles a) to not build the documentation by defaults, and b) to group the building and running of tests, so that make libs makes, um, only the libraries.
---------
Co-authored-by: Alexander Soklev <alex@makepath.com>

.github/workflows/check-api.yml

@@ -0,0 +1,34 @@
+name: Check Fortran API
+on:
+  push:
+    branches:
+    - main
+    - develop
+  pull_request:
+    branches-ignore:
+    - documentation
+  workflow_dispatch:
+
+
+jobs:
+  API:
+    runs-on: ubuntu-22.04
+    env:
+      # Core variables:
+      FC: gfortran-12
+      FCFLAGS: "-ffree-line-length-none -m64 -std=f2008 -march=native -fbounds-check -fmodule-private -fimplicit-none -finit-real=nan -g -DRTE_USE_CBOOL"
+      RRTMGP_ROOT: ${{ github.workspace }}
+      RTE_KERNELS: extern
+    steps:
+    #
+    # Check out repository under $GITHUB_WORKSPACE
+    #
+    - name: Check out code
+      uses: actions/checkout@v4
+    #
+    # Build libraries
+    #
+    - name: Build libraries
+      run: |
+        $FC --version
+        make -j4 libs

.github/workflows/continuous-integration.yml

@@ -86,14 +86,14 @@ jobs:
     #
     # Build libraries, examples and tests
     #
-    - name: Build libraries, examples and tests
+    - name: Build libraries
       run: |
         $FC --version
         make -j4 libs
     #
     # Run examples and tests
     #
-    - name: Run examples and tests
+    - name: Build and run examples and tests
       run: make -j4 tests
     #
     # Compare the results

.github/workflows/self-hosted-ci.yml

@@ -42,7 +42,7 @@ jobs:
     env:
       # Core variables:
       FC: ftn
-      FCFLAGS: ${{ matrix.fcflags }} -DRTE_USE_${{ matrix.fpmodel}}
+      FCFLAGS: ${{ matrix.fcflags }} -DRTE_USE_${{ matrix.fpmodel }}
       # Make variables:
       RRTMGP_ROOT: ${{ github.workspace }}
       RRTMGP_DATA: ${{ github.workspace }}/rrtmgp-data
@@ -93,21 +93,21 @@ jobs:
     #
     # Build libraries, examples and tests
     #
-    - name: Build libraries, examples and tests
+    - name: Build libraries
       run: |
         $FC --version
         make -j8 libs
     #
     # Run examples and tests (expect success)
     #
-    - name: Run examples and tests (expect success)
+    - name: Build and run examples and tests (expect success)
       id: run-success
       if: matrix.config-name != 'cce-gpu-openmp'
       run: make -j8 tests
     #
     # Run examples and tests (expect failure)
     #
-    - name: Run examples and tests (expect failure)
+    - name: Build and run examples and tests (expect failure)
       if: steps.run-success.outcome == 'skipped'
       run: |
         make -j8 tests && {

Makefile

@@ -1,31 +1,28 @@
 #
 # Top-level Makefile
 #
-.PHONY: libs tests check docs
-all:    libs tests check docs
+.PHONY: libs tests check
+all:    libs tests check
 
 libs:
-	$(MAKE) -C build
-	$(MAKE) -C tests
-	$(MAKE) -C examples/all-sky
-	$(MAKE) -C examples/rfmip-clear-sky
+	$(MAKE) -C build                    $@
 
 tests:
+	$(MAKE) -C tests                    $@
 	$(MAKE) -C examples/rfmip-clear-sky $@
 	$(MAKE) -C examples/all-sky         $@
-	$(MAKE) -C tests                    $@
 
 check:
+	$(MAKE) -C tests                    $@
 	$(MAKE) -C examples/rfmip-clear-sky $@
 	$(MAKE) -C examples/all-sky         $@
-	$(MAKE) -C tests                    $@
 
 docs:
 	@cd doc; ./build_documentation.sh
 
 clean:
 	$(MAKE) -C build                    $@
+	$(MAKE) -C tests                    $@
 	$(MAKE) -C examples/rfmip-clear-sky $@
 	$(MAKE) -C examples/all-sky         $@
-	$(MAKE) -C tests                    $@
 	rm -rf public

build/Makefile

@@ -12,6 +12,7 @@ RRTMGP_KERNEL_DIR = ../rrtmgp-kernels
 all:           librte.a                  librrtmgp.a \
                librtekernels.a librtef.a librrtmgpkernels.a librrtmgpf.a
 separate-libs: librtekernels.a librtef.a librrtmgpkernels.a librrtmgpf.a
+libs: all
 
 COMPILE = $(FC) $(FCFLAGS) $(FCINCLUDE) -c
 %.o: %.F90
@@ -22,23 +23,38 @@ include $(RRTMGP_DIR)/Make.depends
 include $(RTE_KERNEL_DIR)/Make.depends
 include $(RRTMGP_KERNEL_DIR)/Make.depends
 
-VPATH = $(RTE_DIR):$(RTE_KERNEL_DIR):$(RRTMGP_DIR):$(RRTMGP_KERNEL_DIR):$(GAS_OPTICS_DIR)
 #
 # If using OpenACC/OpenMP files in *-kernels/accel take precendence  
 #
 ifeq ($(RTE_KERNELS), accel)
-	VPATH = $(RTE_DIR):$(RTE_KERNEL_DIR)/accel:$(RTE_KERNEL_DIR):$(RRTMGP_DIR):$(RRTMGP_KERNEL_DIR)/accel:$(RRTMGP_KERNEL_DIR):$(GAS_OPTICS_DIR)
+	VPATH = $(RTE_KERNEL_DIR)/accel:$(RRTMGP_KERNEL_DIR)/accel
 endif
+#
+# If using external libraries just compile the interfaces 
+#
+ifeq ($(RTE_KERNELS), extern)
+	VPATH = $(RTE_KERNEL_DIR)/api:$(RRTMGP_KERNEL_DIR)/api
+endif
+VPATH += $(RTE_DIR):$(RTE_KERNEL_DIR):$(RRTMGP_DIR):$(RRTMGP_KERNEL_DIR):$(GAS_OPTICS_DIR)
 
+#
+# Complete library - kernels plus Fortran front end 
+#
 librte.a: $(RTE_FORTRAN_KERNELS) $(RTE_FORTRAN_INTERFACE)
 	ar -rvs librte.a $(RTE_FORTRAN_KERNELS) $(RTE_FORTRAN_INTERFACE)
-
+#
+# Library with just the kernels...
+#
 librtekernels.a: $(RTE_FORTRAN_KERNELS)
 	ar -rvs librtekernels.a $(RTE_FORTRAN_KERNELS)
-
+#
+# ... and just the Fortran front-end 
+#
 librtef.a: $(RTE_FORTRAN_INTERFACE)
 	ar -rvs librtef.a $(RTE_FORTRAN_INTERFACE)
-
+#
+# As with RTE, libraries with Fortran front-end and kernels, separate and combined 
+#
 librrtmgp.a: $(RRTMGP_FORTRAN_KERNELS)  $(RRTMGP_FORTRAN_INTERFACE)
 	ar -rvs librrtmgp.a $(RRTMGP_FORTRAN_KERNELS) $(RRTMGP_FORTRAN_INTERFACE)
 

examples/all-sky/Makefile

@@ -1,3 +1,4 @@
+#!/usr/bin/env make
 #
 # Location of RTE+RRTMGP libraries, module files.
 #
@@ -46,7 +47,7 @@ mo_load_coefficients.o:         mo_simple_netcdf.o
 mo_load_cloud_coefficients.o:   mo_simple_netcdf.o mo_cloud_optics_rrtmgp.o         mo_load_cloud_coefficients.F90
 mo_load_aerosol_coefficients.o: mo_simple_netcdf.o mo_aerosol_optics_rrtmgp_merra.o mo_load_aerosol_coefficients.F90
 
-tests:
+tests: rrtmgp_allsky
 	$(RUN_CMD) bash all_tests.sh  
 
 check:

examples/rfmip-clear-sky/Makefile

@@ -1,15 +1,15 @@
+#!/usr/bin/env make
 #
 # Location of RTE+RRTMGP libraries, module files.
 #
 RRTMGP_BUILD = $(RRTMGP_ROOT)/build
 #
 # RRTMGP library, module files
 #
-# LDFLAGS   += -L$(RRTMGP_BUILD)
-# LIBS      += -lrrtmgp -lrte
+LDFLAGS   += -L$(RRTMGP_BUILD)
+LIBS      += -lrrtmgp -lrte
 FCINCLUDE += -I$(RRTMGP_BUILD)
 
-#
 # netcdf Fortran module files has to be in the search path or added via environment variable FCINCLUDE e.g. 
 #FCINCLUDE += -I$(NFHOME)/include
 
@@ -38,19 +38,20 @@ ADDITIONS = mo_simple_netcdf.o mo_rfmip_io.o mo_load_coefficients.o
 
 all: rrtmgp_rfmip_lw rrtmgp_rfmip_sw
 
-rrtmgp_rfmip_lw:   rrtmgp_rfmip_lw.o   $(ADDITIONS) $(RRTMGP_BUILD)/librrtmgp.a $(RRTMGP_BUILD)/librte.a
+rrtmgp_rfmip_lw:   rrtmgp_rfmip_lw.o   $(ADDITIONS)
 
 rrtmgp_rfmip_lw.o: rrtmgp_rfmip_lw.F90 $(ADDITIONS)
 
-rrtmgp_rfmip_sw:   rrtmgp_rfmip_sw.o   $(ADDITIONS) $(RRTMGP_BUILD)/librrtmgp.a $(RRTMGP_BUILD)/librte.a
+rrtmgp_rfmip_sw:   rrtmgp_rfmip_sw.o   $(ADDITIONS)
 
 rrtmgp_rfmip_sw.o: rrtmgp_rfmip_sw.F90 $(ADDITIONS)
 
 mo_rfmip_io.o:          mo_rfmip_io.F90          mo_simple_netcdf.o
 
 mo_load_coefficients.o: mo_load_coefficients.F90 mo_simple_netcdf.o
 
-tests: multiple_input4MIPs_radiation_RFMIP_UColorado-RFMIP-1-2_none.nc \
+tests: rrtmgp_rfmip_lw rrtmgp_rfmip_sw \
+       multiple_input4MIPs_radiation_RFMIP_UColorado-RFMIP-1-2_none.nc \
        rld_Efx_RTE-RRTMGP-181204_rad-irf_r1i1p1f1_gn.nc rlu_Efx_RTE-RRTMGP-181204_rad-irf_r1i1p1f1_gn.nc \
        rsd_Efx_RTE-RRTMGP-181204_rad-irf_r1i1p1f1_gn.nc rsu_Efx_RTE-RRTMGP-181204_rad-irf_r1i1p1f1_gn.nc
 	$(RUN_CMD) ./rrtmgp_rfmip_lw 8 multiple_input4MIPs_radiation_RFMIP_UColorado-RFMIP-1-2_none.nc ${RRTMGP_DATA}/rrtmgp-gas-lw-g256.nc

extensions/mo_fluxes_byband.F90

@@ -156,7 +156,7 @@ end function are_desired_byband
   !
   ! Spectral reduction over all points
   !
-  subroutine sum_byband(ncol, nlev, ngpt, nbnd, band_lims, spectral_flux, byband_flux) bind (C)
+  subroutine sum_byband(ncol, nlev, ngpt, nbnd, band_lims, spectral_flux, byband_flux) bind(C, name="rte_sum_byband")
     integer,                               intent(in ) :: ncol, nlev, ngpt, nbnd
     integer,  dimension(2,          nbnd), intent(in ) :: band_lims
     real(wp), dimension(ncol, nlev, ngpt), intent(in ) :: spectral_flux
@@ -181,7 +181,7 @@ end subroutine sum_byband
   !
   ! Net flux: Spectral reduction over all points
   !
-  subroutine net_byband_full(ncol, nlev, ngpt, nbnd, band_lims, spectral_flux_dn, spectral_flux_up, byband_flux_net) bind (C)
+  subroutine net_byband_full(ncol, nlev, ngpt, nbnd, band_lims, spectral_flux_dn, spectral_flux_up, byband_flux_net) bind(C, name="rte_net_byband_full")
     integer,                               intent(in ) :: ncol, nlev, ngpt, nbnd
     integer,  dimension(2,          nbnd), intent(in ) :: band_lims
     real(wp), dimension(ncol, nlev, ngpt), intent(in ) :: spectral_flux_dn, spectral_flux_up