Adding dH/dt module

From Interactive System for Ice sheet Simulation
Revision as of 12:17, 22 July 2009 by Sprice (Talk | contribs)

Jump to: navigation, search

This page contains step-by-step instructions for adding a new module to Glimmer-CISM. In this case, the module is a first-order, upwinding advection scheme for mass transport (dH/dt) using velocities calculated from a higher-order dynamics model. The procedure, however, is generic and could apply to adding almost any module. The goal here is not to get lost in the details of the upwinding scheme (we'll provide the code for that later) but rather to understand the steps for adding a module in an incremental, structured way that allows you to track small errors and fix them at each step.

Step 1

In step 1, we will create modules containing "empty" subroutines and add these modules to the build.

First, create a module for_upwind_advect_mod.F90 that contains the necessary subroutines. For now, these will just be "stubs", which we will fill in later.

module fo_upwind_advect_mod
 
! subroutines for mass advection scheme based on 1st order upwinding
 
    contains
 
!----------------------------------------------------------------------
 
    subroutine fo_upwind_advect_init( )
 
    ! initialization for 1st-order upwinding mass advection
 
    end subroutine fo_upwind_advect_init
 
!----------------------------------------------------------------------
 
    subroutine fo_upwind_advect_final( )
 
    ! finalization for 1st-order upwinding mass advection
 
    end subroutine fo_upwind_advect_final
 
!----------------------------------------------------------------------
 
    subroutine fo_upwind_advect_main( )
 
    ! 1st-order upwinding mass advection
 
    end subroutine fo_upwind_advect_main
 
!----------------------------------------------------------------------
 
end module fo_upwind_advect_mod

Now create another module for_upwind_advect.F90 that will contain the "driver" subroutine - that which is called from the main code, which in this case is glide.F90 ...

module fo_upwind_advect
 
    ! this is the driver routine for the 1st order, upwind mass transport scheme
 
    use fo_upwind_advect_mod, only : fo_upwind_advect_main
 
    implicit none
    private
    public :: fo_upwind_advect_driver
 
    contains
 
    subroutine fo_upwind_advect_driver( )
 
        call fo_upwind_advect_main( )
 
    end subroutine fo_upwind_advect_driver
 
end module fo_upwind_advect

NOTE: This may seem like extra work ... why don't we just call the subroutine fo_upwind_advect_main directly from the main code? In this case, perhaps this is true. In general, however, having a "driver" routine is good practice. For example, there might be additional pre/post processing of variables that needs to take place before and after the call to the subroutine fo_upwind_advect_main. Making space for that here rather than in the main program, where only the driver is called, makes more sense and keeps the main code cleaner and easier to understand.

Add these new modules to the build by altering the file Makefile.am ...

libglide_a_SOURCES = glide.F90 glide_setup.F90 glide_types.F90 glide_temp.F90 \
                     glide_bwater.F90 glide_deriv.F90 xls.F90 ice3d_lib.F90 \
                     glide_velo_higher.F90 glide_thck.F90 glide_velo.F90 \
                     glide_mask.F90 glide_stop.F90 glide_io.F90 \
                     glide_nc_custom.F90 isostasy.F90 isostasy_el.F90\
                     isostasy_setup.F90 isostasy_types.F90 glide_lithot.F90\
                     glide_lithot3d.F90 glide_lithot1d.F90 glide_profile.F90\
                     glide_diagnostics.F90 glissade.F90 glissade_remap.F90\
                     glissade_velo.F90 glissade_constants.F90 glide_vertint.F90\
                     glide_thckmask.F90 glide_nonlin.F90 glide_grids.F90\
                     glam.F90 glam_strs2.F90 glam_thck_ppm.F90\
                     remap_advection.F90 remap_glamutils.F90 glide_ground.F90

becomes ...

libglide_a_SOURCES = glide.F90 glide_setup.F90 glide_types.F90 glide_temp.F90 \
                     glide_bwater.F90 glide_deriv.F90 xls.F90 ice3d_lib.F90 \
                     glide_velo_higher.F90 glide_thck.F90 glide_velo.F90 \
                     glide_mask.F90 glide_stop.F90 glide_io.F90 \
                     glide_nc_custom.F90 isostasy.F90 isostasy_el.F90\
                     isostasy_setup.F90 isostasy_types.F90 glide_lithot.F90\
                     glide_lithot3d.F90 glide_lithot1d.F90 glide_profile.F90\
                     glide_diagnostics.F90 glissade.F90 glissade_remap.F90\
                     glissade_velo.F90 glissade_constants.F90 glide_vertint.F90\
                     glide_thckmask.F90 glide_nonlin.F90 glide_grids.F90\
                     glam.F90 glam_strs2.F90 glam_thck_ppm.F90\
                     remap_advection.F90 remap_glamutils.F90 glide_ground.F90 \     ! CHANGED LAST TWO LINES
	              fo_upwind_advect_mod.F90, fo_upwind_advect.F90

Now we stop adding/editing things for a minute and type make to rebuild and make sure we haven't broken the code yet. If you get a successful build, then proceed to Step 2.

Step 2

In step 2, we will do some minor updates to other parts of the code so that there is an option to call our 1st order upwinding scheme when we want to evolve the ice thickness (that is, rather than using some other scheme).

In glide_types.F90, add the following to the transport scheme options around line 100 ...

  integer, parameter :: EVOL_PSEUDO_DIFF = 0
  integer, parameter :: EVOL_ADI = 1
  integer, parameter :: EVOL_DIFFUSION = 2
  integer, parameter :: EVOL_INC_REMAP = 3
  integer, parameter :: EVOL_FO_UPWIND = 4         ! ADDED THIS LINE

... similarly, update some lines around 207 for documentation ...

    !*FD Thickness evolution method:
    !*FD \begin{description}
    !*FD \item[0] Pseudo-diffusion approach 
    !*FD \item[2] Diffusion approach (also calculates velocities)
    !*FD \item[3] Incremental remapping
    !*FD \item[4] 1st-order upwinding scheme       ! ADDED THIS LINE
    !*FD \end{description}

In glide_setup.F90, around line 475, change ...

    character(len=*), dimension(0:4), parameter :: evolution = (/ &    ! CHANGED 0:3 TO 0:4
         'pseudo-diffusion                      ', &
         'ADI scheme                            ', &
         'iterated diffusion                    ', &
         'remap thickness                       ', &  
         '1st order upwind                      ' /) 			! ADDED THIS LINE

Time to type make again and check for a successful build. If so, proceed to Step 3.

Step 3

Now we will add use statements, if constructs, and dummy calls to the advection subroutines from the appropriate places in the code. Hence, we are setting up all the necessary structure to call the subroutines but are not passing any arguments to them yet (nor are they actually doing anything yet).

In 'glide.F90, add the following use statement to subroutine glide_initialise ...

    use glam_strs2, only : glam_velo_fordsiapstr_init
    use remap_glamutils, only : horizontal_remap_init
    use fo_upwind_advect_mod, only : fo_upwind_advect_init         ! ADDED

Now add if construct and call to the initialization stub in fo_upwind_advect_mod.F90, around line 190 of glide.F90, just after the if construct for EVOL_INC_REMAP ...

    if (model%options%whichevol== EVOL_FO_UPWIND ) then
        call fo_upwind_advect_init( )
    end if

In glide_stop.F90, add the following to the use statements ...

module glide_stop
 
  use glide_types
  use glimmer_log
  use remap_glamutils
  use fo_upwind_advect_mod, only : fo_upwind_advect_final       ! ADDED

Add the necessary if construct to glide_stop.F90 around line 150, as we did with the initialization routine ...

    if (model%options%whichevol== EVOL_FO_UPWIND ) then
        call fo_upwind_advectfinal( )
    endif

Finally, update the use statements in glide.F90 around line 340, and the case construct for ice sheet evolution, around line 380, so that the 1st order upwinding subroutines can be called ...

    use glide_thck
    use glide_velo
    use glide_ground
    use glide_setup
    use glide_temp
    use glide_mask
    use isostasy
    use glam, only: inc_remap_driver
    use fo_upwind_advect, only: fo_upwind_advect_driver      ! ADDED

... and add a call to the driver routine to the case construct ...

    case(EVOL_FO_UPWIND) ! Use first order upwind scheme for mass transport
 
       call fo_upwind_advect_driver( model )
 
    end select           ! MAKE SURE TO PLACE IT BEFORE THE 'end select' STATEMENT