backprop-0.0.3.0: Heterogeneous, type-safe automatic backpropagation in Haskell

Copyright (c) Justin Le 2017 BSD3 justin@jle.im experimental non-portable None Haskell2010

Numeric.Backprop.Iso

Description

A poor substitute for the Control.Lens.Iso module in lens, providing the Iso type synonym and some sample useful Isos for usage with backprop, without incuring a lens dependency.

If you also import lens, you should only use this module for the Isos it exports, and not import the redefined Iso type synonym or from / iso / review.

Synopsis

# Isomorphisms

type Iso s t a b = forall p f. (Profunctor p, Functor f) => p a (f b) -> p s (f t) Source #

A family of isomorphisms. See Iso'.

type Iso' s a = Iso s s a a Source #

An Iso' s a encodes an isomorphism between an s and an a. It basically lets you go from s -> a and back (from a -> s) while preserving structure. You can basically imagine an Iso' s a to be an (s -> a, a -> s) tuple.

You can get the "forward" direction of an Iso' with view:

view :: Iso'' s a -> (s -> a)


And the "backwards" direction with review:

review :: Iso'' s a -> (a -> s)


You can construct an Iso' using iso, giving the forward and backwards functions:

>>> myIso :: Iso' (Identity a) a
    myIso = iso runIdentity Identity
>>> view myIso (Identity "hello")
"hello"
>>> review myIso "hello"
Identity "hello"


One powerful thing about Iso's is that they're composable using .:

(.) :: Iso' c b -> Iso' b a -> Iso' c a


This is basically provided here so that this package doesn't incurr a lens dependecy, but if you already depend on lens, you should use the version from Control.Lens.Iso instead.

## Construction and usage

iso :: (s -> a) -> (b -> t) -> Iso s t a b Source #

Construct an Iso by giving the "forward" and "backward" direction functions:

>>> myIso :: Iso' (Identity a) a
    myIso = iso runIdentity Identity
>>> view myIso (Identity "hello")
"hello"
>>> review myIso "hello"
Identity "hello"


This is basically provided here so that this package doesn't incurr a lens dependecy, but if you already depend on lens, you should use the version from Control.Lens.Iso instead.

from :: Iso' s a -> Iso' a s Source #

Reverse an Iso'. The forward function becomes the backwards function, and the backwards function becomes the forward function.

This is basically provided here so that this package doesn't incurr a lens dependecy, but if you already depend on lens, you should use the version from Control.Lens.Review instead.

review :: Iso s t a b -> b -> t Source #

Get the "reverse" direction function from an Iso.

This is basically provided here so that this package doesn't incurr a lens dependecy, but if you already depend on lens, you should use the version from Control.Lens.Review instead.

view :: Getting a s a -> s -> a #

view is a synonym for (^.):

>>> view _1 (1, 2)
1


The reason it's not in Lens.Micro is that view in lens has a more general signature:

view :: MonadReader s m => Getting a s a -> m a


So, you would be able to use this view with functions, but not in various reader monads. For most people this shouldn't be an issue; if it is for you, use view from microlens-mtl.

# Useful Isos

coerced :: Coercible s a => Iso' s a Source #

A useful Iso between two types with the same runtime representation.

gTuple :: (Generic a, Code a ~ '[as]) => Iso' a (Tuple as) Source #

An Iso between a type that is a product type, and a tuple that contains all of its components. Uses Generics.SOP and the Generic typeclass.

>>> import qualified Generics.SOP as SOP
>>> data Foo = A Int Bool      deriving Generic
>>> instance SOP.Generic Foo
>>> view gTuple (A 10 True)
10 ::< True ::< Ø
>>> review gTuple (15 ::< False ::< Ø)
A 15 False


gSOP :: Generic a => Iso' a (Sum Tuple (Code a)) Source #

An Iso between a sum type whose constructors are products, and a sum (Sum) of products (Tuple). Uses Generics.SOP and the Generic typeclass.

>>> import qualified Generics.SOP as SOP
>>> data Bar = A Int Bool | B String Double
>>> instance SOP.Generic Bar
>>> 'view' 'gSOP' (A 10 True)
'InL' (10 ::< True ::< Ø)
>>> 'view' 'gSOP' (B "hello" 3.4)
'InR' ('InL' ("hello" ::< 3.4 ::< Ø))
>>> 'review' 'gTuple' ('InL' (15 ::< False ::< Ø))
A 15 False
>>> 'review' 'gTuple' ('InR' ('InL' ("bye" ::< 9.8 ::< Ø)))
B "bye" 9.8


sum1 :: Iso' (Sum f '[a]) (f a) Source #

An iso between a single-type Sum and the single type.

resum1 :: Iso' (f a) (Sum f '[a]) Source #

An iso between a single type and a single-type Sum.

# Utility types

See Numeric.Backprop for a mini-tutorial on Prod and Tuple, and Numeric.Backprop for a mini-tutorial on Sum.

data Prod k f a :: forall k. (k -> *) -> [k] -> * where #

Constructors

 Ø :: Prod k f ([] k) (:<) :: Prod k f ((:) k a1 as) infixr 5

Instances

 Witness ØC ØC (Prod k f (Ø k)) Associated Typestype WitnessC (ØC :: Constraint) (ØC :: Constraint) (Prod k f (Ø k)) :: Constraint # Methods(\\) :: ØC => (ØC -> r) -> Prod k f (Ø k) -> r # IxFunctor1 k [k] (Index k) (Prod k) Methodsimap1 :: (forall a. i b a -> f a -> g a) -> t f b -> t g b # IxFoldable1 k [k] (Index k) (Prod k) MethodsifoldMap1 :: Monoid m => (forall a. i b a -> f a -> m) -> t f b -> m # IxTraversable1 k [k] (Index k) (Prod k) Methodsitraverse1 :: Applicative h => (forall a. i b a -> f a -> h (g a)) -> t f b -> h (t g b) # Functor1 [k] k (Prod k) Methodsmap1 :: (forall a. f a -> g a) -> t f b -> t g b # Foldable1 [k] k (Prod k) MethodsfoldMap1 :: Monoid m => (forall a. f a -> m) -> t f b -> m # Traversable1 [k] k (Prod k) Methodstraverse1 :: Applicative h => (forall a. f a -> h (g a)) -> t f b -> h (t g b) # TestEquality k f => TestEquality [k] (Prod k f) MethodstestEquality :: f a -> f b -> Maybe ((Prod k f :~: a) b) # BoolEquality k f => BoolEquality [k] (Prod k f) MethodsboolEquality :: f a -> f b -> Boolean ((Prod k f == a) b) # Eq1 k f => Eq1 [k] (Prod k f) Methodseq1 :: f a -> f a -> Bool #neq1 :: f a -> f a -> Bool # Ord1 k f => Ord1 [k] (Prod k f) Methodscompare1 :: f a -> f a -> Ordering #(<#) :: f a -> f a -> Bool #(>#) :: f a -> f a -> Bool #(<=#) :: f a -> f a -> Bool #(>=#) :: f a -> f a -> Bool # Show1 k f => Show1 [k] (Prod k f) MethodsshowsPrec1 :: Int -> f a -> ShowS #show1 :: f a -> String # Read1 k f => Read1 [k] (Prod k f) MethodsreadsPrec1 :: Int -> ReadS (Some (Prod k f) f) # (Known [k] (Length k) as, Every k (Known k f) as) => Known [k] (Prod k f) as Associated Typestype KnownC (Prod k f) (as :: Prod k f -> *) (a :: Prod k f) :: Constraint # Methodsknown :: as a # (Witness p q (f a1), Witness s t (Prod a f as)) => Witness (p, s) (q, t) (Prod a f ((:<) a a1 as)) Associated Typestype WitnessC ((p, s) :: Constraint) ((q, t) :: Constraint) (Prod a f ((:<) a a1 as)) :: Constraint # Methods(\\) :: (p, s) => ((q, t) -> r) -> Prod a f ((a :< a1) as) -> r # ListC ((<$>) Constraint * Eq ((<$>) * k f as)) => Eq (Prod k f as) Methods(==) :: Prod k f as -> Prod k f as -> Bool #(/=) :: Prod k f as -> Prod k f as -> Bool # (ListC ((<$>) Constraint * Eq ((<$>) * k f as)), ListC ((<$>) Constraint * Ord ((<$>) * k f as))) => Ord (Prod k f as) Methodscompare :: Prod k f as -> Prod k f as -> Ordering #(<) :: Prod k f as -> Prod k f as -> Bool #(<=) :: Prod k f as -> Prod k f as -> Bool #(>) :: Prod k f as -> Prod k f as -> Bool #(>=) :: Prod k f as -> Prod k f as -> Bool #max :: Prod k f as -> Prod k f as -> Prod k f as #min :: Prod k f as -> Prod k f as -> Prod k f as # ListC ((<$>) Constraint * Show ((<$>) * k f as)) => Show (Prod k f as) MethodsshowsPrec :: Int -> Prod k f as -> ShowS #show :: Prod k f as -> String #showList :: [Prod k f as] -> ShowS # type WitnessC ØC ØC (Prod k f (Ø k)) type WitnessC ØC ØC (Prod k f (Ø k)) = ØC type KnownC [k] (Prod k f) as type KnownC [k] (Prod k f) as = (Known [k] (Length k) as, Every k (Known k f) as) type WitnessC (p, s) (q, t) (Prod a f ((:<) a a1 as)) type WitnessC (p, s) (q, t) (Prod a f ((:<) a a1 as)) = (Witness p q (f a1), Witness s t (Prod a f as))

type Tuple = Prod * I #

A Prod of simple Haskell types.

data Sum k f a :: forall k. (k -> *) -> [k] -> * where #

Constructors

 InL :: Sum k f ((:) k a1 as) InR :: Sum k f ((:) k a1 as)

Instances

 Witness p q (f a) => Witness p q (Sum k f ((:) k a ([] k))) Associated Typestype WitnessC (p :: Constraint) (q :: Constraint) (Sum k f ((:) k a ([] k))) :: Constraint # Methods(\\) :: p => (q -> r) -> Sum k f ((k ': a) [k]) -> r # (Witness p q (f a1), Witness p q (Sum a f ((:<) a b as))) => Witness p q (Sum a f ((:<) a a1 ((:<) a b as))) Associated Typestype WitnessC (p :: Constraint) (q :: Constraint) (Sum a f ((:<) a a1 ((:<) a b as))) :: Constraint # Methods(\\) :: p => (q -> r) -> Sum a f ((a :< a1) ((a :< b) as)) -> r # IxFunctor1 k [k] (Index k) (Sum k) Methodsimap1 :: (forall a. i b a -> f a -> g a) -> t f b -> t g b # IxFoldable1 k [k] (Index k) (Sum k) MethodsifoldMap1 :: Monoid m => (forall a. i b a -> f a -> m) -> t f b -> m # IxTraversable1 k [k] (Index k) (Sum k) Methodsitraverse1 :: Applicative h => (forall a. i b a -> f a -> h (g a)) -> t f b -> h (t g b) # Functor1 [k] k (Sum k) Methodsmap1 :: (forall a. f a -> g a) -> t f b -> t g b # Foldable1 [k] k (Sum k) MethodsfoldMap1 :: Monoid m => (forall a. f a -> m) -> t f b -> m # Traversable1 [k] k (Sum k) Methodstraverse1 :: Applicative h => (forall a. f a -> h (g a)) -> t f b -> h (t g b) # Eq1 k f => Eq1 [k] (Sum k f) Methodseq1 :: f a -> f a -> Bool #neq1 :: f a -> f a -> Bool # Ord1 k f => Ord1 [k] (Sum k f) Methodscompare1 :: f a -> f a -> Ordering #(<#) :: f a -> f a -> Bool #(>#) :: f a -> f a -> Bool #(<=#) :: f a -> f a -> Bool #(>=#) :: f a -> f a -> Bool # Show1 k f => Show1 [k] (Sum k f) MethodsshowsPrec1 :: Int -> f a -> ShowS #show1 :: f a -> String # Read1 k f => Read1 [k] (Sum k f) MethodsreadsPrec1 :: Int -> ReadS (Some (Sum k f) f) # ListC ((<$>) Constraint * Eq ((<$>) * k f as)) => Eq (Sum k f as) Methods(==) :: Sum k f as -> Sum k f as -> Bool #(/=) :: Sum k f as -> Sum k f as -> Bool # (ListC ((<$>) Constraint * Eq ((<$>) * k f as)), ListC ((<$>) Constraint * Ord ((<$>) * k f as))) => Ord (Sum k f as) Methodscompare :: Sum k f as -> Sum k f as -> Ordering #(<) :: Sum k f as -> Sum k f as -> Bool #(<=) :: Sum k f as -> Sum k f as -> Bool #(>) :: Sum k f as -> Sum k f as -> Bool #(>=) :: Sum k f as -> Sum k f as -> Bool #max :: Sum k f as -> Sum k f as -> Sum k f as #min :: Sum k f as -> Sum k f as -> Sum k f as # ListC ((<$>) Constraint * Show ((<$>) * k f as)) => Show (Sum k f as) MethodsshowsPrec :: Int -> Sum k f as -> ShowS #show :: Sum k f as -> String #showList :: [Sum k f as] -> ShowS # type WitnessC p q (Sum a f ((:<) a a1 ((:<) a b as))) type WitnessC p q (Sum a f ((:<) a a1 ((:<) a b as))) = (Witness p q (f a1), Witness p q (Sum a f ((:<) a b as))) type WitnessC p q (Sum k f ((:) k a ([] k))) type WitnessC p q (Sum k f ((:) k a ([] k))) = Witness p q (f a)

newtype I a :: * -> * #

Constructors

 I FieldsgetI :: a

Instances

 Methods(>>=) :: I a -> (a -> I b) -> I b #(>>) :: I a -> I b -> I b #return :: a -> I a #fail :: String -> I a # Methodsfmap :: (a -> b) -> I a -> I b #(<\$) :: a -> I b -> I a # Methodspure :: a -> I a #(<*>) :: I (a -> b) -> I a -> I b #(*>) :: I a -> I b -> I b #(<*) :: I a -> I b -> I a # Methodsfold :: Monoid m => I m -> m #foldMap :: Monoid m => (a -> m) -> I a -> m #foldr :: (a -> b -> b) -> b -> I a -> b #foldr' :: (a -> b -> b) -> b -> I a -> b #foldl :: (b -> a -> b) -> b -> I a -> b #foldl' :: (b -> a -> b) -> b -> I a -> b #foldr1 :: (a -> a -> a) -> I a -> a #foldl1 :: (a -> a -> a) -> I a -> a #toList :: I a -> [a] #null :: I a -> Bool #length :: I a -> Int #elem :: Eq a => a -> I a -> Bool #maximum :: Ord a => I a -> a #minimum :: Ord a => I a -> a #sum :: Num a => I a -> a #product :: Num a => I a -> a # Methodstraverse :: Applicative f => (a -> f b) -> I a -> f (I b) #sequenceA :: Applicative f => I (f a) -> f (I a) #mapM :: Monad m => (a -> m b) -> I a -> m (I b) #sequence :: Monad m => I (m a) -> m (I a) # Witness p q a => Witness p q (I a) Associated Typestype WitnessC (p :: Constraint) (q :: Constraint) (I a) :: Constraint # Methods(\\) :: p => (q -> r) -> I a -> r # Eq a => Eq (I a) Methods(==) :: I a -> I a -> Bool #(/=) :: I a -> I a -> Bool # Num a => Num (I a) Methods(+) :: I a -> I a -> I a #(-) :: I a -> I a -> I a #(*) :: I a -> I a -> I a #negate :: I a -> I a #abs :: I a -> I a #signum :: I a -> I a #fromInteger :: Integer -> I a # Ord a => Ord (I a) Methodscompare :: I a -> I a -> Ordering #(<) :: I a -> I a -> Bool #(<=) :: I a -> I a -> Bool #(>) :: I a -> I a -> Bool #(>=) :: I a -> I a -> Bool #max :: I a -> I a -> I a #min :: I a -> I a -> I a # Show a => Show (I a) MethodsshowsPrec :: Int -> I a -> ShowS #show :: I a -> String #showList :: [I a] -> ShowS # type WitnessC p q (I a) type WitnessC p q (I a) = Witness p q a