CMIP6 > Models > Descriptions

The model description includes scientific domain descriptions, each of which can now be independently completed for a particular realm (e.g. ocean, atmosphere, etc.). Which means, for example, that the ocean realm experts only face describing the ocean properties and so on. It is no longer necessary for one person to marshal all the information.

Scientific domain descriptions include all the key properties which are likely to be compared between model domains (resolution, grid extent, tuning properties, processes simulated, …).

The depth of information has been deliberately limited, with a focus on scientific descriptions rather than describing software details, both to simplify the documentation task in terms of scope, but also to force more concise descriptions of what is actually described and hence allow for more salient comparisons among CIM documents by the modeling community and by scientists using CMIP6 output.

The scientific domain descriptions are defined for CMIP6 via “specialisation” files which define the properties needed to have a configured model.  They are organised following the eight official CMIP6 realms (as listed on the PCMDI github) – atmosphere, ocean, sea-ice, land surface, atmospheric chemistry, aerosols, ocean biogeochemistry, land ice – plus one top level specialisation.

Starting from the CMIP5 versions, the content of each realm has been updated by ES-DOC working with and initial small group of realm experts followed by a wider review by the CMIP community. The top-level specialisation captures properties such as the list of realms present in the model, tuning process, forcings, global conservation, and other global properties. For each realm, a standard short table is also provided to be included in model description papers, as per WGCM request.

This approach clearly separates the concepts encapsulated in the CIM from the specific activity it is used for (here CMIP6). Hence, using CIM2 for an another activity (e.g. CMIP7) will only require changing these specialisation files and not the underlying schema.

Documentation workflow

The model documentation workflow (Fig. below) starts at a modelling institute with the identification of an “ES-DOC officer”, who acts as a liaison between ES-DOC and the modelling group. The ES-DOC officer is responsible for choosing appropriate document creation tools and then working with the home modelling experts who will record the actual model details. The ES-DOC officer can be a modelling expert but this is not a requirement, and it is likely that different people will be the experts for different model realms (atmosphere, ocean, etc.).

Once the documentation for a model realm has been completed, it is published to the ES-DOC archive by the ES-DOC officer. This process triggers a request back to the realm expert for a quality control review. If any corrections are required, then the document is republished to the ES-DOC archive and will be generally available at for viewing, editing via the Questionnaire and comparison with other documents.

It is possible that, within a modelling group, some realms may take longer than others to be fully documented. By splitting the publishing up into individual realms, parts of the model which have been completely described can be made available without having to wait for other realms which may not have been finished.


Figure. Model documentation workflow, outlining institute (i.e. modelling group) responsibilities and that of ES-DOC to jointly produce, publish and quality control the related CIM documents.