AstroUtils

AstroUtils is a small Elixir package for spherical geometry, vector and matrix math, circular statistics, Keplerian mechanics, and time-scale helper functions.

The library is pure computation: it performs no I/O, starts no processes, and has no runtime dependencies. It ships no ephemeris data — you supply the numbers, it does the trigonometry.

Installation

Add astro_utils to your dependencies:

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

Modules

Module	Purpose
`AstroUtils.Angle`	Angle normalization, conversion, angular distance, and signed deltas
`AstroUtils.Vector`	3D vector operations on `{x, y, z}` tuples
`AstroUtils.Matrix3`	3x3 rotation matrices and vector multiplication
`AstroUtils.Coordinates`	Spherical coordinate transforms such as ecliptic longitude to altitude and azimuth
`AstroUtils.Kepler`	Kepler equation solving, true anomaly/radius conversion, and orbital-plane rotations
`AstroUtils.CircularStats`	Circular mean and minimal covering arc for angular samples
`AstroUtils.Time`	Julian-century helpers for time-dependent formulae
`AstroUtils.Math`	Small numeric helpers

Conventions

Angles are in degrees except where a name says _rad: AstroUtils.Matrix3 rotations and AstroUtils.Kepler anomalies take radians.
Longitudes normalize to [0, 360). Signed deltas use (-180, 180].
Vectors are {x, y, z} float tuples. Matrices are row-major lists of three three-element lists.
Distances are unitless: whatever unit you pass in comes back out. Kepler argument names say AU because that is the common case, not a requirement.
Azimuth is measured from North, increasing eastward (0° = N, 90° = E).

Examples

Angles, including the wrap-around cases that trip up naive arithmetic:

AstroUtils.Angle.normalize_360(725.0)
# => 5.0

AstroUtils.Angle.angular_distance(359.0, 1.0)
# => 2.0

AstroUtils.Angle.signed_delta(1.0, 359.0)
# => -2.0

AstroUtils.CircularStats.circular_mean([350.0, 10.0])
# => 0.0

AstroUtils.CircularStats.circular_mean([90.0, 270.0])
# => :undefined

AstroUtils.CircularStats.minimal_covering_arc([350.0, 10.0, 20.0])
# => {:arc, 30.0, 350.0}

Vectors and rotations. Rotation matrices act on vectors (an active rotation); transpose one to invert it:

alias AstroUtils.{Matrix3, Vector}

Vector.normalize({3.0, 4.0, 0.0})
# => {0.6, 0.8, 0.0}

Vector.cross({1.0, 0.0, 0.0}, {0.0, 1.0, 0.0})
# => {0.0, 0.0, 1.0}

Matrix3.rot_z(:math.pi() / 2) |> Matrix3.multiply_vector({1.0, 0.0, 0.0})
# => {6.123233995736766e-17, 1.0, 0.0}

Position a body from its orbital elements: solve Kepler's equation, convert to a true anomaly and radius, then rotate the orbital plane into the ecliptic frame.

alias AstroUtils.Kepler

a_au = 2.5
e = 0.15
mean_anomaly_rad = 0.75

eccentric = Kepler.solve_kepler(mean_anomaly_rad, e)
{true_anomaly, r} = Kepler.true_anomaly_and_radius(eccentric, e, a_au)

Kepler.orbital_to_ecliptic(
  r * :math.cos(true_anomaly),
  r * :math.sin(true_anomaly),
  # argument of perihelion, inclination, longitude of ascending node (degrees)
  60.0,
  8.0,
  120.0
)
# => {-1.231328244081215, -1.8698914150208263, 0.2812653910289619}

AstroUtils.Time.julian_centuries/1 produces the T argument that Meeus, IERS, and IAU polynomial series expect:

AstroUtils.Time.julian_centuries(2451545.0)
# => 0.0

Documentation

Published docs live at hexdocs.pm/astro_utils. Build them locally with mix docs.

License

MIT. See LICENSE.