Change name of conserve_water namelist option in diag_manager_mod

The conserve_water namelist option in diag_manager_mod caused confusion with external users of the diag_manager.  The name is changed in this commit to help clarify what the option did.  Documentation has also been added.

Fixes mom-ocean#30

diag_manager/diag_data.F90

@@ -647,6 +647,12 @@ MODULE diag_data_mod
   ! </DATA>
   ! <DATA NAME="do_diag_field_log" TYPE="LOGICAL" DEFAULT=".FALSE." />
   ! <DATA NAME="write_bytes_in_file" TYPE="LOGICAL" DEFAULT=".FALSE." />
+  ! <DATA NAME="flush_nc_files" TYPE="LOGICAL" DEFAULT=".FALSE.">
+  !   Indicate if diag_manager should force the flush of the netCDF diagnostic
+  !   files to disk Note: changing this to .TRUE. can greatly reduce the model
+  !   performance as at each write to the netCDF diagnostic file, the model must
+  !   wait until the flush to disk finishes.
+  ! </DATA>
   ! <DATA NAME="debug_diag_manager" TYPE="LOGICAL" DEFAULT=".FALSE." />
   ! <DATA NAME="max_num_axis_sets" TYPE="INTEGER" DEFAULT="25" />
   ! <DATA NAME="use_cmor" TYPE="LOGICAL" DEFAULT=".FALSE.">
@@ -688,7 +694,12 @@ MODULE diag_data_mod
   LOGICAL :: do_diag_field_log = .FALSE.
   LOGICAL :: write_bytes_in_file = .FALSE.
   LOGICAL :: debug_diag_manager = .FALSE.
-  LOGICAL :: conserve_water = .TRUE. ! Undocumented namelist to control flushing of output files.
+  LOGICAL :: flush_nc_files = .FALSE. !< Control if diag_manager will force a
+                                      !! flush of the netCDF file on each write.
+                                      !! Note: changing this to .TRUE. can greatly
+                                      !! reduce the performance of the model, as the
+                                      !! model must wait until the flush to disk has
+                                      !! completed.
   INTEGER :: max_num_axis_sets = 25
   LOGICAL :: use_cmor = .FALSE.
   LOGICAL :: issue_oor_warnings = .TRUE.

diag_manager/diag_manager.F90

@@ -210,7 +210,7 @@ MODULE diag_manager_mod
        & first_send_data_call, do_diag_field_log, write_bytes_in_file, debug_diag_manager,&
        & diag_log_unit, time_unit_list, pelist_name, max_axes, module_is_initialized, max_num_axis_sets,&
        & use_cmor, issue_oor_warnings, oor_warnings_fatal, oor_warning, pack_size,&
-       & max_out_per_in_field, conserve_water, region_out_use_alt_value, max_field_attributes, output_field_type,&
+       & max_out_per_in_field, flush_nc_files, region_out_use_alt_value, max_field_attributes, output_field_type,&
        & max_file_attributes, max_axis_attributes, prepend_date, DIAG_FIELD_NOT_FOUND, diag_init_time, diag_data_init,&
        & write_manifest_file
   USE diag_table_mod, ONLY: parse_diag_table
@@ -3715,7 +3715,7 @@ SUBROUTINE diag_manager_init(diag_model_subset, time_init, err_msg)
     NAMELIST /diag_manager_nml/ append_pelist_name, mix_snapshot_average_fields, max_output_fields, &
          & max_input_fields, max_axes, do_diag_field_log, write_bytes_in_file, debug_diag_manager,&
          & max_num_axis_sets, max_files, use_cmor, issue_oor_warnings,&
-         & oor_warnings_fatal, max_out_per_in_field, conserve_water, region_out_use_alt_value, max_field_attributes,&
+         & oor_warnings_fatal, max_out_per_in_field, flush_nc_files, region_out_use_alt_value, max_field_attributes,&
          & max_file_attributes, max_axis_attributes, prepend_date, write_manifest_file
 
     ! If the module was already initialized do nothing

diag_manager/diag_util.F90

@@ -1,4 +1,4 @@
-#include <fms_platform.h>
+s#include <fms_platform.h>
 
 MODULE diag_util_mod
   ! <CONTACT EMAIL="[email protected]">
@@ -33,7 +33,7 @@ MODULE diag_util_mod
        & base_second, num_files, max_files, max_fields_per_file, max_out_per_in_field,&
        & max_input_fields,num_input_fields, max_output_fields, num_output_fields, coord_type,&
        & mix_snapshot_average_fields, global_descriptor, CMOR_MISSING_VALUE, use_cmor, pack_size,&
-       & debug_diag_manager, conserve_water, output_field_type, max_field_attributes, max_file_attributes,&
+       & debug_diag_manager, flush_nc_files, output_field_type, max_field_attributes, max_file_attributes,&
        & file_type, prepend_date, region_out_use_alt_value, GLO_REG_VAL, GLO_REG_VAL_ALT,&
        & DIAG_FIELD_NOT_FOUND, diag_init_time
   USE diag_axis_mod, ONLY: get_diag_axis_data, get_axis_global_length, get_diag_axis_cart,&
@@ -2316,7 +2316,7 @@ SUBROUTINE diag_data_out(file, field, dat, time, final_call_in, static_write_in)
           files(file)%last_flush = time
        END IF
     ELSE
-       IF ( time > files(file)%last_flush .AND. (.NOT.conserve_water.OR.debug_diag_manager) ) THEN
+       IF ( time > files(file)%last_flush .AND. (flush_nc_files.OR.debug_diag_manager) ) THEN
           CALL diag_flush(files(file)%file_unit)
           files(file)%last_flush = time
        END IF