[WIP] Add optional near-field corrections to the phasing function

[baron-de-montblanc]

Description

Included code to perform near-field corrections through keyword arguments passed to the phase() function.

I added two new keys to the phase_dict dictionary (cat_dist_units and cat_near_field), allowing the user to specify the units associated with the cat_dist key, and whether or not to apply near-field corrections (boolean value). As a result, a lot of tests are breaking because these extra keys didn't exist when they were written. I'm having trouble tracking down every instance of phase_dict to patch this.

It also still isn't clear whether or not an unproject_near_field() function is necessary, so I have left in some commented-out lines of code while I work on figuring this out (to be removed or uncommented when this is resolved).

Motivation and Context

This feature allows users to specify the RA, DEC, and distance to a near-field source, and "focus" on that source (it will then appear in focus in an image, for example). This is done in practice by calculating the geometric near-field w values for each visibility, updating those in the uvw_array, computing the resulting phase differences, and updating the phase directly for each visibility. This feature is turned off by default (i.e. the default behavior for the phase() function is just to perform the traditional far-field phasing).

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

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 tests to cover my new feature.
• All new and existing tests pass.
• I have updated the CHANGELOG.

[bhazelton]

Rather than adding new phase_center_dict keys, let's use a new cat type for near-field phased objects, maybe `"near_field"? Then encourage and support passing a Quantity for distance, but if a scalar is passed interpret it as in meters for near field and parsecs for ephem cat types. Update the docs to be very clear about this.

[github-actions]

⚠️ Performance Alert ⚠️

Possible performance regression was detected for benchmark.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 2.

Benchmark suite	Current: ba8783f	Previous: bca6cf0	Ratio
tests/utils/test_bls.py::test_ants_to_bls[min=4259840-len=10]	215140.27267544658 iter/sec (stddev: 0.000005969824238735253)	434661.1807555354 iter/sec (stddev: 0.0000013012435924847232)	2.02

This comment was automatically generated by workflow using github-action-benchmark.

[codecov]

Codecov Report

Attention: Patch coverage is 13.97849% with 80 lines in your changes missing coverage. Please review.

Project coverage is 99.56%. Comparing base (6da30d9) to head (8819458).

Files with missing lines	Patch %	Lines
src/pyuvdata/utils/phasing.py	12.12%	29 Missing ⚠️
src/pyuvdata/utils/tools.py	9.37%	29 Missing ⚠️
src/pyuvdata/uvdata/uvdata.py	21.42%	22 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1482      +/-   ##
==========================================
- Coverage   99.93%   99.56%   -0.37%     
==========================================
  Files          63       63              
  Lines       21849    21939      +90     
==========================================
+ Hits        21834    21844      +10     
- Misses         15       95      +80     

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