Copyright  (c) Justin Le 2016 

License  BSD3 
Maintainer  justin@jle.im 
Stability  unstable 
Portability  portable 
Safe Haskell  None 
Language  Haskell2010 
Simulate physical systems on generalized/arbitrary coordinates using Hamiltonian mechanics and automatic differentiation!
See the https://github.com/mstksg/hamilton#readme for more information on usage!
Synopsis
 data System :: Nat > Nat > Type
 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
 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
 underlyingPos :: System m n > R n > R m
 data Config :: Nat > Type where
 data Phase :: Nat > Type where
 toPhase :: (KnownNat m, KnownNat n) => System m n > Config n > Phase n
 fromPhase :: (KnownNat m, KnownNat n) => System m n > Phase n > Config n
 momenta :: (KnownNat m, KnownNat n) => System m n > Config n > R n
 velocities :: (KnownNat m, KnownNat n) => System m n > Phase n > R n
 keC :: (KnownNat m, KnownNat n) => System m n > Config n > Double
 keP :: (KnownNat m, KnownNat n) => System m n > Phase n > Double
 pe :: System m n > R n > Double
 lagrangian :: (KnownNat m, KnownNat n) => System m n > Config n > Double
 hamiltonian :: (KnownNat m, KnownNat n) => System m n > Phase n > Double
 hamEqs :: (KnownNat m, KnownNat n) => System m n > Phase n > (R n, R n)
 stepHam :: forall m n. (KnownNat m, KnownNat n) => Double > System m n > Phase n > Phase n
 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)
 evolveHam' :: forall m n. (KnownNat m, KnownNat n) => System m n > Phase n > [Double] > [Phase n]
 stepHamC :: forall m n. (KnownNat m, KnownNat n) => Double > System m n > Config n > Config n
 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)
 evolveHamC' :: forall m n. (KnownNat m, KnownNat n) => System m n > Config n > [Double] > [Config n]
Systems and states
Systems
data System :: Nat > Nat > Type Source #
Represents a physical system in which physics happens. A
is a system whose state described using System
m nn
generalized coordinates
(an "n
dimensional" system), where the underlying cartesian coordinate
space is m
dimensional.
For the most part, you are supposed to be able to ignore m
. m
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 m
at the moment is underlyingPos
)
A
's state is described using a System
m n
(which
describes the system in configuration space) or a Config
n
(which
describes the system in phase space).Phase
n
:: (KnownNat m, KnownNat n)  
=> R m  The "inertia" of each of the 
> (forall a. RealFloat a => Vector n a > Vector m a)  Conversion function to convert points in the generalized coordinate space to the underlying cartesian space of the system. 
> (forall a. RealFloat a => Vector n a > a)  The potential energy of the system as a function of the generalized coordinate space's positions. 
> System m n 
Create a system with n
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.
:: (KnownNat m, KnownNat n)  
=> R m  The "inertia" of each of the 
> (forall a. RealFloat a => Vector n a > Vector m a)  Conversion function to convert points in the generalized coordinate space to the underlying cartesian space of the system. 
> (forall a. RealFloat a => Vector m a > a)  The potential energy of the system as a function of the underlying cartesian coordinate space's positions. 
> System m n 
Convenience wrapper over mkSystem
that allows you to specify the
potential energy function in terms of the underlying cartesian
coordinate space.
underlyingPos :: System m n > R n > R m Source #
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.
States
data Config :: Nat > Type where Source #
Represents the full state of a system of n
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
into a Config
n
(convert from
configuration space to phase space) for a given system with Phase
ntoPhase
.
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.
Cfg :: {..} > Config n  

Instances
KnownNat n => Show (Config n) Source #  
Generic (Config a) Source #  
type Rep (Config a) Source #  
Defined in Numeric.Hamilton type Rep (Config a) = D1 (MetaData "Config" "Numeric.Hamilton" "hamilton0.1.0.49DV1GXmEJ3k5kGjYcqsMSn" False) (C1 (MetaCons "Cfg" PrefixI True) (S1 (MetaSel (Just "cfgPositions") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 (R a)) :*: S1 (MetaSel (Just "cfgVelocities") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 (R a)))) 
data Phase :: Nat > Type where Source #
Represents the full state of a system of n
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 state 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 Config
, and then convert it to a Phase
with toPhase
.
Phs :: {..} > Phase n  

Instances
KnownNat n => Show (Phase n) Source #  
Generic (Phase a) Source #  
type Rep (Phase a) Source #  
Defined in Numeric.Hamilton type Rep (Phase a) = D1 (MetaData "Phase" "Numeric.Hamilton" "hamilton0.1.0.49DV1GXmEJ3k5kGjYcqsMSn" False) (C1 (MetaCons "Phs" PrefixI True) (S1 (MetaSel (Just "phsPositions") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 (R a)) :*: S1 (MetaSel (Just "phsMomenta") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 (R a)))) 
toPhase :: (KnownNat m, KnownNat n) => System m n > Config n > Phase n Source #
Convert a configurationspace representaiton of the state of the system to a phasespace representation.
Useful because the hamiltonian simulations use Phase
as its working
state, but Config
is a much more humanunderstandable and intuitive
representation. This allows you to state your starting state in
configuration space and convert to phase space for your simulation to
use.
fromPhase :: (KnownNat m, KnownNat n) => System m n > Phase n > Config n Source #
Invert toPhase
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 humanreadable/humanunderstandable way.
State functions
momenta :: (KnownNat m, KnownNat n) => System m n > Config n > R n Source #
Compute the generalized momenta conjugate to each generalized coordinate of a system by giving the configurationspace state of the system.
Note that getting the momenta from a
involves just using
Phase
nphsMomenta
.
velocities :: (KnownNat m, KnownNat n) => System m n > Phase n > R n Source #
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
involves just using
Config
ncfgVelocities
.
keC :: (KnownNat m, KnownNat n) => System m n > Config n > Double Source #
The kinetic energy of a system, given the system's state in configuration space.
keP :: (KnownNat m, KnownNat n) => System m n > Phase n > Double Source #
The kinetic energy of a system, given the system's state in phase space.
pe :: System m n > R n > Double Source #
The potential energy of a system, given the position in the generalized coordinates of the system.
lagrangian :: (KnownNat m, KnownNat n) => System m n > Config n > Double Source #
The Lagrangian of a system (the difference between the kinetic energy and the potential energy), given the system's state in configuration space.
hamiltonian :: (KnownNat m, KnownNat n) => System m n > Phase n > Double Source #
The Hamiltonian of a system (the sum of kinetic energy and the potential energy), given the system's state in phase space.
hamEqs :: (KnownNat m, KnownNat n) => System m n > Phase n > (R n, R n) Source #
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.
Computed using the maths derived in https://blog.jle.im/entry/hamiltoniandynamicsinhaskell.html.
Simulating hamiltonian dynamics
Over phase space
:: (KnownNat m, KnownNat n)  
=> Double  timestep to step through 
> System m n  system to simulate 
> Phase n  initial state, in phase space 
> Phase n 
Step a system through phase space over over a single timestep.
:: (KnownNat m, KnownNat n, KnownNat s, 2 <= s)  
=> System m n  system to simulate 
> Phase n  initial state, in phase space 
> Vector s Double  desired solution times 
> Vector s (Phase n) 
Evolve a system using a hamiltonian stepper, with the given initial phase space state.
:: (KnownNat m, KnownNat n)  
=> System m n  system to simulate 
> Phase n  initial state, in phase space 
> [Double]  desired solution times 
> [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 Vector
.
The output list should be the same length as the input list.
Over configuration space
Convenience wrappers over the normal phasespace steppers/simulators that allow you to provide input and expect output in configuration space instead of in phase space. Note that the simulation itself still runs in phase space, so these all require conversions to and from phase space under the hood.
:: (KnownNat m, KnownNat n)  
=> Double  timestep to step through 
> System m n  system to simulate 
> Config n  initial state, in phase space 
> Config 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.
:: (KnownNat m, KnownNat n, KnownNat s, 2 <= s)  
=> System m n  system to simulate 
> Config n  initial state, in configuration space 
> Vector s Double  desired solution times 
> Vector s (Config n) 
A convenience wrapper for evolveHam
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.
:: (KnownNat m, KnownNat n)  
=> System m n  system to simulate 
> Config n  initial state, in configuration space 
> [Double]  desired solution times 
> [Config n] 
A convenience wrapper for evolveHam'
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.