Module dual 

Dual numbers for forward-mode automatic differentiation.

A dual number represents a value and its derivative simultaneously, enabling automatic computation of derivatives through operator overloading.

Mathematical Background

A dual number has the form a + a′·ε where ε² = 0 (and a′ denotes the derivative with respect to the seeded input). Arithmetic operations on dual numbers follow these algebraic rules:

• (a + a′·ε) + (b + b′·ε) = (a+b) + (a′+b′)·ε
• -(a + a′·ε) = -a + (-a′)·ε
• (a + a′·ε) - (b + b′·ε) = (a-b) + (a′-b′)·ε
• (a + a′·ε) * (b + b′·ε) = ab + (a′b + ab′)·ε
• 1/(b + b′·ε) = (1/b) + (-b′/b²)·ε
• (a + a′·ε) / (b + b′·ε) = (a + a′·ε) * (1/(b + b′·ε))

The chain rule emerges implicitly from composing these operations—you never write it down explicitly.

This is forward-mode automatic differentiation: we compute the derivative as we compute the function value.

Example

use autodiff::Dual;

// Compute f(x) = x² + 2x at x=3
let x = Dual::variable(3.0);  // x with derivative dx/dx = 1

let f = x * x + Dual::constant(2.0) * x;

assert_eq!(f.value, 15.0);    // f(3) = 9 + 6 = 15
assert_eq!(f.deriv, 8.0);     // f'(3) = 2*3 + 2 = 8

Reusable Functions

The idiomatic way to compute derivatives at multiple points is to write the function once and evaluate it with different seeds:

use autodiff::Dual;

// Define the function once
fn f(x: Dual<f64>) -> Dual<f64> {
    x * x + Dual::constant(2.0) * x
}

// Helper to evaluate f and f' at a point
fn eval_f_and_df(a: f64) -> (f64, f64) {
    let y = f(Dual::variable(a));
    (y.value, y.deriv)
}

// Evaluate at multiple points without rewriting the expression
let (v1, dv1) = eval_f_and_df(3.0);
assert_eq!(v1, 15.0);   // f(3) = 15
assert_eq!(dv1, 8.0);   // f'(3) = 8

let (v2, dv2) = eval_f_and_df(5.0);
assert_eq!(v2, 35.0);   // f(5) = 35
assert_eq!(dv2, 12.0);  // f'(5) = 12

Supported Operations

• Arithmetic: +, -, *, /, negation
• Transcendental: exp, ln, sin, cos, sqrt
• Derivatives propagate automatically; chain rule emerges from composition

Use Cases

• Computing derivatives of scalar functions
• Gradient-based optimization and neural networks
• Sensitivity analysis
• Physics simulations requiring derivatives

Structs

Dual

A dual number representing a value and its derivative.