From 99113c26049a974b1a15a630cf8aa2078f166509 Mon Sep 17 00:00:00 2001 From: adrhill Date: Fri, 10 May 2024 19:45:43 +0200 Subject: [PATCH 1/2] Improve backend type docstrings --- src/dense.jl | 52 +++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 39 insertions(+), 13 deletions(-) diff --git a/src/dense.jl b/src/dense.jl index 55b2954..f66b2d0 100644 --- a/src/dense.jl +++ b/src/dense.jl @@ -1,7 +1,9 @@ """ AutoChainRules{RC} -Chooses any AD library based on [ChainRulesCore.jl](https://github.com/JuliaDiff/ChainRulesCore.jl) (see the list [here](https://juliadiff.org/ChainRulesCore.jl/stable/index.html#ChainRules-roll-out-status)). +Type used to select an automatic differentiation backend based on [ChainRulesCore.jl](https://github.com/JuliaDiff/ChainRulesCore.jl) (see the list [here](https://juliadiff.org/ChainRulesCore.jl/stable/index.html#ChainRules-roll-out-status)). + +Exported by [ADTypes.jl](https://github.com/SciML/ADTypes.jl). # Fields @@ -20,7 +22,9 @@ mode(::AutoChainRules) = ForwardOrReverseMode() # specialized in the extension """ AutoDiffractor -Chooses [Diffractor.jl](https://github.com/JuliaDiff/Diffractor.jl). +Type indicating the use of the [Diffractor.jl](https://github.com/JuliaDiff/Diffractor.jl) backend for automatic differentiation. + +Exported by [ADTypes.jl](https://github.com/SciML/ADTypes.jl). # Constructor @@ -33,7 +37,9 @@ mode(::AutoDiffractor) = ForwardOrReverseMode() """ AutoEnzyme{M} -Chooses [Enzyme.jl](https://github.com/EnzymeAD/Enzyme.jl). +Type indicating the use of the [Enzyme.jl](https://github.com/EnzymeAD/Enzyme.jl) backend for automatic differentiation. + +Exported by [ADTypes.jl](https://github.com/SciML/ADTypes.jl). # Fields @@ -54,7 +60,9 @@ mode(::AutoEnzyme) = ForwardOrReverseMode() # specialized in the extension """ AutoFastDifferentiation -Chooses [FastDifferentiation.jl](https://github.com/brianguenter/FastDifferentiation.jl). +Type indicating the use of the [FastDifferentiation.jl](https://github.com/brianguenter/FastDifferentiation.jl) backend for automatic differentiation. + +Exported by [ADTypes.jl](https://github.com/SciML/ADTypes.jl). # Constructor @@ -67,7 +75,9 @@ mode(::AutoFastDifferentiation) = SymbolicMode() """ AutoFiniteDiff{T1,T2,T3} -Chooses [FiniteDiff.jl](https://github.com/JuliaDiff/FiniteDiff.jl). +Type indicating the use of the [FiniteDiff.jl](https://github.com/JuliaDiff/FiniteDiff.jl) backend for automatic differentiation. + +Exported by [ADTypes.jl](https://github.com/SciML/ADTypes.jl). # Fields @@ -90,7 +100,9 @@ mode(::AutoFiniteDiff) = ForwardMode() """ AutoFiniteDifferences{T} -Chooses [FiniteDifferences.jl](https://github.com/JuliaDiff/FiniteDifferences.jl). +Type indicating the use of the [FiniteDifferences.jl](https://github.com/JuliaDiff/FiniteDifferences.jl) backend for automatic differentiation. + +Exported by [ADTypes.jl](https://github.com/SciML/ADTypes.jl). # Fields @@ -109,7 +121,9 @@ mode(::AutoFiniteDifferences) = ForwardMode() """ AutoForwardDiff{chunksize,T} -Chooses [ForwardDiff.jl](https://github.com/JuliaDiff/ForwardDiff.jl). +Type indicating the use of the [ForwardDiff.jl](https://github.com/JuliaDiff/ForwardDiff.jl) backend for automatic differentiation. + +Exported by [ADTypes.jl](https://github.com/SciML/ADTypes.jl). # Type parameters @@ -136,7 +150,9 @@ mode(::AutoForwardDiff) = ForwardMode() """ AutoPolyesterForwardDiff{chunksize,T} -Chooses [PolyesterForwardDiff.jl](https://github.com/JuliaDiff/PolyesterForwardDiff.jl). +Type indicating the use of the [PolyesterForwardDiff.jl](https://github.com/JuliaDiff/PolyesterForwardDiff.jl) backend for automatic differentiation. + +Exported by [ADTypes.jl](https://github.com/SciML/ADTypes.jl). # Type parameters @@ -163,7 +179,9 @@ mode(::AutoPolyesterForwardDiff) = ForwardMode() """ AutoReverseDiff -Chooses [ReverseDiff.jl](https://github.com/JuliaDiff/ReverseDiff.jl). +Type indicating the use of the [ReverseDiff.jl](https://github.com/JuliaDiff/ReverseDiff.jl) backend for automatic differentiation. + +Exported by [ADTypes.jl](https://github.com/SciML/ADTypes.jl). # Fields @@ -182,7 +200,9 @@ mode(::AutoReverseDiff) = ReverseMode() """ AutoSymbolics -Chooses [Symbolics.jl](https://github.com/JuliaSymbolics/Symbolics.jl). +Type indicating the use of the [Symbolics.jl](https://github.com/JuliaSymbolics/Symbolics.jl) backend for automatic differentiation. + +Exported by [ADTypes.jl](https://github.com/SciML/ADTypes.jl). # Constructor @@ -195,7 +215,9 @@ mode(::AutoSymbolics) = SymbolicMode() """ AutoTapir -Chooses [Tapir.jl](https://github.com/withbayes/Tapir.jl). +Type indicating the use of the [Tapir.jl](https://github.com/withbayes/Tapir.jl) backend for automatic differentiation. + +Exported by [ADTypes.jl](https://github.com/SciML/ADTypes.jl). # Constructor @@ -208,7 +230,9 @@ mode(::AutoTapir) = ReverseMode() """ AutoTracker -Chooses [Tracker.jl](https://github.com/FluxML/Tracker.jl). +Type indicating the use of the [Tracker.jl](https://github.com/FluxML/Tracker.jl) backend for automatic differentiation. + +Exported by [ADTypes.jl](https://github.com/SciML/ADTypes.jl). # Constructor @@ -221,7 +245,9 @@ mode(::AutoTracker) = ReverseMode() """ AutoZygote -Chooses [Zygote.jl](https://github.com/FluxML/Zygote.jl). +Type indicating the use of the [Zygote.jl](https://github.com/FluxML/Zygote.jl) backend for automatic differentiation. + +Exported by [ADTypes.jl](https://github.com/SciML/ADTypes.jl). # Constructor From 9b98c861a041ba512712079116115f887432ad90 Mon Sep 17 00:00:00 2001 From: adrhill Date: Fri, 10 May 2024 20:05:53 +0200 Subject: [PATCH 2/2] Document constructor instead of type --- src/dense.jl | 144 ++++++++++++++++----------------------------------- 1 file changed, 45 insertions(+), 99 deletions(-) diff --git a/src/dense.jl b/src/dense.jl index f66b2d0..1751d91 100644 --- a/src/dense.jl +++ b/src/dense.jl @@ -1,17 +1,13 @@ """ - AutoChainRules{RC} + AutoChainRules(; ruleconfig) -Type used to select an automatic differentiation backend based on [ChainRulesCore.jl](https://github.com/JuliaDiff/ChainRulesCore.jl) (see the list [here](https://juliadiff.org/ChainRulesCore.jl/stable/index.html#ChainRules-roll-out-status)). +Struct used to select an automatic differentiation backend based on [ChainRulesCore.jl](https://github.com/JuliaDiff/ChainRulesCore.jl) (see the list [here](https://juliadiff.org/ChainRulesCore.jl/stable/index.html#ChainRules-roll-out-status)). -Exported by [ADTypes.jl](https://github.com/SciML/ADTypes.jl). +Exported from [ADTypes.jl](https://github.com/SciML/ADTypes.jl). -# Fields +# Keyword Arguments - `ruleconfig::RC`: a [`ChainRulesCore.RuleConfig`](https://juliadiff.org/ChainRulesCore.jl/stable/rule_author/superpowers/ruleconfig.html) object. - -# Constructor - - AutoChainRules(; ruleconfig) """ Base.@kwdef struct AutoChainRules{RC} <: AbstractADType ruleconfig::RC @@ -20,36 +16,28 @@ end mode(::AutoChainRules) = ForwardOrReverseMode() # specialized in the extension """ - AutoDiffractor - -Type indicating the use of the [Diffractor.jl](https://github.com/JuliaDiff/Diffractor.jl) backend for automatic differentiation. - -Exported by [ADTypes.jl](https://github.com/SciML/ADTypes.jl). + AutoDiffractor() -# Constructor +Struct used to select the [Diffractor.jl](https://github.com/JuliaDiff/Diffractor.jl) backend for automatic differentiation. - AutoDiffractor() +Exported from [ADTypes.jl](https://github.com/SciML/ADTypes.jl). """ struct AutoDiffractor <: AbstractADType end mode(::AutoDiffractor) = ForwardOrReverseMode() """ - AutoEnzyme{M} + AutoEnzyme(; mode=nothing) -Type indicating the use of the [Enzyme.jl](https://github.com/EnzymeAD/Enzyme.jl) backend for automatic differentiation. +Struct used to select the [Enzyme.jl](https://github.com/EnzymeAD/Enzyme.jl) backend for automatic differentiation. -Exported by [ADTypes.jl](https://github.com/SciML/ADTypes.jl). +Exported from [ADTypes.jl](https://github.com/SciML/ADTypes.jl). -# Fields +# Keyword Arguments - `mode::M`: can be either - an object subtyping `EnzymeCore.Mode` (like `EnzymeCore.Forward` or `EnzymeCore.Reverse`) if a specific mode is required - `nothing` to choose the best mode automatically - -# Constructors - - AutoEnzyme(; mode=nothing) """ Base.@kwdef struct AutoEnzyme{M} <: AbstractADType mode::M = nothing @@ -58,36 +46,28 @@ end mode(::AutoEnzyme) = ForwardOrReverseMode() # specialized in the extension """ - AutoFastDifferentiation - -Type indicating the use of the [FastDifferentiation.jl](https://github.com/brianguenter/FastDifferentiation.jl) backend for automatic differentiation. - -Exported by [ADTypes.jl](https://github.com/SciML/ADTypes.jl). + AutoFastDifferentiation() -# Constructor +Struct used to select the [FastDifferentiation.jl](https://github.com/brianguenter/FastDifferentiation.jl) backend for automatic differentiation. - AutoFastDifferentiation() +Exported from [ADTypes.jl](https://github.com/SciML/ADTypes.jl). """ struct AutoFastDifferentiation <: AbstractADType end mode(::AutoFastDifferentiation) = SymbolicMode() """ - AutoFiniteDiff{T1,T2,T3} + AutoFiniteDiff(; fdtype=Val(:forward), fdjtype=fdtype, fdhtype=Val(:hcentral)) -Type indicating the use of the [FiniteDiff.jl](https://github.com/JuliaDiff/FiniteDiff.jl) backend for automatic differentiation. +Struct used to select the [FiniteDiff.jl](https://github.com/JuliaDiff/FiniteDiff.jl) backend for automatic differentiation. -Exported by [ADTypes.jl](https://github.com/SciML/ADTypes.jl). +Exported from [ADTypes.jl](https://github.com/SciML/ADTypes.jl). -# Fields +# Keyword Arguments - `fdtype::T1`: finite difference type - `fdjtype::T2`: finite difference type for the Jacobian - `fdhtype::T3`: finite difference type for the Hessian - -# Constructor - - AutoFiniteDiff(; fdtype=Val(:forward), fdjtype=fdtype, fdhtype=Val(:hcentral)) """ Base.@kwdef struct AutoFiniteDiff{T1, T2, T3} <: AbstractADType fdtype::T1 = Val(:forward) @@ -98,19 +78,15 @@ end mode(::AutoFiniteDiff) = ForwardMode() """ - AutoFiniteDifferences{T} + AutoFiniteDifferences(; fdm) -Type indicating the use of the [FiniteDifferences.jl](https://github.com/JuliaDiff/FiniteDifferences.jl) backend for automatic differentiation. +Struct used to select the [FiniteDifferences.jl](https://github.com/JuliaDiff/FiniteDifferences.jl) backend for automatic differentiation. -Exported by [ADTypes.jl](https://github.com/SciML/ADTypes.jl). +Exported from [ADTypes.jl](https://github.com/SciML/ADTypes.jl). -# Fields +# Keyword Arguments - `fdm::T`: a [`FiniteDifferenceMethod`](https://juliadiff.org/FiniteDifferences.jl/stable/pages/api/#FiniteDifferences.FiniteDifferenceMethod) - -# Constructor - - AutoFiniteDifferences(; fdm) """ Base.@kwdef struct AutoFiniteDifferences{T} <: AbstractADType fdm::T @@ -119,23 +95,16 @@ end mode(::AutoFiniteDifferences) = ForwardMode() """ - AutoForwardDiff{chunksize,T} + AutoForwardDiff(; chunksize=nothing, tag=nothing) -Type indicating the use of the [ForwardDiff.jl](https://github.com/JuliaDiff/ForwardDiff.jl) backend for automatic differentiation. +Struct used to select the [ForwardDiff.jl](https://github.com/JuliaDiff/ForwardDiff.jl) backend for automatic differentiation. -Exported by [ADTypes.jl](https://github.com/SciML/ADTypes.jl). +Exported from [ADTypes.jl](https://github.com/SciML/ADTypes.jl). -# Type parameters +# Keyword Arguments - `chunksize`: the preferred [chunk size](https://juliadiff.org/ForwardDiff.jl/stable/user/advanced/#Configuring-Chunk-Size) to evaluate several derivatives at once - -# Fields - - `tag::T`: a [custom tag](https://juliadiff.org/ForwardDiff.jl/release-0.10/user/advanced.html#Custom-tags-and-tag-checking-1) to handle nested differentiation calls (usually not necessary) - -# Constructors - - AutoForwardDiff(; chunksize=nothing, tag=nothing) """ struct AutoForwardDiff{chunksize, T} <: AbstractADType tag::T @@ -148,23 +117,16 @@ end mode(::AutoForwardDiff) = ForwardMode() """ - AutoPolyesterForwardDiff{chunksize,T} + AutoPolyesterForwardDiff(; chunksize=nothing, tag=nothing) -Type indicating the use of the [PolyesterForwardDiff.jl](https://github.com/JuliaDiff/PolyesterForwardDiff.jl) backend for automatic differentiation. +Struct used to select the [PolyesterForwardDiff.jl](https://github.com/JuliaDiff/PolyesterForwardDiff.jl) backend for automatic differentiation. -Exported by [ADTypes.jl](https://github.com/SciML/ADTypes.jl). +Exported from [ADTypes.jl](https://github.com/SciML/ADTypes.jl). -# Type parameters +# Keyword Arguments - `chunksize`: the preferred [chunk size](https://juliadiff.org/ForwardDiff.jl/stable/user/advanced/#Configuring-Chunk-Size) to evaluate several derivatives at once - -# Fields - - `tag::T`: a [custom tag](https://juliadiff.org/ForwardDiff.jl/release-0.10/user/advanced.html#Custom-tags-and-tag-checking-1) to handle nested differentiation calls (usually not necessary) - -# Constructors - - AutoPolyesterForwardDiff(; chunksize=nothing, tag=nothing) """ struct AutoPolyesterForwardDiff{chunksize, T} <: AbstractADType tag::T @@ -177,19 +139,15 @@ end mode(::AutoPolyesterForwardDiff) = ForwardMode() """ - AutoReverseDiff + AutoReverseDiff(; compile=false) -Type indicating the use of the [ReverseDiff.jl](https://github.com/JuliaDiff/ReverseDiff.jl) backend for automatic differentiation. +Struct used to select the [ReverseDiff.jl](https://github.com/JuliaDiff/ReverseDiff.jl) backend for automatic differentiation. -Exported by [ADTypes.jl](https://github.com/SciML/ADTypes.jl). +Exported from [ADTypes.jl](https://github.com/SciML/ADTypes.jl). -# Fields +# Keyword Arguments - `compile::Bool`: whether to [compile the tape](https://juliadiff.org/ReverseDiff.jl/api/#ReverseDiff.compile) prior to differentiation - -# Constructor - - AutoReverseDiff(; compile=false) """ Base.@kwdef struct AutoReverseDiff <: AbstractADType compile::Bool = false @@ -198,30 +156,22 @@ end mode(::AutoReverseDiff) = ReverseMode() """ - AutoSymbolics - -Type indicating the use of the [Symbolics.jl](https://github.com/JuliaSymbolics/Symbolics.jl) backend for automatic differentiation. - -Exported by [ADTypes.jl](https://github.com/SciML/ADTypes.jl). + AutoSymbolics() -# Constructor +Struct used to select the [Symbolics.jl](https://github.com/JuliaSymbolics/Symbolics.jl) backend for automatic differentiation. - AutoSymbolics() +Exported from [ADTypes.jl](https://github.com/SciML/ADTypes.jl). """ struct AutoSymbolics <: AbstractADType end mode(::AutoSymbolics) = SymbolicMode() """ - AutoTapir - -Type indicating the use of the [Tapir.jl](https://github.com/withbayes/Tapir.jl) backend for automatic differentiation. + AutoTapir() -Exported by [ADTypes.jl](https://github.com/SciML/ADTypes.jl). +Struct used to select the [Tapir.jl](https://github.com/withbayes/Tapir.jl) backend for automatic differentiation. -# Constructor - - AutoTapir() +Exported from [ADTypes.jl](https://github.com/SciML/ADTypes.jl). """ struct AutoTapir <: AbstractADType end @@ -230,9 +180,9 @@ mode(::AutoTapir) = ReverseMode() """ AutoTracker -Type indicating the use of the [Tracker.jl](https://github.com/FluxML/Tracker.jl) backend for automatic differentiation. +Struct used to select the [Tracker.jl](https://github.com/FluxML/Tracker.jl) backend for automatic differentiation. -Exported by [ADTypes.jl](https://github.com/SciML/ADTypes.jl). +Exported from [ADTypes.jl](https://github.com/SciML/ADTypes.jl). # Constructor @@ -243,15 +193,11 @@ struct AutoTracker <: AbstractADType end mode(::AutoTracker) = ReverseMode() """ - AutoZygote - -Type indicating the use of the [Zygote.jl](https://github.com/FluxML/Zygote.jl) backend for automatic differentiation. - -Exported by [ADTypes.jl](https://github.com/SciML/ADTypes.jl). + AutoZygote() -# Constructor +Struct used to select the [Zygote.jl](https://github.com/FluxML/Zygote.jl) backend for automatic differentiation. - AutoZygote() +Exported from [ADTypes.jl](https://github.com/SciML/ADTypes.jl). """ struct AutoZygote <: AbstractADType end