Skip to content

Commit 2c36319

Browse files
ccarougeccarouge
committed
Corrections from read through
1 parent c24f202 commit 2c36319

2 files changed

Lines changed: 53 additions & 44 deletions

File tree

‎docs/includes/payu.md‎

Lines changed: 45 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -48,27 +48,34 @@ A representation of the data organisation for _payu_ is given in the following d
4848
As shown in the diagram, the general layout of a _payu_-supported model run consists of two main directories:
4949

5050
- The _control_ directory contains the model configuration and is the directory from which the model run is started.
51-
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. If a model has only one model component, the files with the scientific options are located directly in the _control_ directory. If the model has several model components, the files are locate inside subfolders of the _control_ directory named according to the submodel's `name` specified in the `config.yaml` [`submodels` section](#submodels). To modify these options please refer to the configurations documentation of the respective model component, found on the [Run a Model][Run a Model] page for your chosen model.
52-
- The _laboratory_ directory contains all data from _payu_ experiments of the same model. By default, it is `/scratch/$PROJECT/$USER/<model_name>`. `$PROJECT` and `$USER` are environment variables on _Gadi_ that points to your [default project](/getting_started/set_up_nci_account/#change-default-project-on-gadi) and your username respectively.
53-
See the section on [modifying the PBS resources](#modify-pbs-resources) to learn how to change the _laboratory_ location.
51+
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 sub-directories if the model has several model components. The `submodels` section of the `config.yaml` file specifies the name of the submodels and of the sub-directories containing the pertinent files. To modify these options please refer to the configurations documentation of the respective model component.
52+
- The _laboratory_ directory contains all data from _payu_ experiments of the same model. By default, it is `/scratch/$PROJECT/$USER/<model_name>`. `$PROJECT` and `$USER` are environment variables on _Gadi_ that points to your [default project](/getting_started/set_up_nci_account/#change-default-project-on-gadi) and your username respectively. This location can be changed.
53+
<!--See the section on [modifying the PBS resources](#modify-pbs-resources) to learn how to change the _laboratory_ location. (Should the include be cut to allow adding this sentence and link?)-->
5454

55-
On _Gadi_, it is good practice to put experiment _control_ directories in your `$HOME` directory as this is the only filesystem that is actively backed-up. There is a 10GB limit for home directories, but the _control_ directory only contains text files and symlinks, and so uses relatively little space (<1MB). The _laboratory_ directory is on `/scratch` which is optimised for fast reading and writing of large data and where there is adequate space available for large model output.
55+
!!! tip
56+
57+
On _Gadi_, it is good practice to put experiment _control_ directories in your `$HOME` directory as this is the only filesystem that is actively backed-up. There is a 10GB limit for home directories, but the _control_ directory only contains text files and symlinks, and so uses relatively little space (<1MB). The _laboratory_ directory is on `/scratch` which is optimised for fast reading and writing of large data and where there is adequate space available for large model output.
58+
59+
If you decide to locate your _control_ directory under `/g/data`, be aware of [some complications](https://forum.access-hive.org.au/t/changing-project-codes-for-payu-control-directories-under-g-data/6566) linked to that choice.
5660

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

5963
- _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
6064
- _archive_ &rarr; for storing the output following each successful run. The output, log and restart files are automatically transferred from _work_ to _archive_ upon successful completion of runs.
6165

62-
Within each of the _work_ and _archive_ directories, _payu_ automatically creates a unique subdirectory for each experiment. Within each experiment sub-directory, the output and restart subfolders are called `outputXXX` and `restartXXX`, respectively, where _XXX_ is the run number starting from `000`. Model components are further separated into subdirectories within the output and restart directories.
63-
6466
The _archive_ and _work_ directories for an experiment are most easily accessed through the symbolic links created in the _control_ directory.
6567

6668
!!! warning
67-
Files on the `/scratch` drive, such as the _laboratory_ directory, might be deleted if not accessed for several days. All experiments which are to be kept should be moved to `/g/data/` by enabling the `sync` step in _payu_. To know more, refer to [Syncing output data](#syncing-output-data-to-long-term-storage).
69+
Files on the `/scratch` drive, such as the _laboratory_ directory, might be deleted if not accessed for several days. All experiments which are to be kept should be moved to `/g/data/` by enabling the `sync` step in _payu_.
70+
71+
##### Output and restart files organisation
6872

69-
### Error and output log files
73+
Within each of the _work_ and _archive_ directories, _payu_ automatically creates a unique subdirectory for each experiment. Within each experiment sub-directory, the output and restart subfolders are called `outputXXX` and `restartXXX`, respectively, where _XXX_ is the run number starting from `000`. Model components are further separated into subdirectories within the output and restart directories.
74+
75+
##### Error and output log files
76+
77+
**PBS output files**
7078

71-
#### PBS output files {: .no-toc }
7279
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.
7380

7481
These files usually contain logs about _payu_ tasks, and give an overview of the resources used by the job.<br>
@@ -78,12 +85,13 @@ To move these files to the _archive_ directory, use the following commmand:
7885
payu sweep
7986
```
8087

81-
#### Model log files {: .no-toc }
88+
**Model log files**
8289

8390
While the model is running, the standard output and error streams are saved to file in the _control_ directory. You can examine the contents of these log files to check on the status of a run as it progresses (or after a failed run has completed).
8491

8592
!!! warning
8693
At the end of a successful run, the model log files are archived to the _archive_ directory and will no longer be found in the _control_ directory. If they remain in the _control_ directory after the PBS job for a run has completed, it means the run has failed.
94+
8795
<!--end:about-->
8896

8997
## Prerequisites for _payu_
@@ -112,7 +120,7 @@ After joining the _vk83_ project, load the _payu_ module:
112120
module load payu
113121

114122
To check that _payu_ is available, run:
115-
ø
123+
116124
payu --version
117125
<!--end:access-payu-->
118126

@@ -295,36 +303,37 @@ _payu_ provides the [`payu status`](https://payu.readthedocs.io/en/stable/usage.
295303
Example output from `payu status` for a running simulation:
296304

297305
```
298-
========================================
299-
Run: 8
300-
Job ID: running_example.gadi-pbs
301-
Run ID: xxxx
302-
Stage: model-run
303-
Current Expt Time: 1950-10-01T00:00:00
304-
Exit Status: 0 (Success)
305-
Model Exit Code: 0 (Success)
306-
Output Log: /home/189/USER/expt.o100
307-
Error Log: /home/189/USER/expt.3100
308-
Job File: /scratch/\$PROJECT/USER/archive/expt-branch—6dhash/payu_jobs/8/run/running_example.gadi-pbs.json
309-
========================================
306+
========================================
307+
Run: 8
308+
Job ID: running_example.gadi-pbs
309+
Run ID: xxxx
310+
Stage: model-run
311+
Current Expt Time: 1950-10-01T00:00:00
312+
Exit Status: 0 (Success)
313+
Model Exit Code: 0 (Success)
314+
Output Log: /home/189/USER/expt.o100
315+
Error Log: /home/189/USER/expt.3100
316+
Job File: /scratch/\$PROJECT/USER/archive/expt-branch—6dhash/payu_jobs/8/run/running_example.gadi-pbs.json
317+
========================================
310318
```
311319

312320
Example output from `payu status` for an archived simulation:
321+
313322

314323
```
315-
========================================
316-
Run: 8
317-
Job ID: archive_example.gadi-pbs
318-
Run ID: xxxx
319-
Stage: archive
320-
Total Queue Time: 0h 1m 7s
321-
Model Finish Time: 1950-10-01T00:00:00
322-
Exit Status: 0 (Success)
323-
Model Exit Code: 0 (Success)
324-
Output Log: /home/189/USER/expt.o100
325-
Error Log: /home/189/USER/expt.3100
326-
Job File: /scratch/\$PROJECT/USER/archive/expt-branch—6dhash/payu_jobs/8/run/archive_example.gadi-pbs.json
327-
========================================
324+
========================================
325+
Run: 8
326+
Job ID: archive_example.gadi-pbs
327+
Run ID: xxxx
328+
Stage: archive
329+
Total Queue Time: 0h 1m 7s
330+
Model Finish Time: 1950-10-01T00:00:00
331+
Exit Status: 0 (Success)
332+
Model Exit Code: 0 (Success)
333+
Output Log: /home/189/USER/expt.o100
334+
Error Log: /home/189/USER/expt.3100
335+
Job File: /scratch/\$PROJECT/USER/archive/expt-branch—6dhash/payu_jobs/8/run/archive_example.gadi-pbs.json
336+
========================================
328337
```
329338

330339
To monitor the current queue time of a queued job, use `payu status --update`.

‎docs/models/run_a_model/run_access-esm.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -65,20 +65,19 @@ All {{model}} configurations are open source, licensed under [CC BY 4.0](https:/
6565

6666
## Workflow manager, _payu_
6767

68-
??? abstract "What is _payu_ and how are the simulation files organised by _payu_"
68+
??? info "What is _payu_ and how are the simulation files organised by _payu_"
6969
{%
7070
include-markdown "includes/payu.md"
7171
start="<!--start:about-->"
7272
end="<!--end:about-->"
7373
%}
7474
For {{model}}, the standard output is saved in the file `access.out` and the standard error in `access.err`.
7575

76-
??? info "Accessing _payu_"
77-
{%
78-
include-markdown "includes/payu.md"
79-
start="<!--start:access-payu-->"
80-
end="<!--end:access-payu-->"
81-
%}
76+
{%
77+
include-markdown "includes/payu.md"
78+
start="<!--start:access-payu-->"
79+
end="<!--end:access-payu-->"
80+
%}
8281

8382
----------------------------------------------------------------------------------------
8483

@@ -161,7 +160,8 @@ For a complete documentation on how to use this framework, check the [Model Diag
161160
%}
162161

163162
??? info "Change run length"
164-
### Change run length {: #runtime .no-toc }
163+
164+
### Change run length
165165

166166
One of the most common changes is to adjust the duration of the model run.<br> {{model}} simulations are split into smaller _run lengths_, each with the duration specified by the `runtime` settings in the `config.yaml` file:
167167

0 commit comments

Comments
 (0)