Metadata-Version: 2.4
Name: taiyin-ephemeris-semi-analytic
Version: 0.1.0
Summary: A compact frozen-coefficient semi-analytical planetary and lunar ephemeris
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/RedSC1/taiyin-ephemeris-semi-analytic
Project-URL: Repository, https://github.com/RedSC1/taiyin-ephemeris-semi-analytic.git
Project-URL: Issues, https://github.com/RedSC1/taiyin-ephemeris-semi-analytic/issues
Keywords: astronomy,ephemeris,moon,planets,semi-analytical
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Dynamic: license-file

# Taiyin Semi-Analytical Ephemeris

A frozen-coefficient semi-analytical ephemeris covering calendar years
−3000 through +3000. It has no runtime data files, uses only the Python
standard library, and is published as `taiyin-ephemeris-semi-analytic`.

- Mercury through Pluto and the Earth–Moon barycenter use compact series
  independently fitted to JPL DE441.
- Planetary harmonics are generated from one sine/cosine pair per fundamental
  angle, so periodic terms require only multiplication and addition.
- The Moon uses the truncated XL1 lunar theory table from Shouxing
  Astronomical Ephemeris (寿星天文历/寿星万年历), followed by an independently
  fitted DE441 residual correction.
- Earth and Moon heliocentric positions are reconstructed from the EMB and
  the geocentric lunar vector.

## Command line

The input epoch is Julian Date on the TDB time scale:

```bash
pip install taiyin-ephemeris-semi-analytic
taiyin-semi-analytic 2451545.0 301
```

From a source checkout, the original one-file-style demo command remains:

```bash
python3 ephemeris.py 2451545.0 301
```

The command prints JSON containing:

- `xyz_km`: heliocentric ICRF Cartesian coordinates in kilometres;
- `spherical_icrf_rad_km`: spherical longitude, latitude and radius derived
  from that same ICRF vector, in radians, radians and kilometres;
- `ecliptic_lbr_j2000_rad_km`: J2000 ecliptic longitude, latitude and radius,
  in radians, radians and kilometres;
- explicit target, center and frame metadata.

## Python API

```python
from taiyin_semi_analytic import (
    ecliptic_lbr_j2000,
    position,
    result,
    spherical_icrf,
)

xyz = position(2451545.0, 4)  # Mars
icrf_spherical = spherical_icrf(2451545.0, 4)
ecliptic_lbr = ecliptic_lbr_j2000(2451545.0, 4)
record = result(2451545.0, 4)
```

Both spherical functions return `(longitude, latitude, radius)`.  Angles are
in radians and radius is in kilometres.  `spherical_icrf()` uses the ICRF axes;
`ecliptic_lbr_j2000()` returns the conventional L/B/R coordinates referred to
the J2000 mean ecliptic and equinox.

Supported target IDs:

| ID | Target |
|---:|---|
| 1 | Mercury |
| 2 | Venus |
| 3 | Earth–Moon barycenter |
| 4 | Mars |
| 5 | Jupiter system barycenter |
| 6 | Saturn system barycenter |
| 7 | Uranus system barycenter |
| 8 | Neptune system barycenter |
| 9 | Pluto system barycenter |
| 10 | Sun |
| 301 | Moon |
| 399 | Earth |

All returned vectors are Sun-centered.  IDs 301 and 399 are therefore also
heliocentric, not geocentric.

## Accuracy

Held-out validation against DE441 over calendar years −3000 through +3000
gave the following heliocentric angular RMS values for the frozen planetary
series:

| Target | RMS |
|---|---:|
| Mercury | 1.66″ |
| Venus | 0.66″ |
| EMB | 0.56″ |
| Mars | 2.29″ |
| Jupiter | 3.31″ |
| Saturn | 0.29″ |
| Uranus | 3.65″ |
| Neptune | 0.21″ |
| Pluto | 1.53″ |

The corrected geocentric lunar model measured 0.704″ angular RMS and
0.263 km radial RMS on held-out 32-day-grid epochs; maximum errors on that
grid were 5.22″ and 1.52 km.

## Design lineage

Steve Moshier's PLAN404 was an important inspiration for the compact
semi-analytical representation and harmonic-recursion evaluator used here.
The planetary series were developed by fitting to JPL DE441.

The lunar ecliptic-of-date coordinates are rotated to the J2000 ecliptic with
the published [P03 precession model](https://doi.org/10.1051/0004-6361:20031539)
of Capitaine, Wallace, and Chapront.

## Files

- `taiyin_semi_analytic/core.py`: evaluator and public implementation.
- `taiyin_semi_analytic/coefficients.py`: frozen coefficients.
- `taiyin_semi_analytic/__main__.py`: `python -m taiyin_semi_analytic` entry.
- `ephemeris.py`: source-tree command-line demo wrapper.
- `pyproject.toml`: wheel/sdist and console-script configuration.
- `tests/test_ephemeris.py`: standard-library regression tests.
- `NOTICE`: attribution and third-party provenance.

The project is licensed under Apache License 2.0.  The attributed Shouxing
lunar table retains its upstream provenance notice; see `NOTICE`.
