You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/user_guide/use_cases.md
+89-45Lines changed: 89 additions & 45 deletions
Original file line number
Diff line number
Diff line change
@@ -2,39 +2,49 @@
2
2
3
3
In all examples replace strings like XXXXX, YYYYY, etc. with the appropriate values for your case.
4
4
5
-
## Required run when developing a new feature for CABLE
5
+
## Check bitwise comparability
6
6
7
-
!!! note Separate runs can be faster
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
+
```
8
22
9
-
We show an uniq configuration to get all the results needed but it isn't necessarily the fastest way. Splitting in 2 occurrences of benchcab running at the same time (one for each configuration of the feature branch) can be faster since the benchcab occurrences run in parallel of each other. It requires to setup 2 work directories for benchcab but that is a small amount of work.
23
+
The results of the bitwise comparison will be in the log file from the flux site run.
10
24
11
-
When developing a new feature for CABLE (or adapting an existing feature), you need to show 2 things in the pull request:
12
25
13
-
- the results have not changed compared to the main branch when the feature is off
14
-
- the modelevaluation.org analysis results when the feature is on compared to the main branch
26
+
## Evaluate the effect of a new feature
15
27
16
-
This can be done with one benchcab occurrence:
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
17
32
18
33
```yaml
19
34
realisations:
20
35
- repo:
21
36
git:
22
37
branch: main
23
38
- repo:
24
-
name: my-feature-off # (1)
25
-
git:
26
-
branch: XXXXX
27
-
- repo:
28
-
name: my-feature-on
29
39
git:
30
40
branch: XXXXX
31
-
patch: # (2)
41
+
patch: # (1)
32
42
cable:
33
43
cable_user:
34
-
new_feature: YYYY
44
+
existing_feature: YYYY
35
45
36
46
fluxsite:
37
-
meorg_model_output_id: ZZZZ # (3)
47
+
meorg_model_output_id: ZZZZ # (2)
38
48
39
49
modules: [
40
50
intel-compiler/2021.1.1,
@@ -43,37 +53,37 @@ modules: [
43
53
]
44
54
```
45
55
46
-
1. We are using the same branch twice so we need to name each occurrence differently.
47
-
2. One should use the same option names and values as implemented in the cable namelist file.
48
-
3. You need to setup your environment for meorg_client before using this feature. If splitting in two occurrences for benchcab, this option should only appear with the "my-feature-on" `repo` option.
56
+
1. Use the same 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 in modelevaluation.org on the Model Output page you've specified
49
60
50
-
With this setup, the output of R0 and R1 should be bitwise comparable.
51
-
The analysis of R0 and R2 in modelevaluation.org gives the effect of the new feature on the results.
61
+
## Evaluate the effect of a modified feature
52
62
53
-
### Modification when changing an existing feature instead of developing a new one.
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:
54
64
55
-
In that case, you may want to show the comparison between your branch with the feature on and main *with the feature on as well*.
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
56
67
57
68
```yaml
58
-
realisations:# (1)
69
+
realisations:
59
70
- repo:
60
71
git:
61
72
branch: main
62
-
patch: # (2)
73
+
patch: # (1)
63
74
cable:
64
75
cable_user:
65
76
existing_feature: YYYY
66
-
67
77
- repo:
68
78
git:
69
79
branch: XXXXX
70
-
patch: # (2)
80
+
patch: # (1)
71
81
cable:
72
82
cable_user:
73
83
existing_feature: YYYY
74
84
75
85
fluxsite:
76
-
meorg_model_output_id: ZZZZ # (3)
86
+
meorg_model_output_id: ZZZZ # (2)
77
87
78
88
modules: [
79
89
intel-compiler/2021.1.1,
@@ -82,40 +92,71 @@ modules: [
82
92
]
83
93
```
84
94
85
-
1. We only show the configuration for the feature on case since the configuration for the feature off is the same as previously.
86
-
2. One should use the same option names and values as implemented in the cable namelist file.
87
-
3. You need to setup your environment for meorg_client before using this feature.
95
+
1. Use the same option names and values as implemented in the cable namelist file.
96
+
2. You need to setup your environment for meorg_client before using this feature.
88
97
89
-
## Smaller tests during development
98
+
The evaluation results will be in modelevaluation.org on the Model Output page you've specified
90
99
91
-
### Comparison to one site for local development
100
+
##Evaluation of a bug fix affecting all science options
92
101
93
-
During development, one might want to check their results before committing and pushing to CABLE's GitHub repository. It is possible to run benchcab using a local directory.
94
-
The configuration here test both a new feature on and off but it is valid to only run one or the other case.
102
+
If you have a bug fix that affects all CABLE simulations, you need to run:
103
+
104
+
- the main branch as is
105
+
- the development branch as is
95
106
96
107
```yaml
97
-
experiment: AU-Tum
108
+
realisations: # (1)
109
+
- repo:
110
+
git:
111
+
branch: main
112
+
- repo:
113
+
git:
114
+
branch: XXXXX
115
+
116
+
fluxsite:
117
+
meorg_model_output_id: ZZZZ # (2)
118
+
119
+
modules: [
120
+
intel-compiler/2021.1.1,
121
+
netcdf/4.7.4,
122
+
openmpi/4.1.0
123
+
]
124
+
```
125
+
126
+
1. Use the same option names and values as implemented in the cable namelist file.
127
+
2. You need to setup your environment for meorg_client before using this feature.
128
+
129
+
The evaluation results will be in modelevaluation.org on 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)
98
139
99
140
realisations:
100
141
- repo:
101
142
git:
102
143
branch: main
103
144
- repo:
104
-
name: my-feature-off # (1)
145
+
name: my-feature-off # (2)
105
146
local:
106
-
path: XXXXX # (2)
147
+
path: XXXXX # (3)
107
148
- repo:
108
149
name: my-feature-on
109
150
local:
110
151
path: XXXXX
111
-
patch: # (3)
152
+
patch: # (4)
112
153
cable:
113
154
cable_user:
114
155
new_feature: YYYY
115
156
116
157
fluxsite:
117
-
meorg_model_output_id: ZZZZ # (4)
118
-
pbs: # (5)
158
+
meorg_model_output_id: ZZZZ # (5)
159
+
pbs: # (6)
119
160
ncpus: 8
120
161
mem: 16GB
121
162
walltime: "0:15:00"
@@ -127,8 +168,11 @@ modules: [
127
168
]
128
169
```
129
170
130
-
1. We are using the same branch twice so we need to name each occurrence differently.
131
-
2. Gives the full path to your local CABLE repository with your code changes.
132
-
3. One should use the same option names and values as implemented in the cable namelist file.
133
-
4. You need to setup your environment for meorg_client before using this feature. This option should only appear with the "my-feature-on" `repo` option.
134
-
5. You can reduce the requested resources to reduce the cost of the test.
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 same 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. This option should only appear with the "my-feature-on" `repo` option.
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 comparison on modelevaluation.org shows the impact of the changes.
0 commit comments