Enhance TC-RMW to compute tangential and radial winds.

[JohnHalleyGotway]

Describe the Enhancement

When preparing training material for the MET-TC tools and also applying it for the unified physics testing and evaluation project, @KathrynNewman found that the TC-RWM tool does not actually perform the steps that the documentation claims it does. Namely, it does not compute and report tangential and radial winds. Looking at the tc_rmw.cc source code, I agree with her.

While the wind_ne_to_ra() function looks like logic for winds, that function is never actually being called! Instead process_fields() just loops over the requested fields but includes no special logic for handling U and V.

Reading this, tc_rmw chapter of the User's Guide, I agree that the functionally does not match the documentation. This needs more work.

This task is enhance the TC-RMW tool to compute and report tangential and radial winds. Listing @KathrynNewman as an assignee so that she can advise on and help test the development.

Time Estimate

2 days

Sub-Issues

Consider breaking the enhancement down into sub-issues.
No sub-issues needed.

Relevant Deadlines

List relevant project deadlines here or state NONE.

Funding Source

2793451 - based on guidance on Kathryn

Define the Metadata

Assignee

• Select engineer(s) or no engineer required
• Select scientist(s) or no scientist required

Labels

• Select component(s)
• Select priority
• Select requestor(s)

Projects and Milestone

• Select Repository and/or Organization level Project(s) or add alert: NEED PROJECT ASSIGNMENT label
• Select Milestone as the next official version or Future Versions

Define Related Issue(s)

Consider the impact to the other METplus components.

• METplus, MET, METdatadb, METviewer, METexpress, METcalcpy, METplotpy
  None.

Enhancement Checklist

See the METplus Workflow for details.

• Complete the issue definition above, including the Time Estimate and Funding Source.
• Fork this repository or create a branch of develop.
  Branch name: feature_<Issue Number>_<Description>
• Complete the development and test your changes.
• Add/update log messages for easier debugging.
• Add/update unit tests.
• Add/update documentation.
• Push local changes to GitHub.
• Submit a pull request to merge into develop.
  Pull request: feature <Issue Number> <Description>
• Define the pull request metadata, as permissions allow.
  Select: Reviewer(s) and Linked issues
  Select: Repository level development cycle Project for the next official release
  Select: Milestone as the next official version
• Iterate until the reviewer(s) accept and merge your changes.
• Delete your fork or branch.
• Close this issue.

[davidalbo]

Email from @KathrynNewman:

Yes, that is the expected behavior: if you provide winds (UGRD and VGRD), the calculation for tangential and radial wind should occur and appear in the output file. Ideally, the variable name in the output .nc file would change to be descriptive (vt = tangential, vr = radial, would be logical). If you don't provide UGRD and VGRD, you should get an error that both are required. Does that make sense? I'd be happy to provide example data if that would be helpful!

I've got it to where I can run in the debugger. @KathrynNewman if you can give me an example I can move forward. Needed would be input data, command line you'd use, and config file/files. If I make changes and test, I could give you the output to look at.

[KathrynNewman]

@davidalbo, Great! Where would it be best to put the input file, etc? I'm currently running tc-rmw on Hera (NOAA), but I can easily move a sample down to a RAL machine (Seneca? Kiowa?) for you.

[davidalbo]

@KathrynNewman You can try putting everything here:

seneca:/d1/personal/dave/test-issue2072

If you can't write there, somewhere else on seneca where I can get to would be fine.

[KathrynNewman]

@davidalbo - I couldn't write there, so I put the example case files under my space on seneca:/d1/personal/knewman/test-issue2072

Let me know if you have any questions!

[davidalbo]

@KathrynNewman I can see everything, looks like I want to create this netCDF file:

florence06l.2018090700.fv3r_13km.nc

I can make changes until I can see that I've put the new fields into it, then hand off to you to view and give thumbs up or down.

[davidalbo]

@KathrynNewman please have a look at this on seneca:

/d1/personal/dave/florence06l.2018090700.fv3r_13km.nc

It's a first rough version, may or may not look reasonable.
New fields in the netcdf output flle:

double VR(range, azimuth, pressure, track_point) ;
	VR:long_name = "Radial Velocity" ;
	VR:units = "m/s" ;
	VR:_FillValue = -9999. ;
double VT(range, azimuth, pressure, track_point) ;
	VT:long_name = "Tangential Velocity" ;
	VT:units = "m/s" ;
	VT:_FillValue = -9999. ;

I created data that had the same grid dimensions as most of the other outputs.
Dave

[KathrynNewman]

@davidalbo - I took a look at the sample file. The new fields look good, those names and grid dimensions work. I am a little confused by Vt - I'm seeing negative values, which doesn't seem right... I believe it should be all positive. How is Vt being calculated?

[davidalbo]

@KathrynNewman I'll hit this hard next week, on another project till then. I'm just guessing, would have to look into the calculations, could it be that if you were looking out a radial the tangential wind could be to the right positive or to the left negative? Or the other way around? I could easily be misinterpreting completely.

[KathrynNewman]

Sounds good. I think you are thinking about it correctly when considering a fixed coordinate system. But for the Tropical Cyclone community, the definition is 'the component of the velocity directed along the velocity vector/streamline'. Therefore, by definition it needs to be positive. This is using natural coordinates - so always following the flow.

for Vr, it's always the direction perpendicular to the tangential winds, so here it could be positive or negative.

[jvigh]

Hi Katherine and Dave -- I couldn't help but track along on this discussion.

What Kathryn says applies to natural coordinate systems, however I think the relevant coordinate system for this tool should be a cylindrical coordinate system. In that system, as conventionally applied to tropical cyclones, tangential wind is considered positive in the cyclonic wind direction. So if your back is to the center and you're looking out along a radial, wind going from your right to your left would have a positive tangential velocity in the Northern Hemisphere. In the Southern Hemisphere, wind going from your left to your right would have positive tangential velocity. I just wanted to bring this up to make sure the tool works correctly in both hemispheres.

It is theoretically possible to have negative tangential wind velocity in this coordinate system. Imagine an embedded eyewall mesovortex whose velocity magnitude is larger than the eyewall velocity that is advecting it. In that case, there could be a region where the tangential wind speed could be negative in this coordinate system.

I'm tagging Chris Rozoff and Eric Hendricks who are also TC experts to see if they'd like to add anything. @cmrozoff @eahendricks

I hope this helps!

[davidalbo]

Interesting. I'll share the algorithm that does the conversion when I have time to get in there and take a good look.

[KathrynNewman]

Thanks for weighing in, Jonathan. It's important to make sure we are consistent with the expectations of the user community. Bottom line - the current file has equal magnitude oscillating positive/negative values of Vt, which requires some further attention.

[davidalbo]

Wondering if this capability was never fully implemented or tested. I'm getting what seems like bugs running it slowly through the debugger, using the existing conversion method.

The first point in the input (path?) has a lat,lon of 25,50 which converts to range_km=NAN and azimuth_deg=54.95. Obviously the NAN is problematic. Also the first point has input U,V values of -9999, -9999 which get used as is, no checking for missing data, which I'm assuming -9999 indicates, which is also problematic.

It's either buggy or some problem with the input config or data compared to the code, or it is designed so that NAN's and missing data somehow 'just works'.

[davidalbo]

I think I've isolated the 'NAN' problem. In the file earth_rotation.cc line 102:

https://github.com/dtcenter/MET/blob/main_v10.1/met/src/libcode/vx_grid/earth_rotation.cc#L102

the call to SO3:forward returns z_rot = 1.0000000000000007

which looks to me like a precision roundoff sort of error, it should probably be 1.0.
Something to do with the particulars of this rotation.

The next line method: id_xyz_to_latlon() tries to take asind(1.0000000000000007) which returns NAN.

Possible solutions are to modify this file and test for z_rot values very close to 1.0 or -1.0 and change them if so to 1.0 or -1.0, or to detect the NAN further up in the app and set the outputs to missing if a NAN is seen.

[davidalbo]

@JohnHalleyGotway , @jprestop I'm looking into adding some additional config parameters to make it optional to convert the UV winds to radial/tangential winds for this app. Diving into the code it seems maybe a little bigger change than I'd thought it might be, needing changes to the app code AND library code too. Is there any online documentation on adding a parameter to a config file, or can someone guide me through doing this kind of change? I want to do this in a way consistent with the overall MET way (if I do it at all).

[JohnHalleyGotway]

@davidalbo there is no documentation which details the steps needed to add a new config file option. However, I can point you to a recent example where I did something similar. GitHub issue #1870 was fixed by PR #1893. And you can see the list of 18 modified files for that PR here.

These files include changes to the default config file and config files in the test directory, adding the option to the vx_config library, updating the user's guide documentation, and adding a new test to exercise the new options.

That should point you in the right direction. Please let me know if you have additional questions.

Also note that adding a new config option to MET will require a new METplus issue to make that new option configurable.

[davidalbo]

@JohnHalleyGotway looking into this now. It makes sense, I should be able to mimic the pattern for changes you made. I've never used rst format before, but emacs recognizes it, so maybe I can just cut/paste/edit things in emacs to add content to those files that looks like what is already in them. Any other wisdom on editing rst?

[JohnHalleyGotway]

Restructured Text (rst) is just a lightweight markup language in ASCII. I'd recommend just copy/paste/editing existing content to get the formatting.

Here's my one piece of advice... after committing changes to the documentation in rst and pushing them up to GitHub, Read-The-Docs will automatically go rebuild/rerender the docs for you. Here's the link to the docs for your feature branch:
https://met.readthedocs.io/en/feature_2072_tc_rmw_winds/

So make edits, commit them, push them to GitHub, wait a few minutes, and then double-check that link to make sure they rendered how you expect.

If not, @jprestop or @lisagoodrich can probably help you figure out what went wrong.

[davidalbo]

I'm about done with this issue. I'd like to get something installed for the next release that improves on what we had before, which was that it did nothing at all.

• I ended up putting the wind conversion into it's own C++ class, because embedding it in the main algorithm was getting too complex.
• Unit test updates were successful.
• I tested various settings for the new configuration parameters with behavior as expected. Here are the defaults:

//
// Optionally convert u/v winds to tangential/radial winds
//
compute_tangential_and_radial_winds = TRUE;
u_wind_field_name = "UGRD";
v_wind_field_name = "VGRD";
tangential_velocity_field_name = "VT";
tangential_velocity_long_field_name = "Tangential Velocity";
radial_velocity_field_name = "VR";
radial_velocity_long_field_name = "Radial Velocity";

The user can control whether to do the computation or not, and what to expect as inputs, and what to use for output naming.

Two things still seem important based on the comments within this issue:

1. "Adding a new config option to MET will require a new METplus issue to make that new option configurable". Who does that?
2. " I'm seeing negative values, which doesn't seem right... I believe it should be all positive". If it is indeed problematic to have both positive and negative tangential winds, the users can/should create a new issue for that problem as a bug to be fixed.

[JohnHalleyGotway]

@davidalbo, you can just communicate with @georgemccabe and point out what changes you've made to the MET config files. Then he can handle the updates to the METplus wrappers.

[davidalbo]

Hey @georgemccabe is this all you need for METplus wrappers? These are new config file option in tc_rmw.

//
// Optionally convert u/v winds to tangential/radial winds
//
compute_tangential_and_radial_winds = TRUE;
u_wind_field_name = "UGRD";
v_wind_field_name = "VGRD";
tangential_velocity_field_name = "VT";
tangential_velocity_long_field_name = "Tangential Velocity";
radial_velocity_field_name = "VR";
radial_velocity_long_field_name = "Radial Velocity";

[georgemccabe]

@davidalbo , I created a METplus issue to add support for the new config variables through the wrapper.