API Documentation

ChainRulesTestUtils.:⊢Type
primal ⊢ tangent

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

source
ChainRulesTestUtils.TestIteratorType
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.

source
ChainRulesTestUtils.rand_tangentMethod
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.

source
ChainRulesTestUtils.test_approxFunction
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.

source
ChainRulesTestUtils.test_fruleMethod
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.
source
ChainRulesTestUtils.test_method_tablesMethod
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)

source
ChainRulesTestUtils.test_rruleMethod
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).
    • : currently accumulated cotangent; will be generated automatically if not provided.
    Non-differentiable arguments, such as indices, should have 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.
source
ChainRulesTestUtils.test_scalarMethod
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.
source
ChainRulesTestUtils.@maybe_inferredMacro
@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.

source