ChainRules.rs
A small, backend-agnostic protocol for custom derivatives in scientific Rust.
ChainRules.rs lets scientific libraries publish efficient Jacobian-vector products (JVPs) and vector-Jacobian products (VJPs) without depending on a particular automatic-differentiation engine. AD backends can consume the same rules instead of every library-backend pair inventing its own integration.
[!IMPORTANT]
0.2is a foundational but still experimental protocol. It deliberately specifies only the semantics required to express correct first-order scientific rules. It is not an AD engine or a stable1.0compatibility commitment.
The normative semantics are in PROTOCOL.md. Existing users should read MIGRATION.md; release changes are summarized in CHANGELOG.md.
Why a shared rule protocol?
Scientific operations often have derivatives that should not be obtained by blindly differentiating their implementation. A linear solve should differentiate the mathematical solve and reuse factorization state rather than trace every low-level kernel. An eigensolver or implicit fixed point may also fail in either the primal or reverse computation.
The package that owns an operation has the knowledge needed to provide its
rule. An AD backend knows how to compose rules. chainrules-core is the narrow
interface between those responsibilities:
flowchart LR
S["Scientific library"]
C["chainrules-core<br/>spaces · JVP · VJP · Pullback"]
F["Forward-mode backend"]
R["Reverse-mode backend"]
S -->|publishes typed rules| C
C -->|consumed by| F
C -->|consumed by| R
The core crate does not record a computation graph, run an AD transform, choose an array ecosystem, or implement numerical solver derivatives.
Protocol surface
| Component | Purpose |
|---|---|
Differentiable |
Associates a primal with distinct tangent and cotangent representations |
JvpRule |
Evaluates a primal operation and propagates one input tangent |
VjpRule |
Evaluates a primal operation and constructs a one-shot pullback |
Pullback |
Maps an output cotangent to input cotangents |
NoTangent |
Marks a primal with no differentiable input space |
testing |
Closure-based directional finite differences and adjoint checks |
JVPs, VJPs, and pullbacks return Result with a downstream-defined error.
Pure algebraic rules use std::convert::Infallible. Pullbacks consume
themselves, allowing them to own and release expensive forward caches.
The crate supplies structural associations for real scalars, unit, pairs,
fixed arrays, and vectors. The optional num-complex feature adds
num_complex::Complex<T>.
Installation
[]
= "0.2"
For complex rules:
[]
= { = "0.2", = ["num-complex"] }
Example
use Infallible;
use ;
;
let = Square.jvp.unwrap;
assert_eq!;
let = Square.vjp.unwrap;
let input_cotangent = pullback.apply.unwrap;
assert_eq!;
Complex convention
For a real-valued objective, complex rules use the real pairing
<x, y>_R = Re(x† y).
For example, the pullback of y = A x is x_bar = A† y_bar. This convention
is part of the protocol and is exercised by the complex conformance tests.
Validating a rule
A numerical derivative rule should be checked independently by:
- comparing its JVP against a converged central directional difference; and
- checking the adjoint identity
<Jv, w>_output = <v, J*w>_input.
The testing module accepts closures for perturbation, differencing, and the
input/output pairings. Scientific arrays and structured parameters can
therefore use their native representations without making them dependencies of
chainrules-core.
Rules should also test primal failure, pullback failure, deterministic directions, ownership of retained caches, and mathematically non-differentiable cases. Finite differences are validation oracles, not production gradient implementations.
Design principles
- A narrow core. No matrix, tensor, solver, or AD framework is required.
- Explicit static dispatch. Rules are Rust trait implementations, not entries in a process-wide registry.
- Operation-aware derivatives. Rules differentiate the mathematical operation and may reuse domain-specific caches.
- Typed failure. Numerical failure is a
Result, not a panic or NaN. - Borrowing and ownership are explicit. Pullbacks may borrow primal inputs or own forward caches.
- Conservative growth. New protocol abstractions require evidence from multiple real rules or backends.
Non-goals
ChainRules.rs does not attempt to:
- implement an AD engine, tape, graph, optimizer, or compiler transform;
- standardize an array, matrix, tensor, or device-buffer ecosystem;
- provide a global runtime rule registry;
- standardize cotangent accumulation, flattening, or constrained projection;
- provide reusable or batched pullbacks;
- promise automatic higher-order differentiation;
- ship solver-, ODE-, eigensystem-, Green-function-, or domain-specific rules;
- reproduce the complete API or semantics of Julia ChainRules.
Relationship to Julia ChainRules
The project is inspired by the architectural idea behind ChainRules.jl: derivative rules should be reusable across AD systems. It is neither a source port nor an API-compatibility claim. Rust's trait coherence, ownership, lifetimes, and static dispatch require a Rust-native design.
Contributing
Before proposing a core abstraction, describe the concrete primal operation, tangent and cotangent representations, ownership model, failure paths, and JVP/VJP validation strategy. Domain-specific mathematics belongs in the scientific package unless multiple independent consumers demonstrate a common protocol requirement.
Every numerical rule should include directional finite-difference and adjoint-identity tests where both modes are available.
License
Licensed under the MIT License.