Crate echidna

Expand description

§echidna

A high-performance automatic differentiation (AD) library for Rust.

echidna provides forward-mode, reverse-mode, bytecode-graph-mode, and Taylor-mode automatic differentiation. Write standard Rust numeric code and get exact derivatives automatically – no symbolic rewriting, no numerical finite differences.

§Examples

Compute the gradient of f(x, y) = x^2 + y^2:

let g = echidna::grad(|x: &[echidna::Reverse<f64>]| {
    x[0] * x[0] + x[1] * x[1]
}, &[3.0, 4.0]);
assert!((g[0] - 6.0).abs() < 1e-10);
assert!((g[1] - 8.0).abs() < 1e-10);

Forward-mode with Dual<f64>:

use echidna::{Dual, Float};

let x = Dual::new(2.0_f64, 1.0); // seed derivative = 1
let y = x.sin() + x * x;
assert!((y.eps - (2.0_f64.cos() + 4.0)).abs() < 1e-10);

§AD Modes

Mode	Type	Best for	Description
Forward	`Dual<F>`	Few inputs, many outputs	Propagates tangent vectors (JVP)
Reverse	`Reverse<F>`	Many inputs, few outputs	Adept-style two-stack tape, `Copy`, 12 bytes for f64
Bytecode tape	`BytecodeTape` + `BReverse<F>`	Record-once evaluate-many	Graph mode enabling Hessians, sparse derivatives, GPU acceleration, checkpointing. Requires `bytecode` feature.
Taylor	`Taylor<F, K>`	Higher-order derivatives	Univariate Taylor propagation. Requires `taylor` feature.
Batched forward	`DualVec<F, N>`	Vectorised Jacobians/Hessians	N tangent directions simultaneously

§Feature Flags

Feature	Default	Description
`simba`	yes	simba / approx trait integration
`bytecode`	no	`BytecodeTape` graph-mode AD
`parallel`	no	Rayon parallel evaluation (implies `bytecode`)
`taylor`	no	Taylor-mode AD (`Taylor<F, K>`, `TaylorDyn<F>`)
`laurent`	no	Laurent series for singularity analysis (implies `taylor`)
`stde`	no	Stochastic Taylor Derivative Estimators (implies `bytecode` + `taylor`)
`diffop`	no	Arbitrary differential operator evaluation via jet coefficients (implies `bytecode` + `taylor`)
`serde`	no	Serialization support via serde
`faer`	no	faer linear algebra integration (implies `bytecode`)
`nalgebra`	no	nalgebra linear algebra integration (implies `bytecode`)
`ndarray`	no	ndarray integration (implies `bytecode`)
`gpu-wgpu`	no	GPU acceleration via wgpu (implies `bytecode`)
`gpu-cuda`	no	GPU acceleration via CUDA (implies `bytecode`)

§Core Types

Always available:

Dual<F> – forward-mode dual number
Reverse<F> – reverse-mode AD variable
DualVec<F, N> – batched forward-mode (N tangent directions)
Scalar – trait for writing AD-generic code
Float – trait for underlying floating-point types
Type aliases: Dual64, Dual32, DualVec64, DualVec32, Reverse64, Reverse32

With bytecode:

BytecodeTape – recorded computation graph
BReverse<F> – reverse-mode variable for bytecode evaluation
CustomOp / CustomOpHandle – user-defined tape operations
Type aliases: BReverse64, BReverse32

With taylor:

Taylor<F, K> – fixed-order Taylor coefficients
TaylorDyn<F> – dynamic-order Taylor coefficients
Type aliases: Taylor64, Taylor32, TaylorDyn64, TaylorDyn32

With laurent:

Laurent<F, K> – Laurent series with negative-order terms

§Getting Started

Gradients: use grad() – it manages the reverse-mode tape automatically.
Jacobians: use jacobian() (forward mode) or sparse_jacobian() (sparse, requires bytecode).
Hessians: use hessian() or sparse_hessian() (requires bytecode).
AD-generic code: write functions as fn foo<T: Scalar>(x: T) -> T and they work with any AD type.
Tape reuse (performance): use record() to build a BytecodeTape, then call methods on it for repeated evaluation (requires bytecode).

Re-exports§

pub use api::grad;
pub use api::jacobian;
pub use api::jvp;
pub use api::vjp;
pub use dual::Dual;
pub use dual_vec::DualVec;
pub use float::Float;
pub use reverse::Reverse;
pub use scalar::Scalar;
pub use api::composed_hvp;bytecode
pub use api::hessian;bytecode
pub use api::hessian_vec;bytecode
pub use api::hvp;bytecode
pub use api::record;bytecode
pub use api::record_multi;bytecode
pub use api::sparse_hessian;bytecode
pub use api::sparse_hessian_vec;bytecode
pub use api::sparse_jacobian;bytecode
pub use breverse::BReverse;bytecode
pub use bytecode_tape::BytecodeTape;bytecode
pub use bytecode_tape::CustomOp;bytecode
pub use bytecode_tape::CustomOpHandle;bytecode
pub use checkpoint::grad_checkpointed;bytecode
pub use checkpoint::grad_checkpointed_disk;bytecode
pub use checkpoint::grad_checkpointed_online;bytecode
pub use checkpoint::grad_checkpointed_with_hints;bytecode
pub use nonsmooth::ClarkeError;bytecode
pub use nonsmooth::KinkEntry;bytecode
pub use nonsmooth::NonsmoothInfo;bytecode
pub use sparse::CsrPattern;bytecode
pub use sparse::JacobianSparsityPattern;bytecode
pub use sparse::SparsityPattern;bytecode
pub use laurent::Laurent;laurent
pub use taylor::Taylor;taylor
pub use taylor_dyn::TaylorArena;taylor
pub use taylor_dyn::TaylorDyn;taylor
pub use taylor_dyn::TaylorDynGuard;taylor

Modules§

api: Closure-based API for automatic differentiation.
breversebytecode: Bytecode-tape reverse-mode AD variable.
bytecode_tapebytecode: Bytecode tape for re-evaluable reverse-mode AD.
checkpointbytecode: Compositional gradient checkpointing for iterative computations.
cross_countrybytecode: Cross-country elimination for Jacobian computation.
diffopdiffop: Arbitrary differential operator evaluation via jet coefficients.
dual: Forward-mode dual numbers for automatic differentiation.
dual_vec: Batched forward-mode dual numbers with N tangent lanes.
faer_supportfaer: faer adapters for echidna’s bytecode tape AD.
float: The Float trait marking raw floating-point types usable as AD bases.
gpugpu-wgpu or gpu-cuda: GPU acceleration for batched tape evaluation.
laurentlaurent: Const-generic Laurent coefficient type: Laurent<F, K>.
nalgebra_supportnalgebra: nalgebra adapters for echidna’s bytecode tape AD.
ndarray_supportndarray: ndarray adapters for echidna’s bytecode tape AD.
nonsmoothbytecode: Nonsmooth extensions: branch tracking, kink detection, and Clarke subdifferential.
opcodebytecode: Bytecode opcodes for the bytecode tape.
reverse: Reverse-mode automatic differentiation via an Adept-style tape.
scalar: The Scalar trait for writing AD-generic numeric code.
sparsebytecode: Sparse derivative computation via structural sparsity detection and graph coloring.
stdestde: Stochastic Taylor Derivative Estimators (STDE).
tape: Adept-style two-stack tape for reverse-mode AD.
taylortaylor: Const-generic Taylor coefficient type: Taylor<F, K>.
taylor_dyntaylor: Dynamic (arena-based) Taylor coefficient type: TaylorDyn<F>.
taylor_opstaylor: Shared Taylor coefficient propagation functions.

Type Aliases§

BReverse32bytecode: Type alias for bytecode-tape reverse-mode variables over f32.
BReverse64bytecode: Type alias for bytecode-tape reverse-mode variables over f64.
Dual32: Type alias for forward-mode dual numbers over f32.
Dual64: Type alias for forward-mode dual numbers over f64.
DualVec32: Type alias for batched forward-mode dual numbers over f32.
DualVec64: Type alias for batched forward-mode dual numbers over f64.
Reverse32: Type alias for reverse-mode variables over f32.
Reverse64: Type alias for reverse-mode variables over f64.
Taylor32taylor: Type alias for Taylor coefficients over f32 with K coefficients.
Taylor64taylor: Type alias for Taylor coefficients over f64 with K coefficients.
TaylorDyn32taylor: Type alias for dynamic Taylor coefficients over f32.
TaylorDyn64taylor: Type alias for dynamic Taylor coefficients over f64.

Crate echidna

Crate echidna Copy item path

§echidna

§Examples

§AD Modes

§Feature Flags

§Core Types

§Getting Started

Re-exports§

Modules§

Type Aliases§

Crate echidna