Struct easy_ml::differentiation::Trace
source · pub struct Trace<T: Primitive> {
pub number: T,
pub derivative: T,
}
Expand description
A dual number which traces a real number and keeps track of its derivative. This is used to perform Forward Automatic Differentiation
Trace implements only first order differentiation. For example, given a function
3x2, you can use calculus to work out that its derivative with respect
to x is 6x. You can also take the derivative of 6x with respect to x and work out
that the second derivative is 6. By instead writing the function 3x2 in
code using Trace types as your numbers you can compute the first order derivative
for a given value of x by passing your function Trace { number: x, derivative: 1.0 }
.
use easy_ml::differentiation::Trace;
let x = Trace { number: 3.2, derivative: 1.0 };
let dx = Trace::constant(3.0) * x * x;
assert_eq!(dx.derivative, 3.2 * 6.0);
Why the one for the starting derivative? Because δx/δx = 1, as with symbolic differentiation.
§Acknowledgments
The wikipedia page on Automatic Differentiation provided a very useful overview and explanation for understanding Forward Mode Automatic Differentiation as well as the implementation rules.
Fields§
§number: T
The real number
derivative: T
The first order derivative of this number.
Implementations§
source§impl<T: Numeric + Primitive> Trace<T>
impl<T: Numeric + Primitive> Trace<T>
The main set of methods for using Trace types for Forward Differentiation.
The general steps are
- create one variable
- create as many constants as needed
- do operations on the variable and constants
- the outputs will have derivatives computed which can be accessed from
the
.derivative
field, with each derivative being the output with respect to the input variable. - if you need derivatives for a different input then do everything all over again or do them all in parallel
sourcepub fn constant(c: T) -> Trace<T>
pub fn constant(c: T) -> Trace<T>
Constants are lifted to Traces with a derivative of 0
Why zero for the starting derivative? Because for any constant C δC/δx = 0, as with symbolic differentiation.
sourcepub fn variable(x: T) -> Trace<T>
pub fn variable(x: T) -> Trace<T>
To lift a variable that you want to find the derivative of a function to, the Trace starts with a derivative of 1
Why the one for the starting derivative? Because δx/δx = 1, as with symbolic differentiation.
sourcepub fn derivative(function: impl FnOnce(Trace<T>) -> Trace<T>, x: T) -> T
pub fn derivative(function: impl FnOnce(Trace<T>) -> Trace<T>, x: T) -> T
Computes the derivative of a function with respect to its input x.
This is a shorthand for (function(Trace::variable(x))).derivative
In the more general case, if you provide a function with an input x and it returns N outputs y1 to yN then you have computed all the derivatives δyi/δx for i = 1 to N.
source§impl<T: Numeric + Primitive> Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<T: Numeric + Primitive> Trace<T>where
for<'a> &'a T: NumericRef<T>,
sourcepub fn unary(&self, fx: impl Fn(T) -> T, dfx_dx: impl Fn(T) -> T) -> Trace<T>
pub fn unary(&self, fx: impl Fn(T) -> T, dfx_dx: impl Fn(T) -> T) -> Trace<T>
Creates a new Trace from a reference to an existing Trace by applying some unary function to it which operates on the type the Trace wraps.
To compute the new trace, the unary function of some input x to some output y is needed along with its derivative with respect to its input x.
For example, tanh is a commonly used activation function, but the Real trait does not include this operation and Trace has no operations for it specifically. However, you can use this function to compute the tanh of a Trace like so:
use easy_ml::differentiation::Trace;
let x = Trace::variable(0.7f32);
// the derivative of tanh(x) is sech(x) * sech(x) which is equivalent to
// 1 / (cosh(x) * cosh(x))
let y = x.unary(|x| x.tanh(), |x| 1.0 / (x.cosh() * x.cosh()));
assert_eq!(y.derivative, 1.0f32 / (0.7f32.cosh() * 0.7f32.cosh()));
sourcepub fn binary(
&self,
rhs: &Trace<T>,
fxy: impl Fn(T, T) -> T,
dfxy_dx: impl Fn(T, T) -> T,
dfxy_dy: impl Fn(T, T) -> T
) -> Trace<T>
pub fn binary( &self, rhs: &Trace<T>, fxy: impl Fn(T, T) -> T, dfxy_dx: impl Fn(T, T) -> T, dfxy_dy: impl Fn(T, T) -> T ) -> Trace<T>
Creates a new Trace from a reference to two existing Traces by applying some binary function to them which operates on two arguments of the type the Traces wrap.
To compute the new trace, the binary function of some inputs x and y to some output z is needed along with its derivative with respect to its first input x and its derivative with respect to its second input y.
For example, atan2 takes two arguments, but the Real trait does not include this operation and Trace has no operations for it specifically. However, you can use this function to compute the atan2 of two Traces like so:
use easy_ml::differentiation::Trace;
let x = Trace::variable(3.0f32);
let y = Trace::variable(3.0f32);
// the derivative of atan2 with respect to x is y/(x*x + y*y)
// https://www.wolframalpha.com/input/?i=d%28atan2%28x%2Cy%29%29%2Fdx
// the derivative of atan2 with respect to y is -x/(x*x + y*y)
// https://www.wolframalpha.com/input/?i=d%28atan2%28x%2Cy%29%29%2Fdy
let z = x.binary(&y,
|x, y| x.atan2(y),
|x, y| y/((x*x) + (y*y)),
|x, y| -x/((x*x) + (y*y))
);
Trait Implementations§
source§impl<T: Numeric + Primitive> Add<&T> for &Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<T: Numeric + Primitive> Add<&T> for &Trace<T>where
for<'a> &'a T: NumericRef<T>,
Addition for a trace and a constant of the same type with both referenced.
source§impl<T: Numeric + Primitive> Add<&T> for Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<T: Numeric + Primitive> Add<&T> for Trace<T>where
for<'a> &'a T: NumericRef<T>,
Operation for a trace and a constant of the same type with the right referenced.
source§impl<'l, 'r, T: Numeric + Primitive> Add<&'r Trace<T>> for &'l Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<'l, 'r, T: Numeric + Primitive> Add<&'r Trace<T>> for &'l Trace<T>where
for<'a> &'a T: NumericRef<T>,
Addition for two traces of the same type with both referenced.
source§impl<T: Numeric + Primitive> Add<&Trace<T>> for Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<T: Numeric + Primitive> Add<&Trace<T>> for Trace<T>where
for<'a> &'a T: NumericRef<T>,
Operation for two traces of the same type with the right referenced.
source§impl<T: Numeric + Primitive> Add<T> for &Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<T: Numeric + Primitive> Add<T> for &Trace<T>where
for<'a> &'a T: NumericRef<T>,
Operation for a trace and a constant of the same type with the left referenced.
source§impl<T: Numeric + Primitive> Add<T> for Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<T: Numeric + Primitive> Add<T> for Trace<T>where
for<'a> &'a T: NumericRef<T>,
Operation for a trace and a constant of the same type.
source§impl<T: Numeric + Primitive> Add<Trace<T>> for &Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<T: Numeric + Primitive> Add<Trace<T>> for &Trace<T>where
for<'a> &'a T: NumericRef<T>,
Operation for two traces of the same type with the left referenced.
source§impl<T: Numeric + Primitive> Add for Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<T: Numeric + Primitive> Add for Trace<T>where
for<'a> &'a T: NumericRef<T>,
Operation for two traces of the same type.
source§impl<T: Display + Primitive> Display for Trace<T>
impl<T: Display + Primitive> Display for Trace<T>
A trace is displayed by showing its number component.
source§impl<T: Numeric + Primitive> Div<&T> for &Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<T: Numeric + Primitive> Div<&T> for &Trace<T>where
for<'a> &'a T: NumericRef<T>,
Dvision for a trace and a constant of the same type with both referenced.
source§impl<T: Numeric + Primitive> Div<&T> for Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<T: Numeric + Primitive> Div<&T> for Trace<T>where
for<'a> &'a T: NumericRef<T>,
Operation for a trace and a constant of the same type with the right referenced.
source§impl<'l, 'r, T: Numeric + Primitive> Div<&'r Trace<T>> for &'l Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<'l, 'r, T: Numeric + Primitive> Div<&'r Trace<T>> for &'l Trace<T>where
for<'a> &'a T: NumericRef<T>,
Division for two referenced traces of the same type.
source§impl<T: Numeric + Primitive> Div<&Trace<T>> for Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<T: Numeric + Primitive> Div<&Trace<T>> for Trace<T>where
for<'a> &'a T: NumericRef<T>,
Operation for two traces of the same type with the right referenced.
source§impl<T: Numeric + Primitive> Div<T> for &Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<T: Numeric + Primitive> Div<T> for &Trace<T>where
for<'a> &'a T: NumericRef<T>,
Operation for a trace and a constant of the same type with the left referenced.
source§impl<T: Numeric + Primitive> Div<T> for Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<T: Numeric + Primitive> Div<T> for Trace<T>where
for<'a> &'a T: NumericRef<T>,
Operation for a trace and a constant of the same type.
source§impl<T: Numeric + Primitive> Div<Trace<T>> for &Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<T: Numeric + Primitive> Div<Trace<T>> for &Trace<T>where
for<'a> &'a T: NumericRef<T>,
Operation for two traces of the same type with the left referenced.
source§impl<T: Numeric + Primitive> Div for Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<T: Numeric + Primitive> Div for Trace<T>where
for<'a> &'a T: NumericRef<T>,
Operation for two traces of the same type.
source§impl<T: Numeric + Real + Primitive> Exp for &Trace<T>
impl<T: Numeric + Real + Primitive> Exp for &Trace<T>
Exponential, ie ex of a Trace by reference.
source§impl<T: Numeric + Real + Primitive> Ln for &Trace<T>
impl<T: Numeric + Real + Primitive> Ln for &Trace<T>
Natural logarithm, ie ln(x) of a Trace by reference.
source§impl<T: Numeric + Primitive> Mul<&T> for &Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<T: Numeric + Primitive> Mul<&T> for &Trace<T>where
for<'a> &'a T: NumericRef<T>,
Multiplication for a trace and a constant of the same type with both referenced.
source§impl<T: Numeric + Primitive> Mul<&T> for Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<T: Numeric + Primitive> Mul<&T> for Trace<T>where
for<'a> &'a T: NumericRef<T>,
Operation for a trace and a constant of the same type with the right referenced.
source§impl<'l, 'r, T: Numeric + Primitive> Mul<&'r Trace<T>> for &'l Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<'l, 'r, T: Numeric + Primitive> Mul<&'r Trace<T>> for &'l Trace<T>where
for<'a> &'a T: NumericRef<T>,
Multiplication for two referenced traces of the same type.
source§impl<T: Numeric + Primitive> Mul<&Trace<T>> for Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<T: Numeric + Primitive> Mul<&Trace<T>> for Trace<T>where
for<'a> &'a T: NumericRef<T>,
Operation for two traces of the same type with the right referenced.
source§impl<T: Numeric + Primitive> Mul<T> for &Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<T: Numeric + Primitive> Mul<T> for &Trace<T>where
for<'a> &'a T: NumericRef<T>,
Operation for a trace and a constant of the same type with the left referenced.
source§impl<T: Numeric + Primitive> Mul<T> for Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<T: Numeric + Primitive> Mul<T> for Trace<T>where
for<'a> &'a T: NumericRef<T>,
Operation for a trace and a constant of the same type.
source§impl<T: Numeric + Primitive> Mul<Trace<T>> for &Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<T: Numeric + Primitive> Mul<Trace<T>> for &Trace<T>where
for<'a> &'a T: NumericRef<T>,
Operation for two traces of the same type with the left referenced.
source§impl<T: Numeric + Primitive> Mul for Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<T: Numeric + Primitive> Mul for Trace<T>where
for<'a> &'a T: NumericRef<T>,
Operation for two traces of the same type.
source§impl<T: Numeric + Primitive> Neg for &Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<T: Numeric + Primitive> Neg for &Trace<T>where
for<'a> &'a T: NumericRef<T>,
Negation for a referenced Trace of some type.
source§impl<T: Numeric + Primitive> Neg for Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<T: Numeric + Primitive> Neg for Trace<T>where
for<'a> &'a T: NumericRef<T>,
Negation for a Trace by value of some type.
source§impl<T: PartialEq + Primitive> PartialEq for Trace<T>
impl<T: PartialEq + Primitive> PartialEq for Trace<T>
Any trace of a PartialEq type implements PartialEq
Note that as a Trace is intended to be substitutable with its type T only the number parts of the trace are compared. Hence the following is true
use easy_ml::differentiation::Trace;
assert_eq!(Trace { number: 0, derivative: 1 }, Trace { number: 0, derivative: 2 })
source§impl<T: PartialOrd + Primitive> PartialOrd for Trace<T>
impl<T: PartialOrd + Primitive> PartialOrd for Trace<T>
Any trace of a PartialOrd type implements PartialOrd
Note that as a Trace is intended to be substitutable with its type T only the number parts of the trace are compared. Hence the following is true
use easy_ml::differentiation::Trace;
assert!(Trace { number: 1, derivative: 1 } > Trace { number: 0, derivative: 2 })
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl<T: Numeric + Real + Primitive> Pow<&T> for &Trace<T>
impl<T: Numeric + Real + Primitive> Pow<&T> for &Trace<T>
Power of a trace to a constant of the same type with both referenced.
source§impl<T: Numeric + Real + Primitive> Pow<&T> for Trace<T>
impl<T: Numeric + Real + Primitive> Pow<&T> for Trace<T>
Operation for a trace and a constant of the same type with the right referenced.
source§impl<T: Numeric + Real + Primitive> Pow<&Trace<T>> for &T
impl<T: Numeric + Real + Primitive> Pow<&Trace<T>> for &T
Power of a constant to a trace of the same type with both referenced.
source§impl<'l, 'r, T: Numeric + Real + Primitive> Pow<&'r Trace<T>> for &'l Trace<T>
impl<'l, 'r, T: Numeric + Real + Primitive> Pow<&'r Trace<T>> for &'l Trace<T>
Power of one Trace to another, ie self^rhs for two traces of the same type with both referenced.
source§impl<T: Numeric + Real + Primitive> Pow<&Trace<T>> for T
impl<T: Numeric + Real + Primitive> Pow<&Trace<T>> for T
Operation for a trace and a constant of the same type with the right referenced.
source§impl<T: Numeric + Real + Primitive> Pow<&Trace<T>> for Trace<T>
impl<T: Numeric + Real + Primitive> Pow<&Trace<T>> for Trace<T>
Operation for two traces of the same type with the right referenced.
source§impl<T: Numeric + Real + Primitive> Pow<T> for &Trace<T>
impl<T: Numeric + Real + Primitive> Pow<T> for &Trace<T>
Operation for a trace and a constant of the same type with the left referenced.
source§impl<T: Numeric + Real + Primitive> Pow<T> for Trace<T>
impl<T: Numeric + Real + Primitive> Pow<T> for Trace<T>
Operation for a trace and a constant of the same type.
source§impl<T: Numeric + Real + Primitive> Pow<Trace<T>> for &T
impl<T: Numeric + Real + Primitive> Pow<Trace<T>> for &T
Operation for a trace and a constant of the same type with the left referenced.
source§impl<T: Numeric + Real + Primitive> Pow<Trace<T>> for &Trace<T>
impl<T: Numeric + Real + Primitive> Pow<Trace<T>> for &Trace<T>
Operation for two traces of the same type with the left referenced.
source§impl<T: Numeric + Real + Primitive> Pow<Trace<T>> for T
impl<T: Numeric + Real + Primitive> Pow<Trace<T>> for T
Operation for a trace and a constant of the same type.
source§impl<T: Numeric + Real + Primitive> Pow for Trace<T>
impl<T: Numeric + Real + Primitive> Pow for Trace<T>
Operation for two traces of the same type.
source§impl<T: Numeric + Primitive> Sub<&T> for &Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<T: Numeric + Primitive> Sub<&T> for &Trace<T>where
for<'a> &'a T: NumericRef<T>,
Subtraction for a trace and a constant of the same type with both referenced.
source§impl<T: Numeric + Primitive> Sub<&T> for Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<T: Numeric + Primitive> Sub<&T> for Trace<T>where
for<'a> &'a T: NumericRef<T>,
Operation for a trace and a constant of the same type with the right referenced.
source§impl<'l, 'r, T: Numeric + Primitive> Sub<&'r Trace<T>> for &'l Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<'l, 'r, T: Numeric + Primitive> Sub<&'r Trace<T>> for &'l Trace<T>where
for<'a> &'a T: NumericRef<T>,
Subtraction for two referenced traces of the same type.
source§impl<T: Numeric + Primitive> Sub<&Trace<T>> for Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<T: Numeric + Primitive> Sub<&Trace<T>> for Trace<T>where
for<'a> &'a T: NumericRef<T>,
Operation for two traces of the same type with the right referenced.
source§impl<T: Numeric + Primitive> Sub<T> for &Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<T: Numeric + Primitive> Sub<T> for &Trace<T>where
for<'a> &'a T: NumericRef<T>,
Operation for a trace and a constant of the same type with the left referenced.
source§impl<T: Numeric + Primitive> Sub<T> for Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<T: Numeric + Primitive> Sub<T> for Trace<T>where
for<'a> &'a T: NumericRef<T>,
Operation for a trace and a constant of the same type.
source§impl<T: Numeric + Primitive> Sub<Trace<T>> for &Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<T: Numeric + Primitive> Sub<Trace<T>> for &Trace<T>where
for<'a> &'a T: NumericRef<T>,
Operation for two traces of the same type with the left referenced.
source§impl<T: Numeric + Primitive> Sub for Trace<T>where
for<'a> &'a T: NumericRef<T>,
impl<T: Numeric + Primitive> Sub for Trace<T>where
for<'a> &'a T: NumericRef<T>,
Operation for two traces of the same type.
source§impl<T: Numeric + Primitive> Sum for Trace<T>
impl<T: Numeric + Primitive> Sum for Trace<T>
Any trace of a Numeric type implements Sum, which is the same as adding a bunch of Trace types together.
source§impl<T: Numeric + Primitive> ZeroOne for Trace<T>
impl<T: Numeric + Primitive> ZeroOne for Trace<T>
Trace implements ZeroOne by returning constants.
impl<T: Copy + Primitive> Copy for Trace<T>
Any trace of a Copy type implements Copy