viva_math - v1.2.102

viva_math/autodiff

Forward-mode automatic differentiation via dual numbers.

A dual number a + b·ε (where ε² = 0) carries both a value and an infinitesimal derivative. Applying f to a Dual(x, 1) yields Dual(f(x), f'(x)) — exact gradients without symbolic manipulation or finite-difference truncation error.

When to use

For Vec3 gradients (gradient of a scalar field over PAD space), use Dual3 which carries three partials in parallel.

Example

import viva_math/autodiff as ad

// f(x) = sin(x²)
let x = ad.var(2.0)
let result = ad.sin(ad.mul(x, x))
// result.value ≈ sin(4) ≈ -0.756
// result.tangent = 2x · cos(x²) ≈ -2.614

References

Types

Dual

</>

A dual number value + tangent·ε.

value carries the function evaluation; tangent carries the directional derivative w.r.t. the independent variable.

pub type Dual {
  Dual(value: Float, tangent: Float)
}

Constructors 

  • Dual(value: Float, tangent: Float)

Dual3

</>

A dual number carrying three parallel partials. Use this to compute the gradient ∇f of a scalar field f: ℝ³ → ℝ at a point in one evaluation. 3-dimensional dual carrying a value and three partial derivatives (∂/∂x, ∂/∂y, ∂/∂z) — used by gradient3 to evaluate ∇f in one pass.

pub type Dual3 {
  Dual3(
    value: Float,
    partial_x: Float,
    partial_y: Float,
    partial_z: Float,
  )
}

Constructors 

  • Dual3(
  value: Float,
  partial_x: Float,
  partial_y: Float,
  partial_z: Float,
)

Values

add

</> 
pub fn add(a: Dual, b: Dual) -> Dual

(a + a'ε) + (b + b'ε) = (a+b) + (a'+b')ε.

add3

</> 
pub fn add3(a: Dual3, b: Dual3) -> Dual3

Component-wise sum lifted to Dual3.

add_scalar

</> 
pub fn add_scalar(a: Dual, s: Float) -> Dual

Add a constant — the tangent is unchanged (d/dx (x + c) = 1).

const3

</> 
pub fn const3(value: Float) -> Dual3

Treat value as a constant: all partials = 0.

constant

</> 
pub fn constant(value: Float) -> Dual

Constant dual: tangent = 0.

cos

</> 
pub fn cos(a: Dual) -> Dual

d/dx cos(x) = −sin(x).

div

</> 
pub fn div(a: Dual, b: Dual) -> Dual

(a + a'ε) / (b + b'ε) = a/b + ((a'b − ab')/b²)ε — quotient rule.

exp

</> 
pub fn exp(a: Dual) -> Dual

d/dx exp(x) = exp(x).

exp3

</> 
pub fn exp3(a: Dual3) -> Dual3

d/dx exp(x) = exp(x) lifted to Dual3.

gelu

</> 
pub fn gelu(a: Dual) -> Dual

GELU activation. GELU(x) = x·Φ(x) where Φ is the standard normal CDF. d/dx GELU(x) = Φ(x) + x·φ(x), with φ the standard normal PDF.

grad

</> 
pub fn grad(f: fn(Dual) -> Dual, x: Float) -> Float

Compute f’(x) at a point by lifting x to a dual.

gradient3

</> 
pub fn gradient3(
  f: fn(Dual3, Dual3, Dual3) -> Dual3,
  x: Float,
  y: Float,
  z: Float,
) -> #(Float, Float, Float)

Gradient ∇f at point (x, y, z).

jacobian

</> 
pub fn jacobian(
  f: fn(List(Dual)) -> List(Dual),
  point: List(Float),
) -> List(List(Float))

Generic n-d Jacobian via column-by-column forward AD. Given a function f: ℝⁿ → ℝᵐ represented as fn(Dual, ..., Dual) -> List(Dual), returns each row of the Jacobian by sweeping the unit tangent through each input.

This is the canonical forward-mode strategy: O(n) evaluations of f for a full Jacobian, optimal when n ≤ m.

lift1

</> 
pub fn lift1(
  d: Dual,
  f: fn(Float) -> Float,
  df: fn(Float) -> Float,
) -> Dual

Lift any unary function f together with its derivative f' to a dual.

ln

</> 
pub fn ln(a: Dual) -> Dual

d/dx ln(x) = 1/x. Caller must ensure a.value > 0.

mul

</> 
pub fn mul(a: Dual, b: Dual) -> Dual

(a + a'ε)(b + b'ε) = ab + (a'b + ab')ε — Leibniz product rule on duals.

mul3

</> 
pub fn mul3(a: Dual3, b: Dual3) -> Dual3

Product on Dual3 — Leibniz rule applied component-wise to each partial.

neg

</> 
pub fn neg(a: Dual) -> Dual

Negation: −(a + a'ε) = (−a) + (−a')ε.

pow

</> 
pub fn pow(a: Dual, n: Float) -> Dual

d/dx xⁿ = n·xⁿ⁻¹ (real exponent n).

relu

</> 
pub fn relu(a: Dual) -> Dual

ReLU activation. Derivative is 1 for x > 0 and 0 for x ≤ 0 (subgradient choice at the kink).

scale

</> 
pub fn scale(a: Dual, s: Float) -> Dual

Multiplication by a scalar constant (no tangent on the scalar).

sigmoid

</> 
pub fn sigmoid(a: Dual) -> Dual

d/dx σ(x) = σ(x)·(1 − σ(x)).

sin

</> 
pub fn sin(a: Dual) -> Dual

d/dx sin(x) = cos(x).

sqrt

</> 
pub fn sqrt(a: Dual) -> Dual

d/dx √x = 1 / (2·√x). Caller must ensure a.value > 0.

sub

</> 
pub fn sub(a: Dual, b: Dual) -> Dual

(a + a'ε) − (b + b'ε) = (a−b) + (a'−b')ε.

tanh

</> 
pub fn tanh(a: Dual) -> Dual

d/dx tanh(x) = 1 − tanh²(x).

value_and_grad

</> 
pub fn value_and_grad(
  f: fn(Dual) -> Dual,
  x: Float,
) -> #(Float, Float)

Compute both f(x) and f’(x) in a single pass.

var

</> 
pub fn var(value: Float) -> Dual

A dual number representing an independent variable. var(x) ↔ x + 1·ε so that ∂x/∂x = 1.

var3_x

</> 
pub fn var3_x(value: Float) -> Dual3

The independent variable x: ∂x/∂x = 1, others = 0.

var3_y

</> 
pub fn var3_y(value: Float) -> Dual3

The independent variable y: ∂y/∂y = 1, others = 0.

var3_z

</> 
pub fn var3_z(value: Float) -> Dual3

The independent variable z: ∂z/∂z = 1, others = 0.

✨ Search Document