ESM

UCLA ESM/ESMF Software Test Plan

1. Scope
The scope of this project is restricted to the coupling of existing gridded components that form the UCLA Earth System Model (ESM) using the Earth System Modeling Framework (ESMF) software by means of the ESMF-compliant CCSM coupler via ESMF software.

1.1 System Overview
The software system to be tested includes three gridded components: the UCLA AGCM 7.2, the HYPOP 1.0 global ocean component, and the CICE 3.1 sea ice component; the ESMF-compliant version of the Community Climate System Model (CCSM) coupler; and the ESMF libraries.

2. Referenced Documents
UCLA AGCM Users Guide
http://www.atmos.ucla.edu/~mechoso/esm
POP 2.0 Requirements Document
CICE 3.0.1 Documentation http://www.acl.lanl.gov/climate/eclare/cicecode/cice.html
Community Sea Ice Model v4.0.1 Users Guide http://www.ccsm.ucar.edu/models/ccsm2.0.1/csim/
Community Sea Ice Model v4.0.1 Code Reference Guide
http://www.ccsm.ucar.edu/models/ccsm2.0.1/csim/
Community Sea Ice Model v4.0.1 Scientific Description
http://www.ccsm.ucar.edu/models/ccsm2.0.1/csim/

3. Software Test Environment
Our test hardware environment will be restricted to SGI Origin 3000 hardware at NASA Ames and LANL. We will utilize the current SGI compilers and system libraries provided in this hardware environment. Personnel conducting the tests will be John Baumgardner and Phil Jones from LANL and Joe Spahr from UCLA. We intend to focus on a single grid resolution. The atmosphere model will have a 5 degree longitude by 4 degree latitude resolution and 15 levels. The ocean model will be the so-called ëx3í displaced pole grid with approximately 3 degree resolution. The sea ice model will also have a resolution of approximately 3 degrees. We will write drivers and diagnostic routines primarily to test the correctness of the integration of the component models (verification).

4. Test Identification
This section describes the tests to be performed under this plan.

4.1 General Information
Tests will be performed to assess the reliability and performance of the UCLA ESM integrated with the ESMF.

4.1.1 Test Level
Tests 1, 2, and 3 are at the component/integration level, Test 4 at the integration level, and Test 5 at the system level.

4.1.2 Test Classes
Specify the type of tests that will be performed (performance, invalid input, capacity tests, operational tests)

4.2 Planned Tests
This section describes the specific tests to be performed under this plan.

4.2.1 Stand-Alone AGCM

Test purpose: Verify the implementation of ESMF-compliant control structures for the AGCM. These structures control initialization, sequencing of tasks during the time integration part of the execution, and the finalize.
Test type: Functional
Test inputs: Boundary conditions, restart history, run namelist.
Verification method: Compare output with a control AGCM integration without ESMF.
Special Requirements: Availability of a working, stable version of the ESMF.
Assumptions/Constraints: Codes available in versions appropriate for the available test-hardware environment.
Expected results: AGCM will start, run, and terminate successfully producing correct results.
Actual results: Seasonal simulation of the atmospheric circulation.

4.2.2 Stand-Alone HYPOP

Test purpose: Verify the implementation of ESMF-compliant control structures for the HYPOP. These structures control initialization, sequencing of tasks during the time integration part of the execution, and the finalize.
Test type: Functional
Test inputs: Boundary conditions, restart history, run namelist.
Verification method: Compare output with a control HYPOP integration without ESMF.
Special Requirements: Availability of a working, stable version of the ESMF.
Assumptions/Constraints: Codes available in versions appropriate for our test-hardware environment.
Expected results: HYPOP will start, run, and terminate successfully.
Actual results: Seasonal simulation of the oceanic circulation.

4.2.3 Side-by-side AGCM/HYPOP

Test purpose: Verify the implementation of the ESMF-compliant control structures when the application is configured with two components, but without data exchanges (coupling) between components.
Test type: Functional
Test inputs: Boundary conditions, restart history, run namelist.
Verification method: Compare output with a control AGCM/HYPOP integration without ESMF.
Special Requirements: Availability of a working, stable version of the ESMF.
Assumptions/Constraints: Codes available in versions appropriate for the available test-hardware environment.
Expected results: AGCM/HYPOP will start, run, and terminate successfully.
Actual results: Seasonal climate simulation

4.2.4 Coupled AGCM/HYPOP/CICE (Functional)

Test purpose: Verify the implementation of the ESM-compliant structures for data exchanges (coupling).
Test type: Functional
Test inputs: Boundary conditions, restart history, run namelist.
Verification method: Compare output with a control AGCM/HYPOP/CICE integration without ESMF.
Special Requirements: Availability of a working, stable version of the ESMF.
Assumptions/Constraints: Codes available in versions appropriate for the available test-hardware environment.
Expected results: AGCM/HYPOP/CICE will start, run, and terminate successfully producing correct results.
Actual results: Seasonal climate simulation

4.2.5 Coupled AGCM/HYPOP/CICE (Performance)

Test purpose: Verify that integration to the ESMF does not impose more than 10% overhead to the AGCM/HYPOP/CICE.
Test type: Performance
Test inputs: Boundary conditions, restart history, run namelist.
Verification method: Comparison of timings
Special Requirements: Several sessions of dedicated machine time, one-hour long each. Availability of a working, stable version of the ESMF.
Assumptions/Constraints: Codes available in versions appropriate for the available test-hardware environment.
Expected results: Overhead to the AGCM/HYPOP/CICE by ESMF will be lower than 10%.
Actual results: Seasonal climate simulation.

5. Test Schedules
The tests will be performed sequentially

6. Requirements Traceability

Requirement	TEST
	Stand-alone AGCM	Stand-alone HYPOP & CICE	Side-by-side AGCM/HYPOP	Coupled AGCM/HYPOP/CICE (Functional)	Coupled AGCM/HYPOP/CICE (Performance)
Organization using the ESMF component design model	1.1-1.5 1.7-1.11	1.1-1.5 1.7-1.11	1.6
Inclusion of an ESMF compliant application component				2.1-2.4.1
Inclusion of an ESMF compliant coupler				3.1-3.1.1
System contains atmosphere, ocean and sea-ice components				4.1-4.2.4
Verification of ESMF timing overhead					5.1

Interface Control Document

1.1 Specification of Gridded Components

Our application includes three gridded components: an atmosphere component, UCLA AGCM 7.2; an ocean component, HYPOP 1.0; and a sea ice component, CICE 3.1.

For ESMF compatibility, each of the gridded components will have a single externally visible entry point that corresponds to an ESMF ëset servicesí subroutine. This subroutine will be called at start time to register with the framework the names of driver subroutines that manage the component initialization, run, and finalize tasks.

At the top level each gridded component will be organized in terms of three subroutines that separately direct initialization, run, and finalization functions. The initialization subroutine, called once, will read in required input parameters, allocate the required memory, read in or generate the grid, initialize the required fields and boundary conditions, and read in or generate everything else the model needs in order to run. The run subroutine will be called multiple times. On each call it will accept any required new state data from other components, do its computation, perform any required external I/O, and produce output state data needed by other components. The finalization subroutine, called once, will write out required final results, release allocated memory, close opened files, and otherwise provide a graceful shutdown of the computation. Each component will communicate to other components only through the framework. All non-framework data items will be private to each component. UCLA AGCM, HYPOP and CICE already have initialize and finalize routines, but their interfaces still require some work to be ESMF compliant. For example, all gridded components have to be prepared to receive timing and control variables from the ESMF.

Each gridded component will use at least portions of the ESMF lower level infrastructure. In particular, all components will adopt the ESMF clock/calendar subroutines for their time management requirements. The UCLA AGCM does not yet have an interface to the ESMF time management routines while HYPOP and CICE already do. Components will also use ESMF error logging and I/O utilities.

The AGCM uses a "C" grid (Mesinger and Arakawa, 1976). The resolution we intend to use for the atmosphere is 5o longitude and 4o latitude, which is 72 cells in the longitude direction and 44 cells in latitude with 15 levels in the vertical from the Earthís surface to 1 hPa. The layout we will typically use consists of 16 blocks (of approximately 16x12 cells each). POP uses a "B" grid (Mesinger and Arakawa, 1976). The resolution we plan to use for the ocean and sea ice models will be one known as the 'x3' grid, which has its north pole displaced into Greenland. This grid has 100 cells in the longitude direction and 116 cells in the longitude direction with 25 vertical levels for the ocean. The layout we intend to use is 16 25x29-cell blocks for the ocean and 4 25x116-cell blocks for sea-ice. The running sequence is atmosphere-sea ice-ocean. We anticipate coupling to occur once per hour between the atmosphere and sea-ice components and once per day between the ocean and both the atmosphere and sea-ice components.

1.2 Gridded Component Export Fields

Atmosphere Component (UCLA AGCM 7.2)

field	description	units
PREC	total precipitation	mm/s
RAIN	water flux due to rain	g/cm2/s
SNOW	water flux due to snow	g/cm2/s
FSS	sensible heat flux at the surface	W/m2
FWS	water flux at the surface from evaporation	g/cm2/s
DRAGU	"U" surface drag	dynes/cm2
DRAGV	"V" surface drag	dynes/cm2
SS	net short wave flux at the surface	W/m2
DSWBOT	downward short wave flux at the sfc	W/m2
ULWBOT	upward long wave flux at the sfc	W/m2
DLWBOT	downward long wave flux at the sfc	W/m2
GC	surface condition
T	potential temperature of the PBL	K
SH	specific humidity of the PBL	kg/kg
SLP	sea level pressure	mb
RAOA	atmospheric air density	kg/m3
SWDIDF	downward shortwave near IR diffuse heat flux	W/m2
SWDIDR	downward shortwave near IR direct heat flux	W/m2
SWDVDF	downward shortwave visible diffuse heat flux	W/m2
SWDVDR	downward shortwave visible direct heat flux	W/m2

Ocean Component (HYPOP 1.0)

field	description	units
DHDY	north-south surface slope	m/m
DHDX	east-west surface slope	m/m
QICE	heat flux due to freezing or melting potential (heat flux correction)	W/m2
SSS	sea surface salinity	ppt
SST	sea surface temperature	K
VVEL	north-south surface velocity	m/s
UVEL	east-west surface velocity	m/s

Sea Ice Component (CICE 3.1)

field	description	units
ALBIDF	near IR diffuse albedo	none
ALBIDR	near IR direct albedo	none
ALBVDF	visible diffuse albedo	none
ALBVDR	visible direct albedo	none
EVAP	evaporated water flux	kg/m2/s
IFRC	ice fraction	none
LAT	latent heat flux	W/m2
LWUP	outgoing longwave radiation	W/m2
MELTH	heat used to melt ice	W/m2
MELTW	water flux from ice melt	kg/m2/s
NETSW	shortwave penetrating to bottom of ice	W/m2
SALT	salt flux from ice melt	kg/m2/s
SENS	sensible heat flux	W/m2
TAUXA	east-west wind stress	N/m2
TAUYA	north-south wind stress	N/m2
TREF	2m atm reference temperature	K
TSFC	surface temperature of sea ice	K

1.3 Gridded Component Import Fields

Atmosphere Component (UCLA AGCM 7.2)

field	description	units
SST	sea surface temperature	K
TSFC	surface temperature of sea ice	K
IFRAC	ice fraction	%

Ocean Component (HYPOP 1.0)

field	description	units
EVAP	water flux from evaporation	kg/s/m2
IFRAC	ice fraction	none
LWDWN	downward longwave heat flux	W/m2
LWUP	upward longwave heat flux	W/m2
MELT	water flux from ice melt	kg/s/m2
MELTHF	heat flux from ice melt	W/m2
MSLP	mean sea level pressure	Pa
NETSW	shortwave heat flux	W/m2
PREC	water flux from precipitation	kg/s/m2
ROFF	water flux due to runoff	kg/s/m2
SALT	salt flux	kg/s/m2
SENHF	sensible heat flux	W/m2
TAUX	east-west wind stress	N/m2
TAUY	north-south wind stress	N/m2

Sea Ice Component (CICE 3.1)

field	description	units
FLW	downward longwave heat flux	W/m2
FW	heat flux from freezing or melt potential	W/m2
POTT	atmospheric potential temperature	K
QA	atmospheric specific humidity	kg/kg
RAIN	water flux due to rain	kg/m2/s
RHOA	atmospheric air density	kg/m3
SNOW	water flux due to snow	kg/m2/s
SSS	sea surface salinity	ppt
SST	sea surface temperature	K
SWDIDF	downward shortwave near IR diffuse heat flux	W/m2
SWDIDR	downward shortwave near IR direct heat flux	W/m2
SWDVDF	downward shortwave visible diffuse heat flux	W/m2
SWDVDR	downward shortwave visible direct heat flux	W/m2
TAIR	atmospheric air temperature	K
TILTX	east-west sea surface slope	m/m
TILTY	north-south sea surface slope	m/m
UATM	east-west atmospheric wind	m/s
UOCN	east-west ocean current	m/s
VATM	north-south atmospheric wind	m/s
VOCN	north-south ocean current	m/s
ZLVL	atmospheric level height	m

1.4 ESMF State Objects

The import and export fields enumerated in items 1.2 and 1.3 above will include, in addition to the data arrays, the metadata required for ESMF compatibility such as gridding, layout, coordinate, and units information. In most cases fields will be bundled. Fluxes, which require conservative remapping between components, will be bundled separately from fields that do not require conservative remapping. Metadata providing the remapping specifications required by the coupler component will be included with the bundling description. The import state object and export state object for each component will consist of the fields listed in items 1.2 and 1.3 with the requite bundling and coupler specifications.

2.1 Full Application

Our full UCLA ESMF coupled global climate application will be built from the three gridded components described in section 1.1 and shown in Figure 1, an atmosphere component, UCLA AGCM 7.2, an ocean component, HYPOP 1.0, and a sea ice component, CICE 3.1, all coupled through a single coupler component, the ESMF-compliant NCAR Community Climate System Model (CCSM) coupler (see Figure 2). This coupler will use the ëhub and spokeí strategy to handle all data conversion/transfer among gridded components. The CCSM coupler will understand ESMF objects including the ESMF data objects of states, fields, bundles, grids, and arrays; ESMF services such as regrid and route; and ESMF execution/environment objects such as layouts. We have chosen to use the CCSM coupler because it will have the all the functionality required for our application. The CCSM coupler will be required to accommodate the grid and all the fields of our ocean and sea-ice components and will be able to handle the grid and all the fields associated with the UCLA atmospheric model. In addition the CCSM coupler will likely be available for use several months before the essential routines required to build such a coupler will be available from the ESMF library.

The main program for our climate application will call the ESMF initialization code and provide the environment for components to be created and run. It will first create and then call an application component. This application component in turn will create each of the gridded and coupler components. It will also call the ESMF set services entry point for each component it creates. In addition the application component will manage the main time stepping loop for the application. When computations are complete, the main program will destroy the application component and thereby close down the framework and release all its associated resources.

References

Mesinger, F., and A. Arakawa, 1976: Numerical methods used in atmospheric models. GARP Publication Series 17, 1, WMO.

Figure 1. UCLA ESM Component Structure

Figure 2. UCLA ESM Data Flow Diagram in one coupling cycle.
Data Field boxes indicate local variable storage for the particular model.