The CMIP6 documentation process described in these pages is also explained in a series of short screencast videos:
These videos are also available in the Earth System Documentation YouTube channel.
Screencast transcripts
1. ES-DOC overview
Welcome to the overview screencast about the ES-DOC documentation for CMIP6. In these screencasts we describe the steps to produce the ES-DOC documentation about the CMIP6 process, they each start here, on the CMIP6 pages of the ES-DOC website.
Our documentation covers the four stages from the design of projects through to setting up models and running simulations and finally to publishing data on the Earth System Grid Federation.
The first stage involves the description of MIPs, that’s these projects, and Experiments, gathering Party information about who was involved and how to contact them, and Citations which give references to the scientific literature.
Then we collect information from modelling groups about their models and how those models have been set up to conform to the requirements of the CMIP6 experiments.
ES-DOC also collects information from the modelling groups about the machines that they used to run CMIP6 simulations and the machine’s performance, such as the number of simulated years per real time day.
Finally, ensemble and simulation descriptions will be auto-generated by ES-DOC from the CMIP6 data that is submitted to the ESGF archive. However we’re still going to need modelling groups to document the differences between simulations on ensemble axes.
You can find out more about the ES-DOC documentation for CMIP6 here on our CMIP6 pages of the ES-DOC website. Also these screencasts will show you how to find our CMIP6 documentation and give you an overview of the information that you’ll find there.
If you have any questions about the information presented in these screencasts or that’s on our web pages or in our documentation you can contact us from the email address on our contact page: support@es-doc.org.
2. MIPs and Experiments
Welcome to the ES-DOC screencast about our documentation for the CMIP6 MIPs and their experiments.
The experiment documentation describes the motivation for the experiments and formalises the requirements for models running them. You can find out about how we built the database of experiment documents on our experiment page and you can view the database via the Published Documentation link.
We see here a list of CMIP6 documentation for each of the MIPs. As an example let’s take a look at DAMIP, the Detection Attribution Model Intercomparison Project.
Our documentation starts with some high level information about this MIP.
There’s a description and some information about why this MIP is important, the rationale. We also see a list of all the experiments that are defined by this MIP, they are listed by tier, tier 1 being the highest priority. Finally there’s a list of experiments that are required by this MIP but are not themselves governed by the MIP, in this case the pre-industrial control, the historical and the ssp245 scenario.
In addition there are citations that tell you information about this MIP and there’s also contact information for the principal investigators.
So let’s take a look at one of the DAMIP experiments, hist-nat.
hist-nat is a historical experiment with natural-only forcing.
Just like the MIP documentation this experiment documentation begins with high level information that includes a description and a rationale. We also provide context for this experiment in terms of its relationship to the other experiments within CMIP6.
We then see a list of each of the requirements of the experiment.
These begin with a temporal constraint with information about how long the simulations need to run, in this case for 171 years from the beginning of 1850 until the first of January 2021. There’s an ensemble requirement with information about how many simulations needed for this experiment and also information about the model configuration.
What follows are a list of the forcing constraints for this experiment.
Given that the simulations for this experiment begin in 1850 and end in 2021 so the natural forcing requires both historical and future elements for the volcanic and solar forcing. As well as this solar forcing and volcanic forcing the experiment also requires that greenhouse gas forcing be set to pre-industrial levels, as is tropospheric forcings from aerosols and also land use.
We use these forcing constraints as a framework to collect information from the modelling groups about what they did to their models to conform to the demands of each of these requirements.
Finally there are citations, these provide background information about the design of the experiment and also information about forcing datasets. Finally there’s a list of responsible parties, that is, the people who designed the experiment.
If you find you have any queries whilst you’re viewing our documentation you can navigate back to the es-doc web pages from the es-doc logo at the top of the pages. From there it is just a simple step to our contact page where you’ll find our support email address.
3. ES-DOC Models
Welcome to the ES-DOC screencast about our CMIP6 model documentation.
We used the CMIP5 model documentation as a starting point and consulted climate modellers with diverse realm expertise to update the standard set of information that will be collected about each of the CMIP6 models. Mappings between the CMIP5 and CMIP6 model description databases allows ES-DOC to pre-populate some CMIP6 model documentation with information that was collected for CMIP5, should a modelling group decide to do so, thus reducing the amount of work needed.
The information that we collect about the CMIP6 models are recorded in specialisation files which you can find under our Models menu.
At the bottom of the page you’ll find a table with links to the specialisation information for each of the CMIP6 realms. As an example let’s take a look at the ocean specialisation.
We see the list of key properties for the ocean component and details about the kind of information that will be collected from the modelling groups about each property.
We can find out which process will be included in the ocean realm via the processes box. By selecting one of the processes, in this case lateral physics, we can see details about the information that will be collected about it.
The depth of information we collect has been deliberately limited, with a focus on scientific descriptions rather than describing software details.
We also provide a subset of the complete realm description in the form of a short table.
The short table which you’ll find at the top of each of these pages lists the model realm characteristics that should be used to describe models in the conventional literature, as recommended by WGCM (Working Group on Coupled Modelling of the World Climate Research Programme).
In the case of lateral physics the short table contains a subset of information about the representation of ocean eddies, momentum and tracers.
As well as realm specific information, ES-DOC also collects top level information about each of the CMIP6 Models. So if we go back to the ES-DOC tab we can find our way to the top level information.
At this top level you can find overview information about the model as a whole.
There’s information such as the model genealogy, the code environment and the coupling framework. You can also find information such as about any tuning that needs to be applied and how the model handles properties that need to be conserved.
We’ll tell you about how all this information is going to be collected from modelling groups in a separate screencast.
If you have any queries whilst you’re viewing our documentation you can navigate back to the es-doc web pages from the logo at the top. From here it’s just a simple step to our contact page where you’ll find our support email address.
4. ES-DOC Conformances
Welcome to the ES-DOC screencast about our conformance documentation for CMIP6.
Conformances are closely linked to the experiment descriptions, we use conformances to discover what was done to the models to conform to the demands of each experiment when running the CMIP6 simulations.
Many experiments within MIPs are very similar to each other, they often share many of the same requirements so generally speaking it is only necessary to state once how a requirement was conformed to regardless of how many different experiments use that requirement.
For example, the requirement which specifies pre-industrial carbon dioxide concentration is widely re-used across many experiments and many MIPs, but the way a model is configured for this is likely to be the same in all cases so it only needs to be described once.
You can find information about conformances alongside simulations under the ensembles tab here on our CMIP6 pages.
A conformance description has three components:
- First most crucially, whether or not the requirement was met.
- How any input datasets were modified so they could be used by the model.
- We allow modelling groups to tell us about any additional information to do with a conformance. It’s also possible for the MIP teams to mandate that modelling groups provide additional information about specific conformances.
The diagram at the bottom of the page helps us understand how this conformance information will be collected from modelling groups.
ES-DOC will initially provide the modelling groups with spreadsheets to record the default conformances for each experimental requirement. Subsequent spreadsheets will be provided to override default conformance descriptions in the cases where groups used have used a particular conformance solution for a specific model and experiment combination. ES-DOC will then harvest the conformance information into our database.
A video guide about entering conformance information will be available soon from ES-DOC.
If you have any queries about any of the information presented here you can contact us via our support email address on our contact page.
5. ES-DOC Interacting with scientists (Models)
Welcome to the ES-DOC screencast about interacting with the scientists in your institution. This screencast will show you where to find information about using ES-DOC documentation tools and point you to resources to help with gathering information about your models from the earth system modellers in your institution. The intended audience for this screencast are our ES-DOC liaison officers, though any interested parties are likely to find it of use.
You’ll find information about our software tools via the ES-DOC home page. The es-doc logo on banner at the top all the pages on our website will take you to the home page. From here the software tools can be found under the “Technical” tab and from there the “How-To” tab will direct you to our information aimed at the ES-DOC liaisons.
A good place to start is the ES-DOC liaison checklist, this page has information and links which describe in detail how to create CMIP6 documentation about your models.
We manage our documentation using GitHub, there are GitHub repositories for each of the institutions generating model data for CMIP6. Clear instructions about how to access and use your institute’s GitHub repository can be found here on the checklist.
For now, let’s take a look at the resources you’ll find in the GitHub repos. You’ll see a list repositories, one for each institution, I’m going to select MIROC for this example. Here you’ll find a CMIP6 folder, there may also be a CMIP5. Under “CMIP6” select models and you’ll see a list of each of your institution’s models that we expect to be producing data for CMIP6.
Choose a model and you’ll see a list of xlsx files, one for each of the realms that the model simulates.
Let’s take a look at the ocean. Here you’ll find a link to an xlsx file. The realm spreadsheets are generated from the realm specialisation files (which were covered in a previous screencast). We expect you to use the spreadsheets as the primary way to enter information about your models. In this ocean example you can see a list of topics that are included in this realm and there is a separate tab to enter information about each one.
Here we see the lateral physics spreadsheet. There’s place to enter information about different components. But if presenting your modellers with detailed spreadsheets is going to make life tricky, or create problems with version control you can use our pdf option to collect information.
The pdf view of the realm specialisations can be found alongside the list of realm spreadsheets for your model. There is a pdf view for each of the realms that your model simulates. As an example, let’s take a look at the ocean. You can download and share the pdf files with the modellers in your institution and use them to collect information about each of the realms your model simulates. The pdf files indicate the kind of input that is required, whether that be text, a user defined list, or to choose one or more options from a predefined list.
If you have any queries about how to complete your documentation please send a query to our support email address. You’ll find that back on the contact link of our es-doc pages.