{-# LANGUAGE Arrows #-}
-- |
-- Copyright  : (c) Ivan Perez, 2019-2023
--              (c) Ivan Perez and Manuel Baerenz, 2016-2018
-- License    : BSD3
-- Maintainer : ivan.perez@keera.co.uk
--
-- Integration and derivation of input signals.
--
-- In continuous time, these primitives define SFs that integrate/derive the
-- input signal. Since this is subject to the sampling resolution, simple
-- versions are implemented (like the rectangle rule for the integral).
--
-- In discrete time, all we do is count the number of events.
--
-- The combinator 'iterFrom' gives enough flexibility to program your own
-- leak-free integration and derivation SFs.
--
-- Many primitives and combinators in this module require instances of
-- simple-affine-spaces's 'VectorSpace'. BearRiver does not enforce the use of a
-- particular vector space implementation, meaning you could use 'integral' for
-- example with other vector types like V2, V1, etc. from the library linear.
-- For an example, see
-- <https://gist.github.com/walseb/1e0a0ca98aaa9469ab5da04e24f482c2 this gist>.
module FRP.BearRiver.Integration
    (
      -- * Integration
      integral
    , imIntegral
    , trapezoidIntegral
    , impulseIntegral
    , count

      -- * Differentiation
    , derivative
    , iterFrom
    )
  where

-- External imports
import Control.Arrow    (returnA, (***), (>>^))
import Data.VectorSpace (VectorSpace, zeroVector, (*^), (^+^), (^-^), (^/))

-- Internal imports (dunai)
import Control.Monad.Trans.MSF                 (ask)
import Data.MonadicStreamFunction              (accumulateWith, constM, iPre)
import Data.MonadicStreamFunction.InternalCore (MSF (MSF))

-- Internal imports
import FRP.BearRiver.Event        (Event)
import FRP.BearRiver.Hybrid       (accumBy, accumHoldBy)
import FRP.BearRiver.InternalCore (DTime, SF)

-- * Integration

-- | Integration using the rectangle rule.
integral :: (Monad m, Fractional s, VectorSpace a s) => SF m a a
integral :: forall (m :: * -> *) s a.
(Monad m, Fractional s, VectorSpace a s) =>
SF m a a
integral = a -> SF m a a
forall (m :: * -> *) s a.
(Monad m, Fractional s, VectorSpace a s) =>
a -> SF m a a
integralFrom a
forall v a. VectorSpace v a => v
zeroVector

-- | Integrate using an auxiliary function that takes the current and the last
-- input, the time between those samples, and the last output, and returns a
-- new output.
integralFrom :: (Monad m, Fractional s, VectorSpace a s) => a -> SF m a a
integralFrom :: forall (m :: * -> *) s a.
(Monad m, Fractional s, VectorSpace a s) =>
a -> SF m a a
integralFrom a
a0 = proc a
a -> do
  DTime
dt <- ClockInfo m DTime -> MSF (ClockInfo m) () DTime
forall (m :: * -> *) b a. Monad m => m b -> MSF m a b
constM ClockInfo m DTime
forall (m :: * -> *) r. Monad m => ReaderT r m r
ask        -< ()
  (a -> a -> a) -> a -> MSF (ClockInfo m) a a
forall (m :: * -> *) a s.
Monad m =>
(a -> s -> s) -> s -> MSF m a s
accumulateWith a -> a -> a
forall v a. VectorSpace v a => v -> v -> v
(^+^) a
a0 -< DTime -> s
forall a b. (Real a, Fractional b) => a -> b
realToFrac DTime
dt s -> a -> a
forall v a. VectorSpace v a => a -> v -> v
*^ a
a

-- | \"Immediate\" integration (using the function's value at the current time).
imIntegral :: (Fractional s, VectorSpace a s, Monad m)
           => a -> SF m a a
imIntegral :: forall s a (m :: * -> *).
(Fractional s, VectorSpace a s, Monad m) =>
a -> SF m a a
imIntegral = ((\a
_ a
a' DTime
dt a
v -> a
v a -> a -> a
forall v a. VectorSpace v a => v -> v -> v
^+^ DTime -> s
forall a b. (Real a, Fractional b) => a -> b
realToFrac DTime
dt s -> a -> a
forall v a. VectorSpace v a => a -> v -> v
*^ a
a') (a -> a -> DTime -> a -> a) -> a -> SF m a a
forall (m :: * -> *) a b.
Monad m =>
(a -> a -> DTime -> b -> b) -> b -> SF m a b
`iterFrom`)

-- | Trapezoid integral (using the average between the value at the last time
-- and the value at the current time).
trapezoidIntegral :: (Fractional s, VectorSpace a s, Monad m) => SF m a a
trapezoidIntegral :: forall s a (m :: * -> *).
(Fractional s, VectorSpace a s, Monad m) =>
SF m a a
trapezoidIntegral =
  (a -> a -> DTime -> a -> a) -> a -> SF m a a
forall (m :: * -> *) a b.
Monad m =>
(a -> a -> DTime -> b -> b) -> b -> SF m a b
iterFrom (\a
a a
a' DTime
dt a
v -> a
v a -> a -> a
forall v a. VectorSpace v a => v -> v -> v
^+^ (DTime -> s
forall a b. (Real a, Fractional b) => a -> b
realToFrac DTime
dt s -> s -> s
forall a. Fractional a => a -> a -> a
/ s
2) s -> a -> a
forall v a. VectorSpace v a => a -> v -> v
*^ (a
a a -> a -> a
forall v a. VectorSpace v a => v -> v -> v
^+^ a
a')) a
forall v a. VectorSpace v a => v
zeroVector

-- | Integrate the first input signal and add the /discrete/ accumulation (sum)
-- of the second, discrete, input signal.
impulseIntegral :: (Fractional k, VectorSpace a k, Monad m)
                => SF m (a, Event a) a
impulseIntegral :: forall k a (m :: * -> *).
(Fractional k, VectorSpace a k, Monad m) =>
SF m (a, Event a) a
impulseIntegral = (SF m a a
forall (m :: * -> *) s a.
(Monad m, Fractional s, VectorSpace a s) =>
SF m a a
integral SF m a a
-> MSF (ClockInfo m) (Event a) a
-> MSF (ClockInfo m) (a, Event a) (a, a)
forall b c b' c'.
MSF (ClockInfo m) b c
-> MSF (ClockInfo m) b' c' -> MSF (ClockInfo m) (b, b') (c, c')
forall (a :: * -> * -> *) b c b' c'.
Arrow a =>
a b c -> a b' c' -> a (b, b') (c, c')
*** (a -> a -> a) -> a -> MSF (ClockInfo m) (Event a) a
forall (m :: * -> *) b a.
Monad m =>
(b -> a -> b) -> b -> SF m (Event a) b
accumHoldBy a -> a -> a
forall v a. VectorSpace v a => v -> v -> v
(^+^) a
forall v a. VectorSpace v a => v
zeroVector) MSF (ClockInfo m) (a, Event a) (a, a)
-> ((a, a) -> a) -> MSF (ClockInfo m) (a, Event a) a
forall (a :: * -> * -> *) b c d.
Arrow a =>
a b c -> (c -> d) -> a b d
>>^ (a -> a -> a) -> (a, a) -> a
forall a b c. (a -> b -> c) -> (a, b) -> c
uncurry a -> a -> a
forall v a. VectorSpace v a => v -> v -> v
(^+^)

-- | Count the occurrences of input events.
--
-- >>> embed count (deltaEncode 1 [Event 'a', NoEvent, Event 'b'])
-- [Event 1,NoEvent,Event 2]
count :: (Integral b, Monad m) => SF m (Event a) (Event b)
count :: forall b (m :: * -> *) a.
(Integral b, Monad m) =>
SF m (Event a) (Event b)
count = (b -> a -> b) -> b -> SF m (Event a) (Event b)
forall (m :: * -> *) b a.
Monad m =>
(b -> a -> b) -> b -> SF m (Event a) (Event b)
accumBy (\b
n a
_ -> b
n b -> b -> b
forall a. Num a => a -> a -> a
+ b
1) b
0

-- * Differentiation

-- | A very crude version of a derivative. It simply divides the value
-- difference by the time difference. Use at your own risk.
derivative :: (Monad m, Fractional s, VectorSpace a s) => SF m a a
derivative :: forall (m :: * -> *) s a.
(Monad m, Fractional s, VectorSpace a s) =>
SF m a a
derivative = a -> SF m a a
forall (m :: * -> *) s a.
(Monad m, Fractional s, VectorSpace a s) =>
a -> SF m a a
derivativeFrom a
forall v a. VectorSpace v a => v
zeroVector

-- | A very crude version of a derivative. It simply divides the value
-- difference by the time difference. Use at your own risk.
--
-- Starts from a given value for the input signal at time zero.
derivativeFrom :: (Monad m, Fractional s, VectorSpace a s) => a -> SF m a a
derivativeFrom :: forall (m :: * -> *) s a.
(Monad m, Fractional s, VectorSpace a s) =>
a -> SF m a a
derivativeFrom a
a0 = proc a
a -> do
  DTime
dt   <- ClockInfo m DTime -> MSF (ClockInfo m) () DTime
forall (m :: * -> *) b a. Monad m => m b -> MSF m a b
constM ClockInfo m DTime
forall (m :: * -> *) r. Monad m => ReaderT r m r
ask  -< ()
  a
aOld <- a -> MSF (ClockInfo m) a a
forall (m :: * -> *) a. Monad m => a -> MSF m a a
iPre a
a0     -< a
a
  MSF (ClockInfo m) a a
forall (a :: * -> * -> *) b. Arrow a => a b b
returnA             -< (a
a a -> a -> a
forall v a. VectorSpace v a => v -> v -> v
^-^ a
aOld) a -> s -> a
forall v a. VectorSpace v a => v -> a -> v
^/ DTime -> s
forall a b. (Real a, Fractional b) => a -> b
realToFrac DTime
dt

-- | Integrate using an auxiliary function that takes the current and the last
-- input, the time between those samples, and the last output, and returns a
-- new output.

-- NOTE: BUG in this function, it needs two a's but we can only provide one
iterFrom :: Monad m => (a -> a -> DTime -> b -> b) -> b -> SF m a b
iterFrom :: forall (m :: * -> *) a b.
Monad m =>
(a -> a -> DTime -> b -> b) -> b -> SF m a b
iterFrom a -> a -> DTime -> b -> b
f b
b = (a -> ClockInfo m (b, MSF (ReaderT DTime m) a b))
-> MSF (ReaderT DTime m) a b
forall (m :: * -> *) a b. (a -> m (b, MSF m a b)) -> MSF m a b
MSF ((a -> ClockInfo m (b, MSF (ReaderT DTime m) a b))
 -> MSF (ReaderT DTime m) a b)
-> (a -> ClockInfo m (b, MSF (ReaderT DTime m) a b))
-> MSF (ReaderT DTime m) a b
forall a b. (a -> b) -> a -> b
$ \a
a -> do
  DTime
dt <- ReaderT DTime m DTime
forall (m :: * -> *) r. Monad m => ReaderT r m r
ask
  let b' :: b
b' = a -> a -> DTime -> b -> b
f a
a a
a DTime
dt b
b
  (b, MSF (ReaderT DTime m) a b)
-> ClockInfo m (b, MSF (ReaderT DTime m) a b)
forall a. a -> ReaderT DTime m a
forall (m :: * -> *) a. Monad m => a -> m a
return (b
b, (a -> a -> DTime -> b -> b) -> b -> MSF (ReaderT DTime m) a b
forall (m :: * -> *) a b.
Monad m =>
(a -> a -> DTime -> b -> b) -> b -> SF m a b
iterFrom a -> a -> DTime -> b -> b
f b
b')