PUBLIC INTERFACE ~ PUBLIC DATA ~ PUBLIC ROUTINES ~ NAMELIST ~ DIAGNOSTIC FIELDS ~ ERROR MESSAGES ~ REFERENCES ~ NOTES

Program coupler_main

Contact:  Bruce Wyman ,  V. Balaji
Reviewers: 
Change History: WebCVS Log

OVERVIEW

A main program that couples component models for atmosphere, ocean, land, and sea ice on independent grids.

This version couples model components representing atmosphere, ocean, land and sea ice on independent grids. Each model component is represented by a data type giving the instantaneous model state.

The component models are coupled to allow implicit vertical diffusion of heat and moisture at the interfaces of the atmosphere, land, and ice models. As a result, the atmosphere, land, and ice models all use the same time step. The atmospheric model has been separated into down and up calls that correspond to the down and up sweeps of the standard tridiagonal elimination.

The ocean interface uses explicit mixing. Fluxes to and from the ocean must be passed through the ice model. This includes atmospheric fluxes as well as fluxes from the land to the ocean (runoff).

This program contains the model's main time loop. Each iteration of the main time loop is one coupled (slow) time step. Within this slow time step loop is a fast time step loop, using the atmospheric time step, where the tridiagonal vertical diffusion equations are solved. Exchange between sea ice and ocean occurs once every slow timestep. 

      MAIN PROGRAM EXAMPLE
      --------------------

         DO slow time steps (ocean)

              call flux_ocean_to_ice

              call ICE_SLOW_UP

              DO fast time steps (atmos)

                   call flux_calculation

                   call ATMOS_DOWN

                   call flux_down_from_atmos

                   call LAND_FAST

                   call ICE_FAST

                   call flux_up_to_atmos

                   call ATMOS_UP

              END DO

              call ICE_SLOW_DN

              call flux_ice_to_ocean

              call OCEAN

         END DO

MODULES USED

          constants_mod
       time_manager_mod
                fms_mod
             fms_io_mod
       diag_manager_mod
      field_manager_mod
     tracer_manager_mod
      coupler_types_mod
      data_override_mod
        atmos_model_mod
         land_model_mod
          ice_model_mod
        ocean_model_mod
      flux_exchange_mod
atmos_tracer_driver_mod
                mpp_mod
             mpp_io_mod
        mpp_domains_mod
           memutils_mod

PUBLIC INTERFACE


PUBLIC DATA

None.

PUBLIC ROUTINES

    NAMELIST

    &coupler_nml

    current_date
    The date that the current integration starts with.
    [integer, dimension(6), default: 0]
    force_date_from_namelist
    Flag that determines whether the namelist variable current_date should override the date in the restart file INPUT/coupler.res. If the restart file does not exist then force_date_from_namelist has not effect, the value of current_date will be used.
    [logical, default: .false.]
    calendar
    The calendar type used by the current integration. Valid values are consistent with the time_manager module: 'julian', 'noleap', or 'thirty_day'. The value 'no_calendar' can not be used because the time_manager's date function are used. All values must be lowercase.
    [character(maxlen=17), default: '']
    months
    The number of months that the current integration will be run for.
    [integer, default: 0]
    days
    The number of days that the current integration will be run for.
    [integer, default: 0]
    hours
    The number of hours that the current integration will be run for.
    [integer, default: 0]
    minutes
    The number of minutes that the current integration will be run for.
    [integer, default: 0]
    seconds
    The number of seconds that the current integration will be run for.
    [integer, default: 0]
    dt_atmos
    Atmospheric model time step in seconds, including the fast coupling with land and sea ice.
    [integer, default: 0]
    dt_ocean
    Ocean model time step in seconds.
    [integer, default: 0]
    dt_cpld
    Time step in seconds for coupling between ocean and atmospheric models: must be an integral multiple of dt_atmos and dt_ocean. This is the "slow" timestep.
    [integer, default: 0]
    do_atmos, do_ocean, do_ice, do_land, do_flux
    If true (default), that particular model component (atmos, etc.) is run. If false, the execution of that component is skipped. This is used when ALL the output fields sent by that component to the coupler have been overridden using the data_override feature. For advanced users only: if you're not sure, you should leave these values at TRUE.
    [logical]
    concurrent
    If true, the ocean executes concurrently with the atmosphere-land-ocean on a separate set of PEs. If false (default), the execution is serial: call atmos... followed by call ocean... If using concurrent execution, you must set one of atmos_npes and ocean_npes, see below.
    [logical]
    atmos_npes, ocean_npes
    If concurrent is set to true, we use these to set the list of PEs on which each component runs. At least one of them must be set to a number between 0 and NPES. If exactly one of these two is set non-zero, the other is set to the remainder from NPES. If both are set non-zero they must add up to NPES.
    [integer]
    use_lag_fluxes
    If true, then mom4 is forced with SBCs from one coupling timestep ago If false, then mom4 is forced with most recent SBCs. For a leapfrog MOM coupling with dt_cpld=dt_ocean, lag fluxes can be shown to be stable and current fluxes to be unconditionally unstable. For dt_cpld>dt_ocean there is probably sufficient damping. use_lag_fluxes is set to TRUE by default.
    [logical]
    n_mask
    number of region to be masked out. Its value should be less than MAX_PES.
    [integer]
    mask_list(2,MAXPES)
    The position of the region to be masked out. mask_list(1,:) is the x-layout position and mask_list(2,:) is y-layout position.
    [integer, dimension(2,MAX_MASK_REGION)]
    layout_mask
    Processor domain layout for all the component model. layout_mask need to be set when and only when n_mask is greater than 0 ( some domain region is masked out ). When this namelist is set, it will overload the layout in each component model. The default value is (0,0). Currently we require all the component model has the same layout and same grid size.
    [integer, dimension(2)]

    DATA SETS

    None.

    ERROR MESSAGES

    FATAL error during execution of program coupler_main
    no namelist value for current_date
    A namelist value for current_date must be given if no restart file for coupler_main (INPUT/coupler.res) is found.
    FATAL error during execution of program coupler_main
    invalid namelist value for calendar
    The value of calendar must be 'julian', 'noleap', or 'thirty_day'. See the namelist documentation.
    FATAL error during execution of program coupler_main
    no namelist value for calendar
    If no restart file is present, then a namelist value for calendar must be specified.
    FATAL error during execution of program coupler_main
    initial time is greater than current time
    If a restart file is present, then the namelist value for either current_date or start_date was incorrectly set.
    FATAL error during execution of program coupler_main
    run length must be multiple of ocean time step
    There must be an even number of ocean time steps for the requested run length.
    WARNING error during execution of program coupler_main
    final time does not match expected ending time
    This error should probably not occur because of checks done at initialization time.

    REFERENCES

    None.

    COMPILER SPECIFICS

    None.

    PRECOMPILER OPTIONS

    None.

    LOADER OPTIONS

    None.

    TEST PROGRAM

    None.

    KNOWN BUGS

    None.

    NOTES

       1.If no value is set for current_date, start_date, or calendar (or default value 
     specified) then the value from restart file "INPUT/coupler.res" will be used. 
     If neither a namelist value or restart file value exist the program will fail. 
   2.The actual run length will be the sum of months, days, hours, minutes, and 
     seconds. A run length of zero is not a valid option. 
   3.The run length must be an intergal multiple of the coupling timestep dt_cpld.

    FUTURE PLANS

    None.

    top