Enable independent HC and RC in wind downscaling by mo-AliceLake · Pull Request #2324 · metoppv/improver

mo-AliceLake · 2026-03-09T14:01:22Z

Description

This PR restructures the WindTerrainAdjustment plugin (previously RoughnessCorrection) to provide clean, explicit control over applying Roughness Correction (RC), Height Correction (HC), or their combined behaviour. The goal is to make HC‑only and RC‑only configurations explicitly selectable, allowing clearer scientific experimentation and operational configurations (e.g. HC‑only over UK-domain, etc).

Previously, HC and RC were tightly coupled within a single routine. Running only one of the corrections was possible but relied on implicit side‑effects (e.g. suppressing RC by passing z0=None), which was neither obvious nor robust. This PR replaces those implicit behaviours with a clear interface.

Previously, HC and RC were tightly coupled inside a single routine (do_rc_hc_all). This made it difficult to:

run HC or RC independently for testing or research,
apply only one component in operational setups,
clearly isolate the individual contribution, performance impacts, or numerical behaviour of HC vs RC.

Summary of Changes

Introduced explicit correction modes:

Split the existing do_rc_hc_all routine into three:
- do_hc()
- do_rc()
- do_hc_and_rc() (chained, preserving legacy HC+RC behaviour)
Added a mode argument to the plugin constructor, allowing users to select:
- "hc_and_rc" (default, identical to previous behaviour)
- "hc"
- "rc"

Clarified RC dependency on z0:
In the new interface, requesting RC (mode="rc" or "hc_and_rc") now requires a valid roughness‑length (z0) field. If it is missing, the plugin raises a clear ValueError.
This replaces the old implicit behaviour where suppressing RC was only achievable indirectly by passing z0=None. The new behaviour is explicit and predictable.

Unified masking and validation
Missing‑data, sea‑point, and invalid‑height masking has been consolidated and made consistent across RC, HC, and combined modes.

Testing

Ran tests and they passed OK
Added new tests for the new feature(s)

… and function names, etc

brhooper

Thanks @mo-AliceLake , this looks to have made a lot of progress towards allowing independent application of roughness and height corrections for wind downscaling.

I've added a few comments suggesting ways in which I think the code might be improved. I haven't gotten as far as reviewing the unit tests yet, I hope to review them tomorrow. I have noted that the acceptance tests need updating following changes to the names of things.

brhooper · 2026-06-23T13:22:34Z

        Returns:
            3D float32 array of wind speed after applying RC and HC.


This statement needs updating.

brhooper · 2026-06-23T13:26:20Z

+    def _mask_missing_data(self, height_above_orog, wspeed_original):
+        """Return a boolean mask: True where either RC or HC may be applied.


Have the type hints been removed here on purpose?

brhooper · 2026-06-23T13:27:56Z

+        if wspeed_original.ndim == 3:
+            missing_w = (wspeed_original == RMDI).any(axis=2)
+        else:
+            missing_w = wspeed_original == RMDI


Suggested change

if wspeed_original.ndim == 3:

missing_w = (wspeed_original == RMDI).any(axis=2)

else:

missing_w = wspeed_original == RMDI

missing_w = wspeed_original == RMDI

if wspeed_original.ndim == 3:

missing_w = missing_w.any(axis=2)

I think this would work.

brhooper · 2026-06-23T13:33:43Z

+
+        return valid
+
+    def do_rc(self, height_above_orog, wspeed_original):


This function deserves a doc-string and type-hints.

brhooper · 2026-06-23T13:33:56Z

+            height_above_orog, wspeed_original, mask_rc
+        )
+
+    def do_hc(self, height_above_orog, wspeed_original):


This function deserves a doc-string and type-hints.

brhooper · 2026-06-23T13:47:55Z

+        # Mask where missing data in height and wind fields
+        valid = self._mask_missing_data(height_above_orog, wspeed_original)
        mask_rc = np.copy(self.rc_mask)
+        mask_rc[~valid] = False
+
+        return self.calc_roughness_correction(
+            height_above_orog, wspeed_original, mask_rc
+        )


Slightly reduces data copying.

Suggested change

# Mask where missing data in height and wind fields

valid = self._mask_missing_data(height_above_orog, wspeed_original)

mask_rc = np.copy(self.rc_mask)

mask_rc[~valid] = False

return self.calc_roughness_correction(

height_above_orog, wspeed_original, mask_rc

)

# Mask where missing data in height and wind fields

valid = self._mask_missing_data(height_above_orog, wspeed_original)

valid[~self.rc_mask] = False

return self.calc_roughness_correction(

height_above_orog, wspeed_original, valid

)

brhooper · 2026-06-23T13:49:33Z

@@ -715,17 +741,30 @@
            uhref_orig, height_above_orog, mask_hc, onemfrac
        )


Same suggested change as in do_rc() to remove a data copy step.

Suggested change

# Mask where missing data in height and wind fields

valid = self._mask_missing_data(height_above_orog, wspeed_original)

valid[~self.hc_mask] = False

# Height correction

# Requires wind speed at the reference height, so interpolate first

z_ref = 1.0 / self.wavenumber

if wspeed_original.ndim == 3 and wspeed_original.shape[2] > 1:

uhref_orig = self._interpolate_wspeed_to_height(

wspeed_original,

height_above_orog,

z_ref,

valid,

)

else:

# Single level (e.g. 10m wind) so no interpolation possible

uhref_orig = np.copy(wspeed_original)

# HC only where u(h_ref) is positive

valid[uhref_orig <= 0.0] = False

# Setting this value to 1, is equivalent to setting the

# Bessel function to 1. (Friedrich, 2016)

# Example usage if the Bessel function was not set to 1 is:

# onemfrac = 1.0 - BfuncFrac(nx,ny,nz,heightvec,z_0,waveno, Ustar, UI)

onemfrac = 1.0

hc_add = self._calc_height_corr(

uhref_orig, height_above_orog, valid, onemfrac

)

brhooper · 2026-06-23T14:12:25Z

            model_z0_cube:
                2D vegetative roughness length (m), representing drag from vegetation
                and land cover. Controls the near-surface wind profile.
                Historically static, but may now be time-varying (e.g. from StaGE).

            height_levels_cube:
                1D or 3D height levels of the input wind field (m).

+            mode:
+                Which correction(s) to apply: "hc_and_rc" (default), "hc", or "rc".


I briefly wondered whether the mode input could be removed in favour of assuming providing model_z0_cube implied that a roughness correction should be applied and similarly that providing height_levels_cube implied a height correction should be applied.

I see now, however, that height_levels_cube is not actually necessary for the height correction, so this wouldn't work. Leaving this comment here as evidence that, sometimes, I do try to think during reviews. There's nothing to action.

brhooper · 2026-06-23T14:30:07Z

+        if np.isnan(zwp):
+            # Reorder wind cube so dimensions are consistently (y, x, [, t])
+            if np.isnan(twp):
+                input_cube.transpose([ywp, xwp])
+            else:
+                input_cube.transpose([ywp, xwp, twp])
        else:
-            input_cube.transpose([ywp, xwp, zwp, twp])
+            # Reorder wind cube so dimensions are consistently (y, x, z [, t])
+            if np.isnan(twp):
+                input_cube.transpose([ywp, xwp, zwp])
+            else:
+                input_cube.transpose([ywp, xwp, zwp, twp])


I think this can be made a bit shorter.

Suggested change

if np.isnan(zwp):

# Reorder wind cube so dimensions are consistently (y, x, [, t])

if np.isnan(twp):

input_cube.transpose([ywp, xwp])

else:

input_cube.transpose([ywp, xwp, twp])

else:

input_cube.transpose([ywp, xwp, zwp, twp])

# Reorder wind cube so dimensions are consistently (y, x, z [, t])

if np.isnan(twp):

input_cube.transpose([ywp, xwp, zwp])

else:

input_cube.transpose([ywp, xwp, zwp, twp])

# Reorder wind cube so dimensions are consistently (y, x), (y, x, [, t]) or

# (y, x, z [, t]) depending on what dimensions are present.

coord_order = [ywp, xwp]

for coord in [zwp, twp]:

if not np.isnan(coord):

coord_order.append(coord)

input_cube.transpose(coord_order)

brhooper · 2026-06-23T14:49:47Z

+        dims = [ywp, xwp]
+        if not np.isnan(zwp):
+            dims.append(zwp)
+        input_dims = dims.copy()
+        output_dims = dims.copy()
+        if not np.isnan(twp):
+            input_dims.append(twp)
+            output_dims.insert(0, twp)
+        input_cube.transpose(np.argsort(input_dims))
+        output_cube.transpose(np.argsort(output_dims))


This might be slightly more readable.

Suggested change

dims = [ywp, xwp]

if not np.isnan(zwp):

dims.append(zwp)

input_dims = dims.copy()

output_dims = dims.copy()

if not np.isnan(twp):

input_dims.append(twp)

output_dims.insert(0, twp)

input_cube.transpose(np.argsort(input_dims))

output_cube.transpose(np.argsort(output_dims))

input_dims = [ywp, xwp, zwp, twp]

output_dims = [twp, ywp, xwp, zwp]

for coord in [zwp, twp]:

if np.isnan(coord):

input_dims.remove(coord)

output_dims.remove(coord)

input_cube.transpose(np.argsort(input_dims))

output_cube.transpose(np.argsort(output_dims))

brhooper

Thanks @mo-AliceLake, one additional comment that I should have added yesterday. I think the unit tests look fine.

brhooper · 2026-06-24T12:15:04Z

+            mode:
+                Which correction(s) to apply: "hc_and_rc" (default), "hc", or "rc".


One more thought: it might be worth explicitly defining what each of rc, hc, and hc_and_rc actually do.

mo-AliceLake added 13 commits February 26, 2026 11:30

Updating wind downscaling code to use more descriptive variable names…

2325556

… and function names, etc

Adding name to CLA

51746cf

Adding myself to .mailmap

3f6e5eb

Adding myself to .mailmap

b4c87a3

Adding myself to .mailmap

15d46d8

Adding myself to .mailmap

d6e4f82

Trying without space

d2ba8a2

Fixing unit tests

1b26277

Merging master

cabd6c1

Updating error log message

4a62b37

Attempting to fix .mailmap by using anon github email

f7fedbe

Initial commit to split out HC + RC

3523995

Renaming tests to make them more descriptive

a473594

mo-AliceLake mentioned this pull request Mar 10, 2026

Updating wind downscaling code to be more descriptive #2315

Merged

3 tasks

mo-AliceLake added 3 commits March 10, 2026 11:44

Working on unit tests

8eba0d8

Changing u* -> u_star for clarity

e9b756a

Changing missing spatial coordinates to match old behaviour

b5645d0

mo-AliceLake changed the base branch from master to feature_update_wind_downscaling March 10, 2026 14:12

mo-AliceLake added 6 commits March 10, 2026 15:02

Update cli

9d4e85d

Merging in master

f057682

Merging in updates from alice-update-winddownscaling

bed4a6b

Changing name in __init__.py

ca1c871

Making RC fail when no roughness length supplied

38b34bf

Updating tests

41f9625

mo-AliceLake force-pushed the alice-split-winddownscaling branch from 82e18ff to 41f9625 Compare March 11, 2026 16:10

mo-AliceLake added 5 commits March 11, 2026 16:26

Updating docstrings of unit tests to match test names

9c2ea8b

Making variable names clearer

adace4c

Removing duplicate entry

ebe6e91

Updating variable names to be more intuitive

ccfad17

Improving variable names and docstrings

b1db175

mo-AliceLake added 5 commits April 29, 2026 13:09

Updating variable names in unit tests to match code

b570e4a

Merging in updates from other branch

ff3f13c

Merging in latest branch update

be66b9c

Fixing to work with surface data

2dc134e

Merging in master

52261f2

mo-AliceLake changed the base branch from feature_update_wind_downscaling to master June 12, 2026 13:43

mo-AliceLake changed the base branch from master to feature_update_wind_downscaling June 12, 2026 13:43

mo-AliceLake marked this pull request as ready for review June 12, 2026 13:44

Merging in feature branch

03b013f

brhooper requested changes Jun 23, 2026

View reviewed changes

brhooper requested changes Jun 24, 2026

View reviewed changes

		Returns:
		3D float32 array of wind speed after applying RC and HC.

		def _mask_missing_data(self, height_above_orog, wspeed_original):
		"""Return a boolean mask: True where either RC or HC may be applied.


		return valid

		def do_rc(self, height_above_orog, wspeed_original):

		@@ -715,17 +741,30 @@
		uhref_orig, height_above_orog, mask_hc, onemfrac
		)

+        # Mask where missing data in height and wind fields
+        valid = self._mask_missing_data(height_above_orog, wspeed_original)
+        valid[~self.hc_mask] = False
+        # Height correction
+        # Requires wind speed at the reference height, so interpolate first
+        z_ref = 1.0 / self.wavenumber
+        if wspeed_original.ndim == 3 and wspeed_original.shape[2] > 1:
+            uhref_orig = self._interpolate_wspeed_to_height(
+                wspeed_original,
+                height_above_orog,
+                z_ref,
+                valid,
+)
+        else:
+            # Single level (e.g. 10m wind) so no interpolation possible
+            uhref_orig = np.copy(wspeed_original)
+# HC only where u(h_ref) is positive
+valid[uhref_orig <= 0.0] = False
+# Setting this value to 1, is equivalent to setting the
+# Bessel function to 1. (Friedrich, 2016)
+# Example usage if the Bessel function was not set to 1 is:
+# onemfrac = 1.0 - BfuncFrac(nx,ny,nz,heightvec,z_0,waveno, Ustar, UI)
+onemfrac = 1.0
+hc_add = self._calc_height_corr(
+uhref_orig, height_above_orog, valid, onemfrac
+)

		mode:
		Which correction(s) to apply: "hc_and_rc" (default), "hc", or "rc".

Uh oh!

Conversation

mo-AliceLake commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Summary of Changes

Testing

Uh oh!

brhooper left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brhooper left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mo-AliceLake commented Mar 9, 2026 •

edited

Loading