| License | GPL-2 |
|---|---|
| Maintainer | swiss-ephemeris@lfborjas.com |
| Portability | POSIX |
| Safe Haskell | None |
| Language | Haskell2010 |
SwissEphemeris
Description
Exposes types and functions that mirror the rich functionality of Swiss Ephemeris.
Currently only certain bodies are exposed as data constructors, same for the major house systems. This is for the sake of simplicity
only, if you need more, please refer to the bundled header files in csrc.
You'll need to procure ephemeris files (see the official site, linked above) if you wish to obtain positions for planets outside of the main planetary bodies in the solar system, or before 3000 B.C or after 3000 A.D. For example, the test suite uses a small ephemeris that includes data for the asteroid Chiron, which is astrologically relevant in most modern practices.
Currently, only a few select functions that are useful for western horoscopy are exported. There's a wealth of other calculations possible with the underlying library, however, please refer to their documentation and the bundled sources for ideas!
Synopsis
- newtype JulianTime = JulianTime {}
- newtype SiderealTime = SiderealTime {}
- type HouseCusp = Double
- data SplitDegreesOption
- data Planet
- data HouseSystem
- data ZodiacSignName
- data NakshatraName
- data EclipticPosition = EclipticPosition {}
- data EquatorialPosition = EquatorialPosition {}
- data GeographicPosition = GeographicPosition {}
- data HousePosition = HousePosition {}
- data ObliquityInformation = ObliquityInformation {}
- data Angles = Angles {}
- data CuspsCalculation = CuspsCalculation {
- houseCusps :: [HouseCusp]
- angles :: Angles
- systemUsed :: HouseSystem
- data LongitudeComponents = LongitudeComponents {}
- setEphemeridesPath :: FilePath -> IO ()
- setNoEphemeridesPath :: IO ()
- closeEphemerides :: IO ()
- withEphemerides :: FilePath -> IO a -> IO a
- withoutEphemerides :: IO a -> IO a
- calculateEclipticPosition :: JulianTime -> Planet -> IO (Either String EclipticPosition)
- calculateEquatorialPosition :: JulianTime -> Planet -> IO (Either String EquatorialPosition)
- calculateObliquity :: JulianTime -> IO (Either String ObliquityInformation)
- calculateCusps :: HouseSystem -> JulianTime -> GeographicPosition -> IO CuspsCalculation
- calculateCuspsLenient :: HouseSystem -> JulianTime -> GeographicPosition -> IO CuspsCalculation
- calculateCuspsStrict :: HouseSystem -> JulianTime -> GeographicPosition -> IO (Either String CuspsCalculation)
- equatorialToEcliptic :: ObliquityInformation -> EquatorialPosition -> EclipticPosition
- eclipticToEquatorial :: ObliquityInformation -> EclipticPosition -> EquatorialPosition
- calculateSiderealTime :: JulianTime -> ObliquityInformation -> IO SiderealTime
- calculateSiderealTimeSimple :: JulianTime -> IO SiderealTime
- calculateHousePosition :: HouseSystem -> Double -> GeographicPosition -> ObliquityInformation -> EclipticPosition -> IO (Either String HousePosition)
- calculateHousePositionSimple :: HouseSystem -> JulianTime -> GeographicPosition -> EclipticPosition -> IO (Either String HousePosition)
- julianDay :: Int -> Int -> Int -> Double -> JulianTime
- deltaTime :: JulianTime -> IO Double
- defaultSplitDegreesOptions :: [SplitDegreesOption]
- splitDegrees :: [SplitDegreesOption] -> Double -> LongitudeComponents
- splitDegreesZodiac :: Double -> LongitudeComponents
Documentation
newtype JulianTime Source #
Represents an instant in Julian time.
see:
8. Date and time conversion functions
also cf. julianDay
Constructors
| JulianTime | |
Fields | |
Instances
| Eq JulianTime Source # | |
Defined in SwissEphemeris.Internal | |
| Ord JulianTime Source # | |
Defined in SwissEphemeris.Internal Methods compare :: JulianTime -> JulianTime -> Ordering # (<) :: JulianTime -> JulianTime -> Bool # (<=) :: JulianTime -> JulianTime -> Bool # (>) :: JulianTime -> JulianTime -> Bool # (>=) :: JulianTime -> JulianTime -> Bool # max :: JulianTime -> JulianTime -> JulianTime # min :: JulianTime -> JulianTime -> JulianTime # | |
| Show JulianTime Source # | |
Defined in SwissEphemeris.Internal Methods showsPrec :: Int -> JulianTime -> ShowS # show :: JulianTime -> String # showList :: [JulianTime] -> ShowS # | |
newtype SiderealTime Source #
Represents an instant in sidereal time
Constructors
| SiderealTime | |
Fields | |
Instances
| Eq SiderealTime Source # | |
Defined in SwissEphemeris.Internal | |
| Ord SiderealTime Source # | |
Defined in SwissEphemeris.Internal Methods compare :: SiderealTime -> SiderealTime -> Ordering # (<) :: SiderealTime -> SiderealTime -> Bool # (<=) :: SiderealTime -> SiderealTime -> Bool # (>) :: SiderealTime -> SiderealTime -> Bool # (>=) :: SiderealTime -> SiderealTime -> Bool # max :: SiderealTime -> SiderealTime -> SiderealTime # min :: SiderealTime -> SiderealTime -> SiderealTime # | |
| Show SiderealTime Source # | |
Defined in SwissEphemeris.Internal Methods showsPrec :: Int -> SiderealTime -> ShowS # show :: SiderealTime -> String # showList :: [SiderealTime] -> ShowS # | |
type HouseCusp = Double Source #
The cusp of a given "house" or "sector". It is an ecliptic longitude. see: 14.1 House cusp calculation and 6.2 Astrological house systems
data SplitDegreesOption Source #
Options to split a Double representing degrees:
RoundSeconds -- round at the seconds granularity (omits seconds fraction.)
RoundMinutes -- round at the minutes granularity.
RoundDegrees -- round at the degrees granularity.
SplitZodiacal -- relative to zodiac signs.
SplitNakshatra -- relative to nakshatra.
KeepSign -- when rounding, don't round if it'll move it to the next zodiac/nakshatra sector.
KeepDegrees -- when rounding, don't round if it'll move it to the next degree.
Constructors
| RoundSeconds | |
| RoundMinutes | |
| RoundDegrees | |
| SplitZodiacal | |
| SplitNakshatra | |
| KeepSign | |
| KeepDegrees |
Instances
All bodies for which a position can be calculated. Covers planets in the solar system, points between the Earth and the Moon, and astrologically significant asteroids (currently, only Chiron, but ephemerides data is available for others.) More at 2.1 Planetary and lunar ephemerides and 3.2 bodies
Constructors
| Sun | |
| Moon | |
| Mercury | |
| Venus | |
| Mars | |
| Jupiter | |
| Saturn | |
| Uranus | |
| Neptune | |
| Pluto | |
| MeanNode | |
| TrueNode | |
| MeanApog | |
| OscuApog | |
| Earth | |
| Chiron |
Instances
data HouseSystem Source #
The major house systems. The underlying library supports many more, including the 36-cusp outlier Gauquelin. More info at 6.2 Astrological house systems and 14. House cusp calculation
Constructors
| Placidus | |
| Koch | |
| Porphyrius | |
| Regiomontanus | |
| Campanus | |
| Equal | |
| WholeSign |
Instances
data ZodiacSignName Source #
Represents western zodiac signs. Unless otherwise stated, they correspond to tropical divisions of the ecliptic, vs. the actual constellations.
Constructors
| Aries | |
| Taurus | |
| Gemini | |
| Cancer | |
| Leo | |
| Virgo | |
| Libra | |
| Scorpio | |
| Sagittarius | |
| Capricorn | |
| Aquarius | |
| Pisces |
Instances
data NakshatraName Source #
Nakshatras, provided for thoroughness, please excuse any misspellings! List from: https://en.wikipedia.org/wiki/List_of_Nakshatras note that the underlying library uses 27 nakshatras, so Abhijit is omitted.
Constructors
Instances
data EclipticPosition Source #
Position data for a celestial body on the ecliptic, includes rotational speeds. see: 3.4 Position and speed
Constructors
| EclipticPosition | |
Instances
data EquatorialPosition Source #
Represents a position on the celestial sphere, with speed information included.
Constructors
| EquatorialPosition | |
Fields
| |
Instances
data GeographicPosition Source #
Represents a point on Earth, with negative values for latitude meaning South, and negative values for longitude meaning West. No speed information is included (or needed,) because all calculations are geocentric.
Constructors
| GeographicPosition | |
Instances
data HousePosition Source #
The house a celestial body is in.
Constructors
| HousePosition | |
Fields | |
Instances
| Eq HousePosition Source # | |
Defined in SwissEphemeris.Internal Methods (==) :: HousePosition -> HousePosition -> Bool # (/=) :: HousePosition -> HousePosition -> Bool # | |
| Show HousePosition Source # | |
Defined in SwissEphemeris.Internal Methods showsPrec :: Int -> HousePosition -> ShowS # show :: HousePosition -> String # showList :: [HousePosition] -> ShowS # | |
| Generic HousePosition Source # | |
Defined in SwissEphemeris.Internal Associated Types type Rep HousePosition :: Type -> Type # | |
| type Rep HousePosition Source # | |
Defined in SwissEphemeris.Internal type Rep HousePosition = D1 (MetaData "HousePosition" "SwissEphemeris.Internal" "swiss-ephemeris-1.2.0.0-JDXT6ozMaY2D0XcAJvWZrZ" False) (C1 (MetaCons "HousePosition" PrefixI True) (S1 (MetaSel (Just "houseNumber") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Int) :*: S1 (MetaSel (Just "houseCuspDistance") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Double))) | |
data ObliquityInformation Source #
Includes the obliquity of the ecliptic, the Nutation as longitude as well as mean values.
Constructors
| ObliquityInformation | |
Fields | |
Instances
Relevant angles: ascendant and MC, plus other "exotic" ones: 14. House cusp calculation
Constructors
| Angles | |
Fields
| |
Instances
data CuspsCalculation Source #
Result of calculating the cusps for a given event; will include a list of cusps (most systems use 12 cusps, Gauquelin uses 36.)
Constructors
| CuspsCalculation | |
Fields
| |
Instances
data LongitudeComponents Source #
A longitude expressed in its constituent parts.
Constructors
| LongitudeComponents | |
Instances
setEphemeridesPath :: FilePath -> IO () Source #
Given a path to a directory, point the underlying ephemerides library to it.
You only need to call this function to provide an explicit ephemerides path,
if the environment variable SE_EPHE_PATH is set, it overrides this function.
setNoEphemeridesPath :: IO () Source #
Explicitly state that we don't want to set an ephemeris path,
which will default to the built-in ephemeris, or use the directory
in the SE_EPHE_PATH environment variable, if set.
closeEphemerides :: IO () Source #
Explicitly release all "cache" pointers and open files obtained by the C library.
withEphemerides :: FilePath -> IO a -> IO a Source #
Run a computation with a given ephemerides path open, and then close it. Note that the computation does not receive the ephemerides, in keeping with the underlying library's side-effectful conventions.
withoutEphemerides :: IO a -> IO a Source #
Run a computation with no explicit ephemerides set, if the SE_EPHE_PATH
environment variable is set, that will be used. If not, it'll fall back to
in-memory data.
calculateEclipticPosition :: JulianTime -> Planet -> IO (Either String EclipticPosition) Source #
Given JulianTime (see julianDay),
and a Planet, returns either the position of that planet at the given time,
if available in the ephemeris, or an error. The underlying library may do IO
when reading ephemerides data.
calculateEquatorialPosition :: JulianTime -> Planet -> IO (Either String EquatorialPosition) Source #
Obtain equatorial position (includes declination) of a planet.
If you've called calculateEclipticPosition in your code, this is a very cheap call, as the data
is already available to the C code.
calculateObliquity :: JulianTime -> IO (Either String ObliquityInformation) Source #
Given a time, calculate ecliptic obliquity and nutation
calculateCusps :: HouseSystem -> JulianTime -> GeographicPosition -> IO CuspsCalculation Source #
Alias for calculateCuspsLenient
calculateCuspsLenient :: HouseSystem -> JulianTime -> GeographicPosition -> IO CuspsCalculation Source #
Given a decimal representation of Julian Time (see julianDay),
a GeographicPosition and a HouseSystem
(most applications use Placidus,) return a CuspsCalculation with all
house cusps in that system, and other relevant Angles.
Notice that certain systems,
like Placidus and Koch, are very likely to fail close to the polar circles; in this
and other edge cases, the calculation returns cusps in the Porphyrius system.
The underlying library may do IO when consulting ephemerides data.
calculateCuspsStrict :: HouseSystem -> JulianTime -> GeographicPosition -> IO (Either String CuspsCalculation) Source #
Unlike calculateCuspsLenient, return a Left value if the required house system
couldn't be used to perform the calculations.
equatorialToEcliptic :: ObliquityInformation -> EquatorialPosition -> EclipticPosition Source #
Convert from an equatorial position to an ecliptic position. Requires
knowledge of obliquity (see calculateObliquity.)
eclipticToEquatorial :: ObliquityInformation -> EclipticPosition -> EquatorialPosition Source #
Convert from an ecliptic position to an equatorial position. Requires
knowledge of obliquity (see calculateObliquity.)
calculateSiderealTime :: JulianTime -> ObliquityInformation -> IO SiderealTime Source #
Given a JulianTime and ObliquityInformation, calculate the equivalent SiderealTime.
prefer it over calculateSiderealTimeSimple if you already obtained ObliquityInformation
for another calculation.
calculateSiderealTimeSimple :: JulianTime -> IO SiderealTime Source #
Given JulianTime, get SiderealTime. May consult ephemerides data, hence it being in IO,
will have to calculate obliquity at the given julian time, so it'll be slightly slower than
calculateSiderealTime.
calculateHousePosition :: HouseSystem -> Double -> GeographicPosition -> ObliquityInformation -> EclipticPosition -> IO (Either String HousePosition) Source #
If you happen to have the correct ARMC for a time and place (obtained from calculateCusps)
and obliquity and nutation,
you can use this method to calculate a planet's house position.
Usually, what you have is just the time and place of the event, and positions of a planet,
in those cases, see calculateHousePositionSimple.
calculateHousePositionSimple :: HouseSystem -> JulianTime -> GeographicPosition -> EclipticPosition -> IO (Either String HousePosition) Source #
Calculates the house position of a body in a house in the given system.
requires the geographic coordinates and time of the birth/event, and the
ecliptic coordinates of the planet/body. You only want this function if
you're working in the polar circle, or with objects that are way off the ecliptic;
for most objects in usual astrological charts, simply seeing which cusps
a planet falls between is sufficient, no need for this more complicated method.
see https://groups.io/g/swisseph/message/4052
NOTES: for the Koch system, this is likely to fail, or return counterintuitive
results. Also, we're doing a bit of a funky conversion between sidereal time and
ARMC, if you calculateCusps, the correct armc will be present in the returned Angles
julianDay :: Int -> Int -> Int -> Double -> JulianTime Source #
Given year, month and day as Int and a time as Double, return
a single floating point number representing absolute JulianTime.
The input date is assumed to be in Gregorian time.
deltaTime :: JulianTime -> IO Double Source #
Given a JulianTime (based on a UniversalTime), calculate the delta
between it and "true time":
See 7. Delta T
It relies on ephemeris data being open, and as such belongs in IO.
NOTE: this could be used to create a JulianTime -> EphemerisTime
function to send down to swe_calc, if we choose to port that one.
defaultSplitDegreesOptions :: [SplitDegreesOption] Source #
Convenient defaults when using splitDegrees:
Omit rounding if it would bring it over the next sign or degree.
splitDegrees :: [SplitDegreesOption] -> Double -> LongitudeComponents Source #
Given a Double representing an ecliptic longitude, split it according to any
options from SplitDegreesOption:
if SplitZodiacal or SplitNakshatra are specified, they're returned
in longitudeZodiacSign and longitudeNakshatra, respectively.
If neither of those is specified, the raw signum is then populated, in
longitudeSignum (-1 for negative, 1, for positive.)
NOTE: this function can also be used for latitudes, speeds or quantities
from other positional systems (like declinations,) but the zodiacal or
nakshatra components would of course be nonsensical.
splitDegreesZodiac :: Double -> LongitudeComponents Source #
Given a longitude, return the degrees it's from its nearest sign,
minutes, and seconds; with seconds rounded. Convenience alias for splitDegrees,
when wanting to display e.g. a table in a horoscope.