Swisseph

Swiss Ephemeris for Ruby

Native Ruby bindings for the Swiss Ephemeris library (v2.10.3a), providing high-precision astronomical calculations for astrological applications.

History & Motivation

This gem is a modernized fork of the original aakara/swe4r. Since the original project has been abandoned, this version was created to:

Ensure compatibility with modern Ruby versions.
Automate the build process using CMake.
Provide more idiomatic Ruby aliases and convenience methods.
Maintain active support for the latest Swiss Ephemeris releases.

Convenience Features

Shorthand Methods

All swe_* methods are also available without the swe_ prefix:

# Traditional way:
Swisseph.swe_julday(2024, 1, 1, 12.0)

# Modern shorthand:
Swisseph.julday(2024, 1, 1, 12.0)

Module Aliases

For even shorter code, you can use the Sweph alias:

Sweph.julday(2024, 1, 1, 12.0)

Thread Safety

The underlying Swiss Ephemeris C library keeps process-global state and a shared data-file descriptor, so it is not thread-safe -- two threads inside it at once can segfault the process. Every native call (and its shorthand alias) is serialized through one global re-entrant lock, Swisseph::LOCK, so the bindings are safe to call from multi-threaded hosts (e.g. a threaded Puma app with in-process background workers). A single-threaded caller never waits for the lock; when multiple threads call concurrently they are serialized (a brief wait, far cheaper than the crash it prevents).

Installation

gem install swisseph

Or add to your Gemfile:

gem 'swisseph'

Build Requirements

This gem requires CMake 3.14 or later to build from source. CMake is used to automatically download the Swiss Ephemeris library from GitHub during installation.

Installing CMake:

macOS: brew install cmake
Ubuntu/Debian: sudo apt-get install cmake
Windows: Download from cmake.org

Building swetest CLI

The Swiss Ephemeris includes swetest, a command-line tool for testing calculations. To build it:

rake swetest:build

Then copy the binary to your PATH:

cp ext/swisseph/swisseph_src/swetest ~/bin/

Quick Examples

Calculate Planetary Position

require 'swisseph'

# Get Julian day for May 14, 2012 at 10:15
jd = Sweph.julday(2012, 5, 14, 10.25)

# Calculate Sun position using Moshier ephemeris
sun = Sweph.calc_ut(jd, Sweph::SE_SUN, Sweph::SEFLG_MOSEPH | Sweph::SEFLG_SPEED)

puts "Sun longitude: #{sun[0]}°"
puts "Sun latitude: #{sun[1]}°"

Calculate House Cusps

require 'swisseph'

jd = Sweph.julday(2012, 5, 14, 10.25)
lat, lon = 45.45, -112.18

# Calculate Placidus houses
cusps, angles = Sweph.houses(jd, lat, lon, 'P')

puts "Ascendant: #{angles[0]}°"
puts "House 1: #{cusps[1]}°"

Supported Functions

The gem provides full coverage of the Swiss Ephemeris API. All functions are available in both swe_prefix and shorthand forms.

Category	Key Functions
Planets	`calc_ut`, `calc`, `get_orbital_elements`, `pheno_ut`
Fixed Stars	`fixstar_ut`, `fixstar2_ut`, `fixstar_mag`
Houses	`houses`, `houses_ex`, `house_pos`, `house_name`
Eclipses	`sol_eclipse_when_glob`, `lun_eclipse_when`, `sol_eclipse_where`
Transits	`solcross_ut`, `mooncross_ut`, `rise_trans`
Time	`julday`, `revjul`, `utc_to_jd`, `deltat`, `sidtime`
Utilities	`set_ephe_path`, `set_topo`, `get_planet_name`, `split_deg`

Constants

The gem provides constants for planets, calculation flags, and more:

# Bodies
Swisseph::SE_SUN, SE_MOON, SE_MERCURY, SE_VENUS, SE_MARS...
# Flags
Swisseph::SEFLG_MOSEPH, SEFLG_SWIEPH, SEFLG_SPEED, SEFLG_SIDEREAL...
# Houses
'P' (Placidus), 'K' (Koch), 'E' (Equal), 'C' (Campanus)...

Ephemeris Files

The Moshier ephemeris (SEFLG_MOSEPH) is built-in and requires no files.

For high-precision calculations, a minimal set of Swiss Ephemeris data files is automatically included during installation. For extended time ranges or asteroid files, download them from astro.com and configure:

Sweph.set_ephe_path('/path/to/ephemeris/files')

Documentation

License

GPL-2.0-or-later. See LICENSE for details. Swiss Ephemeris library is (C) Astrodienst AG.