Skip to content

Commit 5d3983c

Browse files
jjokellajjokella
committed
Merge branch 'dev-perturbation' into dev-grace-da
2 parents 39745b5 + 555c1d1 commit 5d3983c

2 files changed

Lines changed: 694 additions & 0 deletions

File tree

‎docs/users_guide/introduction/perturbation.md‎

Lines changed: 261 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,43 @@ The implementation of the perturbation routines was first introduced
66
by Yorck Ewerdwalbesloh in
77
https://gitlab.jsc.fz-juelich.de/detect/cluster-c/c01/perturbationroutineclm5.
88

9+
## Description
10+
11+
eCLM implements perturbations for atmospheric forcing variables
12+
(temperature, precipitation, longwave radiation, and shortwave
13+
radiation) to support ensemble-based data assimilation in
14+
eCLM-PDAF. The perturbation scheme maintains physical consistency
15+
through cross-variable correlations and spatiotemporal coherence.
16+
17+
### Physical Consistency
18+
19+
Perturbed variables are cross-correlated to preserve physical
20+
relationships between forcing fields. For example, a positive
21+
perturbation of incoming shortwave radiation corresponds to a negative
22+
perturbation of longwave radiation and a positive perturbation of
23+
temperature. The cross-correlation structure follows Reichle et
24+
al. (2007) and Han et al. (2014).
25+
26+
### Spatial Correlation
27+
28+
Perturbations are spatially correlated using an isotropic correlation
29+
function based on grid cell separation distance. Precipitation uses a
30+
shorter correlation length scale than other variables to reflect its
31+
more localized spatial structure. Correlation parameters are
32+
configurable.
33+
34+
### Temporal Correlation
35+
36+
Temporal correlation is generated using a first-order autoregressive
37+
(AR-1) model following Evensen (2009). The default temporal
38+
persistence corresponds to a decorrelation timescale of one day, which
39+
is adjustable based on application requirements.
40+
41+
### Implementation
42+
43+
Perturbation fields are read from preprocessed noise files and applied
44+
to atmospheric forcing variables within the eCLM model during runtime.
45+
946
## Key Components ##
1047

1148
### 1. Soil Parameter Perturbation (`SoilStateInitTimeConstMod.F90`) ###
@@ -92,4 +129,228 @@ CESM's multi-instance framework.
92129
- `src/csm_share/streams/shr_dmodel_mod.F90`
93130
- `src/datm/datm_comp_mod.F90`
94131

132+
## Preparing Atmospheric Forcing Noise
133+
134+
This section describes the workflow for generating and configuring
135+
spatiotemporally correlated noise fields for atmospheric forcing
136+
perturbations.
137+
138+
### Noise Generation Tool
139+
140+
The `tools/correlatedNoise.py` script generates monthly NetCDF files
141+
containing spatiotemporally correlated noise fields for all ensemble
142+
members.
143+
144+
**Key Configuration Parameters:**
145+
146+
- **Ensemble size**: Number of ensemble members to generate noise for (must be specified)
147+
- **Temporal resolution** (`dt`): Time step in hours (e.g., `3` for 3-hourly data, `1` for hourly data)
148+
- **Spatial resolution** (`ds`): Grid spacing in km (e.g., `12.5` for 12.5 km grid, `3` for 3 km grid)
149+
- **Spatial sampling** (`nn`): Number of points used for noise generation before upscaling (limited by computational resources)
150+
- **Temporal persistence** (`rho`): AR-1 correlation coefficient (adjust based on forcing time resolution)
151+
- **Covariance matrix**: Cross-variable covariance structure and correlation coefficients (configurable)
152+
- **File paths**: Input/output directories (must be adjusted for local system)
153+
154+
**Output**: One NetCDF file per month containing noise fields for all ensemble members and all perturbed variables.
155+
156+
### Stream File Configuration
157+
158+
Stream files configure how eCLM reads and applies noise fields to
159+
atmospheric forcing data. Three separate stream files are required
160+
(precipitation, solar radiation, and other variables). Each stream
161+
file must specify the following metadata fields:
162+
163+
**Required Metadata:**
164+
165+
- `timeInformation`: Temporal resolution of forcing data in hours (e.g., `3` for 3-hourly data)
166+
- `caseId`: Ensemble member index (e.g., `0` for first member, `1` for second member)
167+
- `numEns`: Total ensemble size used when generating the noise files
168+
- **Perturbation variables**: `tbot_noise` (temperature), `lwdn_noise` (longwave radiation), `precn_noise` (precipitation), `swdn_noise` (shortwave radiation)
169+
170+
171+
### Stream File Examples
172+
173+
The following examples demonstrate proper stream file configuration
174+
for precipitation, solar radiation, and other atmospheric
175+
variables. Each example must be adapted with correct file paths,
176+
temporal parameters, and ensemble member IDs for your specific
177+
application.
178+
179+
#### Precipitation Noise Stream File
180+
181+
**File**: `user_datm.streams.precip_noise.stream_0000.txt`
182+
183+
```xml
184+
<dataSource>
185+
GENERIC
186+
</dataSource>
187+
<domainInfo>
188+
<variableNames>
189+
time time
190+
xc lon
191+
yc lat
192+
area area
193+
mask mask
194+
</variableNames>
195+
<filePath>
196+
/path/to/domain/file
197+
</filePath>
198+
<fileNames>
199+
domain.lnd.EUR-11_EUR-11.230216_mask.nc
200+
</fileNames>
201+
</domainInfo>
202+
<fieldInfo>
203+
<variableNames>
204+
PRECTmms precn_noise
205+
</variableNames>
206+
<filePath>
207+
/path/to/noise/files
208+
</filePath>
209+
<fileNames>
210+
2003-01.nc
211+
2003-02.nc
212+
2003-03.nc
213+
2003-04.nc
214+
2003-05.nc
215+
2003-06.nc
216+
2003-07.nc
217+
2003-08.nc
218+
2003-09.nc
219+
2003-10.nc
220+
2003-11.nc
221+
2003-12.nc
222+
</fileNames>
223+
<offset>
224+
0
225+
</offset>
226+
<timeInformation>
227+
3
228+
</timeInformation>
229+
<caseId>
230+
0
231+
</caseId>
232+
<numEns>
233+
64
234+
</numEns>
235+
</fieldInfo>
236+
```
237+
238+
#### Solar Radiation Noise Stream File
239+
240+
**File**: `user_datm.streams.solar_noise.stream_0000.txt`
241+
242+
```xml
243+
<dataSource>
244+
GENERIC
245+
</dataSource>
246+
<domainInfo>
247+
<variableNames>
248+
time time
249+
xc lon
250+
yc lat
251+
area area
252+
mask mask
253+
</variableNames>
254+
<filePath>
255+
/path/to/domain/file
256+
</filePath>
257+
<fileNames>
258+
domain.lnd.EUR-11_EUR-11.230216_mask.nc
259+
</fileNames>
260+
</domainInfo>
261+
<fieldInfo>
262+
<variableNames>
263+
FSDS swdn_noise
264+
</variableNames>
265+
<filePath>
266+
/path/to/noise/files
267+
</filePath>
268+
<fileNames>
269+
2003-01.nc
270+
2003-02.nc
271+
2003-03.nc
272+
2003-04.nc
273+
2003-05.nc
274+
2003-06.nc
275+
2003-07.nc
276+
2003-08.nc
277+
2003-09.nc
278+
2003-10.nc
279+
2003-11.nc
280+
2003-12.nc
281+
</fileNames>
282+
<offset>
283+
0
284+
</offset>
285+
<timeInformation>
286+
3
287+
</timeInformation>
288+
<caseId>
289+
0
290+
</caseId>
291+
<numEns>
292+
64
293+
</numEns>
294+
</fieldInfo>
295+
```
296+
297+
#### Temperature and Longwave Radiation Noise Stream File
298+
299+
**File**: `user_datm.streams.other_noise.stream_0000.txt`
300+
301+
```xml
302+
<dataSource>
303+
GENERIC
304+
</dataSource>
305+
<domainInfo>
306+
<variableNames>
307+
time time
308+
xc lon
309+
yc lat
310+
area area
311+
mask mask
312+
</variableNames>
313+
<filePath>
314+
/path/to/domain/file
315+
</filePath>
316+
<fileNames>
317+
domain.lnd.EUR-11_EUR-11.230216_mask.nc
318+
</fileNames>
319+
</domainInfo>
320+
<fieldInfo>
321+
<variableNames>
322+
TBOT tbot_noise
323+
FLDS lwdn_noise
324+
</variableNames>
325+
<filePath>
326+
/path/to/noise/files
327+
</filePath>
328+
<fileNames>
329+
2003-01.nc
330+
2003-02.nc
331+
2003-03.nc
332+
2003-04.nc
333+
2003-05.nc
334+
2003-06.nc
335+
2003-07.nc
336+
2003-08.nc
337+
2003-09.nc
338+
2003-10.nc
339+
2003-11.nc
340+
2003-12.nc
341+
</fileNames>
342+
<offset>
343+
0
344+
</offset>
345+
<timeInformation>
346+
3
347+
</timeInformation>
348+
<caseId>
349+
0
350+
</caseId>
351+
<numEns>
352+
64
353+
</numEns>
354+
</fieldInfo>
95355

356+
```

0 commit comments

Comments
 (0)