From 044061a98b2d17455850cebda010f4e7902bab56 Mon Sep 17 00:00:00 2001 From: Aidan Heerdegen Date: Thu, 21 Mar 2024 15:10:41 +1100 Subject: [PATCH] Incorporating review comments --- docs/models/run-a-model/run-access-om.md | 33 +++++++++++++----------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/docs/models/run-a-model/run-access-om.md b/docs/models/run-a-model/run-access-om.md index 1ad381552..b72168fd1 100644 --- a/docs/models/run-a-model/run-access-om.md +++ b/docs/models/run-a-model/run-access-om.md @@ -101,7 +101,7 @@ The general layout of a `payu`-supported model run consists of two main director - The **laboratory** directory, where all the model components reside. For {{ model }}, it is typically `/scratch/$PROJECT/$USER/access-om2`. -- The **control** directory, where the model configuration resides and from where the model is run (in this example, the cloned directory `~/access-om/1deg_jra55_ryf`). +- The **control directory** contains the model configuration and serves as the execution directory for running the model (in this example, the cloned directory `~/access-om/1deg_jra55_ryf`). This separates the small text configuration files from the larger binary outputs and inputs. In this way, the _control_ directory can be in the `$HOME` directory (as it is the only filesystem actively backed-up on _Gadi_). The quotas for `$HOME` are low and strict, which limits what can be stored there, so it is not suitable for larger files. @@ -128,27 +128,27 @@ The main subdirectories of interest are: ### Run configuration -To run an {{ model }} configuration: +To run a configuration: - payu run -f + payu run This will submit a single job to the queue with a run length of `restart_period`. `restart_period` is defined in the `accessom2.nml` file in the _control_ directory. !!! note - The `-f` option ensures that `payu` will run even if there is an existing non-empty `work` directory created from a previous failed run or from running `payu setup`. + You can add the `-f` option to `payu run` and it will run even if there is an existing non-empty `work` directory created from a previous failed run or from running `payu setup`. ### Run configuration multiple times -If you want to run an {{ model }} configuration multiple times automatically use the option `-n`: +If you want to run a configuration multiple times automatically use the option `-n`: - payu run -f -n + payu run -n This will run `number-of-runs` times with a total length of `restart_period * number-of-runs`, where `restart_period` is the length of each model run. For example, to run a configuration for a total of 50 years with `restart_period` of 5 years the `number-of-runs` should be set to `10`: - payu run -f -n 10 + payu run -n 10 !!! note @@ -184,9 +184,12 @@ _S_ indicates the status of your run, where: - _Q_ → Job waiting in the queue to start - _R_ → Job running - _E_ → Job ending +- _H_ → Job on hold If there are no jobs listed with your `jobname` (or if no job is listed), your run either successfully completed or was terminated due to an error. +A job can be on hold for a number of reasons, see the [NCI documentation for more information](https://opus.nci.org.au/display/Help/FAQ+1%3A+Why+My+Jobs+are+NOT+Running). + ### PBS output files When the model completes PBS writes the standard outout and error streams to two files into the _control_ directory: `jobname.o` and `jobname.e` respectively. This is terminal output that isn't otherwise redirected into model log files. @@ -199,13 +202,13 @@ If you want to manually terminate a run, you can do so by executing: qdel job-ID -Which will kill the current job without waiting for it to complete. If you have used the `-n` option, but decide you no longer wish to keep running after the current process completes, you can create a file called `stop_run` in the _control_ directory, and this will prevent `payu` from submitting another job. +Which will kill the current job without waiting for it to complete. If you have used the `-n` option ( e.g., `payu run -n`), but subsequently decide not to keep running after the current process completes, you can create a file called `stop_run` in the _control_ directory, and this will prevent `payu` from submitting another job. ### Error and output log files While the model is running, _payu_ saves the model standard output and standard error in the `access-om2.out` and `access-om2.err` log files in the _control_ directory. You can examine the contents of these files to check on the status of a run as it progresses. -At the end of a successful run these log files are archived. If they remain in the _control_ directory after the PBS job for a run has completed this is an indication the run has failed. +At the end of a successful run these log files are archived to the `archive` directory and will not be found in the _control_ directory. If they remain in the _control_ directory after the PBS job for a run has completed this is an indication the run has failed. ### Did the model run correctly? @@ -247,11 +250,11 @@ For a complete documentation on how to use this framework, check the [Model Diag If `payu` doesn't run correctly for some reason a good first step step, from within the _control_ directory, is to run: - payu setup -f + payu setup This will prepare the model run: create the ephemeral `work` directory based on the experiment configuration, generate manifests and report some useful information to the user, such as the location of the _laboratory_ where the `work` and `archive` directories are located. -payu setup -f +payu setup laboratory path: /scratch/$PROJECT/$USER/access-om2 binary path: /scratch/$PROJECT/$USER/access-om2/bin input path: /scratch/$PROJECT/$USER/access-om2/input @@ -291,9 +294,9 @@ The `config.yaml` file located in the _control_ directory, is the _Master Config ### Change run length -One of the most common changes is to how long the model runs. For example it is common when debugging changes to a model to want to reduce the run length to reduce the amount of resources wasted and get faster feedback on changes. +One of the most common changes is to adjust the duration of the model run. For example when debugging changes to a model, it is common to reduce the run length to minimise resource consumption and return faster feedback on changes. -To change the run length, edit the `restart_period` field in the `&date_manager_nml` section of the `~/access-om/1deg_jra55_iaf/accessom2.nml` file: +To change the run length, edit the `restart_period` field in the `&date_manager_nml` section of the `~/access-om/1deg_jra55_ryf/accessom2.nml` file: &date_manager_nml forcing_start_date = '1958-01-01T00:00:00' @@ -394,7 +397,7 @@ The `name` field here is not actually used for the configuration run so you can This section specifies the submodels and configuration options required to execute the model correctly. -Each submodel contains additional configuration options that are read in when the submodel is running. These options are specified in the subfolder of the _control_ directory, whose name matches the submodel's _name_ (e.g., configuration options for the `ocean` submodel are in the `~/access-om/1deg_jra55_iaf/ocean` directory). +Each submodel contains additional configuration options that are read in when the submodel is running. These options are specified in the subfolder of the _control_ directory, whose name matches the submodel's _name_ (e.g., configuration options for the `ocean` submodel are in the `~/access-om/1deg_jra55_ryf/ocean` directory). ??? note "Expand for detail" @@ -507,7 +510,7 @@ To find out more about other configuration settings for the `config.yaml` file, ### Edit a single {{ model }} component configuration Each of the [model components] contains configuration options specific to that model that are read in when the model component is running. These options are typically useful to modify the physics used in the model, the input data or the model variables saved in the output files. -These configuration options are are specified in files in a subfolder of the _control_ directory, named the same as the submodel's name in the `config.yaml` `submodel` section (e.g., configuration options for the _ocean_ submodel are in the `~/access-om/1deg_jra55_iaf/ocean` directory). +These configuration options are are specified in files in a subfolder of the _control_ directory, named the same as the submodel's name in the `config.yaml` `submodel` section (e.g., configuration options for the _ocean_ submodel are in the `~/access-om/1deg_jra55_ryf/ocean` directory). To modify these options please refer to the User Guide of each individual model component. ---