Rewrite how to run ACCESS-ESM1.5 according to feedback from user experience by ccarouge · Pull Request #1202 · ACCESS-NRI/ACCESS-Hive-Docs

ccarouge · 2026-05-13T06:44:40Z

Motivation

Following user's feedback from user experience events, it appears that:

it is impractical for people to swap between pages when learning to run a model. They become confused about what information is where and where to use it.
it is impractical for people to use very long pages, as it is very hard to find the information they need.

From us, we also have the requirement that we don't want to duplicate the same information on several pages, as it becomes difficult to manage and ensure all occurrences are kept up-to-date.

All these considerations have led the Hive Docs team to consider a reformatting of the Run a Model page. Here are the choices made:

keep the basic information for how to run ACCESS-ESM1.5 visible on the page
use collapsible admonitions for sections with additional information
use include-markdown to include information that is shared with other models. In ESM1.5 case, this is payu information. All information for payu will come from the includes/payu.md file.

Limitations / Difficulties coming from these choices:

the developer's work will be more difficult as the information is spread over 2 pages or more. The information in files used for include sections is not necessarily complete information without the information in the host page.
the reviewer's work will be more difficult as the text rendered on a page might be directly on this page or in an "include file"
include sections should not contain any relative link to a section in the host page, since we can't ensure all host pages will contain such a section. This might result in either less cross-referencing links or in smaller include sections with sentences for linking to sections on the host page directly.

Current status

This rewrite is using the payu.md page that was being developed for ESM1.6. The payu.md page has not yet been clean up of extra text, this is on purpose in case anything there is useful during the review process
Need to review the TOC on the ESM1.5 page: we may want to remove some sections from the TOC.

github-actions · 2026-05-14T00:20:52Z

PR Preview
🚀 Preview of PR head commit `26dbcf9` deployed to https://docs.access-hive.org.au/pr-previews/1202
2026-07-03 16:47 AEST
Preview generated through the Deploy to GitHub Pages workflow run 28643610391.

ccarouge · 2026-06-24T05:58:38Z

@paigem Here is (finally) a first version of ESM1.5 documentation with include bits and collapsible sections. I haven't read the whole page to make sure it is all coherent yet but I wanted to get your opinion on the balance between information directly on the page and in collapsible sections. I have tried to follow these principles:

basic info for Run the Model is directly on the page
examples are in collapsible sections (using the "abstract" admonition style)
more advance information is in collapsible sections (using the "info" admonition style)
one tip is in a collapsible, tip admonition

I'll continue working on it, reading the page, fixing details and cleaning up the payu.md page that is used for the include parts but let me know if you think the balance of information looks alright.

anton-seaice

Looks great @ccarouge - this should make it simpler long term!

anton-seaice · 2026-06-30T01:28:45Z

+When the model fails or completes a run, PBS writes the standard output and error streams to two files inside the _control_ directory: `<jobname>.o<job-ID>` and `<jobname>.e<job-ID>`, respectively.
+
+These files usually contain logs about _payu_ tasks, and give an overview of the resources used by the job.<br>
+To move these files to the _archive_ directory, use the following commmand:


Suggested change

When the model fails or completes a run, PBS writes the standard output and error streams to two files inside the _control_ directory: `<jobname>.o<job-ID>` and `<jobname>.e<job-ID>`, respectively.

These files usually contain logs about _payu_ tasks, and give an overview of the resources used by the job. 

To move these files to the _archive_ directory, use the following commmand:

When the model fails or completes a run, PBS writes the standard output and error streams to two files inside the _control_ directory: `<jobname>.o<job-ID>` and `<jobname>.e<job-ID>`, respectively. These files usually contain logs about _payu_ tasks, and give an overview of the resources used by the job. 

To move these files to the _archive_ directory, use the following commmand:

The formatting is a bit weird:

anton-seaice · 2026-06-30T01:30:28Z

+As shown in the diagram, the general layout of a _payu_-supported model run consists of two main directories:
+
+- The _control_ directory contains the model configuration and is the directory from which the model run is started.  
+  This directory contains information to manage the simulation and the scientific options that define the algorithms used in the model component or the diagnostics saved by the model component. The simulation is orchestrated from a main `config.yaml` file contained in this directory. The files specific to each model component are either located directly in the _control_ directory if the model has one model component, or in subdirectories if the model has several model components. The `submodels` section of the `config.yaml` file specifies the name of the submodels and of the subdirectories containing the pertinent files. To modify these options please refer to the configurations documentation of the respective model component.


This paragraph is a bit long/verbose. Can we break it up or use dot points or something ?

anton-seaice · 2026-06-30T01:31:20Z

-        <terminal-line data="input">payu --version</terminal-line>
-        <terminal-line lineDelay="1000">payu 1.1.6</terminal-line>
-    </terminal-window>
+??? info "What is _payu_ and how are the simulation files organised by _payu_"


Suggested change

??? info "What is _payu_ and how are the simulation files organised by _payu_"

??? info "What is _payu_ and how are simulation files organised by _payu_"

Is this heading going in all pages? Could is go in payu.md instead ?

anton-seaice · 2026-06-30T01:32:56Z


-All released {{ model }} configurations are available from the [{{ model }} configs]({{github_configs}}) GitHub repository.<br>
-Released configurations are tested and supported by ACCESS-NRI, as an adaptation of those originally developed by [CSIRO](https://www.csiro.au/en/research/environmental-impacts/climate-change/climate-science-centre) and [CLEX CMS](https://github.com/coecms/access-esm).
+Released configurations are tested and supported by ACCESS-NRI, as an adaptation of those originally developed by [CSIRO](https://www.csiro.au/en/research/environmental-impacts/climate-change/climate-science-centre) and [CLEX CMS](https://github.com/coecms/access-esm).<br>


Suggested change

Released configurations are tested and supported by ACCESS-NRI, as an adaptation of those originally developed by [CSIRO](https://www.csiro.au/en/research/environmental-impacts/climate-change/climate-science-centre) and [CLEX CMS](https://github.com/coecms/access-esm). 

Released configurations are tested and supported by ACCESS-NRI, and build upon those originally developed by [CSIRO](https://www.csiro.au/en/research/environmental-impacts/climate-change/climate-science-centre) and [CLEX CMS](https://github.com/coecms/access-esm).

I don't find that
format's very clearly:

Maybe   should insert some space afterwards ?

anton-seaice · 2026-06-30T01:37:41Z

+| CMIP6 Concentration-driven pre-industrial | release-preindustrial+concentrations |
+| CMIP6 Concentration-driven historical | release-historical+concentrations


If we are talking about CMIP6, then use piControl and historical I think?

These are answer changing to the published CMIP6 data, so do we need some clarifying language about what we mean by CMIP6 here ?

The change in answers comes from changes in the code or compilation, correct?

I would guess there's also runtime changes which have been answer changing, but am not really involved in esm1.5 so i don't know

I don't understand: "If we are talking about CMIP6, then use piControl and historical I think?" Do you mean instead of "concentration-driven pre-industrial" and "concentration-driven historical"? There were some emissions-driven runs done for CMIP6.

Do you mean instead of "concentration-driven pre-industrial" and "concentration-driven historical"?

Yes - exactly, if we are referring to explicit experiments, then use the CMIP name for them

anton-seaice · 2026-06-30T01:40:25Z

+### Get the model configuration
+
+<!--start:get-config-payu-->
+To get a local copy of a configuration, you need to:


Suggested change

To get a local copy of a configuration, you need to:

Before downloading (cloning) a local copy of a configuration, you need to:

anton-seaice · 2026-06-30T01:44:27Z

 ACCESS-NRI developed the [Model Live Diagnostics](/model_evaluation/evaluation_on_gadi/model_live_diagnostics) framework to check, monitor, visualise, and evaluate model behaviour and progress of ACCESS models currently running on _Gadi_.<br>
 For a complete documentation on how to use this framework, check the [Model Diagnostics documentation](https://med-live-diagnostics.readthedocs.io/en/latest/index.html).


Does this work? looks stale since 2024 ?

I was wondering about that, since it was on ESM1.5 and OM2 pages, I didn't remove it. Happy to remove though.

Feel free to argue it's not in scope (:

anton-seaice · 2026-06-30T01:46:45Z

+    To run the model for longer than the default run length, conduct multiple runs, see 
+    [Run an experiment](#run-an-experiment).
+
+    #### Understand _runtime_, _runspersub_, and _-n_ parameters {: id="multiple-runs"}


It's confusing to say that we don't recommend changing the run length, but oh, actually, here's how to change the run length ??

anton-seaice · 2026-06-30T01:48:06Z

+            days: 0
    ```
+
+    With the default configuration settings, the sea ice component of {{ model }} will produce restart files only at the end of each year. If valid restart files are required when running shorter simulations, the sea ice model     configuration should be modified so that restart files are produced at monthly frequencies. To do this, change the `dumpfreq = 'y'` setting to `dumpfreq = 'm'` in the `cice_in.nml` configuration file located in the `ice`     subdirectory of the _control_ directory.


Doesn't payu crash if you don't have a restart file from the end of the run ?

For cice it hangs onto the restart from the start of the run. It doesn't crash immediately, but I guess it would cause problems in subsequent runs

Why are you assuming that the instructions in the text would not produce a restart at the end of the run @anton-seaice ? Or are you asking for an additional warning about that?

It says If valid restart files are required when running shorter simulations, allowing for us not to require them if we wanted

Oh, I understood it as: if you just run a short simulation and don't care about continuation, then you don't care about the creation of restarts by your short simulation. I'll update the text.

anton-seaice · 2026-06-30T01:52:05Z

+<!--end:payu-restart-prune-->
+
+<!--start:payu-advance-options-->
+### _payu_ advance options


Suggested change

### _payu_ advance options

### _payu_ options for advanced users

blimlim

Thanks @ccarouge for putting this together. I really like the new structure, and don't have many suggested changes for the overall way its organised.

I haven't done too in depth of a review at the moment, but have added a few small comments on things that stood out to me.

blimlim · 2026-06-30T02:53:16Z

+
+Inside the _laboratory_ directory, there are two subdirectories of particular interest: 
+
+- _work_ &rarr; for temporary storage of files needed by the model while it runs. _payu_ creates and removes directories and files in this directory upon successful completion of runs. It is left untouched in case of error to facilitate the identification of the cause of the model failure


I'd read the current text as suggesting the work directory is created at the end of each run. Would something like this be a little more explicit

Suggested change

- _work_ → for temporary storage of files needed by the model while it runs. _payu_ creates and removes directories and files in this directory upon successful completion of runs. It is left untouched in case of error to facilitate the identification of the cause of the model failure

- _work_ → for temporary storage of files needed by the model while it runs. _payu_ creates this directory at the start of each run and removes it upon their successful completion. It is left untouched in case of error to facilitate the identification of the cause of the model failure

blimlim · 2026-06-30T03:42:26Z

+<!--end:get-config-payu-->
+
+<!--start:payu-clone-example-->
+For example, if you want to do a sensitivity experiment in {{model}} using the configuration {{config_example}}. You decide the following:


Just a very small thing. I think "sensitivity experiment" complicates the example, and it could be clearer omitting it:
"For example, if you want to clone the configuration {{config_example}} for {{model}}, ..."

blimlim · 2026-06-30T03:45:10Z

+    payu run -n <number-of-runs>
+
+This will run the configuration `number-of-runs` consecutive times for the configured run length. This way, the *total experiment length* will be `run-length * number-of-runs`. The `run-length` (i.e. the duration of each individual run) is defined in the configuration settings and its specification is model-dependent.
+For example, to run an experiment for a total of 50 years using a configuration with a 5-year _run length_, the `number-of-runs` should be set to `10`:


Related to @anton-seaice's comment here, since we strongly suggest leaving the run length as 1 year, it might be best to use a 1 year run length in this example.

blimlim · 2026-06-30T03:51:59Z

+<!--start:payu-PBS-resources-->
+### Modify PBS resources
+
+If the model has been altered and needs more time or memory to complete, or needs to be submitted under a different NCI project, you will need to modify the following options in the `config.yaml`:


Suggested change

If the model has been altered and needs more time or memory to complete, or needs to be submitted under a different NCI project, you will need to modify the following options in the `config.yaml`:

If the model has been altered and needs more time or memory to complete, you will need to modify the following options in the `config.yaml`:

blimlim · 2026-06-30T03:59:33Z

+
+This section tells _payu_ which driver to use for the main `model` configuration and the location of all `input` files that are common to all its model components.
+
+The `name` field, for the model section, is not actually used for the configuration run, so it can be safely ignored. The `name` field is used for submodels (see below).


I think the top level name option selects the payu driver. @Qian-HuiChen is that correct?

blimlim · 2026-06-30T04:04:04Z

 - **_MOSRS_ account**<br>
-    [MOSRS](https://code.metoffice.gov.uk) is a server run by the UKMO to support collaborative development with other partners organisations. MOSRS contains the source code and configurations for some model components in {{ model }} (e.g., the [UM](/models/model_components/atmosphere/#unified-model-um)).<br>
+    The [Met Office Science Repository Service (MOSRS)](https://code.metoffice.gov.uk) is a server run by the UK Met Office (UKMO) to support collaborative development with other partners organisations. MOSRS contains the source code and configurations for some model components in {{ model }} (e.g., the [UM](/models/model_components/atmosphere/#unified-model-um)).<br>
    To apply for a _MOSRS_ account, please contact your [local institutional sponsor](https://opus.nci.org.au/display/DAE/Prerequisites).


Are there any changes that need to go here with the updated process? We could add an includes/ukmo.md file so that prerequisites can be shared across the UM based models?

I have this open PR with updated MOSRS account instructions.
@ccarouge, the idea is to put these updated MOSRS instructions in an include file that can be used by "rose-cylc" and the "payu" instructions. I did a temporary fix in the ESM1.5 instructions to avoid confusion until the new ESM documentation is ready.

blimlim · 2026-06-30T04:16:20Z

+%}

-For example, if the required configuration is the co2 concentration driven pre-industrial configuration, then the branch to select is [`release-preindustrial+concentrations`](https://forum.access-hive.org.au/t/access-esm1-5-release-information/2352).
+??? abstract "Experiment example"


Suggested change

??? abstract "Experiment example"

??? abstract "Example: Cloning a configuration"

I think the "experiment example" could be made a little clearer that it's about cloning configurations. Not sure that my suggestion is the best though

Clarify instructions for specifying a custom restart path during experiment setup.

ccarouge force-pushed the ACCESS-ESM1.5-snippets branch 2 times, most recently from d0d207f to 3daa37a Compare May 13, 2026 06:49

ccarouge mentioned this pull request May 13, 2026

Testing of includes files #1197

Draft

ccarouge force-pushed the ACCESS-ESM1.5-snippets branch from 252fd18 to b8d41c2 Compare May 13, 2026 07:10

ccarouge force-pushed the ACCESS-ESM1.5-snippets branch from a788dae to 7f52ac0 Compare June 2, 2026 07:01

ccarouge changed the base branch from 978-General-how-to-use-Payu-Docs to development June 2, 2026 07:02

ccarouge force-pushed the ACCESS-ESM1.5-snippets branch from 02d22f8 to a89c91c Compare June 2, 2026 07:30

ccarouge force-pushed the ACCESS-ESM1.5-snippets branch 10 times, most recently from b4c8230 to c24f202 Compare June 24, 2026 05:54

ccarouge changed the title ~~Test snippets in ACCESS-ESM1.5 case~~ Rewrite how to run ACCESS-ESM1.5 according to feedback from user experience Jun 29, 2026

ccarouge force-pushed the ACCESS-ESM1.5-snippets branch 4 times, most recently from 2c36319 to 3e369ec Compare June 29, 2026 05:21

ccarouge requested review from anton-seaice and blimlim June 29, 2026 06:13

anton-seaice reviewed Jun 30, 2026

View reviewed changes

blimlim reviewed Jun 30, 2026

View reviewed changes

ccarouge mentioned this pull request Jul 1, 2026

Add AM3 Run-a-model Docs #1039

Open

Start general payu docs

f542616

ccarouge and others added 26 commits July 3, 2026 10:25

Update instructions for custom restart path in payu.md

822070d

Clarify instructions for specifying a custom restart path during experiment setup.

(#978) - responses to reviews

9640d0e

Replace diagram PNG with SVG

1e5507f

Test snippets in ACCESS-ESM1.5 case

5169eff

Test line continuation

0ef2adb

Try with include-markdown extension

48722fb

Fix include-markdown inclusion

34da000

Add more sections

8393876

Include files for "get the configuration" section

ae26e14

Try macros in terminal

449658f

Work on get a model configuration

5e109f3

Add testing the configuration

255d3ca

Give the URL to the config repo

6a28bca

Add run experiment

e1520d4

Add run_length info.

70e9e03

Change admonition type

25030ba

Add include for monitoring

758ea47

Move log file description with the file organisation for payu

bacd158

Remove redundant text

e0886ba

Add includes to Configuration modifications

6890412

To the end of the file

438ca83

Test configs_docs link

3aaa478

Final options in collapsible sections.

c87e457

More fix

430124d

Corrections from read through

b8abac2

Responses to reviews

299e6bd

ccarouge force-pushed the ACCESS-ESM1.5-snippets branch from f5a6a30 to 299e6bd Compare July 3, 2026 00:29

ccarouge added 3 commits July 3, 2026 10:37

Fix offsets in payu-about section

717db31

Move config vs exp to different include file.

281a645

Various formatting and other changes

26dbcf9

	??? info "What is _payu_ and how are the simulation files organised by _payu_"
	??? info "What is _payu_ and how are simulation files organised by _payu_"

	Released configurations are tested and supported by ACCESS-NRI, as an adaptation of those originally developed by [CSIRO](https://www.csiro.au/en/research/environmental-impacts/climate-change/climate-science-centre) and [CLEX CMS](https://github.com/coecms/access-esm).<br>
	Released configurations are tested and supported by ACCESS-NRI, and build upon those originally developed by [CSIRO](https://www.csiro.au/en/research/environmental-impacts/climate-change/climate-science-centre) and [CLEX CMS](https://github.com/coecms/access-esm).<br>

		\| CMIP6 Concentration-driven pre-industrial \| release-preindustrial+concentrations \|
		\| CMIP6 Concentration-driven historical \| release-historical+concentrations

	To get a local copy of a configuration, you need to:
	Before downloading (cloning) a local copy of a configuration, you need to:

		ACCESS-NRI developed the [Model Live Diagnostics](/model_evaluation/evaluation_on_gadi/model_live_diagnostics) framework to check, monitor, visualise, and evaluate model behaviour and progress of ACCESS models currently running on _Gadi_.<br>
		For a complete documentation on how to use this framework, check the [Model Diagnostics documentation](https://med-live-diagnostics.readthedocs.io/en/latest/index.html).

	### _payu_ advance options
	### _payu_ options for advanced users


		Inside the _laboratory_ directory, there are two subdirectories of particular interest:

		- _work_ → for temporary storage of files needed by the model while it runs. _payu_ creates and removes directories and files in this directory upon successful completion of runs. It is left untouched in case of error to facilitate the identification of the cause of the model failure

	If the model has been altered and needs more time or memory to complete, or needs to be submitted under a different NCI project, you will need to modify the following options in the `config.yaml`:
	If the model has been altered and needs more time or memory to complete, you will need to modify the following options in the `config.yaml`:


		This section tells _payu_ which driver to use for the main `model` configuration and the location of all `input` files that are common to all its model components.

		The `name` field, for the model section, is not actually used for the configuration run, so it can be safely ignored. The `name` field is used for submodels (see below).

	??? abstract "Experiment example"
	??? abstract "Example: Cloning a configuration"

Uh oh!

Conversation

ccarouge commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Current status

Uh oh!

github-actions Bot commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ccarouge commented Jun 24, 2026

Uh oh!

anton-seaice left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anton-seaice Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

blimlim left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ccarouge commented May 13, 2026 •

edited

Loading

github-actions Bot commented May 14, 2026 •

edited

Loading

anton-seaice Jul 1, 2026 •

edited

Loading