Consortium for Small-Scale Modelling

download Consortium for Small-Scale Modelling

of 45

  • date post

    12-Feb-2017
  • Category

    Documents

  • view

    221
  • download

    1

Embed Size (px)

Transcript of Consortium for Small-Scale Modelling

  • Consortium

    for

    Small-Scale Modelling

    COSMO Standards

    for

    Source Code Development

    Version 1.3

    Ulrich Schttler

    August 2015

    DeutscherWetterdienst

    MeteoSwiss

    Ufficio Generale SpazioAereo e Meteorologia

    ENIKHMETEPOOIKH

    HPEIA

    Instytut Meteorologii iGospodarki Wodnej

    Administratia Nationala deMeteorologie

    Rosgidromet

    Agenzia Regionale per laProtezione Ambientale del

    Piemonte

    Agenzia Regionale per la ProtezioneAmbientale dell Emilia-Romagna:

    Servizio Idro Meteo Clima

    Centro Italiano RicercheAerospaziali

    Amt fr GeoInformationswesender Bundeswehr

    www.cosmo-model.org

    Editor: Ulrich Schttler

  • Rev. Modifications Date Author

    1.0 Revisions of the original draft by the SPMMarco Arpagaus

    08.2011 U. SchttlerDWD

    1.1 Clarified Chapter 2 and made it compatiblewith rest of documentAdded another rule for MODULEs in the Styleand Typing Rules

    Enhanced Section 6.4: Release PlanningUpdated Section 6.5 and 6.6 with work actu-ally ongoing.

    08.2012 M. ZiemianskiIMGWU. SchttlerDWD

    1.2 Chapter 6.1: Included definition of Recom-mended CLM-Community Version

    Added Appendix D: Steps of Code Develop-ment for CLM-Community Model VersionsChapter 6.6: Description for meteorologicaltest suites for NWP applicationsChapter 5.3: Documentation of scientificallyoriented code

    08.2014 B. Frh(for CLM)B. Frh(for CLM)F. GofaHNMSU. SchttlerDWD

    1.3 Editorial changes in Chap. 1, 2, 4 and 6Chap. 4: Included link to C++ Style GuideChap. 6: Added COSMO-ICON coordinationChap. 2: Changes for CLM in Chap. 2, Ap-pendix D

    08.2015 U. SchttlerDWD

    B. Frh(for CLM)

    Some Abbreviations and Explanations

    STC Steering CommitteeThe STC is the main governing and steering body of COSMO. It is responsiblefor and approves the changes to the official versions of the COSMO Software.

    SMC Scientific Management CommitteeThe SMC defines the changes to the COSMO Software and is responsible fortheir implementation.

    TAG Technical Advisory GroupThe TAG defines the technical rules for implementing COSMO Software.

    SCA Source Code AdministratorEvery COSMO Software has a main SCA, who is responsible for the mainte-nance.

    VCS Version Control SystemA system to manage changes to source code and documentation which allowsto track modifications and retains the history of all previous versions of asoftware.

  • Contents

    1 Introduction 1

    2 The Development Process - Some Mandatory Aspects 3

    3 Software Design 6

    4 Coding Rules 8

    4.1 Style and Typing Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

    4.2 Mandatory Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

    4.3 Banned Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

    5 Documentation 13

    5.1 Process Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

    5.2 Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

    5.3 Delivering New or Modified Code . . . . . . . . . . . . . . . . . . . . . . . . . 15

    6 Software Maintenance and Quality Control 16

    6.1 Version and Release Management . . . . . . . . . . . . . . . . . . . . . . . . . 16

    6.2 Rules for Implementation of Changes . . . . . . . . . . . . . . . . . . . . . . . 18

    6.3 Rationale for Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

    6.4 Release Planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

    6.5 Standard Test Suite for the COSMO-Model . . . . . . . . . . . . . . . . . . . 24

    6.6 Meteorological Test Suite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

    6.7 Testing the official versions in the VCS . . . . . . . . . . . . . . . . . . . . . . 26

    6.8 Coordination between COSMO and ICON . . . . . . . . . . . . . . . . . . . . 26

    7 Implementation Issues 28

    7.1 Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

    7.2 Working Precision . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

    7.3 Parallelization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

    7.4 Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

  • COSMO Standards for Source Code Development ii

    7.5 Vectorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

    7.6 I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

    7.7 Error Handling / Debug Messages . . . . . . . . . . . . . . . . . . . . . . . . 29

    A Standard Headers for the COSMO-Model and INT2LM 32

    B Amendments for fieldextra 36

    C Amendments for VERSUS 38

    D Steps of Code Development for CLM-Community Model Versions 40

  • COSMO Standards for Source Code Development 1

    1 Introduction

    This document specifies standards for source code development within the Consortium forSmall Scale Modeling, COSMO. The CLM Community, which uses the COSMO-Model, alsofollows these standards. They are valid for all versions of the COSMO Software and willalso be applied to software provided by other institutions or communities that is intendedto be incorporated into COSMO Software. At the date of writing the COSMO Software iscomposed of

    - the COSMO-Model,

    - the interpolation program INT2LM,

    - the postprocessing tool fieldextra,

    - the verification package VERSUS.

    The COSMO Standards for Source Code Development are based on the European Standardsfor Writing and Documenting Exchangeable Fortran 90 Code [1] and should complement andadapt these for the needs of COSMO where necessary. The European Standards have beendefined in the 90ies to facilitate the exchange of code between meteorological centres. Theyprovide a framework for the use of Fortran 90, in which some details have to be elaborated.

    The exchange of code surely has not become common practice up to now, but following theEuropean Standards facilitated the development and documentation of the COSMO-Model.This, in turn, lead to the dissemination of the model system to a wide community. Thefurther development of the COSMO-Model within this bigger community now requires aneven stronger emphasis on a clear and structured development and a detailed documentation.This also holds for the other components of the COSMO Software.

    The aim of this document is to provide some guidelines for several aspects of the developmentand programming process and should serve the following goals:

    encourage well structured programming

    increase readability and useability of source code

    standardize the look and usage of source code units

    create machine independent portable source code

    simplify maintenance tasks

    facilitate quality management and control

    The main chapters of the COSMO Standards are:

    Mandatory AspectsThroughout all sections of this paper, some mandatory aspects of source code develop-ment are specified. This section just summarizes the most important ones at a glanceand can be used as a step-by-step instruction.

  • COSMO Standards for Source Code Development 2

    Software DesignSoftware design is the process of problem solving and planning a software solution. Itthus includes the construction of the underlying physical model as well as the defini-tion of the major components of the software needed to provide a robust and efficientsolution.

    Coding RulesThe coding rules specify a common programming style that has to be adhered to by allCOSMO Software. This enhances the readability and exchangeability of source code.

    DocumentationThe term Documentation refers to both kinds of documentation, i.e. the process doc-umentation, which can be defined separately for every project, and the product docu-mentation. The product documentation is split into the internal code documentationand the external documentation outside of the code.

    Software Maintenance and Quality ControlAn essential part of the software development process is the maintenance of the softwareand the quality control of each version. Also, clear rules have to be defined how to gofrom one version to another in operational production.

    Implementation IssuesIn addition to the Coding Rules, we will give some recommendations for the practicalimplementations. Issues like memory management, parallelization, optimization andvectorization will be discussed briefly.

    The preferred language for model development still is Standard Fortran. But as new computerarchitectures evolve, it might be necessary to use other languages or language extensions.Especially for non-numeric applications (like VERSUS) Fortran surely is not the first choicefor the computer language to use. But no matter which language is used, a portable, i.e. astandard source code is absolutely necessary. Therefore we intend to transfer these standardslogically also to non-Fortran applications.

    We are aware of the fact that the existing COSMO Software does not fulfill all of thesestandards, and sometimes not even the most necessary ones. But the development team isworking on that and tries to make the COSMO-Model better with every new version. Notonly regarding the meteorology, but also regarding the software engineering aspects.

    Some rules stated in this document do not apply to all of the COSMO Software. This will beexplicitly stated when this is the case. If additional rules or clarifications are necessary, theyare stated in appendices to that document or a link is given to accompanying documentation.

    Note that additional and / or slightly different