Advertise .xyz attribute instead of .position

Author: brandon-rhodes

CHANGELOG.rst

@@ -9,6 +9,23 @@ Changelog
 Released versions
 -----------------
 
+Next version
+------------
+
+* The documentation now uses the newer name ``.xyz``, which has been
+  quietly supported for around three years, for the
+  :class:`~skyfield.positionlib.ICRF` attribute that was originally
+  named ``.position`` and holds its position vector.  The old name
+  (which will continue to be supported) could lead to code that looked a
+  little redundant, asking for the ``position`` of a ``position``::
+
+    position = mars.at(t)
+    print(position.position)
+
+  So Skyfield now encourages code to ask for ``position.xyz`` instead.
+  Another advantage is that the new name self-documents that it holds a
+  numeric vector with three components.
+
 v1.50 — 2024 February 15
 ------------------------
 

TODO.rst

@@ -97,7 +97,6 @@ forget.
 
 * Several interesting API questions arise because of
   `this Stack Overflow question <https://stackoverflow.com/questions/62654081/path-between-two-topos-locations-determine-latitude-and-longitude-where-a-giv>`_.
-  Should I finally go through with renaming ``.position`` to ``.xyz``?
   Should ``.from_altaz()`` retain observer data
   so that a follow-up ``.altaz()`` returns the same coordinates?
   Should positions fully support math,
@@ -142,9 +141,9 @@ forget.
 
 * Solar eclipses.
 
-* Some users need to add offsets to vectors like .position and .velocity
+* Some users need to add offsets to vectors like .xyz and .velocity
   so should there be some official way to do so?  We should either
-  document the maneuver ``.position = Distance(au=old_position.au +
+  document the maneuver ``.xyz = Distance(au=old_position.au +
   xyz)`` or (gulp!) make ``Distance`` objects susceptible of being
   modified in-place without their various units going out of sync.
 

builders/build_novas_tests.py

@@ -291,7 +291,7 @@ def output_ephemeris_tests():
     def test_position_and_velocity(de405, ts):
         t = ts.tt_jd({jd!r})
         e = de405['earth'].at(t)
-        compare(e.position.au, {pos!r}, 10 * meter)
+        compare(e.xyz.au, {pos!r}, 10 * meter)
         compare(e.velocity.au_per_d, {vel!r}, 1e-5 * meter / one_second)
 
     """)
@@ -316,7 +316,7 @@ def test_{slug}_geocentric_date{i}(de405, ts):
             e = de405['earth'].at(t)
             p = de405[{planet!r}]
 
-            distance = length_of((e - p.at(t)).position.au)
+            distance = length_of((e - p.at(t)).xyz.au)
             compare(distance * OLD_AU, {distance1!r}, 0.014 * meter)
 
             astrometric = e.observe(p)

design/broadcasting.py

@@ -17,7 +17,7 @@ def main():
     observer = planets['earth'].at(t)
     target = planets['mars']
     r, v, t2, light_time = cfltt(observer, target)
-    print(t.shape, observer.position.km.shape, r.shape)
+    print(t.shape, observer.xyz.km.shape, r.shape)
 
     print('==== N times, one observer, one target ====')
 
@@ -26,7 +26,7 @@ def main():
     observer = planets['earth'].at(t)
     target = planets['mars']
     r, v, t2, light_time = cfltt(observer, target)
-    print(t.shape, observer.position.km.shape, '->', r.shape)
+    print(t.shape, observer.xyz.km.shape, '->', r.shape)
     print('Here is where the planet wound up:')
     print(r)
 
@@ -45,17 +45,17 @@ def main():
         earth._at = build_multi_at(earth._at)
 
     observer = earth.at(t)
-    print('observer', observer.position.au.shape)
+    print('observer', observer.xyz.au.shape)
 
     target = planets['mars']
     target._at = build_multi_at(target._at)  # Turn Mars into 2 planets.
-    print('target', target.at(t).position.au.shape)
+    print('target', target.at(t).xyz.au.shape)
 
     # t = ts.tt(t.tt[:,None])  # What if we add a dimension to t?
     # print('t', t.shape)
 
     r, v, t2, light_time = _correct_for_light_travel_time2(observer, target)
-    print(t.shape, observer.position.km.shape, '->', r.shape)
+    print(t.shape, observer.xyz.km.shape, '->', r.shape)
 
     print('Does it look like a second planet 1 AU away at the same 4 times?')
     print('First planet:')
@@ -74,17 +74,17 @@ def main():
         earth = planets['earth']
         earth._at = build_multi_at(earth._at)
     observer = earth.at(t)
-    print('observer', observer.position.au.shape)
+    print('observer', observer.xyz.au.shape)
 
     target = planets['mars']
     target._at = build_multi_at(target._at)  # Turn Mars into 2 planets.
-    print('target', target.at(t).position.au.shape)
+    print('target', target.at(t).xyz.au.shape)
 
     # t = ts.tt(t.tt[:,None])  # What if we add a dimension to t?
     # print('t', t.shape)
 
     r, v, t2, light_time = _correct_for_light_travel_time3(observer, target)
-    print(t.shape, observer.position.km.shape, '->', r.shape)
+    print(t.shape, observer.xyz.km.shape, '->', r.shape)
 
     print('Does it look like a second planet 1 AU away at the same 4 times?')
     print('First planet:')
@@ -109,15 +109,15 @@ def main():
 
     earth = planets['earth']
     observer = earth.at(t)
-    print('observer', observer.position.au.shape)
+    print('observer', observer.xyz.au.shape)
     print('Supplementing dimensions')
-    observer.position.au = observer.position.au[:,:,None]
+    observer.xyz.au = observer.xyz.au[:,:,None]
     observer.velocity.au_per_d = observer.velocity.au_per_d[:,:,None]
-    print('observer', observer.position.au.shape)
+    print('observer', observer.xyz.au.shape)
 
     target = planets['mars']
     target._at = build_multi_at(target._at)  # Turn Mars into 2 planets.
-    print('target', target.at(t).position.au.shape)
+    print('target', target.at(t).xyz.au.shape)
 
     # TODO: if we work out how we can expand the time's dimensions, as
     # in the following line, before earth.at(t) without raising an
@@ -130,7 +130,7 @@ def main():
     # print('t !!!!!!!!!!!!!!', t.tdb_fraction.shape)
 
     r, v, t2, light_time = _correct_for_light_travel_time4(observer, target)
-    print(t.shape, observer.position.au.shape, '->', r.shape)
+    print(t.shape, observer.xyz.au.shape, '->', r.shape)
 
     print('Does it look like a second planet 1 AU away at the same 4 times?')
     print('First planet:')
@@ -180,7 +180,7 @@ def _correct_for_light_travel_time(observer, target):
     whole = t.whole
     tdb_fraction = t.tdb_fraction
 
-    cposition = observer.position.au
+    cposition = observer.xyz.au
     cvelocity = observer.velocity.au_per_d
 
     tposition, tvelocity, gcrs_position, message = target._at(t)
@@ -222,7 +222,7 @@ def _correct_for_light_travel_time2(observer, target):
     whole = t.whole
     tdb_fraction = t.tdb_fraction
 
-    cposition = observer.position.au
+    cposition = observer.xyz.au
     cvelocity = observer.velocity.au_per_d
 
     tposition, tvelocity, gcrs_position, message = target._at(t)
@@ -276,7 +276,7 @@ def _correct_for_light_travel_time3(observer, target):
     whole = t.whole
     tdb_fraction = t.tdb_fraction
 
-    cposition = observer.position.au
+    cposition = observer.xyz.au
     cvelocity = observer.velocity.au_per_d
 
     cposition = cposition.T
@@ -327,7 +327,7 @@ def _correct_for_light_travel_time4(observer, target):
     whole = t.whole
     tdb_fraction = t.tdb_fraction
 
-    cposition = observer.position.au
+    cposition = observer.xyz.au
     cvelocity = observer.velocity.au_per_d
 
     print('======', cposition.shape)

design/satellite_is_sunlit.py

@@ -45,7 +45,7 @@
 sun_km_per_s = distance_sun_travels_in_one_orbit / 10 / 365.25 / 24 / 60 / 60
 print('Sun km/s:', sun_km_per_s)
 
-light_delay_seconds = s2[0].position.length().light_seconds()
+light_delay_seconds = s2[0].xyz.length().light_seconds()
 print('Sample light delay from Sun to Earth (seconds):', light_delay_seconds)
 
 print('How far does the Sun move in that time?')

design/sgp4_parallel.py

@@ -108,15 +108,15 @@ def test_iss():
     satellites = [iss]
     city = Topos('44.0247 N', '88.5426 W')
     for geo1 in positions_for(satellites, city, times):
-        print(geo1.position.km)
+        print(geo1.xyz.km)
     #
     print("Compare to EarthSatellite at():")
     difference = iss - city
     geo2 = difference.at(times)
     #geo2 = iss.at(times)
-    print(geo2.position.km)
+    print(geo2.xyz.km)
     #
-    assert np.allclose(geo1.position.km, geo2.position.km)
+    assert np.allclose(geo1.xyz.km, geo2.xyz.km)
     one_m_per_hour = 1.0 * 24.0 / AU_M
     assert abs(geo1.velocity.au_per_d - geo2.velocity.au_per_d).max() < one_m_per_hour
 
@@ -136,8 +136,8 @@ def test_two_sats():
     kestrel1, iss1 = positions
     iss2 = (iss - city).at(times)
     kestrel2 = (kestrel - city).at(times)
-    assert np.allclose(iss1.position.km, iss2.position.km)
-    assert np.allclose(kestrel1.position.km, kestrel2.position.km)
+    assert np.allclose(iss1.xyz.km, iss2.xyz.km)
+    assert np.allclose(kestrel1.xyz.km, kestrel2.xyz.km)
     assert np.allclose(iss1.velocity.au_per_d, iss2.velocity.au_per_d)
     assert np.allclose(kestrel1.velocity.au_per_d, kestrel2.velocity.au_per_d)
 

design/subpoint_accuracy.py

@@ -23,7 +23,7 @@ def main():
             for degrees in trial_angles:
                 top = Topos(latitude_degrees=degrees, longitude_degrees=123,
                             elevation_m=elevation_m)
-                xyz_au = top.at(t).position.au
+                xyz_au = top.at(t).xyz.au
                 xyz_au = einsum('ij...,j...->i...', t.M, xyz_au)
                 lat, lon, elev = reverse_terra(xyz_au, t.gast, n)
                 lat = lat / DEG2RAD

documentation/api.rst

@@ -328,7 +328,7 @@ Astronomical positions
 
 The `ICRF` three-dimensional position vector serves as the base class
 for all of the following position classes.  Each class represents an
-|xyz| ``.position`` and ``.velocity`` vector oriented to the axes of
+|xyz| ``.xyz`` and ``.velocity`` vector oriented to the axes of
 the International Celestial Reference System (ICRS),
 an inertial system that’s an update to J2000
 and that does not rotate with respect to the universe.
@@ -364,7 +364,7 @@ All position objects offer five basic attributes:
 .. PAT START
 
 ============= ========================================
-``.position`` An |xyz| `Distance`.
+``.xyz``      An |xyz| `Distance`.
 ``.velocity`` An |xyz| `Velocity`, or ``None``.
 ``.t``        The `Time` of the position, or ``None``.
 ``.center``   Body the vector is measured from.
@@ -373,6 +373,9 @@ All position objects offer five basic attributes:
 
 .. PAT END
 
+The ``.xyz`` attribute used to be named ``.position``.  To support older
+code, Skyfield will always recognize the original name as an alias.
+
 All positions support these methods:
 
 .. autosummary::

documentation/astropy.rst

@@ -59,7 +59,7 @@ between the two libraries:
       t = ts.utc(1980, 1, 1)
       barycentric = earth.at(t)
 
-      print(barycentric.position.to(u.au))
+      print(barycentric.xyz.to(u.au))
       print(barycentric.velocity.to(u.au / u.day))
 
    .. testoutput::

documentation/earth-satellites.rst

@@ -508,7 +508,7 @@ than those of the old J2000 system.)
    t = ts.utc(2014, 1, 23, 11, 18, 7)
 
    geocentric = satellite.at(t)
-   print(geocentric.position.km)
+   print(geocentric.xyz.km)
 
 .. testoutput::
 
@@ -586,7 +586,7 @@ as plain |xyz| coordinates:
 .. testcode::
 
    topocentric = difference.at(t)
-   print(topocentric.position.km)
+   print(topocentric.xyz.km)
 
 .. testoutput::
 
@@ -928,12 +928,12 @@ that are limiting this TLE set’s predictions:
 
     geocentric = sat.at(ts.utc(2013, 11, 9))
     print('Before:')
-    print(geocentric.position.km)
+    print(geocentric.xyz.km)
     print(geocentric.message)
 
     geocentric = sat.at(ts.utc(2013, 11, 13))
     print('\nAfter:')
-    print(geocentric.position.km)
+    print(geocentric.xyz.km)
     print(geocentric.message)
 
 .. testoutput::

documentation/examples.rst

@@ -752,11 +752,11 @@ to both Accra, Ghana, and the top of Mount Bierstadt in Colorado.
    t = ts.utc(2019, 1, 1)
 
    bierstadt = wgs84.latlon(39.5828 * N, 105.6686 * W, elevation_m=4287.012)
-   m1 = length_of(bierstadt.at(t).position.m)
+   m1 = length_of(bierstadt.at(t).xyz.m)
    print(int(m1))
 
    accra = wgs84.latlon(5.6037 * N, 0.1870 * W, elevation_m=61)
-   m2 = length_of(accra.at(t).position.m)
+   m2 = length_of(accra.at(t).xyz.m)
    print(int(m2))
 
    assert m2 > m1

documentation/index.rst

@@ -82,7 +82,7 @@ and return results in native AstroPy units:
 .. testcode::
 
     from astropy import units as u
-    xyz = astrometric.position.to(u.au)
+    xyz = astrometric.xyz.to(u.au)
     altitude = alt.to(u.deg)
 
     print(xyz)

documentation/positions.rst

@@ -224,7 +224,7 @@ They support operations like:
 
 .. testcode::
 
-    print('Earth x,y,z:', barycentric.position.au, 'au')
+    print('Earth x,y,z:', barycentric.xyz.au, 'au')
     print('Mars relative velocity:', astrometric.velocity.km_per_s, 'km/s')
     print('Time of observation:', apparent.t.utc_strftime())
 

documentation/time.rst

@@ -540,7 +540,7 @@ We can compute the position of the Earth as an example:
     earth = planets['earth']
 
     t = ts.utc(2014, 1, 1)
-    pos = earth.at(t).position.au
+    pos = earth.at(t).xyz.au
     print(pos)
 
 .. testoutput::
@@ -553,7 +553,7 @@ We can compute the position of the Earth as an example:
 
     days = [1, 2, 3, 4]
     t = ts.utc(2014, 1, days)
-    pos = earth.at(t).position.au
+    pos = earth.at(t).xyz.au
     print(pos)
 
 .. testoutput::

skyfield/elementslib.py

@@ -42,10 +42,10 @@ def osculating_elements_of(position, reference_frame=None, gm_km3_s2=None):
                     ' should specify one using the `gm_km3_s2` keyword argument')
 
     if reference_frame is not None:
-        position_vec = Distance(reference_frame.dot(position.position.au))
+        position_vec = Distance(reference_frame.dot(position.xyz.au))
         velocity_vec = Velocity(reference_frame.dot(position.velocity.au_per_d))
     else:
-        position_vec = position.position
+        position_vec = position.xyz
         velocity_vec = position.velocity
 
     return OsculatingElements(position_vec,