chainrules-core 0.2.0

Backend-agnostic JVP and VJP rule protocol for scientific Rust
Documentation
# ChainRules.rs protocol

This document specifies the public semantics of `chainrules-core 0.2`.
The crate is a protocol for custom derivative rules. It is not an automatic
differentiation engine, a computation graph, or a numerical solver library.

## Primal values and differential spaces

For a primal type `P`, `Differentiable` associates two representations:

- `P::Tangent` is a forward perturbation consumed by a JVP;
- `P::Cotangent` is a reverse sensitivity produced by a pullback.

The representations may be identical, as they are for ordinary Euclidean
scalars, but their roles are distinct. Scientific types may use different
representations when forward perturbations and reverse accumulators have
different ownership, structure, or storage.

The protocol does not require tangent or cotangent types to implement a
particular algebra. Addition, zero allocation, flattening, device transfer, and
fan-out accumulation remain responsibilities of the consuming backend or the
scientific type.

## `NoTangent` and zero derivatives

`NoTangent` means that a primal has no differentiable input space. Typical
examples include indices, matrix shapes, sparsity patterns, solver choices,
random seeds, and discrete sectors.

It is not the same as a zero derivative. A zero derivative belongs to a
differential space that exists and should be represented by that tangent or
cotangent type. Version 0.2 intentionally does not standardize a shared lazy
zero representation. Backends may use an internal `Option<Cotangent>` or a
type-specific zero without imposing that choice on rule authors.

## JVP rules

For an operation `f` evaluated at `x`, a `JvpRule` computes

```text
y = f(x)
dy = J(x) dx
```

from a primal argument and one input tangent. The primal computation and
pushforward are fused so that an operation may share work between them.

JVP evaluation returns `Result`. Invalid arguments, numerical
non-convergence, singular derivatives, runtime failures, and mathematically
non-differentiable points must be represented by the rule's typed error rather
than a panic or a sentinel NaN.

## VJP rules and pullbacks

For an operation `f` evaluated at `x`, a `VjpRule` computes the primal output
and constructs a pullback. Applying the pullback to an output cotangent
computes

```text
dx_bar = J(x)* dy_bar
```

where `J(x)*` denotes the adjoint under the pairings chosen by the scientific
types.

Pullbacks are one-shot: `Pullback::apply` consumes `self`. This permits a
pullback to own a factorization, Krylov basis, checkpoint set, or device buffer
and release it after reverse evaluation. A pullback may borrow immutable
primal inputs through the generic associated type on `VjpRule`; caches created
during the forward computation may instead be owned by the pullback.

Both rule construction and pullback application return the same typed error at
the protocol boundary. A downstream error enum may record whether the failure
occurred in the primal or reverse stage.

## Complex differentiation

ChainRules.rs treats a complex program with a real-valued objective as a real
differentiable program. The canonical pairing for complex vectors and matrices
is

```text
<x, y>_R = Re(x† y).
```

Under this convention, the cotangent of the complex-linear map `y = A x` is
`x_bar = A† y_bar`. A rule and its tests must use the same convention; silently
mixing it with a bilinear transpose convention is an error.

The optional `num-complex` feature implements `Differentiable` for
`num_complex::Complex<T>`. Domain-specific matrix, state, parameter, and
subspace types should be local newtypes in the scientific package so that they
can define appropriate tangent and cotangent representations without requiring
matrix-library dependencies in `chainrules-core`.

## Mutation and aliasing

A rule describes the mathematical operation, not its instruction trace. An
implementation may use internal mutation, caller-owned buffers, caches, or
external numerical kernels. Those details are opaque to the protocol.

The rule author remains responsible for documenting aliasing requirements and
for ensuring that the primal result and derivative rule correspond to the same
mathematical operation. Version 0.2 does not define differentiation semantics
for arbitrary observable mutation.

## Non-differentiable and ill-conditioned points

Rules must return a typed error when a derivative is undefined or outside the
documented validity domain. Examples include rank changes, branch changes,
closed spectral gaps, singular implicit Jacobians, and failed adjoint solves.

Ill-conditioned but defined derivatives may be returned when the scientific
operation's contract permits them. Conditioning estimates, residuals, and
domain-specific diagnostics belong to the downstream output, pullback, or
error type rather than to `chainrules-core`.

## First-order guarantee

Version 0.2 specifies first-order JVP and VJP rules only. It does not promise
that a pullback can itself be differentiated by an AD backend. Higher-order
derivatives may be implemented by a downstream operation, by composing
first-order rules in a backend that understands them, or by a future protocol
extension driven by concrete workflows.

## Dispatch and coherence

Rules are ordinary Rust trait implementations on operation types. There is no
process-wide registry and no dynamic rule lookup.

Because of Rust's orphan rules, `chainrules-core` supplies associations for a
small set of common foreign types: real scalars, unit, pairs, fixed arrays,
vectors, and optionally `num_complex::Complex<T>`. It does not depend on array,
matrix, tensor, GPU, or AD frameworks. Scientific packages should use local
newtypes for domain-specific semantics.

## Conformance

Every numerical rule should be checked independently by:

1. comparing its JVP with a converged central directional difference on smooth
   cases; and
2. checking the adjoint identity

   ```text
   <Jv, w>_output = <v, J*w>_input.
   ```

The `testing` module accepts closures for perturbation, differencing, and
pairings. This keeps the protocol independent of any vector-space or tensor
trait hierarchy. Finite differences are validation oracles, not production
derivative implementations.

Tests should also cover primal failures, pullback failures, deterministic
directions, combined absolute/relative tolerances, and ownership of any
forward cache retained by the pullback.

## Explicit non-goals

`chainrules-core 0.2` does not provide:

- an AD tape, graph, transform, or optimizer;
- a global rule registry;
- a matrix, tensor, or device-array abstraction;
- cotangent accumulation or flattening;
- a generic projection-to-constraint protocol;
- reusable or batched pullbacks;
- batched JVPs, VJPs, Jacobians, Hessians, or HVPs;
- solver, eigensystem, ODE, KPM, Green-function, or domain-specific rules;
- Python, Julia, GPU, MPI, or AD-backend integration.

Those capabilities may be implemented downstream. A future core extension
requires concrete evidence that multiple rule authors or backends need the
same protocol-level abstraction.