Index: /branches/UKMO/dev_r5518_GO6_package_asm_3d_bgc/NEMOGCM/NEMO/OPA_SRC/ASM/asmbgc.F90
===================================================================
--- /branches/UKMO/dev_r5518_GO6_package_asm_3d_bgc/NEMOGCM/NEMO/OPA_SRC/ASM/asmbgc.F90	(revision 9296)
+++ /branches/UKMO/dev_r5518_GO6_package_asm_3d_bgc/NEMOGCM/NEMO/OPA_SRC/ASM/asmbgc.F90	(revision 9297)
@@ -1,9 +1,9 @@
 MODULE asmbgc
-   !!======================================================================
+   !!===========================================================================
    !!                       ***  MODULE asmbgc  ***
    !! Routines and declarations for biogeochemical assimilation
-   !!======================================================================
+   !!===========================================================================
    !! History :  3.6  ! 2018-02 (D. Ford)  Adapted from existing modules
-   !!----------------------------------------------------------------------
+   !!---------------------------------------------------------------------------
    !! 'key_asminc'          : assimilation increment interface
    !! 'key_top'             : passive tracers
@@ -13,69 +13,83 @@
    !! 'key_roam'            : MEDUSA extras for carbonate cycle
    !! 'key_karaml'          : Kara mixed layer depth
-   !!----------------------------------------------------------------------
-   !! asm_bgc_check_options : check biogeochemical assimilation options
+   !!---------------------------------------------------------------------------
+   !! asm_bgc_check_options : check bgc assimilation options
    !! asm_bgc_init_incs     : initialise bgc increments
    !! asm_bgc_init_bkg      : initialise bgc background
-   !! asm_bgc_bal_wri       : write out balancing increments
+   !! asm_bgc_bal_wri       : write out bgc balancing increments
    !! asm_bgc_bkg_wri       : write out bgc background
    !! slchltot_asm_inc      : apply the slchltot increment
    !! spco2_asm_inc         : apply the pCO2/fCO2 increment
-   !!----------------------------------------------------------------------
-   USE par_kind,      ONLY: wp             ! kind parameters
-   USE par_oce,       ONLY: jpi, jpj, jpk  ! domain array sizes
-   USE iom                                 ! i/o
-   USE zdfmxl, ONLY :  &  
-!   &  hmld_tref,       &   
+   !!---------------------------------------------------------------------------
+   USE par_kind, ONLY:      & ! kind parameters
+      & wp
+   USE par_oce, ONLY:       & ! domain array sizes
+      & jpi,                &
+      & jpj,                &
+      & jpk
+   USE iom                    ! i/o
+   USE oce, ONLY:           & ! active tracer variables
+      & tsn
+   USE zdfmxl, ONLY :       & ! mixed layer depth 
 #if defined key_karaml
-   &  hmld_kara,       &
-   &  ln_kara,         &
+      & hmld_kara,          &
+      & ln_kara,            &
 #endif   
-   &  hmld,            & 
-   &  hmlp,            &
-   &  hmlpt 
+      & hmld,               & 
+      & hmlp,               &
+      & hmlpt 
+   USE asmpar, ONLY:        & ! assimilation parameters
+      & c_asmbkg,           &
+      & c_asmbal,           &
+      & nitbkg_r,           &
+      & nitdin_r,           &
+      & nitiaustr_r,        &
+      & nitiaufin_r
 #if defined key_top
-   USE trc, ONLY: &
-      & trn,      &
+   USE trc, ONLY:           & ! passive tracer variables
+      & trn,                &
       & trb
-   USE par_trc, ONLY: &
+   USE par_trc, ONLY:       & ! passive tracer parameters
       & jptra
 #endif
 #if defined key_medusa && defined key_foam_medusa
-   USE asmlogchlbal_medusa, ONLY: &
+   USE asmlogchlbal_medusa, ONLY: & ! logchl balancing for MEDUSA
       & asm_logchl_bal_medusa
-   USE asmpco2bal, ONLY: &
+   USE asmpco2bal, ONLY:    & ! pCO2 balancing for MEDUSA
       & asm_pco2_bal
-   USE par_medusa
-   USE mocsy_mainmod     ! f2pCO2
-   USE sms_medusa, ONLY: pgrow_avg, &
-      &                  ploss_avg, &
-      &                  phyt_avg,  &
-      &                  mld_max
+   USE par_medusa             ! MEDUSA parameters
+   USE mocsy_mainmod, ONLY: & ! MEDUSA carbonate system
+      & f2pCO2
+   USE sms_medusa, ONLY:    & ! MEDUSA diagnostic variables
+      & pgrow_avg,          &
+      & ploss_avg,          &
+      & phyt_avg,           &
+      & mld_max
 #elif defined key_hadocc
-   USE asmlogchlbal_hadocc, ONLY: &
+   USE asmlogchlbal_hadocc, ONLY: & ! logchl balancing for HadOCC
       & asm_logchl_bal_hadocc
-   USE asmpco2bal, ONLY: &
+   USE asmpco2bal, ONLY:    & ! pCO2 balancing for HadOCC
       & asm_pco2_bal
-   USE par_hadocc
-   USE trc, ONLY: pgrow_avg, &
-       &     ploss_avg, &
-       &     phyt_avg,  &
-       &     mld_max,   &
-       &     HADOCC_CHL
-   USE had_bgc_const, ONLY: cchl_p
-#endif
-   USE asmpar    ! c_asmbkg, c_asmbal, nitbkg_r, nitdin_r, nitiaustr_r, nitiaufin_r
-   USE oce              ! tsn
+   USE par_hadocc             ! HadOCC parameters
+   USE trc, ONLY:           & ! HadOCC diagnostic variables
+      & pgrow_avg,          &
+      & ploss_avg,          &
+      & phyt_avg,           &
+      & mld_max,            &
+      & HADOCC_CHL
+   USE had_bgc_const, ONLY: & ! HadOCC C:Chl ratio
+      & cchl_p
+#endif
 
    IMPLICIT NONE
    PRIVATE                   
 
-   PUBLIC asm_bgc_check_options
-   PUBLIC asm_bgc_init_incs
-   PUBLIC asm_bgc_init_bkg
-   PUBLIC asm_bgc_bal_wri
-   PUBLIC asm_bgc_bkg_wri
-   PUBLIC slchltot_asm_inc
-   PUBLIC spco2_asm_inc
+   PUBLIC asm_bgc_check_options  ! called by asm_inc_init in asminc.F90
+   PUBLIC asm_bgc_init_incs      ! called by asm_inc_init in asminc.F90
+   PUBLIC asm_bgc_init_bkg       ! called by asm_inc_init in asminc.F90
+   PUBLIC asm_bgc_bal_wri        ! called by nemo_gcm in nemogcm.F90
+   PUBLIC asm_bgc_bkg_wri        ! called by asm_bkg_wri in asmbkg.F90
+   PUBLIC slchltot_asm_inc       ! called by bgc_asm_inc in asminc.F90
+   PUBLIC spco2_asm_inc          ! called by bgc_asm_inc in asminc.F90
 
    LOGICAL, PUBLIC :: ln_balwri = .FALSE.        !: No output of balancing incs
@@ -85,36 +99,46 @@
    LOGICAL, PUBLIC :: ln_sfco2inc = .FALSE.      !: No fCO2 increment
 
-   REAL(wp), PUBLIC, DIMENSION(:,:), ALLOCATABLE :: slchltot_bkginc !: Increment to background slchltot
-   REAL(wp), PUBLIC, DIMENSION(:,:), ALLOCATABLE :: spco2_bkginc   !: Increment to background pCO2
+   INTEGER, PUBLIC :: mld_choice_bgc = 1 !: choice of mld for bgc assimilation
+                                         !  1) hmld      - Turbocline/mixing depth
+                                         !                 [W points]
+                                         !  2) hmlp      - Density criterion
+                                         !                 (0.01 kg/m^3 change from 10m)
+                                         !                 [W points]
+                                         !  3) hmld_kara - Kara MLD
+                                         !                 [Interpolated]
+                                         !  4) hmld_tref - Temperature criterion
+                                         !                 (0.2 K change from surface)
+                                         !                 [T points]
+                                         !  5) hmlpt     - Density criterion
+                                         !                 (0.01 kg/m^3 change from 10m)
+                                         !                 [T points]
+
+   REAL(wp), PUBLIC :: rn_maxchlinc = -999.0 !: maximum absolute non-log chlorophyll inc
+                                             ! <= 0 no maximum applied (switch turned off)
+                                             !  > 0 absolute chl inc capped at this value
+
+   REAL(wp), DIMENSION(:,:),     ALLOCATABLE :: slchltot_bkginc ! slchltot inc
+   REAL(wp), DIMENSION(:,:),     ALLOCATABLE :: spco2_bkginc    ! sp(/f)co2 inc
 #if defined key_top
-   REAL(wp), PUBLIC, DIMENSION(:,:,:,:), ALLOCATABLE :: slchltot_balinc  !: Increment to BGC variables from logchl assim
-   REAL(wp), PUBLIC, DIMENSION(:,:,:,:), ALLOCATABLE :: spco2_balinc    !: Increment to BGC variables from pCO2 assim
-#endif
+   REAL(wp), DIMENSION(:,:,:,:), ALLOCATABLE :: slchltot_balinc ! Balancing incs from slchltot asm
+   REAL(wp), DIMENSION(:,:,:,:), ALLOCATABLE :: spco2_balinc    ! Balancing incs from sp(/f)co2 asm
+#endif
+
 #if defined key_hadocc || (defined key_medusa && defined key_foam_medusa)
-   REAL(wp), DIMENSION(:,:),     ALLOCATABLE :: pgrow_avg_bkg  !: Background phyto growth for logchl balancing
-   REAL(wp), DIMENSION(:,:),     ALLOCATABLE :: ploss_avg_bkg  !: Background phyto loss for logchl balancing
-   REAL(wp), DIMENSION(:,:),     ALLOCATABLE :: phyt_avg_bkg   !: Background phyto for logchl balancing
-   REAL(wp), DIMENSION(:,:),     ALLOCATABLE :: mld_max_bkg    !: Background max MLD for logchl balancing
-   REAL(wp), DIMENSION(:,:,:,:), ALLOCATABLE :: tracer_bkg     !: Background tracer state variables
+   REAL(wp), DIMENSION(:,:),     ALLOCATABLE :: pgrow_avg_bkg   ! Background phyto growth
+   REAL(wp), DIMENSION(:,:),     ALLOCATABLE :: ploss_avg_bkg   ! Background phyto loss
+   REAL(wp), DIMENSION(:,:),     ALLOCATABLE :: phyt_avg_bkg    ! Background phyto conc
+   REAL(wp), DIMENSION(:,:),     ALLOCATABLE :: mld_max_bkg     ! Background max MLD
+   REAL(wp), DIMENSION(:,:,:,:), ALLOCATABLE :: tracer_bkg      ! Background tracer state
 #endif
 #if defined key_hadocc
-   REAL(wp), DIMENSION(:,:),     ALLOCATABLE :: chl_bkg        !: Background surface chlorophyll
-   REAL(wp), DIMENSION(:,:),     ALLOCATABLE :: cchl_p_bkg     !: Background surface carbon:chlorophyll
-#endif
-   REAL(wp), PUBLIC :: rn_maxchlinc = -999.0  !: maximum absolute non-log chlorophyll increment from logchl assimilation
-                                      !: <= 0 implies no maximum applied (switch turned off)
-                                      !:  > 0 implies maximum absolute chl increment capped at this value
-
-   INTEGER, PUBLIC :: mld_choice_bgc    = 1   !: choice of mld criteria to use for biogeochemistry assimilation
-                                      !: 1) hmld      - Turbocline/mixing depth                           [W points]
-                                      !: 2) hmlp      - Density criterion (0.01 kg/m^3 change from 10m)   [W points]
-                                      !: 3) hmld_kara - Kara MLD                                          [Interpolated]
-                                      !: 4) hmld_tref - Temperature criterion (0.2 K change from surface) [T points]
-                                      !: 5) hmlpt     - Density criterion (0.01 kg/m^3 change from 10m)   [T points]
+   REAL(wp), DIMENSION(:,:),     ALLOCATABLE :: chl_bkg         ! Background surface chl
+   REAL(wp), DIMENSION(:,:),     ALLOCATABLE :: cchl_p_bkg      ! Background surface c:chl
+#endif
 
 CONTAINS
 
    SUBROUTINE asm_bgc_check_options
-      !!---------------------------------------------------------------------------
+      !!------------------------------------------------------------------------
       !!                    ***  ROUTINE asm_bgc_check_options  ***
       !!
@@ -126,7 +150,8 @@
       !!
       !! References :   asm_inc_init
-      !!---------------------------------------------------------------------------
-
-      IF ( ( ln_balwri ).AND.( .NOT. ln_slchltotinc ).AND.( .NOT. ln_spco2inc ).AND.( .NOT. ln_sfco2inc ) ) THEN
+      !!------------------------------------------------------------------------
+
+      IF ( ( ln_balwri ).AND.( .NOT. ln_slchltotinc ).AND. &
+         & ( .NOT. ln_spco2inc ).AND.( .NOT. ln_sfco2inc ) ) THEN
          CALL ctl_warn( ' Balancing increments are only calculated for logchl and pCO2/fCO2', &
             &           ' Not assimilating logchl, pCO2 or fCO2, so ln_balwri will be set to .false.')
@@ -146,10 +171,10 @@
    END SUBROUTINE asm_bgc_check_options
 
-   !!======================================================================
-   !!======================================================================
-   !!======================================================================
+   !!===========================================================================
+   !!===========================================================================
+   !!===========================================================================
 
    SUBROUTINE asm_bgc_init_incs( knum )
-      !!---------------------------------------------------------------------------
+      !!------------------------------------------------------------------------
       !!                    ***  ROUTINE asm_bgc_init_incs  ***
       !!
@@ -161,9 +186,9 @@
       !!
       !! References :   asm_inc_init
-      !!---------------------------------------------------------------------------
+      !!------------------------------------------------------------------------
       !!
       INTEGER, INTENT(in   ) :: knum   ! i/o unit of increments file
       !!
-      !!---------------------------------------------------------------------------
+      !!------------------------------------------------------------------------
 
       IF ( ln_slchltotinc ) THEN
@@ -208,10 +233,10 @@
    END SUBROUTINE asm_bgc_init_incs
 
-   !!======================================================================
-   !!======================================================================
-   !!======================================================================
+   !!===========================================================================
+   !!===========================================================================
+   !!===========================================================================
 
    SUBROUTINE asm_bgc_init_bkg
-      !!---------------------------------------------------------------------------
+      !!------------------------------------------------------------------------
       !!                    ***  ROUTINE asm_bgc_init_bkg  ***
       !!
@@ -223,10 +248,10 @@
       !!
       !! References :   asm_inc_init
-      !!---------------------------------------------------------------------------
+      !!------------------------------------------------------------------------
       !!
       INTEGER :: inum   ! i/o unit of background file
       INTEGER :: jt     ! loop counter
       !!
-      !!---------------------------------------------------------------------------
+      !!------------------------------------------------------------------------
 
 #if defined key_hadocc || (defined key_medusa && defined key_foam_medusa)
@@ -349,10 +374,10 @@
    END SUBROUTINE asm_bgc_init_bkg
 
-   !!======================================================================
-   !!======================================================================
-   !!======================================================================
+   !!===========================================================================
+   !!===========================================================================
+   !!===========================================================================
 
    SUBROUTINE asm_bgc_bal_wri( kt )
-      !!-----------------------------------------------------------------------
+      !!------------------------------------------------------------------------
       !!
       !!                  ***  ROUTINE asm_bgc_bal_wri ***
@@ -370,5 +395,5 @@
       !! History    :
       !!        ! 2014-08 (D. Ford)  Initial version, based on asm_bkg_wri
-      !!-----------------------------------------------------------------------
+      !!------------------------------------------------------------------------
       !! * Arguments
       INTEGER, INTENT( IN ) :: kt        ! Current time-step
@@ -378,5 +403,5 @@
       INTEGER           :: inum          ! File unit number
       REAL(wp)          :: zdate         ! Date
-      !!-----------------------------------------------------------------------
+      !!------------------------------------------------------------------------
      
       ! Set things up
@@ -456,10 +481,10 @@
    END SUBROUTINE asm_bgc_bal_wri
 
-   !!======================================================================
-   !!======================================================================
-   !!======================================================================
+   !!===========================================================================
+   !!===========================================================================
+   !!===========================================================================
 
    SUBROUTINE asm_bgc_bkg_wri( kt, knum )
-      !!---------------------------------------------------------------------------
+      !!------------------------------------------------------------------------
       !!                    ***  ROUTINE asm_bgc_bkg_wri  ***
       !!
@@ -471,10 +496,10 @@
       !!
       !! References :   asm_bkg_wri
-      !!---------------------------------------------------------------------------
+      !!------------------------------------------------------------------------
       !!
       INTEGER, INTENT(in   ) :: kt     ! Current time-step
       INTEGER, INTENT(in   ) :: knum   ! i/o unit of increments file
       !!
-      !!---------------------------------------------------------------------------
+      !!------------------------------------------------------------------------
 
 #if defined key_hadocc
@@ -515,10 +540,10 @@
    END SUBROUTINE asm_bgc_bkg_wri
 
-   !!======================================================================
-   !!======================================================================
-   !!======================================================================
+   !!===========================================================================
+   !!===========================================================================
+   !!===========================================================================
 
    SUBROUTINE slchltot_asm_inc( kt, ll_asmdin, ll_asmiau, kcycper, pwgtiau )
-      !!----------------------------------------------------------------------
+      !!------------------------------------------------------------------------
       !!                    ***  ROUTINE logchl_asm_inc  ***
       !!          
@@ -530,5 +555,5 @@
       !!
       !! ** Action  : 
-      !!----------------------------------------------------------------------
+      !!------------------------------------------------------------------------
       INTEGER,  INTENT(IN) :: kt        ! Current time step
       LOGICAL,  INTENT(IN) :: ll_asmdin ! Flag for direct initialisation
@@ -541,5 +566,5 @@
       REAL(wp) :: zincwgt         ! IAU weight for current time step
       REAL(wp) :: zincper         ! IAU interval in seconds
-      !!----------------------------------------------------------------------
+      !!------------------------------------------------------------------------
 
       IF ( kt <= nit000 ) THEN
@@ -645,11 +670,11 @@
    END SUBROUTINE slchltot_asm_inc
 
-   !!======================================================================
-   !!======================================================================
-   !!======================================================================
+   !!===========================================================================
+   !!===========================================================================
+   !!===========================================================================
 
    SUBROUTINE spco2_asm_inc( kt, ll_asmdin, ll_asmiau, kcycper, pwgtiau, &
       &                      ll_trainc, pt_bkginc, ps_bkginc )
-      !!----------------------------------------------------------------------
+      !!------------------------------------------------------------------------
       !!                    ***  ROUTINE pco2_asm_inc  ***
       !!          
@@ -661,5 +686,5 @@
       !!
       !! ** Action  : 
-      !!----------------------------------------------------------------------
+      !!------------------------------------------------------------------------
       INTEGER, INTENT(IN)                   :: kt           ! Current time step
       LOGICAL, INTENT(IN)                   :: ll_asmdin    ! Flag for direct initialisation
@@ -693,11 +718,11 @@
       REAL(wp)                              :: zcoef_fco2_7 = 0.118
       REAL(wp)                              :: zcoef_fco2_8 = 82.0578
-      !!----------------------------------------------------------------------
+      !!------------------------------------------------------------------------
 
       IF ( kt <= nit000 ) THEN
 
-         !--------------------------------------------------------------------
+         !----------------------------------------------------------------------
          ! DIC and alkalinity balancing
-         !--------------------------------------------------------------------
+         !----------------------------------------------------------------------
 
          IF ( ln_sfco2inc ) THEN
@@ -912,5 +937,5 @@
    END SUBROUTINE spco2_asm_inc
 
-   !!======================================================================
+   !!===========================================================================
 
 END MODULE asmbgc
