propagator_hop.h

Go to the documentation of this file.

      MODULE propagator_mod
!
!git $Id$
!================================================== Hernan G. Arango ===
!  Copyright (c) 2002-2025 The ROMS Group            Andrew M. Moore   !
!    Licensed under a MIT/X style license                              !
!    See License_ROMS.md                                               !
!=======================================================================
!                                                                      !
!  Optimal Perturbation (Hessian singular vectors) Propagator:         !
!                                                                      !
!  This routine solves the singular vectors of the propagator R(0,t)   !
!  which measure the  fastest  growing of all possible perturbations   !
!  over a given time interval. It involves a single integration of a   !
!  perturbation forward in time with the  tangent linear model  over   !
!  [0,t],  followed by an integration of the result backward in time   !
!  with the adjoint model over [t,0].                                  !
!                                                                      !
!   Reference:                                                         !
!                                                                      !
!     Moore, A.M. et al., 2004: A comprehensive ocean prediction and   !
!       analysis system based on the tangent linear and adjoint of a   !
!       regional ocean model, Ocean Modelling, 7, 227-258.             !
!                                                                      !
!     Smith, K. D., A. M. Moore, and H. G. Arango, 2015: Estimates of  !
!       ocean forecast error covariance derived from Hessian Singular  !
!       Vectors, Ocean Modelling, 89, 104-121,                         !
!       doi:10.1016/j.ocemod.2015.03.003.                              !
!                                                                      !
!=======================================================================
!
      USE mod_kinds
!
      implicit none
!
      PRIVATE
      PUBLIC  :: propagator_hop
!
      CONTAINS
!
!***********************************************************************
      SUBROUTINE propagator_hop (RunInterval, state, ad_state)
!***********************************************************************
!
      USE mod_param
      USE mod_parallel
#ifdef SOLVE3D
      USE mod_coupling
#endif
      USE mod_iounits
      USE mod_ocean
      USE mod_scalars
      USE mod_stepping
!
      USE close_io_mod,    ONLY : close_inp
      USE dotproduct_mod,  ONLY : tl_statenorm
      USE ini_adjust_mod,  ONLY : ad_ini_perturb
      USE inner2state_mod, ONLY : ad_inner2state, tl_inner2state
      USE inner2state_mod, ONLY : ini_c_norm
#ifdef SOLVE3D
      USE set_depth_mod,   ONLY : set_depth
#endif
      USE strings_mod,     ONLY : founderror
!
!  Imported variable declarations.
!
      real(dp), intent(in) :: runinterval
!
      TYPE (t_gst), intent(in) :: state(ngrids)
      TYPE (t_gst), intent(inout) :: ad_state(ngrids)
!
!  Local variable declarations.
!
      integer :: ng, tile
      integer :: ktmp, ntmp, lini
!
      real(r8) :: statenorm(ngrids)
!
      character (len=*), parameter :: myfile =                          &
     &  __FILE__
!
!=======================================================================
!  Forward integration of the tangent linear model.
!=======================================================================
!
      nrun=nrun+1
      IF (master) THEN
        DO ng=1,ngrids
          WRITE (stdout,10) ' PROPAGATOR - Grid: ', ng,                 &
     &                      ',  Iteration: ', nrun,                     &
     &                      ',  number converged RITZ values: ',        &
     &                      nconv(ng)
        END DO
      END IF
!
!  Initialize time stepping indices and counters.
!
      DO ng=1,ngrids
        iif(ng)=1
        indx1(ng)=1
        kstp(ng)=1
        krhs(ng)=1
        knew(ng)=1
        predictor_2d_step(ng)=.false.
!
        iic(ng)=0
        nstp(ng)=1
        nrhs(ng)=1
        nnew(ng)=1
!
        synchro_flag(ng)=.true.
        tdays(ng)=dstart
        time(ng)=tdays(ng)*day2sec
        ntstart(ng)=int((time(ng)-dstart*day2sec)/dt(ng))+1
        ntend(ng)=ntimes(ng)
        ntfirst(ng)=ntstart(ng)
      END DO
!
      lini=1
!
!-----------------------------------------------------------------------
!  Clear tangent linear state variables. There is not need to clean
!  the basic state arrays since they were zeroth out at initialization
!  and bottom of previous iteration.
!-----------------------------------------------------------------------
!
      DO ng=1,ngrids
        DO tile=first_tile(ng),last_tile(ng),+1
          CALL initialize_ocean (ng, tile, itlm)
        END DO
      END DO
 
#ifdef SOLVE3D
!
!-----------------------------------------------------------------------
!  Compute basic state initial level thicknesses used for state norm
!  scaling. It uses zero time-averaged free-surface (rest state).
!  Therefore, the norm scaling is time invariant.
!-----------------------------------------------------------------------
!
      DO ng=1,ngrids
        DO tile=last_tile(ng),first_tile(ng),-1
          CALL set_depth (ng, tile, itlm)
        END DO
      END DO
#endif
!
!-----------------------------------------------------------------------
!  Compute tangent linear initial conditions from state vector.
!-----------------------------------------------------------------------
!
      DO ng=1,ngrids
        DO tile=first_tile(ng),last_tile(ng),+1
          CALL tl_inner2state (ng, tile, lini, state(ng)%vector)
        END DO
      END DO
!
!-----------------------------------------------------------------------
!  Compute initial tangent linear state analysis error norm.
!-----------------------------------------------------------------------
!
      DO ng=1,ngrids
        DO tile=last_tile(ng),first_tile(ng),-1
          CALL ini_c_norm (ng, tile, kstp(ng), nstp(ng),                &
     &                     statenorm(ng))
        END DO
        IF (master) THEN
          WRITE (stdout,20) ' PROPAGATOR - Grid: ', ng,                 &
     &                      ',  Tangent Initial Norm: ', statenorm(ng)
        END IF
      END DO
!
!-----------------------------------------------------------------------
!  Read in initial forcing, climatology and assimilation data from
!  input NetCDF files.  It loads the first relevant data record for
!  the time-interpolation between snapshots.
!-----------------------------------------------------------------------
!
      DO ng=1,ngrids
        CALL close_inp (ng, itlm)
        IF (founderror(exit_flag, noerror, __line__, myfile)) RETURN
 
        CALL tl_get_idata (ng)
        IF (founderror(exit_flag, noerror, __line__, myfile)) RETURN
 
        CALL tl_get_data (ng)
        IF (founderror(exit_flag, noerror, __line__, myfile)) RETURN
      END DO
!
!-----------------------------------------------------------------------
!  Time-step the tangent linear model.
!-----------------------------------------------------------------------
!
      DO ng=1,ngrids
        IF (master) THEN
          WRITE (stdout,30) 'TL', ng, ntstart(ng), ntend(ng)
        END IF
        time(ng)=time(ng)-dt(ng)
        iic(ng)=ntstart(ng)-1
      END DO
 
#ifdef SOLVE3D
      CALL tl_main3d (runinterval)
#else
      CALL tl_main2d (runinterval)
#endif
      IF (founderror(exit_flag, noerror, __line__, myfile)) RETURN
!
!-----------------------------------------------------------------------
!  Clear nonlinear (basic state) and adjoint state variables.
!-----------------------------------------------------------------------
!
      DO ng=1,ngrids
        DO tile=first_tile(ng),last_tile(ng),+1
          CALL initialize_ocean (ng, tile, inlm)
          CALL initialize_ocean (ng, tile, iadm)
#ifdef SOLVE3D
          CALL initialize_coupling (ng, tile, 0)
#endif
        END DO
      END DO
 
#ifdef SOLVE3D
!
!-----------------------------------------------------------------------
!  Compute basic state final level thicknesses used for state norm
!  scaling. It uses zero time-averaged free-surface (rest state).
!  Therefore, the norm scaling is time invariant.
!-----------------------------------------------------------------------
!
      DO ng=1,ngrids
        DO tile=last_tile(ng),first_tile(ng),-1
          CALL set_depth (ng, tile, itlm)
        END DO
      END DO
#endif
!
!-----------------------------------------------------------------------
!  Compute final tangent linear energy norm.
!-----------------------------------------------------------------------
!
      DO ng=1,ngrids
        DO tile=first_tile(ng),last_tile(ng),+1
          CALL tl_statenorm (ng, tile, knew(ng), nstp(ng),              &
     &                       statenorm(ng))
        END DO
        IF (master) THEN
          WRITE (stdout,20) ' PROPAGATOR - Grid: ', ng,                 &
     &                      ',  Tangent   Final Norm: ', statenorm(ng)
        END IF
      END DO
!
!=======================================================================
!  Backward integration with the adjoint model.
!=======================================================================
!
!  Initialize time stepping indices and counters.
!
      DO ng=1,ngrids
        iif(ng)=1
        indx1(ng)=1
        ktmp=knew(ng)
        kstp(ng)=1
        krhs(ng)=3
        knew(ng)=2
        predictor_2d_step(ng)=.false.
!
        iic(ng)=0
        ntmp=nstp(ng)
        nstp(ng)=1
        nrhs(ng)=1
        nnew(ng)=2
!
        synchro_flag(ng)=.true.
        tdays(ng)=dstart+dt(ng)*real(ntimes(ng),r8)*sec2day
        time(ng)=tdays(ng)*day2sec
        ntstart(ng)=ntimes(ng)+1
        ntend(ng)=1
        ntfirst(ng)=ntend(ng)
      END DO
!
!-----------------------------------------------------------------------
!  Initialize adjoint model with the final tangent linear solution
!  scaled by the energy norm.
!-----------------------------------------------------------------------
!
      DO ng=1,ngrids
        DO tile=last_tile(ng),first_tile(ng),-1
          CALL ad_ini_perturb (ng, tile,                                &
     &                         ktmp, knew(ng), ntmp, nstp(ng))
        END DO
      END DO
!
!-----------------------------------------------------------------------
!  Read in initial forcing, climatology and assimilation data from
!  input NetCDF files.  It loads the first relevant data record for
!  the time-interpolation between snapshots.
!-----------------------------------------------------------------------
!
      DO ng=1,ngrids
        CALL close_inp (ng, iadm)
        IF (founderror(exit_flag, noerror, __line__, myfile)) RETURN
 
        CALL ad_get_idata (ng)
        IF (founderror(exit_flag, noerror, __line__, myfile)) RETURN
 
        CALL ad_get_data (ng)
        IF (founderror(exit_flag, noerror, __line__, myfile)) RETURN
      END DO
!
!-----------------------------------------------------------------------
!  Time-step the adjoint model backwards.
!-----------------------------------------------------------------------
!
      DO ng=1,ngrids
        IF (master) THEN
          WRITE (stdout,30) 'AD', ng, ntstart(ng), ntend(ng)
        END IF
        time(ng)=time(ng)+dt(ng)
        iic(ng)=ntstart(ng)+1
      END DO
 
#ifdef SOLVE3D
      CALL ad_main3d (runinterval)
#else
      CALL ad_main2d (runinterval)
#endif
      IF (founderror(exit_flag, noerror, __line__, myfile)) RETURN
!
!-----------------------------------------------------------------------
!  Clear nonlinear state (basic state) variables for next iteration
!  and to insure a rest state time averaged free-surface before adjoint
!  state norm scaling.
!-----------------------------------------------------------------------
!
      DO ng=1,ngrids
        DO tile=first_tile(ng),last_tile(ng),+1
          CALL initialize_ocean (ng, tile, inlm)
#ifdef SOLVE3D
          CALL initialize_coupling (ng, tile, 0)
#endif
        END DO
      END DO
 
#ifdef SOLVE3D
!
!-----------------------------------------------------------------------
!  Compute basic state initial level thicknesses used for state norm
!  scaling. It uses zero free-surface (rest state).  Therefore, the
!  norm scaling is time invariant.
!-----------------------------------------------------------------------
!
      DO ng=1,ngrids
        DO tile=last_tile(ng),first_tile(ng),-1
          CALL set_depth (ng, tile, iadm)
        END DO
      END DO
#endif
!
!-----------------------------------------------------------------------
!  Compute adjoint state vector.
!-----------------------------------------------------------------------
!
      DO ng=1,ngrids
        DO tile=first_tile(ng),last_tile(ng),+1
          CALL ad_inner2state (ng, tile, lini, ad_state(ng)%vector)
        END DO
      END DO
!
 10   FORMAT (/,a,i2.2,a,i3.3,a,i3.3/)
 20   FORMAT (/,a,i2.2,a,1p,e15.6,/)
 30   FORMAT (/,1x,a,1x,'ROMS: started time-stepping:',                 &
     &        ' (Grid: ',i2.2,' TimeSteps: ',i8.8,' - ',i8.8,')')
!
      RETURN
      END SUBROUTINE propagator_hop
 
      END MODULE propagator_mod