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


-- | An embedding of quantum computation as a Haskell arrow
--   
--   This module is a loose port of the Quantum::Entanglement Perl module,
--   which endows its host language with quantum-computationesque effects.
--   In this Haskell version this is done using an arrow to take advantage
--   of the arrow syntax for imperative-looking code. The module has all
--   the fun bells and whistles of quantum computation, including
--   entanglement and interference, even through conditionals (which the
--   Perl analog does not support). The arrow is defined over any instance
--   of MonadRandom, so if you want to get especially crazy, you can
--   experiment with what quantum computation is like when observables
--   include invoking continuations. See the included example.hs for some
--   simple examples of what using this module looks like.
@package quantum-arrow
@version 0.0.5

module QuantumArrow.Quantum

-- | The Quantum arrow represents a quantum computation with observation.
--   You can give a quantum computation a superposition of values, and it
--   will operate over them, returning you a superposition back. If ever
--   you observe (using the qLift or qLift_ functions), the system
--   collapses to an eigenstate of what you observed.
--   
--   <pre>
--   x &lt;- entangle -&lt; [(1, 1 :+ 0), (2, 1 :+ 0)]
--   -- x is in state |1&gt; + |2&gt;; i.e. 1 or 2 with equal probability
--   let y = x + 1
--   -- y is in state |2&gt; + |3&gt;
--   qLift print -&lt; y    -- will print either 2 or 3; let's say it printed 2
--   -- state collapses here, y in state |2&gt;
--   qLift print -&lt; x    -- prints 1 (assuming 2 was printed earlier)
--   </pre>
--   
--   So the variables become entangled with each other in order to maintain
--   consistency of the computation.
data Quantum m b c

-- | Representation of a probability amplitude
type Amp = Complex Double

-- | entangle takes as input a list of values and probability amplitudes
--   and gives as output a superposition of the inputs. For example:
--   
--   <pre>
--   x &lt;- entangle -&lt; [(1, 1 :+ 0), (2, 0 :+ 1)]
--   -- x is now |1&gt; + i|2&gt;
--   qLift print -&lt; x    -- prints 1 or 2 with equal probability
--   </pre>
entangle :: Monad m => Quantum m [(a, Amp)] a

-- | <tt>qLift f -&lt; x</tt> first collapses <tt>x</tt> to an eigenstate
--   (using observe) then executes <tt>f x</tt> in the underlying monad.
--   All conditionals up to this point are collapsed to an eigenstate (True
--   or False) so a <a>current branch</a> of the computation is selected.
qLift :: (Eq a, MonadRandom m) => (a -> m b) -> Quantum m a b

-- | qLift_ is just qIO which doesn't take an input. eg.
--   
--   <pre>
--   qLift_ $ print "hello world" -&lt; ()
--   </pre>
--   
--   All conditionals up to this point are collapsed to an eigenstate (True
--   or False) so a <a>current branch</a> of the computation is selected.
qLift_ :: MonadRandom m => m b -> Quantum m () b

-- | <tt>observeWith f</tt> takes an equivalence relation f, breaks the
--   state space into eigenstates of that relation, and collapses to one.
--   For example:
--   
--   <pre>
--   x &lt;- entangle -&lt; map (\s -&gt; (s,1 :+ 0)) [1..20]
--   observeWith (\x y -&gt; x `mod` 2 == y `mod` 2)
--   </pre>
--   
--   Will collapse <tt>x</tt> to be either even or odd, but make no finer
--   decisions than that.
observeWith :: MonadRandom m => (a -> a -> Bool) -> Quantum m a a

-- | observe is just observeWith on equality.
observe :: (Eq a, MonadRandom m) => Quantum m a a

-- | runQuantum takes an input state vector, runs it through the given
--   Quantum arrow, and returns a state vector of outputs.
runQuantum :: Monad m => Quantum m a b -> [(a, Amp)] -> m [(b, Amp)]

-- | <tt>execQuantum q x</tt> passes the state |x&gt; through q, collapses
--   q's output to an eigenstate, and returns it.
execQuantum :: (Eq b, MonadRandom m) => Quantum m a b -> a -> m b
instance Monad m => ArrowChoice (Quantum m)
instance Monad m => Arrow (Quantum m)
instance Monad m => Category (Quantum m)
instance Monad m => ArrowChoice (Operator m)
instance Monad m => Arrow (Operator m)
instance Monad m => Category (Operator m)
instance Functor QState