Merge changes from GFDL to main (2023-04-06) #249

Created the new module remapping_attic to hold older versions of remapping code that are no longer used by MOM6. The subroutines is PosSumErrSignificant, remapByProjection, remapByDeltaZ and integrateReconOnInterval were moved to remapping_attic, where they can be tested by calling remapping_attic_unit_tests. The hard-coded old_algorithm logical module variable and the code it wraps were also eliminated. Also added a schematic description of the units of the real variables in the various routines in MOM_remapping and corrected some spelling errors. All answers are bitwise identical.

Moved interpolate_column and reintegrate_column (without changing anything) from MOM_diag_vkernels.F90 to MOM_remapping.F90 and incorporated the tests that had been in diag_vkernels_unit_tests into remapping_unit_tests. The entire MOM_diag_vkernels.F90 file was then removed. All answers are bitwise identical, although the module for two public routines was changed and a third was eliminated.

Remove missing_value arguments to interpolate_column and reintegrate_column, instead using 0 for the values in vanished cells. This change helps to address github.com/mom-ocean/issues/769. Also added comments schematically describing some of the argument units. Because 0 was already being used for the missing value (except in unit tests), all solutions are bitwise identical.

Added the new subroutine check_remapped_values with the duplicative error checking code in remapping_core_h and remapping_core_w, both to reduce code volume and promote code coverage, and to make the substance of these two routines easier to follow. All answers are bitwise identical.

- Adds `.gitlab/pipeline-ci-tool.sh` to enact most of the stages of the gitlab CI pipeline - enables interactive/command-line reproduction of the pipeline - `.gitlab/pipeline-ci-tool.sh` is documented in .gitlab/README.md with instructions on how to use at the command line and what each function is doing - All commands formerly in .gitlab-ci.yml are now one-line invocations of `.gitlab/pipeline-ci-tool.sh` so .gitlab-ci.yml is now considerably smaller and easier to read with statements like `.gitlab/pipeline-ci-tool.sh mrs-compile debug_gnu` or `.gitlab/pipeline-ci-tool.sh check-params gnu` - Previously, all results were compared again the stored regression answers. This meant that any error (e.g. layout) would show up as a fail of all types. We use the regression answers to check the repro-symmetric mode and then compare everything else to repro-symmetric or other results as appropriate. This allows us to distinguish between types of errors. The GH actions are doing it this way, and we originally did this in the first forms of the pipeline, but in the last re-factor I lazily switched to using the regression answers for everything.

- The subroutine categorize_axes cannot find the axes in ice restart files and gives warnings WARNING from PE 0: categorize_axes: Failed to identify x- and y- axes in the axis list (xaxis_1, yaxis_1, Time) of a variable being read from INPUT/ice_model.res.nc - This leads to an incorrect initializations and a subsequent sat.vap.press.overflow crash when using infra/FMS2 - Same experiment runs fine with infra/FMS1 - After the fix the infra/FMS1 and infra/FMS2 answers are bitwise identical

- The subroutine categorize_axes cannot find the axes in ice restart files and gives warnings WARNING from PE 0: categorize_axes: Failed to identify x- and y- axes in the axis list (xaxis_1, yaxis_1, Time) of a variable being read from I NPUT/ice_model.res.nc - This leads to an incorrect initializations and a subsequent sat.vap.press.overflow crash when using infra/FMS2 - Same experiment runs fine with infra/FMS1 - After the fix the infra/FMS1 and infra/FMS2 answers are bitwise identical

Added a line initializing the string Cartesian to a blank string in categorize_axes, so that it not be uninitialized when it is used a few lines later.

Set the interpolation weights inside of interpolate_column to explicitly be the complement of one another, thereby saving an extra division at each point and reducing the number of variables that need to be stored, in preparation for the creation of a separate subroutine to find interface positions. This commit is mathematically equivalent to what was there before, and the extensive unit testing of interpolate_column is still passing, but it changes the value of some interpolated interface diagnostics at the level of roundoff (but not the MOM6 solutions themselves, as they do not depend on interpolate_column yet).

This patch introduces a new autoconf macro, AX_FC_CHECK_C_LIB, which confirms if the Fortran compiler can be linked to the netCDF C library. As with other netCDF tests, the nc-config tool is used if necessary (and available). This resolves some recent issues on platforms where netCDF and netCDF-Fortran are installed in separate locations, with different library directories (-L). It also resolves some false assumptions in configure.ac which presumed equivalent access by the configured C and Fortran compilers. Previously, we would test if the C compiler could be linked to netCDF, and then assume that the Fortran compiler shared the same relationship. We now use the Fortran compiler for both C and Fortran tests. This patch fixes many issues observed on MacOS systems, including some persistent problems on the GitHub Actions MacOS tests. For example, we can now use the default GCC 12 compilers, rather than forcing a rollback to GCC 11.

This patch fixes some issues with testing of C bindings in Fortran. Specifically, some tests are using a C compiler which may be unconfigured, causing unexpected errors. The autoconf script now uses the Fortran compiler to test these bindings, rather than using the C compiler to test for their existence. A new macro (AX_FC_CHECK_BIND_C) was added to run these tests. This achieves the actual goal (test of Fortran binding) on top of the original goal (availability of C function), while ensuring that the actual compiler of interest (FC) is used in the test. Two C-based tests are still present in the script for testing the size of jmp_buf and sigjmp_buf. The C compiler is now configured with the AX_MPI macro, and is only used to determine the size of these structs.

* Setup OBC segments for COBALT/OBGC tracers - These are updates required to setup OBC segments for OBGC tracers. - Since COBALT package has more than 50 tracers using the MOM6 table mechanism for setting up OBC segments is not feasible. Rather, this update delegates such setup to mechanims used in ocean_BGS tracers leaving MOM6 mechanism for native tracers intact. - Fixed issues caught by MOM6 githubCI * Add capability to change obc segment update period - COBALT tracers do not need as frequent segment bc updates and can use a larger update period to speed up the model. This commit introduces a new parameter DT_OBC_SEG_UPDATE_OBGC that can be adjusted for obc segment update period. - This commit applies the change only to BGC tracers but can easily be changed to apply for all. * Insert missing US%T_to_sec - The unit conversion factor was missing causing a crash in a newer test. * Updates from Andrew Ross - Avoid low initial values in the tracer reservoirs * Per Andrew Ross review * corrected indentation per review * Avoid using module vars per review request - Reviewer asked to avoid using module variables with "save" attributes. - This commit hides the module variables inside the existing OBC type. * Coding style corrections per review * Modification per review: do_not_log if .not.associated(CS%OBC) Co-authored-by: Robert Hallberg <[email protected]>

In this PR an option is added to use ice viscosity computed from the observed surface velocity, computed by the model and use a constant value (for debugging purposes). A new (char) parameter "ICE_VISCOSITY_COMPUTE" is introduced; its values can be "MODEL" (the ice viscosity computed by the model); "OBS" the ice viscosity is computed at the preprocessing step and read from a file (its name is defined by the parameter "ICE_STIFFNESS_FILE") into a variable with a name defined by "A_GLEN_VARNAME" parameter; "CONSANT" is a constant value defined by a parameter "A_GLEN". These changes are in MOM_ice_shelf_dynamics.F90. Minor changes are done to MOM_ice_shelf_initialize.F90 to correct units, scales.

Update from main

Added calls to get_param to set 12 input variable names in files via runtime parameters, including TIDEAMP_VARNAME, TEMP_COORD_VAR, SALT_COORD_VAR, THICKNESS_IC_VAR, INTERFACE_IC_RESCALE, TEMP_IC_VAR, SALT_IC_VAR, BASIN_VAR, TIDAL_DISSIPATION_VAR, ROUGHNESS_VARNAME, TIDEAMP_VARNAME and KH_BG_2D_VARNAME. Also added two new runtime parameters, THICKNESS_IC_RESCALE and INTERFACE_IC_RESCALE, to allow input thickness and interface height fields to be rescaled. A number of spelling errors in comments or output messages in the files that were being modified as a part of this commit, including changes in the documentation that appears in MOM_parameter_doc files. All answers are bitwise identical, but there are new entries and minor changes in many MOM_parameter_doc files.

Added calls to get_param to set 4 more input variable names in files via runtime, including U_IC_VAR, V_IC_VAR, OPEN_DY_CU_VAR and OPEN_DX_CV_VAR. Also added or amended comments describing internal variables to describe their units more consistently in MOM_shared_initialization. All answers are bitwise identical, but there may be new entries in some MOM_parameter_doc files.

Corrected a bug in converting depths read from an input file from units of cm to m when the ER03 version of tidal mixing is used. This commit will change answers when INT_TIDE_DISSIPATION = True, USE_CVMix_TIDAL = True, and TIDAL_ENERGY_TYPE = "ER03". There are no such configurations in the MOM6-examples pipeline tests, and it is not clear whether or where such a configuration has ever been used. This bug was introduced into dev/gfdl on Nov. 19, 2018 as a part of PR mom-ocean#883 in commit NOAA-GFDL@967e470, which was supposed to be a refactoring of this portion of the code without changing answers, but introduced this bug. This commit should restore solutions with impacted configurations to what they would have been before that earlier commit.

This patch removes the `build_{grid,data}.py` scripts from .testing's tc4, along with the setup of the Python infrastructure used in the .testing Makefile and GitHub Actions CI. The Python scripts have been replaced with equivalent Fortran programs which generate identical netCDF output. A new rule (`preproc`) has been added to the .testing top Makefile for generating the model input files. The netCDF compiler dependenices are configured with autoconf, currently duplicating the macros in `ac/configure.ac`. (NOTE: It may be possible to share these with a common macro in ac/m4. The configure script and Makefile are currently generated from `configure.ac` and `autoreconf`. In the future, we could simply pre-generate `configure` and add it to the repository. This patch was motivated by the inability to install recent netCDF-Python packages on systems with older gcc compilers, including our main production machine. We could have possibly resolved this by adding compiler configuration to pip, or perhaps reported the issue to the netCDF-python project for them to resolve. But the costs of relying on all this Python infrastructure is starting to exceed the benefits, and I would recommend we excise it from our test suite.

GitLab CI includes the internal testing suite (.testing) and included an explicit setup of the Python environment (`make work/local-env`). The rule has since been removed, and the command now fails. This patch removes those steps, since we no longer use Python in the tests. It also slightly reworks the reporting of test output. Instead of re-running `make test`, it uses the `make test.summary` rule to report the final result.

Added a new logical argument to interpolate_column to specify whether the interpolated interface values outside of massless layers should be masked to zero. Also refactored the code in interpolate_column to separate out the determination of the interface position from the interpolation and the masking to facilitate the extension of this code to use higher order interpolation in planned subsequent changes. All answers are bitwise identical, although there is a new mandatory argument for a public interface.

Added ALE_remap_interface_vals and ALE_remap_vertex_vals to handle the interpolation of variables that are at the interfaces atop tracer cells or above the corners of the tracers cells from one grid to another. Because these are not yet used (but have been tested in calls that will be added with the next commit) all answers are bitwise identical, but there are two new publicly visible routines.

Added REMAP_AUXILIARY_VARS to control whether to remap the accelerations that are used in the predictor step of the split RK2 time stepping scheme. Also added the new routines remap_dyn_split_rk2_aux_vars, remap_OBC_fields and remap_vertvisc_aux_vars to do the remapping, and code to call these routines when REMAP_AUXILIARY_VARS is true. By default, REMAP_AUXILIARY_VARS is false, and all answers are bitwise identical, but the entire MOM6-examples regression suite has been run with this set to true, and they do appear to give physically plausible answers in all cases, partially addressing the issue noted at github.com/NOAA-GFDL/issues/203. New entries are added to the MOM_parameter_doc files, and there are three new publicly visible routines, but by default answers do not change.

* Adds the option to set the diffusivity KHTH as horizontally varying * Can be enabled via READ_KHTH = True, filename is provided by user via KHTH_FILE * Will return error if user sets both READ_KHTH = True and KHTH > 0

* full file path is now set as INPUTDIR/KHTH_FILE, where both INPUTDIR and KHTH_FILE are runtime parameters

thickness diffusivity --> isopycnal height diffusivity

Corrected the units written to the output files for 4 diagnostics (CAu_Stokes, CAv_Stokes, area_shelf_h and sfc_mass_flux) and added missing units arguments to the get_param calls for some (mostly unlogged) parameters. The logged calls where units are added include those for EKE_MAX, NDIFF_DRHO_TOL, NDIFF_X_TOL, and IMPULSE_SOURCE_TIME, while some unnecessary carriage returns were removed in the descriptions of some of these and closely related parameters. Also added units to the comment describing the AGlen argument to initialize_ice_AGlen. All answers are bitwise identical, but there can be minor changes in the metadata of some files, and some MOM_parameter_doc and available_diags files might exhibit minor changes.

Added a missing scale factor in the DENSE_WATER_EAST_SPONGE_SALT get_param call in dense_water_initialize_sponges, and added comments describing the local variables (and their units) throughout the dense_water_initialization module. The variable set by DENSE_WATER_SILL_HEIGHT was unused and it probably was always intended to be DENSE_WATER_SILL_DEPTH, which it now is. Units arguments were also added to two of the unlogged get_param calls in this module. Without this change, this test case would not reproduce with dimensional rescaling due to a scale factor that was omitted when salinity was being rescaled on May 3, 2022, which became a part of PR mom-ocean#122 to dev/gfdl, but answers should not change when dimensional rescaling of salinities is not used. All answers and output in the MOM6-examples test suite are bitwise identical.

Removed meaningless units arguments from 31 get_param calls for integer, character, or logical parameters. All answers are bitwise identical, but some entries in the various parameter_doc files are changed.

This patch fixes two issues in the preprocessing of tc4. * ocean_hgrid.nc is marked as a dependency of gen_data * Multiple ouputs are handled more safely in the Makefile Expanding on the second point: We were directing one rule to produce two output files, which resulted in the rule being run twice when invoked in parallel (make -j). This has been replaced with the recommended solution for handling concurrent outputs: use one to generate both, and connect the second to the first with a separate rule. I have also generalized the `make` command in the .testing Makefile. This should address (and hopefully fix) some intermittent errors in the .testing build on Gaea.

.testing: Fix concurrency errors in tc4 rules

Add units arguments to 30 unlogged get_param calls in 4 user modules (DOME2d_initialization, ISOMIP_initialization, Kelvin_initialization and seamount_initialization) to help detect inconsistent units and scaling factors. Also added comments describing many internal real variables and their units in the DOME2d_initialization module and seamount_initialize_temperature_salinity. All answers and output are bitwise identical.

Updated the default values of remap_answer_date as declared during the specification of the wave_speed_CS, remapping_CS and regridding_CS to 99991231 (to use the very latest version of the algorithms) if these control structures are used without further initialization via optional arguments to their various initialization routines (wave_speed_init(), initialize_remapping() and initialize_regridding() or set_regrid_params()). In testing both via the TC tests and the MOM6-examples regression suite, all answers are bitwise identical, because every instance where these are used either does have an appropriate call to the initialization routine, or because (as is the case for remapping diagnostics) they are hard-coded to use the PLM remapping scheme, which is not impacted by this answer_date. It is conceivable, if unlikely, however, that there could be cases outside of the standard MOM6 code that are using this remapping capability without proper initialization of this flag, in which case answers could change. In addition, a comment was updated in the interp_CS_type indicating the cases that would be altered by changing the hard coded default answer_date there, but the default in that case was not changed. All answers and output are identical in the MOM6-examples and TC test suites.

Completed the dimensional rescaling of internal variables in the Rossby_front_initialization and BFB_initialization modules, including the addition of comments describing numerous internal variables and their units. The BFB module was more extensively modified to place logging of the module name and version before the get_param calls for this module, following the MOM6 pattern, to correct spelling errors in get_param descriptions, and to use the grid mask in the grid file rather than a reexamination of the minimum depth to determine the land-mask. The internal subroutine write_BFB_log is no longer needed and has been folded into BFB_set_coord. All answers are bitwise identical, but there are minor changes in the MOM_parameter_doc files for the buoy_forced_basin test case.

The Gaea GitLab test configuration includes two no-library compilation tests for ocean-only and ice-ocean configurations. They are currently configured to run in the same directory. Recently, several unusual I/O errors suggest problems due to concurrent testing of the builds. In order to rule out this possibility, this patch moves the ice-ocean test to a separate directory.

Documented numerous internal variables and their units in 9 vertical parameterization modules (MOM_bkgnd_mixing, MOM_bulk_mixed_layer, MOM_diabatic_aux, MOM_diabatic_driver, MOM_entrain_diffusive, MOM_kappa_shear, MOM_regularize_layers, MOM_set_diffusivity and MOM_set_viscosity). This commit includes the addition of units arguments in 9 unlogged get_param calls while 4 of these calls are now being scaled into the units used in MOM6 and then unscaled when used as the default for other parameters. A number of spelling errors were also corrected in comments. All answers and output are bitwise identical.

If the forcing ustar is exactly zero, the denominator of the momentum mixing rate term reduces to just the Coriolis parameter. With a grid construction that is symmetric about the equator, this term is also exactly zero, leading to a division by zero. To avoid this, a very small minimum ustar value is introduced, using the Earth's rotation as a velocity timescale, in the same manner as in some of the vertical parameterisations. This should prevent the denominator of the momentum mixing rate from going to zero.

Testing to see if GH actions is failing due to MPI installation

This is a first pass to refactoring the makedep script, primarily to make it PEP8 compliant.

Applying makedep to a single shot build of FMS+MOM6 (i.e. skipping the libFMS.a) I found the list of objects was incomplete because the C files were not covered by the module dependencies. makedep figures out the Fortran module dependencies and then has a list of "externals" to cover all the files that don't provide modules. "externals" are always compiled, in lieu of flinting the source code. This commit simply adds all the C object files to the list of externals. When building a library, the module dependencies are ignore and everything gets built, which is why this gap was not seen before.

Fixes all remaining PEP8 violations in ac/makedep (using line length = 132).

Documented numerous internal variables and their units in 3 lateral parameterization modules (MOM_hor_visc, MOM_lateral_mixing_coeffs, MOM_MEKE_types) and the write_cputime module. In addition, the units of a number of internal variables in the MOM_sum_output module and arguments to call_tracer_stocks were added to their descriptions in comments. This commit includes the addition of units arguments in 9 unlogged get_param calls, comments describing why parameters are not rescaled, and the rescaling of MAXVEL in hor_visc_init. A number of spelling errors were also corrected in comments. All answers and output are bitwise identical.

Add units arguments to 10 get_param calls in 7 files. Also changed comments describing the various units that might be used for geoLat or geoLon variables in the ocean_grid_type to use standard syntax. The added units arguments lead to some minor differences in MOM_parameter_doc files, but all answers are bitwise identical.

Added the new elements x_ax_unit_short and y_ax_unit_short to the ocean_grid_type and the dyn_horgrid_type to facilitate the documentation of the units of variables when they depend on the units of the axes. This includes modifying some units that were being reported as the meaningless "[k]" into the meaningful "[km]", and some units that were being reported as just "[degrees]" are now being reported with the more specific "[degrees_E]" or "[degrees_N]". These new elements are also being used in the baroclinic_zone_initialization and circle_OBCs modules, and comments describing the units of a number of the internal variables in the former module were added or modified. The description of the AXIS_UNITS parameter was expanded to provide some of the other working options. All answers are bitwise identical, but there are minor changes in a number of the MOM_parameter_doc files.

Apply dimensional rescaling of parameters that are only used as defaults for other parameters, with the rescaling explicitly undone as a part of the default argument specification. This includes de-emphasizing the use of GV%Angstrom_m, instead using GV%Angstrom_Z. As a result, fewer get_param calls read in dimensional variables without specifying a scaling factor that can be compared with their declared units. All answers and output are bitwise identical.

This addition makes sure that CS%ebt_struct is filled/computed if the user specifies KHTH_USE_EBT_STRUCT = True. Before this addition, an array for CS%ebt_struct got allocated and initialized to 0, if KHTH_USE_EBT_STRUCT = True. But this array never got filled (with values other than 0) unless the user selected any of the following options too: 1) KHTH_USE_FGNV_STREAMFUNCTION = True 2) USE_MEKE = True 3) KhTr_passivity_coeff > 0 4) MLE_front_length > 0 5) Output the diagnostic Rd_dx 6) Use resolution scaling for the a) Laplacian viscosity, b) interface height diffusivity, c) tracer diffusivity, OR d) the MEKE viscosity contribution.

Add appropriate units arguments to 11 log_param calls that were missing them. All answers are bitwise identical, but the logged output can change in some cases.

Dimensionally rescaled the internal variables with units of time in all of the top-level driver codes, from units of [s] to [T ~> s], including thing valid_time arguments to the various drivers' versions of convert_IOB_to_fluxes. All answers are bitwise identical in all cases that have been tested, although it should be noted that the mct_cap and nuopc_cap are not regularly tested as a part of the GFDL MOM6-examples test suite. These changes only apply to dimensional rescaling of timestep variables and the documentation of units.

Rescaled the dimensions of real time arguments to step_MOM and several other MOM routines that are called from the driver code, including shelf_calc_flux, iceberg_forces, iceberg_fluxes and step_offline, along with the routines offline_advection_ale and offline_advection_layer that are called subsequently. As a part of the development of this commit, it was found that one of the scaling factors for setting fluxes%ustar_berg was missing with the mct_cap, and this has been corrected. All answers and output are bitwise identical, but the scaling for several arguments in publicly visible interfaces have changed.

Specify the units of 5 parameters and applied dimensional rescaling to 14 MIN_THICKNESS or other length or viscosity parameters used in the CVMix code to appropriate units like [Z ~> m] or [Z2 T-1 ~> m2 s-1], with related changes to the rescaled units of several other internal variables. Also added comments describing a number of internal variables and their units in the MOM_CVMix and MOM_tidal_mixing code. The preliminary internal calculations in these routines now work in these [Z ~> m] units a bit longer before being recast into MKS units for the calls to the CVMix routines. The unused KPP runtime parameters CORRECT_SURFACE_LAYER_AVERAGE and FIRST_GUESS_SURFACE_LAYER_DEPTH have been marked as obsolete in comments of the code since 2015, and have now been formally obsoleted. All answers are bitwise identical, but there are changes to some MOM_parameter_doc files.

…n added

There are extra US%T_to_s scaling factors in the expressions for ustar_min that were recently introduced with dev/gfdl PR mom-ocean#251; these are duplicative of the scaling factor that is already being applied when the parameter OMEGA is read in. The resulting expressions for ustar_min therefore effectively have units of [Z s T-2 ~> m s-1] when they should have units of [Z T-1 ~> m s-1]. Because ustar_min is a tiny floor on the magnitude of ustar, there is a range of values of T_RESCALE_POWER that will give the same answers as when it is 0, but for large enough values the answers will change, perhaps dramatically. This small commit removes these extra factors. Answers will change for some large values of T_RESCALE_POWER, but they are bitwise identical in the TC testing and in MOM6-examples based regression tests with modest or negative values.

Added the runtime parameters KV_RESTRAT and RESTRAT_USTAR_MIN, to build on the improvements in github.com/NOAA-GFDL/pull/251, and to provide run-time physical parameters to avoid the potential division by zero in the mixed_layer_restrat code noted at github.com/mom-ocean/issues/1168. Once this PR is merged onto the main branch of MOM6, that issue can be closed. By default, these do not change answers in the MOM6-examples test suite, but the default value for RESTRAT_USTAR_MIN was taken from the hard-coded value in PR that PR. The six copies of the eddy growth rate timescale calculations were consolidated into a new internal function, growth_time, with some other related minor refactoring of the code. Also, mixedlayer_restrat_register_restarts now takes a unit_scale_type arguments like many other analogous routines. All answers are bitwise identical, but there are new runtime parameters or comments that lead to changes in the MOM_parameter_doc files. Also clarified in the comments sent to the MOM_parameter_doc files how VISBECK_L_SCALE works as a dimensional scaling factor when it is given a negative value, and rescaled its units when read as though it were always in m.

Corrected the pressure rescaling in calculate_density_second_derivs_scalar() that had been using an uninitialized variable. Also corrected the dimensional rescaling of dSVdT and dSVdS in calc_spec_vol_derivs_1d when temperature and salinity are being rescaled but density is not. Fortunately these do not seem to impact solutions in any production runs, and there do not appear to be any calls to calculate_density_second_derivs_scalar(). Also added checksum calls for tv%varT, tv%varS and tv%covarTS to MOM_thermo_chksum when these elements of the thermovar type are associated. Comments were also added describing the units of a number of internal variables or conversion factor in the MOM_EOS module. All answers in the MOM6-examples test suite are bitwise identical.

Corrected several bugs that would prevent cases with STOCH_EOS = True or that set a non-negative value of STANLEY_COEF from running at all. There was also extensive refactoring of the MOM_stoch_eos.F90 code. Specifically this commit makes the following changes: - The new routine stoch_eos_register_restarts was added to register the restart field associated with the MOM_stoch_EOS module before the restarts are read and before restart_registry_lock is called, which was causing any test case with STOCH_EOS=True or a positive value of STANLEY_COEF to have a fatal error. - Added a missing dimensional rescaling factor in the get_param call for KD_SMOOTH in MOM_stoch_eos_init, which would have caused cases exercising the MOM_stoch_eos options to fail the dimensional consistency tests. - MOM_stoch_eos_init was changed from a subroutine into a function that returns a logical value indicating whether this routine is used further. The order of the arguments was modified to match the order used in every other init call. - The new routine post_stoch_eos_diags was added to write diagnostics associated with the stoch_eos module. - The MOM_stoch_eos_CS type was made opaque. - The unused diag argument was removed from MOM_stoch_eos_run. - Unit arguments were added to the get_param calls for STANLEY_COEFF and STANLEY_A. - Four arrays in the MOM_stoch_eos_CS type that had been declared to optionally use static memory allocation were modified to be simple allocatables, as they are not used in the vast majority of MOM6 cases, and there is no reason to always assign memory to them. - The register_restart_field call for "stoch_eos_pattern" was revised to use the newer, more direct form rather than working via a vardesc type. - Return statements were added to several of the MOM_stoch_eos routines in the cases where they are not supposed to do anything. - The comments describing several real variables in the MOM_stoch_eos module were added or modified to describe their units using the standard format. - The module use statements at the start of the MOM_stoch_eos module were updated to reflect these changes. There were also parallel changes in MOM.F90: - Added use_stochastic_EOS element to the MOM_control_struct to indicate whether the stoch_eos calls are to be used. - MOM_stoch_eos_init is only called if temperature and salinities are state variables, as it makes no sense to call it otherwise. - Calls to stoch_eos routines were updates to reflect the new interfaces. - The contents of the MOM_stoch_eos_CS type are no longer used in MOM.F90. All answers are bitwise identical in cases that do not use dimensional rescaling, but answers will change (be corrected) in some cases that do use dimensional consistency tests. Several public interfaces to MOM_stoch_eos routines were altered, and there are changes to multiple MOM_parameter_doc files due to the new units, and due to the fact that stoch_EOS parameters are no longer being logged in cases where they are meaningless.

Corrected the domain extents used in EOS calls that are triggered with USE_STANLEY_GM and USE_STANLEY_ISO. These bugs were accidentally introduced when the changes adding the MOM_stoch_eos code to the main branch of MOM6 were merged with changes on the dev/gfdl branch. Also added a test for cases when USE_STANLEY_GM is set to true but STANLEY_COEF is negative to reset the internal versions of this flag to false with a sensible warning message rather than encountering segmentation faults. All solutions are bitwise identical in cases that worked before.

Corrected the diagnostics rho_pgf, rho_stanley_pgf and p_stanley to only be calculated if they would be written, give identical output when dimensional rescaling is applied, and be documented with the right units. Also added a test for cases when USE_STANLEY_GM is set to true but STANLEY_COEF is negative to reset the internal versions of this flag to false with a sensible warning message rather than encountering segmentation faults. All solutions are bitwise identical in cases that worked before, but there are changes in some diagnostics when they are dimensionally rescaled.

Also added tests for cases when USE_STANLEY_ISO or USE_STANLEY_ML are set to true but STANLEY_COEF is negative to reset the internal versions of these flags to false with a sensible warning message rather than encountering segmentation faults. All solutions are bitwise identical in cases that worked before.

Added a missing dimensional rescaling factor in the get_param call for the recently added variable DT_OBC_SEG_UPDATE_OBGC in initialize_MOM, which would have caused certain cases to fail the dimensional consistency tests. All answers are bitwise identical in cases that do not use dimensional rescaling, but answers will change (and be corrected) in some cases that use dimensional consistency tests.

Use dimensionally rescaled units when preparing fields to write to the MOM_IC, and then use the conversion argument to the register_restart_field call to undue this scaling, following the pattern for other calls. All answers and output are bitwise identical.

Altered the unit descriptions in comments in the new MOM_spherical_harmonics module to use standard syntax or to indicate the relationship between the units of this input and output variables. Only comments are changed, and all answers are bitwise identical.

Corrected the syntax of the unit descriptions of 6 internal variables scattered around the code. Only comments are changed, and all answers are bitwise identical.

Corrected the descriptions of 12 subroutine argument and internal variables in MOM_wave_interface, including those of 4 arguments to Stokes_PGF, and those of 8 variables related to the Waves%ddt_Us_[xy] diagnostics, which are only enabled with the STOKES_DDT flag that is labeled in the code as "developmental". This commit also includes the addition of the correct conversion arguments to the register_diag_field calls for dudt_Stokes and dvdt_Stokes diagnostics, and to the register_restart calls for Us_x_prev and Us_y_prev. This also required the addition of a unit_scale_type argument to waves_register_restarts. All solutions are bitwise identical, and the dimensional rescaling of two diagnostics are corrected.

Corrected and documents the units for the INTERNAL_TIDE_SOURCE_[XY] runtime parameters, and corrected the (unused) INTERNAL_TIDE_SOURCE_[XY] parameters as read by wave_structure_init to INTERNAL_TIDE_SOURCE_[IJ] and then commented this unused debugging code out. All answers are bitwise identical, but the MOM_parameter_doc files could change in cases that call int_tide_input_init or wave_structure_init.

Standardized documentation of axis-related variable units in user modules. Some of these use the new G%x_ax_unit_short elements to automatically write the AXIS_UNITS-dependent units into the MOM_parameter_doc files. All answers are bitwise identical but there are minor changes in some MOM_parameter_doc files.

Made 6 of the parameters describing the ISOMIP configuration into runtime parameters that are read in and rescaled via get_param calls to read ISOMIP_MAX_BEDROCK, ISOMIP_TROUGH_DEPTH, ISOMIP_BEDROCK_LENGTH, ISOMIP_TROUGH_WIDTH, ISOMIP_DOMAIN_WIDTH and ISOMIP_SIDE_WIDTH. Several of the internal variables in ISOMIP_initialize_topography were also rescaled for dimensional consistency testing, and the units of the internal variables in this same routine were documented. In addition, the default values for the ISOMIP temperatures and salinities were also rescaled. All answers are bitwise identical, but there are 6 new runtime parameters in the MOM_input files for the ISOMIP test cases.

Standardized documentation of axis-related variable units and applied dimensional scaling factors to parameters that are read in for use as defaults for other variables in seamount_initialization, including using the new G%x_ax_unit_short elements to automatically write the AXIS_UNITS-dependent units into the MOM_parameter_doc files. Also added comments describing the internal variables in the same module. All answers are bitwise identical but there are minor changes in some MOM_parameter_doc files.

Added units arguments to 2 get_param calls in Neverworld_initialization. This commit also adds comments describing many internal real variables and their units in this same module. All answers and output are bitwise identical, but there are minor changes in the MOM_parameter_doc files.

Added units arguments to 3 get_param calls in the two RGC modules. Also use elements of the ocean_grid_type to specify the units of some horizontal position related variables and to determine the domain size, rather than using separate get_param calls for LENLAT or LENLAT. This commit also adds comments describing many internal real variables and their units in RGC_tracer.F90. All answers and output are bitwise identical, but there are minor changes in the MOM_parameter_doc files for cases that use the RGC routines.

Add units arguments to 3 get_param calls and modified them in 4 others in adjustment_initialization, using elements of the ocean_grid_type to specify the units of some horizontal position related variables. This commit also adds comments describing many internal real variables and their units in this same file. All answers and output are bitwise identical, but there are minor changes in the MOM_parameter_doc files.

Added an argument documenting the units of S_REF and another rescaling it in dumbbell_initialize_thickness. The units of several other arguments or internal variables in this same file were also described in revised comments. All answers and output are bitwise identical.

Added or modified units arguments for 4 get_param calls in shelfwave_initialization, although until a full grid_type is provided to the various register OBC calls, the axis units will have to be hard-coded rather than using the fields from the grid_type. Also added or revised comments documenting various internal or control structure variables and their units. All answers and output are bitwise identical, but there are minor changes in the MOM_parameter_doc files.

Added units arguments to 4 get_param calls in dye_example. This commit also adds comments describing the units of several internal real variables in this same file. All answers and output are bitwise identical, but there are minor changes in the MOM_parameter_doc files of cases that use this tracer package.

Swapped the order of the i- and j- loops in 13 places in 6 files so that they will be stride-1 in memory for efficiency, and to follow the established patterns elsewhere in the MOM6 code. All answers are bitwise identical.

We were issuing a WARNING when the user indicates to use the STANLEY contribution to density but if the coefficient is negative we were toggling the logical flag but only issuing a warning. This would lead to users getting a result there were not expecting. Better for the run to fail so they can set the coefficient to non-negative.

Reference pressure and the compressibility fraction could previously only be set for coordinates if they were used as the main prognostic coordinate. This updates the logic to allow these parameters to be changed for diagnostic coordinates. To avoid, naming clashes with the prognostic coordinate, new function was written to construct the correct parameter name. Other places within the codebase where this occurred have subsequently been refactored.

The ref_pressure was being passed into the set_regrid_params routine, however additional lines needed to be added for the RHO and HYCOM coordinates so that the value would be injected into their control structures. Setting the same target densities for two diagnostic RHO coordinates, but with different reference pressures now yield different results.

@adcroft

As pointed out by @adcroft, the hybrid coordinate should not generally be used for diagnostic purposes. The description for P_REF when initializing a diagnostic coordinate has been updated to reflect this.

This adds a new vertical viscosity parameterization as in Greatbatch and Lamb (1990), Ferreira & Marshall (2006) and Zhao & Vallis (2008), hereafter referred to as the GL90 vertical viscosity parameterization. This vertical viscosity scheme redistributes momentum in the vertical, and is the equivalent of the Gent & McWilliams (1990) parameterization, but in a TWA (thickness-weighted averaged) set of equations. The vertical viscosity coefficient nu is computed from kappa_GM via thermal wind balance, and the following relation: nu = kappa_GM * f^2 / N^2. The vertical viscosity del_z ( nu del_z u) is applied to the momentum equation with stress-free boundary conditions at the top and bottom. In the current implementation, kappa_GM is assumed either (a) constant or as (b) having an EBT structure. A third possible formulation of nu is depth-independent: nu = f^2 * alpha The latter formulation would be equivalent to a kappa_GM that varies as N^2 with depth. Currently, the GL90 parameterization is only implemented in stacked shallow water (SSW) mode, in which case we have 1/N^2 = h/g'. More specifically, this commit adds a new subroutine that computes the coupling coefficient associated with GL90 via a_cpl_gl90 = nu / h = kappa_GM * f^2 / g' or a_cpl_gl90 = nu / h = f^2 * alpha / h. Further, a_cpl_gl90 is multiplied by a function (botfn), which is 0 within the GL90 bottom boundary layer, whose depth is set by Hbbl_gl90, and 1 otherwise. This modification is necessary to avoid fluxing momentum into vanished layers that ride over steep topography. Finally, a_cpl_gl90 is added to a_cpl, where the latter is the coupling coefficient associated with the remaining vertical stresses, used in the vertical viscosity solver. More information can be found in Loose et al. (https://www.essoar.org/doi/abs/10.1002/essoar.10512867.1), Appendix B. * Introduce logical variable KD_GL90_USE_EBT_STRUCT This variable is analogous to KHTH_USE_EBT_STRUCT, but is specifically for the GL90 scheme. If the user sets KD_GL90_USE_EBT_STRUCT = True, an EBT structure will be applied to KD_GL90.

Apply dimensional rescaling immediately after reading the open face width and porous barrier depth variables in reset_face_lengths_list to facilitate the detection of improperly scaled variables or incorrect unit declarations throughout the code. Also eliminated unnecessary local copies of rescaling factors in the MOM_porous_barriers module. All answers are bitwise identical.

This commit includes minor cleanup of the units documentation in several of the process parameterization routines. These changes include: - Change the units of the (apparently unused) optional read_khdt_[xy] arguments to tracer_hordiff from [m2] to [L2 ~> m2] - Correct a tiny number used for safety in the denominator of a normalization factor based on the (nondimensional) masks from H_subroundoff to a tiny nondimensional number, giving an expression that is dimensionally consistent. Without this change, the diagnostic "KHTR_h" will vary with large enough negative values of H_RESCALE_POWER. - Replace a local variable in bulkmixedlayer_init with units of time with distinct get_param calls setting the default for BUFFER_LAY_DETRAIN_TIME depending on which buffer layer detrainment scheme is used. - Correct the dimensions of the "land_mask" diagnostic internal_tides_init from "logical" to "nondim", because it is a real multiplicable mask, not a boolean logical mask. - Eliminate the internal variable L2_to_Z2 in the calculate_projected_state routine in MOM_kappa_shear which had been described incorrectly and ultimately was not helpful. - Corrected the allocated size declaration for three 3-d v-face arrays - Add comments highlighting a non-stride-1 loop structure for openMP threading in tracer_epipycnal_ML_diff that required the addition of 3 extra 3-d arrays and might be a performance liability in non-openMP configurations. - Extensive modification of the comments describing the variables in MOM_tracer_hordiff to clearly indicate the units of each real variable and similarly of one variable in MOM_geothermal. All answers are bitwise identical unless very large rescaling is done for thickness units, and the only change in model output is to the documented units of one diagnostic that is not used often, and to the diagnostic "KHTR_h" when large enough negative values of H_RESCALE_POWER are used.

Rescaled 3-d diagnostics and tidal input energies in the MOM_tidal_mixing code so that there is more explicit tested documentation of the units of various fields and arguments, and so that there are conversion factors that can be compared with the declared units of diagnostics, and explicit scale factors in the MOM_read_data calls. All answers are bitwise identical.

Rescaled 3-d diagnostics in MOM_CVMix_KPP, and do even more of the preliminary calculations in rescaled variables before explicitly recasting variables into MKS units for the calls to the CVMix routines. With this change, all register_diag_field routines in this module (apart from nondimensional diagnostics) have conversion factors that can be tested for correctness can be compared with the declared units of diagnostics. All answers are bitwise identical.

Avoid using the unscaled argument to MOM_get_param in 5 places in 4 files, and made related changes to avoid using some unscaled variables: - Replace Hmix_min_m (in [m]) with Hmix_min_z (in [Z ~> m]) in bulkmixedlayer_init and then set CS%Hmix_min by rescaling Hmix_min_z to [H ~> m or kg m-2]. - Replace Hmix_m (in [m]) with Hmix_z (in [Z ~> m]) in vertvisc_init, and then set CS%Hmix by rescaling Hmix_z to [H ~> m or kg m-2]. - Add a separate unlogged and unscaled get_param call for FLUXCONST for flux_const_default in the solo_driver surface_forcing_init - Do not rescale FLUXCONST when it is read in the FMS_cap surface_forcing_init. - The Flux_const element of the FMS_cap surface_forcing_CS was not actually being used apart from setting a default for Flux_const_temp and Flux_const_salt, so it was replaced with a local variable in surface_forcing_init. - Added comments better describing the internal variables in surface_forcing_init. All answers and output are bitwise identical.

Added 7 new runtime parameters (LA_DEPTH_MIN, DHH85_MIN_WAVE_FREQ, DHH85_MAX_WAVE_FREQ, RHO_AIR, VISCOSITY_AIR, WAVE_HEIGHT_SCALE_FACTOR and VON_KARMAN_WAVES) to specify the previously hard-coded dimensional parameters in the MOM_wave_interface module. Because there are several different ways to set the parameters related to the Langmuir number calculation, several of these parameters are set in the new private subroutine set_LF17_wave_params, which in turn is called in two different places. Some comments were also added to annotate the units of some of the variables in this module. By default all answers are bitwise identical, but there are new entries in the MOM_parameter_doc.all files for some configurations that use the MOM6 surface wave module.

Added the new runtime parameter DUMBBELL_T_LIGHT to specify the previously hard-coded dimensional parameters in the dumbbell_initialization module. Also used G%x_ax_unit_short to describe the units of the DUMBBELL_LEN. By default all answers are bitwise identical, but there is a new entry in the MOM_parameter_doc.all files for the dumbbell test case.

Added the new runtime parameters KELVIN_WAVE_PERIOD, KELVIN_WAVE_SSH_AMP and KELVIN_WAVE_INFLOW_AMP to specify the previously hard-coded dimensional parameters in the Kelvin_initialization module. This change includes the addition of 3 new elements in the Kelvin_OBC_CS type. By default all answers are bitwise identical, but there are new entries in the MOM_parameter_doc.all files for configurations using the Kelvin_initialization module.

Added the new runtime parameters TIDAL_BAY_PERIOD and TIDAL_BAY_SSH_ANOM to specify the previously hard-coded dimensional parameters in the tidal_bay_initialization module. This change includes the addition of 2 new elements in the tidal_bay_OBC_CS type. By default all answers are bitwise identical, but there are new entries in the MOM_parameter_doc.all files for configurations using the tidal_bay_initialization module.

@adcroft

The current implementation of makedep contains something like a race condition, where the creation of the .mod and .o files may be in an order which breaks the current dependency tree. Currently, .mod depends on .o, and changes to a module do not trigger rebuilds of dependent source. Rather than try to sort out the rule order, which could even depend on compiler internals, this patch just adds both object and module output files as dependencies, and rebuilds if either changes. We might want to come back to this someday and understand the actual order of rule execution. Thanks to Alistair Adcroft (@adcroft) for proposing this solution.

Revised the interface to the two horiz_interp_and_extract to eliminate the unused reentrant_x and tripolar_n arguments and to rename the conversion argument to scale and make it the last mandatory argument in anticipation that we might decide to make it optional, similarly to other routines like MOM_read_data. The renaming is because we use 'conversion' to indicate how the internal representation is to be rescaled for output, most prominently in register_diag_field, whereas everywhere else where we are rescaling input to the model's internal units, we use a scale argument. This makes the convention self-consistent across the MOM6 code, and should avoid some confusion. The calls to these routines were updated in 8 places in 4 modules. In 8 places the get_param calls for TRIPOLAR_N or REENTRANT_X that are no longer needed were eliminated as were the associated internal variables. This commit also includes some additions to comments near the changes that were directly tied to this commit. All answers are bitwise identical, but there are changes to a publicly visible interface; code that tries to use the old interface will not compile.

Added the runtime variables DZ_BOTTOM_TOLERANCE, TRIM_IC_Z_TOLERANCE, DENSITY_INTERP_TOLERANCE, HORIZ_INTERP_TOL_TEMP, HORIZ_INTERP_TOL_SALIN, LAND_FILL_TEMP and LAND_FILL_SALIN to replace hard-coded dimensional constants in the routines MOM_temp_salt_initialize_from_Z, trim_for_ice, and initialize_thickness_from_file in MOM_state_initialization.F90. By default, all answers are bitwise identical, but there are new entries in the MOM_parameter_doc files for some configurations.

Added to the comments describing a number of the internal variables in the MOM_ALE_sponge code, although given that much of this works on variables with arbitrary units, many of the units descriptions have to be simply [various]. All answers and output are bitwise identical.

Added 11 new runtime parameters (DETERMINE_TEMP_ADJUST_T_AND_S, DETERMINE_TEMP_T_MIN, DETERMINE_TEMP_T_MAX, DETERMINE_TEMP_S_MIN, DETERMINE_TEMP_S_MAX, DETERMINE_TEMP_T_TOLERANCE, DETERMINE_TEMP_S_TOLERANCE, DETERMINE_TEMP_RHO_TOLERANCE, DETERMINE_TEMP_DT_DS_WEIGHT, DETERMINE_TEMP_T_ADJ_RANGE, and DETERMINE_TEMP_S_ADJ_RANGE) to replace hard coded dimensional parameters used in the routine determine_temperature. This change also requires that a param_file_type argument and the logical argument just_read are passed to determine temperature. By default, all answers are bitwise identical but there are up to 10 new entries in the MOM_parameter_doc files for some layer-mode configurations with INIT_LAYERS_FROM_Z_FILE and FIT_TO_TARGET_DENSITY_IC set to true.

Added the new runtime parameters INFLOW_SHELF_TEMPERATURE and MISSING_SHELF_TEMPERATURE to the ice_shelf_dynamics module to replace hard coded ice shelf temperatures. White space was also added around "=" in a number of places in this same module to align with the MOM6 style guide. By default, all answers are bitwise identical, but there are new entries in some MOM_parameter_doc files for cases that use the ice shelf code with DYNAMIC_SHELF_MASS.

Pass ocean_grid_type arguments to call_tracer_register and call_OBC_register in place of the hor_index_type arguments that had been used previously. Also use these ocean_grid_type arguments in calls to register_shelfwave_OBC, register_RGC_tracer and register_advection_test_tracer. Within these three routines, the contents of the ocean_grid_type are used to specify axis units. The new runtime parameter SHELFWAVE_AMPLITUDE was added to allow for run-time control of the amplitude of the shelfwave test case. By default all answers are bitwise identical, but there are some changes in the units of parameters as documented in the MOM_parameter_doc files and a new entry in these files for the shelfwave test case.

Added the new runtime parameter BENCHMARK_T_LIGHT and reuse the existing parameter S_REF to specify the previously hard-coded dimensional parameters in the benchmark_initialization module. By default all answers are bitwise identical, but there are new entries in the MOM_parameter_doc.all files for the benchmark test case.

Added the new runtime parameters INITIAL_SSS, DOME2D_T_BAY and DOME2D_EAST_SPONGE_S_RANGE to specify the previously hard-coded dimensional parameters in the DOME2d_initialization module. By default all answers are bitwise identical, but there are new entries in the MOM_parameter_doc.all files for the flow_downslope and similar test cases.

Added the new runtime parameters INITIAL_SSS and SLOSHING_T_PERT to specify the previously hard-coded dimensional parameters in the sloshing_initialization module. Also added comments documenting the purpose and units of the internal real variables in sloshing_initialization.F90. There is also a new comment questioning whether the temperature perturbations are being applied correctly, but for now the code reproduces the previous answers. By default all answers are bitwise identical, but there are new entries in the MOM_parameter_doc.all files for the sloshing test cases.

Added the new runtime parameters DOME_T_LIGHT and reuse the existing parameter S_REF to specify the previously hard-coded dimensional parameters in the DOME_initialization module. By default all answers are bitwise identical, but there are new entries in the MOM_parameter_doc.all files for versions of the DOME test case with temperature and salinity as state variables.

Added the new runtime parameters MIN_DZ_FOR_SLOPE_N2 to specify a previously hard-coded dimensional parameter in the MOM_lateral_mixing_coeffs module. By default all answers are bitwise identical, but there is a new entry in the MOM_parameter_doc.all files for configurations using the some forms of the Eady growth rate slope calculation.

Added the new runtime parameters EN_CHECK_TOLERANCE to specify a previously hard-coded dimensional tolerance in the MOM_internal_tides module. By default all answers are bitwise identical, but there is a new entry in the MOM_parameter_doc.all files for configurations using the MOM_internal_tides module.

Added the runtime parameters MEKE_LSCALE_MAX_VAL and MEKE_MIN_DEPTH_TOT to specify two previously hard-coded dimensional parameters that are used with some options of the MEKE parameterizations. Also added or amended comments annotating the units of some of the internal variables in the MEKE module. By default, all answers are bitwise identical, but there are new entries in the MOM_parameter_doc.all files for some configurations using the MEKE parameterization.

Added the runtime parameter MEKE_MIN_DEPTH_DIFF to specify a previously hard-coded dimensional parameter that is used to constrain the averaging of the horizontal diffusivity used with the MEKE parameterizations. By default, all answers are bitwise identical, but there is a new entries in the MOM_parameter_doc.all files for some configurations.

Introduced a fatal error when diagnoseMLDbyDensityDifference is directed to calculate the mean stratification in a region below the mixed layer but dz_subML is not provided as the depth extent over which to average the stratification, replacing the previous hard coded (but unused) default value of 50 m. Also replaced a hard coded floor on the minimum thickness over which to apply boundary fluxes of 1e-30 m in applyBoundaryFluxesInOut with GV%H_subroundoff, which is also a tiny value. This floor is here just to avoid division by 0; while it is possible for this to change answers in some cases where ANGSTROM=0, even then there are other limiters that should apply so the solutions should not change. All answers are bitwise identical with for the MOM6-examples test suite, and very likely for all existing MOM6 configurations.

Added the new runtime parameter KD_SEED_KAPPA_SHEAR to specify a previously hard-coded dimensional parameter used in the MOM_kappa_shear module. By default all answers are bitwise identical, but there is a new entry in the MOM_parameter_doc.all files for configurations with USE_JACKSON_PARAM = True.

Added the new runtime parameter ENTRAIN_DIFFUSIVE_MAX_ENT to specify a previously hard-coded upper limit on the rate of entrainment in the buffer layers with a bulk mixed layer in the MOM_entrainment_diffusive module. By default all answers are bitwise identical, but there is a new entry in the MOM_parameter_doc.all files for some layer-mode configurations with a bulk mixed layer.

Added the new runtime parameter KPP_LT_MLD_GUESS_MIN to specify a previously hard-coded lower limit on the estimate of the boundary layer depth used to calculate the Langmuir number for some options with KPP. By default all answers are bitwise identical, but there is a new entry in the MOM_parameter_doc.all files for some configurations with a KPP and Langmuir enhanced turbulence.

Added the new runtime parameter REG_SFC_SUFFICIENT_ADJ to specify a previously hard-coded fraction of the target net entrainment to the mixed and buffer layers that is enough to stop the search for additional mass from the interior layers when regularizing the near-surface layers in layer-mode configurations. By default all answers are bitwise identical, but there is a new entry in the MOM_parameter_doc.all files for some layer-mode configurations with REGULARIZE_SURFACE_LAYERS=True.

Added the new runtime parameter SALT_EXTRACTION_LIMIT to specify a previously hard-coded limit on the fraction of the salt in a layer that can be extracted by the surface fluxes within a timestep. Also added do_not_log flags based on the value of ENABLE_THERMODYNAMICS to avoid logging parameters that are only used if thermodynamics are active in cases when it is not. In addition, the doxygen trailer describing this module had been inappropriately borrowed from another module, so it was completely rewritten to describe what the routines in this module actually do. The missing doxygen description of set_pen_shortwave was also added, and a number of spelling errors in comments were corrected. By default all answers are bitwise identical, but there is a new entry in the MOM_parameter_doc.all files for some configurations and meaningless entries have been removed from others.

Added the new runtime parameter MECH_TKE_FLOOR to specify a previously hard-coded tiny positive value for the remaining TKE when the bulk mixed does not yet have HMIX_MIN of fluid during mechanical entrainment. By default all answers are bitwise identical, but the MOM_parameter_doc.all files for some configurations with a bulk mixed layer and HMIX_MIN > 0 have a new entry.

Added the new runtime parameter VARYING_SPONGE_MASK_THICKNESS to specify a previously hard-coded input file thickness below which the target values in time-varying sponges are replaced with those from the layer above. By default all answers are bitwise identical, but the MOM_parameter_doc.all files for configurations with time-varying sponges have a new entry.

Added code to harmonize differences in how different compilers format the output of tiny (< 1e-99) or huge (>= 1e100) real values. All answers are bitwise identical, but output could change with the PGI compiler for any cases that are writing out such extreme values.

This commit replaces previously hard-coded values for dRho_dS and the temperature range for the sloshing test case with values read in from the existing runtime parameters DRHO_DS and the previously unused parameter T_RANGE that was already being read in for this configuration. The default value for dRho_dS from the EOS code (0.8 kg m-3 ppt-1) does not match hard coded value here (1 kg m-3 ppt-1), but in the existing tests using adjustment_initialization DRHO_DS was being explicitly set to the hard-coded value here, so I have chosen to reuse the same parameter with the same default value as is used elsewhere even though it could change answers in cases that do not set DRHO_DS consistently with the previous hard coded parameter. In addition, the previous default value for T_RANGE read into this module (0 degC) did not match the hard-coded range that was being used (1 degC). In this case I have chosen to change the default value for T_RANGE in this module so that by default this will reproduce the previous answers. As a result, there will be changes in the MOM_parameter doc all files for cases (like adjustment2d) that use the adjustment_initialization routines. This commit will change answers in some cases, but in the existing adjustment2d test cases in the MOM6-examples test suite, the answers are bitwise identical without any changes to the existing input parameter files.

Removed the unused element La_SL from the wave_parameters_CS. Also added or renamed a few internal variables or amended the comments describing them to clarify what the code is doing. All answers are bitwise identical.

Add 3 runtime parameters (CHARNOCK_MIN, CHARNOCK_SLOPE_U10 and CHARNOCK_0_WIND_INTERCEPT) to specify the curve fit in the Charnock coefficient calculation. By default all answers are bitwise identical, but there are 3 new runtime parameters in some MOM_parameter_doc.all files.

Added three new runtime parameters (LANGMUIR_STOKES_BACKGROUND, SURFBAND_MIN_THICK_AVG and SURFBAND_OVERRIDE_LAND_SPEED) to replace previously hard-coded dimensional parameter in the Langmuir number and Stokes drift calculations. By default all answers are bitwise identical, but there are new runtime parameters in some MOM_parameter_doc.all files.

Added the new runtime parameter WAVE_INTERFACE_ANSWER_DATE, with a default value that is temporarily set to use the previous answers. This is used to select a more efficient option in ust_2_u10_coare3p5. The answers with this new option differ at roundoff, but are otherwise very similar. By default all answers are bitwise identical, but there is a new runtime parameters in some MOM_parameter_doc.all files.

Modified get_StokesSL_LiFoxKemper to use more robust expressions when WAVE_INTERFACE_ANSWER_DATE >= 20230102, and reset the value to change the answers to ust_2_u10_coare3p5 when WAVE_INTERFACE_ANSWER_DATE >= 20230103. Both options have been tested independently, and give answers that are similar to but more robust than the previous expressions. By default all answers are bitwise identical, but there is a new use of the runtime parameter WAVE_INTERFACE_ANSWER_DATE.

Modified Update_Stokes_Drift to use more robust expressions when WAVE_INTERFACE_ANSWER_DATE >= 20230101. This new option may not be as fully tested as it should be, but it appears to give answers that are similar to but more robust than the previous expressions. By default all answers are bitwise identical, but there is a new use of the runtime parameter WAVE_INTERFACE_ANSWER_DATE.

Eliminated the hard-coded wave_parameters_CS StkLevelMode element and associated code. Also modified the description of WAVE_INTERFACE_ANSWER_DATE to describe the meaning of its various settings. A handful of spelling errors were also corrected. All answers are bitwise identical, but there are changes to some MOM_parameter_doc files.

Renamed two internal variables to Cd and I_sqrtCd in ust_2_u10_coare3p5 for greater clarity and corrected their descriptions in comments, following advice from the review of the pull request that this is a part of. Also added the missing units description "nondim" to the get_param call for DHH85_AGE. All answers are bitwise identical.

* Add GL90 parameterization in stacked shallow water This adds a new vertical viscosity parameterization as in Greatbatch and Lamb (1990), Ferreira & Marshall (2006) and Zhao & Vallis (2008), hereafter referred to as the GL90 vertical viscosity parameterization. This vertical viscosity scheme redistributes momentum in the vertical, and is the equivalent of the Gent & McWilliams (1990) parameterization, but in a TWA (thickness-weighted averaged) set of equations. The vertical viscosity coefficient nu is computed from kappa_GM via thermal wind balance, and the following relation: nu = kappa_GM * f^2 / N^2. The vertical viscosity del_z ( nu del_z u) is applied to the momentum equation with stress-free boundary conditions at the top and bottom. In the current implementation, kappa_GM is assumed either (a) constant or as (b) having an EBT structure. A third possible formulation of nu is depth-independent: nu = f^2 * alpha The latter formulation would be equivalent to a kappa_GM that varies as N^2 with depth. Currently, the GL90 parameterization is only implemented in stacked shallow water (SSW) mode, in which case we have 1/N^2 = h/g'. More specifically, this commit adds a new subroutine that computes the couping coefficient associated with GL90 via a_cpl_gl90 = nu / h = kappa_GM * f^2 / g' or a_cpl_gl90 = nu / h = f^2 * alpha / h. Further, a_cpl_gl90 is multiplied by a function (botfn), which is 0 within the GL90 bottom boundary layer, whose depth is set by Hbbl_gl90, and 1 otherwise. This modification is necessary to avlid fluxing momentum into vanished layers that ride over steep topography. Finally, a_cpl_gl90 is added to a_cpl, where the latter is the coupling coefficient associated with the remaining vertical stresses, used in the vertical viscosity solver. More information can be found in Loose et al. (https://www.essoar.org/doi/abs/10.1002/essoar.10512867.1), Appendix B. New diagnostics: * au_gl90_visc: zonal viscous coupling coefficient associated with GL90, is contained in au_visc * av_gl90_visc: meridional viscous coupling coefficient associated with GL90, is contained in av_visc * Kv_gl90_u: GL90 vertical viscosity at u-points, is contained in Kv_u * Kv_gl90_v: GL90 vertical viscosity at v-points, is contained in Kv_v * du_dt_visc_gl90: zonal acceleration due to GL90 vertical viscosity, included in du_dt_visc * dv_dt_visc_gl90: meridional acceleration due to GL90 vertical viscosity, included in dv_dt_visc * GLwork: Kinetic Energy Source from GL90 Vertical Viscosity The energetics of the GL90 parameterization (named "GLwork") are intentionally computed in MOM_vert_friction, rather than in MOM_diagnostics, where the reamining kinetic energy budget terms are computed. We have to do the computation in MOM_vert_friction to ensure sign- definiteness when GLwork is summed in the vertical. Indeed, MOM_diagnostics does not have access to the velocities and thicknesses used in the vertical solver, but rather uses a time-mean barotropic transport [uv]h to compute the energy budget diagnostics. A detailed discussion and exploration of this issue can be found in ocean-eddy-cpt#25. As a result of not computing the energetics in MOM_diagnostics, GLwork is not exactly contained in KE_visc. KE_visc represents the energetics of all vertical viscosity contributions, including the GL90 vertical viscosity. We could implement a term "KE_visc_gl90" that can be 1-to-1 compared to KE_visc; that is, KE_visc - KE_visc_gl90 would represent exactly the energetics of all viscosity contributions EXCEPT the GL90 viscosity. If we implemented KE_visc_gl90, this term would in practice be very similar as GLwork, but sign-definiteness is not ensured, see above.

@Hallberg-NOAA

…n#297) These changes follow suggestions from @Hallberg-NOAA for clarity in documentation and code readability. These modifications should not impact existing applications (e.g. SPEAR) which are reliant on this code.

Added the new runtime parameters DOME_TRACER_STRIPE_WIDTH, DOME_TRACER_STRIPE_LAT and DOME_TRACER_SHEET_SPACING to specify the previously hard-coded dimensional parameters in the DOME_tracer module, and added the runtime parameters TRACER_EXAMPLE_STRIPE_WIDTH and TRACER_EXAMPLE_STRIPE_LAT to specify parameters used by tracer_example. This change requires that an ocean grid type be passed to register_DOME_tracer and USER_register_tracer_example instead of a hor_index type. Descriptions of the units of a number of internal variables were added to both modules. In addition, the confusing (and dimensionally heterogeneous) trdc array in tracer_column_physics was replaced with 3 internal variables with more suggestive names. By default all answers are bitwise identical, but there are new entries in the MOM_parameter_doc.all files for cases that have USE_DOME_TRACER=True or USE_USER_TRACER_EXAMPLE=True.

Removed extra white space around the named argument assignments for default, units or conversion arguments to align with the MOM6 style guide. Only white space is modified, and all answers are bitwise identical.

Made the previously optional z_tol argument to find_depth_of_pressure_in_cell and cut_off_column_top non-optional. It was already being provided except in a call for unit testing, so adding it as a parameter there led to a simple change and the elimination of a hard-coded dimensional parameter. Also replaced the hard-coded fill values over land in MOM_temp_salt_initialize_from_Z for temperatures and salinities before regridding with the runtime variables temp_land_fill and salt_land_fill that are already being used in the same routine. This does not change any answers, probably because these values are not actually used. All answers are bitwise identical, but some subroutine arguments have been made non-optional.

Updated tc4/MOM_input to reflect the newer parameter settings, including replacing the obsolete NEW_SPONGES parameter with INTERPOLATE_SPONGE_TIME_SPACE. Without this change, NEW_SPONGES can not be formally and properly obsoleted without breaking the TC testing. All answers and testing are identical with this change.

Formally obsoleted the runtime parameter NEW_SPONGES. The agreed upon replacement is INTERPOLATE_SPONGE_TIME_SPACE, which has been available for almost a year. There is a warning message rather than a fatal error if NEW_SPONGES is used and both are set consistently, and a hint if they are not. Also added or amended comments describing a number of the internal variables or their units in MOM_state_initialization. All answers and output are bitwise identical.

Updated the comments in MOM_initialize_topography to reflect the fact that US is no longer an optional argument. Only comments are changed, and all answers are bitwise identical.

Added a description of the units to the comments for each of the real variables in MOM_grid_initialization and MOM_shared_initialization. Only comments are changed, and all answers are bitwise identical.

Added or amended comments to document the units of numerous internal variables and function arguments in MOM_wave_speed.F90. Only comments are changed, but the position of some variable declarations is changed to help the comments make more sense. All answers are bitwise identical and no output is changed.

Made the CS argument mandatory for wave_speeds and added the new runtime parameter INTERNAL_WAVE_CG1_THRESH to specify the threshold first mode internal below which all higher mode speeds are reported as 0, replacing a previously hard-coded dimensional value. As a result of this change there is a new waves_CS element in diabatic_CS and a call to wave_speed_init from diabatic_driver_init. By default, all answers are bitwise identical, but there is a new entry in some MOM_parameter_doc files that have INTERNAL_TIDES=True.

* Add KE_visc_gl90 diagnostic KE_visc_gl90 is an alternative to the diagnostic GLwork. Both diagnostics describe the energetics of the GL90 parameterization, as part of the kinetic energy budget. * KE_visc_gl90 is consistent with KE_visc, and the remaining KE diagnostics. In particular, it is true that KE_visc_gl90 is exactly contained in KE_visc, i.e., we have that KE_visc - KE_visc_gl90 represents exactly the energetics of all viscosity contributions except the GL90 viscosity. * GLwork is not directly compatible with KE_visc, but is guaranteed to be sign-definite if summed in the vertical.

This patch introduces a generalized I/O interface, through a new class, `MOM_file`, for reading and writing of axis-based model fields. A common API for interacting with files is defined in the `MOM_file` class, and two implementations are provided: * `MOM_infra_file`, using the "infra" framework (i.e. FMS) * `MOM_netcdf_file`, using native netCDF framework This separation allows us to define certain generic functions by class, and platform-specific functions by type. It will also allow for removal of legacy FMS1 operations which are no longer used for the majority of I/O but are still required for isolated MOM files. This change will allow us to move incompatible files from the FMS to the netCDF implementation, while still preserving a common structure for both files. The majority of the details of `MOM_file` and its subclasses are defined in `MOM_io_file.F90`, which is exclusively accessed through `MOM_io.F90`. The netCDF implementation, designed to be used by `MOM_netcdf_file` but is designed as a standalone system, is defined in `MOM_netcdf.F90`. *Interface* `MOM_file` includes the following functions: * `open` * `close` * `flush` * `register_axis` * `register_field` * `write_attribute` * `write_field` * `file_is_open` * `get_file_info` * `get_file_fields` * `get_field_atts` * `read_field_chksum` Most are designed to resemble the existing MOM I/O operations. Note that some of these have not yet been implemented for `MOM_netcdf_file`, since they are never used in the model. `MOM_file_infra` includes the following additional operations: * `get_file_times` * `get_file_fieldtypes` See documentation for usage of these functions. The "axis"/"field" model from FMS1 has been preserved, where axes are associated with variables which contain the grid point, and fields are defined with respect to the file's axes. Operations such as field counters will exclude any variables associated with the axes. The `axistype` and `fieldtype` from FMS have been replaced with new abstractions (`MOM_axis` and `MOM_field`). Internally, these point to either the FMS types or equivalent netCDF types. *Implementation* Each file type contains an instance of its native type, as well as lists of associated axes and fields. List are implemented as linked lists of names (stored as `label`) which are used to identify and extract or write the axis/field to the internal type. The mechanics of this are largely hidden from the user and can be changed in the future, if needed, without disruption to the rest of the codebase. The current netCDF implementation very closely mirrors the FMS infra behavior, but this can be relaxed or modified as needed. netCDF I/O is currently only designed for serial I/O, with all of the data on the root PE. Further development would be needed to support any kind of parallel I/O. *Current Usage* Two functions have been transferred from infra to the netCDF I/O: * `Depth_list.nc` * `ocean.stats.nc` The following legacy functions and types from FMS have been preserved: * `create_file` * `reopen_file` * `file_type` * `open_file` * `get_file_info` * `get_file_fields` * `get_file_times` This is primarily to preserve compatibility with SIS2, but may also be useful for other code, such as model drivers. These may be phased out in the future, however.

In order to adapt pipelines to work from a read-only NFS space we need the pre-processing step for tc4 to be [optionally] broken into two steps: a compile step and a data generation step. Changes: - Added the target "executables to tc4/Makefile, so only compilation occurs when invoked. The "all" target still compiles if needed. - Added target "preproc-compile" to .testing/Makefile whcih invokes the "executables" target of tc4/Makefile. The target "preproc" still compiles if needed. - Added `make-preproc-compile` to the gitlab pipeline prior to submitting the "make test" job to the compute nodes. - I also disconnected the "clean.stats" target from "clean.preproc" since the latter removes the pre-processing executables too and given that we can't re-compile those and re-create the stats from the same location it makes sense to keep those clean steps separated.

- Added CPP macro "WORKSPACE" which defaults to ".". This controls where the work/ and results/ directories are located as used by the target "test" in .testing/Makefile. - Use WORKSPACE=/lustre/f2/scratch/$USER/runner/$CI_RUNNER_ID in the job script so that if the runner is later moved to a read-only-from-compute disk the pipeline still works.

Purely asesthetic Purely aesthetic change, but on success, it's nice to see the long list of green checks. Previously we only showed any detail on a fail and on success show the one line summary.

Added the ability to use reproducing sums to create spatially homogenized tracer fields when Z_INIT_HOMOGENIZE = True, for rotational symmetry and consistency across layouts. The previous version had used non-reproducing sums. This new code is used when HOR_REGRID_ANSWER_DATE >= 20230101, and the comments describing HOR_REGRID_ANSWER_DATE have been updated to reflect this. As a part of this change, the new publicly visible routine homogenize_field was added to the MOM_horizontal_regridding module, so that the homogenization occurs in a single part of the code rather than being spread across several files. By default this commit could lead to answer changes in some cases, depending whether and how HOR_REGRID_ANSWER_DATE is set, but it turns out that the existing single_column test cases that use this have only 4 points and happen to give the same answers with either the older or newer version of the code. This commit addresses MOM6 issue mom-ocean#296 (github.com/NOAA-GFDL/issues/296), which can be closed as soon as this commit is merged in to the dev/gfdl branch of MOM6.

VarMix_CS%slope_x was being set with units of [Z L-1 ~> nondim], but described in comments as though it was simply [nondim], and then used in the (apparently unused?) calculate_slopes=.false. branch in calc_slope_functions_using_just_e as though its units actually were [nondim]. This commit corrects this inconsistency, while also rescaling the internal slope variables in that routine to also have the proper units of [Z L-1 ~> nondim]. In so doing, several rescaling factors could be eliminated from the calculations. In addition, the slopes used in calc_QG_Leith_viscosity were also being rescaled with the wrong factor or had dimensionally incorrect tiny values in some denominators, and this has been corrected as well. In testing this rescaling fix, a number of other bugs were identified with USE_QG_LEITH_VISC=True (as described at github.com/mom-ocean/issues/1590), so a fatal error message was added if this option is enabled. All answers in the MOM6-examples test suite are bitwise identical, but the code will now give a fatal error if USE_QG_LEITH_VISC=.true.

Incorporated a slope squared rescaling factor into the definition of the local N2min variable in wave_speed, thereby eliminating 4 points in the code where rescaling had been necessary and another local variable. All answers and output are bitwise identical.

Use rescaled variables for 6 global mean temperature and salinity diagnostics, using the tmp_scale arguments to the various global mean functions so that they have conversion factors that can be verified against their declared units in their register_scalar_field calls. Also added or corrected unit descriptions for a handful of variables in the MOM_diagnostics module. All answers and output are bitwise identical.

Added an optional unscale argument to the various check_redundant and chksum_vec routines so that the values that are written out in error messages are independent of rescaling values. Also added or amended comments to document the units of numerous internal variables and function arguments in MOM_debugging.F90. All answers are bitwise identical, but there are new optional arguments to several publicly visible routines.

Added unscale arguments to the various check_redundant calls so that any error messages that are generated by inconsistent redundant points will be invariant to the unit scaling that is is in use. Also rescaled the units of dtbt_reset_period to [T ~> s] in the MOM_control_struct. All answers are bitwise identical, but in some rare debugging output will become consistent.

Added or amended comments to document the units of numerous internal variables and function arguments in MOM_spatial_means.F90. Only comments are changed, and all answers are bitwise identical.

Added or amended comments to document the units of numerous internal variables and function arguments in MOM_checksums.F90. Only comments are changed, and all answers are bitwise identical.

Added schematic unit descriptions to the comments describing the arguments to the MOM_io routines, and clearly indicating when they work with rescaled variables. Only comments are changed, and all answers are bitwise identical.

Added schematic unit descriptions to the comments describing the arguments to the MOM_restart routines, and clearly indicating when they work with rescaled variables. Only comments are changed, and all answers are bitwise identical.

Added schematic unit descriptions to the comments describing the arguments to the MOM_array_transform routines, and clearly indicating that they work with variables with arbitrary units. Only comments are changed, and all answers are bitwise identical.

Revised the schematic unit descriptions to the comments describing the arguments to the MOM_horizontal_regridding routines, to clearly indicate when they work with rescaled variables. Only comments are changed, and all answers are bitwise identical.

Document the (nondimensional) units of both real variables in MOM_intrinsic functions. Only comments are changed, and all answers are bitwise identical.

Added or amended comments to document the units of numerous internal variables in MOM_energetic_PBL.F90, and corrected a few spelling errors in comments. Only comments are changed, and all answers are bitwise identical.

Added or amended comments to document the units of numerous internal variables in MOM_diapyc_energy_req.F90, and corrected a few spelling errors in comments. Also eliminated an unused variable. All answers are bitwise identical.

Added or amended comments to document the units of 16 internal variables in MOM_opacity.F90, and corrected a spelling error in a comment. Only comments are changed, and all answers are bitwise identical.

Added or amended comments to document the units of 21 internal variables in MOM_bulk_mixed_layer.F90, and corrected a few spelling errors in comments. Only comments are changed, and all answers are bitwise identical.

Revised the line breaks for a get_param call in vertvisc_init to put the units, default, and scale arguments on the same line, and used a merged scaling factor in the same call. Also added or amended comments to document the units of 9 internal variables in this same file. All answers and output are bitwise identical.

Added or amended comments to document the units of 14 internal variables in MOM_tidal_mixing.F90. Only comments are changed, and all answers are bitwise identical.

Amended comments to document the units of 1 internal variable in MOM_ALE_sponge.F90. Only comments are changed, and all answers are bitwise identical.

Amended comments to document the units of 1 internal variable in MOM_kappa_shear.F90. Only comments are changed, and all answers are bitwise identical.

Amended comments to document the units of an argument to the private subroutine find_maxF_kb in MOM_entrainment_diffusive.F90. Only comments are changed, and all answers are bitwise identical.

Amended comments to document the units of 2 internal variables in MOM_CVMix_KPP.F90. Only comments are changed, and all answers are bitwise identical.

Amended comments to document the units of 3 internal variables in MOM_CVMix_conv.F90. Only comments are changed, and all answers are bitwise identical.

Amended comments to document the units of 1 internal variable in MOM_bkgnd_mixing.F90. Only comments are changed, and all answers are bitwise identical.

Amended comments to document the units of 1 internal variable in MOM_regularize_layers.F90. Only comments are changed, and all answers are bitwise identical.

Amended comments to document the units of 1 internal variable in MOM_set_viscosity.F90. Only comments are changed, and all answers are bitwise identical.

Amended comments to document the units of 7 internal variables, arguments or elements of types in MOM_sponge.F90. Only comments are changed, and all answers are bitwise identical.

Added or amended comments to document the units of numerous internal variables in MOM_internal_tides.F90, and corrected a few spelling errors in comments. Only comments are changed, and all answers are bitwise identical.

Added or amended comments to document the units of 13 internal variables in MOM_tidal_forcing.F90, and corrected a few spelling errors in comments. Only comments are changed, and all answers are bitwise identical.

Changed the terminology in the thickness_diffuse module to be more accurate, specifically changing phrases like "thickness diffusion" to "isopycnal height diffusion". The two are only the same in the limit of a uniform bottom depth, and isopycnal coordinate and a vertically uniform diffusivity, and the new phrases reflect what is actually being done. In addition, the "Brunt-Vaisala frequency" is now being described as the "buoyancy frequency" for greater clarity of language and less use of jargon. Some units were also added to the descriptions using the standard syntax used elsewhere in the code. For now, these changes are restricted to the internal comments, so that there are no changes in the MOM_parameter_doc or output files. All answers are bitwise identical.

This commit fixed a number of dimensional rescaling issues that were introduced to the MOM_MEKE code switch the SmartRedis related options. Specifically, it adds a missing scale factor for the time_interp_external call for the offline data Eddy kinetic energy used in MEKE when EKE_SOURCE=file. It also corrects the documented units and conversion factors for 4 diagnostics related to machine learning within MEKE. This commit also adds or amends comments to document the units of 27 internal variables in MOM_MEKE.F90, and corrected a few spelling errors in comments. All answers and output are bitwise identical in the existing MOM6-examples test suite, but there may be other examples where the units or rescaling of diagnostics are corrected or (in cases using EKE_SOURCE=file) where dimensional consistency testing issues are corrected for the solutions themselves.

Added or amended comments to document the units of 75 variables in 23 files in the src/core, src/initialization, src/ice_shelf and src/user directories that had been overlooked when the other variables in these files had their units documented. Only comments are changed, and all answers are bitwise identical.

Added or amended comments to document the units of about 250 variables in 6 files in the src/equation_of_state directories. Also revised comments to make it clear that the MOM6 code for the UNESCO equation of state is based on the Jackett and MacDougall (1995) refit to the UNESCO equation of state (which uses potential temperature as a state variable) as opposed to the original UNESCO equation of state, as documented in an appendix to Gill (1982) (which uses in-situ temperature as a state variable). Also corrected a handful of spelling errors in comments. Only comments are changed, and all answers are bitwise identical.

- After a recent update to how the build environment is defined within MOM6-examples, the "no libraries" build test (unique to MOM6) is failing because the Makefile now no longer contains the environment. This commit overrides a CPP macro that points to the bash script that is needed.

This commit makes a set of changes so that the chksums output by the OM4_05 configuration with DEBUG = True reproduce between 252 and 256 PE runs (note that the solutions themselves already reproduced). This is includes adding a new optional omit_corners argument to the MOM_state_chksum and MOM_thermo_chksum routines, and revising the haloshift, omit_corners or symmetric arguments on 6 subroutine calls, to check more appropriate loop ranges. All answers are bitwise identical, but there is a new optional argument to three publicly visible debugging routines.

Added or amended comments to document the units of 30 variables in FMS_cap/MOM_surface_forcing_gfdl.F90, FMS_cap/ocean_model_MOM.F90, solo_driver/MOM_surface_forcing and unit_drivers/MOM_sum_driver.F90. Only comments are changed, and all answers are bitwise identical.

Added or amended comments to document the units of about 172 parameters or variables in MOM_EOS_NEMO.F90. Only comments are changed, and all answers are bitwise identical.

This commit adds an optional unscale argument to the log_param_real interfaces. All answers and output are bitwise identical.

Use the new unscale optional argument in 10 log_param calls for real variables. All answers and output are bitwise identical.

Because get_param is case-sensitive, CVMix_shear_is_used can incorrectly return false if USE_PP81 = True and USE_LMD94 = False. This would cause such cases to fail to reproduce across restarts or use uninitialize or incorrect arrays, but because the Pacanowski and Philader parameterization is very out-dated it appears not to be used in any active test case. Moreover, no one has reported any such issues yet. Therefore, rather than adding a flag to reproduce the old (unreproducing) results, this commit simply corrects this bug. The (case-sensitive) parameter "Use_PP81" was also formally obsoleted. All answers are bitwise identical in all known MOM6 configurations, but this could lead to answer changes in certain unlikely configurations.

This patch introduces `read_netCDF_data`, a new method for reading netCDF datasets using the native netCDF I/O interface. It is designed to resemble the existing `MOM_read_data` function. Motivation ---------- Legacy input files may contain content which is not supported by the newest framework I/O (FMS). In order to retain support for these input files, particularly over a wider range of compilers, this patch provides an alternative method for reading these files. Interface --------- As with `MOM_read_data`, the function is provided with a netCDF filepath and a variable name, and returns the values to a provided variable. The `global_file` and `file_may_be_4d` flags have been dropped, since they are related to specific FMS2 compatibility issues. (Global vs domain-decomposed reads is controlled by the presence of a `MOM_domain`) Limited domain-decomposed I/O is supported, providing parallel I/O over a single file, to the extent supported by the filesystem. Parallelization over multiple files, as in FMS I/O, is not supported. Each FMS PE (MPI rank) reads its own segment, as defined by its MOM_domain. Output can be saved to either compute or data domains; as in FMS, the appropriate placement is inferred from the size of the output array. Support is currently limited to time-independent 2D arrays with center-cell indexing. That is, the `position` and `timelevel` arguments are not yet supported. The subroutines raise an error if these are provided, as an indication that they may support them in the future. Implementation -------------- Internally, the function opens a `MOM_netcdf_file`, generates its field/axis manifest, and reads the field contents. As with `MOM_read_data`, an internal rotation may be applied. The file is closed upon completion. (This behavior is designed to emulate the existing `MOM_read_data`; in a future implementation, we may want to use a persistent file handle which reduces the number of I/O operations.) Opening a `MOM_netcdf_file` now supports a `MOM_domain` argument, which is used to determine the index bounds of its local segment of the global domain. This is used to compute appropriate bounds for the native netCDF IO calls. As part of these changes, the `get_file_fields` function has been separated into itself and a new function, `update_file_contents`, which populates the internal axis and field metadata list. Usage ----- The following fields have been moved to the native netCDF IO: * `tideamp` (tidal mixing, FMS surface forcing) * `gustiness` (solo and FMS surface forcing) * `h2` (roughness in tidal mixing) This only comprises the fields which must be handled natively in order for the GFDL regression suite to pass with the PGI compiler; more files could be moved to native I/O in the future. Bugfixes -------- Some bugfixes to the netCDF I/O are also included: * `filename` attribute is now only written in an writeable state * Previously, `get_file_fields` (and now `update_file_contents`) assumed that every axis had an equivalent variable, which could lead to potential errors if an axis had no equvalent field, such as index bounds. We now count the number of variables with matching dimension names, tagged as axes, rather than assuming that every axis has a variable, and exclude them from the field list. * Not a bugfix, but `hor_index_init` was modified so that `param_file` is now an optional input. This function is used in `MOM_netcdf_file`, where `param_file` is not available. The argument is only used to call `log_param`. Previous usage of these functions was restricted to writing output with well-defined content, so were unaffected by these issues.

The introduction of makedep means that Python is now a dependency of the MOM6 compilation. On some systems, we cannot assume that `python` is the name of the interpreter, and strictly should not even assume that it exists. This is notably an issue on the recent MacOS M1 systems, which use `python3` as its interpreter, and do not provide one named `python`. This patch adds macros to the MOM6 and FMS autoconf builds to detect if Python is on the system, and makes a few attempts to determine the name of the interpreter (python, python3, python2). Perhaps more can be done here, but this is probably sufficient in nearly all cases.

reopen_MOM_file includes an inquire test to determine whether we are attempting to reopen an existing file. If missing, it will attempt to create the missing file. The switch from FMS to netCDF I/O exposed a race condition here, where one rank may create the file, and another delayed rank may incorrectly identify this new file as already existing. This resulted in a segmentation fault. Unsure why this was not detected before; it could be that FMS was more resilient to the possibility of missing files. Regardless, the `exists` value was volatile and could lead to potential error. This patch introduces a temporary fix to the issue by checking the root PE and threading value. When threading is single-file, only the root PE participates in the existence test and file creation. This accounts for the case where either the root PE or any larger subset containing the root PE calls the function. It does not account for the more exotic case where a non-root PE many wish to create a file. If threading is set to MULTIPLE (i.e. IO domains) then an error is raised, since there's currently no safe way to implement an equivalent `inquire()` test. We can revisit this function when stronger controls around threaded IO are introduced. But for now, I believe that this is the best that we can do.

Erratic slowdowns in our Lustre filesystem mean that test runtimes are largely unpredictable. This patch increases the runtimes from 20min to 1hr, to better cope with this issue.

Corrected the units in the get_param call for WAVE_HEIGHT_SCALE_FACTOR, and corrected the units descriptions in comments of 22 wind stress related variables in 6 driver routines, from [R L Z T-1 ~> Pa] to [R L Z T-2 ~> Pa], but the actual conversion factors in the code are correct. Also fixed 42 other inconsistent units in comments in 28 files scattered throughout the MOM6 code. WAVE_HEIGHT_SCALE_FACTOR was added in December 2022 as a part of PR mom-ocean#289 to dev/gfdl. These inconsistent units were detected because they do not match the patterns of other valid units; most are recent additions. Apart from a single unit in a get_param call, only comments are changed, and all answers are bitwise identical.

Restored an else that was inadvertently deleted as a part of code clean up in MOM-ocean/MOM6 PR mom-ocean#1127 on June 5, 2020. This bug causes bulkmixedlayer to be called twice (with cumulative effects) when 0. < ML_MIX_FIRST < 1., and not to be called at all when ML_MIX_FIRST = 1. This bug only applies to cases where the bulk mixed layer is enabled by setting BULKMIXEDLAYER=True and USE_REGRIDDING=False (i.e., in layered mode configurations with active thermodynamics), however because the default value of ML_MIX_FIRST = 0, this bug does not appear to be used in any active test cases, and it went undetected when it was introduced. All answers in the MOM6-examples test suite are bitwise identical, but this could change answers in some cases.

Revised write_energy so that only the root_PE attempts to open, reopen or write to a netcdf file. Although FMS can handle cases where multiple PEs make the same calls with internal logic, this change avoids requiring such internal (hidden) logical tests, and instead is more explicit on what is actually intended. This change is complementary to MOM6 dev/gfdl PR mom-ocean#328, which adds internal logic to handle the case where all PEs are making a call to reopen a single netcdf file. All answers and output are bitwise identical.

Fixed two horizontal indexing bugs in `get_field_nc`, where the difference between the array starting index (always 1 in this subroutine) and the values in the handle argument were not being taken into account when the array was being passed in with only its computational domain. Also initialized the internal `unlim_index` array in `get_netcdf_fields` to fix a problem with using an uninitialized array that was being flagged when run in debug mode. With this commit, the model is once again reproducing the expected answers when rescaling is applied for vertical distances or time. Co-authored-by: Marshall Ward <[email protected]>

Add "PPM_CW" as an option for INTERPOLATION_SCHEME and REMAPPING_SCHEME. This implements the original Colella and Woodward (1984) edge calculation for PPM. It computes 4th order explicit edge values but constrains them to produce a monotonic profile, which is particularly effective for remapping. INTERPOLATION_SCHEME="PPM_CW" is identical to "REMAPPING_PPM_HYBGEN", but hybgen_PPM_coefs has been replaced by edge_values_explicit_h4cw and PPM_monotonicity for flexibility and to simplify upgrades. Answers with existing INTERPOLATION_SCHEME options are unchanged. REMAPPING_SCHEME="PPM_CW" is a new option which can perform better than "P1M_H2" when used with INTERPOLATION_SCHEME="PPM_CW". Answers with existing REMAPPING_SCHEME options are unchanged. HYCOM1 regridding walks a monotonic density profile to locate the new interface locations where the interface density equals the target density. However, it assumes that moving one interface has no effect on the density at all other interfaces and this need not be the case. When regridding, with HYCOM1_ONLY_IMPROVES=True, an interface is only moved if this improves the fit to its target density. The default of False does not change answers.

Updated check_MOM6_scaling_factors and compose_dimension_list to reflect that fact that MOM6 is now doing dimensional consistency testing for temperature (via [C ~> degC]) and salinity (via [S ~> ppt]), with an expanded dimension of the scaling key from 6 to 8 and additional calls to add_scaling. Also updated the weights on the add_scaling calls, which are essentially counts of the frequency of the various unit descriptors in the MOM6 code, to reflect only the counts of variables with doxygen comments (i.e., arguments, function return values and elements of types) but excluding the user, framework and diagnostics directories and the passive tracer packages. All model solutions are bitwise identical, but there will be updated suggestions for combinations of scaling factors that minimize the aliasing of the units that are used.

Removed the coord_slight module and all calls to it, and obsoleted all run-time parameters that are exclusively related to it. This code was an attempt from 2015 to define an appropriate hybrid vertical coordinate for global climate modeling, but it never worked very well (usually falling apart in the second year), and it has not been used in any publication or active model for many years. The test case that exercised this coordinate in the MOM6-examples test suite is also being removed via MOM6-examples PR mom-ocean#388. The coord_SLight code is being eliminated altogether now to simplify the MOM6 code base and reduce the volume of untested and unused code. All answers in all known MOM6 configurations in active use are bitwise identical, although there is a remote chance that someone somewhere might be using the SLIGHT coordinate.

Fixed a bug in MOM_calculate_grad_Coriolis() that was causing the model to hang due to mismatched halo updates when GLOBAL_INDEXING = True. Also added missing callTree (a.k.a. granny tracker) calls at the start and end of the same routine. All answers are bitwise identical in any cases that worked before.

Resolving conflict in MOM_CVMix_shear.F90 Conflict due to introduction of changes to Ri smoothing in CVMix in main, alongside changes to units in comments in dev/gfdl.

Due to some machines reporting a regression in the mixed layer restratification code, this patch reverts the calculation of the growth time in a separate function. Most of the content related to comments and parameter setup have been retained, even if those parameters are no longer used.

…ate-2023-04-06 GFDL to main (2023-04-06)

Commits on Nov 15, 2022

Merge branch 'main' into main_to_dev

marshallward committed Nov 15, 2022

Configuration menu

View commit details

Copy full SHA for 2623242

Browse repository at this point

Copy the full SHA

2623242 View commit details

Browse the repository at this point in the history

Commits on Feb 8, 2023

Merge branch 'main' into dev/gfdl

marshallward committed Feb 8, 2023

Configuration menu

View commit details

Copy full SHA for 168305f

Browse repository at this point

Copy the full SHA

168305f View commit details

Browse the repository at this point in the history

Commits on Mar 2, 2023

Merge branch 'main' into dev/gfdl

marshallward committed Mar 2, 2023

Configuration menu

View commit details

Copy full SHA for 7af22d6

Browse repository at this point

Copy the full SHA

7af22d6 View commit details

Browse the repository at this point in the history

Merge changes from GFDL to main (2023-04-06) #249

Merge changes from GFDL to main (2023-04-06) #249

Commits on Oct 28, 2022

Commits on Oct 30, 2022

Commits on Oct 31, 2022

Commits on Nov 7, 2022

Commits on Nov 9, 2022

Commits on Nov 10, 2022

Commits on Nov 11, 2022

Commits on Nov 15, 2022

Commits on Nov 16, 2022

Commits on Nov 21, 2022

Commits on Nov 22, 2022

Commits on Nov 23, 2022

Commits on Nov 24, 2022

Commits on Nov 25, 2022

Commits on Nov 28, 2022

Commits on Nov 29, 2022

Commits on Dec 3, 2022

Commits on Dec 7, 2022

Commits on Dec 9, 2022

Commits on Dec 12, 2022

Commits on Dec 13, 2022

Commits on Dec 14, 2022

Commits on Dec 15, 2022

Commits on Dec 16, 2022

Commits on Dec 18, 2022

Commits on Dec 19, 2022

Commits on Dec 20, 2022

Commits on Dec 21, 2022

Commits on Dec 23, 2022

Commits on Dec 29, 2022

Commits on Dec 30, 2022

Commits on Jan 3, 2023

Commits on Jan 4, 2023

Commits on Jan 5, 2023

Commits on Jan 7, 2023

Commits on Jan 9, 2023

Commits on Jan 12, 2023

Commits on Jan 13, 2023

Commits on Jan 18, 2023

Commits on Jan 22, 2023

Commits on Jan 27, 2023

Commits on Jan 28, 2023

Commits on Jan 31, 2023

Commits on Feb 1, 2023

Commits on Feb 2, 2023

Commits on Feb 3, 2023

Commits on Feb 8, 2023

Commits on Feb 10, 2023

Commits on Feb 11, 2023

Commits on Feb 13, 2023

Commits on Feb 15, 2023

Commits on Feb 19, 2023

Commits on Feb 24, 2023

Commits on Feb 28, 2023

Commits on Mar 1, 2023

Commits on Mar 2, 2023

Commits on Mar 3, 2023

Commits on Mar 26, 2023

Commits on Mar 30, 2023

Commits on Apr 1, 2023

Commits on Apr 3, 2023

Commits on Apr 5, 2023

Commits on Apr 29, 2023

Commits on May 4, 2023

Commits on Jul 7, 2023