ephem 0.4.1 → 0.5.0

data/benchmarks/run.rb

@@ -0,0 +1,431 @@
+# frozen_string_literal: true
+
+require "benchmark/ips"
+require "objspace"
+require_relative "../lib/ephem"
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+ROOT = File.expand_path("..", __dir__)
+SPK_FULL = File.join(ROOT, "spec", "support", "data", "de432s.bsp")
+SPK_EXCERPT = File
+  .join(ROOT, "spec", "support", "data", "de421_2000_excerpt.bsp")
+PCK_EXCERPT = File
+  .join(ROOT, "spec", "support", "data", "moon_pa_de440_excerpt.bpc")
+
+JD_J2000 = Ephem::Core::Constants::Time::J2000_EPOCH # 2451545.0
+JD_TEST = 2459000.0 # 2020-09-30, well within de432s range
+
+SEQUENTIAL_STEPS = 1000
+
+# Body pairs available in DE432s: [center, target]
+BODY_PAIRS = {
+  "Sun" => [0, 10],
+  "Earth-Moon Bary" => [0, 3],
+  "Mars Bary" => [0, 4],
+  "Jupiter Bary" => [0, 5],
+  "Saturn Bary" => [0, 6]
+}.freeze
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def separator(title)
+  puts
+  puts "=" * 70
+  puts "  #{title}"
+  puts "=" * 70
+  puts
+end
+
+def ensure_file!(path)
+  return if File.exist?(path)
+  abort "SPK file not found: #{path}\n" \
+        "Run specs first or place the file manually."
+end
+
+# ---------------------------------------------------------------------------
+# Preflight
+# ---------------------------------------------------------------------------
+
+ensure_file!(SPK_FULL)
+ensure_file!(SPK_EXCERPT)
+
+puts "Ephem Benchmark Suite"
+puts "-" * 70
+puts "Ruby:     #{RUBY_VERSION} (#{RUBY_PLATFORM})"
+puts "Ephem:    #{Ephem::VERSION}"
+puts "SPK:      #{File.basename(SPK_FULL)} (#{(File.size(SPK_FULL) / 1024.0 / 1024).round(2)} MB)"
+puts "Excerpt:  #{File.basename(SPK_EXCERPT)} (#{(File.size(SPK_EXCERPT) / 1024.0).round(1)} KB)"
+puts "J2000:    #{JD_J2000}"
+puts "Test JD:  #{JD_TEST}"
+puts "-" * 70
+
+# Pre-open the main SPK file and warm up data for hot-path benchmarks
+spk = Ephem::SPK.open(SPK_FULL)
+segment_emb = spk[0, 3]    # Earth-Moon Barycenter
+segment_sun = spk[0, 10]   # Sun
+
+# Trigger lazy data loading so hot-path benchmarks don't include I/O
+segment_emb.compute(JD_TEST)
+segment_sun.compute(JD_TEST)
+
+# Pre-compute time arrays for sequential/random benchmarks
+sequential_times = Array.new(SEQUENTIAL_STEPS) { |i| JD_TEST + i }
+random_times = sequential_times.shuffle
+
+# =========================================================================
+# 1. SPK FILE OPENING
+# =========================================================================
+
+separator "1. SPK File Opening"
+
+GC.start
+Benchmark.ips do |x|
+  x.report("SPK.open (full 10MB)") do
+    s = Ephem::SPK.open(SPK_FULL)
+    s.close
+  end
+
+  x.report("SPK.open (excerpt 54KB)") do
+    s = Ephem::SPK.open(SPK_EXCERPT)
+    s.close
+  end
+
+  x.compare!
+end
+
+# =========================================================================
+# 2. FIRST DATA LOAD (COLD START)
+# =========================================================================
+
+separator "2. First Data Load (Cold Start)"
+
+puts "Measures the cost of the first compute() call on a segment,"
+puts "which triggers lazy loading of coefficient data from disk."
+puts
+
+GC.start
+Benchmark.ips do |x|
+  x.report("cold compute (load + eval)") do
+    segment_emb.clear_data
+    segment_emb.compute(JD_TEST)
+  end
+
+  x.report("warm compute (cached)") do
+    segment_emb.compute(JD_TEST)
+  end
+
+  x.compare!
+end
+
+# Ensure data is loaded again for subsequent benchmarks
+segment_emb.compute(JD_TEST)
+
+# =========================================================================
+# 3. SINGLE POSITION COMPUTATION (HOT PATH)
+# =========================================================================
+
+separator "3. Single Position Computation (Hot Path)"
+
+puts "segment.compute(time) — Chebyshev eval + Vector creation"
+puts
+
+GC.start
+Benchmark.ips do |x|
+  x.report("compute (position)") { segment_emb.compute(JD_TEST) }
+end
+
+# =========================================================================
+# 4. SINGLE STATE COMPUTATION
+# =========================================================================
+
+separator "4. Single State Computation"
+
+puts "segment.compute_and_differentiate(time) — position + velocity"
+puts
+
+GC.start
+Benchmark.ips do |x|
+  x.report("compute_and_differentiate (state)") do
+    segment_emb.compute_and_differentiate(JD_TEST)
+  end
+end
+
+# =========================================================================
+# 5. POSITION vs STATE (COMPARISON)
+# =========================================================================
+
+separator "5. Position vs State (Direct Comparison)"
+
+GC.start
+Benchmark.ips do |x|
+  x.report("compute (position only)") { segment_emb.compute(JD_TEST) }
+  x.report("compute_and_differentiate") do
+    segment_emb.compute_and_differentiate(JD_TEST)
+  end
+
+  x.compare!
+end
+
+# =========================================================================
+# 6. SEQUENTIAL TIME ACCESS
+# =========================================================================
+
+separator "6. Sequential Time Access (#{SEQUENTIAL_STEPS} days)"
+
+puts "Tests interval-finding binary search with temporal locality."
+puts "The @last_interval cache should accelerate sequential access."
+puts
+
+GC.start
+Benchmark.ips do |x|
+  x.report("sequential (#{SEQUENTIAL_STEPS} days)") do
+    sequential_times.each { |t| segment_emb.compute(t) }
+  end
+end
+
+# =========================================================================
+# 7. RANDOM TIME ACCESS
+# =========================================================================
+
+separator "7. Random Time Access (#{SEQUENTIAL_STEPS} days, shuffled)"
+
+puts "Same times as above but shuffled — measures interval cache miss impact."
+puts
+
+GC.start
+Benchmark.ips do |x|
+  x.report("sequential access") do
+    sequential_times.each { |t| segment_emb.compute(t) }
+  end
+
+  x.report("random access") do
+    random_times.each { |t| segment_emb.compute(t) }
+  end
+
+  x.compare!
+end
+
+# =========================================================================
+# 8. BATCH COMPUTATION
+# =========================================================================
+
+separator "8. Batch vs Loop Computation"
+
+batch_sizes = [10, 100, 1000]
+
+batch_sizes.each do |n|
+  times = sequential_times.first(n)
+
+  puts "--- Batch size: #{n} ---"
+  GC.start
+  Benchmark.ips do |x|
+    x.report("loop (#{n} times)") do
+      times.each { |t| segment_emb.compute_and_differentiate(t) }
+    end
+
+    x.report("batch (#{n} times)") do
+      segment_emb.compute_and_differentiate(times)
+    end
+
+    x.compare!
+  end
+  puts
+end
+
+# =========================================================================
+# 9. MULTIPLE BODIES
+# =========================================================================
+
+separator "9. Multiple Bodies (Computation Speed by Target)"
+
+# Pre-load all segments
+body_segments = {}
+BODY_PAIRS.each do |name, (center, target)|
+  seg = spk[center, target]
+  seg.compute(JD_TEST) # warm up
+  body_segments[name] = seg
+end
+
+GC.start
+Benchmark.ips do |x|
+  body_segments.each do |name, seg|
+    x.report(name) { seg.compute(JD_TEST) }
+  end
+
+  x.compare!
+end
+
+# =========================================================================
+# 10. CHEBYSHEV POLYNOMIAL (MICRO-BENCHMARK)
+# =========================================================================
+
+separator "10. Chebyshev Polynomial Evaluation (Micro)"
+
+puts "Direct ChebyshevPolynomial.evaluate / evaluate_derivative calls"
+puts "with real coefficients extracted from a loaded segment."
+puts
+
+# Extract real coefficient data from the loaded segment
+coefficients = segment_emb.instance_variable_get(:@coefficients)
+radii = segment_emb.instance_variable_get(:@radii)
+
+# Pick the first interval's coefficients
+test_coeffs = coefficients[0]
+test_radius = radii[0]
+test_t = 0.0 # midpoint of the interval (normalized)
+
+puts "Polynomial degree: #{test_coeffs.size} terms"
+puts "Components per term: #{test_coeffs.first.size}"
+puts
+
+GC.start
+Benchmark.ips do |x|
+  x.report("evaluate (position)") do
+    Ephem::Computation::ChebyshevPolynomial.evaluate(test_coeffs, test_t)
+  end
+
+  x.report("evaluate_derivative (velocity)") do
+    Ephem::Computation::ChebyshevPolynomial.evaluate_derivative(
+      test_coeffs, test_t, test_radius
+    )
+  end
+
+  x.report("evaluate_with_derivative (pos+vel, 1 pass)") do
+    Ephem::Computation::ChebyshevPolynomial.evaluate_with_derivative(
+      test_coeffs, test_t, test_radius
+    )
+  end
+
+  x.compare!
+end
+
+# =========================================================================
+# 11. VECTOR OPERATIONS
+# =========================================================================
+
+separator "11. Vector Operations"
+
+v1 = Ephem::Core::Vector.new(1.0, 2.0, 3.0)
+v2 = Ephem::Core::Vector.new(4.0, 5.0, 6.0)
+
+GC.start
+Benchmark.ips do |x|
+  x.report("Vector.new") { Ephem::Core::Vector.new(1.0, 2.0, 3.0) }
+  x.report("Vector + Vector") { v1 + v2 }
+  x.report("Vector - Vector") { v1 - v2 }
+  x.report("Vector.dot") { v1.dot(v2) }
+  x.report("Vector.cross") { v1.cross(v2) }
+  x.report("Vector.magnitude") { v1.magnitude }
+  x.report("Vector.to_a") { v1.to_a }
+
+  x.compare!
+end
+
+# =========================================================================
+# 12. MEMORY PROFILING
+# =========================================================================
+
+separator "12. Memory Profiling"
+
+# --- 12a. Object allocations per compute call ---
+puts "--- Object allocations per call ---"
+puts
+
+# Warm up
+segment_emb.compute(JD_TEST)
+segment_emb.compute_and_differentiate(JD_TEST)
+
+# Measure compute
+GC.start
+GC.disable
+before = GC.stat[:total_allocated_objects]
+segment_emb.compute(JD_TEST)
+after = GC.stat[:total_allocated_objects]
+GC.enable
+puts "  compute (position):              #{after - before} objects allocated"
+
+# Measure compute_and_differentiate
+GC.start
+GC.disable
+before = GC.stat[:total_allocated_objects]
+segment_emb.compute_and_differentiate(JD_TEST)
+after = GC.stat[:total_allocated_objects]
+GC.enable
+puts "  compute_and_differentiate:       #{after - before} objects allocated"
+
+# Measure batch of 100
+times_100 = sequential_times.first(100)
+GC.start
+GC.disable
+before = GC.stat[:total_allocated_objects]
+segment_emb.compute_and_differentiate(times_100)
+after = GC.stat[:total_allocated_objects]
+GC.enable
+alloc_100 = after - before
+puts "  batch compute_and_diff (100):    #{alloc_100} objects (#{(alloc_100 / 100.0).round(1)}/call)"
+
+puts
+
+# --- 12b. Segment data memory footprint ---
+puts "--- Segment data memory footprint ---"
+puts
+
+# Force a fresh load and measure
+segment_fresh = spk[0, 3]
+segment_fresh.clear_data
+
+GC.start
+before_mem = ObjectSpace.memsize_of_all
+segment_fresh.compute(JD_TEST) # triggers load
+GC.start
+after_mem = ObjectSpace.memsize_of_all
+
+delta_kb = (after_mem - before_mem) / 1024.0
+puts "  Segment [0,3] data load:         ~#{delta_kb.round(1)} KB"
+
+# Report coefficient array size
+coeffs = segment_fresh.instance_variable_get(:@coefficients)
+if coeffs
+  puts "  Coefficient records:             #{coeffs.size}"
+  puts "  Terms per record:                #{coeffs.first&.size}"
+  puts "  Components per term:             #{coeffs.first&.first&.size}"
+end
+
+# =========================================================================
+# 13. PCK ORIENTATION (BINARY PCK)
+# =========================================================================
+
+separator "13. PCK Orientation (Binary PCK)"
+
+puts "angles_at (Euler angles) vs orientation_at (angles + rates)"
+puts
+
+pck = Ephem::PCK.open(PCK_EXCERPT)
+moon = pck[31008] # MOON_PA_DE440 frame
+moon.angles_at(JD_J2000) # warm up
+
+orientation_times = Array.new(SEQUENTIAL_STEPS) { |index| JD_J2000 + index }
+
+GC.start
+Benchmark.ips do |x|
+  x.report("angles_at (scalar)") { moon.angles_at(JD_J2000) }
+  x.report("orientation_at (scalar)") { moon.orientation_at(JD_J2000) }
+  x.report("angles_at (batch 1000)") { moon.angles_at(orientation_times) }
+
+  x.compare!
+end
+
+pck.close
+
+# =========================================================================
+# Cleanup
+# =========================================================================
+
+spk.close
+
+separator "Benchmark Complete"

data/lib/ephem/cli.rb

@@ -47,22 +47,22 @@ module Ephem
         Ruby Ephem - A tool for working with JPL Ephemerides
 
         Commands:
-          excerpt - Create an excerpt of an SPK file
+          excerpt - Create an excerpt of an SPK or binary PCK kernel
           help    - Show this help message
 
         Excerpt command:
           ruby-ephem excerpt [options] START_DATE END_DATE INPUT_FILE OUTPUT_FILE
 
         Options:
-          --targets TARGET_IDS  - Comma-separated list of target IDs to include
-                                  (default: all targets)
+          --targets TARGET_IDS  - Comma-separated list of target/body IDs to
+                                  include (default: all)
 
-        Example:
+        Examples:
           ruby-ephem excerpt --targets 3,10,399 2000-01-01 2030-01-01 de440s.bsp excerpt.bsp
+          ruby-ephem excerpt --targets 31008 2000-01-01 2030-01-01 moon_pa_de440.bpc moon_excerpt.bpc
 
-        This will create an excerpt of de440s.bsp containing only the specified
-        targets (Earth-Moon barycenter, Sun, Earth) for the period from
-        2000-01-01 to 2030-01-01.
+        The input kernel kind (SPK or binary PCK) is detected automatically and
+        the excerpt is written in the same format.
       HELP
     end
 
@@ -125,9 +125,9 @@ module Ephem
           puts "Including all targets"
         end
 
-        spk = Ephem::SPK.open(input_file)
+        kernel = open_kernel(input_file)
 
-        excerpt_spk = spk.excerpt(
+        excerpt_kernel = kernel.excerpt(
           output_path: output_file,
           start_jd: start_jd,
           end_jd: end_jd,
@@ -136,8 +136,8 @@ module Ephem
         )
 
         puts "Excerpt created successfully!"
-        puts "Original segments: #{spk.segments.size}"
-        puts "Excerpt segments: #{excerpt_spk.segments.size}"
+        puts "Original segments: #{kernel.segments.size}"
+        puts "Excerpt segments: #{excerpt_kernel.segments.size}"
 
         original_size = File.size(input_file)
         excerpt_size = File.size(output_file)
@@ -148,12 +148,25 @@ module Ephem
         puts "Original: #{original_size} bytes"
         puts "Excerpt: #{excerpt_size} bytes"
 
-        spk.close
-        excerpt_spk.close
+        kernel.close
+        excerpt_kernel.close
       rescue => e
         puts "Error creating excerpt: #{e.message}"
         puts e.backtrace if options[:debug]
       end
     end
+
+    def self.open_kernel(path)
+      daf = Ephem::IO::DAF.new(File.open(path, "rb"))
+
+      if daf.file_type == :pck
+        Ephem::PCK.new(daf: daf)
+      else
+        Ephem::SPK.new(daf: daf)
+      end
+    rescue
+      daf&.close
+      raise
+    end
   end
 end

data/lib/ephem/computation/chebyshev_polynomial.rb

@@ -22,13 +22,13 @@ module Ephem
         b1x = b1y = b1z = 0.0
         b2x = b2y = b2z = 0.0
 
+        t2 = 2.0 * t
         k = n - 1
         while k > 0
           c = coeffs[k]
           c0 = c[0]
           c1 = c[1]
           c2 = c[2]
-          t2 = 2.0 * t
           tx = t2 * b1x - b2x + c0
           ty = t2 * b1y - b2y + c1
           tz = t2 * b1z - b2z + c2
@@ -52,9 +52,9 @@ module Ephem
       # @param coeffs [Array<Array<Float>>] Array of coefficients; shape is
       #   [n_terms][3].
       # @param t [Float] The normalized independent variable (in [-1, 1]).
-      # @param radius [Float] The half-length of the time interval (days).
+      # @param radius [Float] The half-length of the time interval (seconds).
       # @return [Array<Float>] The 3-vector derivative (velocity), in units per
-      #   second.
+      #   day.
       def self.evaluate_derivative(coeffs, t, radius)
         n = coeffs.size
         return [0.0, 0.0, 0.0] if n < 2
@@ -62,13 +62,13 @@ module Ephem
         d1x = d1y = d1z = 0.0
         d2x = d2y = d2z = 0.0
 
+        t2 = 2.0 * t
         k = n - 1
         while k > 0
           c = coeffs[k]
           c0 = c[0]
           c1 = c[1]
           c2 = c[2]
-          t2 = 2.0 * t
           k2 = 2 * k
           tx = t2 * d1x - d2x + k2 * c0
           ty = t2 * d1y - d2y + k2 * c1
@@ -85,6 +85,65 @@ module Ephem
         scale = Ephem::Core::Constants::Time::SECONDS_PER_DAY / (2.0 * radius)
         [d1x * scale, d1y * scale, d1z * scale]
       end
+
+      ##
+      # Evaluates a 3D Chebyshev polynomial and its time derivative in a single
+      # pass. It runs the same value and derivative recurrences as {evaluate}
+      # and {evaluate_derivative}, but fused into one loop so the coefficient
+      # fetch and loop control are shared. Results are bit-for-bit identical to
+      # calling the two methods separately.
+      #
+      # @param coeffs [Array<Array<Float>>] coefficients; shape [n_terms][3].
+      # @param t [Float] normalized independent variable, in [-1, 1].
+      # @param radius [Float] half-length of the time interval (seconds).
+      # @return [Array(Array<Float>, Array<Float>)] [position, velocity], with
+      #   velocity in units per day.
+      def self.evaluate_with_derivative(coeffs, t, radius)
+        n = coeffs.size
+        b1x = b1y = b1z = 0.0
+        b2x = b2y = b2z = 0.0
+        d1x = d1y = d1z = 0.0
+        d2x = d2y = d2z = 0.0
+
+        t2 = 2.0 * t
+        k = n - 1
+        while k > 0
+          c = coeffs[k]
+          c0 = c[0]
+          c1 = c[1]
+          c2 = c[2]
+          k2 = 2 * k
+
+          bx = t2 * b1x - b2x + c0
+          by = t2 * b1y - b2y + c1
+          bz = t2 * b1z - b2z + c2
+          dx = t2 * d1x - d2x + k2 * c0
+          dy = t2 * d1y - d2y + k2 * c1
+          dz = t2 * d1z - d2z + k2 * c2
+
+          b2x = b1x
+          b2y = b1y
+          b2z = b1z
+          b1x = bx
+          b1y = by
+          b1z = bz
+          d2x = d1x
+          d2y = d1y
+          d2z = d1z
+          d1x = dx
+          d1y = dy
+          d1z = dz
+          k -= 1
+        end
+
+        c0, c1, c2 = coeffs[0]
+        position = [t * b1x - b2x + c0, t * b1y - b2y + c1, t * b1z - b2z + c2]
+
+        scale = Ephem::Core::Constants::Time::SECONDS_PER_DAY / (2.0 * radius)
+        velocity = [d1x * scale, d1y * scale, d1z * scale]
+
+        [position, velocity]
+      end
     end
   end
 end