From 630097939c8eb7a2cbef3ba2828452d488f21b46 Mon Sep 17 00:00:00 2001 From: adrhill Date: Thu, 22 Aug 2024 13:47:00 +0200 Subject: [PATCH 1/3] Document limitations of operator overloading utils --- docs/src/dev/adding_overloads.md | 2 +- src/overloads/special_cases.jl | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/src/dev/adding_overloads.md b/docs/src/dev/adding_overloads.md index 4271ab2..6857c30 100644 --- a/docs/src/dev/adding_overloads.md +++ b/docs/src/dev/adding_overloads.md @@ -11,7 +11,7 @@ Having read our guide [*"How SparseConnectivityTracer works"*](@ref how-sct-work to improve the performance of your functions or to work around some of SCT's [limitations](@ref limitations). !!! warning "Don't overload manually" - We strongly discourage you from manually adding methods on our tracer types. + If you want to overload a simple `Function` that takes `Real` arguments, we strongly discourage you from manually adding methods on our tracer types. Instead, use the same mechanisms we use ourselves. !!! tip "Copy one of our package extensions" diff --git a/src/overloads/special_cases.jl b/src/overloads/special_cases.jl index e116c47..cfbe69e 100644 --- a/src/overloads/special_cases.jl +++ b/src/overloads/special_cases.jl @@ -20,6 +20,8 @@ function Base.rand( rng::AbstractRNG, ::SamplerType{D} ) where {P,T<:AbstractTracer,D<:Dual{P,T}} p = rand(rng, P) + # This unfortunately can't just return the primal value. + # Random.jl will otherwise throw "TypeError: in typeassert, expected Dual{P,T}, got a value of type P". t = myempty(T) return Dual(p, t) end From 844cb1898dbb5bbf12db30d2f9b93f00e20eaf70 Mon Sep 17 00:00:00 2001 From: adrhill Date: Thu, 22 Aug 2024 13:49:23 +0200 Subject: [PATCH 2/3] Fixes --- docs/src/dev/adding_overloads.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/dev/adding_overloads.md b/docs/src/dev/adding_overloads.md index 6857c30..f35b680 100644 --- a/docs/src/dev/adding_overloads.md +++ b/docs/src/dev/adding_overloads.md @@ -11,7 +11,7 @@ Having read our guide [*"How SparseConnectivityTracer works"*](@ref how-sct-work to improve the performance of your functions or to work around some of SCT's [limitations](@ref limitations). !!! warning "Don't overload manually" - If you want to overload a simple `Function` that takes `Real` arguments, we strongly discourage you from manually adding methods on our tracer types. + If you want to overload a `Function` that takes `Real` arguments, we strongly discourage you from manually adding methods on our tracer types. Instead, use the same mechanisms we use ourselves. !!! tip "Copy one of our package extensions" From 3cb5c772d7f9d7fe1e7d327a607e836b539ec779 Mon Sep 17 00:00:00 2001 From: adrhill Date: Thu, 22 Aug 2024 13:57:17 +0200 Subject: [PATCH 3/3] More emphasis --- docs/src/dev/adding_overloads.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/src/dev/adding_overloads.md b/docs/src/dev/adding_overloads.md index f35b680..888aa14 100644 --- a/docs/src/dev/adding_overloads.md +++ b/docs/src/dev/adding_overloads.md @@ -10,9 +10,14 @@ Having read our guide [*"How SparseConnectivityTracer works"*](@ref how-sct-work [`Dual`](@ref SparseConnectivityTracer.Dual) to improve the performance of your functions or to work around some of SCT's [limitations](@ref limitations). +## Avoid hand-written overloads + !!! warning "Don't overload manually" - If you want to overload a `Function` that takes `Real` arguments, we strongly discourage you from manually adding methods on our tracer types. - Instead, use the same mechanisms we use ourselves. + If you want to overload a `Function` that takes `Real` arguments, + we strongly discourage you from manually adding methods to your function that use our internal tracer types. + + Instead, use the same code generation mechanisms that we use. + This page of the documentation shows you how. !!! tip "Copy one of our package extensions" The easiest way to add overloads is to copy one of our [package extensions](https://github.com/adrhill/SparseConnectivityTracer.jl/tree/main/ext) and to modify it.