CHANGELOG.rst

@@ -9,6 +9,62 @@ Changelog
 Released versions
 -----------------
 
+v1.51 — 2024 February 23
+------------------------
+
+* Skyfield now supports ephemeris files like ``de441.bsp`` that have two
+  or more segments per target.  In earlier versions of Skyfield, only
+  one segment per target would get used, which for ``de441.bsp`` was
+  cutting the range of supported dates in half.
+  `#691 <https://github.com/skyfielders/python-skyfield/issues/691>`_
+
+* 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)
+    x, y, z = position.position
+
+  So Skyfield now encourages code to ask for ``position.xyz`` instead.
+  An advantage is that the new name is self-documenting: the name
+  reminds the user that it is a 3-vector of Cartesian components.
+
+* Skyfield’s internal table for the ∆T Earth orientation parameter has
+  been updated, so that its predictions now extend to 2026-02-28.
+
+* Fix: the :meth:`~skyfield.sgp4lib.EarthSatellite.find_events()` Earth
+  satellite method was returning an empty list of events if the only
+  event in the time period was a lone rising or setting.  It should now
+  detect and return them.
+  `#856 <https://github.com/skyfielders/python-skyfield/issues/856>`_
+  `#996 <https://github.com/skyfielders/python-skyfield/issues/996>`_
+  `#1017 <https://github.com/skyfielders/python-skyfield/issues/1017>`_
+
+* Fix: the :meth:`~skyfield.sgp4lib.EarthSatellite.find_events()` Earth
+  satellite method, faced with a single pass that was very close to the
+  start time, was returning an inaccurate setting time.  It should now
+  return an accurate setting time.
+  `#1000 <https://github.com/skyfielders/python-skyfield/issues/1000>`_
+
+* Fix: the :meth:`~skyfield.sgp4lib.EarthSatellite.find_events()` Earth
+  satellite method would miss a rising that came a fraction of a second
+  before the corresponding culmination.  It should now find both.
+  `#559 <https://github.com/skyfielders/python-skyfield/issues/559>`_
+
+* Fix: bodies with Kepler orbits (like comets and asteroids) were
+  incorrectly returning positions with only a single dimension if given
+  a :class:`~skyfield.timelib.Time` that was an array but had only one
+  element.  This could cause the rising and setting almanac routines to
+  raise a ``ValueError`` if they found only a single rising or setting.
+  `#959 <https://github.com/skyfielders/python-skyfield/issues/959>`_
+
+* Fix: the position vectors for Kepler orbit bodies, like comets and
+  asteroids, now have a useful ``.target_name`` like ``'Ceres'`` or
+  ``'1P/Halley'`` instead of the less informative value ``'str'``.
+
 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.
 
@@ -191,3 +190,10 @@ Adding more smarts to ephemeris handling
   need to be vectorized and updated to use a Skyfield approach to vector
   and matrix operations.  When complete and documented, make a comment
   at: https://github.com/skyfielders/python-skyfield/issues/350
+
+* Maybe someday keep notes on ‘the story of Skyfield’ somewhere in the
+  repository, for details I later forget — like the fact I just
+  rediscovered, that an ephemeris object like ``earth`` used to have
+  methods ``.geometry_of(another_body)``, ``.topos(...)``, and
+  ``.satellite(...)``, all of which went away once the concept of vector
+  addition and subtraction were added to Skyfield.

bin/build

@@ -1,14 +1,25 @@
 #!/bin/bash
 
-set -ex
+set -e
 
 cd "$(readlink -f $(dirname "${BASH_SOURCE[0]}"))"
 cd ..
 
-# Alas!  Unless we 'rm' the build/ directory first, the wheel will
-# include old files that are no longer part of Skyfield but that are
-# left over from previous builds.
-rm -rf build/
+echo
+echo 'Have you remembered to rebuild the delta-T tables?'
+echo
 
-python setup.py sdist $@
-SKYFIELD_USE_SETUPTOOLS=yes python setup.py bdist_wheel $@
+echo 'Looking for bad file permissions...'
+bad=$(
+    find skyfield -type f ! -perm -644
+    find skyfield -type d ! -perm -755
+)
+if [ -n "$bad" ]
+then
+    ls -ld $bad
+    exit 1
+fi
+echo 'Everything looks good!'
+echo
+
+PYTHONDONTWRITEBYTECODE= uv build

bin/test-pythons

@@ -0,0 +1,27 @@
+#!/bin/bash
+
+set -e
+
+cd "$(readlink -f $(dirname "${BASH_SOURCE[0]}"))"
+cd ..
+
+./bin/build
+
+for version in 3.7 3.13
+do
+    echo
+    echo $version
+    echo
+    venv=.tox/$version
+    if [ ! -d $venv ]
+    then
+        uv venv --python $version $venv
+    fi
+    source $venv/bin/activate
+    pushd ci
+    uv pip install pytz pandas
+    uv pip install ../dist/skyfield-1.51-py3-none-any.whl
+    uv pip install ~/assay
+    assay --batch skyfield.tests
+    popd
+done

builders/build_arrays.py

@@ -44,11 +44,10 @@ def main(argv):
         url = 'https://maia.usno.navy.mil/ser7/finals2000A.all'
         f = load.open(url)
     with f:
-        utc_mjd, dut1 = iers.parse_dut1_from_finals_all(f)
-
+        finals2000A = iers.parse_x_y_dut1_from_finals_all(f)
 
     daily_tt, daily_delta_t, leap_dates, leap_offsets = (
-        iers.build_timescale_arrays(utc_mjd, dut1)
+        iers.build_timescale_arrays(finals2000A['utc_mjd'], finals2000A['dut1'])
     )
 
     # Removing the 1.0 increment between terms offers vastly improved

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