Skip to content

Commit 87ccbca

Browse files
ccarougeccarouge
authored
Merge pull request #322 from CABLE-LSM/319-add-examples-of-configs-use-cases
config examples for various use cases
2 parents aa5d6c0 + 01dbc88 commit 87ccbca

File tree

2 files changed

+179
-0
lines changed

2 files changed

+179
-0
lines changed

‎docs/user_guide/use_cases.md

+178
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# Configuration examples for various use cases
2+
3+
In all examples replace strings like XXXXX, YYYYY, etc. with the appropriate values for your case.
4+
5+
## Check bitwise comparability
6+
7+
```yaml
8+
realisations:
9+
- repo:
10+
git:
11+
branch: main
12+
- repo:
13+
git:
14+
branch: XXXXX
15+
16+
modules: [
17+
intel-compiler/2021.1.1,
18+
netcdf/4.7.4,
19+
openmpi/4.1.0
20+
]
21+
```
22+
23+
The results of the bitwise comparison will be in the log file from the flux site run.
24+
25+
26+
## Evaluate the effect of a new feature
27+
28+
If you are developing a new feature and want to check the effect compared to the main version, you need to run:
29+
30+
- the main version as is
31+
- the development branch with the new feature turned on for all science configurations
32+
33+
```yaml
34+
realisations:
35+
- repo:
36+
git:
37+
branch: main
38+
- repo:
39+
git:
40+
branch: XXXXX
41+
patch: # (1)
42+
cable:
43+
cable_user:
44+
existing_feature: YYYY
45+
46+
fluxsite:
47+
meorg_model_output_id: ZZZZ # (2)
48+
49+
modules: [
50+
intel-compiler/2021.1.1,
51+
netcdf/4.7.4,
52+
openmpi/4.1.0
53+
]
54+
```
55+
56+
1. Use the option names and values as implemented in the cable namelist file.
57+
2. You need to setup your environment for meorg_client before using this feature.
58+
59+
The evaluation results will be on modelevaluation.org accessible from the Model Output page you've specified
60+
61+
## Evaluate the effect of a modified feature
62+
63+
If you are modifying an *existing* feature of CABLE (bug fix or other development) and want to check the effect of your changes compared to the main version, with that feature turned on, you need to run:
64+
65+
- the main branch with the new feature turned on for all science configurations
66+
- the development branch with the new feature turned on for all science configurations
67+
68+
```yaml
69+
realisations:
70+
- repo:
71+
git:
72+
branch: main
73+
patch: # (1)
74+
cable:
75+
cable_user:
76+
existing_feature: YYYY
77+
- repo:
78+
git:
79+
branch: XXXXX
80+
patch: # (2)
81+
cable:
82+
cable_user:
83+
existing_feature: YYYY
84+
85+
fluxsite:
86+
meorg_model_output_id: ZZZZ # (3)
87+
88+
modules: [
89+
intel-compiler/2021.1.1,
90+
netcdf/4.7.4,
91+
openmpi/4.1.0
92+
]
93+
```
94+
95+
1. Use the option names and values as implemented in the cable namelist file.
96+
2. Use the option names and values as implemented in the cable namelist file.
97+
3. You need to setup your environment for meorg_client before using this feature.
98+
99+
The evaluation results will be on modelevaluation.org accessible from the Model Output page you've specified
100+
101+
## Evaluation of a bug fix affecting all science options
102+
103+
If you have a bug fix that affects all CABLE simulations, you need to run:
104+
105+
- the main branch as is
106+
- the development branch as is
107+
108+
```yaml
109+
realisations:
110+
- repo:
111+
git:
112+
branch: main
113+
- repo:
114+
git:
115+
branch: XXXXX
116+
117+
fluxsite:
118+
meorg_model_output_id: ZZZZ # (1)
119+
120+
modules: [
121+
intel-compiler/2021.1.1,
122+
netcdf/4.7.4,
123+
openmpi/4.1.0
124+
]
125+
```
126+
127+
1. You need to setup your environment for meorg_client before using this feature.
128+
129+
The evaluation results will be on modelevaluation.org accessible from the Model Output page you've specified
130+
131+
## Early test of development using a local repository
132+
133+
Do a quick test at one site only to compare a new feature on and off together and with the main branch.
134+
135+
To run only the fluxsite experiment, execute `benchcab fluxsite` with the following config.yaml file.
136+
137+
```yaml
138+
experiment: AU-Tum # (1)
139+
140+
realisations:
141+
- repo:
142+
git:
143+
branch: main
144+
- repo:
145+
name: my-feature-off # (2)
146+
local:
147+
path: XXXXX # (3)
148+
- repo:
149+
name: my-feature-on
150+
local:
151+
path: XXXXX
152+
patch: # (4)
153+
cable:
154+
cable_user:
155+
new_feature: YYYY
156+
157+
fluxsite:
158+
meorg_model_output_id: ZZZZ # (5)
159+
pbs: # (6)
160+
ncpus: 8
161+
mem: 16GB
162+
walltime: "0:15:00"
163+
164+
modules: [
165+
intel-compiler/2021.1.1,
166+
netcdf/4.7.4,
167+
openmpi/4.1.0
168+
]
169+
```
170+
171+
1. Testing at one flux site only to save time and resources.
172+
2. We are using the same branch twice so we need to name each occurrence differently.
173+
3. Give the full path to your local CABLE repository with your code changes.
174+
4. Use the option names and values as implemented in the cable namelist file.
175+
5. You need to setup your environment for meorg_client before using this feature.
176+
6. You can reduce the requested resources to reduce the cost of the test.
177+
178+
Comparisons of R0 and R1 should show bitwise agreement. R2 and R0 (and R1) comparison on modelevaluation.org shows the impact of the changes.

‎mkdocs.yml

+1
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,7 @@ nav:
7676
- User Guide:
7777
- user_guide/index.md
7878
- user_guide/config_options.md
79+
- user_guide/use_cases.md
7980
- user_guide/default_science_configurations.md
8081
- user_guide/running_CABLE_v2.md
8182
- user_guide/expected_output.md

0 commit comments

Comments
 (0)