Physics.Orbit

Types and functions for dealing with Kepler orbits.

The Orbit data type and dependencies

data Orbit a

Data type defining an orbit parameterized by the type used to represent values

Constructors

Orbit

Fields

• eccentricity :: !(Unitless a)

  The orbit's eccentricity, e.

  eccentricity must be non-negative.

  An eccentricity of 0 describes a circular orbit.

  An eccentricity of less than 1 describes an elliptic orbit.

  An eccentricity equal to 1 describes a parabolic orbit.

  An eccentricity greater than 1 describes a hyperbolic orbit.

• periapsis :: !(Distance a)

  The orbit's periapsis, q.

  periapsis must be positive.

  The periapsis is the distance between the bodies at their closest approach.

• inclinationSpecifier :: !(InclinationSpecifier a)

  The inclinationSpecifier describes the angle between the obtital plane and the reference plane.

• periapsisSpecifier :: !(PeriapsisSpecifier a)

  periapsisSpecifier is Circular iff eccentricity is 0

  The periapsis specifier describes any rotation of the orbit relative to the reference direction in the orbital plane.

• primaryGravitationalParameter :: !(Quantity ((:*) ((:^) Meter (Succ (Succ (Succ 'Zero)))) ((:^) Second (Pred (Pred 'Zero)))) a)

  The gravitational parameter of the system's primary, μ.

  μ is equal to the mass of the primary times <https://en.wikipedia.org/wiki/Gravitational_constant G>.

  primaryGravitationalParameter must be positive.

Instances

Show a => Show (Orbit a)

Defined in Physics.Orbit

Methods

showsPrec :: Int -> Orbit a -> ShowS

show :: Orbit a -> String

showList :: [Orbit a] -> ShowS

Eq a => Eq (Orbit a)

Defined in Physics.Orbit

Methods

(==) :: Orbit a -> Orbit a -> Bool

(/=) :: Orbit a -> Orbit a -> Bool

data InclinationSpecifier a

Along with PeriapsisSpecifier the InclinationSpecifier describes orbital elements extra to its geometry.

Constructors

Inclined

The orbit does not lie exactly in the reference plane

Fields

• longitudeOfAscendingNode :: !(Angle a)

  The longitude of the ascending node, Ω.

  The angle between the reference direction and the point where the orbiting body crosses the reference plane in the positive z direction.

• inclination :: !(Angle a)

  The orbit's inclination, i.

  The angle between the reference plane and the orbital plane

NonInclined

The orbit lies in the reference plane

Instances

Show a => Show (InclinationSpecifier a)

Defined in Physics.Orbit

Methods

showsPrec :: Int -> InclinationSpecifier a -> ShowS

show :: InclinationSpecifier a -> String

showList :: [InclinationSpecifier a] -> ShowS

Eq a => Eq (InclinationSpecifier a)

Defined in Physics.Orbit

Methods

(==) :: InclinationSpecifier a -> InclinationSpecifier a -> Bool

(/=) :: InclinationSpecifier a -> InclinationSpecifier a -> Bool

data PeriapsisSpecifier a

Along with InclinationSpecifier the PeriapsisSpecifier describes orbital elements extra to its geometry.

Constructors

Eccentric

The orbit is not circular

Fields

• argumentOfPeriapsis :: !(Angle a)

  The argument of periapsis, ω.

  The argumentOfPeriapsis is the angle of the periapsis relative to the reference direction in the orbital plane.

Circular

The orbit has an eccentricity of 0 so the argumentOfPeriapsis is indeterminate.

Instances

Show a => Show (PeriapsisSpecifier a)

Defined in Physics.Orbit

Methods

showsPrec :: Int -> PeriapsisSpecifier a -> ShowS

show :: PeriapsisSpecifier a -> String

showList :: [PeriapsisSpecifier a] -> ShowS

Eq a => Eq (PeriapsisSpecifier a)

Defined in Physics.Orbit

Methods

(==) :: PeriapsisSpecifier a -> PeriapsisSpecifier a -> Bool

(/=) :: PeriapsisSpecifier a -> PeriapsisSpecifier a -> Bool

data Classification

What form the orbit's geometry takes. This is dependant only on the eccentricity, e >= 0, of the orbit.

Constructors

Elliptic

0 <= e < 1

This includes circular orbits.

Parabolic

e == 1

Hyperbolic

e > 1

Instances

Read Classification

Defined in Physics.Orbit

Methods

readsPrec :: Int -> ReadS Classification

readList :: ReadS [Classification]

readPrec :: ReadPrec Classification

readListPrec :: ReadPrec [Classification]

Show Classification

Defined in Physics.Orbit

Methods

showsPrec :: Int -> Classification -> ShowS

show :: Classification -> String

showList :: [Classification] -> ShowS

Eq Classification

Defined in Physics.Orbit

Methods

(==) :: Classification -> Classification -> Bool

(/=) :: Classification -> Classification -> Bool

Functions for dealing with orbits

Utilities

isValid :: (Ord a, Num a) => Orbit a -> Bool

Determines if the orbital elements are valid (e >= 0 etc...). The behavior of all the other functions in this module is undefined when given an invalid orbit.

classify :: (Num a, Ord a) => Orbit a -> Classification

What shape is the orbit

normalizeOrbit :: (Floating a, Real a) => Orbit a -> Orbit a

Return an equivalent orbit such that

• i ∈ [0..π)
• Ω ∈ [0..2π)
• ω ∈ [0..2π)
• inclinationSpecifier == NonInclined if i = 0
• periapsisSpecifier == Circular if e == 0 and ω == 0

Orbital elements

apoapsis :: (Fractional a, Ord a) => Orbit a -> Maybe (Distance a)

Calculate the distance between the bodies when they are at their most distant. apoapsis returns Nothing when given a parabolic or hyperbolic orbit.

meanMotion :: (Floating a, Ord a) => Orbit a -> Quantity ((:/) Radian Second) a

Calculate the mean motion, n, of an orbit

This is the rate of change of the mean anomaly with respect to time.

period :: (Floating a, Ord a) => Orbit a -> Maybe (Time a)

Calculate the orbital period, p, of an elliptic orbit.

period returns Nothing if given a parabolic or hyperbolic orbit.

arealVelocity :: (Ord a, Floating a) => Orbit a -> Quantity ((:/) ((:^) Meter (Succ (Succ 'Zero))) Second) a

Calculate the areal velocity, A, of the orbit.

The areal velocity is the area swept out by the line between the orbiting body and the primary per second.

Geometry

semiMajorAxis :: (Fractional a, Ord a) => Orbit a -> Maybe (Distance a)

Calculate the semi-major axis, a, of the Orbit. Returns Nothing when given a parabolic orbit for which there is no semi-major axis. Note that the semi-major axis of a hyperbolic orbit is negative.

semiMinorAxis :: (Floating a, Ord a) => Orbit a -> Distance a

Calculate the semi-minor axis, b, of the Orbit. Like semiMajorAxis 'semiMinorAxis' o is negative when o is a hyperbolic orbit. In the case of a parabolic orbit semiMinorAxis returns 0m.

semiLatusRectum :: Num a => Orbit a -> Distance a

Calculate the semiLatusRectum, l, of the Orbit

hyperbolicApproachAngle :: (Floating a, Ord a) => Orbit a -> Maybe (Angle a)

Calculate the angle at which a body leaves the system when on a hyperbolic trajectory relative to the argument of periapsis. This is the limit of the true anomaly as time tends towards -infinity minus the argument of periapsis. The approach angle is in the closed range (-π..π/2).

This is the negation of the departure angle.

hyperbolicApproachAngle returns Nothing when given a non-hyperbolic orbit and -π when given a parabolic orbit.

hyperbolicDepartureAngle :: (Floating a, Ord a) => Orbit a -> Maybe (Angle a)

Calculate the angle at which a body leaves the system when on an escape trajectory relative to the argument of periapsis. This is the limit of the true anomaly as time tends towards infinity minus the argument of periapsis. The departure angle is in the closed range (π/2..π).

This is the negation of the approach angle.

hyperbolicDepartureAngle returns Nothing when given an elliptic orbit and π when given a parabolic orbit.

Conversions

To time since periapse

timeAtMeanAnomaly :: (Floating a, Ord a) => Orbit a -> Angle a -> Time a

Calculate the time since periapse, t, when the body has the given mean anomaly, M. M may be negative, indicating that the orbiting body has yet to reach periapse.

The sign of the time at mean anomaly M is the same as the sign of M.

The returned time is unbounded.

timeAtEccentricAnomaly :: (Floating a, Ord a) => Orbit a -> Angle a -> Maybe (Time a)

Calculate the time since periapse, t, of an elliptic orbit when at eccentric anomaly E.

timeAtEccentricAnomaly returns Nothing if given a parabolic or hyperbolic orbit.

timeAtHyperbolicAnomaly :: (Floating a, Ord a) => Orbit a -> AngleH a -> Maybe (Time a)

Calculate the time since periapse, t, of a hyperbolic orbit when at hyperbolic anomaly H.

Returns Nothing if given an elliptic or parabolic orbit.

timeAtTrueAnomaly :: (Real a, Floating a) => Orbit a -> Angle a -> Maybe (Time a)

Calculate the time since periapse given the true anomaly, ν, of an orbiting body.

Returns Nothing if the body never passed through the specified true anomaly.

To mean anomaly

meanAnomalyAtTime :: (Floating a, Ord a) => Orbit a -> Time a -> Angle a

Calculate the mean anomaly, M, at the given time since periapse, t. t may be negative, indicating that the orbiting body has yet to reach periapse.

The sign of the mean anomaly at time t is the same as the sign of t.

The returned mean anomaly is unbounded.

meanAnomalyAtEccentricAnomaly :: (Floating a, Ord a) => Orbit a -> Angle a -> Maybe (Angle a)

Calculate the mean anomaly, M, of an elliptic orbit when at eccentric anomaly E

meanAnomalyAtEccentricAnomaly returns Nothing if given a parabolic or hyperbolic orbit.

The number of orbits represented by the anomalies is preserved; i.e. M div 2π = E div 2π

meanAnomalyAtHyperbolicAnomaly :: (Floating a, Ord a) => Orbit a -> AngleH a -> Maybe (Angle a)

Calculate the mean anomaly, M, of a hyperbolic orbit when at hyperbolic anomaly H

meanAnomalyAtTrueAnomaly :: (Real a, Floating a) => Orbit a -> Angle a -> Maybe (Angle a)

Calculate the mean anomaly, M, of an orbiting body when at the given true anomaly, ν.

The number of orbits represented by the anomalies is preserved; i.e. M div 2π = ν div 2π

Returns Nothing for parabolic orbits.

Returns Nothing when the trajectory is not defined for the given true anomaly.

To eccentric anomaly

eccentricAnomalyAtTime :: (Converge [a], Floating a, Real a) => Orbit a -> Time a -> Maybe (Angle a)

Calculate the eccentric anomaly, E, of an elliptic orbit at time t.

eccentricAnomalyAtTime returns Nothing when given a parabolic or hyperbolic orbit.

The number of orbits represented by the time is preserved; i.e. t div p = E div 2π

eccentricAnomalyAtMeanAnomaly :: forall a. (Converge [a], Floating a, Real a) => Orbit a -> Angle a -> Maybe (Angle a)

Calculate the eccentric anomaly, E, of an elliptic orbit when at mean anomaly M. This function is considerably slower than most other conversion functions as it uses an iterative method as no closed form solution exists.

The number of orbits represented by the anomalies is preserved; i.e. M div 2π = E div 2π

eccentricAnomalyAtMeanAnomaly returns Nothing when given a parabolic or hyperbolic orbit.

eccentricAnomalyAtMeanAnomalyFloat :: Orbit Float -> Angle Float -> Maybe (Angle Float)

eccentricAnomalyAtMeanAnomaly specialized to Float.

This function is used to calculate the initial guess for eccentricAnomalyAtMeanAnomaly.

eccentricAnomalyAtTrueAnomaly :: (Floating a, Real a) => Orbit a -> Angle a -> Maybe (Angle a)

Calculate the eccentric anomaly, E, of an orbiting body when it has true anomaly, ν.

The number of orbits represented by the anomalies is preserved; i.e. ν div 2π = E div 2π

Returns Nothing if given a parabolic or hyperbolic orbit.

To hyperbolic anomaly

hyperbolicAnomalyAtTime :: forall a. (Converge [a], RealFloat a) => Orbit a -> Time a -> Maybe (AngleH a)

hyperbolicAnomalyAtMeanAnomaly :: forall a. (Converge [a], RealFloat a) => Orbit a -> Angle a -> Maybe (AngleH a)

hyperbolicAnomalyAtMeanAnomalyDouble :: Orbit Double -> Angle Double -> Maybe (AngleH Double)

Calculate the hyperbolic anomaly, H, at a given mean anomaly. Unline eccentricAnomalyAtMeanAnomalyFloat this uses double precision floats to help avoid overflowing.

hyperbolicAnomalyAtTrueAnomaly :: (Floating a, Ord a) => Orbit a -> Angle a -> Maybe (AngleH a)

Returns the hyperbolic anomaly, H, for an orbit at true anomaly ν.

Returns Nothing when given an Elliptic or Parabolic orbit, or a true anomaly out of the range of the hyperbolic orbit.

To true anomaly

trueAnomalyAtTime :: forall a. (Converge [a], RealFloat a) => Orbit a -> Time a -> Angle a

Calculate the true anomaly, ν, of a body at time since periapse, t.

trueAnomalyAtMeanAnomaly :: (Converge [a], RealFloat a) => Orbit a -> Angle a -> Angle a

Calculate the true anomaly, ν, of an orbiting body when it has the given mean anomaly, _M.

trueAnomalyAtEccentricAnomaly

Arguments

:: RealFloat a

=> Orbit a

An elliptic orbit

-> Angle a

The eccentric anomaly _E

-> Maybe (Angle a)

The true anomaly, ν

Calculate the true anomaly, ν, of an orbiting body when it has the given eccentric anomaly, _E.

The number of orbits represented by the anomalies is preserved; i.e. ν div 2π = E div 2π

trueAnomalyAtHyperbolicAnomaly :: (Ord a, Floating a) => Orbit a -> AngleH a -> Maybe (Angle a)

Properties of orbits

specificAngularMomentum :: Floating a => Orbit a -> Quantity ((:*) ((:^) Meter (Succ (Succ 'Zero))) ((:^) Second (Pred 'Zero))) a

Specific angular momentum, h, is the angular momentum per unit mass

specificOrbitalEnergy :: (Ord a, Floating a) => Orbit a -> Quantity ((:/) Joule ((:@) Kilo Gram)) a

Specific orbital energy, ε, is the orbital energy per unit mass

specificPotentialEnergyAtTrueAnomaly :: (Ord a, Floating a) => Orbit a -> Angle a -> Quantity ((:/) Joule ((:@) Kilo Gram)) a

Specific potential energy, εp, is the potential energy per unit mass at a particular true anomaly

specificKineticEnergyAtTrueAnomaly :: (Ord a, Floating a) => Orbit a -> Angle a -> Quantity ((:/) Joule ((:@) Kilo Gram)) a

Specific kinetic energy, εk, is the kinetic energy per unit mass at a particular true anomaly

speedAtTrueAnomaly :: (Ord a, Floating a) => Orbit a -> Angle a -> Speed a

What is the speed, v, of a body at a particular true anomaly

radiusAtTrueAnomaly :: (Ord a, Floating a) => Orbit a -> Angle a -> Distance a

The distance, r, from the primary body to the orbiting body at a particular true anomaly.

Other utilities

escapeVelocityAtDistance :: Floating a => Quantity ((:*) ((:^) Meter (Succ (Succ (Succ 'Zero)))) ((:^) Second (Pred (Pred 'Zero)))) a -> Distance a -> Speed a

The escape velocity for a primary with specified gravitational parameter at a particular distance.

Unit synonyms

type Quantity u = MkQu_ULN u 'DefaultLCSU

type Time = Quantity Second

A measure in seconds.

type Distance = Quantity Meter

A measure in meters.

type Speed = Quantity ((:*) Meter ((:^) Second (Pred 'Zero)))

A measure in meters per second.

type Mass = Quantity ((:@) Kilo Gram)

A measure in kilograms.

type Angle = Quantity Radian

A measure in radians.

type AngleH = Quantity RadianHyperbolic

A measure in radians (hyperbolic)

data RadianHyperbolic

Constructors

RadianHyperbolic

Instances

Show RadianHyperbolic

Defined in Physics.Orbit.Metrology

Methods

showsPrec :: Int -> RadianHyperbolic -> ShowS

show :: RadianHyperbolic -> String

showList :: [RadianHyperbolic] -> ShowS

Unit RadianHyperbolic

Defined in Physics.Orbit.Metrology

Associated Types

type BaseUnit RadianHyperbolic

type DimOfUnit RadianHyperbolic

type UnitFactorsOf RadianHyperbolic :: [Factor Type]

Methods

conversionRatio :: RadianHyperbolic -> Rational

canonicalConvRatio :: RadianHyperbolic -> Rational

type BaseUnit RadianHyperbolic

Defined in Physics.Orbit.Metrology

type BaseUnit RadianHyperbolic = Canonical

type DimOfUnit RadianHyperbolic

Defined in Physics.Orbit.Metrology

type DimOfUnit RadianHyperbolic = PlaneAngleHyperbolic

type UnitFactorsOf RadianHyperbolic

Defined in Physics.Orbit.Metrology

type UnitFactorsOf RadianHyperbolic = If (IsCanonical RadianHyperbolic) '['F RadianHyperbolic One] (UnitFactorsOf (BaseUnit RadianHyperbolic))

data PlaneAngleHyperbolic

Constructors

PlaneAngleHyperbolic

Instances

Dimension PlaneAngleHyperbolic

Defined in Physics.Orbit.Metrology

Associated Types

type DimFactorsOf PlaneAngleHyperbolic :: [Factor Type]

type DimFactorsOf PlaneAngleHyperbolic

Defined in Physics.Orbit.Metrology

type DimFactorsOf PlaneAngleHyperbolic = '['F PlaneAngleHyperbolic One]

type DefaultUnitOfDim PlaneAngleHyperbolic

Defined in Physics.Orbit.Metrology

type DefaultUnitOfDim PlaneAngleHyperbolic = RadianHyperbolic

type Unitless = Quantity Number

A unitless measure.

Reexported from CReal

class Converge a

If a type is an instance of Converge then it represents a stream of values which are increasingly accurate approximations of a desired value

Minimal complete definition

converge, convergeErr

Instances

Converge [CReal n]

The overlapping instance for CReal n has a slightly different behavior. The instance for Eq will cause converge to return a value when the list converges to within 2^-n (due to the Eq instance for CReal n) despite the precision the value is requested at by the surrounding computation. This instance will return a value approximated to the correct precision.

It's important to note when the error function reaches zero this function behaves like converge as it's not possible to determine the precision at which the error function should be evaluated at.

Find where log x = π using Newton's method

>>> let initialGuess = 1
>>> let improve x = x - x * (log x - pi)
>>> let Just y = converge (iterate improve initialGuess)
>>> showAtPrecision 10 y
"23.1406"
>>> showAtPrecision 50 y
"23.1406926327792686"

Defined in Data.CReal.Converge

Associated Types

type Element [CReal n]

Methods

converge :: [CReal n] -> Maybe (Element [CReal n])

convergeErr :: (Element [CReal n] -> Element [CReal n]) -> [CReal n] -> Maybe (Element [CReal n])

Eq a => Converge [a]

Every list of equatable values is an instance of Converge. converge returns the first element which is equal to the succeeding element in the list. If the list ends before the sequence converges the last value is returned.

Defined in Data.CReal.Converge

Associated Types

type Element [a]

Methods

converge :: [a] -> Maybe (Element [a])

convergeErr :: (Element [a] -> Element [a]) -> [a] -> Maybe (Element [a])