Initial physics file reader for CAM-SIMA (#385)

Tag name (required for release branches):
Originator(s): @mwaxmonsky @nusbaume

Description (include the issue title, and the keyword ['closes',
'fixes', 'resolves'] followed by the issue number):

This PR contains the CAM-SIMA subroutines and interfaces required for
implementing the file I/O reader object in PR
ESCOMP/atmospheric_physics#240 in a CAM-SIMA simulation.

Currently CAM-SIMA uses the Parallel I/O (PIO) system to read NetCDF
files whenever a user calls the FileIO object, and so that is what is
used for this initial implementation, but if different methods are
required in the future we can hopefully implement them in a similar but
independent fashion.

This PR also adds a new MUSICA namelist variable to fix a bug that
prevented the model from building whenever the MUSICA CCPP scheme wasn't
being used.

Describe any changes made to build system: N/A

Describe any changes made to the namelist: N/A

List any changes to the defaults for the input datasets (e.g. boundary
datasets): N/A

List all files eliminated and why: N/A

List all files added and what they do:

A       src/physics/utils/pio_reader.F90
A       src/physics/utils/pio_reader_sub.F90
 - SIMA's NetCDF file reader object implementation using PIO.

A       src/physics/utils/rrtmgp-data
- RRTMGP data files. Mostly used for testing now, but will be needed for
RRTMGP itself once the time comes (otherwise it can simply be removed).

A       src/physics/utils/musica_sima_namelist.F90
- Implement new CAM-SIMA 'musica_config' namelist variable in a
separate, non-CCPPized module.

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

M       .gitmodules
M       src/physics/ncar_ccpp
 - Updated atmospheric_physics submodule

M       cime_config/cam_autogen.py
- Make sure the 'phys_utils' directory is always available during a
build.

M       cime_config/namelist_definition_cam.xml
M       src/control/runtime_opts.F90
M       src/physics/utils/musica_ccpp_dependencies.F90
- Implement the 'musica_config' SIMA namelist option to control MUSICA
dependencies settings.

M       src/utils/string_utils.F90
 - Make 'to_lower' and 'to_upper' functions public.

If there are new failures (compared to the
`test/existing-test-failures.txt` file),
have them OK'd by the gatekeeper, note them here, and add them to the
file.
If there are baseline differences, include the test and the reason for
the
diff. What is the nature of the change? Roundoff?

derecho/intel/aux_sima:

derecho/gnu/aux_sima:

If this changes climate describe any run(s) done to evaluate the new
climate in enough detail that it(they) could be reproduced:

CAM-SIMA date used for the baseline comparison tests if different than
latest:

---------

Co-authored-by: Michael Waxmonsky <mwaxmonsky@ucar.edu>

Author: nusbaume

.gitmodules

@@ -20,9 +20,15 @@
 [submodule "ncar-physics"]
         path          = src/physics/ncar_ccpp
 	url           = https://github.com/ESCOMP/atmospheric_physics
-	fxtag         = ac83803062a5d38b92e416e1cf737d3811e20cd1
+	fxtag         = 0af2e2b80bc2f8597b685bf08b0917233ce84afa
         fxrequired    = AlwaysRequired
         fxDONOTUSEurl = https://github.com/ESCOMP/atmospheric_physics
+[submodule "rrtmgp-data"]
+	path = src/physics/utils/rrtmgp-data
+	url = https://github.com/earth-system-radiation/rrtmgp-data.git
+        fxrequired    = AlwaysRequired
+        fxtag         = v1.8
+        fxDONOTUSEurl = https://github.com/earth-system-radiation/rrtmgp-data.git
 [submodule "ccs_config"]
         path          = ccs_config
         url           = https://github.com/ESMCI/ccs_config_cesm.git

cime_config/cam_autogen.py

@@ -601,20 +601,20 @@ def generate_physics_suites(build_cache, preproc_defs, host_name,
     # So go-ahead and copy all of the source code from
     # there to the bld directory:
     if do_gen_ccpp:
-        # Set CCPP physics "utilities" path
-        atm_phys_util_dir = os.path.join(atm_schemes_path, "utilities")
+        # Set CCPP physics 'utilities' path
+        atm_phys_utilities_dir  = os.path.join(atm_schemes_path, "utilities")
 
-        # Check that directory exists
-        if not os.path.isdir(atm_phys_util_dir):
+        # Check that the directory exists
+        if not os.path.isdir(atm_phys_utilities_dir):
             # CAM-SIMA will likely not run without this, so raise an error
-            emsg = "ERROR: Unable to find CCPP physics utilities directory:\n"
-            emsg += f" {atm_phys_util_dir}\n Have you run 'git-fleximod'?"
+            emsg = "ERROR: Unable to find CCPP physics 'utilities' directory:\n"
+            emsg += f" {atm_phys_utilities_dir}\n Have you run 'git-fleximod'?"
             raise CamAutoGenError(emsg)
         # end if
 
-        # Copy all utility source files to the build directory
-        atm_phys_util_files = glob.glob(os.path.join(atm_phys_util_dir, "*.F90"))
-        for util_file in atm_phys_util_files:
+        # Copy all 'utilities' source files to the build directory
+        atm_phys_utilities_files = glob.glob(os.path.join(atm_phys_utilities_dir, "*.F90"))
+        for util_file in atm_phys_utilities_files:
             shutil.copy(util_file, physics_blddir)
         # end for
 
@@ -632,11 +632,32 @@ def generate_physics_suites(build_cache, preproc_defs, host_name,
             raise CamAutoGenError(emsg)
         # end if
 
+        # Copy all 'to_be_ccppized' source files to the build directory
         atm_phys_to_be_ccppized_files = glob.glob(os.path.join(atm_phys_to_be_ccppized_dir, "*.F90"))
         for to_be_ccppized_file in atm_phys_to_be_ccppized_files:
            shutil.copy(to_be_ccppized_file, physics_blddir)
         # end for
-    # end if
+
+        # Copy 'phys_utils' modules to the build directory,
+        # as SIMA's pio_reader module depends on them.
+        # Note: This requirement will likely disappear once
+        # the abstract File I/O interface has been moved to the
+        # CCPP-framework itself.
+        atm_phys_phys_utils_dir = os.path.join(atm_phys_top_dir, "phys_utils")
+
+        # Check that the directory exists
+        if not os.path.isdir(atm_phys_phys_utils_dir):
+            # CAM-SIMA will likely not run without this, so raise an error
+            emsg = "ERROR: Unable to find CCPP physics 'phys_utils' directory:\n"
+            emsg += f" {atm_phys_phys_utils_dir}\n Have you run 'git-fleximod'?"
+            raise CamAutoGenError(emsg)
+
+        # Copy all 'phys_utils' source files to the build directory
+        atm_phys_phys_utils_files = glob.glob(os.path.join(atm_phys_phys_utils_dir, "*.F90"))
+        for util_file in atm_phys_phys_utils_files:
+            shutil.copy(util_file, physics_blddir)
+
+    # end if (do_gen_ccpp)
 
     if do_gen_ccpp or do_gen_nl:
         # save build details in the build cache

cime_config/namelist_definition_cam.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0"?>
 
-<entry_id_pg version="0.1">
+<entry_id_pg version="2.0">
 
 <!-- Initial Conditions -->
 
@@ -364,6 +364,23 @@
     </values>
   </entry>
 
+<!-- Host model chemistry settings -->
+
+  <entry id="musica_config">
+    <type>char*256</type>
+    <category>chemistry</category>
+    <group>chemistry_nl</group>
+    <desc>
+      Configuration option for the
+      MUSICA chemistry package.
+
+      Default: none
+    </desc>
+    <values>
+      <value>none</value>
+    </values>
+  </entry>
+
 <!-- Tropopause -->
   <entry id="tropopause_climo_file">
     <type>char*256</type>

src/control/runtime_opts.F90

@@ -45,6 +45,7 @@ subroutine read_namelist(nlfilename, single_column, scmlat, scmlon)
       use inic_analytic_utils, only: analytic_ic_readnl
 
       use tropopause_climo_read, only: tropopause_climo_readnl
+      use musica_sima_namelist,  only: musica_ccpp_dependencies_readnl
 
 !      use tracers,             only: tracers_readnl
 !      use nudging,             only: nudging_readnl
@@ -102,6 +103,7 @@ subroutine read_namelist(nlfilename, single_column, scmlat, scmlon)
 !      call check_energy_readnl(nlfilename)
       call analytic_ic_readnl(nlfilename)
       call tropopause_climo_readnl(nlfilename)
+      call musica_ccpp_dependencies_readnl(nlfilename)
 !      call scam_readnl(nlfilename, single_column, scmlat, scmlon)
 !      call nudging_readnl(nlfilename)
 

src/physics/ncar_ccpp

@@ -13,7 +13,7 @@ module musica_ccpp_dependencies
 !
 !--------------------------------------------------------------------------
 
-  use ccpp_kinds, only: kind_phys
+  use ccpp_kinds,   only: kind_phys
 
   implicit none
   private
@@ -76,7 +76,7 @@ subroutine initialize_musica_species_constituents(constituents_properties, &
     use ccpp_constituent_prop_mod, only: ccpp_constituent_prop_ptr_t
     use ccpp_const_utils,          only: ccpp_const_get_idx
     use cam_logfile,               only: iulog
-    use musica_ccpp_namelist,      only: filename_of_micm_configuration
+    use musica_sima_namelist,      only: musica_config_str
 
     type(ccpp_constituent_prop_ptr_t), pointer :: constituents_properties(:)
     real(kind_phys),                   pointer :: constituents_array(:,:,:)
@@ -105,20 +105,16 @@ subroutine initialize_musica_species_constituents(constituents_properties, &
     ! Currently, we only support two types of MUSICA configurations: Chapman and Terminator,
     ! until the file I/O object is implemented. If the configuration is neither of these,
     ! an error will be thrown.
-    position = index(filename_of_micm_configuration, chapman_config) ! Check if the substring exists
-    if (position > 0) then
+    if (trim(musica_config_str) == "chapman") then
       is_chapman = .true.
       write(iulog,*) "[MUSICA Info] Using the Chapman configuriation."
+    else if (trim(musica_config_str) == "terminator") then
+      is_terminator = .true.
+      write(iulog,*) "[MUSICA Info] Using the Terminator configuriation."
     else
-      position = index(filename_of_micm_configuration, terminator_config)
-      if (position > 0) then
-        is_terminator = .true.
-        write(iulog,*) "[MUSICA Info] Using the Terminator configuriation."
-      else
-        errcode = 1
-        errmsg = "[MUSICA Error] MUSICA configuration is not found."
-        return
-      end if
+      errcode = 1
+      errmsg = "[MUSICA Error] MUSICA configuration is not found."
+      return
     end if
 
     if (is_chapman) then
@@ -136,7 +132,7 @@ subroutine initialize_musica_species_constituents(constituents_properties, &
     species_group(1) = species_constructor(&
         "cloud_liquid_water_mixing_ratio_wrt_moist_air_and_condensed_water", 0.00060_kind_phys)
 
-    if (is_chapman) then   
+    if (is_chapman) then
       species_group(2) = species_constructor("O2", 0.22474_kind_phys)
       species_group(3) = species_constructor("O", 5.3509e-10_kind_phys)
       species_group(4) = species_constructor("O1D", 5.3509e-10_kind_phys)
@@ -174,6 +170,7 @@ subroutine musica_ccpp_dependencies_init( &
     use cam_abortutils,            only: check_allocate, endrun
     use cam_logfile,               only: iulog
     use ccpp_constituent_prop_mod, only: ccpp_constituent_prop_ptr_t
+    use musica_sima_namelist,      only: musica_config_str
 
     !-----------------------------------------------------------------------
     !
@@ -192,6 +189,9 @@ subroutine musica_ccpp_dependencies_init( &
     character(len=512)          :: errmsg
     integer                     :: errcode
 
+    ! Check if a MUSICA configuration is being used.  If not then just exit.
+    if (trim(musica_config_str) == "none") return
+
     write(iulog,*) 'WARNING: Using placeholder data for MUSICA chemistry.'
 
     call initialize_musica_species_constituents(constituents_properties, &

src/physics/utils/musica_ccpp_dependencies.F90

@@ -0,0 +1,87 @@
+! Copyright (C) 2024-2025 University Corporation for Atmospheric Research
+! SPDX-License-Identifier: Apache-2.0
+module musica_sima_namelist
+!--------------------------------------------------------------------------
+!
+! This module provides namelist functionality for the "musica_ccpp_dependencies.F90"
+! file, which can't easily contain namelist read functionality directly due to CCPP
+! requirements.
+!
+! IMPORTANT: This module should be removed once "musica_ccpp_dependencies.F90",
+!            which is a temporary file, has also been removed.
+!
+!--------------------------------------------------------------------------
+
+  use shr_kind_mod, only: shr_kind_cl
+  use runtime_obj,  only: unset_str
+
+  implicit none
+  private
+
+  ! public routines
+  public :: musica_ccpp_dependencies_readnl
+
+  ! public variables
+  character(len=shr_kind_cl), public :: musica_config_str = unset_str
+
+!==============================================================================
+contains
+!==============================================================================
+
+  subroutine musica_ccpp_dependencies_readnl(nlfile)
+
+    use shr_nl_mod,     only: find_group_name => shr_nl_find_group_name
+    use shr_kind_mod,   only: shr_kind_cm
+    use mpi,            only: mpi_character
+    use spmd_utils,     only: mpicom
+    use cam_logfile,    only: iulog
+    use cam_abortutils, only: endrun
+    use spmd_utils,     only: masterproc
+    use string_utils,   only: to_lower
+
+    !-----------------------------------------------------------------------
+    !
+    ! Read CAM-SIMA's MUSICA dependencies namelist
+    !
+    !-----------------------------------------------------------------------
+
+    ! filepath for file containing namelist input
+    character(len=*), intent(in) :: nlfile
+
+    ! Local variables
+    integer                      :: unitn, ierr
+    character(len=*), parameter  :: subname = 'musica_ccpp_dependencies_readnl'
+    character(len=shr_kind_cm)   :: errmsg
+    character(len=shr_kind_cl)   :: musica_config
+
+    namelist /chemistry_nl/ musica_config
+
+    errmsg = ''
+
+    if (masterproc) then
+       open(newunit=unitn, file=trim(nlfile), status='old')
+       call find_group_name(unitn, 'chemistry_nl', status=ierr)
+       if (ierr == 0) then
+          read(unitn, chemistry_nl, iostat=ierr, iomsg=errmsg)
+          if (ierr /= 0) then
+             call endrun(subname // ':: ERROR reading namelist:' // errmsg)
+          end if
+       end if
+       close(unitn)
+    end if
+
+    ! Broadcast namelist variable
+    call mpi_bcast(musica_config, len(musica_config), mpi_character, 0, mpicom, ierr)
+
+    ! Set module variable with lower case namelist-provided string
+    musica_config_str = to_lower(musica_config)
+
+    ! Print out namelist variables
+    if (masterproc) then
+      write(iulog,*) subname, ' options:'
+      write(iulog,*) '  MUSICA Configuration option: ', trim(musica_config_str)
+    endif
+
+  end subroutine musica_ccpp_dependencies_readnl
+
+end module musica_sima_namelist