Add calculation of solar zenith angle and Earth–Sun distance (#337)

Tag name (required for release branches):
Originator(s): Matt Dawson

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

Adds the calculation of solar zenith angle and Earth–Sun distance and
makes them available as CCPP standard named variables.

@nusbaume - I wasn't sure if I put the call to recalculate the orbital
properties is correct. If it isn't let me know, and I can move it.

closes #328 
Additionally:
- adds some stubbed-out dependencies needed for MUSICA, until the actual
values are available from other physics schemes or the host model
- adds some testing infrastructure needed for unit tests of this code.
Once #326 is merged in, I can update this PR to use the new unit testing
infrastructure

In draft until ESCOMP/atmospheric_physics#171 is
merged in

Describe any changes made to build system:
none

Describe any changes made to the namelist:
none

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

List all files eliminated and why:
none

List all files added and what they do:

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

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: Courtney Peverley <[email protected]>
Co-authored-by: Kuan-Chih Wang <[email protected]>

.gitignore

@@ -15,3 +15,4 @@ test_driver_*.sh
 *~
 .#*
 \#*#
+**/.vscode/

src/control/cam_comp.F90

@@ -84,25 +84,27 @@ subroutine cam_init(caseid, ctitle, model_doi_url,                         &
       !
       !-----------------------------------------------------------------------
 
-      use cam_initfiles,        only: cam_initfiles_open
-      use dyn_grid,             only: model_grid_init
-      use phys_comp,            only: phys_init
-      use phys_comp,            only: phys_register
-      use dyn_comp,             only: dyn_init
-!      use cam_restart,          only: cam_read_restart
-      use camsrfexch,           only: hub2atm_alloc, atm2hub_alloc
-      use cam_history,          only: history_init_files
-!      use history_scam,         only: scm_intht
-      use cam_pio_utils,        only: init_pio_subsystem
-      use cam_instance,         only: inst_suffix
-!      use history_defaults,     only: initialize_iop_history
-      use stepon,               only: stepon_init
-      use air_composition,      only: air_composition_init
-      use cam_ccpp_cap,         only: cam_ccpp_initialize_constituents
-      use physics_grid,         only: columns_on_task
-      use vert_coord,           only: pver
-      use phys_vars_init_check, only: mark_as_initialized
-      use tropopause_climo_read, only: tropopause_climo_read_file
+      use cam_initfiles,            only: cam_initfiles_open
+      use dyn_grid,                 only: model_grid_init
+      use phys_comp,                only: phys_init
+      use phys_comp,                only: phys_register
+      use dyn_comp,                 only: dyn_init
+!      use cam_restart,              only: cam_read_restart
+      use camsrfexch,               only: hub2atm_alloc, atm2hub_alloc
+      use cam_history,              only: history_init_files
+!      use history_scam,             only: scm_intht
+      use cam_pio_utils,            only: init_pio_subsystem
+      use cam_instance,             only: inst_suffix
+!      use history_defaults,         only: initialize_iop_history
+      use stepon,                   only: stepon_init
+      use air_composition,          only: air_composition_init
+      use cam_ccpp_cap,             only: cam_ccpp_initialize_constituents
+      use physics_grid,             only: columns_on_task
+      use vert_coord,               only: pver
+      use phys_vars_init_check,     only: mark_as_initialized
+      use tropopause_climo_read,    only: tropopause_climo_read_file
+      use musica_ccpp_dependencies, only: musica_ccpp_dependencies_init
+      use orbital_data,             only: orbital_data_init
 
       ! Arguments
       character(len=cl), intent(in) :: caseid                ! case ID
@@ -259,6 +261,16 @@ subroutine cam_init(caseid, ctitle, model_doi_url,                         &
       ! end if
       call history_init_files(model_doi_url, caseid, ctitle)
 
+      ! Temporary:  Prescribe realistic but inaccurate physical quantities
+      ! necessary for MUSICA that are currently unavailable in CAM-SIMA.
+      !
+      ! Remove this when MUSICA input data are available from CAM-SIMA or
+      ! other physics schemes.
+      call musica_ccpp_dependencies_init(columns_on_task, pver, iulog)
+
+      ! Initialize orbital data
+      call orbital_data_init(columns_on_task)
+
    end subroutine cam_init
 
    !
@@ -271,8 +283,16 @@ subroutine cam_timestep_init()
       !
       !-----------------------------------------------------------------------
 
-      use phys_comp, only: phys_timestep_init
-      use stepon,    only: stepon_timestep_init
+      use phys_comp,    only: phys_timestep_init
+      use physics_grid, only: lat_rad, lon_rad
+      use orbital_data, only: orbital_data_advance
+      use stepon,       only: stepon_timestep_init
+
+      ! Update current fractional calendar day. Needs to be updated at every timestep.
+      calday = get_curr_calday()
+
+      ! Update the orbital data
+      call orbital_data_advance(calday, lat_rad, lon_rad)
 
       ! Update timestep flags in physics state
       is_first_timestep = is_first_step()
@@ -294,9 +314,6 @@ subroutine cam_timestep_init()
       !
       call phys_timestep_init()
 
-      ! Update current fractional calendar day. Needs to be updated at every timestep.
-      calday = get_curr_calday()
-
    end subroutine cam_timestep_init
    !
    !-----------------------------------------------------------------------

src/data/registry.xml

@@ -9,6 +9,8 @@
   <metadata_file>$SRCROOT/src/control/camsrfexch.meta</metadata_file>
   <metadata_file>$SRCROOT/src/control/runtime_obj.meta</metadata_file>
   <metadata_file>$SRCROOT/src/data/physconst.meta</metadata_file>
+  <metadata_file>$SRCROOT/src/physics/utils/orbital_data.meta</metadata_file>
+  <metadata_file>$SRCROOT/src/physics/utils/musica_ccpp_dependencies.meta</metadata_file>
   <metadata_file>$SRCROOT/src/physics/utils/physics_grid.meta</metadata_file>
   <metadata_file>$SRCROOT/src/physics/utils/cam_constituents.meta</metadata_file>
   <metadata_file>$SRCROOT/src/physics/utils/tropopause_climo_read.meta</metadata_file>

src/physics/utils/musica_ccpp_dependencies.F90

@@ -0,0 +1,197 @@
+! Copyright (C) 2024 National Science Foundation-National Center for Atmospheric Research
+! SPDX-License-Identifier: Apache-2.0
+module musica_ccpp_dependencies
+!--------------------------------------------------------------------------
+!
+! This module temporarily provides data that MUSICA chemistry consumes but
+! does not produce. The values are realistic but are not based on the
+! actual model state. These should be removed as the producers of this data
+! are added to CAM-SIMA or as CCPP-compliant physics schemes.
+!
+! IMPORTANT: This module must be completely removed before doing any actual
+!            science with MUSICA chemistry in CAM-SIMA.
+!
+!--------------------------------------------------------------------------
+
+  use ccpp_kinds, only: kind_phys
+
+  implicit none
+  private
+
+  public :: musica_ccpp_dependencies_init
+
+  !> \section arg_table_musica_ccpp_dependencies Argument Table
+  !! \htmlinclude arg_table_musica_ccpp_dependencies.html
+  !!
+  integer, public, protected :: photolysis_wavelength_grid_section_dimension = 102
+  integer, public, protected :: photolysis_wavelength_grid_interface_dimension = 103
+  real(kind_phys), allocatable, public, protected :: photolysis_wavelength_grid_interfaces(:)
+  real(kind_phys), allocatable, public, protected :: extraterrestrial_radiation_flux(:)
+  real(kind_phys), allocatable, public, protected :: surface_albedo(:)
+  real(kind_phys), allocatable, public, protected :: blackbody_temperature_at_surface(:)
+  real(kind_phys), allocatable, public, protected :: cloud_area_fraction(:,:)
+
+  ! local parameters
+  character(len=*), parameter :: module_name = '(musica_ccpp_dependencies)'
+
+!==============================================================================
+contains
+!==============================================================================
+
+  subroutine musica_ccpp_dependencies_init(horizontal_dimension, &
+      vertical_layer_dimension, log_file_unit)
+
+    use cam_abortutils, only: check_allocate
+
+    !-----------------------------------------------------------------------
+    !
+    ! Initialize the MUSICA scheme dependencies.
+    !
+    !-----------------------------------------------------------------------
+
+    integer, intent(in) :: horizontal_dimension
+    integer, intent(in) :: vertical_layer_dimension
+    integer, intent(in) :: log_file_unit
+
+    integer :: error_code
+    character(len=*), parameter :: subroutine_name = &
+        trim(module_name)//':(musica_ccpp_dependencies_init)'
+
+    write(log_file_unit,*) 'WARNING: Using placeholder data for MUSICA chemistry.'
+
+    allocate(photolysis_wavelength_grid_interfaces(photolysis_wavelength_grid_interface_dimension), &
+             stat=error_code)
+    call check_allocate(error_code, subroutine_name, &
+                        'photolysis_wavelength_grid_interfaces(photolysis_wavelength_grid_interface_dimension)', &
+                        file=__FILE__, line=__LINE__)
+    allocate(extraterrestrial_radiation_flux(photolysis_wavelength_grid_section_dimension), &
+             stat=error_code)
+    call check_allocate(error_code, subroutine_name, &
+                        'extraterrestrial_radiation_flux(photolysis_wavelength_grid_section_dimension)', &
+                        file=__FILE__, line=__LINE__)
+    allocate(surface_albedo(horizontal_dimension), stat=error_code)
+    call check_allocate(error_code, subroutine_name, &
+                        'surface_albedo(horizontal_dimension)', &
+                        file=__FILE__, line=__LINE__)
+    allocate(blackbody_temperature_at_surface(horizontal_dimension), stat=error_code)
+    call check_allocate(error_code, subroutine_name, &
+                        'blackbody_temperature_at_surface(horizontal_dimension)', &
+                        file=__FILE__, line=__LINE__)
+    allocate(cloud_area_fraction(horizontal_dimension, vertical_layer_dimension), stat=error_code)
+    call check_allocate(error_code, subroutine_name, &
+                        'cloud_area_fraction(horizontal_dimension, vertical_layer_dimension)', &
+                        file=__FILE__, line=__LINE__)
+
+    surface_albedo(:) = 0.1_kind_phys
+    blackbody_temperature_at_surface(:) = 292.3_kind_phys
+    cloud_area_fraction(:,:) = 0.7_kind_phys
+    extraterrestrial_radiation_flux(:) = 1.0e14_kind_phys
+    photolysis_wavelength_grid_interfaces = (/ &
+      120.0e-9_kind_phys, &
+      121.4e-9_kind_phys, &
+      121.9e-9_kind_phys, &
+      123.5e-9_kind_phys, &
+      124.3e-9_kind_phys, &
+      125.5e-9_kind_phys, &
+      126.3e-9_kind_phys, &
+      127.1e-9_kind_phys, &
+      130.1e-9_kind_phys, &
+      131.1e-9_kind_phys, &
+      135.0e-9_kind_phys, &
+      140.0e-9_kind_phys, &
+      145.0e-9_kind_phys, &
+      150.0e-9_kind_phys, &
+      155.0e-9_kind_phys, &
+      160.0e-9_kind_phys, &
+      165.0e-9_kind_phys, &
+      168.0e-9_kind_phys, &
+      171.0e-9_kind_phys, &
+      173.0e-9_kind_phys, &
+      174.4e-9_kind_phys, &
+      175.4e-9_kind_phys, &
+      177.0e-9_kind_phys, &
+      178.6e-9_kind_phys, &
+      180.2e-9_kind_phys, &
+      181.8e-9_kind_phys, &
+      183.5e-9_kind_phys, &
+      185.2e-9_kind_phys, &
+      186.9e-9_kind_phys, &
+      188.7e-9_kind_phys, &
+      190.5e-9_kind_phys, &
+      192.3e-9_kind_phys, &
+      194.2e-9_kind_phys, &
+      196.1e-9_kind_phys, &
+      198.0e-9_kind_phys, &
+      200.0e-9_kind_phys, &
+      202.0e-9_kind_phys, &
+      204.1e-9_kind_phys, &
+      206.2e-9_kind_phys, &
+      208.0e-9_kind_phys, &
+      211.0e-9_kind_phys, &
+      214.0e-9_kind_phys, &
+      217.0e-9_kind_phys, &
+      220.0e-9_kind_phys, &
+      223.0e-9_kind_phys, &
+      226.0e-9_kind_phys, &
+      229.0e-9_kind_phys, &
+      232.0e-9_kind_phys, &
+      235.0e-9_kind_phys, &
+      238.0e-9_kind_phys, &
+      241.0e-9_kind_phys, &
+      244.0e-9_kind_phys, &
+      247.0e-9_kind_phys, &
+      250.0e-9_kind_phys, &
+      253.0e-9_kind_phys, &
+      256.0e-9_kind_phys, &
+      259.0e-9_kind_phys, &
+      263.0e-9_kind_phys, &
+      267.0e-9_kind_phys, &
+      271.0e-9_kind_phys, &
+      275.0e-9_kind_phys, &
+      279.0e-9_kind_phys, &
+      283.0e-9_kind_phys, &
+      287.0e-9_kind_phys, &
+      291.0e-9_kind_phys, &
+      295.0e-9_kind_phys, &
+      298.5e-9_kind_phys, &
+      302.5e-9_kind_phys, &
+      305.5e-9_kind_phys, &
+      308.5e-9_kind_phys, &
+      311.5e-9_kind_phys, &
+      314.5e-9_kind_phys, &
+      317.5e-9_kind_phys, &
+      322.5e-9_kind_phys, &
+      327.5e-9_kind_phys, &
+      332.5e-9_kind_phys, &
+      337.5e-9_kind_phys, &
+      342.5e-9_kind_phys, &
+      347.5e-9_kind_phys, &
+      350.0e-9_kind_phys, &
+      355.0e-9_kind_phys, &
+      360.0e-9_kind_phys, &
+      365.0e-9_kind_phys, &
+      370.0e-9_kind_phys, &
+      375.0e-9_kind_phys, &
+      380.0e-9_kind_phys, &
+      385.0e-9_kind_phys, &
+      390.0e-9_kind_phys, &
+      395.0e-9_kind_phys, &
+      400.0e-9_kind_phys, &
+      405.0e-9_kind_phys, &
+      410.0e-9_kind_phys, &
+      415.0e-9_kind_phys, &
+      420.0e-9_kind_phys, &
+      430.0e-9_kind_phys, &
+      440.0e-9_kind_phys, &
+      450.0e-9_kind_phys, &
+      500.0e-9_kind_phys, &
+      550.0e-9_kind_phys, &
+      600.0e-9_kind_phys, &
+      650.0e-9_kind_phys, &
+      700.0e-9_kind_phys, &
+      750.0e-9_kind_phys &
+    /)
+
+  end subroutine musica_ccpp_dependencies_init
+
+end module musica_ccpp_dependencies

src/physics/utils/musica_ccpp_dependencies.meta

@@ -0,0 +1,48 @@
+[ccpp-table-properties]
+  name = musica_ccpp_dependencies
+  type = module
+[ccpp-arg-table]
+  name  = musica_ccpp_dependencies
+  type  = module
+[ photolysis_wavelength_grid_section_dimension ]
+  standard_name = photolysis_wavelength_grid_section_dimension
+  units = count
+  type = integer
+  dimensions = ()
+  protected = True
+[ photolysis_wavelength_grid_interface_dimension ]
+  standard_name = photolysis_wavelength_grid_interface_dimension
+  units = count
+  type = integer
+  dimensions = ()
+  protected = True
+[ photolysis_wavelength_grid_interfaces ]
+  standard_name = photolysis_wavelength_grid_interfaces
+  units = m
+  type = real | kind = kind_phys
+  dimensions = (photolysis_wavelength_grid_interface_dimension)
+  protected = True
+[ extraterrestrial_radiation_flux ]
+  standard_name = extraterrestrial_radiation_flux
+  units = photons cm-2 s-1 nm-1
+  type = real | kind = kind_phys
+  dimensions = (photolysis_wavelength_grid_section_dimension)
+  protected = True
+[ surface_albedo ]
+  standard_name = surface_albedo_due_to_UV_and_VIS_direct
+  units = none
+  type = real | kind = kind_phys
+  dimensions = (horizontal_dimension)
+  protected = True
+[ blackbody_temperature_at_surface ]
+  standard_name = blackbody_temperature_at_surface
+  type = real | kind = kind_phys
+  units = K
+  dimensions = (horizontal_dimension)
+  protected = True
+[ cloud_area_fraction ]
+  standard_name = cloud_area_fraction
+  type = real | kind = kind_phys
+  units = fraction
+  dimensions = (horizontal_dimension,vertical_layer_dimension)
+  protected = True