# 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.