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


-- | Physics on generalized coordinate systems using Hamiltonian Mechanics and AD
--   
--   See README.md (or read online at
--   <a>https://github.com/mstksg/hamilton#readme</a>)
@package hamilton
@version 0.1.0.3


-- | Simulate physical systems on generalized/arbitrary coordinates using
--   Hamiltonian mechanics and automatic differentiation!
--   
--   See the <a>https://github.com/mstksg/hamilton#readme</a> for more
--   information on usage!
module Numeric.Hamilton

-- | Represents a physical system in which physics happens. A
--   <tt><a>System</a> m n</tt> is a system whose state described using
--   <tt>n</tt> generalized coordinates (an "<tt>n</tt>-dimensional"
--   system), where the underlying cartesian coordinate space is
--   <tt>m</tt>-dimensional.
--   
--   For the most part, you are supposed to be able to ignore <tt>m</tt>.
--   <tt>m</tt> is only provided because it's useful when plotting/drawing
--   the system with a given state back in rectangular coordinates. (The
--   only function that use the <tt>m</tt> at the moment is
--   <a>underlyingPos</a>)
--   
--   A <tt><a>System</a> m n</tt>'s state is described using a
--   <tt><a>Config</a> n</tt> (which describes the system in configuration
--   space) or a <tt><a>Phase</a> n</tt> (which describes the system in
--   phase space).
data System :: Nat -> Nat -> Type

-- | Create a system with <tt>n</tt> generalized coordinates by describing
--   its coordinate space (by a function from the generalized coordinates
--   to the underlying cartesian coordinates), the inertia of each of those
--   underlying coordinates, and the pontential energy function.
--   
--   The potential energy function is expressed in terms of the genearlized
--   coordinate space's positions.
mkSystem :: forall m n. (KnownNat m, KnownNat n) => R m -> (forall a. RealFloat a => Vector n a -> Vector m a) -> (forall a. RealFloat a => Vector n a -> a) -> System m n

-- | Convenience wrapper over <a>mkSystem</a> that allows you to specify
--   the potential energy function in terms of the underlying cartesian
--   coordinate space.
mkSystem' :: forall m n. (KnownNat m, KnownNat n) => R m -> (forall a. RealFloat a => Vector n a -> Vector m a) -> (forall a. RealFloat a => Vector m a -> a) -> System m n

-- | Converts the position of generalized coordinates of a system to the
--   coordinates of the system's underlying cartesian coordinate system.
--   Useful for plotting/drawing the system in cartesian space.
underlyingPos :: System m n -> R n -> R m

-- | Represents the full state of a system of <tt>n</tt> generalized
--   coordinates in configuration space (informally, "positions and
--   velocities")
--   
--   A configuration space representaiton is more directly "physically
--   meaningful" and intuitive/understandable to humans than a phase space
--   representation. However, it's much less mathematically ideal to work
--   with because of the lack of some neat underlying symmetries.
--   
--   You can convert a <tt><a>Config</a> n</tt> into a <tt><a>Phase</a>
--   n</tt> (convert from configuration space to phase space) for a given
--   system with <a>toPhase</a>. This allows you to state your system in
--   configuration space and then convert it to phase space before handing
--   it off to the hamiltonian machinery.
data Config :: Nat -> Type
[Cfg] :: {cfgPositions :: !R n " The current values ("positions") of each of the @n@ generalized coordinates", cfgVelocities :: !R n " The current rate of changes ("velocities") of each of the @n@ generalized coordinates"} -> Config n

-- | Represents the full state of a system of <tt>n</tt> generalized
--   coordinates in phase space (informally, "positions and momentums").
--   
--   Phase space representations are much nicer to work with mathematically
--   because of some neat underlying symmetries. For one, positions and
--   momentums are "interchangeable" in a system; if you swap every
--   coordinate's positions with their momentums, and also swap them in the
--   equations of motions, you get the same system back. This isn't the
--   case with configuration space representations.
--   
--   A hamiltonian simulation basically describes the trajectory of each
--   coordinate through phase space, so this is the <i>state</i> of the
--   simulation. However, configuration space representations are much more
--   understandable to humans, so it might be useful to give an initial
--   state in configuration space using <a>Config</a>, and then convert it
--   to a <a>Phase</a> with <a>toPhase</a>.
data Phase :: Nat -> Type
[Phs] :: {phsPositions :: !R n " The current values ("positions") of each of the @n@ generalized coordinates.", phsMomenta :: !R n " The current conjugate momenta ("momentums") to each of the @n@ generalized coordinates"} -> Phase n

-- | Convert a configuration-space representaiton of the state of the
--   system to a phase-space representation.
--   
--   Useful because the hamiltonian simulations use <a>Phase</a> as its
--   working state, but <a>Config</a> is a much more human-understandable
--   and intuitive representation. This allows you to state your starting
--   state in configuration space and convert to phase space for your
--   simulation to use.
toPhase :: (KnownNat m, KnownNat n) => System m n -> Config n -> Phase n

-- | Invert <a>toPhase</a> and convert a description of a system's state in
--   phase space to a description of the system's state in configuration
--   space.
--   
--   Possibly useful for showing the phase space representation of a
--   system's state in a more human-readable/human-understandable way.
fromPhase :: (KnownNat m, KnownNat n) => System m n -> Phase n -> Config n

-- | Compute the generalized momenta conjugate to each generalized
--   coordinate of a system by giving the configuration-space state of the
--   system.
--   
--   Note that getting the momenta from a <tt><a>Phase</a> n</tt> involves
--   just using <a>phsMomenta</a>.
momenta :: (KnownNat m, KnownNat n) => System m n -> Config n -> R n

-- | Compute the rate of change of each generalized coordinate by giving
--   the state of the system in phase space.
--   
--   Note that getting the velocities from a <tt><a>Config</a> n</tt>
--   involves just using <a>cfgVelocities</a>.
velocities :: (KnownNat m, KnownNat n) => System m n -> Phase n -> R n

-- | The kinetic energy of a system, given the system's state in
--   configuration space.
keC :: (KnownNat m, KnownNat n) => System m n -> Config n -> Double

-- | The kinetic energy of a system, given the system's state in phase
--   space.
keP :: (KnownNat m, KnownNat n) => System m n -> Phase n -> Double

-- | The potential energy of a system, given the position in the
--   generalized coordinates of the system.
pe :: System m n -> R n -> Double

-- | The Lagrangian of a system (the difference between the kinetic energy
--   and the potential energy), given the system's state in configuration
--   space.
lagrangian :: (KnownNat m, KnownNat n) => System m n -> Config n -> Double

-- | The Hamiltonian of a system (the sum of kinetic energy and the
--   potential energy), given the system's state in phase space.
hamiltonian :: (KnownNat m, KnownNat n) => System m n -> Phase n -> Double

-- | The "hamiltonian equations" for a given system at a given state in
--   phase space. Returns the rate of change of the positions and conjugate
--   momenta, which can be used to progress the simulation through time.
hamEqs :: (KnownNat m, KnownNat n) => System m n -> Phase n -> (R n, R n)

-- | Step a system through phase space over over a single timestep.
stepHam :: forall m n. (KnownNat m, KnownNat n) => Double -> System m n -> Phase n -> Phase n

-- | Evolve a system using a hamiltonian stepper, with the given initial
--   phase space state.
evolveHam :: forall m n s. (KnownNat m, KnownNat n, KnownNat s, 2 <= s) => System m n -> Phase n -> Vector s Double -> Vector s (Phase n)

-- | Evolve a system using a hamiltonian stepper, with the given initial
--   phase space state.
--   
--   Desired solution times provided as a list instead of a sized
--   <a>Vector</a>. The output list should be the same length as the input
--   list.
evolveHam' :: forall m n. (KnownNat m, KnownNat n) => System m n -> Phase n -> [Double] -> [Phase n]

-- | Step a system through configuration space over over a single timestep.
--   
--   Note that the simulation itself still runs in phase space; this
--   function just abstracts over converting to and from phase space for
--   the input and output.
stepHamC :: forall m n. (KnownNat m, KnownNat n) => Double -> System m n -> Config n -> Config n

-- | A convenience wrapper for <a>evolveHam</a> that works on configuration
--   space states instead of phase space states.
--   
--   Note that the simulation itself still runs in phase space; this
--   function just abstracts over converting to and from phase space for
--   the inputs and outputs.
evolveHamC :: forall m n s. (KnownNat m, KnownNat n, KnownNat s, 2 <= s) => System m n -> Config n -> Vector s Double -> Vector s (Config n)

-- | A convenience wrapper for <a>evolveHam'</a> that works on
--   configuration space states instead of phase space states.
--   
--   Note that the simulation itself still runs in phase space; this
--   function just abstracts over converting to and from phase space for
--   the inputs and outputs.
evolveHamC' :: forall m n. (KnownNat m, KnownNat n) => System m n -> Config n -> [Double] -> [Config n]
instance GHC.Generics.Generic (Numeric.Hamilton.Phase a)
instance GHC.Generics.Generic (Numeric.Hamilton.Config a)
instance GHC.TypeNats.KnownNat n => GHC.Show.Show (Numeric.Hamilton.Config n)
instance GHC.TypeNats.KnownNat n => GHC.Show.Show (Numeric.Hamilton.Phase n)
