AstroEquations

A comprehensive Elixir library of scientific and astronomical equations.

696+ pure functions across 23 modules — all in SI units, fully typed, fully documented, zero runtime dependencies.

Modules

Installation

# mix.exs
def deps do
  [
    {:astroequations, "~> 0.3"}
  ]
end

Quick Start

alias AstroEquations.Physics.{Energy, SpecialRelativity, Thermodynamics}
alias AstroEquations.AstrophysicsAndAstronomy.{Astrometry, BlackHole, Stars}
alias AstroEquations.Mathematics.Notation

# Classical mechanics
Energy.kinetic_energy(1.0, 10.0)              #=> 50.0  (J)
Energy.escape_velocity(5.972e24, 6.371e6)     #=> 11_185.7  (m/s)

# Special Relativity
c = Notation.speed_of_light()
SpecialRelativity.gamma_factor(0.9 * c)       #=> 2.294
SpecialRelativity.time_dilation(1.0, 0.9 * c) #=> 2.294  (seconds)

# Thermodynamics
Thermodynamics.carnot_efficiency(800, 300)    #=> 0.625
Thermodynamics.wiens_displacement(5778)       #=> 5.015e-7  (m — Sun's peak)

# Astrophysics
BlackHole.schwarzschild_radius(1.989e30)      #=> 2953.25  (m)
BlackHole.hawking_temperature(1.989e30)       #=> ~6.17e-8  (K)
Stars.nuclear_timescale(1.0)                  #=> 1.0e10  (yr — Sun's lifetime)
Astrometry.luminosity_distance(1.0)           #=> 857.6  (Mpc at z = 1)

# Unit conversions
Notation.pc_to_m(1)       #=> 3.085_677_581e16  (m)
Notation.ev_to_j(13.6)    #=> 2.179e-18          (J)
Notation.solar_mass()     #=> 1.988_92e30         (kg)

Design

Pure functions

Every function is a pure mathematical transformation — no state, no side effects. Safe in any concurrent or distributed context.

SI units throughout

All inputs and outputs use SI base units unless explicitly stated otherwise in the function documentation (e.g. nuclear_timescale returns years, recession_velocity uses km/s for conventional astronomy usage).

Input guards

Physics-critical functions carry when is_positive(mass) style guards that reject nonsensical inputs at the boundary with a FunctionClauseError rather than silently producing NaN or incorrect results downstream.

# These raise FunctionClauseError immediately:
Energy.kinetic_energy(-1.0, 10.0)      # negative mass
BlackHole.schwarzschild_radius(0)      # zero mass
Oscillations.spring_period(-5.0, 1.0) # negative spring constant

Composable guards

Every module exports three reusable guards you can import into your own code:

import AstroEquations.Physics.Energy,
  only: [is_positive: 1, is_non_negative: 1, is_real: 1]

def specific_intensity(flux, area) when is_positive(flux) and is_positive(area) do
  flux / area
end

Fully typed

Every public function has @spec, @doc, @doc since:, and domain-typed parameters. Every module exports @type definitions with @typedoc. Dialyzer and ExDoc both have full coverage.

Quality and CI

# Full quality check (format + credo + dialyzer + tests)
mix check

# Auto-fix formatting then strict lint
mix lint

# Run tests with coverage report
mix coveralls.html

# Tests for a single namespace
mix test test/physics/

# Only fast unit tests (skip @tag :property)
mix test --exclude property

# CI pipeline (same as check but also verifies no unused deps)
mix ci

Contributing

1. Fork and create a feature branch.
2. Follow the conventions in existing modules:
   • Every new public function needs @spec, @doc, @doc since:, at least one ## Examples block, and appropriate input guards.
   • Large number literals must use underscore separators (2.997_924_58e8).
   • Zero-arity functions must not use parentheses in their def line.
   • Predicate functions must not start with is_ (use foo? not is_foo?).
3. Run mix check — all checks must pass.
4. Update CHANGELOG.md under [Unreleased].

License

Apache-2.0