echidna 0.9.0

A high-performance automatic differentiation library for Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145

//! The [`Float`] trait marking raw floating-point types usable as AD bases.
//!
//! Bundles `num_traits::Float`, `FloatConst`, `Copy`, `Send`, `Sync`, and other
//! utility traits. Implemented for `f32`, `f64`, and composed AD types.

use std::fmt::{Debug, Display};

use num_traits::{Float as NumFloat, FloatConst, FromPrimitive};

use crate::dual::Dual;
use crate::dual_vec::DualVec;
use crate::reverse::Reverse;
use crate::tape::TapeThreadLocal;

#[cfg(feature = "bytecode")]
use crate::breverse::BReverse;
#[cfg(feature = "bytecode")]
use crate::bytecode_tape::BtapeThreadLocal;

/// Marker trait for floating-point types that can serve as the base of AD computations.
///
/// Bundles the numeric and utility traits needed throughout echidna.
/// Implemented by primitive types (`f32`, `f64`) and by `Dual<F>`, which enables
/// nested forward-mode: `Dual<Dual<f64>>` for second-order derivatives.
pub trait Float:
    NumFloat
    + FloatConst
    + FromPrimitive
    + Copy
    + Send
    + Sync
    + Default
    + Debug
    + Display
    + IsAllZero
    + 'static
{
}

impl Float for f32 {}
impl Float for f64 {}
impl<F: Float> Float for Dual<F> {}
impl<F: Float, const N: usize> Float for DualVec<F, N> {}

#[cfg(feature = "taylor")]
impl<F: Float, const K: usize> Float for crate::taylor::Taylor<F, K> {}
#[cfg(feature = "taylor")]
impl<F: Float + crate::taylor_dyn::TaylorArenaLocal> Float for crate::taylor_dyn::TaylorDyn<F> {}

impl<F: Float + TapeThreadLocal> Float for Reverse<F> {}

#[cfg(feature = "bytecode")]
impl<F: Float + BtapeThreadLocal> Float for BReverse<F> {}

#[cfg(feature = "laurent")]
impl<F: Float, const K: usize> Float for crate::laurent::Laurent<F, K> {}

/// Checks whether all components (primal + tangent) are zero.
///
/// Used by `reverse_tangent` to safely skip zero adjoints without
/// incorrectly dropping tangent (eps) contributions. `PartialEq` only
/// compares `.re`, so a value with `re==0` but `eps!=0` would be
/// incorrectly pruned without this trait.
#[cfg_attr(not(feature = "bytecode"), allow(dead_code))]
#[doc(hidden)]
pub trait IsAllZero {
    fn is_all_zero(&self) -> bool;
}

impl IsAllZero for f32 {
    #[inline(always)]
    fn is_all_zero(&self) -> bool {
        *self == 0.0
    }
}

impl IsAllZero for f64 {
    #[inline(always)]
    fn is_all_zero(&self) -> bool {
        *self == 0.0
    }
}

impl<F: Float + IsAllZero> IsAllZero for Dual<F> {
    #[inline(always)]
    fn is_all_zero(&self) -> bool {
        // Use is_all_zero() recursively instead of == to correctly handle
        // nested types like Dual<Dual<f64>> where PartialEq ignores eps.
        self.re.is_all_zero() && self.eps.is_all_zero()
    }
}

impl<F: Float + IsAllZero, const N: usize> IsAllZero for DualVec<F, N> {
    #[inline(always)]
    fn is_all_zero(&self) -> bool {
        self.re.is_all_zero() && self.eps.iter().all(|e| e.is_all_zero())
    }
}

#[cfg(feature = "taylor")]
impl<F: Float, const K: usize> IsAllZero for crate::taylor::Taylor<F, K> {
    #[inline(always)]
    fn is_all_zero(&self) -> bool {
        self.coeffs.iter().all(|&c| c == F::zero())
    }
}

#[cfg(feature = "taylor")]
impl<F: Float + crate::taylor_dyn::TaylorArenaLocal> IsAllZero for crate::taylor_dyn::TaylorDyn<F> {
    #[inline(always)]
    fn is_all_zero(&self) -> bool {
        if self.value != F::zero() {
            return false;
        }
        if self.index == crate::taylor_dyn::CONSTANT {
            return true;
        }
        crate::taylor_dyn::with_active_arena(|arena: &mut crate::taylor_dyn::TaylorArena<F>| {
            arena.coeffs(self.index).iter().all(|&c| c == F::zero())
        })
    }
}

impl<F: Float + TapeThreadLocal> IsAllZero for Reverse<F> {
    #[inline(always)]
    fn is_all_zero(&self) -> bool {
        self.value == F::zero()
    }
}

#[cfg(feature = "bytecode")]
impl<F: Float + BtapeThreadLocal> IsAllZero for BReverse<F> {
    #[inline(always)]
    fn is_all_zero(&self) -> bool {
        self.value == F::zero()
    }
}

#[cfg(feature = "laurent")]
impl<F: Float, const K: usize> IsAllZero for crate::laurent::Laurent<F, K> {
    #[inline(always)]
    fn is_all_zero(&self) -> bool {
        self.is_all_zero_pub()
    }
}