ESCOMP · jtruesdal · Aug 3, 2026 · Sep 30, 2025 · May 22, 2026 · Jun 23, 2026
diff --git a/bld/namelist_files/namelist_definition.xml b/bld/namelist_files/namelist_definition.xml
@@ -220,6 +220,53 @@
        Default: FALSE
        </entry>
 
+<entry id="Nudge_SpectralFilter" type="logical" category="nudging"
+       group="nudging_nl" valid_values="" >
+	Toggle Spectral Filtering of Nudging Tendencies ON/OFF.
+
+        Nudge_SpectralFilter - LOGICAL Option to apply spherical harminic filtering to
+                                       the model state and target data so that nudging
+                                       tendencies are only applied to scales larger than
+                                       the specified truncation.
+       Default: FALSE
+       </entry>
+
+<entry id="Nudge_SpectralNtrunc" type="integer" category="nudging"
+       group="nudging_nl" valid_values="" >
+       Set Horizonal Scale for Spectral Filtering
+
+       Nudge_SpectralNtrunc - INT The number of meridional spherical harmonic modes used
+                                  for spectral filtering. The nominal horizontal scale of
+                                  the filtering can be estimated as:
+
+                                     Hscale = PI*6350/Nudge_SpectralNtrunc
+
+                             i.e. Nudge_SpectralNtrunc=40 corresponds to a horizontal
+                                  nudging scale  Hscale~500km.
+       Default: -1
+       </entry>
+
+<entry id="Nudge_SpectralNring" type="integer" category="nudging"
+       group="nudging_nl" valid_values="" >
+       Set size of local-area grid used to suppress Sampling Errors.
+
+       Nudge_SpectralNring  - INT The number of sampling rings used for local area averaging
+                                  of spherical harmonic modes, to suppress sampling errors.
+                                  When initializing each basis, a local average of SH values
+                                  is computed for the area associated with each grid point.
+                                  SpectralNring set the number of rings of equal-area points
+                                  in this sampling domain.
+                                  Each ring (kk) contains 8*(kk-1) sample points.
+
+                                     Nudge_SpectralNring     Number of Sampling Points
+                                     -------------------     -------------------------
+                                        1                        1      (DEFAULT SampleGrid NOT used)
+                                        2                        9
+                                        3                       25
+                                        4                       49
+       Default:  1
+       </entry>
+
 <entry id="Nudge_Path" type="char*256" input_pathname="abs" category="nudging"
        group="nudging_nl" valid_values="" >
        Full pathname of analyses data to use for nudging.
@@ -307,6 +354,9 @@
          0 == OFF      (No Nudging of this variable)
          1 == CONSTANT (Spatially Uniform Nudging)
          2 == HEAVISIDE WINDOW FUNCTION
+         3 == HEAVISIDE WINDOW FUNCTION IN VERTICAL
+              and USER SPECIFIED HORIZONAL DOMAIN
+              (Specified by user via Nudge_Bwindow_File)
        Default: 0
        </entry>
 
@@ -323,6 +373,9 @@
          0 == OFF      (No Nudging of this variable)
          1 == CONSTANT (Spatially Uniform Nudging)
          2 == HEAVISIDE WINDOW FUNCTION
+         3 == HEAVISIDE WINDOW FUNCTION IN VERTICAL
+              and USER SPECIFIED HORIZONAL DOMAIN
+              (Specified by user via Nudge_Bwindow_File)
        Default: 0
        </entry>
 
@@ -339,6 +392,9 @@
          0 == OFF      (No Nudging of this variable)
          1 == CONSTANT (Spatially Uniform Nudging)
          2 == HEAVISIDE WINDOW FUNCTION
+         3 == HEAVISIDE WINDOW FUNCTION IN VERTICAL
+              and USER SPECIFIED HORIZONAL DOMAIN
+              (Specified by user via Nudge_Bwindow_File)
        Default: 0
        </entry>
 
@@ -355,6 +411,9 @@
          0 == OFF      (No Nudging of this variable)
          1 == CONSTANT (Spatially Uniform Nudging)
          2 == HEAVISIDE WINDOW FUNCTION
+         3 == HEAVISIDE WINDOW FUNCTION IN VERTICAL
+              and USER SPECIFIED HORIZONAL DOMAIN
+              (Specified by user via Nudge_Bwindow_File)
        Default: 0
        </entry>
 
@@ -367,10 +426,12 @@
 
 <entry id="Nudge_PSprof" type="integer" category="nudging"
        group="nudging_nl" valid_values="" >
-       Profile index for PS nudging.
+       Profile index for PS nudging.(Horizontal Only)
          0 == OFF      (No Nudging of this variable)
          1 == CONSTANT (Spatially Uniform Nudging)
          2 == HEAVISIDE WINDOW FUNCTION
+         3 == USER SPECIFIED HORIZONAL DOMAIN
+              (Specified by user via Nudge_Bwindow_File)
        Default: 0
        </entry>
 
@@ -381,6 +442,14 @@
        Default: 0.
        </entry>
 
+<entry id="Nudge_PSscal" type="real" category="nudging"
+	group="nudging_nl" valid_values="" >
+       Coeffcient controling the vertical influence function.
+          Nudge_PSscal < 1.0 : P'(n) = [    B(n)      ]*(Target_Ps - Model_Ps)
+          Nudge_PSscal > 1.0 : P'(n) = [(Pref/P0)**scl]*(Target_Ps - Model_Ps)
+       Default: 0.
+       </entry>
+
 <entry id="Nudge_Hwin_lat0" type="real" category="nudging"
        group="nudging_nl" valid_values="" >
        LAT0 center of Horizontal Window in degrees [-90.,90.].
@@ -461,6 +530,13 @@
        Default: FALSE
        </entry>
 
+<entry id="Nudge_Bwindow_File" type="char*256" input_pathname="abs" category="nudging"
+       group="nudging_nl" valid_values="" >
+       Filename for the Horizonal Boundary Window to use for nudging with profile option 3.
+        (e.g. '/$DIN_LOC_ROOT/atm/cam/nudging/BoundaryWindowFile.nc')
+       Default: 'BoundaryWindowFile.nc'
+       </entry>
+
 <entry id="Nudge_ZonalFilter" type="logical" category="nudging"
        group="nudging_nl" valid_values="" >
        Switch to turn on zonal mean filtering nudging.  If TRUE, the nudging scheme

diff --git a/cime_config/testdefs/testmods_dirs/cam/nudging/user_nl_cam b/cime_config/testdefs/testmods_dirs/cam/nudging/user_nl_cam
@@ -20,6 +20,11 @@
  Nudge_TimeScale_Opt = 0
  Nudge_Times_Per_Day=4
  Model_Times_Per_Day=48
+ Nudge_ZonalFilter=.false.
+ Nudge_ZonalNbasis=-1
+ Nudge_SpectralFilter=.false.
+ Nudge_SpectralNtrunc=-1
+ Nudge_SpectralNring= 1
  Nudge_Uprof  =1
  Nudge_Ucoef  =1.00
  Nudge_Vprof  =1
@@ -30,6 +35,7 @@
  Nudge_Qcoef  =0.00
  Nudge_PSprof =0
  Nudge_PScoef =0.00
+ Nudge_PSscal =0.00
  Nudge_Beg_Year =2008
  Nudge_Beg_Month=12
  Nudge_Beg_Day  =16
@@ -48,5 +54,6 @@
  Nudge_Vwin_Lindex  =5.
  Nudge_Vwin_Ldelta  =1.0
  Nudge_Vwin_Invert  =.false.
+ Nudge_Bwindow_File='BoundaryWindowFile.nc'
 /
 
diff --git a/cime_config/testdefs/testmods_dirs/cam/outfrq3s_nudging_f10_L26/user_nl_cam b/cime_config/testdefs/testmods_dirs/cam/outfrq3s_nudging_f10_L26/user_nl_cam
@@ -13,6 +13,9 @@
  Nudge_TimeScale_Opt = 0
  Nudge_Times_Per_Day=4
  Model_Times_Per_Day=48
+ Nudge_SpectralFilter=.false.
+ Nudge_SpectralNtrunc=-1
+ Nudge_SpectralNring= 1
  Nudge_Uprof  =1
  Nudge_Ucoef  =1.00
  Nudge_Vprof  =1
@@ -21,8 +24,9 @@
  Nudge_Tcoef  =1.00
  Nudge_Qprof  =1
  Nudge_Qcoef  =1.00
- Nudge_PSprof =1
- Nudge_PScoef =1.00
+ Nudge_PSprof =0
+ Nudge_PScoef =0.00
+ Nudge_PSscal =0.00
  Nudge_Beg_Year =0001
  Nudge_Beg_Month=01
  Nudge_Beg_Day  =01

diff --git a/cime_config/testdefs/testmods_dirs/cam/outfrq3s_nudging_ne5_L26/user_nl_cam b/cime_config/testdefs/testmods_dirs/cam/outfrq3s_nudging_ne5_L26/user_nl_cam
@@ -13,6 +13,9 @@
  Nudge_TimeScale_Opt = 0
  Nudge_Times_Per_Day=4
  Model_Times_Per_Day=48
+ Nudge_SpectralFilter=.false.
+ Nudge_SpectralNtrunc=-1
+ Nudge_SpectralNring= 1
  Nudge_Uprof  =1
  Nudge_Ucoef  =1.00
  Nudge_Vprof  =1
@@ -21,8 +24,9 @@
  Nudge_Tcoef  =1.00
  Nudge_Qprof  =1
  Nudge_Qcoef  =1.00
- Nudge_PSprof =1
- Nudge_PScoef =1.00
+ Nudge_PSprof =0
+ Nudge_PScoef =0.00
+ Nudge_PSscal =0.00
  Nudge_Beg_Year =0001
  Nudge_Beg_Month=01
  Nudge_Beg_Day  =01

diff --git a/doc/ChangeLog b/doc/ChangeLog
@@ -1,4 +1,101 @@
+===============================================================
+
+Tag name: cam6_4_191
+Originator(s): patc, jet, fvitt
+Date: Aug 3, 2026
+One-line Add Spectral Nudging Option and Fix Nudging Behavior When Files Are Missing- #1402
+Github PR URL: https://github.com/ESCOMP/CAM/pull/1402
+
+Purpose of changes (include the issue number and title text for each relevant GitHub issue):
+This pull request addresses issues #1393 and #1273
+
+For Issue #1273 an error exit with a message is invoked if a missing nudging file is encountered.
+
+For Issue #1393 a module for computing spherical harmonics on the physics grid is implemented. The nudging module has additional functionality that uses this module to optionally filter nudging tendencies to scales larger then a specified truncation scale.
+
+This functionality is controlled by 2 additional variables in the &nudging_nl namelist.
+Nudge_SpectralFilter- LOGICAL Option to apply spherical harminic filtering to
+the model state and target data so that nudging
+tendencies are only applied to scales larger than
+the specified truncation.
+
+Nudge_SpectralNtrunc - INT The number of meridional spherical harmonic modes used
+for spectral filtering. The nominal horizontal scale of
+the filtering can be estimated as:
+     Hscale = PI*6350/Nudge_SpectralNtrunc
+	i.e. Nudge_SpectralNtrunc=40 corresponds to a horizontal nudging scale  Hscale~500km.
+
+New Functionality was also added for PS nudging and user defined nudging windows.
+	- PS nudging is now available via namelist variables nudge_pscoef, nudge_psprof,
+	  and nudge_psscal
+        - User-defined nudging window can be specified via a netcdf file defining the
+	  horizontal boundaries and using a profile index of 3 for nudge_uprof,
+	  nudge_vprof, nudge_tprof, nudge_qprof or nudge_psprof
+
+Describe any changes made to build system: N/A
+
+Describe any changes made to the namelist:
+
+	New Namelist variables added - see nudging.F90 for more information.
+	- nudge_bwindow_file - CHAR path to the Horizonal Boundary Window file.
+	- nudge_psscal - REAL Coeffcient controling the vertical influence function.
+	- nudge_spectralfilter - LOGICAL Option to apply spherical harminic filtering to model state
+	- nudge_spectralnring - INT number of sampling rings used for local area avg of spherical harmonic modes
+	- nudge_spectralntrunc - INT number of meridional spherical harmonic modes
+	- nudge_zonalfilter - LOGICAL apply zonal mean filtering
+	- nudge_zonalnbasis - INT number of meridional modes(Legendre Polynomials) used for filtering
+
+	New Namelist Defaults
+	- nudge_pscoef 1.00 => 0.00
+	- nudge_psprof 1 => 0
+
+List any changes to the defaults for the boundary datasets: N/A
+
+Describe any substantial timing or memory changes: N/A
+
+Code reviewed by: jet, fvitt
+
+List all files eliminated:
+D       src/utils/zonal_mean_mod.F90
+
+List all files added and what they do:
+A       src/utils/ug_spectralmethods_mod.F90
+	- Refactored spectral methods which added spectral functionality and replace zonal_mean_mod.F90
+
+List all existing files that have been modified, and describe the changes:
+M       bld/namelist_files/namelist_definition.xml
+	- new spectral namelist variables
+M       cime_config/testdefs/testmods_dirs/cam/nudging/user_nl_cam
+M       cime_config/testdefs/testmods_dirs/cam/outfrq3s_nudging_f10_L26/user_nl_cam
+M       cime_config/testdefs/testmods_dirs/cam/outfrq3s_nudging_ne5_L26/user_nl_cam
+	- new  user_nl_cam files for spectral nudge testing
+M       src/physics/cam/nudging.F90
+	- refactor of nudging routine.
+M       src/physics/cam/phys_grid_ctem.F90
+	- new location for zonal_mean procedures, moved from zonal_mean_mod.F90
+M       tools/nudging/user_nl_cam-NUDGING_TEMPLATE
+	- nudgeting template
 
+If there were any failures reported from running test_driver.sh on any test
+platform, and checkin with these failures has been OK'd by the gatekeeper,
+then copy the lines from the td.*.status files for the failed tests to the
+appropriate machine below.  All failed tests must be justified.
+
+derecho/intel/aux_cam:
+    FAIL SMS_Ln9.f09_f09_mg17.F2010climo.derecho_intel.cam-nudging NLCOMP
+	- expected due to addition of new nl variables
+
+derecho/nvhpc/aux_cam: all BFB
+
+izumi/nag/aux_cam:
+  FAIL ERC_D_Ln9.f10_f10_mt232.FHIST_C5.izumi_nag.cam-outfrq3s_subcol COMPARE_base_rest
+     - pre-existing failure -- see https://github.com/ESCOMP/CAM/issues/1514
+
+izumi/gnu/aux_cam:
+  NLFAIL ERC_D_Ln9.ne5_ne5_mg37.QPC4.izumi_gnu.cam-outfrq3s_nudging_ne5_L26 NLCOMP
+     - expected due to addition of new nl variables
+
+===============================================================
 ===============================================================
 
 Tag name: cam6_4_190
@@ -1101,8 +1198,8 @@ but without RTTOV output), RTTOV will not be compiled.
 
 Describe any changes made to the namelist:
 Trigger use of COSP-RTTOV with cosp_lrttov_sim, cosp_rttov_Ninstruments, cosp_rttov_instrument_namelists
-Allows COSP output to apply simple swathing using âcosp_N_SWATHS_[INSTRUMENT_NAME]â, âcosp_SWATH_LOCALTIMES_[INSTRUMENT_NAME]â,
-âcosp_SWATH_WIDTHS_[INSTRUMENT_NAME]"
+Allows COSP output to apply simple swathing using ?cosp_N_SWATHS_[INSTRUMENT_NAME]?, ?cosp_SWATH_LOCALTIMES_[INSTRUMENT_NAME]?,
+?cosp_SWATH_WIDTHS_[INSTRUMENT_NAME]"
 
 List any changes to the defaults for the boundary datasets: N/A
 
@@ -13312,7 +13409,7 @@ Github PR URL: https://github.com/ESCOMP/CAM/pull/1117
 Purpose of changes (include the issue number and title text for each relevant GitHub issue):
   - Continuing development of gravity wave parameterization (//github.com/ESCOMP/CAM/issues/1115)
   - Added vorticity calculation to SE dycore.  Vorticity is passed to the gravity wave (GW) scheme in
-    model physics to provide a possible source for âmoving mountainâ GW, i.e., low-phase speed GW forced
+    model physics to provide a possible source for ?moving mountain? GW, i.e., low-phase speed GW forced
     by atmospheric circulations. This provides another forcing option, in addition to boundary layer
     momentum flux implemented earlier. Vorticity anomalies as sources for GW have been proposed by other
     researchers in published papers.
@@ -35744,7 +35841,7 @@ Purpose of changes (include the issue number and title text for each relevant Gi
  - add value of zmconv_parcel_pbl in the namelist #498
  - Update externals to cesm2_3_beta07 #499
  - default pecount for ne120xx needs to be increased to run "out of the box" #500
- - Update dyn_grid to read from the INI grid if the initial conditions file has dimension âncol.â Always write using the GLL grid. (no issue opened for this bug)
+ - Update dyn_grid to read from the INI grid if the initial conditions file has dimension ?ncol.? Always write using the GLL grid. (no issue opened for this bug)
 
 Describe any changes made to build system:
 
@@ -62420,7 +62517,7 @@ yellowstone/intel/aux_cam:
   SMS_D_Ln9.f19_f19.FXHIST.yellowstone_intel.cam-outfrq9s (Overall: FAIL) details:
     FAIL SMS_D_Ln9.f19_f19.FXHIST.yellowstone_intel.cam-outfrq9s NLCOMP
     FAIL SMS_D_Ln9.f19_f19.FXHIST.yellowstone_intel.cam-outfrq9s RUN time=118
-  SMS_Ld1.f09_f09.FW1850.yellowstone_intel.cam-reduced_hist1d (Overall: NLFAIâÃL) details:
+  SMS_Ld1.f09_f09.FW1850.yellowstone_intel.cam-reduced_hist1d (Overall: NLFAI?ßL) details:
     FAIL SMS_Ld1.f09_f09.FW1850.yellowstone_intel.cam-reduced_hist1d NLCOMP
 
   Run failures for SPCAM and WACCMX are pre-existing due to CLM version
@@ -64087,8 +64184,8 @@ Describe any changes made to build system:
 Describe any changes made to the namelist:
  - Added the following namelist variables for gw_rdg
      gw_rdg_do_divstream -- If .true. use separate dividing streamlines for downslope wind and
-                            flow splitting regimes (âDSâ configuration). If .false. use single
-                            dividing streamline as in Scinocca&McFarlane 2000 (âSMâ configuration).
+                            flow splitting regimes (?DS? configuration). If .false. use single
+                            dividing streamline as in Scinocca&McFarlane 2000 (?SM? configuration).
      gw_rdg_C_BetaMax_DS -- Enhancement factor for downslope wind stress in DS configuration
      gw_rdg_C_GammaMax -- Enhancement factor for depth of downslope wind regime in DS configuration
      gw_rdg_Frx0 -- Lower inverse Froude number limits on linear ramp terminating downslope wind
@@ -65069,7 +65166,7 @@ Purpose of changes:
  Modify the chemical tropopause definition poleward of 50 degrees from using a
  fixed 300 hPa level (see note for 5_4_89) to use the lapse rate tropopause at
  P > 125 hPa and the climatology if the lapse rate tropopause is found at
- P < 125 hPa or is not found. This eliminates âfalseâ tropopause detection in the
+ P < 125 hPa or is not found. This eliminates ?false? tropopause detection in the
  75 hPa < P < 125 hPa range that are not physical and have a detrimental effect on
  heterogeneous chemistry in the polar stratosphere, provides a diagnostic that can
  respond to some climate change, and gives a smoother and more physical tropopause
@@ -89667,7 +89764,7 @@ M   models/atm/cam/test/system/tests_chem_mpi
  - updates to chemistry regression tests
 
 M   models/atm/cam/src/chemistry/utils/tracer_data.F90
- -- Bugzilla â Bug 1824 -- don't use cyc_ndx_beg before it is defined
+ -- Bugzilla ? Bug 1824 -- don't use cyc_ndx_beg before it is defined
 
 If there were any failures reported from running test_driver.sh on any test
 platform, and checkin with these failures has been OK'd by the gatekeeper,