Crate chainrules

Expand description

§chainrules

chainrules provides a shared scalar rule basis for Rust automatic differentiation crates.

It is designed for reusable scalar calculus, not for tapes, traced values, or tensor-specific execution engines. The crate focuses on stateless helpers that can be called from downstream AD runtimes and tensor libraries.

§What It Provides

stateless scalar primal helpers
stateless scalar foo_frule helpers
stateless scalar foo_rrule helpers
real/complex projection helpers for common scalar formulas

Supported scalar domains:

f32
f64
Complex32
Complex64

§Supported Functions

Current shipped scalar families:

arithmetic: add, sub, mul, div
powers and roots: powf, powi, sqrt
exponentials and logs: exp, expm1, log, log1p
trigonometric: sin, cos, asin, acos, atan
hyperbolic: sinh, cosh, tanh, asinh, acosh, atanh
Julia-compatible trigonometric helpers: sec, csc, cot, sinpi, cospi, sincospi, sind, cosd, tand
Julia-compatible hyperbolic helpers: sech, csch, coth
non-smooth real helpers: round, floor, ceil, sign, min, max
smooth helpers: cbrt, inv, exp2, exp10, log2, log10, hypot, pow, sincos, tan
complex and projection helpers: conj, abs, abs2, angle, real, imag, complex
real-valued binary helpers: atan2

This crate is a landing zone for scalar rules ported or adapted from Julia’s ChainRules.jl where they fit this crate boundary, but it is not a full port of ChainRules.jl.

§Validation

Rules in this crate are not accepted on provenance alone. They are checked with repository-local tests:

tests/scalarops_tests.rs covers direct formulas, edge cases, and smooth real/complex behavior
tests/julia_compat_trig_tests.rs covers Julia migration helpers, including landmark real inputs and representative Complex64 behavior
tests/nonsmooth_scalar_tests.rs covers the documented zero-gradient and tie-routing policies for non-smooth helpers
tests/complex_helper_tests.rs covers the projection helpers and complex constructor surface
tests/oracle_scalar_rules.rs replays vendored published oracle cases from ../../third_party/tensor-ad-oracles, with direct float64 replay and selected direct Complex64 replay for tan, exp2, and log2
complex forward-mode checks use the standard JVP convention on C ~= R^2 in repository-local formula tests such as tests/smooth_basis_tests.rs
complex reverse-mode checks remain conjugate-Wirtinger for real-valued losses

§Examples

use chainrules::{powf, powf_frule, powf_rrule};

let y = powf(2.0_f64, 3.0_f64);
assert_eq!(y, 8.0_f64);

let (y, dy) = powf_frule(2.0_f64, 3.0_f64, 1.0_f64);
assert_eq!(y, 8.0_f64);
assert_eq!(dy, 12.0_f64);

let dx = powf_rrule(2.0_f64, 3.0_f64, 1.0_f64);
assert_eq!(dx, 12.0_f64);

§Notes

This crate is the landing zone for shared scalar rule logic, including Julia-style convenience functions when they help migration.

It does not define tensor, array, broadcast, reduction, or engine-specific rules.

Structs§

NodeId: Stable identifier of an AD graph node.

Enums§

AutodiffError: AD-specific error type.
SavePolicy: Saved-tensor retention policy for reverse-mode rules.

Traits§

Differentiable: Trait defining the tangent space for a differentiable type.
ForwardRule: Forward-mode AD rule interface (frule).
ReverseRule: Reverse-mode AD rule interface (rrule).
ScalarAd: Scalar trait used by elementary AD rule helpers.

Functions§

abs: Primal abs.
abs2: Primal abs2.
abs2_frule: Forward rule for abs2.
abs2_rrule: Reverse rule for abs2.
acos: Primal acos.
acos_frule: Forward rule for acos.
acos_rrule: Reverse rule for acos.
acosh: Primal acosh.
acosh_frule: Forward rule for acosh.
acosh_rrule: Reverse rule for acosh.
add: Primal add.
add_frule: Forward rule for add.
add_rrule: Reverse rule for add.
angle: Primal angle.
angle_rrule: Reverse rule for angle.
asin: Primal asin.
asin_frule: Forward rule for asin.
asin_rrule: Reverse rule for asin.
asinh: Primal asinh.
asinh_frule: Forward rule for asinh.
asinh_rrule: Reverse rule for asinh.
atan: Primal atan.
atan2: Primal atan2(y, x) for ordered real scalars.
atan2_frule: Forward rule for atan2(y, x).
atan2_rrule: Reverse rule for atan2(y, x).
atan_frule: Forward rule for atan.
atan_rrule: Reverse rule for atan.
atanh: Primal atanh.
atanh_frule: Forward rule for atanh.
atanh_rrule: Reverse rule for atanh.
cbrt: Primal cbrt.
cbrt_frule: Forward rule for cbrt.
cbrt_rrule: Reverse rule for cbrt.
ceil: Primal ceil.
ceil_frule: Forward rule for ceil.
ceil_rrule: Reverse rule for ceil.
complex: Construct a complex number from real and imaginary parts.
conj: Primal conj.
conj_frule: Forward rule for conj.
conj_rrule: Reverse rule for conj.
cos: Primal cos.
cos_frule: Forward rule for cos.
cos_rrule: Reverse rule for cos.
cosd: Primal cosd.
cosd_frule: Forward rule for cosd.
cosd_rrule: Reverse rule for cosd.
cosh: Primal cosh.
cosh_frule: Forward rule for cosh.
cosh_rrule: Reverse rule for cosh.
cospi: Primal cospi.
cospi_frule: Forward rule for cospi.
cospi_rrule: Reverse rule for cospi.
cot: Primal cot.
cot_frule: Forward rule for cot.
cot_rrule: Reverse rule for cot.
coth: Primal coth.
coth_frule: Forward rule for coth.
coth_rrule: Reverse rule for coth.
csc: Primal csc.
csc_frule: Forward rule for csc.
csc_rrule: Reverse rule for csc.
csch: Primal csch.
csch_frule: Forward rule for csch.
csch_rrule: Reverse rule for csch.
div: Primal div.
div_frule: Forward rule for div.
div_rrule: Reverse rule for div.
exp: Primal exp.
exp2: Primal 2^x.
exp2_frule: Forward rule for 2^x.
exp2_rrule: Reverse rule for 2^x.
exp10: Primal 10^x.
exp10_frule: Forward rule for 10^x.
exp10_rrule: Reverse rule for 10^x.
exp_frule: Forward rule for exp.
exp_rrule: Reverse rule for exp.
expm1: Primal exp(x) - 1.
expm1_frule: Forward rule for exp(x) - 1.
expm1_rrule: Reverse rule for exp(x) - 1.
floor: Primal floor.
floor_frule: Forward rule for floor.
floor_rrule: Reverse rule for floor.
hypot: Primal hypot.
hypot_frule: Forward rule for hypot.
hypot_rrule: Reverse rule for hypot.
imag: Primal imag.
imag_rrule: Reverse rule for imag.
inv: Primal inv.
inv_frule: Forward rule for inv.
inv_rrule: Reverse rule for inv.
log: Primal log.
log2: Primal log2.
log1p: Primal log(1 + x).
log1p_frule: Forward rule for log(1 + x).
log1p_rrule: Reverse rule for log(1 + x).
log2_frule: Forward rule for log2.
log2_rrule: Reverse rule for log2.
log10: Primal log10.
log10_frule: Forward rule for log10.
log10_rrule: Reverse rule for log10.
log_frule: Forward rule for log.
log_rrule: Reverse rule for log.
max: Primal max.
max_frule: Forward rule for max.
max_rrule: Reverse rule for max.
min: Primal min.
min_frule: Forward rule for min.
min_rrule: Reverse rule for min.
mul: Primal mul.
mul_frule: Forward rule for mul.
mul_rrule: Reverse rule for mul.
pow: Primal pow(x, exponent).
pow_frule: Forward rule for pow(x, exponent).
pow_rrule: Reverse rule for pow(x, exponent).
powf: Primal powf.
powf_frule: Forward rule for powf with fixed exponent. Returns (primal, tangent).
powf_rrule: Reverse rule for powf with fixed exponent.
powi: Primal powi.
powi_frule: Forward rule for powi with fixed integer exponent. Returns (primal, tangent).
powi_rrule: Reverse rule for powi with fixed integer exponent.
real: Primal real.
real_rrule: Reverse rule for real.
round: Primal round.
round_frule: Forward rule for round.
round_rrule: Reverse rule for round.
sec: Primal sec.
sec_frule: Forward rule for sec.
sec_rrule: Reverse rule for sec.
sech: Primal sech.
sech_frule: Forward rule for sech.
sech_rrule: Reverse rule for sech.
sign: Primal sign.
sign_frule: Forward rule for sign.
sign_rrule: Reverse rule for sign.
sin: Primal sin.
sin_frule: Forward rule for sin.
sin_rrule: Reverse rule for sin.
sincos: Primal sincos.
sincos_frule: Forward rule for sincos.
sincos_rrule: Reverse rule for sincos.
sincospi: Primal sincospi.
sincospi_frule: Forward rule for sincospi.
sincospi_rrule: Reverse rule for sincospi.
sind: Primal sind.
sind_frule: Forward rule for sind.
sind_rrule: Reverse rule for sind.
sinh: Primal sinh.
sinh_frule: Forward rule for sinh.
sinh_rrule: Reverse rule for sinh.
sinpi: Primal sinpi.
sinpi_frule: Forward rule for sinpi.
sinpi_rrule: Reverse rule for sinpi.
sqrt: Primal sqrt.
sqrt_frule: Forward rule for sqrt.
sqrt_rrule: Reverse rule for sqrt.
sub: Primal sub.
sub_frule: Forward rule for sub.
sub_rrule: Reverse rule for sub.
tan: Primal tan.
tan_frule: Forward rule for tan.
tan_rrule: Reverse rule for tan.
tand: Primal tand.
tand_frule: Forward rule for tand.
tand_rrule: Reverse rule for tand.
tanh: Primal tanh.
tanh_frule: Forward rule for tanh.
tanh_rrule: Reverse rule for tanh.

Type Aliases§

AdResult: Result alias for AD APIs.
PullbackEntry: Reverse-rule pullback output entry (input_node, input_cotangent).
PullbackWithTangentsEntry: Reverse-rule pullback-with-tangents output entry.