Extended submodel interface of echam6 S. Rast HAMMOZ meeting, Zurich, 2010-3-24/25

Radiation, convection, diffusion, clouds Introduction ECHAM6 General circulation Physics of atmosphere Radiation, convection, diffusion, clouds I n t e r f a c e Two way communication Submodel 1 Submodel 2 ... Submodel n

General interface properties Dummy subroutines: Collection of subroutines providing hooks to echam6 Data structures: Collect local echam6 variables in a data structure to pass to submodels Data structure for transported quantities (tracers) includes transport properties (flags) Chemical species and their physical properties are stored in separate data structure. The tracer and species concept supports families of species Boundary conditions (emissions, climatologies) are collected in one data structure Flexible diagnostics per species/tracer/mode

Differences with respect to echam5 submodel interface Distinction between tracers and species allows for the introduction of families of species in one (transported) tracer Boundary condition data structure allows for consistent and namelist controlled treatment of emissions and climatological boundary conditions Diagnostic stream helps to control the quantity of output by namelist

Coupling submodels with help of this interface I For introduction of submodels, one must change mo_submodel_interface only Dummy subroutines for calls of specific submodel routines are provided Interface based on data structures (streams) originally introduced by A. Rhodin, L. Kornblüh et. al. extended on demand

Coupling submodels with help of this interface II Register submodel Read submodel specific namelist Setup tracer/species structure and memory for submodel Read boundary conditions several hooks to interact with echam6 physics diagnostics

Coupling among submodels Coupling among submodels: Each submodel has to provide its own special interface BUT Data structures of echam6 can help: Data structure for species, diagnostic, boundary conditions

Style guide - Icon style guide The relevant style guide is the style guide for ICON: „Programming Guide for ICON“ (ask S. Rast) Example for header of Modules: !> !! <Short description of module for listings and indices> !! !! <Describe the concepts of the routines and algorithms used in the module.> !! <Details of procedures are documented below with their definitions.> !! <Include any applicable external references inline as module::procedure,> !! <external_procedure(), or by using @see.> !! <Donât forget references to literature.> !! @author <Name, affiliation of author> !! $Id: n/a$ !! @par Revision History !! <Description of activity> by <Name> (<YYYY-MM-DD>)

Style guide - Icon style guide !! @par Copyright !! 2002-2009 by DWD and MPI-M !! This software is provided for non-commercial use only. !! See the LICENSE and the WARRANTY conditions. !! !! @par License !! The use of ICON is hereby granted free of charge for an unlimited time, !! provided the following rules are accepted and applied: !! <ol> !! <li> You may use or modify this code for your own non commercial and non !! violent purposes. !! <li> The code may not be re-distributed without the consent of the authors. !! <li> The copyright notice and statement of authorship must appear in all !! copies. !! <li> You accept the warranty conditions (see WARRANTY). !! <li> In case you intend to use the code commercially, we oblige you to sign !! an according license agreement with DWD and MPI-M. !! </ol> !! @par Warranty !! This code has been tested up to a certain level. Defects and weaknesses, !! which may be included in the code, do not establish any warranties by the !! authors. !! The authors do not make any warranty, express or implied, or assume any !! liability or responsibility for the use, acquisition or application of this !! software. MODULE mo_xyz

Test of your submodel - part I Test your module on a PC (or small computer) with tests for arithmetic exceptions uninitialized variables incompatible parameter lists of subroutines/functions e.g. with the NAG compiler (-C=all -nan -gline) Keep in mind: Any supercomputer is not a toy and testing on those machines is normally difficult. If you like to send a rover to Mars, you will test it first on Earth before you realize that your solar module does not unfold because of programming errors!

Test of your submodel - part II Pitfalls: Even if your parameter lists are checked, the exact shape of your arrays is not checked. There will be a check of the number of dimensions and the total number of elements only! E.g.: REAL(dp) :: u(nlon,nlat) call winds(u,nlon,nlat) subroutine winds(u,nlat,nlon) REAL(dp) :: u(nlat,nlon)

Test of your submodel Before you can run your model on any supercomputer, it must pass the following tests on a PC/small system Nproma test: Bit identical results for two different values of nproma which are not a divisor of nlon (e.g. 17 and 23) Parallel test: Bit identical results on 1 and 2 processors Rerun test: Bit identical results after a rerun as compared to an uninterrupted run Submodel switch off test: Bit identical results for echam from main branch and your version but submodel switched off

Conclusion Interface allows coupling of submodels to echam6 with changes of only one module Code of submodels can be maintained somewhere else than at MPI Hamburg Interface is flexible and can be extended easily Data structures of interface are particularly suited for aerosol/chemistry submodels (tracers, species) Easy handling of boundary conditions Tests are extremely important