Unit test infrastructure setup (#144)

Originator(s): @mwaxmonsky 

Summary (include the keyword ['closes', 'fixes', 'resolves'] and issue
number): Sets up the basic infrastructure to start enabling unit
testing. Addresses #82

Describe any changes made to the namelist: N/A

List all files eliminated and why: N/A

List all files added and what they do:
A       .github/workflows/code-coverage.yaml
A       test/unit-test/CMakeLists.txt
A       test/unit-test/include/ccpp_kinds.F90
A       test/unit-test/tests/CMakeLists.txt
A       test/unit-test/tests/utilities/CMakeLists.txt
A       test/unit-test/tests/utilities/test_state_converters.pf
- Initial round of infrastructure to start enabling unit tests.

List all existing files that have been modified, and describe the
changes: N/A
(Helpful git command: `git diff --name-status
development...<your_branch_name>`)

List any test failures: N/A

Is this a science-changing update? New physics package, algorithm
change, tuning changes, etc? No

.github/workflows/unit-tests.yaml

@@ -0,0 +1,72 @@
+name: unit-test-code-coverage
+
+on:
+  push:
+    branches:
+      - development
+      - main
+  workflow_dispatch:
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  gcc-toolchain:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout atmospheric_physics
+        uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: |
+          sudo apt update && sudo apt -y install libopenmpi-dev openmpi-bin
+
+      - name: Build pFUnit
+        run: |
+          git clone --depth 1 --branch v4.10.0 https://github.com/Goddard-Fortran-Ecosystem/pFUnit.git
+          cd pFUnit
+          pwd
+          cmake -B./build -S.
+          cd build
+          make install
+
+      - name: Build atmospheric_physics
+        run: |
+          cmake \
+            -DCMAKE_PREFIX_PATH=/home/runner/work/atmospheric_physics/atmospheric_physics/pFUnit/build/installed \
+            -DATMOSPHERIC_PHYSICS_ENABLE_CODE_COVERAGE=ON \
+            -B./build \
+            -S./test/unit-test
+          cd build
+          make
+
+      - name: Run tests
+        run: |
+          cd build && ctest -V --output-on-failure --output-junit test_results.xml
+
+      - name: Upload unit test results
+        uses: actions/upload-artifact@v4
+        with:
+          name: unit-test-results
+          path: build/test_results.xml
+
+      - name: Setup GCov
+        run: |
+          python3 -m venv venv
+          source venv/bin/activate
+          pip3 install gcovr
+
+      - name: Run Gcov
+        run: |
+          source venv/bin/activate
+          cd build
+          gcovr -r .. --filter '\.\./schemes' --html atmospheric_physics_code_coverage.html --txt
+
+      - name: Upload code coverage results
+        uses: actions/upload-artifact@v4
+        with:
+          name: code-coverage-results
+          path: build/atmospheric_physics_code_coverage.html
+

test/unit-test/CMakeLists.txt

@@ -0,0 +1,39 @@
+cmake_minimum_required(VERSION 3.17)
+
+project(atmospheric_physics VERSION 0.0.1 LANGUAGES Fortran)
+
+find_package(PFUNIT REQUIRED)
+
+if(NOT ATMOSPHERIC_PHYSICS_IS_TOP_LEVEL)
+  message(WARNING "atmospheric-physics is not integrated into the CMake build of any top level "
+                  "project yet and this CMake is for testing purposes only.  "
+                  "Making a change to this project's CMake will not impact the build of "
+                  "a parent project at this time.")
+endif()
+
+option(ATMOSPHERIC_PHYSICS_ENABLE_TESTS "Run pFUnit unit tests" OFF)
+option(ATMOSPHERIC_PHYSICS_ENABLE_CODE_COVERAGE "Run code coverage tool" OFF)
+
+if(ATMOSPHERIC_PHYSICS_ENABLE_CODE_COVERAGE)
+  add_compile_options(-O0 --coverage)
+  add_link_options(--coverage)
+endif()
+
+set(CMAKE_BUILD_TYPE Debug)
+
+set(UTILITIES_SRC
+    ../../schemes/utilities/state_converters.F90
+    ../../schemes/utilities/static_energy.F90
+    ../../schemes/utilities/physics_tendency_updaters.F90
+    include/ccpp_kinds.F90
+)
+
+add_library(utilities ${UTILITIES_SRC})
+target_compile_options(utilities PRIVATE -ffree-line-length-none)
+target_include_directories(utilities PUBLIC ${CMAKE_CURRENT_BINARY_DIR})
+
+if(ATMOSPHERIC_PHYSICS_ENABLE_TESTS OR ATMOSPHERIC_PHYSICS_ENABLE_CODE_COVERAGE)
+  enable_testing()
+  add_subdirectory(tests)
+endif()
+

test/unit-test/README.md

@@ -0,0 +1,26 @@
+# Unit Tests
+
+To add or update unit tests, follow the instructions from the [development guide](https://escomp.github.io/CAM-SIMA-docs/atmospheric_physics/development_workflow/#5-unit-testing).  Also, make sure [pFUnit](https://github.com/Goddard-Fortran-Ecosystem/pFUnit) is built and installed following the [build directions](https://github.com/Goddard-Fortran-Ecosystem/pFUnit?tab=readme-ov-file#building-and-installing-pfunit) (see the atmospheric_physics [github workflow file](../../.github/workflows/unit-tests.yaml) for a more detailed example of how to build pFUnit):
+
+```bash
+$ git clone --depth 1 --branch v4.10.0 https://github.com/Goddard-Fortran-Ecosystem/pFUnit.git
+$ cd pFUnit
+$ cmake -B./build -S.
+$ cd build
+$ make install
+```
+
+To run the tests, from the root directory of your clone, run:
+
+```bash
+$ cmake \
+    -DCMAKE_PREFIX_PATH=<path_to_pfunit>/build/installed \
+    -DATMOSPHERIC_PHYSICS_ENABLE_CODE_COVERAGE=ON \
+    -B./build \
+    -S./test/unit-test
+$ cd build
+$ make
+$ ctest -V --output-on-failure
+```
+
+Where `<path_to_pfunit>` is the path to your pfunit repository.  The install path of pFUnit may be different depending on how you've built your local verison (see the example in the [workflow file](../../.github/workflows/unit-tests.yaml)).

test/unit-test/include/ccpp_kinds.F90

@@ -0,0 +1,11 @@
+module ccpp_kinds
+
+    use ISO_FORTRAN_ENV, only: kind_phys => REAL64
+
+    implicit none
+    private
+
+    public :: kind_phys
+
+ end module ccpp_kinds
+

test/unit-test/tests/CMakeLists.txt

@@ -0,0 +1,2 @@
+add_subdirectory(utilities)
+

test/unit-test/tests/utilities/CMakeLists.txt

@@ -0,0 +1,5 @@
+add_pfunit_ctest(utilities_tests
+  TEST_SOURCES test_state_converters.pf
+  LINK_LIBRARIES utilities
+)
+

test/unit-test/tests/utilities/test_state_converters.pf

@@ -0,0 +1,27 @@
+@test
+subroutine test_temp_to_potential_temp()
+    use funit
+    use state_converters, only : temp_to_potential_temp_run
+    use ccpp_kinds, only: kind_phys
+
+    integer, parameter :: ncol = 5
+    integer, parameter :: nz   = 5
+
+    real(kind_phys) :: temp(ncol, nz)
+    real(kind_phys) :: exner(ncol, nz)
+    real(kind_phys) :: theta(ncol, nz)
+    character(len=512) :: errmsg
+    integer :: errflg
+
+    temp = 1
+    exner = 1
+    theta = 1
+
+    errmsg = ""
+    errflg = 0
+
+    call temp_to_potential_temp_run(ncol, nz, temp, exner, theta, errmsg, errflg)
+
+    @assertEqual(0, errflg)
+
+end subroutine test_temp_to_potential_temp