Testing Framework Update

CMakeLists.txt

@@ -50,8 +50,8 @@ add_subdirectory(${HLM_ROOT}/src/fates/fire fates_fire)
 add_subdirectory(${HLM_ROOT}/src/fates/radiation fates_radiation)
 
 # Testing directories
-add_subdirectory(${HLM_ROOT}/src/fates/testing/testing_shr test_share)
-add_subdirectory(${HLM_ROOT}/src/fates/testing/functional_testing/fire/shr fire_share)
+add_subdirectory(${HLM_ROOT}/src/fates/testing/tests/fortran_shr test_share)
+add_subdirectory(${HLM_ROOT}/src/fates/testing/tests/functional/fire/shr fire_share)
 
 # Remove shr_mpi_mod from share_sources.
 # This is needed because we want to use the mock shr_mpi_mod in place of the real one

main/FatesUtilsMod.F90

@@ -244,9 +244,9 @@ subroutine QuadraticRootsNSWC(a,b,c,root1,root2,err)
         endif
         if ( e<0.0_r8 ) then
            ! complex conjugate zeros
-           write (fates_log(),*)'error, imaginary roots detected in quadratic solve'
            err = .true.
-           call endrun(msg=errMsg(sourcefile, __LINE__))
+           call endrun(msg="imaginary roots detected in quadratic solve",                &
+            additional_msg=errMsg(sourcefile, __LINE__))
         else
             ! real zeros
             if ( b1>=0.0_r8 ) d = -d

testing/CMakeLists.txt

@@ -1,18 +1,19 @@
 # This is where you add specific test directories
 
 ## Functional tests
-add_subdirectory(functional_testing/allometry fates_allom_ftest)
-add_subdirectory(functional_testing/math_utils fates_math_ftest)
-add_subdirectory(functional_testing/fire/fuel fates_fuel_ftest)
-add_subdirectory(functional_testing/fire/ros fates_ros_ftest)
-add_subdirectory(functional_testing/patch fates_patch_ftest)
-add_subdirectory(functional_testing/fire/mortality fates_firemort_ftest)
+add_subdirectory(tests/functional/allometry fates_allom_ftest)
+add_subdirectory(tests/functional/fire/fuel fates_fuel_ftest)
+add_subdirectory(tests/functional/fire/ros fates_ros_ftest)
+add_subdirectory(tests/functional/patch fates_patch_ftest)
+add_subdirectory(tests/functional/fire/mortality fates_firemort_ftest)
 
 ## Unit tests
-add_subdirectory(unit_testing/fire_weather_test fates_fire_weather_utest)
-add_subdirectory(unit_testing/fire_fuel_test fates_fire_fuel_utest)
-add_subdirectory(unit_testing/sort_cohorts_test fates_sort_cohorts_utest)
-add_subdirectory(unit_testing/insert_cohort_test fates_insert_cohort_utest)
-add_subdirectory(unit_testing/validate_cohorts_test fates_validate_cohorts_utest)
-add_subdirectory(unit_testing/count_cohorts_test fates_count_cohorts_utest)
-add_subdirectory(unit_testing/fire_equations_test fates_fire_equations_utest)
+add_subdirectory(tests/unit/fire_weather_test fates_fire_weather_utest)
+add_subdirectory(tests/unit/fire_fuel_test fates_fire_fuel_utest)
+add_subdirectory(tests/unit/sort_cohorts_test fates_sort_cohorts_utest)
+add_subdirectory(tests/unit/insert_cohort_test fates_insert_cohort_utest)
+add_subdirectory(tests/unit/validate_cohorts_test fates_validate_cohorts_utest)
+add_subdirectory(tests/unit/count_cohorts_test fates_count_cohorts_utest)
+add_subdirectory(tests/unit/fire_equations_test fates_fire_equations_utest)
+add_subdirectory(tests/unit/quadratic_roots_test fates_quadratic_roots_utest)
+add_subdirectory(tests/unit/great_circle_test fates_great_circle_utest)

testing/README.md

@@ -0,0 +1,116 @@
+# FATES Testing Framework
+
+This directory contains the infratstructure to set up, build, and execute FATES functional
+and unit tests.
+
+## Test Definitions
+
+* **Functional Tests**: Standalone Fortran programs that exercse specific modules of the
+FATES production code. They often output NetCDF data and include a Python class for
+automated plotting and science validation. These are "hands-on" tests for developers.
+
+* **Unit Tests**: Discrete tests with a clear Pass/Fail status, utilizing **pfUnit** or
+**CTest**. These are best for testing edge cases, error handling, and logical branches
+within individual subroutines.
+
+## Environment Setup
+
+### Python Requirements
+
+The framework requires Python 3.12+ with `xarray`, `pandas`, `scipy`, `netCDF`, `numpy`,
+and `matplotlib`. You can create a compatible environment using the provided file:
+
+```bash
+conda env create --file=environment.yml
+conda activate fates_testing
+```
+
+### System Requirements
+
+While these tests do not require a host land model (e.g., CTSM/ELM), they require:
+
+* **CIME and shr**: These must be present in your source tree.
+* **Libraries**: NetCDF (C and Fortran), ESMF, and pfUnit.
+* **Machine Tags**: Valid machine and compiler configurations (e.g., NCAR Derecho/Izumi).
+If FATES is already running on your machine, these scripts should work out of the box.
+
+See `docs/cime_setup.md` for a step-by-step guide to setting up the environment on your
+own machine (Mac/Linux).
+
+## Execution
+
+### Running Functional Tests
+
+```bash
+# Run all functional tests using default parameters
+./run_functional_tests.py
+
+# Run specific tests with a custom parameter file
+./run_functional_tests.py --test-list allometry,fire --param-file my_params.json
+```
+
+### Running Unit Tests
+
+```bash
+# Run all unit tests
+./run_unit_tests.py
+```
+
+*Note: Use the `--help` flag on either script to see full options for build directories,
+skipping runs, and saving figures.*
+
+## Creating New Tests
+
+To maintain consistency, always use the boilerplate generator to start a new test.
+
+### Step 1. Generate Scaffolding
+
+Run the generator script. This updates the CMake system, adds config entries, and creates
+your test directory.
+
+```bash
+# Example: Create a new functional test named 'hydro_stress'
+./generate_empty_test.py functional --test-name hydro_stress
+```
+
+### Step 2: Implement the Fortran Logic
+
+Navigate to `tests/[unit|functional]/[test_name]` and edit the generated `.F90` or `.pf`
+file.
+
+* **Functional**: Write a standard Fortran program.
+* **Unit**: Write a pfUnit-compatible test module.
+
+### Step 3: Configure Metadata
+
+Edit `config/functional.cfg` or `config/unit.cfg`. The generator provides defaults, but
+you may need to update:
+
+* `out_file`: The name of the NetCDF file your Fortran code generates.
+* `use_param_file`: Set to `True` to pass the FATES JSON parameter file to your binary.
+* `datm_file`: (Optional) Driver file name. All driver data should be placed in `testing/tests/data`
+
+### Step 4: Python Analysis (Functional Only)
+
+The generator creates a Python file (`[test_name]_test.py`) in your test directory. Edit
+the `plot_output` method to define how your test results should be visualized or validated.
+
+## Directory Structure
+
+* `framework/`: Core logic for loading, building, and executing tests.
+* `config/`: Registry of all active tests and their arguments.
+* `tests/`: The source code for individual test cases.
+* `templates/`: Boilerplate files used by the generator.
+
+## Troubleshooting
+
+* **Missing Drivers**: If a functional tests requires a `datm_file`, ensure the file name0 in
+the `.cfg` is correct and the data is in `testing/tests/data`.
+The script will perform a pre-flight check and fail if the file is missing.
+
+* **Build Failures**: Ensure your environment modules (compiler, netcdf, esmf) match the
+configuration in your CIME machine tags. Also, if you are using a Fortran module that is
+in a file that is not currently listed in one of the `CMakeLists.txt` files, you will
+need to add it. There should be a `CMakeLists.txt` file in each subdirectory of the FATES
+source code. Add the file to the corresponding `CMakeLists.txt` inside the `fates_sources`
+list.