API reference
DifferentiationInterfaceTest — ModuleDifferentiationInterfaceTestTesting and benchmarking utilities for automatic differentiation in Julia.
Exports
Entry points
DifferentiationInterfaceTest.test_differentiation — Functiontest_differentiation(
+API reference · DifferentiationInterfaceTest.jl API reference
DifferentiationInterfaceTest — ModuleDifferentiationInterfaceTest
Testing and benchmarking utilities for automatic differentiation in Julia.
Exports
sourceEntry points
DifferentiationInterfaceTest.test_differentiation — Functiontest_differentiation(
backends::Vector{<:ADTypes.AbstractADType};
...
)
@@ -22,12 +22,12 @@
atol,
rtol
)
-
Cross-test a list of backends on a list of scenarios, running a variety of different tests.
Default arguments
scenarios::Vector{<:AbstractScenario}: the output of default_scenarios()
Keyword arguments
Testing:
correctness=true: whether to compare the differentiation results with the theoretical values specified in each scenariotype_stability=false: whether to check type stability with JET.jl (thanks to @test_opt)sparsity: whether to check sparsity of the jacobian / hessianref_backend: if not nothing, an ADTypes.AbstractADType object to use instead of the scenario-specific reference to provide true valuesdetailed=false: whether to print a detailed or condensed test log
Filtering:
input_type=Any: restrict scenario inputs to subtypes of thisoutput_type=Any: restrict scenario outputs to subtypes of thisfirst_order=true: include first order operatorssecond_order=true: include second order operators
Options:
logging=false: whether to log progressisapprox=isapprox: function used to compare objects, with the standard signature isapprox(x, y; atol, rtol)atol=0: absolute precision for correctness testing (when comparing to the reference outputs)rtol=1e-3: relative precision for correctness testing (when comparing to the reference outputs)
sourcetest_differentiation(
+
Cross-test a list of backends on a list of scenarios, running a variety of different tests.
Default arguments
scenarios::Vector{<:AbstractScenario}: the output of default_scenarios()
Keyword arguments
Testing:
correctness=true: whether to compare the differentiation results with the theoretical values specified in each scenariotype_stability=false: whether to check type stability with JET.jl (thanks to @test_opt)sparsity: whether to check sparsity of the jacobian / hessianref_backend: if not nothing, an ADTypes.AbstractADType object to use instead of the scenario-specific reference to provide true valuesdetailed=false: whether to print a detailed or condensed test log
Filtering:
input_type=Any: restrict scenario inputs to subtypes of thisoutput_type=Any: restrict scenario outputs to subtypes of thisfirst_order=true: include first order operatorssecond_order=true: include second order operators
Options:
logging=false: whether to log progressisapprox=isapprox: function used to compare objects, with the standard signature isapprox(x, y; atol, rtol)atol=0: absolute precision for correctness testing (when comparing to the reference outputs)rtol=1e-3: relative precision for correctness testing (when comparing to the reference outputs)
sourcetest_differentiation(
backend::ADTypes.AbstractADType,
args...;
kwargs...
)
-
Shortcut for a single backend.
sourceDifferentiationInterfaceTest.benchmark_differentiation — Functionbenchmark_differentiation(
+
Shortcut for a single backend.
sourceDifferentiationInterfaceTest.benchmark_differentiation — Functionbenchmark_differentiation(
backends::Vector{<:ADTypes.AbstractADType};
...
) -> Vector{DifferentiationInterfaceTest.BenchmarkDataRow}
@@ -41,4 +41,4 @@
excluded,
logging
) -> Vector{DifferentiationInterfaceTest.BenchmarkDataRow}
-
Benchmark a list of backends for a list of operators on a list of scenarios.
Keyword arguments
- filtering: same as
test_differentiation for the filtering part. logging=false: whether to log progress
sourcePre-made scenario lists
DifferentiationInterfaceTest.default_scenarios — Functiondefault_scenarios()
Create a vector of AbstractScenarios with standard array types.
sourceDifferentiationInterfaceTest.sparse_scenarios — Functionsparse_scenarios()
Create a vector of AbstractScenarios with sparse array types, focused on sparse Jacobians and Hessians.
sourceDifferentiationInterfaceTest.component_scenarios — Functioncomponent_scenarios()
Create a vector of AbstractScenarios with component array types from ComponentArrays.jl.
sourceDifferentiationInterfaceTest.gpu_scenarios — Functiongpu_scenarios()
Create a vector of AbstractScenarios with GPU array types from JLArrays.jl.
sourceDifferentiationInterfaceTest.static_scenarios — Functionstatic_scenarios()
Create a vector of AbstractScenarios with static array types from StaticArrays.jl.
sourceScenario types
DifferentiationInterfaceTest.AbstractScenario — TypeAbstractScenario
Store a testing scenario composed of a function and its input + output.
This abstract type should never be used directly: construct one of the subtypes corresponding to the operator you want to test.
Subtypes
PushforwardScenarioPullbackScenarioDerivativeScenarioGradientScenarioJacobianScenarioSecondDerivativeScenarioHVPScenarioHessianScenario
Fields
All subtypes have the following fields:
f: function to applyx: primal inputy: primal outputref: reference to compare against
In addition, some subtypes contain an additional seed (dx or dy).
Constructor
If y is provided, f is interpreted as a 2-argument function f!(y, x) = nothing. Otherwise, f is interpreted as an 1-argument function f(x) = y.
The reference keyword ref should be a function that takes x (and a potential seed dx or dy) to return the correct object.
The operator behavior keyword operator should be either :inplace or :outofplace depending on what must be tested.
sourceDifferentiationInterfaceTest.PushforwardScenario — TypePushforwardScenario(f; x, y, dx, ref, operator)
See AbstractScenario for details.
sourceDifferentiationInterfaceTest.PullbackScenario — TypePullbackScenario(f; x, y, dy, ref, operator)
See AbstractScenario for details.
sourceDifferentiationInterfaceTest.DerivativeScenario — TypeDerivativeScenario(f; x, y, ref, operator)
See AbstractScenario for details.
sourceDifferentiationInterfaceTest.GradientScenario — TypeGradientScenario(f; x, y, ref, operator)
See AbstractScenario for details.
sourceDifferentiationInterfaceTest.JacobianScenario — TypeJacobianScenario(f; x, y, ref, operator)
See AbstractScenario for details.
sourceDifferentiationInterfaceTest.SecondDerivativeScenario — TypeSecondDerivativeScenario(f; x, y, ref, operator)
See AbstractScenario for details.
sourceDifferentiationInterfaceTest.HVPScenario — TypeHVPScenario(f; x, y, dx, ref, operator)
See AbstractScenario for details.
sourceDifferentiationInterfaceTest.HessianScenario — TypeHessianScenario(f; x, y, ref, operator)
See AbstractScenario for details.
sourceInternals
This is not part of the public API.
DifferentiationInterfaceTest.AutoZeroForward — TypeAutoZeroForward <: ADTypes.AbstractADType
Trivial backend that sets all derivatives to zero. Used in testing and benchmarking.
sourceDifferentiationInterfaceTest.AutoZeroReverse — TypeAutoZeroReverse <: ADTypes.AbstractADType
Trivial backend that sets all derivatives to zero. Used in testing and benchmarking.
sourceDifferentiationInterfaceTest.BenchmarkDataRow — TypeBenchmarkDataRow
Ad-hoc storage type for differentiation benchmarking results. If you have a vector rows::Vector{BenchmarkDataRow}, you can turn it into a DataFrame as follows:
df = DataFrames.DataFrame(rows)
Fields
These are not part of the public API.
backend::String
mode::ADTypes.AbstractMode
scenario::Symbol
operator::Symbol
func::Symbol
arguments::Int64
input_type::Type
output_type::Type
input_size::Tuple
output_size::Tuple
calls::Int64
samples::Int64
evals::Int64
time::Float64
bytes::Float64
allocs::Float64
compile_fraction::Float64
gc_fraction::Float64
sourceSettings
This document was generated with Documenter.jl version 1.4.0 on Thursday 25 April 2024. Using Julia version 1.10.2.
Benchmark a list of backends for a list of operators on a list of scenarios.
Keyword arguments
- filtering: same as
test_differentiationfor the filtering part. logging=false: whether to log progress
Pre-made scenario lists
DifferentiationInterfaceTest.default_scenarios — Functiondefault_scenarios()Create a vector of AbstractScenarios with standard array types.
DifferentiationInterfaceTest.sparse_scenarios — Functionsparse_scenarios()Create a vector of AbstractScenarios with sparse array types, focused on sparse Jacobians and Hessians.
DifferentiationInterfaceTest.component_scenarios — Functioncomponent_scenarios()Create a vector of AbstractScenarios with component array types from ComponentArrays.jl.
DifferentiationInterfaceTest.gpu_scenarios — Functiongpu_scenarios()Create a vector of AbstractScenarios with GPU array types from JLArrays.jl.
DifferentiationInterfaceTest.static_scenarios — Functionstatic_scenarios()Create a vector of AbstractScenarios with static array types from StaticArrays.jl.
Scenario types
DifferentiationInterfaceTest.AbstractScenario — TypeAbstractScenarioStore a testing scenario composed of a function and its input + output.
This abstract type should never be used directly: construct one of the subtypes corresponding to the operator you want to test.
Subtypes
PushforwardScenarioPullbackScenarioDerivativeScenarioGradientScenarioJacobianScenarioSecondDerivativeScenarioHVPScenarioHessianScenario
Fields
All subtypes have the following fields:
f: function to applyx: primal inputy: primal outputref: reference to compare against
In addition, some subtypes contain an additional seed (dx or dy).
Constructor
If y is provided, f is interpreted as a 2-argument function f!(y, x) = nothing. Otherwise, f is interpreted as an 1-argument function f(x) = y.
The reference keyword ref should be a function that takes x (and a potential seed dx or dy) to return the correct object.
The operator behavior keyword operator should be either :inplace or :outofplace depending on what must be tested.
DifferentiationInterfaceTest.PushforwardScenario — TypePushforwardScenario(f; x, y, dx, ref, operator)See AbstractScenario for details.
DifferentiationInterfaceTest.PullbackScenario — TypePullbackScenario(f; x, y, dy, ref, operator)See AbstractScenario for details.
DifferentiationInterfaceTest.DerivativeScenario — TypeDerivativeScenario(f; x, y, ref, operator)See AbstractScenario for details.
DifferentiationInterfaceTest.GradientScenario — TypeGradientScenario(f; x, y, ref, operator)See AbstractScenario for details.
DifferentiationInterfaceTest.JacobianScenario — TypeJacobianScenario(f; x, y, ref, operator)See AbstractScenario for details.
DifferentiationInterfaceTest.SecondDerivativeScenario — TypeSecondDerivativeScenario(f; x, y, ref, operator)See AbstractScenario for details.
DifferentiationInterfaceTest.HVPScenario — TypeHVPScenario(f; x, y, dx, ref, operator)See AbstractScenario for details.
DifferentiationInterfaceTest.HessianScenario — TypeHessianScenario(f; x, y, ref, operator)See AbstractScenario for details.
Internals
This is not part of the public API.
DifferentiationInterfaceTest.AutoZeroForward — TypeAutoZeroForward <: ADTypes.AbstractADTypeTrivial backend that sets all derivatives to zero. Used in testing and benchmarking.
DifferentiationInterfaceTest.AutoZeroReverse — TypeAutoZeroReverse <: ADTypes.AbstractADTypeTrivial backend that sets all derivatives to zero. Used in testing and benchmarking.
DifferentiationInterfaceTest.BenchmarkDataRow — TypeBenchmarkDataRowAd-hoc storage type for differentiation benchmarking results. If you have a vector rows::Vector{BenchmarkDataRow}, you can turn it into a DataFrame as follows:
df = DataFrames.DataFrame(rows)Fields
These are not part of the public API.
backend::Stringmode::ADTypes.AbstractModescenario::Symboloperator::Symbolfunc::Symbolarguments::Int64input_type::Typeoutput_type::Typeinput_size::Tupleoutput_size::Tuplecalls::Int64samples::Int64evals::Int64time::Float64bytes::Float64allocs::Float64compile_fraction::Float64gc_fraction::Float64