API Documentation

primal ⊢ tangent

Infix shorthand method to construct a PrimalAndTangent. Enter via \vdash + tab on supporting editors.

TestIterator{T,IS<:Base.IteratorSize,IE<:Base.IteratorEltype}

A configurable iterator for testing purposes.

TestIterator(data, itersize, itereltype)
TestIterator(data)

The iterator wraps another iterator data, such as an array, that must have at least as many features implemented as the test iterator and have a FiniteDifferences.to_vec overload. By default, the iterator it has the same features as data.

The optional methods eltype, length, and size are automatically defined and forwarded to data if the type arguments indicate that they should be defined.

rand_tangent([rng::AbstractRNG,] x)

Returns a arbitary tangent vector appropriate for the primal value x. Note that despite the name, no promises on the statistical randomness are made. Rather it is an arbitary value, that is generated using the rng.

test_approx(actual, expected, [msg]; kwargs...)

@test's that actual ≈ expected, but breaks up data such that human readable results are shown on failures. Understands things like unthunking ChainRuleCore.Thunks, etc.

If provided msg is printed on a failure. Often additional items are appended to msg to give bread-crumbs into nested structures.

All keyword arguments are passed to isapprox.

test_frule([config::RuleConfig,] f, args..; kwargs...)

Arguments

• config: defaults to ChainRulesTestUtils.TestConfig.
• f: function for which the frule should be tested. Its tangent can be provided using f ⊢ ḟ. (You can enter ⊢ via \vdash + tab in the Julia REPL and supporting editors.)
• args...: either the primal args x, or primals and their tangents: x ⊢ ẋ
  • x: input at which to evaluate f (should generally be set to an arbitrary point in the domain).
  • ẋ: differential w.r.t. x; will be generated automatically if not provided.
  Non-differentiable arguments, such as indices, should have ẋ set as NoTangent().

Keyword Arguments

• output_tangent: tangent against which to test accumulation of derivatives. Should be a differential for the output of f. Is set automatically if not provided.
• fdm::FiniteDifferenceMethod: the finite differencing method to use.
• frule_f=frule: function with an frule-like API that is tested (defaults to frule). Used for testing gradients from AD systems.
• If check_inferred=true, then the inferrability (type-stability) of the frule is checked, as long as f is itself inferrable.
• fkwargs are passed to f as keyword arguments.
• testset_name: if provided, the name of the testset used to wrap the tests.

Otherwise it is determined from the function and argument types.

• All remaining keyword arguments are passed to isapprox.

test_method_tables()

Checks that the method tables for rrule and frule are sensible. This in future may carry out a number of checks, but presently just checks to make sure that no rules have been added to the very general DataType, Union or UnionAll types, which is easy to do accidentally when writing rules for constructors. It happens if you write e.g. rrule(::typeof(Foo), x) rather than rrule(::Type{<:Foo}, x). This would then actually define rrule(::DataType, x). (or UnionAll if Foo was parametric, or Union if Foo was a type alias for a Union)

test_rrule([config::RuleConfig,] f, args...; kwargs...)

Arguments

• config: defaults to ChainRulesTestUtils.TestConfig.
• f: function for which the rrule should be tested. Its tangent can be provided using f ⊢ f̄. (You can enter ⊢ via \vdash + tab in the Julia REPL and supporting editors.)
• args...: either the primal args x, or primals and their tangents: x ⊢ x̄
  • x: input at which to evaluate f (should generally be set to an arbitrary point in the domain).
  • x̄: currently accumulated cotangent; will be generated automatically if not provided.
  Non-differentiable arguments, such as indices, should have x̄ set as NoTangent().

Keyword Arguments

• output_tangent: the seed to propagate backward for testing (technically a cotangent). should be a differential for the output of f. Is set automatically if not provided.
• check_thunked_output_tangent=true: also checks that passing a thunked version of the output tangent to the pullback returns the same result.
• fdm::FiniteDifferenceMethod: the finite differencing method to use.
• rrule_f=rrule: function with an rrule-like API that is tested (defaults to rrule). Used for testing gradients from AD systems.
• If check_inferred=true, then the inferrability (type-stability) of the rrule is checked — if f is itself inferrable — along with the inferrability of the pullback it returns.
• fkwargs are passed to f as keyword arguments.
• testset_name: if provided, the name of the testset used to wrap the tests.

Otherwise it is determined from the function and argument types.

• All remaining keyword arguments are passed to isapprox.

test_scalar(f, z; rtol=1e-9, atol=1e-9, fdm=central_fdm(5, 1), fkwargs=NamedTuple(), check_inferred=true, kwargs...)

Given a function f with scalar input and scalar output, perform finite differencing checks, at input point z to confirm that there are correct frule and rrules provided.

Arguments

• f: function for which the frule and rrule should be tested.
• z: input at which to evaluate f (should generally be set to an arbitrary point in the domain).

Keyword Arguments

• fdm: the finite differencing method to use.
• fkwargs are passed to f as keyword arguments.
• If check_inferred=true, then the inferrability (type-stability) of the frule and rrule are checked.
• testset_name: if provided, the name of the testset used to wrap the tests. Otherwise it is determined from the function and argument types.
• All remaining keyword arguments are passed to isapprox.

@maybe_inferred [Type] f(...)

Like @inferred, but does not check the return type if tests are run as part of PkgEval or if the environment variable CHAINRULES_TEST_INFERRED is set to false.