A1 Core principles

Every paper must include a section at the end of the paper before the “Acknowledgements” entitled “Code availability” or “Code and data availability” as appropriate.

1. This section must include citations for the persistent public archives of the precise versions of all of the code and data associated with the paper. The generic means to access other versions of the code and data as well as the licence of the code should also be explained. The licence should conform to the Open Source Definition¹⁶. Suitable licences¹⁷ are for example GPL¹⁸ or MIT¹⁹.

2. Where the authors cannot, for reasons beyond their control, publicly archive part or all of the code and data associated with a paper, they must clearly state the restrictions. They must also provide confidential access to the code and data for the editor and reviewers in order to enable peer review. The arrangements for this access must not compromise the anonymity of the reviewers. All manuscripts which do not make code and data available at this level are to be rejected. Where only part of the code or data is subject to these restrictions, the remaining code and/or data must still be publicly archived. In particular, authors must make every endeavour to publish any code whose development is described in the manuscript.

Code and data access must be provided at the time that the discussion paper is submitted. Embargoes, whether pending acceptance or for a defined period, are not acceptable.

A2 Scope

The code and data associated with a paper which are subject to the above requirements include, depending on the paper type, the following:

1. the source code for the complete model or module or other coded product described in the paper (must be provided for model description, development and technical, and methods for assessment paper types);

2. the manual and any other model documentation (applies to model description, development and technical, and methods for assessment, to the extent the editor considers applicable);

3. all configuration files, boundary conditions, and input data (must be provided for experiment description papers and any other papers in which results from model runs are reported);

4. data sets for forcing of models or comparison with model output (must be provided for papers describing such data sets or for papers in which model output are compared with such data);

5. preprocessing, run control and postprocessing scripts covering every data processing action for all the results reported in the paper (applies for all papers, to the extent the editor considers applicable).

In every case, the citation from the paper must identify the exact version of the code and/or data used.

Although the code and data will not be reviewed formally, the editor and reviewers are free to make general comments on any code or data, if they so wish. During the review process, the ease of model download, compilation, and running of test cases may be assessed.

A3 Archive standards

A frozen version of the code and data as developed in the paper must be archived. Usually, a third-party archive is preferable. In some cases, such as when the code is a fragment from a larger model, authors may include the code in the supplement to the paper. Third-party archives must have the following:

1. institutional support providing reasonable confidence that the material will remain available for many years/decades

2. mechanisms preventing the depositor of the material from unilaterally removing it from the archive

3. mechanisms for identifying the precise version of the material referred to in a persistent way. This will usually be a DOI.

Where code and data change during the revision process of the manuscript, the updated versions must also be archived. Authors must take care that the results in revised manuscripts are correctly associated with the corresponding archived data (with different DOIs referenced in the submitted and final manuscripts in cases where data have changed).

Many GMD authors find Zenodo²⁰ a suitable archival location. Zenodo's GitHub integration²¹ makes archiving particularly easy for the large proportion of authors who manage their code using Git. Authors who need to archive a single documentation file, such as a technical report, may find the arXiv suitable²². Authors whose data are too large to be archived at Zenodo will need to identify a suitable alternative. Appropriate choices may depend on the topic of the paper, the funder of the research, and the country where the research was conducted. One of the repositories listed by Springer Nature ²³, PLOS²⁴ or ESSD²⁵ may be suitable. In any case, the requirements above must be satisfied.

Project or institution websites and online revision control sites such as GitHub²⁶, GitLab²⁷ or Bitbucket²⁸ are made for code development but not suitable for archiving frozen code versions. Authors are encouraged to provide links to a website or revision control system as a preferred download location, so long as this is in addition to, and not instead of, the citation of an archive.

A4 Template for code and data availability section

The following code and data availability section meets the requirements of this policy for papers focussed on development of models or development of methods for assessment of models. Other wordings are, of course, possible so long as the required information is all present. For larger models it is very helpful if authors can identify the location of the main parts of the code that are discussed in the manuscript. For experiment description papers, evaluation papers, and some technical and development papers where details for a variety of different data sets or models are required, the section will be considerably longer.

The current version of model is available from the project website: url under the licence name licence. The exact version of the model used to produce the results used in this paper is archived on Zenodo (citation), as are input data and scripts to run the model and produce the plots for all the simulations presented in this paper (citation).

In line with the FORCE11 Joint Declaration of Data Citation Principles, the data citations should appear in the bibliography and be referenced in the text in the same way as other publications (Martone, 2014).

B1 Model description papers

Model description papers are comprehensive descriptions of numerical models which fall within the scope of GMD. The papers should be detailed, complete, rigorous, and accessible to a wide community of geoscientists. In addition to complete models, this type of paper may also describe model components and modules, as well as frameworks and utility tools used to build practical modelling systems, such as coupling frameworks or other software toolboxes with a geoscientific application. The GMD definition of a numerical model is generous, including statistical models, models derived from data (whether model output or observational data), spreadsheet-based models, box models, 1-dimensional models, through to multi-dimension mechanistic models.

• The main paper must give the model name and version number (or other unique identifier) in the title.

• The publication should consist of three parts: the main paper, a user manual, and the source code, ideally supported by some summary outputs from test case simulations.

• The main paper should describe both the underlying scientific basis and purpose of the model and overview the numerical solutions employed. The scientific goal is reproducibility: ideally, the description should be sufficiently detailed to in principle allow for the re-implementation of the model by others, so all technical details which could substantially affect the numerical output should be described. Any non-peer-reviewed literature on which the publication rests should be either made available on a persistent public archive, with a unique identifier, or uploaded as supplementary information.

• The model web page URL, the hardware and software requirements and the licence information should be given in the text. If papers are describing subsequent development to a paper already published in GMD, authors should request them to be electronically linked to the previous version(s) in a special issue, and an overview web page will be created.

• The model description should be contextualised appropriately. For example, the inclusion of discussion of the scope of applicability and limitations of the approach adopted is expected.

• Examples of model output should be provided, with evaluation against standard benchmarks, observations, and/or other model output included as appropriate. In this respect, authors are expected to distinguish between verification (checking that the chosen equations are solved correctly) and evaluation (assessing whether the model is a good representation of the real system). Sufficient verification and evaluation must be included to show that the model is fit for purpose and works as expected. Where evaluation is very extensive, a separate paper focussed solely on this aspect may be submitted.

• Code must be published on a persistent public archive with a unique identifier for the exact model version described in the paper or uploaded to the supplement, unless this is impossible for reasons beyond the control of authors. All papers must include a section, at the end of the paper, entitled “Code availability”. Here, either instructions for obtaining the code, or the reasons why the code is not available should be clearly stated. For established models, there may be an existing means of accessing the code through a particular system. In this case, there must exist a means of permanently accessing the precise model version described in the paper. Making code available through personal websites or via email contact to the authors is not sufficient. After the paper is accepted the model archive should be updated to include a link to the GMD paper.

• When code cannot be made public, topical editors and reviewers must still be given access to the model code.

• Although the source code and user manual will not be reviewed formally, the editors and reviewers are free to make general comments on the code if they so wish. During the review process, the ease of model download, compilation and running of test cases may be assessed.

B2 Development and technical papers

These papers describe technical developments relating to model improvements such as the speed or accuracy of numerical integration schemes as well as new parameterisations for processes represented in modules. Also included are papers relating to technical aspects of running models and the reproducibility of results, e.g. assessments of their performance with different compilers, or under different computer architectures. In addition, papers focussing on data assimilation are welcome. Development and technical papers usually include a significant amount of evaluation against standard benchmarks, observations, and/or other model output as appropriate.

In the case where new code is described in the paper, this is subject to the same availability requirements as for complete model descriptions. The code should be made available, and a model availability paragraph must be included.

If the model development relates to a single model, then the model name and the version number must be included in the title of the paper. If the main intention of an article is to make a general (i.e. model independent) statement about the usefulness of a new development, but the usefulness is shown with the help of one specific model, the model name and version number must be stated in the title. The title could have a form such as, “Title outlining amazing generic advance: a case study with Model XXX (version Y)”.

B3 Methods for assessment of models

Methods for assessment of models include work on developing new metrics for assessing model performance and novel ways of comparing model results with observational data. Also included are discussions of novel methods for data analysis, visualisation with relevance to geoscientific modelling, or the application of existing techniques to this field. These papers may also be theoretical, in which case an example implementation should be provided as supplementary information. They may also be based on the description of a fully fledged software tool.

The process of analysing model output for comparison with data may involve algorithms similar to those implemented in complex numerical models. In these cases, model output is input to another model in order to produce output comparable to observed quantities. Papers describing these algorithms may be submitted as either methods for model assessment or model description papers.

Descriptions of software tools are subject to the same criteria as model descriptions (name and version must be identified in the title, code must be supplied for the peer-review process, etc.), and a code availability paragraph must be included in the manuscript.

B4 Model experiment description papers

Model experiment description papers contain descriptions of standard experiments for a particular type of model, such as might be used in a MIP (model inter-comparison project). Configurations and overview results of individual models can also be included as well as descriptions of the methodology of experimental procedures such as ensemble generation. Such papers should include the discussion of why particular choices were made in the experiment design and sample model output. In the case of papers describing MIPs, they should explain any specific project protocols, should highlight differences in the application of the protocol by the different groups, and should include sufficient descriptions/figures of model results to give an overview of the project. For model experiment description papers, similar version control criteria apply as to model description papers: the experiment protocol should be given a version number; boundary conditions should be given a version number; a data availability paragraph must be included in the manuscript; and links to the GMD paper should be included on the experiment website. Since the primary purpose of these papers is to make experiments accessible to the community, all input data required to perform the experiments must be made publicly available.

Papers describing data sets designed for the support and evaluation of model simulations are within scope and included in this paper type. These data sets may be syntheses of data which have been published elsewhere. The data sets must also be made available, and any code used to create the syntheses should also be made available.

B5 Model evaluation papers

Model evaluation is an important component of most GMD papers. Model development papers in particular often include a large proportion of evaluation. Typically, this comprises a comparison of the performance of different model configurations or parameterisations. In some cases, the evaluation is sufficiently substantial that a stand-alone paper is required. In this case it is required that the model, model development, or model experiment has already been described in another paper (or that the description is also under review). The model name and version number should be identified in the title. The authors must provide the citation of the description paper in the evaluation manuscript itself and also in the letter to the editor when submitting an evaluation manuscript. If the description is in GMD, then there is the possibility of linking the papers, either in the form of a companion paper (e.g. Part 1 and Part 2) or as part of a special issue devoted to a particular model or experiment. Preprocessing, run control and postprocessing scripts covering every data processing action for all the results reported in the paper should be provided for evaluation papers.

It is, however, common for pure evaluation papers to contain substantial conclusions about geoscience rather than about models, and such papers are not suitable for submission to GMD. These are more likely to reach the appropriate audience in those EGU journals which publish scientific results related to the GMD subject areas.

B6 Review and perspective papers

Review and perspective papers summarise the status of knowledge and outline future directions of research within the scope of the journal.

Before preparing and submitting a review article, please contact the executive editors. A code and/or data availability section must be included. By default, the code and data availability requirements for models, experiments, code and data discussed in review papers are the same as for the other paper types, but in some cases deviations from this standard may be appropriate (for example, authors may need to discuss some code or data from external sources, for which they have no means of gaining or granting access). This should be discussed with the executive editors prior to submission of the paper.

B7 Corrigenda

Corrigenda correct errors in preceding papers. The manuscript title is as follows: Corrigendum to “TITLE” published in JOURNAL, VOLUME, PAGES, YEAR. Please note that corrigenda are only possible for final revised journal papers and not for the corresponding discussion paper. Corrigenda should only be used for correcting errors in the papers and not for those occurring in the model development being described.