ephem 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f1c6e88ad1dcd62c35cc6e4cff28ee9f119f85480714927a93de144ee27fb999
-  data.tar.gz: 7bc8cb949dac93e4e5aab30624144033323ca8e1e7d337d64cfcb92186dac68e
+  metadata.gz: cef92715e68f52ead4e478fab7cdb01ea71a00fbff55dd8e48ad2367c5fd9148
+  data.tar.gz: 48ea29041ed2507a5f8365dd865fdb08b9c8fdc498b62e492e4f54fbf93db0ff
 SHA512:
-  metadata.gz: 946a9bec06bb68047fde60fed001516e4dc735b7f18869bcf52aca60ce4d1a8c7335c8f679e4dfb7c8ebc248a5cbdff1781876e0882729bd8ce8e3b77692ff8a
-  data.tar.gz: df5949acbd246409f664a2188256652808cd2f9e2aa50c3ea6362a9db19ea7cad89e4d7597bbe34429e5acd6e13556d6b776d0119ec14835fa1db378e5c24dc2
+  metadata.gz: b3164cc106358b4e4289b9887cee06f810d3912493c61ad13dd18d258686a9b86ee640a51cadb42250e57208fd0e822f322b4a1af92dadab788028c2a996401b
+  data.tar.gz: 404dc6bd76f297938f12f3f24a3e1bd36477c32da3bb728bb19aa942a3ed82fb84cb28c99019b3103718580999c9f30eb833d65f9627b9f3a200802116452e47

data/.tool-versions

@@ -1 +1 @@
-ruby 3.4.1
+ruby 4.0.5

data/CHANGELOG.md

@@ -1,10 +1,99 @@
 # Changelog
 
+## [0.5.0] - 2026-06-23
+
+### Features
+
+- Read binary PCK (`DAF/PCK`) orientation kernels via `Ephem::PCK`, exposing a
+  body's Euler angles and rates over time (`angles_at`, `orientation_at`), the
+  foundation for DE440-grade lunar libration ([#76], [#80])
+- Add `Ephem::Core::Orientation` (Euler angles + optional rates) and
+  `Ephem::Core::Rotation` (kernel-agnostic rotation-matrix helpers), plus
+  `Orientation#to_matrix` / `OrientationSegment#matrix_at` for the built-in
+  3-1-3 (Z-X-Z) reference→body convention
+- Excerpt and the `excerpt` CLI now support binary PCK kernels, detecting the
+  kernel kind automatically
+- Download binary PCK lunar orientation kernels from NAIF via `Ephem::Download`
+- Add `#inspect` and `#to_s` to `State` for easier debugging ([#67])
+
+### Improvements
+
+- Route queries to the covering segment when a body/pair spans multiple
+  time-split segments (SPK and PCK), with no overhead for single-segment keys
+- Share the type-2 Chebyshev machinery between SPK and PCK segments
+- Evaluate position and velocity in a single Chebyshev pass
+  (`ChebyshevPolynomial.evaluate_with_derivative`), speeding up every state /
+  orientation query (`compute_and_differentiate`, `state_at`, `orientation_at`)
+  with bit-for-bit identical results
+- Correct the documented velocity unit to km/day (the actual, validated value)
+- Remove the `numo-narray` dependency ([#65])
+- Skip derivative evaluation in `Segment#compute` ([#57])
+- Hoist loop-invariant `t2` computation in Chebyshev evaluation ([#58])
+- Cache the `RecordParser` instance in `SummaryManager` ([#63])
+- Eliminate a redundant `read_record` call in `SummaryManager` ([#62])
+- Replace duplicated endianness format lookups with shared constants ([#64])
+- Replace `instance_variable_get` with proper `attr_reader`s in `Excerpt`
+  ([#66])
+- Use separate error margins for position and velocity validation ([#61])
+- Add a comprehensive benchmark suite ([#68])
+- Upgrade default Ruby to 4.0.5 ([#81])
+- Match SPICE last-loaded-wins precedence for overlapping segments ([#83])
+- Add a dedicated spec for the shared type-2 Chebyshev evaluation ([#84])
+- Bump standard from 1.50.0 to 1.55.0 by @dependabot ([#45], [#46], [#56],
+  [#78])
+- Bump actions/checkout from 4 to 7 by @dependabot ([#44], [#52], [#79])
+- Bump rake from 13.3.0 to 13.4.2 by @dependabot ([#48], [#73])
+- Bump zlib from 3.2.1 to 3.2.3 by @dependabot ([#49], [#70])
+- Bump rspec from 3.13.1 to 3.13.2 by @dependabot ([#47])
+- Bump parallel from 1.27.0 to 1.28.0 by @dependabot ([#71])
+- Bump benchmark-ips from 2.14.0 to 2.15.1 by @dependabot ([#75])
+- Bump json from 2.18.1 to 2.19.2 by @dependabot ([#77])
+
+### Bug fixes
+
+- Fix `compute_and_differentiate` returning mismatched velocities for an array
+  of times
+- Fix precision loss in `time_to_seconds` for dates far from J2000 ([#60])
+
+[#44]: https://github.com/rhannequin/ruby-ephem/pull/44
+[#45]: https://github.com/rhannequin/ruby-ephem/pull/45
+[#46]: https://github.com/rhannequin/ruby-ephem/pull/46
+[#47]: https://github.com/rhannequin/ruby-ephem/pull/47
+[#48]: https://github.com/rhannequin/ruby-ephem/pull/48
+[#49]: https://github.com/rhannequin/ruby-ephem/pull/49
+[#52]: https://github.com/rhannequin/ruby-ephem/pull/52
+[#56]: https://github.com/rhannequin/ruby-ephem/pull/56
+[#57]: https://github.com/rhannequin/ruby-ephem/pull/57
+[#58]: https://github.com/rhannequin/ruby-ephem/pull/58
+[#60]: https://github.com/rhannequin/ruby-ephem/pull/60
+[#61]: https://github.com/rhannequin/ruby-ephem/pull/61
+[#62]: https://github.com/rhannequin/ruby-ephem/pull/62
+[#63]: https://github.com/rhannequin/ruby-ephem/pull/63
+[#64]: https://github.com/rhannequin/ruby-ephem/pull/64
+[#65]: https://github.com/rhannequin/ruby-ephem/pull/65
+[#66]: https://github.com/rhannequin/ruby-ephem/pull/66
+[#67]: https://github.com/rhannequin/ruby-ephem/pull/67
+[#68]: https://github.com/rhannequin/ruby-ephem/pull/68
+[#70]: https://github.com/rhannequin/ruby-ephem/pull/70
+[#71]: https://github.com/rhannequin/ruby-ephem/pull/71
+[#73]: https://github.com/rhannequin/ruby-ephem/pull/73
+[#75]: https://github.com/rhannequin/ruby-ephem/pull/75
+[#76]: https://github.com/rhannequin/ruby-ephem/issues/76
+[#77]: https://github.com/rhannequin/ruby-ephem/pull/77
+[#78]: https://github.com/rhannequin/ruby-ephem/pull/78
+[#79]: https://github.com/rhannequin/ruby-ephem/pull/79
+[#80]: https://github.com/rhannequin/ruby-ephem/pull/80
+[#81]: https://github.com/rhannequin/ruby-ephem/pull/81
+[#83]: https://github.com/rhannequin/ruby-ephem/pull/83
+[#84]: https://github.com/rhannequin/ruby-ephem/pull/84
+
+**Full Changelog**: https://github.com/rhannequin/ruby-ephem/compare/v0.4.1...v0.5.0
+
 ## [0.4.1] - 2025-08-03
 
 ### Improvements
 
-* Exclude BSP files from release ([#42])
+- Exclude BSP files from release ([#42])
 
 [#42]: https://github.com/rhannequin/ruby-ephem/pull/42
 
@@ -14,13 +103,13 @@
 
 ### Improvements
 
-* Improve Chebyshev polynomial performance ([#33])
-* Improve download file management ([#34])
-* Validate against all kernels and date ranges ([#36])
-* Add supported Ruby versions ([#35])
-* Bump rspec from 3.13.0 to 3.13.1 by @dependabot ([#38])
-* Bump rake from 13.2.1 to 13.3.0 by @dependabot ([#39])
-* Bump csv from 3.3.4 to 3.3.5 by @dependabot ([#40])
+- Improve Chebyshev polynomial performance ([#33])
+- Improve download file management ([#34])
+- Validate against all kernels and date ranges ([#36])
+- Add supported Ruby versions ([#35])
+- Bump rspec from 3.13.0 to 3.13.1 by @dependabot ([#38])
+- Bump rake from 13.2.1 to 13.3.0 by @dependabot ([#39])
+- Bump csv from 3.3.4 to 3.3.5 by @dependabot ([#40])
 
 [#33]: https://github.com/rhannequin/ruby-ephem/pull/33
 [#34]: https://github.com/rhannequin/ruby-ephem/pull/34
@@ -36,15 +125,15 @@
 
 ### Bug fixes
 
-* Write downloaded ephemeris in binary mode by @trevorturk ([#31])
+- Write downloaded ephemeris in binary mode by @trevorturk ([#31])
 
 ### Improvements
 
-* Bump standard from 1.49.0 to 1.50.0 by @dependabot ([#29])
+- Bump standard from 1.49.0 to 1.50.0 by @dependabot ([#29])
 
 ### New Contributors
 
-* @trevorturk made their first contribution in [#31]
+- @trevorturk made their first contribution in [#31]
 
 **Full Changelog**: https://github.com/rhannequin/ruby-ephem/compare/v0.3.0...v0.3.1
 
@@ -55,15 +144,15 @@
 
 ## Features
 
-* Improve find_interval with binary search ([#24])
-* Use alias methods to get segment position or state ([#27])
+- Improve find_interval with binary search ([#24])
+- Use alias methods to get segment position or state ([#27])
 
 ## Improvements
 
-* Bump irb from 1.15.1 to 1.15.2 by @dependabot ([#21])
-* Bump standard from 1.47.0 to 1.49.0 by @dependabot ([#23])
-* Bump csv from 3.3.3 to 3.3.4 by @dependabot ([#25])
-* Bump parallel from 1.26.3 to 1.27.0 by @dependabot ([#26])
+- Bump irb from 1.15.1 to 1.15.2 by @dependabot ([#21])
+- Bump standard from 1.47.0 to 1.49.0 by @dependabot ([#23])
+- Bump csv from 3.3.3 to 3.3.4 by @dependabot ([#25])
+- Bump parallel from 1.26.3 to 1.27.0 by @dependabot ([#26])
 
 **Full Changelog**: https://github.com/rhannequin/ruby-ephem/compare/v0.2.0...v0.3.0
 
@@ -78,27 +167,27 @@
 
 ### Features
 
-* Simplify download ([#12])
-* SPK excerpt generator ([#13])
-* Improve documentation on excerpts ([#16])
-* IMCCE INPOP support ([#20])
+- Simplify download ([#12])
+- SPK excerpt generator ([#13])
+- Improve documentation on excerpts ([#16])
+- IMCCE INPOP support ([#20])
 
 ### Improvements
 
-* Add Dependabot ([#6])
-* Replace testing kernel ([#17])
-* Add `irb` to dev dependencies ([#14])
-* Add support for Rubies `3.2.7` and `3.4.2` ([#15])
-* Bump csv from 3.3.0 to 3.3.2 by @dependabot ([#7])
-* Bump standard from 1.43.0 to 1.44.0 by @dependabot ([#8])
-* Bump standard from 1.44.0 to 1.45.0 by @dependabot ([#9])
-* Bump csv from 3.3.2 to 3.3.3 by @dependabot ([#11])
-* Bump standard from 1.45.0 to 1.47.0 by @dependabot ([#10])
-* Bump json from 2.10.1 to 2.10.2 by @dependabot ([#18])
+- Add Dependabot ([#6])
+- Replace testing kernel ([#17])
+- Add `irb` to dev dependencies ([#14])
+- Add support for Rubies `3.2.7` and `3.4.2` ([#15])
+- Bump csv from 3.3.0 to 3.3.2 by @dependabot ([#7])
+- Bump standard from 1.43.0 to 1.44.0 by @dependabot ([#8])
+- Bump standard from 1.44.0 to 1.45.0 by @dependabot ([#9])
+- Bump csv from 3.3.2 to 3.3.3 by @dependabot ([#11])
+- Bump standard from 1.45.0 to 1.47.0 by @dependabot ([#10])
+- Bump json from 2.10.1 to 2.10.2 by @dependabot ([#18])
 
 ### New Contributors
 
-* @dependabot made their first contribution in [#7]
+- @dependabot made their first contribution in [#7]
 
 **Full Changelog**: https://github.com/rhannequin/ruby-ephem/compare/v0.1.0...v0.2.0
 

data/README.md

@@ -12,8 +12,9 @@ These files are a collection of numerical integrations of the equations of
 motion of the Solar System, used to calculate the positions of the planets,
 the Moon, and other celestial bodies with high precision.
 
-Ephem currently only support planetary ephemerides like DE421, DE430,
-INPOP19A, etc.
+Ephem supports planetary ephemerides like DE421, DE430, INPOP19A, etc. (SPK),
+as well as binary PCK orientation kernels such as the lunar orientation kernel
+`moon_pa_de440_200625.bpc`.
 
 The library is in high development mode and does not have a stable version yet.
 The API is subject to major changes at the moment, please keep that in mind if
@@ -99,6 +100,67 @@ puts "Velocity: #{state.velocity}"
 # The velocity is expressed in km/day
 ```
 
+## Orientation kernels (binary PCK)
+
+Binary PCK (`DAF/PCK`) kernels store the orientation of a body frame over time
+as Euler angles, rather than position. The most common use is the Moon's
+physical libration via a lunar orientation kernel such as
+`moon_pa_de440_200625.bpc`.
+
+```rb
+# Download and load a binary PCK orientation kernel
+Ephem::Download.call(
+  name: "moon_pa_de440_200625.bpc",
+  target: "tmp/moon_pa_de440_200625.bpc"
+)
+pck = Ephem::PCK.open("tmp/moon_pa_de440_200625.bpc")
+
+puts pck
+# => PCK file with 2 segments:
+# 1549-12-21..2426-02-16 Type 2 orientation of frame 31008 relative to frame 1
+# 2426-02-16..2650-01-25 Type 2 orientation of frame 31008 relative to frame 1
+
+# Query a body frame by its NAIF frame ID (31008 = MOON_PA_DE440).
+# The time is expressed in Julian Date (TDB).
+frame = pck[31008]
+orientation = frame.orientation_at(2451545.0)
+
+# The three classical 3-1-3 (Z-X-Z) Euler angles, in radians
+puts "phi:   #{orientation.phi}"
+puts "theta: #{orientation.theta}"
+puts "psi:   #{orientation.psi}"
+
+# Rates are in radians/day (ephem's per-day convention, like SPK velocities)
+puts "rates: #{orientation.rates.inspect}"
+
+# Use #angles_at when you do not need the rates (it skips the derivative)
+angles = frame.angles_at(2451545.0)
+
+pck.close
+```
+
+### Building the body-fixed frame
+
+The orientation maps the reference frame into the body-fixed frame through the
+3-1-3 (Z-X-Z) Euler sequence `M = Rz(psi) * Rx(theta) * Rz(phi)`. That
+convention is built in, so you can get the rotation matrix directly:
+
+```rb
+# Straight from a frame, at a given time
+matrix = frame.matrix_at(2451545.0)
+
+# ...or from an Orientation you already have
+matrix = orientation.to_matrix
+
+# Project a geocentric Earth->Moon vector into the body-fixed frame
+body_fixed = Ephem::Core::Rotation.apply(matrix, earth_to_moon)
+```
+
+`Ephem::Core::Rotation` also exposes the lower-level, kernel-agnostic building
+blocks (`about_x`, `about_y`, `about_z`, `multiply`, `apply`) if you need a
+different axis order or an additional fixed rotation (such as the PA -> ME
+offset, whose constants the consumer supplies).
+
 ## CLI
 
 The gem also provides a CLI to generate an excerpt from an original kernel file.
@@ -121,6 +183,13 @@ While DE440s originally supports 14 segments from 1849 to 2150 with a size of
 Not only the excerpt is smaller, but most importantly it is way more
 efficient to parse and to use in your application.
 
+The input kernel kind (SPK or binary PCK) is detected automatically, so the
+same command excerpts orientation kernels too:
+
+```bash
+ruby-ephem excerpt --targets 31008 2000-01-01 2030-01-01 /path/to/moon_pa_de440.bpc moon_excerpt.bpc
+```
+
 ## Accuracy
 
 Data from this library has been tested against the Python library [jplephem]
@@ -136,8 +205,8 @@ The times tested are noon UTC for every day between 2000-01-01 and
 2050-01-01. Vectors tested are always with `center` 0 (Solar System Barycenter),
 and `target` from `1` (Mercury Barycenter) to `10` (Sun).
 
-Rake tasks ensure data from this library match with `jplephem` with a margin
-error of 2 centimeters.
+Rake tasks ensure data from this library match with `jplephem`. Positions match
+exactly and velocities are within 0.002 mm/s.
 
 You can run them by following this pattern:
 
@@ -159,6 +228,14 @@ usage time.
 
 [jplephem]: https://pypi.org/project/jplephem/
 
+## Benchmarks
+
+Run the benchmark suite to measure performance across the computation pipeline:
+
+```bash
+bundle exec ruby benchmarks/run.rb
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run