viva_math - v1.2.100

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.

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

add3

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

add_scalar

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

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

div

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

exp

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

exp3

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

gelu

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

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

mul

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

mul3

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

neg

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

pow

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

relu

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

scale

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

sigmoid

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

sin

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

sqrt

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

sub

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

tanh

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

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

var3_z

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