Merge branch 'master' into darwin

doc/_extensions/mitgcm.py

@@ -26,7 +26,7 @@ def setup(app):
         filelink('https://github.com/MITgcm/MITgcm/blob/master/%s'))
     app.add_role(
         'varlink',
-        autolink('http://mitgcm.org/lxr/ident/MITgcm?_i=%s'))
+        autolink('http://lxr.mitgcm.org/lxr2/ident/MITgcm?_i=%s'))
 
 def filelink(pattern):
     """

doc/examples/examples.rst

@@ -277,19 +277,19 @@ For many experiments, additional information is provided in a ``README`` file lo
    and a setup using piecewise quartic ("mono" and "weno" limiter)
    advection schemes (:filelink:`input.pqm <verification/advect_xz/input.pqm>`).
 
+#. :filelink:`aim.5l_cs <verification/aim.5l_cs>` - 5-level intermediate atmospheric physics, global
+   configuration on cube sphere grid (32x32 grid points per face,
+   roughly 2.8\ :sup:`o` resolution).
+   Also contains an additional setup with a slab-ocean and
+   thermodynamic sea ice (:filelink:`input.thSI <verification/aim.5l_cs/input.thSI>`).
+
 #. :filelink:`aim.5l_Equatorial_Channel <verification/aim.5l_Equatorial_Channel>` - 5-level intermediate atmospheric
    physics, 3-D equatorial channel configuration.
 
 #. :filelink:`aim.5l_LatLon <verification/aim.5l_LatLon>` - 5-level intermediate atmospheric physics, global
    configuration, on latitude-longitude grid with 128x64x5 grid points
    (2.8\ :sup:`o` resolution).
 
-#. :filelink:`aim.5l_cs <verification/aim.5l_cs>` - 5-level intermediate atmospheric physics, global
-   configuration on cube sphere grid (32x32 grid points per face,
-   roughly 2.8\ :sup:`o` resolution).
-   Also contains an additional setup with a slab-ocean and
-   thermodynamic sea ice (:filelink:`input.thSI <verification/aim.5l_cs/input.thSI>`).
-
 #. :filelink:`cfc_example <verification/cfc_example>` - Global ocean with online computation and advection
    of CFC11 and CFC12.
 
@@ -560,6 +560,10 @@ For many experiments, additional information is provided in a ``README`` file lo
    - with package :filelink:`ggl90 <pkg/ggl90>` scheme (Gaspar et al. 1990 :cite:`gas-eta:90`) scheme
      (:filelink:`input.ggl90 <verification/vermix/input.ggl90>`)
 
+   - with :filelink:`ggl90 <pkg/ggl90>` package and parameterized Langmuir circulation effects
+     (:varlink:`useLANGMUIR` ``= .TRUE.`` in ``data.ggl90``,
+     :filelink:`input.gglLC <verification/vermix/input.gglLC>`)
+
    - with Mellor and Yamada (1982) :cite:`mellor:82` level 2 (:filelink:`pkg/my82`)
      scheme (:filelink:`input.my82 <verification/vermix/input.my82>`)
 
@@ -618,9 +622,11 @@ directories ``code_oad`` and ``input_oad`` respectively.
    TAF adjoint setup, uses package :filelink:`ecco <pkg/ecco>`.
 
 #. :filelink:`global_oce_latlon <verification/global_oce_latlon>` - Simple adjoint experiment (used also to test OpenAD compiler), TAF and OpenAD adjoint setups.
-   Also contains additional OpenAD adjoint setups:
+   Also contains additional TAF and OpenAD adjoint setups:
 
-   - using package :filelink:`ggl90 <pkg/ggl90>` (:filelink:`input_oad.ggl90 <verification/global_oce_latlon/input_oad.ggl90>`).
+   - using package :filelink:`ggl90 <pkg/ggl90>`
+     (:filelink:`input_ad.ggl90 <verification/global_oce_latlon/input_ad.ggl90>`,
+     :filelink:`input_oad.ggl90 <verification/global_oce_latlon/input_oad.ggl90>`).
 
    - using package :filelink:`kpp <pkg/kpp>` (:filelink:`input_oad.kpp <verification/global_oce_latlon/input_oad.kpp>`).
 

doc/getting_started/getting_started.rst

@@ -3170,18 +3170,27 @@ MITgcm input files for grid-related data (e.g., :varlink:`delXFile`),
 forcing fields (e.g., :varlink:`tauThetaClimRelax`),
 parameter fields (e.g., :varlink:`viscAhZfile`), etc. are assumed to
 be in "flat" or "unblocked" `binary format <https://en.wikipedia.org/wiki/Binary_file>`_.
-For historical reasons, MITgcm files use big-endian
+
+Data is expected to be in
+`Fortran/column-major order <https://en.wikipedia.org/wiki/Row-_and_column-major_order>`_,
+in the order (:math:`x`, :math:`y`, :math:`z`, :math:`t`).
+`MATLAB <https://www.mathworks.com/products/matlab.html>`_ typically
+uses F-order, while Python's `NumPy <https://numpy.org>`_ uses C-order (row-major order).
+
+For historical reasons, many large MITgcm projects use big-endian
 `byte ordering <https://en.wikipedia.org/wiki/Endianness>`_,
 **NOT** little-endian which is the more common default for today's computers.
-Thus, some care is required to create MITgcm-readable input files.
-
+Thus, some care is required to create MITgcm-readable input files.  However, if
+you prepare your own input files, it is perfectly fine to use little-endian so
+long as you also compile your executable to be little-endian compatible.
 
 - Using `MATLAB <https://www.mathworks.com/products/matlab.html>`_:
   When writing binary files, MATLAB's `fopen <https://www.mathworks.com/help/matlab/ref/fopen.html>`_
   command includes a MACHINEFORMAT option ``'b'`` which instructs MATLAB
   to read or write using big-endian byte ordering. 2-D arrays should be
-  index-ordered in MATLAB as (:math:`x`, :math:`y`) and 3-D arrays as
-  (:math:`x`, :math:`y`, :math:`z`); data is ordered from low to high in
+  index-ordered in MATLAB as (:math:`x`, :math:`y`), 3-D arrays as
+  (:math:`x`, :math:`y`, :math:`z`), and 4-D arrays as
+  (:math:`x`, :math:`y`, :math:`z`, :math:`t`); data is ordered from low to high in
   each index, with :math:`x` varying most rapidly.
 
   An example to create a bathymetry file of single-precision, floating
@@ -3217,9 +3226,17 @@ Thus, some care is required to create MITgcm-readable input files.
      h = reshape(fread(fid, Inf, accuracy), nx, ny);
      fclose(fid);
 
-- Using `Python <https://www.python.org/>`_:
+- Using Python's `NumPy <https://numpy.org>`_:
 
-  A python version of the above script to create a bathymetry file is as follows:
+  The `tofile <https://numpy.org/doc/stable/reference/generated/numpy.ndarray.tofile.html>`_
+  method on a NumPy array writes the data in
+  `row-major or C-order <https://en.wikipedia.org/wiki/Row-_and_column-major_order>`_,
+  so arrays should be shaped to take this into account for the MITgcm:
+  (:math:`y`, :math:`x`) for 2-D,  (:math:`z`, :math:`y`, :math:`x`) for 3-D, and
+  (:math:`t`, :math:`z`, :math:`y`, :math:`x`) for 4-D.
+
+  A python version of the above script can use NumPy to create a bathymetry file is as
+  follows:
 
   ::
 
@@ -3239,24 +3256,20 @@ Thus, some care is required to create MITgcm-readable input files.
     # save as single-precision (NumPy type float32) with big-endian byte ordering
     h.astype('>f4').tofile('bathy.bin')
 
-  The dtype specification ``'>f4'`` above instructs Python to write the file with
+  The dtype specification ``'>f4'`` above instructs NumPy to write the file with
   big-endian byte ordering (specifically, due to the '>') as single-precision real
   numbers (due to the 'f4' which is NumPy ``float32`` or equivalently,
   Fortran ``real*4`` format).
 
-  To read this bathymetry file back into Python, reshaped back to (ny, nx):
+  To read this bathymetry file back into NumPy, reshaped back to (ny, nx):
 
   ::
 
     h = np.fromfile('bathy.bin', '>f4').reshape(ny, nx)
 
-  where again the dtype spec instructs Python to read a big-endian
+  where again the dtype spec instructs NumPy to read a big-endian
   file of single-precision, floating point values.
 
-  Note that 2-D and 3-D arrays should be index-ordered as
-  (:math:`y`, :math:`x`) and (:math:`z`, :math:`y`, :math:`x`),
-  respectively, to be written in proper ordering for MITgcm.
-
   A more complicated example of using Python to generate input date is provided in
   :filelink:`verification/tutorial_baroclinic_gyre/input/gendata.py`.
 

doc/tag-index

@@ -1,6 +1,30 @@
     Notes on tags used in MITgcmUV
     ==============================
 
+checkpoint68v (2024/02/03)
+o model/src:
+  - change param "metricTerms" to integer param "selectMetricTerms" and change
+    param "use3dCoriolis" to integer param "select3dCoriScheme" but keep former
+    parameters in namelist (backward compatible).
+  - remove un-used param "writeStatePrec" + also in experiment param file "data"
+  - rotateGrid: fix missing 3-D Coriolis term to gV ; adjust usage restriction.
+o pkg/ecco:
+  - remove call to ECCO_CHECK from ecco_cost_init_fixed.F (but keep the other
+    call from packages_check.F) and move ECCO_SUMMARY call to ecco_check.F
+o pkg/shelfice:
+  - put the update of kTopC code within "#ifdef ALLOW_SHELFICE_REMESHING/#endif"
+    and add run-time switch "SHI_update_kTopC" to allow to turn it off.
+  - Change the initial setting of "kTopC" to remain unaffected by machine
+    truncation error and if using SHELFICEMassStepping, set it according to
+    shelficeMassInit.
+o verification/solid-body.cs-32x32x1:
+  - update set up (faster flow, smaller planet ..) and fix initial Ps condition.
+o pkg/ggl90:
+  - revisit Langmuir Circulation (LC) mixing-length calculation: fix bugs in
+    some "mxlMaxFlag" implementation and ensure it works with P-coordinate.
+    Update vermix.gglLC ref. output and add new secondary AD test (with LC on)
+    in global_oce_latlon experiment.
+
 checkpoint68u (2023/12/10)
 o pkg/seaice:
   - new/improved LSR convergence criteria (CPP: SEAICE_ALLOW_LSR_FLEX, run-time:

model/inc/PARAMS.h

@@ -1,5 +1,3 @@
-C
-
 CBOP
 C     !ROUTINE: PARAMS.h
 C     !INTERFACE:
@@ -202,7 +200,9 @@ C     saltAdvScheme       :: Salt. Horiz.advection scheme selector
 C     saltVertAdvScheme   :: Salt. Vert. Advection scheme selector
 C     selectKEscheme      :: Kinetic Energy scheme selector (Vector Inv.)
 C     selectVortScheme    :: Scheme selector for Vorticity term (Vector Inv.)
+C     selectMetricTerms   :: Scheme selector for Metric terms (Flux-Form)
 C     selectCoriScheme    :: Scheme selector for Coriolis term
+C     select3dCoriScheme  :: Scheme selector for 3-D Coriolis (in Omega.cos Phi)
 C     selectBotDragQuadr  :: quadratic bottom drag discretisation option:
 C                           =0: average KE from grid center to U & V location
 C                           =1: use local velocity norm @ U & V location
@@ -213,7 +213,6 @@ C                            with digit =0 : disable ;
 C                           = 1 : increases mixing linearly with recip_hFac
 C                           = 2,3,4 : increases mixing by recip_hFac^(2,3,4)
 C     readBinaryPrec      :: Precision used for reading binary files
-C     writeStatePrec      :: Precision used for writing model state.
 C     writeBinaryPrec     :: Precision used for writing binary files
 C     rwSuffixType        :: controls the format of the mds file suffix.
 C                          =0 (default): use iteration number (myIter, I10.10);
@@ -238,9 +237,10 @@ C-    plotLevel           :: controls printing of field maps ; higher -> more fl
      &        momForcingOutAB, tracForcingOutAB,
      &        tempAdvScheme, tempVertAdvScheme,
      &        saltAdvScheme, saltVertAdvScheme,
-     &        selectKEscheme, selectVortScheme, selectCoriScheme,
+     &        selectKEscheme, selectVortScheme, selectMetricTerms,
+     &        selectCoriScheme, select3dCoriScheme,
      &        selectBotDragQuadr, pCellMix_select,
-     &        readBinaryPrec, writeBinaryPrec, writeStatePrec,
+     &        readBinaryPrec, writeBinaryPrec,
      &        rwSuffixType, monitorSelect, debugLevel, plotLevel
       INTEGER cg2dMaxIters
       INTEGER cg2dMinItersNSA
@@ -266,11 +266,12 @@ C-    plotLevel           :: controls printing of field maps ; higher -> more fl
       INTEGER saltAdvScheme, saltVertAdvScheme
       INTEGER selectKEscheme
       INTEGER selectVortScheme
+      INTEGER selectMetricTerms
       INTEGER selectCoriScheme
+      INTEGER select3dCoriScheme
       INTEGER selectBotDragQuadr
       INTEGER pCellMix_select
       INTEGER readBinaryPrec
-      INTEGER writeStatePrec
       INTEGER writeBinaryPrec
       INTEGER rwSuffixType
       INTEGER monitorSelect
@@ -318,10 +319,8 @@ C     momForcing    :: Flag which turns external forcing of momentum on and off.
 C     momTidalForcing    :: Flag which turns tidal forcing on and off.
 C     momPressureForcing :: Flag which turns pressure term in momentum equation
 C                          on and off.
-C     metricTerms   :: Flag which turns metric terms on or off.
 C     useNHMTerms   :: If TRUE use non-hydrostatic metric terms.
 C     useCoriolis   :: Flag which turns the coriolis terms on and off.
-C     use3dCoriolis :: Turns the 3-D coriolis terms (in Omega.cos Phi) on - off
 C     useCDscheme   :: use CD-scheme to calculate Coriolis terms.
 C     vectorInvariantMomentum :: use Vector-Invariant form (mom_vecinv package)
 C                                (default = F = use mom_fluxform package)
@@ -429,9 +428,8 @@ C                        & Last iteration, in addition multiple of dumpFreq iter
      & no_slip_sides, no_slip_bottom, bottomVisc_pCell, useSmag3D,
      & useFullLeith, useStrainTensionVisc, useAreaViscLength,
      & momViscosity, momAdvection, momForcing, momTidalForcing,
-     & momPressureForcing, metricTerms, useNHMTerms,
-     & useCoriolis, use3dCoriolis,
-     & useCDscheme, vectorInvariantMomentum,
+     & momPressureForcing, useNHMTerms,
+     & useCoriolis, useCDscheme, vectorInvariantMomentum,
      & useJamartMomAdv, upwindVorticity, highOrderVorticity,
      & useAbsVorticity, upwindShear,
      & momStepping, calc_wVelocity, tempStepping, saltStepping,
@@ -489,11 +487,9 @@ C                        & Last iteration, in addition multiple of dumpFreq iter
       LOGICAL momForcing
       LOGICAL momTidalForcing
       LOGICAL momPressureForcing
-      LOGICAL metricTerms
       LOGICAL useNHMTerms
 
       LOGICAL useCoriolis
-      LOGICAL use3dCoriolis
       LOGICAL useCDscheme
       LOGICAL vectorInvariantMomentum
       LOGICAL useJamartMomAdv
@@ -765,12 +761,12 @@ C     dumpFreq      :: Frequency with which model state is written to
 C                      post-processing files ( s ).
 C     diagFreq      :: Frequency with which model writes diagnostic output
 C                      of intermediate quantities.
-C     afFacMom      :: Advection of momentum term tracer parameter
-C     vfFacMom      :: Momentum viscosity tracer parameter
-C     pfFacMom      :: Momentum pressure forcing tracer parameter
-C     cfFacMom      :: Coriolis term tracer parameter
-C     foFacMom      :: Momentum forcing tracer parameter
-C     mtFacMom      :: Metric terms tracer parameter
+C     afFacMom      :: Advection of momentum term multiplication factor
+C     vfFacMom      :: Momentum viscosity term    multiplication factor
+C     pfFacMom      :: Momentum pressure forcing  multiplication factor
+C     cfFacMom      :: Coriolis term              multiplication factor
+C     foFacMom      :: Momentum forcing           multiplication factor
+C     mtFacMom      :: Metric terms               multiplication factor
 C     cosPower      :: Power of cosine of latitude to multiply viscosity
 C     cAdjFreq      :: Frequency of convective adjustment
 C
@@ -791,8 +787,8 @@ C     convertFW2Salt :: salinity, used to convert Fresh-Water Flux to Salt Flux
 C                       (use model surface (local) value if set to -1)
 C     temp_EvPrRn :: temperature of Rain & Evap.
 C     salt_EvPrRn :: salinity of Rain & Evap.
-C     temp_addMass :: temperature of addMass array
-C     salt_addMass :: salinity of addMass array
+C     temp_addMass :: temperature of addMass field
+C     salt_addMass :: salinity of addMass field
 C        (notes: a) tracer content of Rain/Evap only used if both
 C                     NonLin_FrSurf & useRealFreshWater are set.
 C                b) use model surface (local) value if set to UNSET_RL)
@@ -1034,7 +1030,7 @@ C             derived from the orography. Implemented: 0,1 (see INI_P_GROUND)
       _RL atm_Po, atm_Cp, atm_Rd, atm_kappa, atm_Rq
       INTEGER integr_GeoPot, selectFindRoSurf
 
-C----------------------------------------
+C---+----1----+----2----+----3----+----4----+----5----+----6----+----7-|--+----|
 C-- Logical flags for selecting packages
       LOGICAL useGAD
       LOGICAL useOBCS
@@ -1099,11 +1095,9 @@ C-- Logical flags for selecting packages
      &        usePTRACERS, useGCHEM, useRBCS, useOffLine, useMATRIX,
      &        useFRAZIL, useSEAICE, useSALT_PLUME, useShelfIce,
      &        useStreamIce, useICEFRONT, useThSIce, useLand,
-     &        useATM2D, useAIM, useAtm_Phys, useFizhi, useGridAlt,
+     &        useATM2d, useAIM, useAtm_Phys, useFizhi, useGridAlt,
      &        useDiagnostics, useREGRID, useLayers, useMNC,
      &        useRunClock, useEMBED_FILES, useOASIM,
      &        useMYPACKAGE
 
-CEH3 ;;; Local Variables: ***
-CEH3 ;;; mode:fortran ***
-CEH3 ;;; End: ***
+C---+----1----+----2----+----3----+----4----+----5----+----6----+----7-|--+----|

model/src/calc_gw.F

@@ -83,7 +83,7 @@ SUBROUTINE CALC_GW(
 C     rThickC_W     :: thickness (in r-units) of W-Cell at Western Edge
 C     rThickC_S     :: thickness (in r-units) of W-Cell at Southern Edge
 C     rThickC_C     :: thickness (in r-units) of W-Cell (centered on W pt)
-C     recip_rThickC :: reciprol thickness of W-Cell (centered on W-point)
+C     recip_rThickC :: reciprocal thickness of W-Cell (centered on W-point)
 C     flx_NS        :: vertical momentum flux, meridional direction
 C     flx_EW        :: vertical momentum flux, zonal direction
 C     flxAdvUp      :: vertical mom. advective   flux, vertical direction (@ level k-1)
@@ -614,7 +614,7 @@ SUBROUTINE CALC_GW(
            ENDDO
           ENDDO
         ENDIF
-        IF ( use3dCoriolis .AND. k.GT.1 ) THEN
+        IF ( select3dCoriScheme.GE.1 .AND. k.GT.1 ) THEN
           CALL MOM_W_CORIOLIS_NH(
      I               bi,bj,k,
      I               uVel, vVel,

model/src/config_check.F

@@ -1084,12 +1084,11 @@ SUBROUTINE CONFIG_CHECK( myThid )
         CALL PRINT_ERROR( msgBuf, myThid )
         errCount = errCount + 1
        ENDIF
-       IF ( useFLT .OR. useZonal_Filt .OR. useECCO ) THEN
-        WRITE(msgBuf,'(2A)')
-     &       'CONFIG_CHECK: specifying Euler angles will probably ',
-     &       'not work with pkgs FLT, ZONAL_FLT, ECCO'
-        CALL PRINT_ERROR( msgBuf, myThid )
-        errCount = errCount + 1
+       IF ( useFLT .OR. useECCO ) THEN
+        WRITE(msgBuf,'(2A)') '** WARNING ** CONFIG_CHECK: specifying',
+     &       ' Euler angles may not work with pkgs FLT, ECCO'
+        CALL PRINT_MESSAGE( msgBuf, errorMessageUnit,
+     &                      SQUEEZE_RIGHT, myThid )
        ENDIF
       ENDIF
 

model/src/config_summary.F

@@ -461,8 +461,8 @@ SUBROUTINE CONFIG_SUMMARY( myThid )
       CALL PRINT_MESSAGE( msgBuf, ioUnit, SQUEEZE_RIGHT, myThid )
       CALL PRINT_MESSAGE(endList, ioUnit, SQUEEZE_RIGHT, myThid )
 C-----
-      CALL WRITE_0D_L( metricTerms,  INDEX_NONE, 'metricTerms =',
-     &                '  /* metric-Terms on/off flag */')
+      CALL WRITE_0D_I( selectMetricTerms, INDEX_NONE,
+     & 'selectMetricTerms=', ' /* Metric-Terms on/off flag (=0/1) */')
       CALL WRITE_0D_L( useNHMTerms,  INDEX_NONE, 'useNHMTerms =',
      &              ' /* Non-Hydrostatic Metric-Terms on/off */')
       WRITE(msgBuf,'(2A)')
@@ -475,8 +475,8 @@ SUBROUTINE CONFIG_SUMMARY( myThid )
      &  ' 2= Spherical ; 3= read from file'
       CALL PRINT_MESSAGE( msgBuf, ioUnit, SQUEEZE_RIGHT, myThid )
       CALL PRINT_MESSAGE(endList, ioUnit, SQUEEZE_RIGHT, myThid )
-      CALL WRITE_0D_L( use3dCoriolis,  INDEX_NONE,
-     & 'use3dCoriolis =', ' /* 3-D Coriolis on/off flag */')
+      CALL WRITE_0D_I( select3dCoriScheme, INDEX_NONE,
+     & 'select3dCoriScheme=', ' /* 3-D Coriolis on/off flag (=0/1) */')
       CALL WRITE_0D_L( useCoriolis,  INDEX_NONE,
      & 'useCoriolis =', '  /* Coriolis on/off flag */')
       CALL WRITE_0D_L( useCDscheme,  INDEX_NONE,