Merge pull request #469 from SciML/myb/register_der

Document registering the derivative of a function

Author: ChrisRackauckas

src/function_registration.jl

@@ -10,6 +10,31 @@ ModelingToolkit IR. Example:
 ```
 
 registers `f` as a possible two-argument function.
+
+You may also want to tell ModelingToolkit the derivative of the registered
+function. Here is an example to do it
+
+```julia
+julia> using ModelingToolkit
+
+julia> foo(x, y) = sin(x) * cos(y)
+foo (generic function with 1 method)
+
+julia> @parameters t; @variables x(t) y(t) z(t); @derivatives D'~t;
+
+julia> @register foo(x, y)
+foo (generic function with 4 methods)
+
+julia> foo(x, y)
+foo(x(t), y(t))
+
+julia> ModelingToolkit.derivative(::typeof(foo), (x, y), ::Val{1}) = cos(x) * cos(y) # derivative w.r.t. the first argument
+
+julia> ModelingToolkit.derivative(::typeof(foo), (x, y), ::Val{2}) = -sin(x) * sin(y) # derivative w.r.t. the second argument
+
+julia> isequal(expand_derivatives(D(foo(x, y))), expand_derivatives(D(sin(x) * cos(y))))
+true
+```
 """
 macro register(sig)
     splitsig = splitdef(:($sig = nothing))
@@ -116,4 +141,4 @@ function inject_registered_module_functions(expr)
 
         return x
     end
-end
+end

test/function_registration.jl

@@ -62,3 +62,15 @@ sys = ODESystem([eq], t, [u], [x])
 fun = ODEFunction(sys)
 
 @test fun([0.5], [7.0], 0.) == [74.0]
+
+# derivative
+foo(x, y) = sin(x) * cos(y)
+@parameters t; @variables x(t) y(t) z(t); @derivatives D'~t;
+@register foo(x, y)
+expr = foo(x, y)
+@test expr.op === foo
+@test expr.args[1] === x
+@test expr.args[2] === y
+ModelingToolkit.derivative(::typeof(foo), (x, y), ::Val{1}) = cos(x) * cos(y) # derivative w.r.t. the first argument
+ModelingToolkit.derivative(::typeof(foo), (x, y), ::Val{2}) = -sin(x) * sin(y) # derivative w.r.t. the second argument
+@test isequal(expand_derivatives(D(foo(x, y))), expand_derivatives(D(sin(x) * cos(y))))