chainrules-core 0.2.0

Backend-agnostic JVP and VJP rule protocol for scientific Rust
Documentation
use std::cell::Cell;
use std::convert::Infallible;
use std::rc::Rc;

use chainrules_core::testing::{
    assert_adjoint_identity, assert_close, assert_scalar_adjoint_identity, central_difference,
    directional_central_difference,
};
use chainrules_core::{Differentiable, JvpRule, NoTangent, Pullback, VjpRule};

struct Square;

struct SquarePullback {
    x: f64,
}

impl JvpRule<f64> for Square {
    type Output = f64;
    type Error = Infallible;

    fn jvp(&self, x: &f64, tangent: &f64) -> Result<(f64, f64), Self::Error> {
        Ok((x * x, 2.0 * x * tangent))
    }
}

impl Pullback<f64, f64> for SquarePullback {
    type Error = Infallible;

    fn apply(self, cotangent: f64) -> Result<f64, Self::Error> {
        Ok(2.0 * self.x * cotangent)
    }
}

impl VjpRule<f64> for Square {
    type Output = f64;
    type Error = Infallible;
    type Pullback<'a> = SquarePullback;

    fn vjp<'a>(&'a self, x: &'a f64) -> Result<(f64, Self::Pullback<'a>), Self::Error> {
        Ok((x * x, SquarePullback { x: *x }))
    }
}

#[test]
fn infallible_rules_remain_ergonomic() {
    let x = 3.0;
    let direction = -0.25;
    let output_cotangent = 1.75;

    let (value, jvp) = Square.jvp(&x, &direction).unwrap();
    let numerical = central_difference(|argument| argument * argument, x, direction, 1.0e-5);
    assert_close(jvp, numerical, 1.0e-9, 1.0e-9);

    let (reverse_value, pullback) = Square.vjp(&x).unwrap();
    let input_cotangent = pullback.apply(output_cotangent).unwrap();
    assert_close(value, reverse_value, 0.0, 0.0);
    assert_scalar_adjoint_identity(jvp, output_cotangent, direction, input_cotangent, 1.0e-12);
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
enum ReciprocalError {
    ZeroInput,
    NonFiniteCotangent,
}

struct Reciprocal;

struct ReciprocalPullback {
    inverse_square: f64,
}

impl JvpRule<f64> for Reciprocal {
    type Output = f64;
    type Error = ReciprocalError;

    fn jvp(&self, x: &f64, tangent: &f64) -> Result<(f64, f64), Self::Error> {
        if *x == 0.0 {
            return Err(ReciprocalError::ZeroInput);
        }
        Ok((x.recip(), -tangent / (x * x)))
    }
}

impl Pullback<f64, f64> for ReciprocalPullback {
    type Error = ReciprocalError;

    fn apply(self, cotangent: f64) -> Result<f64, Self::Error> {
        if !cotangent.is_finite() {
            return Err(ReciprocalError::NonFiniteCotangent);
        }
        Ok(-cotangent * self.inverse_square)
    }
}

impl VjpRule<f64> for Reciprocal {
    type Output = f64;
    type Error = ReciprocalError;
    type Pullback<'a> = ReciprocalPullback;

    fn vjp<'a>(&'a self, x: &'a f64) -> Result<(f64, Self::Pullback<'a>), Self::Error> {
        if *x == 0.0 {
            return Err(ReciprocalError::ZeroInput);
        }
        Ok((
            x.recip(),
            ReciprocalPullback {
                inverse_square: (x * x).recip(),
            },
        ))
    }
}

#[test]
fn primal_and_pullback_failures_are_typed() {
    assert_eq!(Reciprocal.jvp(&0.0, &1.0), Err(ReciprocalError::ZeroInput));
    assert!(matches!(
        Reciprocal.vjp(&0.0),
        Err(ReciprocalError::ZeroInput)
    ));

    let (_, pullback) = Reciprocal.vjp(&2.0).unwrap();
    assert_eq!(
        pullback.apply(f64::NAN),
        Err(ReciprocalError::NonFiniteCotangent)
    );
}

struct BorrowingSquarePullback<'a> {
    x: &'a f64,
}

impl Pullback<f64, f64> for BorrowingSquarePullback<'_> {
    type Error = Infallible;

    fn apply(self, cotangent: f64) -> Result<f64, Self::Error> {
        Ok(2.0 * *self.x * cotangent)
    }
}

struct BorrowingSquare;

impl VjpRule<f64> for BorrowingSquare {
    type Output = f64;
    type Error = Infallible;
    type Pullback<'a> = BorrowingSquarePullback<'a>;

    fn vjp<'a>(&'a self, x: &'a f64) -> Result<(f64, Self::Pullback<'a>), Self::Error> {
        Ok((x * x, BorrowingSquarePullback { x }))
    }
}

#[test]
fn pullbacks_can_borrow_primal_inputs() {
    let x = 4.0;
    let (_, pullback) = BorrowingSquare.vjp(&x).unwrap();
    assert_close(pullback.apply(0.5).unwrap(), 4.0, 0.0, 0.0);
}

struct CacheGuard {
    drops: Rc<Cell<usize>>,
}

impl Drop for CacheGuard {
    fn drop(&mut self) {
        self.drops.set(self.drops.get() + 1);
    }
}

struct CachedPullback {
    scale: f64,
    _cache: CacheGuard,
}

impl Pullback<f64, f64> for CachedPullback {
    type Error = Infallible;

    fn apply(self, cotangent: f64) -> Result<f64, Self::Error> {
        Ok(self.scale * cotangent)
    }
}

#[test]
fn one_shot_pullback_releases_owned_cache_after_application() {
    let drops = Rc::new(Cell::new(0));
    let pullback = CachedPullback {
        scale: 2.0,
        _cache: CacheGuard {
            drops: Rc::clone(&drops),
        },
    };

    assert_close(pullback.apply(3.0).unwrap(), 6.0, 0.0, 0.0);
    assert_eq!(drops.get(), 1);
}

struct Parameters {
    value: f64,
}

struct ParameterDirection {
    value: f64,
}

#[derive(Debug, PartialEq)]
struct ParameterGradient {
    value: f64,
}

impl Differentiable for Parameters {
    type Tangent = ParameterDirection;
    type Cotangent = ParameterGradient;
}

struct ScaledParameter {
    scale: f64,
}

struct ScaledParameterPullback {
    scale: f64,
}

impl JvpRule<Parameters> for ScaledParameter {
    type Output = f64;
    type Error = Infallible;

    fn jvp(
        &self,
        parameters: &Parameters,
        tangent: &ParameterDirection,
    ) -> Result<(f64, f64), Self::Error> {
        Ok((self.scale * parameters.value, self.scale * tangent.value))
    }
}

impl Pullback<f64, ParameterGradient> for ScaledParameterPullback {
    type Error = Infallible;

    fn apply(self, cotangent: f64) -> Result<ParameterGradient, Self::Error> {
        Ok(ParameterGradient {
            value: self.scale * cotangent,
        })
    }
}

impl VjpRule<Parameters> for ScaledParameter {
    type Output = f64;
    type Error = Infallible;
    type Pullback<'a> = ScaledParameterPullback;

    fn vjp<'a>(
        &'a self,
        parameters: &'a Parameters,
    ) -> Result<(f64, Self::Pullback<'a>), Self::Error> {
        Ok((
            self.scale * parameters.value,
            ScaledParameterPullback { scale: self.scale },
        ))
    }
}

#[test]
fn tangent_and_cotangent_representations_can_differ() {
    let rule = ScaledParameter { scale: 3.0 };
    let parameters = Parameters { value: 2.0 };
    let direction = ParameterDirection { value: -0.5 };

    let (_, jvp) = rule.jvp(&parameters, &direction).unwrap();
    let (_, pullback) = rule.vjp(&parameters).unwrap();
    let gradient = pullback.apply(2.0).unwrap();

    assert_close(jvp, -1.5, 0.0, 0.0);
    assert_eq!(gradient, ParameterGradient { value: 6.0 });
}

#[test]
fn standard_product_associations_are_structural() {
    fn assert_space<Primal, Tangent, Cotangent>()
    where
        Primal: Differentiable<Tangent = Tangent, Cotangent = Cotangent>,
    {
    }

    assert_space::<(), NoTangent, NoTangent>();
    assert_space::<(f64, f32), (f64, f32), (f64, f32)>();
    assert_space::<[f64; 3], [f64; 3], [f64; 3]>();
    assert_space::<Vec<f64>, Vec<f64>, Vec<f64>>();
}

#[test]
fn generic_directional_difference_supports_vector_outputs() {
    let point = [1.5, -0.75];
    let direction = [0.25, 2.0];
    let derivative = directional_central_difference(
        |offset| {
            Ok::<_, Infallible>(vec![
                (point[0] + offset * direction[0]).powi(2),
                (point[1] + offset * direction[1]).sin(),
            ])
        },
        1.0e-5,
        |positive, negative, denominator| {
            positive
                .into_iter()
                .zip(negative)
                .map(|(left, right)| (left - right) / denominator)
                .collect::<Vec<_>>()
        },
    )
    .unwrap();

    assert_close(derivative[0], 2.0 * point[0] * direction[0], 1.0e-9, 1.0e-9);
    assert_close(derivative[1], point[1].cos() * direction[1], 1.0e-9, 1.0e-9);
}

#[test]
fn generic_adjoint_check_accepts_custom_pairings() {
    let input_tangent = vec![0.5, -2.0];
    let jvp = vec![4.5, -2.5];
    let output_cotangent = vec![1.25, -0.75];
    let input_cotangent = vec![3.0, -3.0];

    assert_adjoint_identity(
        &jvp,
        &output_cotangent,
        &input_tangent,
        &input_cotangent,
        |left, right| left.iter().zip(right).map(|(a, b)| a * b).sum(),
        |left, right| left.iter().zip(right).map(|(a, b)| a * b).sum(),
        1.0e-12,
        1.0e-12,
    );
}

#[test]
fn result_returning_closures_are_pullbacks() {
    let pullback = |cotangent: f64| Ok::<_, &'static str>(2.0 * cotangent);
    assert_close(pullback.apply(1.5).unwrap(), 3.0, 0.0, 0.0);
}