| Copyright | (c) Justin Le 2023 |
|---|---|
| License | BSD3 |
| Maintainer | justin@jle.im |
| Stability | experimental |
| Portability | non-portable |
| Safe Haskell | Safe-Inferred |
| Language | Haskell2010 |
Numeric.Backprop.Num
Description
Provides the exact same API as Numeric.Backprop, except requiring
Num instances for all types involved instead of Backprop instances.
This was the original API of the library (for version 0.1).
Num is strictly more powerful than Backprop, and is a stronger
constraint on types than is necessary for proper backpropagating. In
particular, fromInteger is a problem for many types, preventing useful
backpropagation for lists, variable-length vectors (like Data.Vector)
and variable-size matrices from linear algebra libraries like hmatrix
and accelerate.
However, this module might be useful in situations where you are working
with external types with Num instances, and you want to avoid writing
orphan instances for external types.
If you have external types that are not Num instances, consider
instead Numeric.Backprop.External.
If you need a Num instance for tuples, you can use the orphan
instances in the <https://hackage.haskell.org/package/NumInstances
NumInstances> package (in particular, Data.NumInstances.Tuple) if you
are writing an application and do not have to worry about orphan
instances.
See Numeric.Backprop for fuller documentation on using these functions.
Since: 0.2.0.0
Synopsis
- data BVar s a
- data W
- backprop :: (Num a, Num b) => (forall s. Reifies s W => BVar s a -> BVar s b) -> a -> (b, a)
- evalBP :: (forall s. Reifies s W => BVar s a -> BVar s b) -> a -> b
- gradBP :: (Num a, Num b) => (forall s. Reifies s W => BVar s a -> BVar s b) -> a -> a
- backpropWith :: Num a => (forall s. Reifies s W => BVar s a -> BVar s b) -> a -> (b, b -> a)
- evalBP0 :: (forall s. Reifies s W => BVar s a) -> a
- backprop2 :: (Num a, Num b, Num c) => (forall s. Reifies s W => BVar s a -> BVar s b -> BVar s c) -> a -> b -> (c, (a, b))
- evalBP2 :: (forall s. Reifies s W => BVar s a -> BVar s b -> BVar s c) -> a -> b -> c
- gradBP2 :: (Num a, Num b, Num c) => (forall s. Reifies s W => BVar s a -> BVar s b -> BVar s c) -> a -> b -> (a, b)
- backpropWith2 :: (Num a, Num b) => (forall s. Reifies s W => BVar s a -> BVar s b -> BVar s c) -> a -> b -> (c, c -> (a, b))
- backpropN :: (RPureConstrained Num as, Num b) => (forall s. Reifies s W => Rec (BVar s) as -> BVar s b) -> Rec Identity as -> (b, Rec Identity as)
- evalBPN :: forall as b. (forall s. Reifies s W => Rec (BVar s) as -> BVar s b) -> Rec Identity as -> b
- gradBPN :: (RPureConstrained Num as, Num b) => (forall s. Reifies s W => Rec (BVar s) as -> BVar s b) -> Rec Identity as -> Rec Identity as
- backpropWithN :: RPureConstrained Num as => (forall s. Reifies s W => Rec (BVar s) as -> BVar s b) -> Rec Identity as -> (b, b -> Rec Identity as)
- constVar :: a -> BVar s a
- auto :: a -> BVar s a
- coerceVar :: Coercible a b => BVar s a -> BVar s b
- (^^.) :: forall b a s. (Num a, Num b, Reifies s W) => BVar s b -> Lens' b a -> BVar s a
- (.~~) :: (Num a, Num b, Reifies s W) => Lens' b a -> BVar s a -> BVar s b -> BVar s b
- (%~~) :: (Num a, Num b, Reifies s W) => Lens' b a -> (BVar s a -> BVar s a) -> BVar s b -> BVar s b
- (^^?) :: forall b a s. (Num b, Num a, Reifies s W) => BVar s b -> Traversal' b a -> Maybe (BVar s a)
- (^^..) :: forall b a s. (Num b, Num a, Reifies s W) => BVar s b -> Traversal' b a -> [BVar s a]
- (^^?!) :: forall b a s. (Num b, Num a, Reifies s W) => BVar s b -> Traversal' b a -> BVar s a
- viewVar :: forall b a s. (Num a, Num b, Reifies s W) => Lens' b a -> BVar s b -> BVar s a
- setVar :: forall a b s. (Num a, Num b, Reifies s W) => Lens' b a -> BVar s a -> BVar s b -> BVar s b
- overVar :: (Num a, Num b, Reifies s W) => Lens' b a -> (BVar s a -> BVar s a) -> BVar s b -> BVar s b
- sequenceVar :: (Traversable t, Num a, Reifies s W) => BVar s (t a) -> t (BVar s a)
- collectVar :: (Foldable t, Functor t, Num a, Reifies s W) => t (BVar s a) -> BVar s (t a)
- previewVar :: forall b a s. (Num b, Num a, Reifies s W) => Traversal' b a -> BVar s b -> Maybe (BVar s a)
- toListOfVar :: forall b a s. (Num b, Num a, Reifies s W) => Traversal' b a -> BVar s b -> [BVar s a]
- isoVar :: (Num a, Reifies s W) => (a -> b) -> (b -> a) -> BVar s a -> BVar s b
- isoVar2 :: (Num a, Num b, Reifies s W) => (a -> b -> c) -> (c -> (a, b)) -> BVar s a -> BVar s b -> BVar s c
- isoVar3 :: (Num a, Num b, Num c, Reifies s W) => (a -> b -> c -> d) -> (d -> (a, b, c)) -> BVar s a -> BVar s b -> BVar s c -> BVar s d
- isoVarN :: (RPureConstrained Num as, Reifies s W) => (Rec Identity as -> b) -> (b -> Rec Identity as) -> Rec (BVar s) as -> BVar s b
- liftOp :: (RPureConstrained Num as, Reifies s W) => Op as b -> Rec (BVar s) as -> BVar s b
- liftOp1 :: (Num a, Reifies s W) => Op '[a] b -> BVar s a -> BVar s b
- liftOp2 :: (Num a, Num b, Reifies s W) => Op '[a, b] c -> BVar s a -> BVar s b -> BVar s c
- liftOp3 :: (Num a, Num b, Num c, Reifies s W) => Op '[a, b, c] d -> BVar s a -> BVar s b -> BVar s c -> BVar s d
- newtype Op as a = Op {}
- op0 :: a -> Op '[] a
- opConst :: forall as a. RPureConstrained Num as => a -> Op as a
- idOp :: Op '[a] a
- bpOp :: RPureConstrained Num as => (forall s. Reifies s W => Rec (BVar s) as -> BVar s b) -> Op as b
- op1 :: (a -> (b, b -> a)) -> Op '[a] b
- op2 :: (a -> b -> (c, c -> (a, b))) -> Op '[a, b] c
- op3 :: (a -> b -> c -> (d, d -> (a, b, c))) -> Op '[a, b, c] d
- opCoerce :: Coercible a b => Op '[a] b
- opTup :: Op as (Rec Identity as)
- opIso :: (a -> b) -> (b -> a) -> Op '[a] b
- opIsoN :: (Rec Identity as -> b) -> (b -> Rec Identity as) -> Op as b
- opLens :: Num a => Lens' a b -> Op '[a] b
- noGrad1 :: (a -> b) -> Op '[a] b
- noGrad :: (Rec Identity as -> b) -> Op as b
- class Reifies (s :: k) a | s -> a
Types
A is a value of type BVar s aa that can be "backpropagated".
Functions referring to BVars are tracked by the library and can be
automatically differentiated to get their gradients and results.
For simple numeric values, you can use its Num, Fractional, and
Floating instances to manipulate them as if they were the numbers they
represent.
If a contains items, the items can be accessed and extracted using
lenses. A can be used to access an Lens' b aa inside a b, using
^^. (viewVar):
(^.) :: a ->Lens'a b -> b (^^.) ::BVars a ->Lens'a b ->BVars b
There is also ^^? (previewVar), to use a Prism'
or Traversal' to extract a target that may or may not be present
(which can implement pattern matching), ^^..
(toListOfVar) to use a Traversal' to extract all
targets inside a BVar, and .~~ (setVar) to set and update values
inside a BVar.
If you have control over your data type definitions, you can also use
splitBV and joinBV to manipulate
data types by easily extracting fields out of a BVar of data types and
creating BVars of data types out of BVars of their fields. See
Numeric.Backprop for a tutorial on this use pattern.
For more complex operations, libraries can provide functions on BVars
using liftOp and related functions. This is how you
can create primitive functions that users can use to manipulate your
library's values. See
https://backprop.jle.im/08-equipping-your-library.html for a detailed
guide.
For example, the hmatrix library has a matrix-vector multiplication
function, #> :: L m n -> R n -> L m.
A library could instead provide a function #> :: , which the user can then use to manipulate their
BVar (L m n) -> BVar
(R n) -> BVar (R m)BVars of L m ns and R ns, etc.
See Numeric.Backprop and documentation for
liftOp for more information.
Instances
| IsoHKD (BVar s :: Type -> Type) (a :: Type) Source # | Since: 0.2.6.3 |
| BVGroup s ('[] :: [Type]) (K1 i a :: Type -> Type) (K1 i (BVar s a) :: Type -> Type) Source # | |
| (Backprop a, Reifies s W) => Backprop (BVar s a) Source # | Since: 0.2.2.0 |
| (Floating a, Reifies s W) => Floating (BVar s a) Source # | |
Defined in Numeric.Backprop.Internal Methods sqrt :: BVar s a -> BVar s a # (**) :: BVar s a -> BVar s a -> BVar s a # logBase :: BVar s a -> BVar s a -> BVar s a # asin :: BVar s a -> BVar s a # acos :: BVar s a -> BVar s a # atan :: BVar s a -> BVar s a # sinh :: BVar s a -> BVar s a # cosh :: BVar s a -> BVar s a # tanh :: BVar s a -> BVar s a # asinh :: BVar s a -> BVar s a # acosh :: BVar s a -> BVar s a # atanh :: BVar s a -> BVar s a # log1p :: BVar s a -> BVar s a # expm1 :: BVar s a -> BVar s a # | |
| (Num a, Reifies s W) => Num (BVar s a) Source # | |
| (Fractional a, Reifies s W) => Fractional (BVar s a) Source # | |
| NFData a => NFData (BVar s a) Source # | This will force the value inside, as well. |
Defined in Numeric.Backprop.Internal | |
| Eq a => Eq (BVar s a) Source # | Compares the values inside the Since: 0.1.5.0 |
| Ord a => Ord (BVar s a) Source # | Compares the values inside the Since: 0.1.5.0 |
Defined in Numeric.Backprop.Internal | |
| type HKD (BVar s :: Type -> Type) (a :: Type) Source # | |
Running
backprop :: (Num a, Num b) => (forall s. Reifies s W => BVar s a -> BVar s b) -> a -> (b, a) Source #
backprop, but with Num constraints instead of
Backprop constraints.
See module documentation for Numeric.Backprop.Num for information on using this with tuples.
backpropWith :: Num a => (forall s. Reifies s W => BVar s a -> BVar s b) -> a -> (b, b -> a) Source #
backpropWith, but with Num constraints instead of
Backprop constraints.
See module documentation for Numeric.Backprop.Num for information on using this with tuples.
Note that argument order changed in v0.2.4.
Since: 0.2.0.0
Multiple inputs
backprop2 :: (Num a, Num b, Num c) => (forall s. Reifies s W => BVar s a -> BVar s b -> BVar s c) -> a -> b -> (c, (a, b)) Source #
gradBP2 :: (Num a, Num b, Num c) => (forall s. Reifies s W => BVar s a -> BVar s b -> BVar s c) -> a -> b -> (a, b) Source #
Arguments
| :: (Num a, Num b) | |
| => (forall s. Reifies s W => BVar s a -> BVar s b -> BVar s c) | |
| -> a | |
| -> b | |
| -> (c, c -> (a, b)) | Takes function giving gradient of final result given the output of function |
backpropWith2, but with Num constraints instead of
Backprop constraints.
Note that argument order changed in v0.2.4.
Since: 0.2.0.0
backpropN :: (RPureConstrained Num as, Num b) => (forall s. Reifies s W => Rec (BVar s) as -> BVar s b) -> Rec Identity as -> (b, Rec Identity as) Source #
backpropN, but with Num constraints instead of
Backprop constraints.
The in the constraint says that every
value in the type-level list RPureConstrained Num asas must have a Num instance. This
means you can use, say, '[Double, Float, Int], but not '[Double,
Bool, String].
If you stick to concerete, monomorphic usage of this (with specific
types, typed into source code, known at compile-time), then
should be fulfilled automatically.AllPureConstrained Num as
evalBPN :: forall as b. (forall s. Reifies s W => Rec (BVar s) as -> BVar s b) -> Rec Identity as -> b Source #
evalBP generalized to multiple inputs of different types. See
documentation for backpropN for more details.
gradBPN :: (RPureConstrained Num as, Num b) => (forall s. Reifies s W => Rec (BVar s) as -> BVar s b) -> Rec Identity as -> Rec Identity as Source #
backpropWithN :: RPureConstrained Num as => (forall s. Reifies s W => Rec (BVar s) as -> BVar s b) -> Rec Identity as -> (b, b -> Rec Identity as) Source #
backpropWithN, but with Num constraints instead
of Backprop constraints.
See backpropN for information on the AllConstrained constraint.
Note that argument order changed in v0.2.4.
Since: 0.2.0.0
Manipulating BVar
constVar :: a -> BVar s a Source #
Lift a value into a BVar representing a constant value.
This value will not be considered an input, and its gradients will not be backpropagated.
coerceVar :: Coercible a b => BVar s a -> BVar s b Source #
Coerce a BVar contents. Useful for things like newtype wrappers.
Since: 0.1.5.2
(^^.) :: forall b a s. (Num a, Num b, Reifies s W) => BVar s b -> Lens' b a -> BVar s a infixl 8 Source #
(.~~) :: (Num a, Num b, Reifies s W) => Lens' b a -> BVar s a -> BVar s b -> BVar s b infixl 8 Source #
(%~~) :: (Num a, Num b, Reifies s W) => Lens' b a -> (BVar s a -> BVar s a) -> BVar s b -> BVar s b infixr 4 Source #
(^^?) :: forall b a s. (Num b, Num a, Reifies s W) => BVar s b -> Traversal' b a -> Maybe (BVar s a) infixl 8 Source #
^^?, but with Num constraints instead of
Backprop constraints.
Note that many automatically-generated prisms by the lens package use
tuples, which cannot work this this by default (because tuples do not
have a Num instance).
If you are writing an application or don't have to worry about orphan
instances, you can pull in the orphan instances from
NumInstances.
Alternatively, you can chain those prisms with conversions to the
anonymous canonical strict tuple types in Numeric.Backprop.Tuple,
which do have Num instances.
myPrism ::Prism'c (a, b) myPrism .isotupT2t2Tup::Prism'c (T2a b)
(^^..) :: forall b a s. (Num b, Num a, Reifies s W) => BVar s b -> Traversal' b a -> [BVar s a] Source #
(^^?!) :: forall b a s. (Num b, Num a, Reifies s W) => BVar s b -> Traversal' b a -> BVar s a infixl 8 Source #
setVar :: forall a b s. (Num a, Num b, Reifies s W) => Lens' b a -> BVar s a -> BVar s b -> BVar s b Source #
overVar :: (Num a, Num b, Reifies s W) => Lens' b a -> (BVar s a -> BVar s a) -> BVar s b -> BVar s b Source #
sequenceVar :: (Traversable t, Num a, Reifies s W) => BVar s (t a) -> t (BVar s a) Source #
sequenceVar, but with Num constraints instead of
Backprop constraints.
Since v0.2.4, requires a Num constraint on t a.
collectVar :: (Foldable t, Functor t, Num a, Reifies s W) => t (BVar s a) -> BVar s (t a) Source #
collectVar, but with Num constraints instead of
Backprop constraints.
Prior to v0.2.3, required a Num constraint on t a.
previewVar :: forall b a s. (Num b, Num a, Reifies s W) => Traversal' b a -> BVar s b -> Maybe (BVar s a) Source #
previewVar, but with Num constraints instead of
Backprop constraints.
See documentation for ^^? for more information and important notes.
toListOfVar :: forall b a s. (Num b, Num a, Reifies s W) => Traversal' b a -> BVar s b -> [BVar s a] Source #
toListOfVar, but with Num constraints instead of
Backprop constraints.
With Isomorphisms
isoVar2 :: (Num a, Num b, Reifies s W) => (a -> b -> c) -> (c -> (a, b)) -> BVar s a -> BVar s b -> BVar s c Source #
isoVar3 :: (Num a, Num b, Num c, Reifies s W) => (a -> b -> c -> d) -> (d -> (a, b, c)) -> BVar s a -> BVar s b -> BVar s c -> BVar s d Source #
isoVarN :: (RPureConstrained Num as, Reifies s W) => (Rec Identity as -> b) -> (b -> Rec Identity as) -> Rec (BVar s) as -> BVar s b Source #
With Ops
liftOp3 :: (Num a, Num b, Num c, Reifies s W) => Op '[a, b, c] d -> BVar s a -> BVar s b -> BVar s c -> BVar s d Source #
Op
An describes a differentiable function from Op as aas to a.
For example, a value of type
Op '[Int, Bool] Double
is a function from an Int and a Bool, returning a Double. It can
be differentiated to give a gradient of an Int and a Bool if given
a total derivative for the Double. If we call Bool \(2\), then,
mathematically, it is akin to a:
\[ f : \mathbb{Z} \times 2 \rightarrow \mathbb{R} \]
See runOp, gradOp, and gradOpWith for examples on how to run it,
and Op for instructions on creating it.
It is simpler to not use this type constructor directly, and instead use
the op2, op1, op2, and op3 helper smart constructors.
See Numeric.Backprop.Op for a mini-tutorial on using Rec and
'Rec Identity'.
To use an Op with the backprop library, see liftOp, liftOp1,
liftOp2, and liftOp3.
Constructors
| Op | Construct an See the module documentation for Numeric.Backprop.Op for more
details on the function that this constructor and |
Instances
| (RPureConstrained Num as, Floating a) => Floating (Op as a) Source # | |
| (RPureConstrained Num as, Num a) => Num (Op as a) Source # | |
| (RPureConstrained Num as, Fractional a) => Fractional (Op as a) Source # | |
Creation
Create an Op that takes no inputs and always returns the given
value.
There is no gradient, of course (using gradOp will give you an empty
tuple), because there is no input to have a gradient of.
>>>runOp (op0 10) RNil(10, RNil)
For a constant Op that takes input and ignores it, see opConst and
opConst'.
opConst :: forall as a. RPureConstrained Num as => a -> Op as a Source #
An Op that ignores all of its inputs and returns a given constant
value.
>>>gradOp' (opConst 10) (1 :& 2 :& 3 :& RNil)(10, 0 :& 0 :& 0 :& RNil)
bpOp :: RPureConstrained Num as => (forall s. Reifies s W => Rec (BVar s) as -> BVar s b) -> Op as b Source #
Giving gradients directly
op1 :: (a -> (b, b -> a)) -> Op '[a] b Source #
Create an Op of a function taking one input, by giving its explicit
derivative. The function should return a tuple containing the result of
the function, and also a function taking the derivative of the result
and return the derivative of the input.
If we have
\[ \eqalign{ f &: \mathbb{R} \rightarrow \mathbb{R}\cr y &= f(x)\cr z &= g(y) } \]
Then the derivative \( \frac{dz}{dx} \), it would be:
\[ \frac{dz}{dx} = \frac{dz}{dy} \frac{dy}{dx} \]
If our Op represents \(f\), then the second item in the resulting
tuple should be a function that takes \(\frac{dz}{dy}\) and returns
\(\frac{dz}{dx}\).
As an example, here is an Op that squares its input:
square :: Num a =>Op'[a] a square =op1$ \x -> (x*x, \d -> 2 * d * x )
Remember that, generally, end users shouldn't directly construct Ops;
they should be provided by libraries or generated automatically.
op2 :: (a -> b -> (c, c -> (a, b))) -> Op '[a, b] c Source #
Create an Op of a function taking two inputs, by giving its explicit
gradient. The function should return a tuple containing the result of
the function, and also a function taking the derivative of the result
and return the derivative of the input.
If we have
\[ \eqalign{ f &: \mathbb{R}^2 \rightarrow \mathbb{R}\cr z &= f(x, y)\cr k &= g(z) } \]
Then the gradient \( \left< \frac{\partial k}{\partial x}, \frac{\partial k}{\partial y} \right> \) would be:
\[ \left< \frac{\partial k}{\partial x}, \frac{\partial k}{\partial y} \right> = \left< \frac{dk}{dz} \frac{\partial z}{dx}, \frac{dk}{dz} \frac{\partial z}{dy} \right> \]
If our Op represents \(f\), then the second item in the resulting
tuple should be a function that takes \(\frac{dk}{dz}\) and returns
\( \left< \frac{\partial k}{dx}, \frac{\partial k}{dx} \right> \).
As an example, here is an Op that multiplies its inputs:
mul :: Num a =>Op'[a, a] a mul =op2'$ \x y -> (x*y, \d -> (d*y, x*d) )
Remember that, generally, end users shouldn't directly construct Ops;
they should be provided by libraries or generated automatically.
From Isomorphisms
opTup :: Op as (Rec Identity as) Source #
An Op that takes as and returns exactly the input tuple.
>>>gradOp' opTup (1 :& 2 :& 3 :& RNil)(1 :& 2 :& 3 :& RNil, 1 :& 1 :& 1 :& RNil)
opIsoN :: (Rec Identity as -> b) -> (b -> Rec Identity as) -> Op as b Source #
An Op that runs the input value through an isomorphism between
a tuple of values and a value. See opIso for caveats.
In Numeric.Backprop.Op since version 0.1.2.0, but only exported from Numeric.Backprop since version 0.1.3.0.
Since: 0.1.2.0
No gradients
noGrad1 :: (a -> b) -> Op '[a] b Source #
Create an Op with no gradient. Can be evaluated with evalOp, but
will throw a runtime exception when asked for the gradient.
Can be used with BVar with liftOp1, and evalBP will work fine.
gradBP and backprop will also work fine if the result is never used
in the final answer, but will throw a runtime exception if the final
answer depends on the result of this operation.
Useful if your only API is exposed through backprop. Just be sure to tell your users that this will explode when finding the gradient if the result is used in the final result.
Since: 0.1.3.0
noGrad :: (Rec Identity as -> b) -> Op as b Source #
Create an Op with no gradient. Can be evaluated with evalOp, but
will throw a runtime exception when asked for the gradient.
Can be used with BVar with liftOp, and evalBP will work fine.
gradBP and backprop will also work fine if the result is never used
in the final answer, but will throw a runtime exception if the final
answer depends on the result of this operation.
Useful if your only API is exposed through backprop. Just be sure to tell your users that this will explode when finding the gradient if the result is used in the final result.
Since: 0.1.3.0
Utility
class Reifies (s :: k) a | s -> a #
Minimal complete definition
Instances
| KnownNat n => Reifies (n :: Nat) Integer | |
Defined in Data.Reflection | |
| KnownSymbol n => Reifies (n :: Symbol) String | |
Defined in Data.Reflection | |
| Reifies Z Int | |
Defined in Data.Reflection | |
| Reifies n Int => Reifies (D n :: Type) Int | |
Defined in Data.Reflection | |
| Reifies n Int => Reifies (PD n :: Type) Int | |
Defined in Data.Reflection | |
| Reifies n Int => Reifies (SD n :: Type) Int | |
Defined in Data.Reflection | |
| (B b0, B b1, B b2, B b3, B b4, B b5, B b6, B b7, w0 ~ W b0 b1 b2 b3, w1 ~ W b4 b5 b6 b7) => Reifies (Stable w0 w1 a :: Type) a | |
Defined in Data.Reflection | |