id	summary	reporter	owner	description	type	status	priority	milestone	component	version	resolution	keywords	cc
897	VERY IMPORTANT:  Adding ROMS-JEDI driver and Refactoring Modules	arango		"This is an important update to facilitate the coding of the '''ROMS-JEDI''' interface.   The development of the '''ROMS-JEDI''' interface is still private within '''JCSDA''' !GitHub repositories.  It is not ready for any application since it is still under development.  However, several changes are made to improve ROMS.

* A new driver '''ROMS/Drivers/jedi_roms.h''' is added to facilitate '''JEDI''' to take direct control of the ROMS '''initialize''', '''run''', and '''finalize''' phases for the '''NLM''', '''TLM,''' and '''ADM''' dynamical/numerical kernels.  It is activated with new C-preprocessing option '''JEDI'''.  It uses the same strategy as coupling where the ESMF/NUOPC library controls how the ROMS kernel is initialized, advanced, and terminated.

* All the ROMS modules are refactored to include a '''deallocation''' subroutine.  For example, '''mod_ocean.F''' now includes '''allocate_ocean''', '''deallocate_ocean''', and '''initialize_ocean''' subroutines.
 
 The destroying (deallocating) of all ROMS derived-type structures is essential in Object-Oriented Programming ('''OOP''') for releasing memory space, avoiding memory leaks, and facilitating changing the size of the state arrays (regridding).  Recall that all the ROMS derived-type objects include several pointer-variables. After a variable has been deallocated, it cannot be defined or referenced until it is allocated or assigned again.

* A new module '''ROMS/Utility/destroy.F''' is added to deallocate each variable in the derived-type structure separately. However, it is not used by default since the Fortran '''2003''' standard allows deallocating just the parent object to deallocate all array variables within its scope automatically. So, for example, to deallocate all the variables in the '''OCEAN(:)''' structure, we need:
 {{{
      IF (ng.eq.Ngrids) THEN
        IF (allocated(OCEAN)) deallocate ( OCEAN )
      END IF
}}}
 We expect that all the Users of ROMS have at least a '''Fortran 2003''' compiler.  Otherwise, it is possible to activate the new C-preprocessing option '''SUBOBJECT_DEALLOCATION''' to deallocate each pointer variable within the structure object. For example:
 {{{
      IF (.not.destroy(ng, OCEAN(ng)%zeta, MyFile,                      &
     &                 __LINE__, 'OCEAN(ng)%zeta')) RETURN

}}}
 Here, the ROMS function '''destroy''' deallocates the free-surface pointer variable '''zeta''' in the '''OCEAN(ng)''' structure for nested grid '''ng'''.

 By the way, the '''DEALLOCATE''' Fortran statement releases the space allocated for an allocatable variable or a pointer target and nullifies the pointer.

* The modules '''mod_param.F''', '''mod_parallel.F''', '''mod_iounits.F''', and '''mod_scalars.F''' were slightly modified to avoid cyclic dependencies when compiling.  It required to pass the '''Ngrids''' as argument in few allocation calls in '''read_phypar.F''':
 {{{
            CASE ('Ngrids')
              Npts=load_i(Nval, Rval, 1, Ivalue)
              Ngrids=Ivalue(1)
              IF (Ngrids.le.0) THEN
                IF (Master) WRITE (out,290) 'Ngrids', Ngrids,           &
     &            'must be greater than zero.'
                exit_flag=5
                RETURN
              END IF
              got_Ngrids=.TRUE.                ! Allocating variables in
              CALL allocate_param              ! modules that solely
              CALL allocate_parallel (Ngrids)  ! depend on the number 
              CALL allocate_iounits (Ngrids)   ! nested grids
              CALL allocate_stepping (Ngrids)
              ...
}}}

* The module '''mod_arrays.F''' is restructured into three distinct routines: '''ROMS_allocate_arrays''', '''ROMS_deallocate_arrays''', and '''ROMS_initialize_arrays'''. It cleans nicely the module '''roms_kernel_mod''' for all available drivers.

* Added the reporting of the '''river_file''' global attribute in output NetCDF files. In '''def_info.F''', we have:
 {{{
#ifndef ANA_PSOURCE
        IF (exit_flag.eq.NoError) THEN
          IF (LuvSrc(ng).or.LwSrc(ng).or.(ANY(LtracerSrc(:,ng)))) THEN
            status=nf90_put_att(ncid, nf90_global, 'river_file',        &
     &                          TRIM(SSF(ng)%name))
            IF (FoundError(status, nf90_noerr, __LINE__, MyFile)) THEN
              IF (Master) WRITE (stdout,20) 'river_file', TRIM(ncname)
              exit_flag=3
              ioerror=status
            END IF
          END IF
        END IF
#endif
}}}
 Many thanks to John Wilkin for bringing this issue to my attention.

* Corrected a typo in the CPP directives in '''ad_get_data.F''', '''tl_get_data.F''', and '''rp_get_data.F'''. We need to have
 {{{
# if !defined ANA_PAIR       && \
     (defined ATM_PRESS      || defined BULK_FLUXES  || \
      defined ECOSIM)
#  if !(defined FRC_COUPLING || defined FORWARD_FLUXES)
}}}
 a space was added before '''FORWARD_FLUXES'''. Many thanks to Raquel Toste for [https://www.myroms.org/forum/viewtopic.php?f=19&t=5916 reporting] this typo.
"	upgrade	closed	major	Release ROMS/TOMS 4.0	Nonlinear	3.9	Done