A BVar s a is a value of type a 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 Lens' b a can be used to access an a inside a b, using ^^. (viewVar):

(^.) :: a -> Lens' a b -> b (^^.) :: BVar s a -> Lens' a b -> BVar s 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 #> :: BVar (L m n) -> BVar (R n) -> BVar (R m), which the user can then use to manipulate their BVars of L m ns and R ns, etc.

See Numeric.Backprop and documentation for liftOp for more information.

An ephemeral Wengert Tape in the environment. Used internally to track of the computational graph of variables.

For the end user, one can just imagine Reifies s W as a required constraint on s that allows backpropagation to work.

backprop, but with Num constraints instead of Backprop constraints.

See module documentation for Numeric.Backprop.Num for information on using this with tuples.

Turn a function BVar s a -> BVar s b into the function a -> b that it represents.

Benchmarks show that this should have virtually no overhead over directly writing a a -> b. BVar is, in this situation, a zero-cost abstraction, performance-wise.

See documentation of backprop for more information.

gradBP, but with Num constraints instead of Backprop constraints.

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

evalBP but with no arguments. Useful when everything is just given through constVar.

backprop2, but with Num constraints instead of Backprop constraints.

evalBP for a two-argument function. See backprop2 for notes.

gradBP2, but with Num constraints instead of Backprop constraints.

backpropWith2, but with Num constraints instead of Backprop constraints.

Note that argument order changed in v0.2.4.

Since: 0.2.0.0

backpropN, but with Num constraints instead of Backprop constraints.

The RPureConstrained Num as in the constraint says that every value in the type-level list as 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 AllPureConstrained Num as should be fulfilled automatically.

evalBP generalized to multiple inputs of different types. See documentation for backpropN for more details.

gradBPN, but with Num constraints instead of Backprop constraints.

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

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.

Shorter alias for constVar, inspired by the ad library.

Since: 0.2.0.0

Coerce a BVar contents. Useful for things like newtype wrappers.

Since: 0.1.5.2

^^., but with Num constraints instead of Backprop constraints.

.~~, but with Num constraints instead of Backprop constraints.

%~~, but with Num constraints instead of Backprop constraints.

Since: 0.2.4.0

^^?, 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 . iso tupT2 t2Tup :: Prism' c (T2 a b) 

^^.., but with Num constraints instead of Backprop constraints.

^^?!, but with Num constraints instead of Backprop constraints.

Like ^^?!, is *UNSAFE*.

Since: 0.2.1.0

viewVar, but with Num constraints instead of Backprop constraints.

setVar, but with Num constraints instead of Backprop constraints.

overVar, but with Num constraints instead of Backprop constraints.

Since: 0.2.4.0

sequenceVar, but with Num constraints instead of Backprop constraints.

Since v0.2.4, requires a Num constraint on t a.

collectVar, but with Num constraints instead of Backprop constraints.

Prior to v0.2.3, required a Num constraint on t a.

previewVar, but with Num constraints instead of Backprop constraints.

See documentation for ^^? for more information and important notes.

toListOfVar, but with Num constraints instead of Backprop constraints.

isoVar, but with Num constraints instead of Backprop constraints.

isoVar, but with Num constraints instead of Backprop constraints.

isoVar3, but with Num constraints instead of Backprop constraints.

isoVarN, but with Num constraints instead of Backprop constraints.

liftOp, but with Num constraints instead of Backprop constraints.

liftOp1, but with Num constraints instead of Backprop constraints.

liftOp2, but with Num constraints instead of Backprop constraints.

liftOp3, but with Num constraints instead of Backprop constraints.

An Op as a describes a differentiable function from as 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.

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'.

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) 

An Op that just returns whatever it receives. The identity function.

idOp = opIso id id 

bpOp, but with Num constraints instead of Backprop constraints.

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.

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.

Create an Op of a function taking three inputs, by giving its explicit gradient. See documentation for op2 for more details.

An Op that coerces an item into another item whose type has the same runtime representation.

>>> gradOp' opCoerce (Identity 5) :: (Int, Identity Int) (5, Identity 1) 

opCoerce = opIso coerced coerce 

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) 

An Op that runs the input value through an isomorphism.

Warning: This is unsafe! It assumes that the isomorphisms themselves have derivative 1, so will break for things like exp & log. Basically, don't use this for any "numeric" isomorphisms.

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

An Op that extracts a value from an input value using a Lens'.

Warning: This is unsafe! It assumes that it extracts a specific value unchanged, with derivative 1, so will break for things that numerically manipulate things before returning them.

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

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