From 1d1aa8e1a2bb43f1eec3123fd3963071e4d8744b Mon Sep 17 00:00:00 2001 From: Claire Carouge Date: Mon, 11 Sep 2023 17:10:34 +1000 Subject: [PATCH 1/5] #135 - Alternate config_options style --- docs/user_guide/config_options.md | 180 ++++++++++++++++++++---------- 1 file changed, 123 insertions(+), 57 deletions(-) diff --git a/docs/user_guide/config_options.md b/docs/user_guide/config_options.md index a80cd967..9d0fe83c 100644 --- a/docs/user_guide/config_options.md +++ b/docs/user_guide/config_options.md @@ -35,101 +35,124 @@ The different running modes of `benchcab` are solely dependent on the options us ## Technical options -### `project` +### project -: NCI project ID to charge the simulations to. +: **Default:** _required option, no default_. :octicons-dash-24: NCI project ID to charge the simulations to. -### `modules` +``` yaml -: NCI modules to use for compiling CABLE +project: nf33 -### `fluxsite` -: Contains settings specific to fluxsite tests. -: This key is **optional**. Default settings for the fluxsite tests will be used if it is not present - -#### `pbs` +``` -: Contains settings specific to the PBS scheduler at NCI for the PBS script running the CABLE simulations at FLUXNET sites and the bitwise comparison for these simulations. -: This key is **optional**. Default values for the PBS settings will apply if it is not specified. +### modules -##### `ncpus` +: **Default:** _required option, no default_. :octicons-dash-24: NCI modules to use for compiling CABLE -: The number of CPU cores to allocate for the PBS job, i.e. the `-l ncpus=<4>` PBS flag (see [PBS Directives Explained][nci-pbs-directives]). -: This key is **optional** and can be omitted from the config file. By default `ncpus` is set to `18`. +``` yaml -##### `mem` +modules: [ + intel-compiler/2021.1.1, + netcdf/4.7.4, + openmpi/4.1.0 +] -: The total memory limit for the PBS job, i.e. the `-l mem=<10GB>` PBS flag (see [PBS Directives Explained][nci-pbs-directives]). -: This key is **optional** and can be omitted from the config file. By default `mem` is set to `30GB`. +``` -##### `walltime` +### fluxsite +Contains settings specific to fluxsite tests. -: The wall clock time limit for the PBS job, i.e. `-l walltime=` PBS flag (see [PBS Directives Explained][nci-pbs-directives]). -: This key is **optional** and can be omitted from the config file. By default `walltime` is set to `6:00:00`. +This key is _optional_. **Default** settings for the fluxsite tests will be used if it is not present -##### `storage` +```yaml +fluxsite: + pbs: + ncpus: 18 + mem: 30GB + walltime: 06:00:00 + storage: [scratch/a00, gdata/xy11] + multiprocess: True +``` -: A list of extra storage flags required for the PBS job, i.e. `-l storage=` (see [PBS Directives Explained][nci-pbs-directives]). -: This key is **optional** and can be omitted from the config file. By default `storage` is set to `[]`. +#### pbs -#### `multiprocess` +Contains settings specific to the PBS scheduler at NCI for the PBS script running the CABLE simulations at FLUXNET sites and the bitwise comparison for these simulations. -: Enables or disables multiprocessing for executing embarrassingly parallel tasks. -: This key is **optional** and can be omitted from the config file. By default `multiprocess` is set to `True`. +This key is _optional_. **Default** values for the PBS settings will apply if it is not specified. -Example: ```yaml fluxsite: pbs: - ncpus: 16 - mem: 64GB - walltime: 00:01:00 + ncpus: 18 + mem: 30GB + walltime: 06:00:00 storage: [scratch/a00, gdata/xy11] - multiprocess: True ``` -## Simulations options +[`ncpus`](#+pbs.ncpus){ #+pbs.ncpus } -### `realisations` +: **Default:** 18, _optional key_. :octicons-dash-24: The number of CPU cores to allocate for the PBS job, i.e. the `-l ncpus=<4>` PBS flag in [PBS Directives Explained][nci-pbs-directives]. -: Entries for each CABLE branch to use. Each entry is a dictionary, `{}`, that contains the following keys: +```yaml -#### `path` +fluxsite: + pbs: + ncpus: 18 -: The path of the branch relative to the SVN root of the CABLE repository (`https://trac.nci.org.au/svn/cable`). -: Example: +``` - - to checkout `https://trac.nci.org.au/svn/cable/trunk`, set `path: "trunk"` - - to checkout `https://trac.nci.org.au/svn/cable/branches/Users/foo/my_branch`, set `path: "branches/Users/foo/my_branch"` +[`mem`](#+pbs.mem){ #+pbs.mem } -#### `name` +: **Default:** 30GB, _optional key_. :octicons-dash-24: The total memory limit for the PBS job, i.e. the `-l mem=<10GB>` PBS flag in [PBS Directives Explained][nci-pbs-directives]. -: An alias name used internally by `benchcab` for the branch. The `name` key also specifies the directory name when checking out the branch, that is, `name` is the optional `PATH` argument to `svn checkout`. -: This key is **optional** and can be omitted from the config file. By default `name` is set to the base name of [`path`](#`path`). +```yaml -#### `build_script` +fluxsite: + pbs: + mem: 30GB -: This key is **optional**. The path to a custom shell script to build the code in that branch, relative to the name of the branch. **Note:** any lines in the provided shell script that call the [environment modules API][environment-modules] will be ignored. To specify modules to use for the build script, please specify them using the [`modules`](#`modules`) key. -: Example: `build_script: offline/build.sh` to specify a build script under `/offline/`. +``` -#### `revision` +[`walltime`](#+pbs.walltime){ #+pbs.walltime } -: The revision number to use for the branch. -: This key is **optional** and can be omitted from the config file (in which case the HEAD of the branch is used). +: **Default:** `6:00:00`, _optional key_. :octicons-dash-24: The wall clock time limit for the PBS job, i.e. `-l walltime=` PBS flag in [PBS Directives Explained][nci-pbs-directives]. -#### `patch` +```yaml -: Branch-specific namelist settings for `cable.nml`. Settings specified in `patch` get "patched" to the base namelist settings used for both branches. Any namelist settings specified here will overwrite settings defined in the default namelist file and in the science configurations. This means these settings will be set as stipulated in the `patch` for this branch for all science configurations run by `benchcab`. -: The `patch` key must be a dictionary-like data structure that is compliant with the [`f90nml`][f90nml-github] python package. -: This key is **optional** and can be omitted from the config file (in which case `patch` does not modify the namelist file). +fluxsite: + pbs: + walltime: 6:00:00 -#### `patch_remove` +``` +[`storage`](#+pbs.storage){ #+pbs.storage } -: Specifies branch-specific namelist settings to be removed from the `cable.nml` namelist settings. When the `patch_remove` key is specified, the specified namelists are removed from all namelist files for this branch for all science configurations run by `benchcab`. -: The `patch_remove` key must be a dictionary-like data structure that is compliant with the [`f90nml`][f90nml-github] python package. Note, when specifying a namelist parameter in `patch_remove`, the value of the namelist parameter is ignored. -: This key is **optional** and can be omitted from the config file (in which case `patch_remove` does not modify the namelist file). +: **Default:** [], _optional key_. :octicons-dash-24: List of extra storage flags required for the PBS job, i.e. `-l storage=` in [PBS Directives Explained][nci-pbs-directives]. + +```yaml + +fluxsite: + pbs: + storage: [scratch/a00, gdata/xy11] + +``` + +#### multiprocess + +: **Default:** True, _optional key_. :octicons-dash-24: Enables or disables multiprocessing for executing embarrassingly parallel tasks. + +```yaml + +fluxsites: + multiprocess: True + +``` + +## Simulations options + +### realisations + +Entries for each CABLE branch to use. Each entry is a dictionary, `{}`, that contains the following keys. -Example: ```yaml realisations: [ { # head of the trunk @@ -153,6 +176,49 @@ realisations: [ ] ``` +[path](#+realisation.path){ #+realisation.path } + +: **Default:** _required option, no default_. :octicons-dash-24: The path of the branch relative to the SVN root of the CABLE repository (`https://trac.nci.org.au/svn/cable`). + +```yaml +realisations: { + path: "trunk" # (1) +} + path: "branches/Users/foo/my_branch" # (2) + +``` + +1. To checkout `https://trac.nci.org.au/svn/cable/trunk` +2. To checkout `https://trac.nci.org.au/svn/cable/branches/Users/foo/my_branch` + +#### `name` + +: An alias name used internally by `benchcab` for the branch. The `name` key also specifies the directory name when checking out the branch, that is, `name` is the optional `PATH` argument to `svn checkout`. +: This key is **optional** and can be omitted from the config file. By default `name` is set to the base name of [`path`](#`path`). + +#### `build_script` + +: This key is **optional**. The path to a custom shell script to build the code in that branch, relative to the name of the branch. **Note:** any lines in the provided shell script that call the [environment modules API][environment-modules] will be ignored. To specify modules to use for the build script, please specify them using the [`modules`](#`modules`) key. +: Example: `build_script: offline/build.sh` to specify a build script under `/offline/`. + +#### `revision` + +: The revision number to use for the branch. +: This key is **optional** and can be omitted from the config file (in which case the HEAD of the branch is used). + +#### `patch` + +: Branch-specific namelist settings for `cable.nml`. Settings specified in `patch` get "patched" to the base namelist settings used for both branches. Any namelist settings specified here will overwrite settings defined in the default namelist file and in the science configurations. This means these settings will be set as stipulated in the `patch` for this branch for all science configurations run by `benchcab`. +: The `patch` key must be a dictionary-like data structure that is compliant with the [`f90nml`][f90nml-github] python package. +: This key is **optional** and can be omitted from the config file (in which case `patch` does not modify the namelist file). + +#### `patch_remove` + +: Specifies branch-specific namelist settings to be removed from the `cable.nml` namelist settings. When the `patch_remove` key is specified, the specified namelists are removed from all namelist files for this branch for all science configurations run by `benchcab`. +: The `patch_remove` key must be a dictionary-like data structure that is compliant with the [`f90nml`][f90nml-github] python package. Note, when specifying a namelist parameter in `patch_remove`, the value of the namelist parameter is ignored. +: This key is **optional** and can be omitted from the config file (in which case `patch_remove` does not modify the namelist file). + + ### `experiment` : Type of experiment to run. Experiments are defined in the **NRI Land testing** workspace on [modelevaluation.org][meorg]. This key specifies the met forcing files used in the test suite. To choose from: From 390db6844c4fafd9c2e10517048afd3dd05f7b14 Mon Sep 17 00:00:00 2001 From: Claire Carouge Date: Fri, 15 Sep 2023 20:37:38 +1000 Subject: [PATCH 2/5] #140 - Finish first reformatting --- docs/user_guide/config_options.md | 143 +++++++++++++++++++++++------- 1 file changed, 113 insertions(+), 30 deletions(-) diff --git a/docs/user_guide/config_options.md b/docs/user_guide/config_options.md index 9d0fe83c..c20c4c56 100644 --- a/docs/user_guide/config_options.md +++ b/docs/user_guide/config_options.md @@ -10,7 +10,7 @@ The different running modes of `benchcab` are solely dependent on the options us For this test, you want to: * Specify the details of two branches of CABLE - * Do not specify a [`patch`](#`patch`) + * Do not specify a [`patch`](#+realisation.patch) * Use the default set of science options, i.e. do not specify [`science_configurations`](#`science_configurations`) in `config.yaml` * Choose the [`experiment`](#`experiment`) suitable for your stage of development. A run with the `forty-two-site-test` will be required for submissions of new development to CABLE. @@ -19,7 +19,7 @@ The different running modes of `benchcab` are solely dependent on the options us For this test, you want to: * Specify the details of two branches of CABLE - * Specify a [`patch`](#`patch`) for **one** of the branches + * Specify a [`patch`](#+realisation.patch) for **one** of the branches * Use the default set of science options, i.e. do not specify [`science_configurations`](#`science_configurations`) in `config.yaml` * Choose the [`experiment`](#`experiment`) suitable for your stage of development. A run with the `forty-two-site-test` will be required for submissions of new development to CABLE. @@ -29,8 +29,8 @@ The different running modes of `benchcab` are solely dependent on the options us This running mode is quite open to customisations: * Specify the number of CABLE's branches you need - * Use [`patch`](#`patch`) on branches as required - * Specify the [science configurations](#`science_configurations`) you want to run. [`patch`](#`patch`) will be applied on top of the science configurations listed. + * Use [`patch`](#+realisation.patch) on branches as required + * Specify the [science configurations](#`science_configurations`) you want to run. [`patch`](#+realsation.patch) will be applied on top of the science configurations listed. ## Technical options @@ -176,52 +176,129 @@ realisations: [ ] ``` -[path](#+realisation.path){ #+realisation.path } +[`path`](#+realisation.path){ #+realisation.path } : **Default:** _required option, no default_. :octicons-dash-24: The path of the branch relative to the SVN root of the CABLE repository (`https://trac.nci.org.au/svn/cable`). ```yaml -realisations: { - path: "trunk" # (1) -} - path: "branches/Users/foo/my_branch" # (2) +realisations: [ + { # head of the trunk + path: "trunk", # (1) + }, + { # some development branch + path: "branches/Users/foo/my_branch", # (2) + } +] ``` 1. To checkout `https://trac.nci.org.au/svn/cable/trunk` 2. To checkout `https://trac.nci.org.au/svn/cable/branches/Users/foo/my_branch` -#### `name` +[`name`](#+realisation.name){ #+realisation.name } + +: **Default:** base name of [path](#+realisation.path), _optional key_. :octicons-dash-24: An alias name used internally by `benchcab` for the branch. The `name` key also specifies the directory name when checking out the branch, that is, `name` is the optional `PATH` argument to `svn checkout`. + +```yaml +realisations: [ + { # head of the trunk + path: "trunk", + }, + { # some development branch + path: "branches/Users/foo/my_branch", + name: "my_feature", # (1) + } +] -: An alias name used internally by `benchcab` for the branch. The `name` key also specifies the directory name when checking out the branch, that is, `name` is the optional `PATH` argument to `svn checkout`. -: This key is **optional** and can be omitted from the config file. By default `name` is set to the base name of [`path`](#`path`). +``` -#### `build_script` +1. Checkout the branch in the directory `src/my_feature` -: This key is **optional**. The path to a custom shell script to build the code in that branch, relative to the name of the branch. **Note:** any lines in the provided shell script that call the [environment modules API][environment-modules] will be ignored. To specify modules to use for the build script, please specify them using the [`modules`](#`modules`) key. -: Example: `build_script: offline/build.sh` to specify a build script under `/offline/`. +[`build_script`](#+realisation.build_script){ #+realisation.build_script } -#### `revision` +: **Default:** unset, _optional key_. :octicons-dash-24: The path to a custom shell script to build the code in that branch, relative to the name of the branch. **Note:** any lines in the provided shell script that call the [environment modules API][environment-modules] will be ignored. To specify modules to use for the build script, please specify them using the [`modules`](#modules) key. -: The revision number to use for the branch. -: This key is **optional** and can be omitted from the config file (in which case the HEAD of the branch is used). +```yaml +realisations: [ + { # head of the trunk + path: "trunk", + }, + { # some development branch + path: "branches/Users/foo/my_branch", + build_script: "offline/build.sh", # (1) + } +] +``` + +1. Uses the build script stored by `benchcab` as `src/my_branch/offline/build.sh` + +[`revision`](#+realisation.revision){ #+realisation.revision } + +: **Default:** HEAD of the branch is checked out, _optional key_. :octicons-dash-24: The revision number to checkout for the branch. This option can be used to ensure the reproducibility of the tests. + +```yaml +realisations: [ + { # head of the trunk + path: "trunk", + }, + { # some development branch + path: "branches/Users/foo/my_branch", + revision: 439, + } +] +``` -#### `patch` +[`patch`](#+realisation.patch){ #+realisation.patch } -: Branch-specific namelist settings for `cable.nml`. Settings specified in `patch` get "patched" to the base namelist settings used for both branches. Any namelist settings specified here will overwrite settings defined in the default namelist file and in the science configurations. This means these settings will be set as stipulated in the `patch` for this branch for all science configurations run by `benchcab`. +: **Default:** unset, _optional key_. :octicons-dash-24: Branch-specific namelist settings for `cable.nml`. Settings specified in `patch` get "patched" to the base namelist settings used for both branches. Any namelist settings specified here will overwrite settings defined in the default namelist file and in the science configurations. This means these settings will be set as stipulated in the `patch` for this branch for all science configurations run by `benchcab`. : The `patch` key must be a dictionary-like data structure that is compliant with the [`f90nml`][f90nml-github] python package. -: This key is **optional** and can be omitted from the config file (in which case `patch` does not modify the namelist file). -#### `patch_remove` +```yaml +realisations: [ + { # head of the trunk + path: "trunk", + }, + { # some development branch + path: "branches/Users/foo/my_branch", + patch: { # (1) + cable: { + cable_user: { + FWSOIL_SWITCH: "Lai and Ktaul 2000", + } + } + } + } +] +``` -: Specifies branch-specific namelist settings to be removed from the `cable.nml` namelist settings. When the `patch_remove` key is specified, the specified namelists are removed from all namelist files for this branch for all science configurations run by `benchcab`. -: The `patch_remove` key must be a dictionary-like data structure that is compliant with the [`f90nml`][f90nml-github] python package. Note, when specifying a namelist parameter in `patch_remove`, the value of the namelist parameter is ignored. -: This key is **optional** and can be omitted from the config file (in which case `patch_remove` does not modify the namelist file). +1. Sets FWSOIL_SWITCH to "Lai and Ktaul 2000" for all science configurations for this branch + +[`patch_remove`](#+realisation.path_remove){#+realisation.patch_remove} + +: **Default:** unset, no effect, _optional key. :octicons-dash-24: Specifies branch-specific namelist settings to be removed from the `cable.nml` namelist settings. When the `patch_remove` key is specified, the specified namelists are removed from all namelist files for this branch for all science configurations run by `benchcab`. When specifying a namelist parameter in `patch_remove`, the value of the namelist parameter is ignored. +: The `patch_remove` key must be a dictionary-like data structure that is compliant with the [`f90nml`][f90nml-github] python package. + +```yaml +realisations: [ + { # head of the trunk + path: "trunk", + }, + { # some development branch + path: "branches/Users/foo/my_branch", + patch_remove: { + cable: { + soilparmnew: nil, # (1) + } + } + } +] +``` +1. The value is ignored and does not have to be a possible value for the namelist option. -### `experiment` +### experiment -: Type of experiment to run. Experiments are defined in the **NRI Land testing** workspace on [modelevaluation.org][meorg]. This key specifies the met forcing files used in the test suite. To choose from: +: **Default:** _required option, no default_. :octicons-dash-24: Type of experiment to run. Experiments are defined in the **NRI Land testing** workspace on [modelevaluation.org][meorg]. This key specifies the met forcing files used in the test suite. To choose from: - [`forty-two-site-test`][forty-two-me]: to run simulations using 42 FLUXNET sites - [`five-site-test`][five-me]: to run simulations using 5 FLUXNET sites @@ -231,10 +308,16 @@ realisations: { - `US-Var`: to run simulations at the Vaira Ranch-Ione (US) site - `US-Whs`: to run simulations at the Walnut Gulch Lucky Hills Shrub (US) site -### `science_configurations` +```yaml + +experiment: "AU-How" + +``` + +### science_configurations + +: **Default:** unset, no impact, _optional key_. :octicons-dash-24: User defined science configurations. Science configurations that are specified here will replace [the default science configurations](default_science_configurations.md). In the output filenames, each configuration is identified with S where N is an integer starting from 0 for the first listed configuration and increasing by 1 for each subsequent configuration. -: User defined science configurations. This key is **optional** and can be omitted from the config file. Science configurations that are specified here will replace [the default science configurations](default_science_configurations.md). In the output filenames, each configuration is identified with S where N is an integer starting from 0 for the first listed configuration and increasing by 1 for each subsequent configuration. -: Example: ```yaml science_configurations: [ { # S0 configuration From 6688edf5a095715ce285a3a5638119a48ee61cb2 Mon Sep 17 00:00:00 2001 From: Claire Carouge Date: Fri, 15 Sep 2023 21:00:49 +1000 Subject: [PATCH 3/5] #140 - remove a level of heading and reorganise options --- docs/user_guide/config_options.md | 53 +++++++++++++++---------------- 1 file changed, 25 insertions(+), 28 deletions(-) diff --git a/docs/user_guide/config_options.md b/docs/user_guide/config_options.md index 25fdc66d..683b00d4 100644 --- a/docs/user_guide/config_options.md +++ b/docs/user_guide/config_options.md @@ -33,9 +33,7 @@ The different running modes of `benchcab` are solely dependent on the options us * Specify the [science configurations](#`science_configurations`) you want to run. [`patch`](#+realsation.patch) will be applied on top of the science configurations listed. -## Technical options - -### project +## project : **Default:** _required option, no default_. :octicons-dash-24: NCI project ID to charge the simulations to. @@ -45,7 +43,7 @@ project: nf33 ``` -### modules +## modules : **Default:** _required option, no default_. :octicons-dash-24: NCI modules to use for compiling CABLE @@ -59,7 +57,25 @@ modules: [ ``` -### fluxsite +## experiment + +: **Default:** _required option, no default_. :octicons-dash-24: Type of experiment to run. Experiments are defined in the **benchcab-evaluation** workspace on [modelevaluation.org][meorg]. This key specifies the met forcing files used in the test suite. To choose from: + + - [`forty-two-site-test`][forty-two-me]: to run simulations using 42 FLUXNET sites + - [`five-site-test`][five-me]: to run simulations using 5 FLUXNET sites + - `AU-Tum`: to run simulations at the Tumbarumba (AU) site + - `AU-How`: to run simulations at the Howard Spring (AU) site + - `FI-Hyy`: to run simulations at the Hyytiala (FI) site + - `US-Var`: to run simulations at the Vaira Ranch-Ione (US) site + - `US-Whs`: to run simulations at the Walnut Gulch Lucky Hills Shrub (US) site + +```yaml + +experiment: "AU-How" + +``` + +## fluxsite Contains settings specific to fluxsite tests. This key is _optional_. **Default** settings for the fluxsite tests will be used if it is not present @@ -74,7 +90,7 @@ fluxsite: multiprocess: True ``` -#### pbs +### pbs Contains settings specific to the PBS scheduler at NCI for the PBS script running the CABLE simulations at FLUXNET sites and the bitwise comparison for these simulations. @@ -136,7 +152,7 @@ fluxsite: ``` -#### multiprocess +### multiprocess : **Default:** True, _optional key_. :octicons-dash-24: Enables or disables multiprocessing for executing embarrassingly parallel tasks. @@ -147,9 +163,7 @@ fluxsites: ``` -## Simulations options - -### realisations +## realisations Entries for each CABLE branch to use. Each entry is a dictionary, `{}`, that contains the following keys. @@ -296,25 +310,8 @@ realisations: [ 1. The value is ignored and does not have to be a possible value for the namelist option. -### experiment - -: **Default:** _required option, no default_. :octicons-dash-24: Type of experiment to run. Experiments are defined in the **benchcab-evaluation** workspace on [modelevaluation.org][meorg]. This key specifies the met forcing files used in the test suite. To choose from: - - - [`forty-two-site-test`][forty-two-me]: to run simulations using 42 FLUXNET sites - - [`five-site-test`][five-me]: to run simulations using 5 FLUXNET sites - - `AU-Tum`: to run simulations at the Tumbarumba (AU) site - - `AU-How`: to run simulations at the Howard Spring (AU) site - - `FI-Hyy`: to run simulations at the Hyytiala (FI) site - - `US-Var`: to run simulations at the Vaira Ranch-Ione (US) site - - `US-Whs`: to run simulations at the Walnut Gulch Lucky Hills Shrub (US) site - -```yaml - -experiment: "AU-How" - -``` -### science_configurations +## science_configurations : **Default:** unset, no impact, _optional key_. :octicons-dash-24: User defined science configurations. Science configurations that are specified here will replace [the default science configurations](default_science_configurations.md). In the output filenames, each configuration is identified with S where N is an integer starting from 0 for the first listed configuration and increasing by 1 for each subsequent configuration. From 17df79b587bb7bf7c079ac4b22b68b342350522c Mon Sep 17 00:00:00 2001 From: Claire Carouge Date: Fri, 15 Sep 2023 21:02:42 +1000 Subject: [PATCH 4/5] 140 - Add link to subheading for better readability --- docs/user_guide/config_options.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user_guide/config_options.md b/docs/user_guide/config_options.md index 683b00d4..022584b7 100644 --- a/docs/user_guide/config_options.md +++ b/docs/user_guide/config_options.md @@ -90,7 +90,7 @@ fluxsite: multiprocess: True ``` -### pbs +### [pbs](#pbs) Contains settings specific to the PBS scheduler at NCI for the PBS script running the CABLE simulations at FLUXNET sites and the bitwise comparison for these simulations. @@ -152,7 +152,7 @@ fluxsite: ``` -### multiprocess +### [multiprocess](#multiprocess) : **Default:** True, _optional key_. :octicons-dash-24: Enables or disables multiprocessing for executing embarrassingly parallel tasks. From efc9b36d959c0e1e80204391ca49af15831ef706 Mon Sep 17 00:00:00 2001 From: Claire Carouge Date: Fri, 22 Sep 2023 16:07:40 +1000 Subject: [PATCH 5/5] #140- response to review - remove admonition box, now redundant - list experiments in table - changed "required option" to "required key" for consitency with "optional key" --- docs/user_guide/config_options.md | 27 +++++++++++++-------------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/docs/user_guide/config_options.md b/docs/user_guide/config_options.md index 022584b7..cf07000b 100644 --- a/docs/user_guide/config_options.md +++ b/docs/user_guide/config_options.md @@ -1,8 +1,5 @@ # config.yaml options -!!! note "Required options" - All keys listed here are required unless stated otherwise. - The different running modes of `benchcab` are solely dependent on the options used in `config.yaml`. The following gives some typical ways to configure `benchcab` for each mode, but the tool is not restricted to these choices of options: === "Regression test" @@ -35,7 +32,7 @@ The different running modes of `benchcab` are solely dependent on the options us ## project -: **Default:** _required option, no default_. :octicons-dash-24: NCI project ID to charge the simulations to. +: **Default:** _required key, no default_. :octicons-dash-24: NCI project ID to charge the simulations to. ``` yaml @@ -45,7 +42,7 @@ project: nf33 ## modules -: **Default:** _required option, no default_. :octicons-dash-24: NCI modules to use for compiling CABLE +: **Default:** _required key, no default_. :octicons-dash-24: NCI modules to use for compiling CABLE ``` yaml @@ -59,15 +56,17 @@ modules: [ ## experiment -: **Default:** _required option, no default_. :octicons-dash-24: Type of experiment to run. Experiments are defined in the **benchcab-evaluation** workspace on [modelevaluation.org][meorg]. This key specifies the met forcing files used in the test suite. To choose from: +: **Default:** _required key, no default_. :octicons-dash-24: Type of experiment to run. Experiments are defined in the **benchcab-evaluation** workspace on [modelevaluation.org][meorg]. This key specifies the met forcing files used in the test suite. To choose from: - - [`forty-two-site-test`][forty-two-me]: to run simulations using 42 FLUXNET sites - - [`five-site-test`][five-me]: to run simulations using 5 FLUXNET sites - - `AU-Tum`: to run simulations at the Tumbarumba (AU) site - - `AU-How`: to run simulations at the Howard Spring (AU) site - - `FI-Hyy`: to run simulations at the Hyytiala (FI) site - - `US-Var`: to run simulations at the Vaira Ranch-Ione (US) site - - `US-Whs`: to run simulations at the Walnut Gulch Lucky Hills Shrub (US) site +: | Key value | Experiment description | +|-----------|------------------------| +| [`forty-two-site-test`][forty-two-me] | Run simulations for 42 FLUXNET sites | +| [`five-site-test`][five-me] | Run simulations for 5 FLUXNET sites | +| `AU-Tum` | Run simulations at the Tumbarumba (AU) site | +| `AU-How` | Run simulations at the Howard Spring (AU) site | +| `FI-Hyy` | Run simulations at the Hyytiala (FI) site | +| `US-Var` | Run simulations at the Vaira Ranch-Ione (US) site | +| `US-Whs` | Run simulations at the Walnut Gulch Lucky Hills Shrub (US) site | ```yaml @@ -192,7 +191,7 @@ realisations: [ [`path`](#+realisation.path){ #+realisation.path } -: **Default:** _required option, no default_. :octicons-dash-24: The path of the branch relative to the SVN root of the CABLE repository (`https://trac.nci.org.au/svn/cable`). +: **Default:** _required key, no default_. :octicons-dash-24: The path of the branch relative to the SVN root of the CABLE repository (`https://trac.nci.org.au/svn/cable`). ```yaml realisations: [