xad-rs 0.1.1

//! `FReal` — active real for single-variable forward-mode AD.
//!
//! An [`FReal<T>`] carries both a value and a single scalar tangent
//! (the derivative with respect to one seeded input direction).
//! Propagation uses the chain rule applied pointwise at every operator;
//! there is no tape, no thread-local state, and the type is entirely
//! stack-allocated and `Copy`-able modulo the inner scalar's `Clone`.
//!
//! Forward single-variable mode is the cheapest AD mode in this crate —
//! operators compile to a handful of fmul/fadds — so it's the right
//! choice when you have **one input direction** (seed `derivative = 1`
//! on exactly one variable) and you don't need the multi-direction
//! batching that [`Dual`](crate::dual::Dual) provides.
//!
//! ```
//! use xad_rs::freal::FReal;
//!
//! // f(x) = x² + 3x, at x = 2
//! // f'(x) = 2x + 3 = 7
//! let x = FReal::new(2.0_f64, 1.0);   // value 2, tangent 1
//! let f = &x * &x + &x * 3.0;
//! assert_eq!(f.value(), 10.0);
//! assert_eq!(f.derivative(), 7.0);
//! ```
//!
//! For **many** directions in a single forward pass, use
//! [`Dual`](crate::dual::Dual) instead. For reverse mode, use
//! [`AReal`](crate::areal::AReal).

use crate::traits::Scalar;
use std::fmt;
use std::ops::{Add, AddAssign, Div, DivAssign, Mul, MulAssign, Neg, Sub, SubAssign};

/// Active real number for forward-mode AD.
///
/// Stores a value and its tangent (derivative with respect to a seed direction).
#[derive(Clone)]
pub struct FReal<T: Scalar> {
    value: T,
    derivative: T,
}

impl<T: Scalar> FReal<T> {
    /// Create a new FReal with the given value and derivative.
    pub fn new(value: T, derivative: T) -> Self {
        FReal { value, derivative }
    }

    /// Create an FReal with zero derivative (a constant).
    pub fn constant(value: T) -> Self {
        FReal {
            value,
            derivative: T::zero(),
        }
    }

    /// Get the underlying value.
    #[inline]
    pub fn value(&self) -> T {
        self.value
    }

    /// Set the underlying value.
    #[inline]
    pub fn set_value(&mut self, v: T) {
        self.value = v;
    }

    /// Get the derivative (tangent).
    #[inline]
    pub fn derivative(&self) -> T {
        self.derivative
    }

    /// Set the derivative (tangent).
    #[inline]
    pub fn set_derivative(&mut self, d: T) {
        self.derivative = d;
    }
}

impl<T: Scalar> From<T> for FReal<T> {
    fn from(value: T) -> Self {
        FReal::constant(value)
    }
}

impl From<i32> for FReal<f64> {
    fn from(value: i32) -> Self {
        FReal::constant(value as f64)
    }
}

impl From<i32> for FReal<f32> {
    fn from(value: i32) -> Self {
        FReal::constant(value as f32)
    }
}

// FReal + FReal
impl<T: Scalar> Add for FReal<T> {
    type Output = FReal<T>;
    #[inline]
    fn add(self, rhs: FReal<T>) -> FReal<T> {
        FReal {
            value: self.value + rhs.value,
            derivative: self.derivative + rhs.derivative,
        }
    }
}

impl<T: Scalar> Add for &FReal<T> {
    type Output = FReal<T>;
    #[inline]
    fn add(self, rhs: &FReal<T>) -> FReal<T> {
        FReal {
            value: self.value + rhs.value,
            derivative: self.derivative + rhs.derivative,
        }
    }
}

impl<T: Scalar> Add<&FReal<T>> for FReal<T> {
    type Output = FReal<T>;
    #[inline]
    fn add(self, rhs: &FReal<T>) -> FReal<T> {
        FReal {
            value: self.value + rhs.value,
            derivative: self.derivative + rhs.derivative,
        }
    }
}

impl<T: Scalar> Add<FReal<T>> for &FReal<T> {
    type Output = FReal<T>;
    #[inline]
    fn add(self, rhs: FReal<T>) -> FReal<T> {
        FReal {
            value: self.value + rhs.value,
            derivative: self.derivative + rhs.derivative,
        }
    }
}

// FReal + scalar
impl<T: Scalar> Add<T> for FReal<T> {
    type Output = FReal<T>;
    #[inline]
    fn add(self, rhs: T) -> FReal<T> {
        FReal {
            value: self.value + rhs,
            derivative: self.derivative,
        }
    }
}

impl<T: Scalar> Add<T> for &FReal<T> {
    type Output = FReal<T>;
    #[inline]
    fn add(self, rhs: T) -> FReal<T> {
        FReal {
            value: self.value + rhs,
            derivative: self.derivative,
        }
    }
}

// scalar + FReal
impl Add<FReal<f64>> for f64 {
    type Output = FReal<f64>;
    #[inline]
    fn add(self, rhs: FReal<f64>) -> FReal<f64> {
        FReal {
            value: self + rhs.value,
            derivative: rhs.derivative,
        }
    }
}

impl Add<&FReal<f64>> for f64 {
    type Output = FReal<f64>;
    #[inline]
    fn add(self, rhs: &FReal<f64>) -> FReal<f64> {
        FReal {
            value: self + rhs.value,
            derivative: rhs.derivative,
        }
    }
}

impl Add<FReal<f32>> for f32 {
    type Output = FReal<f32>;
    #[inline]
    fn add(self, rhs: FReal<f32>) -> FReal<f32> {
        FReal {
            value: self + rhs.value,
            derivative: rhs.derivative,
        }
    }
}

impl Add<&FReal<f32>> for f32 {
    type Output = FReal<f32>;
    #[inline]
    fn add(self, rhs: &FReal<f32>) -> FReal<f32> {
        FReal {
            value: self + rhs.value,
            derivative: rhs.derivative,
        }
    }
}

// FReal - FReal
impl<T: Scalar> Sub for FReal<T> {
    type Output = FReal<T>;
    #[inline]
    fn sub(self, rhs: FReal<T>) -> FReal<T> {
        FReal {
            value: self.value - rhs.value,
            derivative: self.derivative - rhs.derivative,
        }
    }
}

impl<T: Scalar> Sub for &FReal<T> {
    type Output = FReal<T>;
    #[inline]
    fn sub(self, rhs: &FReal<T>) -> FReal<T> {
        FReal {
            value: self.value - rhs.value,
            derivative: self.derivative - rhs.derivative,
        }
    }
}

impl<T: Scalar> Sub<&FReal<T>> for FReal<T> {
    type Output = FReal<T>;
    #[inline]
    fn sub(self, rhs: &FReal<T>) -> FReal<T> {
        FReal {
            value: self.value - rhs.value,
            derivative: self.derivative - rhs.derivative,
        }
    }
}

impl<T: Scalar> Sub<FReal<T>> for &FReal<T> {
    type Output = FReal<T>;
    #[inline]
    fn sub(self, rhs: FReal<T>) -> FReal<T> {
        FReal {
            value: self.value - rhs.value,
            derivative: self.derivative - rhs.derivative,
        }
    }
}

// FReal - scalar
impl<T: Scalar> Sub<T> for FReal<T> {
    type Output = FReal<T>;
    #[inline]
    fn sub(self, rhs: T) -> FReal<T> {
        FReal {
            value: self.value - rhs,
            derivative: self.derivative,
        }
    }
}

impl<T: Scalar> Sub<T> for &FReal<T> {
    type Output = FReal<T>;
    #[inline]
    fn sub(self, rhs: T) -> FReal<T> {
        FReal {
            value: self.value - rhs,
            derivative: self.derivative,
        }
    }
}

// scalar - FReal
impl Sub<FReal<f64>> for f64 {
    type Output = FReal<f64>;
    #[inline]
    fn sub(self, rhs: FReal<f64>) -> FReal<f64> {
        FReal {
            value: self - rhs.value,
            derivative: -rhs.derivative,
        }
    }
}

impl Sub<&FReal<f64>> for f64 {
    type Output = FReal<f64>;
    #[inline]
    fn sub(self, rhs: &FReal<f64>) -> FReal<f64> {
        FReal {
            value: self - rhs.value,
            derivative: -rhs.derivative,
        }
    }
}

impl Sub<FReal<f32>> for f32 {
    type Output = FReal<f32>;
    #[inline]
    fn sub(self, rhs: FReal<f32>) -> FReal<f32> {
        FReal {
            value: self - rhs.value,
            derivative: -rhs.derivative,
        }
    }
}

impl Sub<&FReal<f32>> for f32 {
    type Output = FReal<f32>;
    #[inline]
    fn sub(self, rhs: &FReal<f32>) -> FReal<f32> {
        FReal {
            value: self - rhs.value,
            derivative: -rhs.derivative,
        }
    }
}

// FReal * FReal
impl<T: Scalar> Mul for FReal<T> {
    type Output = FReal<T>;
    #[inline]
    fn mul(self, rhs: FReal<T>) -> FReal<T> {
        // d(a*b) = a'*b + a*b'
        FReal {
            value: self.value * rhs.value,
            derivative: self.derivative * rhs.value + self.value * rhs.derivative,
        }
    }
}

impl<T: Scalar> Mul for &FReal<T> {
    type Output = FReal<T>;
    #[inline]
    fn mul(self, rhs: &FReal<T>) -> FReal<T> {
        FReal {
            value: self.value * rhs.value,
            derivative: self.derivative * rhs.value + self.value * rhs.derivative,
        }
    }
}

impl<T: Scalar> Mul<&FReal<T>> for FReal<T> {
    type Output = FReal<T>;
    #[inline]
    fn mul(self, rhs: &FReal<T>) -> FReal<T> {
        FReal {
            value: self.value * rhs.value,
            derivative: self.derivative * rhs.value + self.value * rhs.derivative,
        }
    }
}

impl<T: Scalar> Mul<FReal<T>> for &FReal<T> {
    type Output = FReal<T>;
    #[inline]
    fn mul(self, rhs: FReal<T>) -> FReal<T> {
        FReal {
            value: self.value * rhs.value,
            derivative: self.derivative * rhs.value + self.value * rhs.derivative,
        }
    }
}

// FReal * scalar
impl<T: Scalar> Mul<T> for FReal<T> {
    type Output = FReal<T>;
    #[inline]
    fn mul(self, rhs: T) -> FReal<T> {
        FReal {
            value: self.value * rhs,
            derivative: self.derivative * rhs,
        }
    }
}

impl<T: Scalar> Mul<T> for &FReal<T> {
    type Output = FReal<T>;
    #[inline]
    fn mul(self, rhs: T) -> FReal<T> {
        FReal {
            value: self.value * rhs,
            derivative: self.derivative * rhs,
        }
    }
}

// scalar * FReal
impl Mul<FReal<f64>> for f64 {
    type Output = FReal<f64>;
    #[inline]
    fn mul(self, rhs: FReal<f64>) -> FReal<f64> {
        FReal {
            value: self * rhs.value,
            derivative: self * rhs.derivative,
        }
    }
}

impl Mul<&FReal<f64>> for f64 {
    type Output = FReal<f64>;
    #[inline]
    fn mul(self, rhs: &FReal<f64>) -> FReal<f64> {
        FReal {
            value: self * rhs.value,
            derivative: self * rhs.derivative,
        }
    }
}

impl Mul<FReal<f32>> for f32 {
    type Output = FReal<f32>;
    #[inline]
    fn mul(self, rhs: FReal<f32>) -> FReal<f32> {
        FReal {
            value: self * rhs.value,
            derivative: self * rhs.derivative,
        }
    }
}

impl Mul<&FReal<f32>> for f32 {
    type Output = FReal<f32>;
    #[inline]
    fn mul(self, rhs: &FReal<f32>) -> FReal<f32> {
        FReal {
            value: self * rhs.value,
            derivative: self * rhs.derivative,
        }
    }
}

// FReal / FReal
impl<T: Scalar> Div for FReal<T> {
    type Output = FReal<T>;
    #[inline]
    fn div(self, rhs: FReal<T>) -> FReal<T> {
        // d(a/b) = (a'*b - a*b') / b^2
        let inv_b = T::one() / rhs.value;
        FReal {
            value: self.value * inv_b,
            derivative: (self.derivative * rhs.value - self.value * rhs.derivative) * inv_b * inv_b,
        }
    }
}

impl<T: Scalar> Div for &FReal<T> {
    type Output = FReal<T>;
    #[inline]
    fn div(self, rhs: &FReal<T>) -> FReal<T> {
        let inv_b = T::one() / rhs.value;
        FReal {
            value: self.value * inv_b,
            derivative: (self.derivative * rhs.value - self.value * rhs.derivative) * inv_b * inv_b,
        }
    }
}

impl<T: Scalar> Div<&FReal<T>> for FReal<T> {
    type Output = FReal<T>;
    #[inline]
    fn div(self, rhs: &FReal<T>) -> FReal<T> {
        let inv_b = T::one() / rhs.value;
        FReal {
            value: self.value * inv_b,
            derivative: (self.derivative * rhs.value - self.value * rhs.derivative) * inv_b * inv_b,
        }
    }
}

impl<T: Scalar> Div<FReal<T>> for &FReal<T> {
    type Output = FReal<T>;
    #[inline]
    fn div(self, rhs: FReal<T>) -> FReal<T> {
        let inv_b = T::one() / rhs.value;
        FReal {
            value: self.value * inv_b,
            derivative: (self.derivative * rhs.value - self.value * rhs.derivative) * inv_b * inv_b,
        }
    }
}

// FReal / scalar
impl<T: Scalar> Div<T> for FReal<T> {
    type Output = FReal<T>;
    #[inline]
    fn div(self, rhs: T) -> FReal<T> {
        let inv = T::one() / rhs;
        FReal {
            value: self.value * inv,
            derivative: self.derivative * inv,
        }
    }
}

impl<T: Scalar> Div<T> for &FReal<T> {
    type Output = FReal<T>;
    #[inline]
    fn div(self, rhs: T) -> FReal<T> {
        let inv = T::one() / rhs;
        FReal {
            value: self.value * inv,
            derivative: self.derivative * inv,
        }
    }
}

// scalar / FReal
impl Div<FReal<f64>> for f64 {
    type Output = FReal<f64>;
    #[inline]
    fn div(self, rhs: FReal<f64>) -> FReal<f64> {
        let inv = 1.0 / rhs.value;
        FReal {
            value: self * inv,
            derivative: -self * rhs.derivative * inv * inv,
        }
    }
}

impl Div<&FReal<f64>> for f64 {
    type Output = FReal<f64>;
    #[inline]
    fn div(self, rhs: &FReal<f64>) -> FReal<f64> {
        let inv = 1.0 / rhs.value;
        FReal {
            value: self * inv,
            derivative: -self * rhs.derivative * inv * inv,
        }
    }
}

impl Div<FReal<f32>> for f32 {
    type Output = FReal<f32>;
    #[inline]
    fn div(self, rhs: FReal<f32>) -> FReal<f32> {
        let inv = 1.0 / rhs.value;
        FReal {
            value: self * inv,
            derivative: -self * rhs.derivative * inv * inv,
        }
    }
}

impl Div<&FReal<f32>> for f32 {
    type Output = FReal<f32>;
    #[inline]
    fn div(self, rhs: &FReal<f32>) -> FReal<f32> {
        let inv = 1.0 / rhs.value;
        FReal {
            value: self * inv,
            derivative: -self * rhs.derivative * inv * inv,
        }
    }
}

// Negation
impl<T: Scalar> Neg for FReal<T> {
    type Output = FReal<T>;
    #[inline]
    fn neg(self) -> FReal<T> {
        FReal {
            value: -self.value,
            derivative: -self.derivative,
        }
    }
}

impl<T: Scalar> Neg for &FReal<T> {
    type Output = FReal<T>;
    #[inline]
    fn neg(self) -> FReal<T> {
        FReal {
            value: -self.value,
            derivative: -self.derivative,
        }
    }
}

// Compound assignment
impl<T: Scalar> AddAssign for FReal<T> {
    fn add_assign(&mut self, rhs: FReal<T>) {
        self.value = self.value + rhs.value;
        self.derivative = self.derivative + rhs.derivative;
    }
}

impl<T: Scalar> AddAssign<&FReal<T>> for FReal<T> {
    fn add_assign(&mut self, rhs: &FReal<T>) {
        self.value = self.value + rhs.value;
        self.derivative = self.derivative + rhs.derivative;
    }
}

impl<T: Scalar> AddAssign<T> for FReal<T> {
    fn add_assign(&mut self, rhs: T) {
        self.value = self.value + rhs;
    }
}

impl<T: Scalar> SubAssign for FReal<T> {
    fn sub_assign(&mut self, rhs: FReal<T>) {
        self.value = self.value - rhs.value;
        self.derivative = self.derivative - rhs.derivative;
    }
}

impl<T: Scalar> SubAssign<&FReal<T>> for FReal<T> {
    fn sub_assign(&mut self, rhs: &FReal<T>) {
        self.value = self.value - rhs.value;
        self.derivative = self.derivative - rhs.derivative;
    }
}

impl<T: Scalar> SubAssign<T> for FReal<T> {
    fn sub_assign(&mut self, rhs: T) {
        self.value = self.value - rhs;
    }
}

impl<T: Scalar> MulAssign for FReal<T> {
    fn mul_assign(&mut self, rhs: FReal<T>) {
        let new_deriv = self.derivative * rhs.value + self.value * rhs.derivative;
        self.value = self.value * rhs.value;
        self.derivative = new_deriv;
    }
}

impl<T: Scalar> MulAssign<&FReal<T>> for FReal<T> {
    fn mul_assign(&mut self, rhs: &FReal<T>) {
        let new_deriv = self.derivative * rhs.value + self.value * rhs.derivative;
        self.value = self.value * rhs.value;
        self.derivative = new_deriv;
    }
}

impl<T: Scalar> MulAssign<T> for FReal<T> {
    fn mul_assign(&mut self, rhs: T) {
        self.value = self.value * rhs;
        self.derivative = self.derivative * rhs;
    }
}

impl<T: Scalar> DivAssign for FReal<T> {
    fn div_assign(&mut self, rhs: FReal<T>) {
        let inv_b = T::one() / rhs.value;
        self.derivative =
            (self.derivative * rhs.value - self.value * rhs.derivative) * inv_b * inv_b;
        self.value *= inv_b;
    }
}

impl<T: Scalar> DivAssign<&FReal<T>> for FReal<T> {
    fn div_assign(&mut self, rhs: &FReal<T>) {
        let inv_b = T::one() / rhs.value;
        self.derivative =
            (self.derivative * rhs.value - self.value * rhs.derivative) * inv_b * inv_b;
        self.value *= inv_b;
    }
}

impl<T: Scalar> DivAssign<T> for FReal<T> {
    fn div_assign(&mut self, rhs: T) {
        let inv = T::one() / rhs;
        self.value *= inv;
        self.derivative *= inv;
    }
}

// Comparison
impl<T: Scalar> PartialEq for FReal<T> {
    fn eq(&self, other: &Self) -> bool {
        self.value == other.value
    }
}

impl<T: Scalar> PartialEq<T> for FReal<T> {
    fn eq(&self, other: &T) -> bool {
        self.value == *other
    }
}

impl<T: Scalar> PartialOrd for FReal<T> {
    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
        self.value.partial_cmp(&other.value)
    }
}

impl<T: Scalar> PartialOrd<T> for FReal<T> {
    fn partial_cmp(&self, other: &T) -> Option<std::cmp::Ordering> {
        self.value.partial_cmp(other)
    }
}

impl<T: Scalar> fmt::Display for FReal<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.value)
    }
}

impl<T: Scalar> fmt::Debug for FReal<T> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "FReal({}, deriv={})", self.value, self.derivative)
    }
}

impl<T: Scalar> Default for FReal<T> {
    fn default() -> Self {
        FReal::constant(T::zero())
    }
}