-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Types and functions for Kepler orbits.
--   
--   Types and functions for Kepler orbits.
@package orbits
@version 0.3

module Data.Constants.Mechanics.Extra

-- | One complete revolution in radians
turn :: Floating a => PlaneAngle a

-- | π radians
halfTurn :: Floating a => PlaneAngle a

-- | Multiply by 1 radian
addRad :: Qu b  'DefaultLCSU a -> Qu (Normalize ('[ 'F PlaneAngle One] @+ b))  'DefaultLCSU a

-- | Divide by 1 radian
delRad :: Qu u  'DefaultLCSU a -> Qu (Normalize (u @- '[ 'F PlaneAngle One]))  'DefaultLCSU a


-- | Types and functions for dealing with Kepler orbits.
module Physics.Orbit

-- | Data type defining an orbit parameterized by the type used to
--   represent values
data Orbit a
Orbit :: !Unitless a -> !Distance a -> !InclinationSpecifier a -> !PeriapsisSpecifier a -> !Quantity (:*) ((:^) Meter (Succ (Succ (Succ  'Zero)))) ((:^) Second (Pred (Pred  'Zero))) a -> Orbit a

-- | The orbit's eccentricity, e.
--   
--   <a>eccentricity</a> 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.
[eccentricity] :: Orbit a -> !Unitless a

-- | The orbit's periapsis, q.
--   
--   <a>periapsis</a> must be positive.
--   
--   The periapsis is the distance between the bodies at their closest
--   approach.
[periapsis] :: Orbit a -> !Distance a

-- | The <a>inclinationSpecifier</a> describes the angle between the
--   obtital plane and the reference plane.
[inclinationSpecifier] :: Orbit a -> !InclinationSpecifier a

-- | <a>periapsisSpecifier</a> is <a>Circular</a> iff <a>eccentricity</a>
--   is 0
--   
--   The periapsis specifier describes any rotation of the orbit relative
--   to the reference direction in the orbital plane.
[periapsisSpecifier] :: Orbit a -> !PeriapsisSpecifier a

-- | The gravitational parameter of the system's primary, μ.
--   
--   μ is equal to the mass of the primary times
--   &lt;<a>https://en.wikipedia.org/wiki/Gravitational_constant</a> G&gt;.
--   
--   <a>primaryGravitationalParameter</a> must be positive.
[primaryGravitationalParameter] :: Orbit a -> !Quantity (:*) ((:^) Meter (Succ (Succ (Succ  'Zero)))) ((:^) Second (Pred (Pred  'Zero))) a

-- | Along with <a>PeriapsisSpecifier</a> the <a>InclinationSpecifier</a>
--   describes orbital elements extra to its geometry.
data InclinationSpecifier a

-- | The orbit does not lie exactly in the reference plane
Inclined :: !Angle a -> !Angle a -> InclinationSpecifier 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.
[longitudeOfAscendingNode] :: InclinationSpecifier a -> !Angle a

-- | The orbit's inclination, i.
--   
--   The angle between the reference plane and the orbital plane
[inclination] :: InclinationSpecifier a -> !Angle a

-- | The orbit lies in the reference plane
NonInclined :: InclinationSpecifier a

-- | Along with <a>InclinationSpecifier</a> the <a>PeriapsisSpecifier</a>
--   describes orbital elements extra to its geometry.
data PeriapsisSpecifier a

-- | The orbit is not circular
Eccentric :: !Angle a -> PeriapsisSpecifier a

-- | The argument of periapsis, ω.
--   
--   The <a>argumentOfPeriapsis</a> is the angle of the periapsis relative
--   to the reference direction in the orbital plane.
[argumentOfPeriapsis] :: PeriapsisSpecifier a -> !Angle a

-- | The orbit has an eccentricity of 0 so the <a>argumentOfPeriapsis</a>
--   is indeterminate.
Circular :: PeriapsisSpecifier a

-- | What for the orbit's geometry takes. This is dependant only on the
--   <a>eccentricity</a>, e &gt;= 0, of the orbit.
data Classification

-- | 0 &lt;= e &lt; 1
--   
--   This includes circular orbits.
Elliptic :: Classification

-- | e == 1
Parabolic :: Classification

-- | e &gt; 1
Hyperbolic :: Classification

-- | Return true is the orbit is valid and false if it is invalid. The
--   behavior of all the other functions in this module is undefined when
--   given an invalid orbit.
isValid :: (Ord a, Num a) => Orbit a -> Bool

-- | <a>classify</a> is a funciton which returns the orbit's class.
classify :: (Num a, Ord a) => Orbit a -> Classification

-- | Calculate the distance between the bodies when they are at their most
--   distant. <a>apoapsis</a> returns <a>Nothing</a> when given a parabolic
--   or hyperbolic orbit.
apoapsis :: (Fractional a, Ord a) => Orbit a -> Maybe (Distance a)

-- | Calculate the mean motion, n, of an orbit
--   
--   This is the rate of change of the mean anomaly with respect to time.
meanMotion :: (Floating a, Ord a) => Orbit a -> Quantity (:/) Radian Second a

-- | Calculate the orbital period, p, of an elliptic orbit.
--   
--   <a>period</a> returns Nothing if given a parabolic or hyperbolic
--   orbit.
period :: (Floating a, Ord a) => Orbit a -> Maybe (Time a)

-- | Calculate the areal velocity, A, of the orbit.
--   
--   The areal velocity is the area <a>swept out</a> by the line between
--   the orbiting body and the primary per second.
arealVelocity :: (Ord a, Floating a) => Orbit a -> Quantity (:/) ((:^) Meter (Succ (Succ  'Zero))) Second a

-- | Calculate the semi-major axis, a, of the <a>Orbit</a>. Returns
--   <a>Nothing</a> 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.
semiMajorAxis :: (Fractional a, Ord a) => Orbit a -> Maybe (Distance a)

-- | Calculate the semi-minor axis, b, of the <a>Orbit</a>. Like
--   <a>semiMajorAxis</a> <tt>'semiMinorAxis' o</tt> is negative when
--   <tt>o</tt> is a hyperbolic orbit. In the case of a parabolic orbit
--   <a>semiMinorAxis</a> returns 0m.
semiMinorAxis :: (Floating a, Ord a) => Orbit a -> Distance a

-- | Calculate the semiLatusRectum, l, of the <a>Orbit</a>
semiLatusRectum :: Num a => Orbit a -> Distance 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.
--   
--   <a>hyperbolicApproachAngle</a> returns Nothing when given a
--   non-hyperbolic orbit and -π when given a parabolic orbit.
hyperbolicApproachAngle :: (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.
--   
--   <a>hyperbolicDepartureAngle</a> returns Nothing when given an elliptic
--   orbit and π when given a parabolic orbit.
hyperbolicDepartureAngle :: (Floating a, Ord a) => Orbit a -> Maybe (Angle a)

-- | Calculate the time since periapse, t, when the body has the given
--   <a>mean anomaly</a>, 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.
timeAtMeanAnomaly :: (Floating a, Ord a) => Orbit a -> Angle a -> Time a

-- | Calculate the time since periapse, t, of an elliptic orbit when at
--   eccentric anomaly E.
--   
--   <a>timeAtEccentricAnomaly</a> returns Nothing if given a parabolic or
--   hyperbolic orbit.
timeAtEccentricAnomaly :: (Floating a, Ord a) => Orbit a -> Angle a -> Maybe (Time a)

-- | Calculate the time since periapse given the true anomaly, ν, of an
--   orbiting body.
timeAtTrueAnomaly :: (Real a, Floating a) => Orbit a -> Angle a -> Maybe (Time a)

-- | Calculate the <a>mean anomaly</a>, 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.
meanAnomalyAtTime :: (Floating a, Ord a) => Orbit a -> Time a -> Angle a

-- | Calculate the mean anomaly, M, of an elliptic orbit when at eccentric
--   anomaly E
--   
--   <a>meanAnomalyAtEccentricAnomaly</a> returns Nothing if given a
--   parabolic or hyperbolic orbit.
--   
--   The number of orbits represented by the anomalies is preserved; i.e. M
--   <a>div</a> 2π = E <a>div</a> 2π
meanAnomalyAtEccentricAnomaly :: (Floating a, Ord 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
--   <a>div</a> 2π = ν <a>div</a> 2π
--   
--   Currently only implemented for elliptic orbits.
meanAnomalyAtTrueAnomaly :: (Real a, Floating a) => Orbit a -> Angle a -> Maybe (Angle a)

-- | Calculate the eccentric anomaly, E, of an elliptic orbit at time t.
--   
--   <a>eccentricAnomalyAtTime</a> returns Nothing when given a parabolic
--   or hyperbolic orbit.
--   
--   The number of orbits represented by the time is preserved; i.e. t
--   <a>div</a> p = E <a>div</a> 2π
eccentricAnomalyAtTime :: (Converge [a], Floating a, Real a) => Orbit a -> Time 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
--   <a>div</a> 2π = E <a>div</a> 2π
--   
--   <a>eccentricAnomalyAtMeanAnomaly</a> returns Nothing when given a
--   parabolic or hyperbolic orbit.
eccentricAnomalyAtMeanAnomaly :: forall a. (Converge [a], Floating a, Real a) => Orbit a -> Angle a -> Maybe (Angle a)

-- | <a>eccentricAnomalyAtMeanAnomaly</a> specialized to <a>Float</a>.
--   
--   This function is used to calculate the initial guess for
--   <a>eccentricAnomalyAtMeanAnomaly</a>.
eccentricAnomalyAtMeanAnomalyFloat :: Orbit Float -> Angle Float -> Maybe (Angle Float)

-- | 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. ν
--   <a>div</a> 2π = E <a>div</a> 2π
--   
--   Returns Nothing if given a parabolic or hyperbolic orbit.
eccentricAnomalyAtTrueAnomaly :: (Floating a, Real a) => Orbit a -> Angle a -> Maybe (Angle a)

-- | Calculate the true anomaly, ν, of a body at time since periapse, t.
trueAnomalyAtTime :: (Converge [a], RealFloat a) => Orbit a -> Time a -> Maybe (Angle a)

-- | Calculate the true anomaly, ν, of an orbiting body when it has the
--   given mean anomaly, _M.
trueAnomalyAtMeanAnomaly :: (Converge [a], RealFloat a) => Orbit a -> Angle a -> Maybe (Angle a)

-- | 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. ν
--   <a>div</a> 2π = E <a>div</a> 2π
trueAnomalyAtEccentricAnomaly :: RealFloat a => Orbit a -> Angle a -> Maybe (Angle a)

-- | A measure in seconds.
type Time = Quantity (Second)

-- | A measure in meters.
type Distance = Quantity (Meter)

-- | A measure in meters per second.
type Speed = Quantity ((:*) Meter ((:^) Second (Pred  'Zero)))

-- | A measure in kilograms.
type Mass = Quantity ((:@) Kilo Gram)

-- | A measure in radians.
type Angle = Quantity (Radian)

-- | A unitless measure.
type Unitless = Quantity (Number)

-- | If a type is an instance of Converge then it represents a stream of
--   values which are increasingly accurate approximations of a desired
--   value
class Converge a
instance GHC.Classes.Eq Physics.Orbit.Classification
instance GHC.Read.Read Physics.Orbit.Classification
instance GHC.Show.Show Physics.Orbit.Classification
instance GHC.Classes.Eq a => GHC.Classes.Eq (Physics.Orbit.Orbit a)
instance GHC.Show.Show a => GHC.Show.Show (Physics.Orbit.Orbit a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Physics.Orbit.PeriapsisSpecifier a)
instance GHC.Show.Show a => GHC.Show.Show (Physics.Orbit.PeriapsisSpecifier a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Physics.Orbit.InclinationSpecifier a)
instance GHC.Show.Show a => GHC.Show.Show (Physics.Orbit.InclinationSpecifier a)