Architecture Overview #

Codebase metrics, performance bottleneck analysis, and future development vision for LibEphemeris. For the implemented LEB binary ephemeris system, see the LEB Technical Guide.

---

Table of Contents #

1. Codebase Overview
2. Performance Bottleneck Analysis
3. Future Rust Port via PyO3
4. Appendix: Full Module Inventory

---

1. Codebase Overview #

Project Metrics #

Architecture Summary #

LibEphemeris does NOT implement its own orbital integrator. It delegates all positional astronomy to Skyfield (which reads JPL DE440/DE441 SPK kernels via jplephem). The library provides:

• A Swiss Ephemeris-compatible Python API (1:1 with pyswisseph)
• 24 astrological house systems
• 43 sidereal/ayanamsha modes
• Solar/lunar eclipse search and contact point calculation
• Besselian element computation
• Lunar node and Lilith calculations (4 methods)
• Fixed star catalog (102 stars)
• Hypothetical/Uranian body support (8 Hamburg School + Transpluto)
• Minor body/asteroid support with auto-SPK download
• Atmospheric extinction and heliacal visibility models

Runtime Dependencies #

Module Breakdown by LOC #

---

2. Performance Bottleneck Analysis #

2.1 Current Performance Profile #

The library is pure Python with zero native extensions. No Cython, mypyc, C extensions, or compiled code exists anywhere in the project.

Cost per Operation #

2.2 Where CPU Time Is Spent (Priority Order) #

1. Skyfield .observe() calls (dominant cost, ~90%+ of total time) #

Each .observe() involves light-time iteration (2-3 iterations of JPL Chebyshev polynomial evaluation via jplephem). This is the single largest cost factor in every operation.

2. Central difference velocity (3x multiplier) #

The velocity computation in _calc_body() (planets.py:1909-1910) calls itself recursively twice for central difference:

result_prev, _ = _calc_body(t_prev, ipl, flags_no_speed)
result_next, _ = _calc_body(t_next, ipl, flags_no_speed)
velocity = (result_next - result_prev) / (2 * dt)

This means every swe_calc_ut() with SEFLG_SPEED costs 3x the position-only cost. Each of the 3 calls runs the full Skyfield pipeline: .at().observe().apparent().

Total Skyfield calls per swe_calc_ut() with SEFLG_SPEED:

Each .observe() internally iterates light-time (~2-3 iterations), so the true count of JPL ephemeris segment evaluations is approximately 9-12 Chebyshev polynomial evaluations per single swe_calc_ut() call.

3. Eclipse search (combinatorial explosion) #

sol_eclipse_when_glob() call breakdown:

4. No position caching #

When calculating a full chart (10 planets at the same JD), the Earth observer position earth.at(t) is recomputed 30 times (10 planets x 3 pipelines each) despite being identical every time.

5. erfa.nut06a() (mitigated by cache) #

Would be expensive (~0.02ms per call with 1365 nutation terms), but the LRU cache in cache.py (128 entries) makes this negligible for same-JD calculations. Cache hit: ~0.0001ms (200x speedup).

2.3 Existing Caching Infrastructure #

What is NOT cached:

• Planet positions (every swe_calc_ut() hits Skyfield every time)
• Skyfield Time objects (created fresh each call)
• Earth position for observer (recomputed per planet)

2.4 numpy Usage in Hot Paths #

All numpy usage in the hot paths is scalar or small 3-element vector operations (e.g., np.array(offset) for tuple→array conversion). No vectorized batch computation (np.dot, np.matmul, etc.) is used anywhere in the critical path.

---

3. Future Rust Port via PyO3 #

Note: The LEB-reader-only Rust port strategy is also documented in the LEB Technical Guide.

This section describes a vision for porting the full library (~7,800 lines) to Rust, beyond just the LEB reader.

3.1 Strategy #

Once the Python implementation is validated, port the reader + pipeline to Rust. The same .leb file format works for both Python and Rust. The generator stays in Python (it runs once, not performance-critical).

3.2 Rust Crate Structure #

engine/
├── Cargo.toml
├── pyproject.toml          # maturin build config
├── src/
│   ├── lib.rs              # PyO3 module entry point
│   ├── leb.rs              # .leb reader, mmap, index        (~200 lines)
│   ├── chebyshev.rs        # Clenshaw eval + derivative      (~80 lines)
│   ├── calc.rs             # Main calc pipeline               (~400 lines)
│   ├── coords.rs           # ICRS/ecliptic/equatorial transforms (~300 lines)
│   ├── precession.rs       # IAU 2006 polynomial              (~150 lines)
│   ├── light_time.rs       # 3-iteration light-time           (~60 lines)
│   ├── aberration.rs       # Annual aberration                (~100 lines)
│   ├── ayanamsha.rs        # 43 sidereal systems              (~800 lines)
│   ├── houses/             # 25 house systems (26 codes)                 (~2000 lines)
│   │   ├── mod.rs
│   │   ├── placidus.rs
│   │   ├── koch.rs
│   │   └── ...
│   ├── eclipse.rs          # Eclipse search + contacts         (~1500 lines)
│   ├── crossing.rs         # Crossings, stations               (~500 lines)
│   ├── lunar.rs            # Lunar nodes, Lilith               (~400 lines)
│   ├── hypothetical.rs     # Kepler equation, hypotheticals    (~300 lines)
│   ├── stars.rs            # Fixed stars + proper motion       (~200 lines)
│   ├── constants.rs        # All SE_*, SEFLG_*                 (~400 lines)
│   ├── error.rs            # Error types                       (~100 lines)
│   └── pymodule.rs         # PyO3 bindings                     (~800 lines)
│
│   Total: ~7,800 lines Rust

3.3 Rust Dependencies #

[dependencies]
pyo3 = { version = "0.23", features = ["extension-module"] }
memmap2 = "0.9"              # Memory-mapped .leb files
byteorder = "1.5"            # Binary parsing
thiserror = "2"              # Typed errors
parking_lot = "0.12"         # Fast Mutex/RwLock

[dev-dependencies]
approx = "0.5"               # Float comparison in tests
criterion = "0.5"            # Benchmarks

Zero math dependencies: all trigonometry uses f64::sin(), f64::cos(), etc.

3.4 Expected Speedup After Rust Port #

3.5 Python Integration (Transparent Fallback) #

# libephemeris/planets.py
try:
    from libephemeris_engine import Ephemeris as _NativeEphemeris
    _engine = _NativeEphemeris("path/to/ephemeris.leb")
    _HAS_ENGINE = True
except ImportError:
    _HAS_ENGINE = False

def swe_calc_ut(tjd_ut, ipl, iflag):
    if _HAS_ENGINE:
        return _engine.calc_ut(tjd_ut, ipl, iflag)
    reader = state.get_leb_reader()
    if reader is not None:
        return fast_calc.fast_calc_ut(reader, tjd_ut, ipl, iflag)
    return _calc_body_skyfield(...)  # original code, unchanged

Three tiers of performance:

1. Rust engine (~1-5us) - if libephemeris_engine is installed
2. Python .leb reader (~25-75us) - if .leb file is configured
3. Skyfield (~350-1050us) - fallback, always available

3.6 Rust Port Timeline (After Python Validation) #

---

Appendix: Full Module Inventory #

A.1 Coordinate Frames by Body Type #

This table documents the coordinate frame produced by each body’s calculation function, as found in the source code analysis:

A.2 Numerical Algorithms Used #

A.3 House Systems Implemented (24) #

A.4 Ayanamsha Systems (43) #

All 43 systems are implemented in planets.py::_calc_ayanamsa() (~375 lines). They use the IAU 2006 general precession polynomial (5th degree) as the precession backbone, with system-specific reference epochs and offsets.

Categories:

• Formula-based (Lahiri, Fagan-Bradley, Krishnamurti, etc.): aya = offset + precession_polynomial(T)
• Star-based (“True” modes): compute apparent ecliptic longitude of reference star via Skyfield, subtract target position
• Galactic-based: calibrated formulas or galactic pole computation
• User-defined (SE_SIDM_USER): aya = ayan_t0 + [p(T_now) - p(T0)]