LibEphemeris vs Swiss Ephemeris — Comparison & Known Differences #

This document is a direct, exhaustive comparison between libephemeris and pyswisseph (the Python wrapper for Swiss Ephemeris). It documents measured precision, known differences, their root causes, and the methodology used to verify compatibility.

LibEphemeris aims for 1:1 API compatibility with Swiss Ephemeris. The two libraries produce results that are extremely close but will never be bit-identical, because they are built on fundamentally different foundations:

Table of Contents #

• 1. Precision Summary
• 2. Known Differences in Detail
• 3. Bugs Found and Fixed
• 4. API Signature Differences
• 5. Validation Methodology
• 6. References

---

1. Precision Summary #

All measurements taken across 100–210 dates spanning the DE440 range (1550–2650 CE), comparing libephemeris output against pyswisseph with identical flags and parameters.

Planetary positions #

All planets except the Moon are sub-2" (sub-arcsecond for outer planets). The Moon difference is explained in Section 2.2.

Lunar nodes and Lilith #

Mean Lilith latitude ~20" difference is from different analytical node formulas used in the orbital-plane-to-ecliptic projection. No practical impact.

Heliocentric, barycentric, equatorial, and XYZ modes #

Other areas #

Velocities #

---

2. Known Differences in Detail #

These are not bugs. They are inherent consequences of using different astronomical models, different ephemerides, or different algorithmic strategies. Each is explained in full so that users and developers understand exactly what to expect.

2.1. Crossing functions — full-orbit search for slow planets #

swe_cross_ut now handles full-orbit searches for all planets, including slow outer planets like Jupiter and Saturn. The algorithm automatically scales the Brent bracket search window based on the estimated time to crossing (dt_guess), and filters out false sign changes at the antipodal point (target ± 180°) during the coarse scan. This ensures convergence even when the crossing is 10+ years away and the planet undergoes multiple retrograde periods en route.

Previously, Jupiter 0° Aries searches could converge on 180° instead of 0°. This was fixed by:

1. Scaling the search window to max(min_window, dt_guess * 1.5) instead of a fixed 500-day cap
2. Scaling the number of coarse samples proportionally (search_window / 30 days per sample)
3. Rejecting bracket candidates where the signed-difference jump exceeds 180° (wrapping artifacts at the antipodal point)

2.2. Moon precision — max ~135" over 800 years #

What: The maximum difference in lunar longitude between libephemeris and pyswisseph is approximately 135 arcseconds (0.037°), occurring at the extremes of the DE440 date range (around 1550 CE and 2650 CE).

Why: The two libraries use fundamentally different lunar models:

• libephemeris uses JPL DE440, where the Moon’s position is computed by numerical integration of the full equations of motion for all Solar System bodies. DE440 is fitted to Lunar Laser Ranging data (1970–present) with ~1 milliarcsecond precision for the modern era.

• pyswisseph uses a combination of DE431 for the modern period and the ELP/MPP02 analytical theory for the Moon. The analytical theory represents the Moon’s motion as a sum of thousands of trigonometric terms — a fundamentally different mathematical approach.

For dates near the present (1900–2100), the two models agree to within a few arcseconds. But as you move to historical or far-future dates, they diverge because:

1. Different tidal acceleration models: The Moon is slowly receding from Earth due to tidal friction. DE440 and the Swiss Ephemeris analytical theory model this effect with slightly different parameters, causing cumulative divergence over centuries.

2. Different fitting datasets: DE440 incorporates 8 additional years of Lunar Laser Ranging data compared to DE431, plus improved planetary observations from Juno (Jupiter) and MESSENGER (Mercury) that indirectly affect the lunar solution.

3. Numerical vs analytical: Numerical integration accumulates floating-point errors over very long time spans, while analytical series have truncation errors from omitting higher-order terms. The two error profiles are different.

Practical impact: For dates within ±200 years of the present, the difference is < 5". For typical astrological use (natal charts, transits, progressions), the difference is astronomically negligible — it corresponds to a timing error of roughly 4 minutes in the Moon’s position.

2.3. Delta T — up to 232 seconds divergence #

What: The computed Delta T (ΔT = TT − UT1) can differ by up to 232 seconds between the two libraries for extreme dates.

Why: Delta T represents the difference between uniform atomic time (TT) and the irregular rotation of the Earth (UT1). The Earth’s rotation is unpredictable — it slows down due to lunar tides, speeds up due to post-glacial rebound, and fluctuates on decadal timescales for reasons not fully understood.

The two libraries use different models to estimate ΔT:

For the modern era (1900–2020), where direct measurements exist, the two models agree to within ~1 second. The 232-second maximum occurs for dates around 500 CE or beyond 2500 CE, where:

• Historical dates: The only data sources are ancient eclipse records (Babylonian, Chinese, Arabic). The Stephenson et al. (2016) model re-analyzed these records with improved methodology, producing different ΔT values than the older Espenak & Meeus (2006) model.
• Future dates: Nobody knows how the Earth’s rotation will change. Both models extrapolate using different parabolic formulas, and the divergence grows quadratically with time.

Practical impact: ΔT affects the mapping from calendar time to astronomical time. A 232-second difference means that the two libraries place the same calendar date at slightly different points on the astronomical timeline. For planetary positions, this translates to at most a few arcseconds of positional difference (the Moon moves ~0.5"/second, so 232 seconds ≈ 116" of lunar motion — consistent with the Moon precision figures above). For the Sun and planets, the effect is much smaller.

2.4. House cusp speeds — numerical vs analytical derivatives #

What: swe_houses_ex2 and swe_houses_armc_ex2 compute cusp velocities using centered finite differences when SEFLG_SPEED is set. The maximum difference from pyswisseph is ~0.7 deg/day (~0.2% relative).

Why: The two libraries use different differentiation strategies:

• libephemeris uses numerical differentiation (central difference at ±1 minute): speed = (cusp(t+dt) − cusp(t−dt)) / (2·dt), with proper 0°/360° wraparound handling.

• pyswisseph uses analytical derivatives by differentiating the house cusp formulas symbolically with respect to time.

Both approaches are valid. The numerical method introduces a small truncation error proportional to dt², which at a 1-minute step produces differences of < 1 deg/day from the analytical result. Given that cusp speeds are ~280–340 deg/day, this corresponds to < 0.3% relative error.

Note: Cusp speeds are only computed when SEFLG_SPEED is passed in the flags parameter. Without this flag, zero velocities are returned for efficiency.

2.5. Asteroids — Keplerian approximation vs integrated ephemerides #

What: Minor body positions (Chiron, Ceres, Pallas, Juno, Vesta) can differ by up to ~5° from pyswisseph.

Why: The two libraries compute asteroid orbits using radically different methods:

• pyswisseph uses pre-integrated ephemerides from NASA JPL stored in dedicated asteroid ephemeris files. These are computed by numerical integration that includes gravitational perturbations from all major planets, relativistic corrections, solar radiation pressure, and other effects. The result is sub-arcsecond precision.

• libephemeris uses a Keplerian approximation by default: it treats the asteroid as orbiting the Sun on an ideal ellipse defined by its mean orbital elements. This ignores:

  • Gravitational perturbations from Jupiter (dominant effect for Chiron, which orbits between Saturn and Uranus)
  • Perturbations from Saturn and other planets
  • Orbital resonance effects
  • Secular variations of the orbital elements over time

Near the epoch of the orbital elements, the Keplerian approximation is accurate (< 1°). But it degrades with time because the real orbit is continuously perturbed. Chiron is particularly affected because its orbit is chaotic — small perturbations from Saturn and Uranus grow exponentially.

Mitigation: libephemeris supports loading SPK kernels from JPL Horizons for any minor body:

import libephemeris as eph
eph.set_auto_spk_download(True)  # Automatic download from JPL Horizons

With SPK kernels, all minor body calculations achieve sub-arcsecond precision matching JPL Horizons exactly. The Keplerian fallback exists only for cases where SPK data is unavailable.

Note: The JPL DE440/DE441 ephemerides used by libephemeris cover only the major planets (Mercury–Pluto) and the Moon. Asteroid positions require separate data sources regardless of the ephemeris generation.

---

3. Bugs Found and Fixed #

The deep validation effort uncovered 12 bugs in libephemeris, all of which have been fixed and verified. This section documents them as evidence of the validation’s thoroughness.

3.1. Output flag handling (2 bugs) #

3.2. Unit and threshold errors (2 bugs) #

3.3. House system bug (1 bug) #

3.4. Fixed star bugs (3 bugs) #

3.5. Lunar eclipse classification (2 bugs) #

The Danjon atmospheric shadow enlargement is a well-established correction: Earth’s atmosphere refracts sunlight around the limb, making the geometric shadow ~1.2% larger than it would be without atmosphere. The factor 1/85 was determined empirically by André Danjon and is used by the Astronomical Almanac and by Swiss Ephemeris.

3.6. Algorithmic improvements (2 bugs) #

---

4. API Signature Differences #

libephemeris aims for 1:1 API compatibility with pyswisseph, but some function signatures differ. Developers migrating from pyswisseph should be aware of these:

Return value differences #

Parameter differences #

Structural differences #

libephemeris-only extensions #

These functions exist in libephemeris but have no pyswisseph equivalent:

---

5. Validation Methodology #

Test infrastructure #

The validation consists of 5 test suites totaling 1,619 automated tests:

Test parameters #

• Mode: Skyfield only (LEB mode not tested in this comparison)
• Date range: 1550–2650 CE (full DE440 range), with concentration around 1900–2100
• Sample density: 100–210 dates per test, distributed to cover equinoxes, solstices, eclipses, and random dates
• Locations: 11 global locations including equator, tropics, mid-latitudes, Arctic, and Antarctic
• Flags: All individual flags (SEFLG_SPEED, SEFLG_EQUATORIAL, SEFLG_J2000, SEFLG_NONUT, SEFLG_NOABERR, SEFLG_NOGDEFL, SEFLG_TRUEPOS, SEFLG_RADIANS, SEFLG_XYZ, SEFLG_HELCTR, SEFLG_BARYCTR, SEFLG_ICRS, SEFLG_SIDEREAL) and common combinations
• House systems: All 24 supported systems

What “pass” means #

Each test compares libephemeris output against pyswisseph output with tolerance thresholds appropriate to the quantity being measured:

These tolerances were determined empirically through exhaustive comparison testing and independently verified against JPL Horizons, astropy/ERFA, and SIMBAD (see Section 6). Earlier versions of this document had much looser tolerances (e.g., 0.15° for True Node, 1.5° for latitude) that have been tightened by 100–1500× after triangulated verification showed the actual agreement is far better.

Final results #

All 87 exported swe_* functions are covered by at least one test suite.

---

6. Independent Verification Results #

These results are from triangulated comparisons: libephemeris vs pyswisseph vs independent source (JPL Horizons, astropy/ERFA). The purpose is to determine, for each area of disagreement, which implementation is more astronomically accurate.

6.1. Lunar True Node — match JPL Horizons to < 0.01" #

Method: Computed True Node (Ω) using all three sources across 24 dates (1950–2050).

Conclusion: Both libraries are effectively identical for True Node longitude. The old test tolerance of 0.15° was absurdly relaxed (actual agreement is 150× tighter). Tightened to 0.001°.

6.2. True Lilith (Osculating Apogee) — both equivalent #

Method: Compared osculating apogee longitude using all three sources across 200 dates (1950–2050).

The ~240" offset from Horizons is not a bug — it’s inherent to the two-body eccentricity vector formula (e = (v×h)/μ - r/|r|), which ignores solar perturbations on the Moon. Horizons uses a different effective GM that accounts for perturbations.

LibEphemeris matches pyswisseph to mean 0.1", max 0.5" (effectively identical). Old tolerance of 0.1° tightened to 0.001°.

6.3. J2000 frame for lunar bodies — LibEphemeris more accurate #

Method: Compared J2000 ecliptic coordinates across planets and lunar bodies.

Finding: For planets (Sun, Moon, Mars, Jupiter), both libraries agree with astropy/ERFA to < 1" — no meaningful difference.

However, for lunar nodes and Lilith in J2000 frame, pyswisseph applies a systematic ~14" offset that should not exist at the J2000.0 epoch. At J2000.0, tropical and J2000 ecliptic coordinates are identical by definition (zero precession), yet pyswisseph shifts the position by ~0.004°. LibEphemeris correctly returns identical tropical and J2000 values at the J2000.0 epoch.

Conclusion: LibEphemeris has a more accurate J2000 frame transformation for analytically-computed bodies.

6.4. Latitude, equatorial, velocity — all verified identical #

Comprehensive measurement of latitude, equatorial (RA/Dec), and velocity differences for all lunar nodes/Lilith across all core dates shows:

All previous tolerances (0.2–1.5°) were wildly over-conservative. Tightened to reflect actual measured precision.

6.5. Fixed star flags — previously silently ignored #

The fixed_stars.py module previously handled only 4 of 19 SEFLG flags. Most critically, SEFLG_SIDEREAL returned tropical coordinates without warning. This has been fixed — all meaningful flags are now handled: SEFLG_SIDEREAL, SEFLG_J2000, SEFLG_NONUT, SEFLG_XYZ, SEFLG_RADIANS, SEFLG_TRUEPOS, SEFLG_MOSEPH, SEFLG_SPEED3, SEFLG_TOPOCTR.

6.6. Fixed star catalog — cross-checked against Hipparcos/SIMBAD #

All 116 catalog stars were independently verified against authoritative sources:

Proper motions updated to van Leeuwen 2007 (new Hipparcos reduction, A&A 474, 653-664):

• 99 stars had proper motion values updated from the original 1997 Hipparcos catalog
• Data independently sourced from CDS/VizieR catalog I/311/hip2 via TAP query
• Largest correction: Tarf (Beta Cancri) — 18.3" position error at 100 years with old PM

Position (RA/Dec) cross-checked against SIMBAD:

• All 10 principal stars verified to <0.02" against SIMBAD J2000 positions
• Two catalog bugs found and fixed:
  • Algedi: coordinates were for Alpha-1 Cap instead of Alpha-2 Cap (HIP 100064)
  • Asellus Borealis: HIP number was wrong (43103 = Iota Cnc, corrected to 42806 = Gamma Cnc)

Post-update agreement with SE (101 comparable stars at J2025.0):

• 100% within 0.002° (7.2")
• 98% within 0.5"
• 80% within 0.1"
• Max difference: Rigil Kentaurus 0.51" (nearest star — parallax not modeled)
• Remaining sub-arcsecond differences are from Skyfield vs SE precession/nutation pipeline

IAU WGSN star name differences (5 stars resolve to different physical components):

• Menkar: we use Alpha Ceti (IAU WGSN), SE uses Lambda Ceti
• Algedi: we use Alpha-2 Cap (IAU), SE uses Alpha-1 Cap
• Algieba, Albireo, Almach: different component designations

Independent astropy verification (10 principal stars, 3 epochs):

• At J2025.0: LibEphemeris wins longitude 4/10, SE wins 6/10 vs astropy
• At J2025.0: LibEphemeris wins latitude 5/10, SE wins 3/10 vs astropy
• At J2100.0: LibEphemeris wins longitude 5/10, SE wins 5/10 vs astropy
• Sirius 0.24" latitude offset traced to annual parallax (not modeled — Sirius is 2.6 pc)
• Fomalhaut 0.11" longitude offset also from parallax (7.7 pc)

6.7. Heliocentric, barycentric, equatorial, and XYZ modes — verified #

Comprehensive testing across 4 coordinate modes, 10 bodies, 10 dates (1950–2050):

Heliocentric (SEFLG_HELCTR) — bodies Mercury–Pluto:

• Position: < 0.0004° (1.1") max (Mercury), sub-arcsecond for all bodies
• Speed: < 0.0002°/day

Barycentric (SEFLG_BARYCTR) — bodies Moon–Pluto:

• Position: < 0.001° for all bodies except Sun
• Barycentric Sun: up to 0.04° (138") in angular terms, but this is a distance-amplification artifact. The actual 3D positional difference is only ~120 km (0.017% of the solar radius), amplified by the tiny Sun-SSB distance (~0.001–0.009 AU). Independent verification against raw Skyfield/JPL DE440 confirms libephemeris is closer to the source ephemeris at J2000.

Equatorial (SEFLG_EQUATORIAL) — Sun, Moon, Mars, Jupiter:

• RA: < 0.0005° (1.7") max (Moon)
• Dec: < 0.0002° (0.6") max

XYZ Cartesian (SEFLG_XYZ) — all bodies:

• Position: < 0.00005 AU for all bodies (< 0.00004 AU for Sun–Saturn)
• Neptune/Pluto show ~0.00003 AU max, corresponding to sub-arcsecond angular difference at their distances (30+ AU)

Bug found and fixed: SEFLG_XYZ and SEFLG_RADIANS flags were not preserved in the return flag of swe_calc_ut() / swe_calc(). These output format flags were stripped before calculation but not restored in the returned retflag. Now fixed.

---

7. Intentional divergences from Swiss Ephemeris #

LibEphemeris aims for 1:1 compatibility with pyswisseph, but in specific cases where Swiss Ephemeris has a demonstrable behavioral bug, LibEphemeris prioritizes correctness over compatibility.

7.1. SIDEREAL + J2000 for TrueNode, OscuApog, IntpApog, IntpPerg #

Status: Intentional divergence since leb/precision branch.

Observed behavior: pyswisseph silently ignores SEFLG_J2000 for SE_TRUE_NODE, SE_OSCU_APOG, SE_INTP_APOG, and SE_INTP_PERG when SEFLG_SIDEREAL is also set. The same combination works correctly for SE_MEAN_NODE and SE_MEAN_APOG. No error or warning is emitted.

Why it is incorrect: Ayanamsha (1D longitude zero-point shift) and J2000 ecliptic precession (3D plane rotation) are geometrically distinct, composable operations. The internal inconsistency between mean and true bodies, combined with a growing error proportional to ecliptic precession (~0.34° at 2024, ~14° at 3000 CE, ~28° at 0 CE), confirms this is a code-path bug rather than a design decision.

Physical evidence: With the pyswisseph behavior, the True Node ends up ~29° from the Mean Node at 0 CE under SIDEREAL | J2000 — physically impossible (the true node oscillates ±1.5° around the mean). With the LibEphemeris fix, the distance returns to ~1.04° (correct).

LibEphemeris fix: SEFLG_J2000 is honored for all bodies uniformly. The algorithm uses mean ayanamsha (no nutation component) and applies J2000 ecliptic precession after the sidereal correction — the same pipeline already used correctly for mean bodies.

Impact: Only affects users who combine SEFLG_SIDEREAL | SEFLG_J2000 on these four bodies. Using SEFLG_SIDEREAL alone (the standard astrological use case) produces identical results to pyswisseph.

Full analysis: se-bug-sidereal-j2000-nodes.md

---

8. References #

1. Park, R.S. et al. (2021). “The JPL Planetary and Lunar Ephemerides DE440 and DE441.” Astronomical Journal, 161(3), 105.
2. Folkner, W.M. et al. (2014). “The Planetary and Lunar Ephemerides DE430 and DE431.” Interplanetary Network Progress Report, 196, 1-81.
3. Stephenson, F.R., Morrison, L.V. & Hohenkerk, C.Y. (2016). “Measurement of the Earth’s rotation: 720 BC to AD 2015.” Proceedings of the Royal Society A, 472, 20160404.
4. Espenak, F. & Meeus, J. (2006). “Five Millennium Canon of Solar Eclipses: -1999 to +3000.” NASA/TP-2006-214141.
5. Danjon, A. (1951). “Les éclipses de Lune par la pénombre en 1951.” L’Astronomie, 65, 51-53.
6. Chapront, J. et al. (2002). “A new determination of lunar orbital parameters.” Astronomy & Astrophysics, 387, 700-709.
7. ESA (1997). The Hipparcos and Tycho Catalogues. ESA SP-1200.