Skip to content

Commit 847ed5a

Browse files
jjokellajjokella
authored
docs: Sync users_guide docs with python scripts
- `create_ensemble_namelists.md`: add `--forcings-dir`, `--suffix-finidat`, and `--suffix paramfile` to the Options table; update the `lnd_in_NNNN` row to list all three optional suffixes; add usage examples for the two new suffix flags - `modify_case_namelists.md`: add missing `--papi-` (`&papi_inparm`) and `--cplcustom-` (`&seq_cplflds_userspec`) entries to the files/groups table - `normalize_namelists.md`: correct "three transformations" to four; add equals-sign spacing as transformation #4
1 parent dba0df3 commit 847ed5a

3 files changed

Lines changed: 39 additions & 18 deletions

File tree

‎docs/users_guide/create_ensemble_namelists.md‎

Lines changed: 28 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -17,13 +17,13 @@ a suffix (`_NNNN`).
1717

1818
The following modifications are applied per file type:
1919

20-
| Output file | Source | Modification |
21-
|--------------------------|---------------------|---------------------------------------------------------------------------------------|
22-
| `{mod}_modelio.nml_NNNN` | `{mod}_modelio.nml` | `logfile` gets `_NNNN` inserted before `.log` |
23-
| `datm_in_NNNN` | `datm_in` | Each stream filename in `shr_strdata_nml:streams` gets `_NNNN` inserted before `.txt` |
24-
| `lnd_in_NNNN` | `lnd_in` | Unchanged copy; optionally `clm_inparm:fsurdat` gets a five-digit suffix |
25-
| `mosart_in_NNNN` | `mosart_in` | Unchanged copy |
26-
| `datm.streams_NNNN.*` | `datm.streams.*` | `fieldInfo/filePath` is redirected from `./forcings` to `./forcings/real_NNNNN` |
20+
| Output file | Source | Modification |
21+
|--------------------------|---------------------|-------------------------------------------------------------------------------------------------------------------|
22+
| `{mod}_modelio.nml_NNNN` | `{mod}_modelio.nml` | `logfile` gets `_NNNN` inserted before `.log` |
23+
| `datm_in_NNNN` | `datm_in` | Each stream filename in `shr_strdata_nml:streams` gets `_NNNN` inserted before `.txt` |
24+
| `lnd_in_NNNN` | `lnd_in` | Unchanged copy; optionally `clm_inparm:fsurdat` (5-digit), `finidat` (after `.clm2`), or `paramfile` get a suffix |
25+
| `mosart_in_NNNN` | `mosart_in` | Unchanged copy |
26+
| `datm.streams_NNNN.*` | `datm.streams.*` | `fieldInfo/filePath` is redirected from `./forcings` to `./forcings/real_NNNNN` |
2727

2828
The `{mod}` components processed for modelio files are:
2929
`atm`, `esp`, `glc`, `ice`, `lnd`, `ocn`, `rof`, `wav`, `cpl`.
@@ -44,16 +44,31 @@ python3 create_ensemble_namelists.py \
4444
--rundir /path/to/rundir \
4545
--num_ensemble 50 \
4646
--suffix-fsurdat
47+
48+
# Add per-member suffix to the initial conditions file
49+
python3 create_ensemble_namelists.py \
50+
--rundir /path/to/rundir \
51+
--num_ensemble 50 \
52+
--suffix-finidat
53+
54+
# Add per-member suffix to the CLM parameter file
55+
python3 create_ensemble_namelists.py \
56+
--rundir /path/to/rundir \
57+
--num_ensemble 50 \
58+
--suffix-paramfile
4759
```
4860

4961
### Options
5062

51-
| Option | Description |
52-
|------------------------|------------------------------------------------------------------------------|
53-
| `-r`, `--rundir` | Directory containing the base namelist files. Defaults to `.` |
54-
| `-n`, `--num_ensemble` | Number of ensemble members to generate. Defaults to `96` |
55-
| `-b`, `--backend` | Namelist backend: `re` (default, regexp-based) or `f90nml` |
56-
| `--suffix-fsurdat` | Also add a five-digit member suffix to `clm_inparm:fsurdat` in `lnd_in_NNNN` |
63+
| Option | Description |
64+
|------------------------|--------------------------------------------------------------------------------------------------|
65+
| `-r`, `--rundir` | Directory containing the base namelist files. Defaults to `.` |
66+
| `-n`, `--num_ensemble` | Number of ensemble members to generate. Defaults to `96` |
67+
| `-b`, `--backend` | Namelist backend: `re` (default, regexp-based) or `f90nml` |
68+
| `-f`, `--forcings-dir` | Forcings directory used in stream file `fieldInfo/filePath` entries. Defaults to `./forcings` |
69+
| `--suffix-fsurdat` | Add a five-digit member suffix to `clm_inparm:fsurdat` in `lnd_in_NNNN` |
70+
| `--suffix-finidat` | Add a four-digit member suffix to `clm_inparm:finidat` in `lnd_in_NNNN`, inserted after `.clm2` |
71+
| `--suffix-paramfile` | Add a four-digit member suffix to `clm_inparm:paramfile` in `lnd_in_NNNN`, inserted before `.nc` |
5772

5873
## Expected run directory layout
5974

‎docs/users_guide/modify_case_namelists.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,9 +32,11 @@ prefix of each option flag identifies both:
3232
| `--driver-` | `drv_in` | `&cime_driver_inst` |
3333
| `--pes-` | `drv_in` | `&cime_pes` |
3434
| `--esmf-` | `drv_in` | `&esmf_inparm` |
35+
| `--papi-` | `drv_in` | `&papi_inparm` |
3536
| `--pio-` | `drv_in` | `&pio_default_inparm` |
3637
| `--prof-` | `drv_in` | `&prof_inparm` |
3738
| `--cplflds-` | `drv_in` | `&seq_cplflds_inparm` |
39+
| `--cplcustom-` | `drv_in` | `&seq_cplflds_userspec` |
3840
| `--flux_mct-` | `drv_in` | `&seq_flux_mct_inparm` |
3941
| `--clm_inparm-` | `lnd_in` | `&clm_inparm` |
4042
| `--ndepdyn-` | `lnd_in` | `&ndepdyn_nml` |

‎docs/users_guide/normalize_namelists.md‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,24 +5,28 @@ clean and human-readable.
55

66
## What it does
77

8-
The script applies three transformations to every namelist file it
8+
The script applies four transformations to every namelist file it
99
finds:
1010

11-
1. **Indentation** — lines inside a `&group … /` block are re-indented
11+
1. **Indentation** - lines inside a `&group ... /` block are re-indented
1212
to exactly two spaces. Group header (`&group`) and closing (`/`)
1313
lines are left as-is.
1414

15-
2. **Quote style** — string values delimited by double quotes are
16-
rewritten to use single quotes (`"value"` → `'value'`). The value
15+
2. **Quote style** - string values delimited by double quotes are
16+
rewritten to use single quotes (`"value"` -> `'value'`). The value
1717
content is never modified.
1818

19-
3. **Continuation alignment** — continuation lines of multi-line values are
19+
3. **Continuation alignment** - continuation lines of multi-line values are
2020
indented to align with the value start on the `key = value` line above:
2121
```
2222
hist_fincl1 = 'SOILWATER_10CM', 'H2OSOI',
2323
'SOILLIQ', 'SOILICE'
2424
```
2525

26+
4. **Equals-sign spacing** - exactly one space is placed before and after
27+
the `=` sign in every `key = value` entry (`key=value` and
28+
`key = value` are both rewritten to `key = value`).
29+
2630
Lines outside a group (blank lines, comment blocks appended by
2731
`modify_case_namelists.py`, etc.) are passed through unchanged.
2832

0 commit comments

Comments
 (0)