Angelus

Angelus is an Elixir ephemeris library backed by NAIF CSPICE and JPL kernels. It provides geocentric ecliptic positions for a small, explicit set of astrological bodies while keeping kernel loading and native SPICE integration visible to the caller.

The v0.1 scope is intentionally limited to ephemeris generation. Natal charts, houses, aspects, orbs, dignities, transits, and other chart-level features are out of scope for this release.

Features

• Geocentric positions in the ECLIPJ2000 frame.
• Ecliptic longitude, latitude, distance in AU, position vectors, velocity vectors, and light-time metadata.
• Default v0.1 JPL/NAIF kernel policy using DE442 and companion body-center kernels.
• Explicit runtime kernel loading; kernels are not loaded implicitly.
• Native SPICE worker distributed as precompiled release artefacts for supported platforms.

Supported Bodies

Angelus v0.1 supports these public body atoms:

[
  :sun,
  :moon,
  :mercury,
  :venus,
  :mars,
  :jupiter,
  :saturn,
  :uranus,
  :neptune,
  :pluto,
  :true_node,
  :mean_node,
  :chiron,
  :lilith
]

The public datetime range is 1900-01-01 through 2100-01-24, inclusive.

Installation

Angelus is not yet published to Hex. Add it from Git while the package is under development:

def deps do
  [
    {:angelus, github: "angelus-astro/angelus", tag: "v0.1.0"}
  ]
end

When published to Hex, the dependency will be:

def deps do
  [
    {:angelus, "~> 0.1.0"}
  ]
end

Requirements

• Elixir ~> 1.19.
• For supported platforms, no local C compiler or CSPICE installation is required when installing from Hex.
• Local source builds require a C compiler available as cc, plus curl, jq, tar, and either sha256sum or shasum.

Precompiled CSPICE-enabled native workers are produced only for macOS Apple Silicon and Linux glibc x86_64.

Quick Start

Fetch dependencies and compile the native worker:

mix deps.get
mix compile

When installed from Hex on one of those supported platforms, compilation downloads the matching precompiled spice_worker. Local development in this repository can force a source build with ANGELUS_FORCE_BUILD=1 or just build.

Download the default v0.1 kernel set:

mix angelus.kernels

This downloads JPL/NAIF kernels into priv/kernels/. It does not load them at runtime.

Load kernels explicitly before calculating positions:

{:ok, _metadata} = Angelus.load_kernels()

{:ok, positions} = Angelus.positions([:sun, :moon], ~U[1990-05-24 06:30:00Z])

positions.sun.longitude
positions.moon.distance_au

Query one body at a time with Angelus.position/3:

{:ok, sun} = Angelus.position(:sun, ~U[2000-01-01 12:00:00Z])

sun.longitude

Kernel Loading

Angelus.load_kernels/0 loads the default files from priv/kernels/.

Use :base_path when kernels live somewhere else:

Angelus.load_kernels(base_path: "/opt/angelus/kernels")

Use :replace to clear an already-loaded kernel set before loading another one:

Angelus.load_kernels(base_path: "/opt/angelus/kernels", replace: true)

You can also pass explicit absolute kernel paths:

Angelus.load_kernels([
  "/opt/angelus/kernels/latest_leapseconds.tls",
  "/opt/angelus/kernels/pck00011.tpc",
  "/opt/angelus/kernels/gm_de440.tpc",
  "/opt/angelus/kernels/de442.bsp",
  "/opt/angelus/kernels/mar099.bsp",
  "/opt/angelus/kernels/jup349.bsp",
  "/opt/angelus/kernels/sat459.bsp",
  "/opt/angelus/kernels/ura184_part-1.bsp",
  "/opt/angelus/kernels/ura184_part-2.bsp",
  "/opt/angelus/kernels/ura184_part-3.bsp",
  "/opt/angelus/kernels/nep105.bsp",
  "/opt/angelus/kernels/plu060.bsp"
])

Explicit paths must form the complete supported v0.1 kernel set. See Angelus.Spice.default_kernel_files/0 for the required filenames.

Return Values

Position APIs return tagged tuples:

{:ok, %Angelus.Ephemeris.BodyPosition{}}
{:ok, %{sun: %Angelus.Ephemeris.BodyPosition{}, moon: %Angelus.Ephemeris.BodyPosition{}}}
{:error, reason}

Angelus.Ephemeris.BodyPosition includes:

• :longitude - geocentric ecliptic longitude in degrees, normalized to [0, 360).
• :latitude - geocentric ecliptic latitude in degrees.
• :distance_au - distance from Earth in astronomical units.
• :position_km and :velocity_km_s - SPICE state vectors.
• :metadata - engine, kernel, target, observer, frame, and version metadata.

Development

Common commands:

mix setup
mix compile
mix test
mix consistency

By default, mix compile may use a published precompiled worker. To force a local source build while working on this repository:

ANGELUS_FORCE_BUILD=1 mix compile

For a fast stub worker without CSPICE:

ANGELUS_FORCE_BUILD=1 mix compile -- SKIP_CSPICE=1

If you have just installed, the repository also provides:

just build             # compile with CSPICE support
just build-stub        # compile stub worker only, no CSPICE download
just test              # run unit tests
just test-integration  # build with CSPICE and run integration tests
just clean             # remove local build outputs and downloaded native libraries

Unit tests can run against the stub worker. Integration tests require the real CSPICE worker and downloaded kernels.

Kernel and Data Licensing

Angelus does not include third-party astrological ephemeris code or data. JPL/NAIF kernels are downloaded separately and distributed under their respective terms.

The source code in this repository is MIT licensed. Native artefacts include components from NAIF CSPICE, distributed under NAIF's respective terms.

Angelus is not affiliated with or endorsed by NASA, JPL, NAIF, IAU, or SOFA.