EHN: Vectorising gate2geographic_location()

[billetd]

Scope

This PR vectorises the gate2geographic_location() function, and all relevant child functions (including geocentric conversion and virtual height model functions) to enable calculations of multiple beam/range combos at once. I wanted this for a project I'm working on because I end up iterating over a lot of different range gates. This provides a big speed up that scales the more beams/gates you need. This touches a fair few different spots, mostly just to ensure it handles both numpy arrays OR single scalars. This means it should not affect any upstream code that also uses these functions.

Currently, this makes the assumption that all the beams/gates come from the same radar and record (constant stid, rsep, and frang). It could be updated to handle that down the line, but that would be a lot more work.

Approval

Number of approvals: 2

Test

import pydarn
import numpy as np
from pydarn.utils.coordinates import gate2geographic_location

fitacf_file = '/Volumes/The Box/FBI/test/fitacfs/2025/01/20250131.2000.00.inv.a.fitacf'
fitacf_data, _ = pydarn.read_fitacf(fitacf_file)

# Station ID
stid = fitacf_data[0]['stid']
stid_enum = pydarn.RadarID(stid)

# Other required info
rsep = fitacf_data[0]['rsep']
frang = fitacf_data[0]['frang']

# Get coordinates of a single beam/gate - reproduces existing functionaility
lat_single, lon_single = gate2geographic_location(
    stid=stid_enum, beam=7, range_gate=62,
    height=300, center=True, rsep=rsep, frang=frang,
    virtual_height_model=pydarn.VHModels.CHISHAM
)

print(lat_single)
print(lon_single)

# Get coordinates of multiple beams/gates at once
beams = np.array([14, 2, 7])
ranges = np.array([12, 54, 62])
lat_multiple, lon_multiple = gate2geographic_location(
    stid=stid_enum, beam=beams, range_gate=ranges,
    center=True, rsep=rsep, frang=frang,
    virtual_height_model=pydarn.VHModels.CHISHAM
)

print(lat_multiple)
print(lon_multiple)

Output:

79.0786759977364
-44.99405343894708
[71.52700326 86.07959106 79.078676  ]
[-118.79550748  -59.52516538  -44.99405344]

To show this produces the exact same results as before, you can run this test code on the develop branch (for the single beam/gate only):

import pydarn
import numpy as np
from pydarn.utils.coordinates import gate2geographic_location

fitacf_file = '/Volumes/The Box/FBI/test/fitacfs/2025/01/20250131.2000.00.inv.a.fitacf'
fitacf_data, _ = pydarn.read_fitacf(fitacf_file)

# Station ID
stid = fitacf_data[0]['stid']
stid_enum = pydarn.RadarID(stid)

# Other required info
rsep = fitacf_data[0]['rsep']
frang = fitacf_data[0]['frang']

# Get coordinates of a single beam/gate
lat_single, lon_single = gate2geographic_location(
    stid=stid_enum, beam=7, range_gate=62,
    height=300, center=True, rsep=rsep, frang=frang,
    virtual_height_model=pydarn.VHModels.CHISHAM
)

print(lat_single)
print(lon_single)

Output:

79.0786759977364
-44.99405343894708

[carleyjmartin]

Code looks fine, I'll test when I can.

We should maybe think about why it's returning the values to different significant figures, and maybe decide on the sig fig we want to use.