Split marbl_mod and marbl_ciso_mod

docs/src/dev-guide/add-diagnostic.rst

@@ -5,7 +5,9 @@ Adding a Diagnostic
 ===================
 
 This is a five step process.
-There are three changes to make in the Fortran code, all of which are made in ``marbl_diagnostics_mod.F90``.
+There are three changes to make in the Fortran code.
+The indexing type is in ``marbl_interface_private_types.F90``, and the rest of the code is in ``marbl_diagnostics_mod.F90``.
+(If your diagnostic is part of the carbon isotope tracer module, that code belongs in ``marbl_ciso_diagnostics_mod.F90``.)
 There are also two steps to make sure the diagnostic is known the GCM so it is included in the output.
 
 For this example, we follow the in situ temperature, which uses the ``insitu_temp`` index.
@@ -18,12 +20,12 @@ Step 1. Add to MARBL diagnostic indexing type
 
 To reduce the number of string comparisons inside routines called every time-step, MARBL uses integer indices to track many different variables.
 These indices are packed into datatypes to group common indices together.
-So the indices for diagnostics variables are split into ``marbl_surface_forcing_diagnostics_indexing_type`` and ``marbl_interior_forcing_diagnostics_indexing_type``.
+So the indices for diagnostics variables are split into ``marbl_surface_flux_diagnostics_indexing_type`` and ``marbl_interior_tendency_diagnostics_indexing_type``.
 ``insitu_temp`` is an interior forcing diagnostic.
 
 .. code-block:: fortran
 
-   type, private :: marbl_interior_diagnostics_indexing_type
+   type, private :: marbl_interior_tendency_diagnostics_indexing_type
      ! General 2D diags
      integer(int_kind) :: zsatcalc
      integer(int_kind) :: zsatarag
@@ -35,7 +37,7 @@ So the indices for diagnostics variables are split into ``marbl_surface_forcing_
      .
      .
      .
-   end type marbl_surface_forcing_diagnostics_indexing_type
+   end type marbl_interior_tendency_diagnostics_indexing_type
 
 -----------------------------------
 Step 2. Add to diagnostic structure
@@ -78,10 +80,10 @@ This step copies data only available in MARBL into the datatype that is availabl
   end associate
 
 .. note::
-  In situ temperature is copied to the diagnostic type in ``marbl_diagnostics_set_interior_forcing()``.
+  In situ temperature is copied to the diagnostic type in ``marbl_diagnostics_interior_tendency_compute()``.
   This subroutine also calls many different ``store_diagnostics_*`` subroutines, but in a future release the ``store_diagnostics`` routines will be condensed into a smaller subset of routines.
   Regardless, find the routine that makes the most sense for your diagnostic variable.
-  (Surface forcing fields are copied to the diagnostic type in ``marbl_diagnostics_set_surface_forcing()``.)
+  (Surface forcing fields are copied to the diagnostic type in ``marbl_diagnostics_surface_flux_compute()``.)
 
 -----------------------------------------
 Step 4. Update the Diagnostics YAML files

docs/src/dev-guide/add-tracer.rst

@@ -138,22 +138,18 @@ Step 4. Compute surface flux for new tracer (if necessary)
 
 Not all tracers return a surface flux, so this may not be necessary for your tracer.
 For this example, we will follow the oxygen tracer.
-Surface fluxes are computed in ``marbl_mod::marbl_set_surface_forcing``:
+Surface fluxes are computed in ``marbl_surface_flux_mod::marbl_surface_flux_compute``:
 
 .. code-block:: fortran
 
-  subroutine marbl_set_surface_forcing( &
+  subroutine marbl_surface_flux_compute( &
   .
   .
   .
     associate(                                                                                      &
     .
     .
     .
-         stf                  => surface_tracer_fluxes(:,:),                                        &
-         .
-         .
-         .
          o2_ind            => marbl_tracer_indices%o2_ind,                                      &
          .
          .
@@ -164,7 +160,7 @@ Surface fluxes are computed in ``marbl_mod::marbl_set_surface_forcing``:
     !  fluxes initially set to 0
     !-----------------------------------------------------------------------
 
-    stf(:, :) = c0
+    surface_fluxes(:, :) = c0
     .
     .
     .
@@ -183,22 +179,19 @@ Surface fluxes are computed in ``marbl_mod::marbl_set_surface_forcing``:
        pv_o2(:) = xkw_ice(:) * sqrt(660.0_r8 / schmidt_o2(:))
        o2sat(:) = ap_used(:) * o2sat_1atm(:)
        flux_o2_loc(:) = pv_o2(:) * (o2sat(:) - surface_vals(:, o2_ind))
-       stf(:, o2_ind) = stf(:, o2_ind) + flux_o2_loc(:)
-
-.. note::
-  This subroutine will be renamed ``marbl_compute_surface_fluxes`` to better reflect what the code is doing.
+       surface_fluxes(:, o2_ind) = surface_fluxes(:, o2_ind) + flux_o2_loc(:)
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Step 5. Compute tracer tendency
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The tracer tendencies are computed in a two step process - MARBL computes the tracer tendency terms from a variety of processes and then combines the terms in the end.
 Given the modular nature of MARBL, the tendencies from each process are computed in their own routine.
-This is done in ``marbl_mod::set_interior_forcing``:
+This is done in ``marbl_interior_tendency_mod::interior_tendency_compute``:
 
 .. code-block:: fortran
 
-  subroutine marbl_set_interior_forcing( &
+  subroutine marbl_interior_tendency_compute( &
   .
   .
   .
@@ -276,8 +269,7 @@ So you will need to update ``marbl_compute_dtracer_local`` to compute the tracer
     dtracers(o2_ind) = o2_production - o2_consumption
 
 .. note::
-  #. This subroutine will be renamed ``marbl_compute_interior_tendencies`` to better reflect what the code is doing.
-  #. The ``k`` loop in the example may be removed in favor of doing per-process computations on an entire column at once.
+  The ``k`` loop in the example may be removed in favor of doing per-process computations on an entire column at once.
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Step 6. Add any necessary diagnostics

docs/src/dev-guide/coding-conventions.rst

@@ -56,12 +56,13 @@ How to Call an Object-oriented Subroutine
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 A subroutine inside a class is referenced just like any other member, via the ``%`` character.
-For example, MARBL times the call to the subroutine ``marbl_compute_carbonate_chemistry()`` from the subroutine ``marbl_set_interior_forcing()`` (part of ``marbl_mod.F90``).
+For example, MARBL times the call to the subroutine ``marbl_compute_carbonate_chemistry()`` from
+the subroutine ``marbl_interior_tendency_compute()`` (part of ``marbl_interior_tendency_mod.F90``).
 The timer calls look like this:
 
 .. code-block:: fortran
 
-  subroutine marbl_set_interior_forcing( &
+  subroutine marbl_interior_tendency_compute( &
   .
   .
   .

docs/src/dev-guide/marbl-interface.rst

@@ -19,48 +19,48 @@ The class definition is shown below:
      type(marbl_tracer_index_type)     , pointer    , public  :: tracer_indices => NULL()
      type(marbl_log_type)                           , public  :: StatusLog
 
-     type(marbl_saved_state_type)              , public               :: surface_saved_state             ! input/output
-     type(marbl_saved_state_type)              , public               :: interior_saved_state             ! input/output
-     type(marbl_surface_saved_state_indexing_type), public            :: surf_state_ind
-     type(marbl_interior_saved_state_indexing_type), public           :: interior_state_ind
+     type(marbl_saved_state_type)              , public               :: surface_flux_saved_state             ! input/output
+     type(marbl_saved_state_type)              , public               :: interior_tendency_saved_state        ! input/output
+     type(marbl_surface_flux_saved_state_indexing_type), public       :: surf_state_ind
+     type(marbl_interior_tendency_saved_state_indexing_type), public  :: interior_state_ind
      type(marbl_timers_type)                   , public               :: timer_summary
 
-     ! public data - interior forcing
-     real (r8)                                 , public, allocatable  :: column_tracers(:,:)     ! input  *
-     real (r8)                                 , public, allocatable  :: column_dtracers(:,:)    ! output *
-     type(marbl_interior_forcing_indexing_type), public               :: interior_forcing_ind         !
-     type(marbl_forcing_fields_type)           , public, allocatable  :: interior_input_forcings(:)
-     type(marbl_diagnostics_type)              , public               :: interior_forcing_diags  ! output
+     ! public data related to computing interior tendencies
+     real (r8), allocatable                             , public  :: tracers(:,:)                  ! input
+     type(marbl_forcing_fields_type), allocatable       , public  :: interior_tendency_forcings(:) ! input
+     real (r8), allocatable                             , public  :: interior_tendencies(:,:)      ! output
+     type(marbl_interior_tendency_forcing_indexing_type), public  :: interior_tendency_forcing_ind ! FIXME #311: should be private
+     type(marbl_diagnostics_type)                       , public  :: interior_tendency_diags       ! output
 
-     ! public data surface forcing
-     real (r8)                                 , public, allocatable  :: surface_vals(:,:)           ! input  *
-     type(marbl_surface_forcing_indexing_type) , public               :: surface_forcing_ind         !
-     type(marbl_forcing_fields_type)           , public, allocatable  :: surface_input_forcings(:) ! input  *
-     real (r8)                                 , public, allocatable  :: surface_tracer_fluxes(:,:)  ! output *
-     type(marbl_surface_forcing_output_type)   , public               :: surface_forcing_output      ! output
-     type(marbl_diagnostics_type)              , public               :: surface_forcing_diags       ! output
+     ! public data related to computing surface fluxes
+     real (r8)                                      , public, allocatable  :: tracers_at_surface(:,:)     ! input
+     type(marbl_forcing_fields_type)                , public, allocatable  :: surface_flux_forcings(:)    ! input
+     type(marbl_surface_flux_forcing_indexing_type) , public               :: surface_flux_forcing_ind    ! FIXME #311: should be private
+     real (r8)                                      , public, allocatable  :: surface_fluxes(:,:)         ! output
+     type(marbl_surface_flux_output_type)           , public               :: surface_flux_output         ! output
+     type(marbl_diagnostics_type)                   , public               :: surface_flux_diags          ! output
 
      ! public data - global averages
-     real (r8)                                 , public, allocatable  :: glo_avg_fields_interior(:)   ! output (nfields)
-     real (r8)                                 , public, allocatable  :: glo_avg_averages_interior(:) ! input (nfields)
-     real (r8)                                 , public, allocatable  :: glo_avg_fields_surface(:,:)  ! output (num_elements,nfields)
-     real (r8)                                 , public, allocatable  :: glo_avg_averages_surface(:)  ! input (nfields)
+     real (r8)                                 , public, allocatable  :: glo_avg_fields_interior_tendency(:)   ! output (nfields)
+     real (r8)                                 , public, allocatable  :: glo_avg_averages_interior_tendency(:) ! input (nfields)
+     real (r8)                                 , public, allocatable  :: glo_avg_fields_surface_flux(:,:)      ! output (num_elements,nfields)
+     real (r8)                                 , public, allocatable  :: glo_avg_averages_surface_flux(:)      ! input (nfields)
 
      ! FIXME #77: for now, running means are being computed in the driver
      !            they will eventually be moved from the interface to inside MARBL
-     real (r8)                                 , public, allocatable  :: glo_scalar_interior(:)
-     real (r8)                                 , public, allocatable  :: glo_scalar_surface(:)
+     real (r8)                                 , public, allocatable  :: glo_scalar_interior_tendency(:)
+     real (r8)                                 , public, allocatable  :: glo_scalar_surface_flux(:)
 
-     type(marbl_running_mean_0d_type)          , public, allocatable  :: glo_avg_rmean_interior(:)
-     type(marbl_running_mean_0d_type)          , public, allocatable  :: glo_avg_rmean_surface(:)
-     type(marbl_running_mean_0d_type)          , public, allocatable  :: glo_scalar_rmean_interior(:)
-     type(marbl_running_mean_0d_type)          , public, allocatable  :: glo_scalar_rmean_surface(:)
+     type(marbl_running_mean_0d_type)          , public, allocatable  :: glo_avg_rmean_interior_tendency(:)
+     type(marbl_running_mean_0d_type)          , public, allocatable  :: glo_avg_rmean_surface_flux(:)
+     type(marbl_running_mean_0d_type)          , public, allocatable  :: glo_scalar_rmean_interior_tendency(:)
+     type(marbl_running_mean_0d_type)          , public, allocatable  :: glo_scalar_rmean_surface_flux(:)
 
      ! private data
      type(marbl_PAR_type)                      , private              :: PAR
      type(marbl_particulate_share_type)        , private              :: particulate_share
-     type(marbl_surface_forcing_share_type)    , private              :: surface_forcing_share
-     type(marbl_surface_forcing_internal_type) , private              :: surface_forcing_internal
+     type(marbl_surface_flux_share_type)       , private              :: surface_flux_share
+     type(marbl_surface_flux_internal_type)    , private              :: surface_flux_internal
      logical                                   , private              :: lallow_glo_ops
      type(marbl_internal_timers_type)          , private              :: timers
      type(marbl_timer_indexing_type)           , private              :: timer_ids
@@ -73,8 +73,8 @@ The class definition is shown below:
      procedure, public  :: extract_timing
      procedure, private :: glo_vars_init
      procedure, public  :: get_tracer_index
-     procedure, public  :: set_interior_forcing
-     procedure, public  :: set_surface_forcing
+     procedure, public  :: interior_tendency_compute
+     procedure, public  :: surface_flux_compute
      procedure, public  :: set_global_scalars
      procedure, public  :: shutdown
      generic            :: inquire_settings_metadata => inquire_settings_metadata_by_name, &

docs/src/usr-guide/GCM-interface/GCM_requirements/saved_state.rst

@@ -75,8 +75,8 @@ MARBL splits the saved state fields between those needed for computing surface f
 
 .. code-block:: fortran
 
-  marbl_instance%surface_saved_state
-  marbl_instance%interior_saved_state
+  marbl_instance%surface_flux_saved_state
+  marbl_instance%interior_tendency_saved_state
 
 Both of these are of type ``marbl_saved_state_type``:
 
@@ -110,9 +110,10 @@ Both of these are of type ``marbl_saved_state_type``:
 What Should the GCM Do?
 -----------------------
 
-After ``marbl_instance%set_surface_forcing()`` returns, the GCM needs to process ``marbl_intance%surface_saved_state``.
-That means looping through each element in the ``marbl_instance%surface_saved_state%state(:)`` array, checking ``state(n)%rank``, and then storing either ``state(n)%field_2d`` or ``state(n)%field_3d`` in a global array.
-Before calling ``set_surface_forcing()`` in the next time step, these saved values should be copied back into ``marbl_intance%surface_saved_state``.
+After ``marbl_instance%surface_flux_compute()`` returns, the GCM needs to process ``marbl_instance%surface_flux_saved_state``.
+That means looping through each element in the ``marbl_instance%surface_flux_saved_state%state(:)`` array, checking ``state(n)%rank``,
+and then storing either ``state(n)%field_2d`` or ``state(n)%field_3d`` in a global array.
+Before calling ``surface_flux_compute()`` in the next time step, these saved values should be copied back into ``marbl_intance%surface_flux_saved_state``.
 
-Similar actions must be taken with ``marbl_instance%interior_saved_state`` before / after calls to ``marbl_instance%set_interior_forcing()``.
+Similar actions must be taken with ``marbl_instance%interior_tendency_saved_state`` before / after calls to ``marbl_instance%interior_tendency_compute()``.