chainrules-core 0.2.0

Backend-agnostic JVP and VJP rule protocol for scientific Rust
Documentation
# Migrating from 0.1 to 0.2

`chainrules-core 0.2` deliberately breaks the experimental 0.1 traits to make
scientific rules precise about tangent direction, reverse sensitivities,
failure, and pullback ownership.

## `Differentiable` has a cotangent association

Version 0.1:

```rust
impl Differentiable for Parameters {
    type Tangent = ParameterDirection;
}
```

Version 0.2:

```rust
impl Differentiable for Parameters {
    type Tangent = ParameterDirection;
    type Cotangent = ParameterGradient;
}
```

Use the same type for both associations when the forward and reverse
representations coincide.

## JVP rules return `Result`

Add an `Error` associated type and wrap the output in `Result`.

```rust
impl JvpRule<f64> for Square {
    type Output = f64;
    type Error = std::convert::Infallible;

    fn jvp(&self, x: &f64, dx: &f64) -> Result<(f64, f64), Self::Error> {
        Ok((x * x, 2.0 * x * dx))
    }
}
```

Use a domain-specific error enum for numerical operations. Do not encode
non-convergence or non-differentiability as NaN.

## Pullbacks return `Result` and use cotangents

Version 0.2 pullbacks have an error association and map output cotangents to
input cotangents:

```rust
impl Pullback<f64, f64> for SquarePullback {
    type Error = std::convert::Infallible;

    fn apply(self, output_cotangent: f64) -> Result<f64, Self::Error> {
        Ok(2.0 * self.x * output_cotangent)
    }
}
```

The pullback remains one-shot. The 0.1 README called it reusable even though
`apply(self, ...)` consumed it; 0.2 removes that ambiguity.

The blanket closure implementation now applies to closures returning
`Result<InputCotangent, Error>`.

## VJP rules return `Result`

Add `Error`, bind the pullback error, and return the primal/pullback pair in
`Result`:

```rust
impl VjpRule<f64> for Square {
    type Output = f64;
    type Error = std::convert::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 }))
    }
}
```

The generic associated type still permits a pullback to borrow `self` or the
primal arguments.

## `ZeroTangent` is removed

`ZeroTangent` in 0.1 was only a marker and could not compose with an arbitrary
nonzero tangent type. Version 0.2 does not standardize a lazy zero.

- Keep `NoTangent` for values with no differentiable space.
- Use the actual zero of a tangent/cotangent type when one is required.
- AD backends may use an internal `Option<Cotangent>` to avoid allocating a
  known zero before the first contribution.

## Complex values

Enable the optional feature when using `num_complex::Complex<T>`:

```toml
[dependencies]
chainrules-core = { version = "0.2", features = ["num-complex"] }
```

Complex rules for real-valued objectives use the real pairing
`Re(x.conj() * y)`. See `PROTOCOL.md`.

## Testing helpers

The scalar helpers remain available. Version 0.2 adds:

- `directional_central_difference`, which delegates perturbation and
  differencing to closures;
- `assert_adjoint_identity`, which delegates the input and output pairings to
  closures.

This supports vectors, matrices, structured parameters, and complex values
without adding a tensor dependency to the protocol.