Home

Consortium for Small-Scale Modelling - CLM

1. lt A one line description of this function gt lt Type gt FUNCTION lt FunctionName gt lt InputArguments gt Description lt Say what this function does gt Method lt Say how it does it include references to external documentation gt lt If this routine is divided into sections be brief here and put Method comments at the start of each section gt Current Code Owner lt Name of person responsible for this code gt History Version Date Comment succo sese ilo lt version gt lt date gt Original code lt Your name gt Code Description Language Fortran 90 Software Standards COSMO Standards for Source Code Development Declarations Modules used USE ONLY amp Imported Type Definitions Imported Parameters Imported Scalar Variables with intent in Imported Scalar Variables with intent out Imported Array Variables with intent in Imported Array Variables with intent out Imported Routines lt Repeat from USE for each module gt Declarations must be of the form lt type gt lt VariableName gt Description purpose of variable Function arguments Scalar arguments with intent in Array arguments with intent in Local parameters Local scalars Local arrays PSO sor Meader a a POS SO SS Function Body END FUNCTION lt FunctionName gt COSMO Standards for Source Code Development Module h
2. CONSORTIUM FOR SMALL SCALE MODELING Consortium co SMO for Small Scale Modelling COSMO Standards for Source Code Development Version 1 2 Ulrich Sch ttler August 2014 Deutscher MeteoSwiss Wetterdienst EONIKH Ufficio Generale Spazio METEQPOAOTIKH Aereo e Meteorologia YIHPEXIA Instytut Meteorologii i Administratia Nationala de Gospodarki Wodnej Meteorologie Pocruypomer Agenzia Regionale per la Agenzia Regionale per la Protezione Protezione Ambientale del Ambientale dell Emilia Romagna Piemonte Servizio Idro Meteo Clima Centro Italiano Ricerche Amt fiir GeoInformationswesen Aerospaziali der Bundeswehr www cosmo model org Editor Ulrich Schattler Revision Modifications Date Author 1 0 Revisions of the original draft by the SPM 08 2011 U Schattler Marco Arpagaus DWD 1 1 Clarified Chapter 2 and made it compatible 08 2012 M Ziemianski with rest of document IMGW Added another rule for MODULEs in the Style U Schattler and Typing Rules DWD Enhanced Section 6 4 Release Planning Updated Section 6 5 and 6 6 with work ac tually ongoing 1 2 Chapter 6 1 Included definition of Recom 08 2014 B Fr h mended CLM Community Version for CLM Added Appendix D Steps of Code Develop B Fr h ment for CLM Community Model Versions for CLM Chapter 6 6 Description for meteorological F Gofa test suites for NWP applications HNMS Chapter 5 3 Documentation of
3. Local CHARACTER variables start with the letter yz All other variables can start with any other letter except the above ones Local REAL variables start with the letter z e Do not put multiple statements on one line this will reduce code readability e If necessary introduce continuation lines by amp at the end of the line to be continued Do not use empty lines between continued lines because some compilers cannot handle them and will abort For viewing on terminals and for printers about 90 characters per line should not be exceeded e CPP the C Pre Processor keys are only used for Differentiating codes in relation to computer architecture and compiler properties Controlling the access to external libraries Controlling the access to non COSMO software packages as e g COSMO ART 4 2 Mandatory Features The newer Fortran Standards offer some means to write code faster and much more portable than e g Fortran 77 Among them are e Dynamic memory allocation e The KIND concept to specify the working precision The use of these features is mandatory For a more detailed explanation see Chapter 7 4 3 Banned Features Some of the following sections detail features deprecated in or made redundant from Fortran 90 onwards Others ban features whose use is deemed to be bad programming practice as they can degrade the maintainability of the code COMMON blocks use the declaration part of MODULEs instead
4. EQUIVALENCE use POINTERs or derived data types instead to form data structures e Assigned and computed GOTOs use the CASE construct instead e Arithmetic IF statements use the block IF ELSE ELSEIF ENDIF construct instead e Labels COSMO Standards for Source Code Development 12 Labelled DO constructs use named ENDDO instead I O routine s END and ERR use IOSTAT instead FORMAT statements use CHARACTER parameters or explicit format specifiers inside the READ or WRITE statement instead Avoid any unused statement like a labeled CONTINUE not being jumped to e GOTO Avoid GOTO by making use of IF CASE DO WHILE EXIT or CYCLE statements e PAUSE e ENTRY statements a subprogram may only have one entry point e Fixed source form e Avoid FUNCTIONs with side effects i e functions that alter variables in their argument list or in modules used or functions which perform I O operations Although this is common practice in C there are good reasons to avoid side effects First the code is easier to understand if you can rely on the rule that functions do not change their arguments second some compilers generate more efficient code for pure functions because they can store the arguments in different places from Fortran 95 on there are the attributes PURE and ELEMENTAL e Avoid changing the shape of an array implicitly when passing it into a subroutine Al though actually forbidden in the Fortran 77 s
5. Performance diagrams upper air verification T RH WindSp for selected pressure levels 250 500 700 850 925 1000 mb BIAS MAE RMSE After the completion of each meteorological test a report will have to be prepared by the responsible person for this task that will include the main comparisons graphs and will highlight the main findings extracted from the comparison of the two model versions test and last released performed using the NWP test suite This report will summarize the main verification results and will include the evaluation based on the statistical outcome of the test model version A new version of the model will in principle be validated if the set of verification results show a positive impact on the common domain or if the results are neutral but the scientific bases of the code are sounder COSMO CLM Test Suite to be added 6 7 Testing the official versions in the VCS If a contribution to the COSMO Software has fulfilled all steps specified above especially all the prescribed tests and is accepted by the Management for a future official version the code is given together with all documentation to the SCA He incorporates them into the COSMO Standards for Source Code Development 26 VCS according to the Release Planning In accordance with the guiding authority SMC for COSMO CLM_CO and TAG for CLM he assigns a status to each version development test release See Sect 6 1 for the definition of t
6. avail able by such a VCS is an official version while all other versions that exist only in a private framework are private versions SCA defines a status of the official version which can be development test or released version e Reference Version Reference version is an official released software version approved by the Steering Com mittee It must be at least every unified version of the software According to the Agreement establishing the COSMO Consortium the Steering Committee is responsible for approval of the valid reference version of the Software The STC approves also the COSMO resources if they are used for the development of the Software And the STC of course also approves this document and therefore the whole development process For the COSMO Model the STC defined some extra rules to coordinate the Software devel opment between the NWP COSMO CLM and COSMO ART communities The STC confirms the importance of these three COSMO applications and the fruitful cooper ation between the respective communities For accomplishing this goal it stresses in particular the key role of the common reference COSMO code and its long term stability Consequently the ART and CLM communities take part in the source code management process via sci entific cooperation with the respective Working Groups and via their representatives in the COSMO Standards for Source Code Development 4 Scientific Management Committee The STC will thoroug
7. going to be a released version the NWP and or COSMO CLM test suite have to run with this version see 6 6 Some comments on these rules UE 2a 2b 3a Before the discussion in the SMC new developments changes can also be discussed in other groups development teams Working Groups teams at universities etc which want to contribute to the development of the COSMO Software The SMC will then discuss and decide on the acceptance of changes and propose a Priority Project a Priority Task or a Working Group Task to the STC For major developments it is recommended to split up the design and implementation process in several steps to make sure early that scientific technical requirements are met This can be done by discussing the design with other scientists and or the TAG If developers are not sure about meeting technical requirements the TAG should be contacted in an early phase of the development Testing the changes Which tests have to be performed depends on the type of change In the list of actions the SMC should also specify for all developments which tests are required COSMO Standards for Source Code Development 21 3b Bug fixes Bug fixes have to be implemented into an official version without much delay but it has to be clear that it is a bug This can be discussed with the Code Developer Responsible and or the Working Group Coordinator The bug the solution and the expecte
8. readable if meaningful words are used to construct variable and subprogram names All internal documentation has to be written in English 5 3 Delivering New or Modified Code If new or modified code is delivered the programmer has also to provide the corresponding external documentation to the Editor of the Documentation System e Internal product documentation The code has to be structured in meaningful units sections which are documented within the source code e External product documentation For new code an external scientific and implementation documentation as well as an extension to the User Guide has to be provided For modified code the existing external documentation has to be updated If new scientifically oriented components are added to the COSMO Model external scientific documentation can be provided by a COSMO Technical Report or by a COSMO Newsletter article e Process documentation The programmer has to produce a short documentation of the changes to the existing software version that can be included to the version history and the changes log file e All documentation has to be written in such a way that it can be taken over to the existing official documentation without substantial modifications or technical adjust ments It is planned to distribute the LaTex source files of the documentation together with the Source Code Repository COSMO Standards for Source Code Development 16 6 Software Mainten
9. scientifically U Sch ttler oriented code DWD Some Abbreviations and Explanations STC Steering Committee The STC is the main governing and steering body of COSMO It is responsible for and approves the changes to the official versions of the COSMO Software SMC Scientific Management Committee The SMC defines the changes to the COSMO Software and is responsible for their implementation TAG Technical Advisory Group The TAG defines the technical rules for implementing COSMO Software SCA Source Code Administrator Every COSMO Software has a main SCA who is responsible for the mainte nance VCS Version Control System A system to manage changes to source code and documentation which allows to track modifications and retains the history of all previous versions of a software Contents 1 Introduction 2 The Development Process Some Mandatory Aspects 3 Software Design 4 Coding Rules 4 1 4 2 4 3 Style and Typing Rules gt siii 482246 paia a eh AE Mandatory Features a Banned Features ccom a 68 04 04 dara A aS 5 Documentation 5 1 5 2 5 3 Process Documentation das cada a A a GE we a Product Documentation ks saca a a a A Es Delivering New or Modified Code 6 Software Maintenance and Quality Control 6 1 6 2 6 3 6 4 6 5 6 6 6 7 Version and Release Management 0000002 e Rules for Implementation of Changes aoaa
10. system architectural design downloadable through GUI of the system 3 Coding Rule document that describes the convention adopted that will be available on ftp meteoam it in the next future 4 Performance Test that describes the test cases to follow for system testing available on ftp meteoam it N B User and Technical manuals are updated every time a new version of system is delivered Other used tools are 1 MySQL workbench for database design 2 Doxygen for automatic PHP documentation COSMO Standards for Source Code Development 38 Software Maintenance and Quality Control VERSUS is maintained by CNMCA using Patching versioning A complete installation pack age will be release a the end of the Project development with no Patches in addition All changes to the code are tested extensively before the official release Performance test dataset available on ftp meteoam it and the test cases to follow described on PerformanceTest doc documentation should be used by the user to check system performance after any update COSMO Standards for Source Code Development 39 D Steps of Code Development for CLM Community Model Versions Contact the CLM Community Technical Advisory Group in case of further questions mail to clm_ tag at listserv dfn de Steps What to do see Tab Sec 6 1 Inform the CLM Contact a member of the CLM coordination group 2 2 1 Community co C
11. ARACTER data types the length type parameter LEN specifies the number of characters in such an entitiy 7 3 Parallelization 7 4 Optimization 7 5 Vectorization 7 6 I O 7 7 Error Handling Debug Messages Just a comment COSMO Standards for Source Code Development 29 Error messages should be meaningful and easily understandable for the user and it should be possible to find them in the source code It is not sufficient just to give an error code number especially it should be avoided to compose this number as a sum of an index with some basis number which makes it too difficult to locate the error with a grep or similar COSMO Standards for Source Code Development 30 References 1 Andrews Philip UKMO Gerard Cats KNMI HIRLAM David Dent ECMWF Michael Gertz DWD and Jean Louis Ricard MeteoFrance European Standards For Writing and Documenting Exchangeable Fortran 90 Code Version 1 1 1995 2 E Kalnay et al Rules for Interchange of Physical Parametrizations Bull A M S 70 No 6 p 620 1989 3 Sommerville lan Software Engineering Fourth Edition Addison Wesley 1992 COSMO Standards for Source Code Development 31 A Standard Headers for the COSMO Model and INT2LM The standard headers are presented in this appendix They are written as templates Text inside lt gt brackets must be replaced with appropriate text by the user Program Header lt A one line description of this pr
12. Arguments OutputArguments gt Description lt Say what this routine does gt Method lt Say how it does it include references to external documentation gt lt If this routine is divided into sections be brief here and put Method comments at the start of each section gt Current Code Owner lt Name of person responsible for this code gt History Version Date Comment PE anaa Sees lt version gt lt date gt Original code lt Your name gt Code Description Language Fortran 90 Software Standards COSMO Standards for Source Code Development Declarations Modules used USE ONLY amp Imported Type Definitions Imported Parameters Imported Scalar Variables with intent in out Imported Array Variables with intent in out Imported Routines lt Repeat from USE for each module gt Declarations must be of the form lt type gt lt VariableName gt Description purpose of variable Subroutine arguments Scalar arguments with intent in Array arguments with intent in Scalar arguments with intent inout Array arguments with intent inout Scalar arguments with intent out Array arguments with intent out Local parameters Local scalars Local arrays EO ge Nesdger ee E Subroutine Body END SUBROUTINE lt SubroutineName gt COSMO Standards for Source Code Development 33 Function header
13. LM CO mail to clm_colat listserv dfn de Add 6 1 ordination group information about the intended development to the about your plans CLM topic browser Get a released Download a COSMO CLM version available from the version CLM Community home page RedC and contact the CLM TAG mail to clm_taglat listserv dfn de if an other COSMO version is needed Implement your Right from the implementation of the first 2 3 2 1 changes changes the released version becomes a Atde 4 velopment versionAt lst private version see 7 A COSMO Standards for Source Code Development CSCD Section 6 1 Although a development version is not subject to the conditions of the CSCD it is good practice to follow them right from the beginning For new program units FUNCTIONs MODULEs PROGRAMs SUBROUTINEs use the available templates Perform devel Define and apply some development specific tests and 2 3 3 5 opment specific simulations exhibiting the effect of the code devel tests and simula opment on your development version The tests and tions simulations should be applicable also to the released version in which the final implementation of the de velopment will be included Write a short re Summarize the development and the results from the 2 1 port development specific tests in a short report and pro vide it to CLM CO Use the development report tem plate CLM CO discusses the report and recom mends the implementation
14. The components then have to be mapped to programming language components such as procedures functions or modules Fig 1 gives a sketch of the top down design for the software of the COSMO Model This rather coarse but generic breakdown could also be used for other software projects Main Organizational Layer lmorg Physics organize_physics Sub Systems Dynamics Layer organize_dynamics e Leapfrog dynami e Microphysics cal core e Radiation Components e Runge Kutta dy namical core e Convection e Relaxation e etc it T Common Meteorological Utilities Layer ye Panallchize On l una Utilities Figure 1 Schematic view of a Software Design In the following we will give some common rules for the design and implementation of individ ual software components especially for the use in meteorological models Some of them are derived from the European Standards 1 which in turn are based on the plug compatibility rules of Kalnay 2 She defines a package as a set of Fortran subroutines to parameterize atmospheric subgrid scale physical processes To exchange packages between different centres it is necessary to use a standard programming style that facilitates the interchange In the European Standards the term package is used but not cleary defined As they refer to the plug compatibility rules of Kalnay et al 2 it is likely that e g the physics packages are meant More commonly we will speak of software components o
15. a aa a a Rationale for Changes sarmad erdam radda ki fir k satai Release Planmiao o dor o a dom ola al Be dra oa a e RA A Standard Test Suite for the COSMO Model aaa aaa a Meteorological Test Suite Testing the official versions in the VOS LL 7 Implementation Issues wl 1 2 7 3 TA 7 5 Memory Management Working Precisi n lt Losa cea 2 eon dk wade go bee EO Boe SE e MA Oi iu af 6 le ee ee EA ee AE Boe ae ee ee os ODDIO su Bh cn ee e ey rd e SE Vectorizati o oa soraba e e a A ALA 11 11 13 13 14 15 16 16 18 21 22 24 24 25 COSMO Standards for Source Code Development ii A Standard Headers for the COSMO Model and INT2LM B Amendments for fieldextra C Amendments for VERSUS D Steps of Code Development for CLM Community Model Versions 31 35 37 39 COSMO Standards for Source Code Development 1 1 Introduction This document specifies standards for source code development within the Consortium for Small Scale Modeling COSMO The CLM Community which uses the COSMO Model also follows these standards They are valid for all versions of the COSMO Software and will also be applied to software provided by other institutions or communities that is intended to be incorporated into COSMO Software At the date of writing the COSMO Software is composed of the COSMO Model the interpolation program INT2LM the postprocessing tool fieldextra the verification pac
16. all tests are successful a if necessary consolidated version x y will become Release II COSMO Standards for Source Code Development 24 6 5 Standard Test Suite for the COSMO Model Depending on the category of changes all contributions to the software have to go through the steps specified in Section 6 2 before they are submitted to the SCA One aspect is to test pure technical issues like the independence of the processor configurations and similar things Issues to be checked are for example e Independence of processor configurations MPI and OpenMP for parallel code e Reproducibility of results with older versions if applicable e Restart functionality e I O with Grib NetCDF e Tests with array bound checking e Possibility to run with input data from different models GME IFS ERA etc e Timings efficiency scalability e Portability For testing most of these issues a standard technical test suite has been developed at Me teoSwiss which can easily be installed and applied at every center The user can then adapt and use already existing tests or can define additional tests of his own A User Guide for the test suite and a tar file can be found on http www cosmo model org content model documentation standards default htm 6 6 Meteorological Test Suite NWP Test Suite In addition to the developers tests on individual implementations the NWP test suite has to be performed for each completed new version of th
17. ance and Quality Control The purpose of this section is to define a clear and transparent release management This should ensure a proper implementation of new versions and a smooth updating of the opera tional systems A necessary condition for that purpose is to give clear rules how the software can be updated 6 1 Version and Release Management The purpose of maintenance is that the product continues to meet the needs of the end user Over the lifetime of a system its original requirements can be modified to reflect changing needs the system s environment can change and errors may show up Therefore we can identify three categories of maintenance A Further developments If the requirements to the software are changing the software must be extended to meet the new requirements This means either that new components have to be developed or that existing components must be changed significantly in contents B Perfective maintenance technical changes Perfective maintenance improves the system but does not change the functionality These can be changes in parallelization data I O or also modifications to the general architecture of the software C Corrective maintenance bug fixes This is needed to correct detected bugs and coding errors Usually they are easy to correct but less easy to find sometimes Maintenance can be considered as an iteration of the development process and therefore the same standards and procedures should b
18. ased to the NWP community CLM release A version that passed the COSMO CLM tests see 3 5 3 6 in Table 6 1 and standard evaluation and is released to the CLM Community NOTE COSMO CLM subversions are maintained within the CLM Community There fore COSMO CLM releases may differ from any NWP versions of the code Unified release A model version which is a NWP and a COSMO CLM release STC approves a special released version to be the Reference Version and that concerns espe cially software versions which are unified for all COSMO communities COSMO Standards for Source Code Development 18 For the COSMO Model it is planned that each main model version Version x 0 is a uni fied release for numerical weather prediction regional climate modelling and environmental modelling The following sections are mainly written for the COSMO Model and the INT2LM Neverthe less some of the rules are also applicable to other COSMO Software but specific guidelines e g for fieldextra are given in the Appendices 6 2 Rules for Implementation of Changes All updates for the COSMO Software should follow two guidelines e Scientific The COSMO Software is further developed according to the COSMO Science Plan which describes the COSMO goal and the strategy to attain the goal in the near future Of course this does not mean that developments can only find their way into the model if they are reflected in the Science Plan COSMO is still ope
19. cience Plan But on the way between two Reference Versions several working released versions might occur Rationale how new releases are defined Assume there are 5 new accepted contributions A B C D E that have to be implemented into official versions The SMC puts up the following list for Release Planning e Release I contains contributions A C D e Release II based on Release I contains contributions B E The SCA implements the contributions e development version x n contains contribution A e development version x n 1 contains contribution C The SCA declares version x n 1 to be a Test Version because contributions A and C have to be tested together After successful testing contribution D is implemented e developement version x n 2 contains contribution D The SCA again declares version x n 2 to be a Test Version This is now also a release candidate for Release I If the testing is successful version x n 2 will be declared as a Release Version If the testing indicates problems these have to be investigated again which might lead to additional development work and additional model versions After successful testing a consolidated model version x m will become Release I and imple mentation of the other developments can start e developement version x m 1 contains contribution B e developement version x m 2 contains contribution E The SCA declares version x m 2 to be a Test Version and if
20. d effects on the results have to be documented 3c Technical changes For technical changes no or only slight differences in the results are expected Slight differences due to numerical reasons e g changing order of computations for optimiza tion are acceptable but must be clearly documented 3d Verification Sometimes physically more consistent implementations can lead to worse verification scores for what reasons ever Changes can be taken over in such cases also 3e Timings For operational reasons increasing run times are not desired On the other hand it is obvious that more accurate better algorithms can take more time to run 6 In order to assure a good quality code and support in the future there is the need that all components of the code do have a responsible contact person This responsible person has to be affiliated at a COSMO member or a COSMO partner institution institutions which are allowed to use the COSMO Model Preferably this should be the developer him or herself but alternatively an institution responsibility can be accepted 8 Before checking code into the VCS the SCA will give the changes back to the developers for a last cross check of the implementation Sharing of code with other software and incorporation of code from other communities If code from the CLM or the ART communities should be incorporated into the COSMO Model the same rules do apply e g the Unified Releases The only excep
21. d into official versions and how new releases are defined 1 Every contribution has to be accepted by SMC before it can be put to an official version according to No 7 from Table 6 1 The SMC includes accepted contributions to the Release Planning So all accepted contributions are assigned to a special future release The SCA updates the lists on the COSMO web site accordingly 2 Accepted contributions are implemented by the SCA into official versions Depending on the scope of the contributions several contributions can be put to a single or to several new Development Versions 3 After implementing some or all of the accepted contributions the SCA in collaboration with the SMC defines a certain version to be a Test Version 4 The Test Version is tested by designated COSMO colleagues See also Sect 6 7 for more details on testing COSMO Standards for Source Code Development 23 5 If the tests were successful e either other contributions are implemented on top of this Test Version to get another Test Version e or this Test Version is defined to be a Release Version if all the contributions for a special release are implemented and will be distributed Every released version contains concluded developments and is capable of performing proper forecasts But not every released version is necessarily a Reference Version Reference Versions are defined and approved by the STC based on general planning in line with the COSMO S
22. e COSMO Model before aquiring the status of a released version by the SMC A COSMO Priority Task was defined in the year 2013 14 with the goal to develop a platform using ECMWF resources on which new test versions of the COSMO Model will be tested for their forecasting performance against the previous version within a common statistical framework A detailed manual that describes the use of the NWP test suite is available on the COSMO web site For the purposes of the NWP test suite each COSMO Model test version will be installed and executed in a hardware environment that is accessible and available to COSMO scien tists assigned by STC who will be responsible for the maintenance and the operation of the suite on an annual basis ECMWF computer resources are used for the aim of this task for simulation and archiving purposes as well as for the performance of the verification analysis by using billing units of the members provided through a special project SPITRASP The COSMO Standards for Source Code Development 25 model domain horizontal and vertical resolution duration of simulation number of simula tions that are applied within this NWP test suite are following the guidelines provided by an assigned group of COSMO coordinators The model domain covers the main area of interest from a meteorological point of view that surrounds the territory of the participating COSMO countries The forecast period of each daily run is 72 hours
23. e applied This means among other things If necessary new requirements must be formulated and validated E g the need for a new parameterization or a new dynamical core New components must be designed and implemented If existing components of the system must be changed there has to be a clear redesign before the implementation phase Parts or all of the system must be tested and validated Quality Control In short there have to be similar rules to update the software and implement changes as there are for the initial development For COSMO Software Table 6 1 in Sect 6 2 specifies these rules To keep track of all the changes a version control system VCS must be used With a VCS the source code is stored at a central repository and the history of all files can be COSMO Standards for Source Code Development 17 recorded Thus it is able to distinguish between the different versions of the software The COSMO Model and the INT2LM are maintained at DWD using a VCS which is an in house development based on publicly available tools fieldextra is maintained by MeteoSwiss using Subversion Every version which is not part of a VCS is called a private version and is available only for the developer Only if code is provided to the SCA and checked into the VCS it is part of an official version For every official version the SCA defines a certain status to identify its availability for the users Development Versi
24. eader lt A one line description of this module gt Description lt Say what this module is for gt Current Code Owner lt Name of person responsible for this code gt History Version Date Comment ll ces dei ao lt version gt lt date gt Original code lt Your name gt Code Description Language Fortran 90 Software Standards COSMO Standards for Source Code Development Modules used USE ONLY amp Imported Type Definitions Imported Parameters Imported Scalar Variables with intent in Imported Scalar Variables with intent out Imported Array Variables with intent in Imported Array Variables with intent out Imported Routines lt Repeat from USE for each module gt Declarations must be of the form lt type gt lt VariableName gt Description purpose of variable Global i e public Declarations Global Type Definitions Global Parameters Global Scalars Global Arrays Local i e private Declarations Local Type Definitions Local Parameters Local Scalars Local Arrays Operator definitions Define new operators or overload existing ones END MODULE lt ModuleName gt COSMO Standards for Source Code Development 35 B Amendments for fieldextra Style and Typing Rules A set of additional coding rules and conventions are defined in the file README developer distributed with the fie
25. eloping and main taining the system user documentation provides a product description oriented towards system users 5 1 Process Documentation Process Documentation contains the following important features e Standards for coding rules documentation quality control testing and verification This document e For subsequent changes to the code A version history and a changes log file The SCA distributes that with every version of the Software e Plans for future developments milestones and deliverables The Management maintains lists for these purposes e A list of known reported bugs Bug Tracker This is maintained by the SCA e Regular reporting on the work done The SCA of the COSMO Software are reporting to the SMC This is done in the framework of the COSMO Priority Task Support Activities All process documentation will be available on the COSMO web page in the near future COSMO Standards for Source Code Development 14 5 2 Product Documentation Product Documentation may be split into two categories external documentation outside the code and internal documentation inside the code In order for the documentation to be useful it needs to be both up to date and readable at centres other than that at which the code was originally produced Since these other centres may wish or need to modify the imported code we specify that all documentation both internal and external must be available in English E
26. ent parallelization optimization and vectorization will be discussed briefly The preferred language for model development still is Standard Fortran But as new computer architectures 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 choice for the computer language to use But no matter which language is used a portable i e a standard source code is absolutely necessary Therefore we intend to transfer these standards logically also to non Fortran applications We are aware of the fact that the existing COSMO Software does not fulfill all of these standards and sometimes not even the most necessary ones But the development team is working on that and tries to make the COSMO Model better with every new version Not only 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 be explicitly stated when this is the case If additional rules or clarifications are necessary they are stated in appendices to that document Note that additional and or slightly different and adjusted rules might be valid for the source code development at partner institutions and communities for source code not to be incorporated into COSMO Software This document will be enacted during summer 2011 but will be revised in the future based on
27. ents have an optional argument to let you do this Passing arrays through argument lists Call by reference vs Call by value COSMO Standards for Source Code Development 28 Assume shaped vs explicit shaped arrays 7 2 Working Precision Use of the KIND type concept Fortran 90 provides representation methods for the intrinsic data types INTEGER REAL COMPLEX CHARACTER LOGICAL Each method can be specified by a value called kind type parameter which is a scalar integer initialization expression that indicates the decimal exponent range for the integer type the decimal precision and exponent range for the real and complex types and the representation methods for the character and logical types Each intrinsic type supports a specific set of kind type parameters For REAL types for example every compiler must support the former types single precision and double precision To specify the representation method the kind type parameter can be given for some type specifiers INTEGER REAL COMPLEX REAL KIND method or REAL KIND methods Here method are the kind type parameters Intrinsic functions are provided to specify the kind parameter for a specified precision and variable range method SELECTED_REAL_KIND 12 200 specifies the representation method that has a working precision of at least 12 significant digits and an exponent range of at least 200 This is the double precision data type For CH
28. ersions Therefore we give the following recommendations when introducing changes Bug fixes Can be introduced without backwards compatibility Technical changes These should change the results only because of numerical reasons If it can be shown by long term simulations that the changes are neutral they can be introduced without backwards compatibility If this cannot be shown then these changes should be treated as the next item Modifications which change the results but should be adopted by everybody Use a clearly documented internal switch in the source code Once the change is commonly accepted this switch can be removed again Adding of new components In this case a new namelist switch may be used 6 4 Release Planning In addition to the list of actions Planning for Future Developments the SMC will maintain a roadmap for every COSMO Software including priorities for the upcoming changes the Release Planning STC who eventually has to approve resources for the work required will continuously be informed about these lists which will be published on the COSMO web site The planning should aim at having at most 2 3 major releases for the software every year There might be more development and test versions Especially bug fixes can be implemented in interim versions In the following we want to describe the perhaps iterative process how accepted contribu tions to the COSMO Model also INT2LM are incorporate
29. es e Ideas can be initiated among others by individuals the Working Groups and the Management itself e If COSMO resources are to be used for the Software development the approval of the Steering Committee is needed 3 The development The Developer now has to prepare the changes and do the tests according to the COSMO Standards This is still done with a private version The following issues have to be met e The source code provided is properly designed Some guidelines for software design especially for the COSMO Model are out lined in Chap 3 Software Design The Developer should design the changes and the assembly into the official Software in collaboration with the SCA and the code responsible persons of the corresponding software components e The source code provided conforms to the coding rules The decision whether the coding rules are fulfilled is taken by the SCA of the corresponding software In case of conflict the case is taken to the Technical COSMO Standards for Source Code Development 5 Advisory Group TAG For CLM versions the CLM Community has its own TAG which is responsible in this case See Chap 4 Coding Rules for details e All source code modifications are documented This means that for all modifications extensions changes bug fixes the product documentation scientific user guide has been written or updated and a contribu tion to the process documentation short description of
30. hese terms The following tests will be done with the official versions Development Versions If several changes by different developers have to be incorporated into an official version the SCA can build different development versions for that The SCA checks the standard technical test suite for these versions Test Versions While the individual changes have been tested separately by the developers the test versions which summarize different contributions are given to special test persons within the Consortium who are conducting more extensive common tests For the COSMO Model for example DWD will test such versions in its Parallelsuite Released Versions or Releases If a test version passes these tests successfully it can be released to all users COSMO Standards for Source Code Development 27 7 Implementation Issues This chapter should give some hints for efficient programming All that follows is a draft and will be further developed in the near future NOTE This chapter is work in progress The TAG will complete it until the SMC meeting in early 2012 7 1 Memory Management Allocation of Memory The use of dynamic memory is highly desirable as it allows one set of compiled code to work for any specified resolution and allows the efficient reuse of work space memory Care must be taken however as there is potential for inefficient memory usage particularly in parallelized code For example heap fragmen
31. hly consider their opinions while making the final decisions on the reference software For functions which are mission critical for CLM or ART it will be open for implementing them with ifdefs In the following the steps are specified that changes to the Software have to pass At the same time it shows the management decisions that have to be taken when adopting developments to the official COSMO Software 1 The idea In the beginning there has to be an idea about what can be developed for the Software The Developer implements all necessary changes into a private version based on the latest official version of the Software and performs appropriate tests He she presents the results as a report and or a presentation to the Management and proves the usefulness of the changes Note In this state it is not necessary to fulfill the rules of the COSMO Standard but it will be very helpful for the further steps 2 The first decision The Management decides whether the idea and the corresponding change to the Soft ware is in line with the scientific and or the technical planning If it is of interest and usefulness has been proved it is included into the Planning for Future Developments see Chap 6 4 Release Planning for details The Developer is asked to design and implement the changes according to the COSMO Standards Depending on the complexity of the changes the Management decides on minimum range of necessary tests Not
32. ight define additional or modified rules and conventions for development See Appendix B for amendments regarding fieldextra 4 1 Style and Typing Rules The general objective behind a style guide is to write portable code that is easily readable and can be maintained by different people Many rules follow common sense and should be obvious Although it is always tempting for scientists to restrict coding efforts to their specific application we strongly urge you to try and write the code in a more general form This will make it much easier to make modifications or couple your routine to others The following coding rules can be split into 1 Rules that should be applied and will be checked by the source code administrators before implementing changes to the official version Some of these rules are strict which is indicated below and their application is mandatory 2 Conventions that are not checked but are highly recommended to follow COSMO Standards for Source Code Development 9 1 Rules e strict Only use standard language elements to ensure a portable code e strict Use free format syntax e Text style strict Fortran statements keywords must be written in upper case only strict Names of variables parameters subroutines etc must be written in lower case strict Never use a Fortran keyword as variable name strict Owing to the international user community all naming of variables mod ules func
33. in a released ver sion or not Port the devel If necessary port the implemented and tested develop 4 7 2 1 opment into the ment in the last released version 2nd private version A and last released ver The CSCD are mandatory now 2 2 sion still under development COSMO Standards for Source Code Development 40 Technical test Apply the technical test suite to the 2nd private ver 4 7 3 1 suite sion Contact the source code administrator SCA in A order to know how to do that Repeat the Discuss with the coordinator of the respective working 3 5 development group which development specific simulations need to specific tests and be repeated with the 2nd private version conduct the simulations simulations compare the effect with that of the orig inal implementation and update the short report CLM CO discusses the updated report and recommends the implementation in a released version or not CSCD check provide the development to the SCA together with the 4 3 2 test results and the internal and process documenta 5 3 and tion 8 SCA checks if the coding rules of CSCD are respected In case the check is negative the code has to be revised and the revised version has to be sent to the SCA again Standard test Pass on the new development to the coordinator of 3 6 suite the evaluation group The evaluation group applies the standard test suite discusse
34. in argument lists Always use the attribute INTENT IN OUT INOUT to indicate usage of the variables e Miscellaneous Checking of return codes e g from ALLOCATE DEALLOCATE OPEN READ statements helps in avoiding unexpected program behaviour and should be used whereever possible I O Separate the information to be output from the formatting information on how to output it on I O statements That is do not put text inside the brackets of the I O statement Use gt gt lt lt instead of gt ge eq 1t le ne in logical comparisons The new syntax being closer to standard mathematical notation should be clearer If array notation is used show the array s shape in brackets to improve the read ability e g array_1d array_1d_b array_1d_c array_2d scalar another_array_2d 2 Conventions e All new code should be based on the templates given for different programming units see A Unused header lines should be removed e We recommend the following conventions for variable names INTEGER variables start with the letters i j k m n Local INTEGER variables start with iz jz kz mz nz loop indices i j k etc are an exception to this rule COSMO Standards for Source Code Development 11 LOGICAL variables start with the letter 1 Local LOGICAL variables start with the letter 1z CHARACTER variables start with the letter y
35. ions of this paper some mandatory aspects of source code develop ment are specified This section just summarizes the most important ones at a glance and can be used as a step by step instruction COSMO Standards for Source Code Development 2 e Software Design Software design is the process of problem solving and planning a software solution It thus 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 efficient solution e Coding Rules The coding rules specify a common programming style that has to be adhered to by all COSMO Software This enhances the readability and exchangeability of source code e Documentation The 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 documentation and the external documentation outside of the code e Software Maintenance and Quality Control An essential part of the software development process is the maintenance of the software and the quality control of each version Also clear rules have to be defined how to go from one version to another in operational production e Implementation Issues In addition to the Coding Rules we will give some recommendations for the practical implementations Issues like memory managem
36. k that it is still useful to name the temperature as t and not as temperature This notation is also closer to the formulas in the documentation Do not use the DIMENSION statement or attribute declare the shape and size of arrays inside brackets after the variable name on the declaration statement Use the saved space for documenting Always use the notation even if there are no attributes Declare the length of a character variable using the LEN syntax COSMO Standards for Source Code Development 10 There still is no default REAL datatype across all compilers Most compilers imple ment the REAL datatype in 32 bit decision but there can be exceptions To improve portability between all compilers it is extremely useful to make use of KINDs to obtain the required numerical precision and range A module should be written to define parameters corresponding to each required KIND This module can then be USEd in every routine allowing all variables to be declared with an appropriate precision See Sect 7 2 Working Precision for more details e Program Units and Interface Blocks strict Always name program units and always use the END PROGRAM END MODULE END SUBROUTINE END INTERFACE etc constructs again specifying the name of the program unit Always use only one MODULE per file where the file name matches the name of the MODULE Always use USE modulename ONLY to specify which of For variables
37. kage VERSUS The COSMO Standards for Source Code Development are based on the European Standards for Writing and Documenting Exchangeable Fortran 90 Code 1 and should complement and adapt these for the needs of COSMO where necessary The European Standards have been defined in the 90ies to facilitate the exchange of code between meteorological centres They provide 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 the European 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 The further development of the COSMO Model within this bigger community now requires an even 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 development and programming process and should serve the following goals e encourage well structured programming e increase readability and useability of source code e standardize the look and usage of source code units e create machine independent portable source code e simplify maintenance tasks e facilitate quality management and control The main chapters of the COSMO Standards are e Mandatory Aspects Throughout all sect
38. l as 2 3 km Verification results should be positive or neutral regarding the latest official release Note The term should is chosen on purpose Sometimes a change leads to a more physical formulation although the results do not improve 3 5 Individual tests exhibiting the effects of the modifica y V v CLM tions 3 6 Standard evaluation of climate simulations V CLM COSMO Standards for Source Code Development 20 No Description Further Bug Fixes Technical Changes Developments Presentation of the results The results should be pre sented to the corresponding COSMO and or CLM Working Group if possible during the COSMO Gen eral Meeting the COSMO User Seminar or the CLM Assembly where appropriate Provide extensions modifications for the Documenta V V g tion System Provide a test case and associated results if appropriate For new components a code responsible person has to V be nominated by the developer s Discussion within the Management about the imple V af mentation into the VCS and updating of the Release Planning For COSMO a final approval has to be done by the STC Submission of the changes to the SCA who does a fi y y af nal check whether the technical requirements Coding Rules Documentation are met He checks the modi fications into the VCS and in collaboration with SMC assigns a status development test release to the new version If it is
39. l version The official implementation may have a status of development test or released version As there might be several contributions which should not be implemented all in one there might be several consecutive versions which are not released officially called Development Versions see 6 1 Version and Release Management for more details The SCA provides the officially implemented code to the Developer again for cross checking 6 The STC approval The STC approves the Reference version of the software after it was approved by the Management via its second decision and after it was implemented by the SCA and pos itively tested by the COSMO test users to become a release version The STC approval concerns especially software versions which are unified for all COSMO communities COSMO Standards for Source Code Development 6 3 Software Design Before the software can be designed the physical model has to be constructed For non physical or non numerical projects an abstract specification has to be developed that spec ifies the tasks of the software and the services it should provide Also the constraints under which it has to operate have to be defined A Top Down design starting by the main task and splitting this into smaller units modular design is most promising for an efficient software development Depending on the complexity of the model the system can be split into sub systems which themselves consist of components
40. ldextra package At the time of the writing this document is a work in progress based on the release 10 4 of fieldextra Note that most of the rules defined in Chap 4 of this document apply The most notable exceptions are DIMENSION Use of DIMENSION statement is recommended USE modulename ONLY Is not required for general purpose modules such as modules used for definition of program entities fxtr_definition or modules used to manage program diagnostic support_information GOTO Usage is accepted when dealing with error conditions to jump to the error processing part of the procedure Variable names Do not use the naming conventions associated with the variable type e g LOGICAL starts with 1 and similar Multiple statements on the same line Is allowed for short statements logically related e g exception handling initialization of some local variables Documentation The documentation for fieldextra is written in plain ASCII The following documents are available within the fieldextra package or on the COSMO web site CREDITS list of contributors HISTORY version history and change log files list of known bugs ROADMAP plans milestones and deliverables README install installation guide FirstContact pdf README user README user locale and FAQ user guide README developer and README cosmo_api implementation guide COSMO Standards for Source Code Development 36 Software Main
41. n for developments that do not fully adhere to this plan if they are valuable for the community Similar but less extensive plans do also exist for other COSMO Software e Technical Implementation and documentation of all changes have to follow the COSMO Standards for Source Code Development this document This holds for all developments whether they come from inside or outside of COSMO Depending on the categories of changes given in Sect 6 1 and on the type of the code the standards for updating software are different For the COSMO Model changes of Category A further developments surely have to fulfill more requirements than technical changes Table 6 1 below lists a set of rules that have to be followed Bug fixes and technical changes can skip some of these rules The last columns indicate which rules have to be obeyed Note that these rules apply to the COSMO Model and the INT2LM For other COSMO Software similar rules may be specified The CLM Community also compiled a lists with Steps of Code Development for CLM Community Model Versions wich is given in Appendix D Table 6 1 Rules for Implementation of Changes No Description Further lt Developments Bug Fixes Technical Changes 1 Information of Working Group Coordinators and dis cussion within the Management on planned changes new developments The Management maintains a list of actions for planned ongoing developments the Planning for Fut
42. ne for the package The package component should be written in such a form that it can easily be extended in the future if e g the requirements change The routines of a package component shall be grouped together in bigger program units of reasonable size In principle it would be good to have them all in one file or compilation unit but this might not be possible due to computer resources available memory during compilation or also human resources one file of several thousand lines of code will be hard to manage by a programmer The interface s with other packages components must be clearly defined and doc umented The interface specification must be unambiguous as it allows the package component to be used without deeper knowledge of the internal operations The data structures used in the system implementation must be defined and docu mented in detail This also includes the memory management of the software The algorithms used to provide the services have to be designed and documented System Installation Once the software has been designed and implemented some means should be provided for the installation of the system This also has to be documented clearly COSMO Standards for Source Code Development 8 4 Coding Rules The general ethos is to write portable code that is easily readable and maintainable Code should be written in as general a way as possible to allow for modifications In practice this mea
43. ns that coding will take a little longer This extra effort is well spent however as maintenance costs will be reduced over the lifetime of the software The SCA of the corresponding code will supervise the programmers and check all develop ments If changes are not in line with the coding rules or more general with the COSMO Standards the code can be rejected and or be given back to the developers for improvement In case of conflict a Technical Advisory Group TAG will decide on the issue Since the rules specified in the following do not cover all aspects the SCA and or the responsible TAG either COSMO or CLM can be contacted in case of further questions The rules presented in this chapter are mainly applicable for Standard Fortran but some of them can surely be transferred to other programming languages We give some style and typing rules and for Fortran we distinguish between mandatory features and banned features from former Fortran standards Fortran77 and older The Fortran Standard is evolving with the years but compilers do not always comply with the full standard By the time of writing this document the NEC Compiler for example does not support a significant part of the Fortran 2003 Standard Therefore we only require compliance with the Fortran 95 Standard Please contact the TAG before using elements from a newer standard These rules are primarily intended for the COSMO Model and the INT2LM Other COSMO Software m
44. ogram gt Description lt Say what this program does gt Method lt Say how it does it include references to external documentation gt lt If this routine is divided into sections be brief here and put Method comments at the start of each section gt Input files lt Describe these and say in which routine they are read gt Output files lt Describe these and say in which routine they are written gt Current Code Owner lt Name of person responsible for this code gt History Version Date Comment a iene pece lt version gt lt date gt Original code lt Your name gt Code Description Language Fortran 90 Software Standards COSMO Standards for Source Code Development Modules used USE ONLY amp Imported Type Definitions Imported Parameters Imported Scalar Variables with intent in out Imported Array Variables with intent in out Imported Routines lt Repeat from USE for each module gt Declarations must be of the form lt type gt lt VariableName gt Description purpose of variable Local parameters scalars arrays b End of header __co_rm _r r__ yTr_rrr 9 gu1 i oa a eee Program Body END PROGRAM lt ProgramName gt COSMO Standards for Source Code Development 32 Subroutine header lt A one line description of this subroutine gt SUBROUTINE lt SubroutineName gt lt InputArguments inout
45. on one daily cycle based on the OOUTC initializing data The simulation period for each test was decided to include one month for the summer July 2013 and one month for the winter season January 2013 in total 4 months two for each model version The initial and boundary data are provided by the ECMWF IFS system As a first approach the 7km version of the COSMO Model is used for these tests following the operational resolution in most meteorological services If the implemented changes in the model code are especially designed to influence the performance of a higher resolution model version then the NWP test suite can be expanded to include additional experiments to check the dependencies of results on the mesh size The VERSUS verification software is installed on a virtual machine based on ECGATE linux system at ECMWF in order to facilitate the verification process For the needs of the NWP tests the verification analysis includes grid to point comparisons utilized to compare gridded surface and upper air model data to point observations A list of selected stations around 3500 stations situated in various places of interest in the domain of simulation are utilized for each test Verification forms include the current standard verification statistics widely used by the NWP community in particular for surface continuous parameters 2mT Dew Point T WindSp TCC MSLP BIAS RMSE 6h 12h 24h accumulated precipitation ETS FBI
46. ons These versions are intermediate versions that are only given to the developers for fur ther work and testing private versions Such versions are necessary if several changes by different developers have to be incor porated into an official version With different development versions the SCA has the possibility to check in the different developments one by one Test Versions These versions can combine several contributions by different developers and are defined by the SMC see 6 4 They are given to special test persons who are conducting more extensive common tests The individual changes have been tested separately by the developers To check that the changes also work well in combination further tests have to be performed Also different configurations have to be tested here Released Versions or Releases If a test version passes the common tests successfully it can be released to all users Recommended CLM Community Versions The released versions need an intensive evaluation in the climate mode including the provision of an optimum configuration for regional climate simulations In the case the model proves to provide better results in the climate mode the version can be recommended to the CLM Community users For the COSMO Model there are some flavors of releases Depending on the different com munities NWP release A version that passed the NWP tests see 3 3 3 4 in Table 6 1 and verification and is rele
47. r just components COSMO Standards for Source Code Development 7 The goal of these rules is to make the physics routines easily transferable between models with only a few hours of work and at the same time minimize the degradation in model efficiency Common rules for the design and implementation A package component shall provide different set up and running procedures if nec essary each with a single entry point All initialization of static data must be done in the set up procedure and these data must not be altered by the running procedures A package component shall refer only to its own modules and subprograms to programmer defined utility procedures such as error handling parallelization or basic algorithms to external libraries to the intrinsic routines included in the Fortran standard The package component shall not terminate program execution If any error occurs within the package it should gracefully exit externally reporting the error via an integer variable in its argument list with the possibility to indicate fatal errors Packages should also write a diagnostic message describing the problem using Fortran I O to an error stream unit number selectable via the package s set up routine The package component should be written as general as possible e g independent of resolution time step etc The resolution for example must be adjustable via the set up routi
48. s the results and recommends the implementation in a released version or not Presentation of Present the development to the correspond 6 2 4 results ing CLM Working Group if possible during the COSMO CLM ART User Seminar or the CLM Community Assembly Extend Modify Revise the parts of the source document of the 5 2 the official COSMO documentation that need to be extended COSMO or and modified Write the scientific documentation Documentation and the necessary extension for the user s guide and provide it to CLM Community coordinator mail to clm coordination at dwd de 3still under development still under development Sstill under development
49. s to be applied at the individual routine level There are four types of internal docu mentation all of which must be present e Procedure headers Every subroutine function module etc must have a header The purpose of the header is to describe the function of the routine probably by referring to external documenta tion and to document the variables used within the routine All variables used within a routine must be declared in the header and commented as to their purpose includ ing physical units if applicable It is a requirement of this standard that the headers listed in Appendix A or similar headers for different COSMO Software be used and COSMO Standards for Source Code Development 15 completed fully Centres are allowed to add extra sections to these headers if they so wish e Section comments These divide the code into numbered logical sections and may refer to the external documentation These comments must be placed on their own lines at the start of the section they are defining The recommended format for section comments is lt Section number gt lt Section title gt where the text in lt gt is to be replaced appropriately e Other comments These are aimed at a programmer reading the code and are intended to simplify the task of understanding what is going on These comments must be placed either immediately before or on the same line as the code they are commenting e Meaningful names Code is much more
50. tandard it was very common practice to pass n dimensional arrays into a subroutine where they would say be treated as a 1 dimensional array This practice though banned in Fortran 90 is still possible with external routines for which no INTERFACE block has been supplied This only works because of assumptions made about how the data is stored Note When using external libraries like BLAS or LAPACK this is still common prac tice The performance improvement here is worth these dirty tricks and well marked by the BLAS and LAPACK usage e Try to avoid the use of DATA and BLOCKDATA This functionality is now given by initial izers COSMO Standards for Source Code Development 13 5 Documentation All large software systems have an enormous amount of associated documentation Some remarkable part of the software process costs should be used to produce this documentation Therefore developer and management should pay as much attention to the documentation and its associated costs as to the development of the software itself The documentation associated with a system falls into two classes e Process Documentation These documents record the process of development and maintenance Plans schedules and project standards for example are process documentation e Product Documentation This documentation describes the product which is developed System documentation describes the product from the point of view from the engineers dev
51. tation can occur if space is allocated by a lower level routine and then not freed before control is passed back up the calling tree There are three ways of obtaining dynamic memory in Fortran 90 1 Automatic arrays These are arrays initially declared within a subprogram whose extents depend upon variables known at runtime e g variables passed into the subprogram via its argument list Automatic arrays will not be retained once the subprogram ends 2 Pointer arrays Array variables declared with the POINTER attribute may be allocated at run time by using the ALLOCATE command 3 Allocatable arrays Array variables declared with the ALLOCATABLE attribute may be allocated at run time by using the ALLOCATE command However unlike pointers allocatables were not al lowed inside derived data types before Fortran2003 and some compilers might still not recognize it Space allocated using 2 and 3 above must be explicitly freed using the DEALLOCATE state ment In a given program unit do not repeatedly ALLOCATE space DEALLOCATE it and then ALLOCATE a larger block of space This will almost certainly generate large amounts of unus able memory and can degrade performance depending on the platform Using ALLOCATEs in every time step or even more often should therefore be avoided unless there is no other way to implement a special feature Always test the success of a dynamic memory allocation and deallocation The ALLOCATE and DEALLOCATE statem
52. tenance and Quality Control fieldextra is maintained by MeteoSwiss using Subversion The code design is described in the documentation of fieldextra A test case with its associated results should be provided with any new development All changes to the code have to be tested using the standard set of examples provided within the fieldextra package COSMO Standards for Source Code Development 37 C Amendments for VERSUS Style and Typing Rules A set of coding rules and conventions are defined in the file CodingRules pdf that will be distributed with the Software Note that most of the rules are defined on following modules 1 RDBMS MySQL hosting e forecasts to be verified time series and grib format e observation Synop and Temp data e configuration data to perform verification models station lists and so on e manager of the verification results Numeric scores and plots 2 Loader Front end for data loading into DB This module is written using php code and follows the object oriented paradigm 3 Scores Front End for e scores computation by means of R language scripting e graphical production by means of jpgraph php libray 4 A Web GUI for users written by into php code Documentation The VERSUS documentation is written using openOffice The available documents are 1 User Manual that describes the VERSUS functionalities downloadable through GUI of the system 2 Technical Manual describes the
53. the changes for the version log file is available See Chap 5 Documentation for details e All changes have been tested The results are published appropriately To ensure continuing high quality of the COSMO Software tests have to be per formed for all new or modified Software Depending on the scope of the changes more or less extensive tests are required The results have to be published to in form the community e g as a COSMO Technical Report a contribution to the COSMO Newsletter a presentation at the General Meeting or the COSMO User Seminar and are linked to the appropriate entries of the code management web pages See Chap 6 Software Maintenance and Quality Control for details e A Code Responsible Person is available in the future In order to assure a good quality code and support in the future there is the need that all components of the code do have a responsible person who can be contacted in case of questions or problems See Chap 6 Software Maintenance and Quality Control for details 4 The second decision The Management checks the results of the tests and whether the above conditions are fulfilled If all issues are satisfied the change is included into the Release Planning which defines the intended version number and date for an official release The code is given to the SCA for implementation into an official version 5 The official implementation The SCA implements the changes into an officia
54. the experiences made The users are invited to give their feedback COSMO Standards for Source Code Development 3 2 The Development Process Some Mandatory Aspects This section sketches the process of software development i e the steps that modifications or new contributions to COSMO Software have to pass before they are part of official COSMO Software It summarizes the general rules that have to be fulfilled by the developers and can be taken as step by step instructions how COSMO Software can be developed Links to more detailed explanations in the following chapters are given For a better understanding some terms are defined first e The Software The code under consideration e The Developer Everybody contributing to the Software by implementing changes and or new com ponents e The Management The group that has to decide on changes to the Software For COSMO this is the Scientific Management Committee SMC on the basic working level and the Steering Committee STC on the final level For this document The Management addresses the role of SMC while the role of the STC is described explicitly For the CLM Community it is the CLM Coordination group CLM_ CO e The Source Code Administrator Every COSMO Software has a main Source Code Administrator SCA who is respon sible for the maintenance e Private versions and official versions The Software is maintained using a version control system VCS Every version
55. tion is for code which is only incorporated with ifdef as is the case for e g COSMO ART Code that is belonging to the sources of the COSMO Model also the code between ifdef and endif has to obey to the rules Additional code that is only linked afterwards e g the sources from COSMO ART does not have to fulfill these rules There is also the necessity to incorporate code from other centres like e g the convection code from IFS Such code is taken as it is to have it comparable to the IFS versions and to keep track of the changes there 6 3 Rationale for Changes All modifications of the COSMO Model should follow the Rationale for Changes In the past we often had the situation that new features have been implemented into an official version as optional even if they were not fully developed and tested yet This approach ensures that the results of the operational applications are not affected but leads to a rapid growth of the number of Namelist variables with which the COSMO Model can be controlled Adding new features with this procedure more or less as a technical change must be avoided in COSMO Standards for Source Code Development 22 the future The Management not only has to decide about adding new features or variants of algorithms but also needs to decide on which components can eventually be removed On the other hand there is a demand from the CLM community that results should be reproducible between subsequent v
56. tions and subroutines as well as all comments must be written in English e Code indentation strict To improve the readability of the code indent the lines within DO DO WHILE block IF CASE INTERFACE etc Indentation of 2 characters seems to be appropriate in most cases strict Where they occur on separate lines indent also internal comments like the code they refer to for reflecting the structure of the code strict Indent continuation lines to ensure that e g parts of a multi line equation or function procedure call line up in a readable manner strict Do not use tab characters in your code This will ensure that the code looks as intended when ported or printed strict Use blank space in the horizontal and vertical to improve readability In particular leave blank space between variables and operators and try to line up related code into columns Similarly try to make equations recognizable and readable as equations e Variables and constants strict IMPLICIT NONE must be used in all program units This ensures that all variables must be explicitly declared and hence documented It also allows the compiler to detect typographical errors in variable names One IMPLICIT NONE per program unit is enough Try to use meaningful variable names or at least avoid use of cryptic names A variable name in Fortran can have up to 31 characters Fortran 90 95 and even up to 63 characters in Fortran 2003 Nevertheless we thin
57. ure Developments COSMO Standards for Source Code Development 19 2 3 n ar y E E Eg No Description E 2 in E 20 Bos BA MEO 2 1 Design development implementation and documen J v tation of the changes within COSMO or by external partners 2 2 The COSMO Standards for Source Code Development y V af this document have to be followed This is monitored by the TAG 3 Testing of the changes according to the Quality Con trol System of the COSMO partner or of the external partner that implements them For NWP users this system must include at least the steps 3 1 3 4 For CLM users steps 3 1 3 2 3 5 and 3 6 apply 3 1 Pass the technical standard test suite see Sect 6 5 si y PP all This is monitored by the SCA TAG 3 2 4 eyes assurance All changes must be checked by a V V J all second person This is monitored by the SCA TAG 3 3 Testing of single cases with verification against obser v v gf NWP vations 34 If significant changes of results are expected more in V V af NWP tensive tests have to be performed e g Longer experiments also for different seasons domains climates with verification against ob servations Experiments to check interdependencies between data assimilation and forecast and also possible impacts on a fine grid nest 7 km 2 3 km Additional experiments to check dependencies of results on the mesh size 7 km as wel
58. xternal Documentation In most cases this will be provided at the package level rather than for each individual routine It must include the following e Scientific Documentation This sets out the problem being solved by the package and the scientific rationale for the solution method adopted This documentation should be independent of i e not refer to the code itself e Implementation Documentation This documents a particular implementation of the solution method described in the scientific documentation and or describes the structure of the code for more technical oriented software All public procedures subroutines functions modules etc in the package should be listed by name together with a brief description of what they do A calling tree for routines within the package must be included The main data structures must be described e User Guide This describes all things that are necessary to know for to use the software in an educated way In particular this describes in detail all inputs into the package This includes both subroutine arguments to the package and any switches or tuneable variables within the package Where appropriate default values sensible value ranges etc should be given Any files or namelists read should be described in detail The external documentation for the COSMO Model and the INT2LM is written in LaTex Other COSMO Software might define different formats Internal Documentation This i

Consortium for Small-Scale Modelling - CLM

Contents

Download Pdf Manuals

Related Search

Related Contents