chainrules-core 0.2.0

Backend-agnostic JVP and VJP rule protocol for scientific Rust
Documentation
#![cfg(feature = "num-complex")]

use std::convert::Infallible;

use chainrules_core::testing::{
    assert_adjoint_identity, assert_close, directional_central_difference,
};
use chainrules_core::{Differentiable, JvpRule, Pullback, VjpRule};
use num_complex::Complex64;

fn real_pair(left: &Complex64, right: &Complex64) -> f64 {
    (left.conj() * right).re
}

fn vector_real_pair(left: &[Complex64; 2], right: &[Complex64; 2]) -> f64 {
    left.iter()
        .zip(right)
        .map(|(left, right)| real_pair(left, right))
        .sum()
}

struct ComplexScale {
    factor: Complex64,
}

struct ComplexScalePullback {
    adjoint_factor: Complex64,
}

impl JvpRule<Complex64> for ComplexScale {
    type Output = Complex64;
    type Error = Infallible;

    fn jvp(
        &self,
        argument: &Complex64,
        tangent: &Complex64,
    ) -> Result<(Complex64, Complex64), Self::Error> {
        Ok((self.factor * argument, self.factor * tangent))
    }
}

impl Pullback<Complex64, Complex64> for ComplexScalePullback {
    type Error = Infallible;

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

impl VjpRule<Complex64> for ComplexScale {
    type Output = Complex64;
    type Error = Infallible;
    type Pullback<'a> = ComplexScalePullback;

    fn vjp<'a>(
        &'a self,
        argument: &'a Complex64,
    ) -> Result<(Complex64, Self::Pullback<'a>), Self::Error> {
        Ok((
            self.factor * argument,
            ComplexScalePullback {
                adjoint_factor: self.factor.conj(),
            },
        ))
    }
}

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

    assert_space::<Complex64, Complex64, Complex64>();
    assert_space::<Vec<Complex64>, Vec<Complex64>, Vec<Complex64>>();
    assert_space::<[Complex64; 2], [Complex64; 2], [Complex64; 2]>();
}

#[test]
fn complex_rule_uses_the_documented_real_pairing() {
    let rule = ComplexScale {
        factor: Complex64::new(1.25, -0.75),
    };
    let argument = Complex64::new(-0.4, 1.1);
    let direction = Complex64::new(0.3, -0.2);
    let output_cotangent = Complex64::new(-1.4, 0.6);

    let (_, jvp) = rule.jvp(&argument, &direction).unwrap();
    let numerical = directional_central_difference(
        |offset| Ok::<_, Infallible>(rule.factor * (argument + offset * direction)),
        1.0e-6,
        |positive, negative, denominator| (positive - negative) / denominator,
    )
    .unwrap();
    assert_close((jvp - numerical).norm(), 0.0, 0.0, 1.0e-9);

    let (_, pullback) = rule.vjp(&argument).unwrap();
    let input_cotangent = pullback.apply(output_cotangent).unwrap();
    assert_adjoint_identity(
        &jvp,
        &output_cotangent,
        &direction,
        &input_cotangent,
        real_pair,
        real_pair,
        1.0e-12,
        1.0e-12,
    );
}

#[derive(Clone, Copy, Debug)]
struct Matrix2 {
    entries: [[Complex64; 2]; 2],
}

impl Matrix2 {
    fn solve(self, right: [Complex64; 2]) -> Result<[Complex64; 2], SolveError> {
        let [[a, b], [c, d]] = self.entries;
        let determinant = a * d - b * c;
        if determinant.norm() <= 1.0e-12 {
            return Err(SolveError::Singular);
        }
        Ok([
            (d * right[0] - b * right[1]) / determinant,
            (-c * right[0] + a * right[1]) / determinant,
        ])
    }

    fn adjoint(self) -> Self {
        let [[a, b], [c, d]] = self.entries;
        Self {
            entries: [[a.conj(), c.conj()], [b.conj(), d.conj()]],
        }
    }
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
enum SolveError {
    Singular,
}

struct Solve2 {
    matrix: Matrix2,
}

struct Solve2Pullback {
    adjoint: Matrix2,
}

impl JvpRule<[Complex64; 2]> for Solve2 {
    type Output = [Complex64; 2];
    type Error = SolveError;

    fn jvp(
        &self,
        right: &[Complex64; 2],
        tangent: &[Complex64; 2],
    ) -> Result<([Complex64; 2], [Complex64; 2]), Self::Error> {
        Ok((self.matrix.solve(*right)?, self.matrix.solve(*tangent)?))
    }
}

impl Pullback<[Complex64; 2], [Complex64; 2]> for Solve2Pullback {
    type Error = SolveError;

    fn apply(self, cotangent: [Complex64; 2]) -> Result<[Complex64; 2], Self::Error> {
        self.adjoint.solve(cotangent)
    }
}

impl VjpRule<[Complex64; 2]> for Solve2 {
    type Output = [Complex64; 2];
    type Error = SolveError;
    type Pullback<'a> = Solve2Pullback;

    fn vjp<'a>(
        &'a self,
        right: &'a [Complex64; 2],
    ) -> Result<([Complex64; 2], Self::Pullback<'a>), Self::Error> {
        Ok((
            self.matrix.solve(*right)?,
            Solve2Pullback {
                adjoint: self.matrix.adjoint(),
            },
        ))
    }
}

#[test]
fn fallible_complex_solve_rule_satisfies_finite_difference_and_duality() {
    let rule = Solve2 {
        matrix: Matrix2 {
            entries: [
                [Complex64::new(2.0, 0.5), Complex64::new(-0.25, 0.1)],
                [Complex64::new(0.4, -0.2), Complex64::new(1.5, -0.3)],
            ],
        },
    };
    let right = [Complex64::new(1.0, -0.2), Complex64::new(-0.5, 0.7)];
    let direction = [Complex64::new(0.3, 0.1), Complex64::new(-0.2, 0.4)];
    let output_cotangent = [Complex64::new(-0.8, 0.5), Complex64::new(0.25, -0.6)];

    let (_, jvp) = rule.jvp(&right, &direction).unwrap();
    let numerical = directional_central_difference(
        |offset| {
            rule.matrix.solve([
                right[0] + offset * direction[0],
                right[1] + offset * direction[1],
            ])
        },
        1.0e-6,
        |positive, negative, denominator| {
            [
                (positive[0] - negative[0]) / denominator,
                (positive[1] - negative[1]) / denominator,
            ]
        },
    )
    .unwrap();
    assert_close((jvp[0] - numerical[0]).norm(), 0.0, 0.0, 1.0e-9);
    assert_close((jvp[1] - numerical[1]).norm(), 0.0, 0.0, 1.0e-9);

    let (_, pullback) = rule.vjp(&right).unwrap();
    let input_cotangent = pullback.apply(output_cotangent).unwrap();
    assert_adjoint_identity(
        &jvp,
        &output_cotangent,
        &direction,
        &input_cotangent,
        vector_real_pair,
        vector_real_pair,
        1.0e-12,
        1.0e-12,
    );
}

#[test]
fn singular_solve_fails_in_forward_and_reverse_rule_construction() {
    let rule = Solve2 {
        matrix: Matrix2 {
            entries: [
                [Complex64::new(1.0, 0.0), Complex64::new(2.0, 0.0)],
                [Complex64::new(2.0, 0.0), Complex64::new(4.0, 0.0)],
            ],
        },
    };
    let right = [Complex64::new(1.0, 0.0), Complex64::new(0.0, 0.0)];

    assert_eq!(rule.jvp(&right, &right), Err(SolveError::Singular));
    assert!(matches!(rule.vjp(&right), Err(SolveError::Singular)));
}