# ChainRules.rs
[](https://github.com/matrixlab-research/ChainRules.rs/actions/workflows/ci.yml)
[](https://crates.io/crates/chainrules-core)
[](https://docs.rs/chainrules-core)
[](https://www.rust-lang.org/)
[](LICENSE)
**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.2` is 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 stable `1.0` compatibility
> commitment.
The normative semantics are in [PROTOCOL.md](PROTOCOL.md). Existing users
should read [MIGRATION.md](MIGRATION.md); release changes are summarized in
[CHANGELOG.md](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:
```mermaid
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
| `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
```toml
[dependencies]
chainrules-core = "0.2"
```
For complex rules:
```toml
[dependencies]
chainrules-core = { version = "0.2", features = ["num-complex"] }
```
## Example
```rust
use std::convert::Infallible;
use chainrules_core::{JvpRule, Pullback, VjpRule};
struct Square;
struct SquarePullback {
x: f64,
}
impl JvpRule<f64> for Square {
type Output = f64;
type Error = Infallible;
fn jvp(&self, x: &f64, dx: &f64) -> Result<(f64, f64), Self::Error> {
Ok((x * x, 2.0 * x * dx))
}
}
impl Pullback<f64, f64> for SquarePullback {
type Error = Infallible;
fn apply(self, output_cotangent: f64) -> Result<f64, Self::Error> {
Ok(2.0 * self.x * output_cotangent)
}
}
impl VjpRule<f64> for Square {
type Output = f64;
type Error = Infallible;
type Pullback<'a> = SquarePullback;
fn vjp<'a>(
&'a self,
x: &'a f64,
) -> Result<(f64, Self::Pullback<'a>), Self::Error> {
Ok((x * x, SquarePullback { x: *x }))
}
}
let (value, jvp) = Square.jvp(&3.0, &0.5).unwrap();
assert_eq!((value, jvp), (9.0, 3.0));
let (value, pullback) = Square.vjp(&3.0).unwrap();
let input_cotangent = pullback.apply(0.5).unwrap();
assert_eq!((value, input_cotangent), (9.0, 3.0));
```
## Complex convention
For a real-valued objective, complex rules use the real pairing
```text
<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:
1. comparing its JVP against a converged central directional difference; and
2. 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](https://github.com/JuliaDiff/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](LICENSE).