Contact:   Bruce Wyman, V. Balaji
Reviewers: 
Change History:  WebCVS Log
Last Modified:  $Date: 2003/10/24 22:01:05 $

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

  atmos_model_mod
    ice_model_mod
   land_model_mod
  ocean_model_mod
flux_exchange_mod
 diag_manager_mod
 time_manager_mod
    utilities_mod
          mpp_mod (only for timing calls: may be eliminated)

This is a main program. There are no callable interfaces.

A namelist interface called &coupler_nml should reside in file input.nml. See the details below.

For compatibility with previous versions the namelist input &coupler_nml may also reside in file coupler.res.

None.

None.

&coupler_nml

current_date

The date that the current integration starts with.
[integer, dimension(6), default: current_date=0]

override

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 override has not effect, the value of current_date will be used.
[logical, default: override=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: calendar=' ' ]

months

The number of months that the current integration will be run for.
[integer, default: months=0]

days

The number of days that the current integration will be run for.
[integer, default: days=0]

hours

The number of hours that the current integration will be run for.
[integer, default: hours=0]

minutes

The number of minutes that the current integration will be run for.
[integer, default: minutes=0]

seconds

The number of seconds that the current integration will be run for.
[integer, default: seconds=0]

dt_atmos

Atmospheric model time step in seconds, including the fast coupling with land and sea ice.
[integer, default: dt_atmos=0]

dt_ocean

Ocean model time step in seconds.
[integer, default: dt_ocean=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: dt_cpld=0]

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.

None.

None.

FATAL ERRORS in program coupler_main

namelist file input.nml does not exist

The file input.nml contains namelist input records and must reside in the directory where the executable is run. For compatibility with previous versions of program coupler_main the namelist input &coupler_nml may also reside in file coupler.res.

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.

invalid namelist value for calendar

The value of calendar must be 'julian', 'noleap', or 'thirty_day'. See the namelist documentation.

no namelist value for calendar

If no restart file is present, then a namelist value for calendar must be specified.

if run length in months then starting day must be <= 28

If the namelist variable months > 0, then the current (starting) date cannot bw greater than 28. This is because incrementing to the next month may be a problem for February.

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.

run length must be multiple of ocean time step

There must be an even number of ocean time steps for the requested run length.

ocean time step is not a multiple of the atmosphere time step

There must be an even number of fast atmospheric time steps for the length of one slow ocean time step.

WARNINGS in program coupler_main

final time does not match expected ending time

This error should probably not occur because of checks done at initialization time.

None.

None.

None.

None.

None.

None.

1. Parallel scheduling of atmosphere and ocean models to support sequential and concurrent coupling on parallel systems.
2. Multiple instances of any component to support ensemble studies.