Skip to content

Commit

Permalink
#140 - Finish first reformatting
Browse files Browse the repository at this point in the history
  • Loading branch information
@ccarouge
ccarouge committed Sep 15, 2023
1 parent 1d1aa8e commit 390db68
Showing 1 changed file with 113 additions and 30 deletions.
143 changes: 113 additions & 30 deletions docs/user_guide/config_options.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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.

Expand All @@ -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
Expand Down Expand Up @@ -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 `<name_of_branch>/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
Expand All @@ -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<N\> 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<N\> 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
Expand Down

0 comments on commit 390db68

Please sign in to comment.