FHD-style beam decomposition

[bhazelton]

Description

Add support for two new types of beams which are the two parts that FHD decomposes Jones matrices (E-field beams) into.
While these are needed by FHD, I suspect they might be more broadly useful to other simulators as well. I currently need them for pyFHD and it really makes the most sense to implement them on UVBeam because the decomposition needs to be done before interpolation.

The two new types of beams are:

• The projection from celestial polarization vector components (orthogonal on the sky) to instrumental polarization vector components (the directions of maximal feed response which are generally non-orthogonal on the sky). This is similar to a rotation matrix, but is not unitary because the feed aligned vector components are not orthogonal in all directions on the sky. This is currently called feed_aligned_projection but I'm open to other names.
• The complex, direction dependent response of each feed to electric fields aligned with the feed. This is currently called feed_aligned_response but I'm open to other names.

This PR adds support for these two new kinds of beams to UVBeam, AnalyticBeam and BeamInterface objects.

To Do:

• update the tutorial (not sure how much to do here)
• update the changelog

The math describing this decomposition is laid out in this memo: https://www.overleaf.com/read/wzbkxghywnyp#cb19bc

All comments or questions on the memo are very welcome!

Motivation and Context

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation change (documentation changes only)
• Version change
• Build or continuous integration change
• Other

Checklist:

• I have read the contribution guide.
• My code follows the code style of this project.

New feature checklist:

• I have added or updated the docstrings associated with my feature using the numpy docstring format.
• I have updated the tutorial to highlight my new feature (if appropriate).
• I have added/updated tests to cover my new feature.
• I have updated the CHANGELOG.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.93%. Comparing base (74f1b92) to head (c5f68a6).

Additional details and impacted files

@@           Coverage Diff            @@
##             main    #1641    +/-   ##
========================================
  Coverage   99.93%   99.93%            
========================================
  Files          67       67            
  Lines       22848    22983   +135     
========================================
+ Hits        22834    22969   +135     
  Misses         14       14            

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[steven-murray]

Can we get a mathematical definition, or link to a definition, here? "Related to time delays" is a little hard to understand :-D

[bhazelton]

Sorry for the long delay, this question prompted me to dramatically improve and expand the existing memo on this to get it to a place where I felt comfortable pointing you to it. It's now linked in the top comment, but I'll put the link here too: https://www.overleaf.com/read/wzbkxghywnyp#cb19bc

I'd appreciate any comments/questions on the memo. I think it's likely to turn into a paper at some point, so I'd like to make sure it's understandable to a wide audience.

[steven-murray]

@bhazelton can I perhaps suggest per_feed_unpolarized_response instead of feed_iresponse? It's more of a mouthful, but more descriptive. I dunno what to call the other.... feed_projection is maybe OK. Projection is not very descriptive, but I honestly don't understand the formulation here well enough to suggest otherwise.

[jpober]

I've read through the associated memo and think I understand what the math is accomplishing here (but admittedly haven't scrutinized the code for its implementation of that math). For names for the two new beam types, I think something like decomp_unpolarized_response and decomp_polarization_projection might be my preference. They're lengthy, but I feel like if you omit the decomp or similar you'll get the user who just sets their beam to unpolarized_response because they don't want to deal with polarization (haha, good luck). I agree with Steven that iresponse isn't sufficient, since with lower case i it's very unclear you're referencing Stokes I.

[bhazelton]

I've read through the associated memo and think I understand what the math is accomplishing here (but admittedly haven't scrutinized the code for its implementation of that math). For names for the two new beam types, I think something like decomp_unpolarized_response and decomp_polarization_projection might be my preference. They're lengthy, but I feel like if you omit the decomp or similar you'll get the user who just sets their beam to unpolarized_response because they don't want to deal with polarization (haha, good luck). I agree with Steven that iresponse isn't sufficient, since with lower case i it's very unclear you're referencing Stokes I.

Thanks Jonnie! As I wrote that memo, my thinking and explanation of the two components evolved. I just updated the description in the top level comment on this PR to reflect my updated language. Given that evolution, I'm inclined to move away from the language around Stokes I or unpolarized response. What about: feed_aligned_response and feed_aligned_projection? Or if you want to keep the decomp prefix we could go with decomp_aligned_response and decomp_aligned_projection?

[jpober]

I don't actually love the sounds of starting things with decomp, I just liked having something that indicates these aren't really stand-alone beam types that the average user should be mucking with. I think your names are complex enough that they'll have the same effect, i.e., the novice user who just wants a "simple" beam won't try and use them.