Differentiation Core

---
name: differentiation-core
description: "Routes scalar and array differentiation, higher-order derivatives,
  and gradient checking for Autograd's core AD operators."
disable-model-invocation: true
metadata:
  disco-role: operating
license: MIT
---

# Differentiation Core

Use this sub-skill when a task is about Autograd's core differentiation operators: scalar gradients, Jacobians, directional derivatives, Hessians, VJP/JVP pullbacks, generalized Gauss-Newton products, complex holomorphic derivatives, checkpointing, or numerical gradient checks.

## Trigger examples

- "I need `grad` or `value_and_grad` for a scalar loss."
- "I need `jacobian` or `elementwise_grad` for a vector-valued output."
- "I need a Hessian-vector product, `make_vjp`, or `make_jvp`."
- "I want to verify a derivative with `check_grads`."
- "My function has `if`/`while` branches and I want to know whether Autograd can still differentiate it."

## Read first

- `references/api-reference.md` for operator selection, return conventions, and mode relationships.
- `references/workflows.md` for scalar-loss, vector-output, higher-order, complex, and gradient-checking recipes.
- `references/troubleshooting.md` for scalar-output errors, argnum confusion, shape mismatches, holomorphic warnings, and checkpoint tradeoffs.
- `scripts/differentiation_smoke.py` for a runnable smoke that exercises the core operators without plotting.

## Boundary routing

- Wrapper behavior, NumPy/SciPy support, `A.dot(B)` / in-place / container pitfalls, and optional dependency questions belong in `../numpy-scipy-primitives/SKILL.md`.
- `primitive`, `defvjp`, `defjvp`, and custom VJP/JVP mechanics belong in `../extend-primitives/SKILL.md`.
- Optimizer wiring, flattening, and `fixed_point` belong in `../optimization-workflows/SKILL.md`.

## How to choose an operator

- Use reverse mode when the output is a real scalar and the input is large: `grad`, `value_and_grad`, or `make_vjp`.
- Use forward mode when the input is scalar or you want one directional derivative: `deriv` or `make_jvp`.
- Use `jacobian` when you need the full output-to-input sensitivity tensor.
- Use `elementwise_grad` when the function is real-valued and elementwise so the Jacobian is diagonal or column-summed.
- Use `hessian`, `hessian_tensor_product`, `hessian_vector_product`, or `make_ggnvp` when you need curvature without writing the matrix explicitly.
- Use `holomorphic_grad` only for complex-holomorphic functions.
- Use `checkpoint` when the function is deep and memory is the bottleneck.
- Use `grad_and_aux` when the function returns a scalar loss plus extra side information.

## Core rules

- `grad` and `value_and_grad` require a real scalar output.
- `jacobian` works on scalar or array outputs and returns a tensor with output shape first and input shape last.
- `elementwise_grad` is not a general Jacobian helper; it returns the column-sum/diagonal behavior used for elementwise real functions.
- Control flow is transparent to Autograd: the executed Python path matters, not the unexecuted branches.
- `make_vjp` exposes the reverse-mode pullback; `make_jvp` exposes the forward-mode pushforward.
- Higher-order derivatives are usually formed by composing these operators.
- `grad_and_aux` differentiates only the first output and returns the auxiliary payload unchanged.
- `checkpoint` recomputes forward intermediates during the backward pass to trade time for memory.

## Typical route

1. Start with `grad` for a scalar loss.
2. If the output is vector-valued, switch to `jacobian` or `elementwise_grad`.
3. If you need both the value and the gradient, use `value_and_grad`.
4. If you need a directional derivative, use `deriv` or `make_jvp`.
5. If you need a pullback from output cotangents, use `make_vjp`.
6. If you need curvature information, use `hessian` or a Hessian-vector product helper.
7. If the function is complex-valued and holomorphic, use `holomorphic_grad`.
8. If the function is deep and memory-bound, wrap it with `checkpoint`.
9. Validate the chosen operator with `check_grads` before trusting a new workflow.

## Reliability notes

- Use `check_grads` for a single function and `combo_check` when you want the same assertion to cover several positional or keyword combinations.
- When a derivative shape looks wrong, inspect the primal input and output shapes before changing the operator.
- When the function is intentionally branchy, choose a test point away from the branch threshold.
- When the failure message names a missing VJP or JVP rule for a primitive, route to `../extend-primitives/SKILL.md` instead of trying to solve it here.

## What this sub-skill does not cover

- Built-in NumPy/SciPy wrapper behavior and compatibility traps live in `../numpy-scipy-primitives/SKILL.md`.
- Defining new primitives or VJP/JVP rules lives in `../extend-primitives/SKILL.md`.
- Optimizer flattening and structured parameter updates live in `../optimization-workflows/SKILL.md`.

## Fastest sanity check

Run `scripts/differentiation_smoke.py` when you need a quick end-to-end check that the bundled differentiation guidance still matches the installed package.