Merge pull request #22 from SymbolicML/deprecate-implicit

Deprecate implicit call API

Author: MilesCranmer

README.md

@@ -36,7 +36,7 @@ x2 = Node(; feature=2)
 expression = x1 * cos(x2 - 3.2)
 
 X = randn(Float64, 2, 100);
-expression(X) # 100-element Vector{Float64}
+expression(X, operators) # 100-element Vector{Float64}
 ```
 
 (We can construct this expression with normal operators, since calling `OperatorEnum()` will `@eval` new functions on `Node` that use the specified enum.)
@@ -53,18 +53,18 @@ First, what happens if we naively use Julia symbols to define and then evaluate
 This is quite slow, meaning it will be hard to quickly search over the space of expressions. Let's see how DynamicExpressions.jl compares:
 
 ```julia
-@btime expression(X)
+@btime expression(X, operators)
 # 693 ns
 ```
 
-Much faster! And we didn't even need to compile it. (Internally, this is calling `eval_tree_array(expression, X, operators)` - where `operators` has been pre-defined when we called `OperatorEnum()`). 
+Much faster! And we didn't even need to compile it. (Internally, this is calling `eval_tree_array(expression, X, operators)`). 
 
 If we change `expression` dynamically with a random number generator, it will have the same performance:
 
 ```julia
 @btime begin
     expression.op = rand(1:3)  # random operator in [+, -, *]
-    expression(X)
+    expression(X, operators)
 end
 # 842 ns
 ```
@@ -113,13 +113,13 @@ expression = x1 * cos(x2 - 3.2)
 We can take the gradient with respect to inputs with simply the `'` character:
 
 ```julia
-grad = expression'(X)
+grad = expression'(X, operators)
 ```
 
 This is quite fast:
 
 ```julia
-@btime expression'(X)
+@btime expression'(X, operators)
 # 2894 ns
 ```
 
@@ -128,7 +128,7 @@ and again, we can change this expression at runtime, without loss in performance
 ```julia
 @btime begin
     expression.op = rand(1:3)
-    expression'(X)
+    expression'(X, operators)
 end
 # 3198 ns
 ```
@@ -180,14 +180,14 @@ Now, let's create an expression:
 tree = "H" * my_string_func(x1)
 # ^ `(H * my_string_func(x1))`
 
-tree(["World!", "Me?"])
+tree(["World!", "Me?"], operators)
 # Hello World!
 ```
 
 So indeed it works for arbitrary types. It is a bit slower due to the potential for type instability, but it's not too bad:
 
 ```julia
-@btime tree(["Hello", "Me?"])
+@btime tree(["Hello", "Me?"], operators)
 # 1738 ns
 ``` 
 
@@ -220,15 +220,15 @@ tree = vec_add(vec_add(vec_square(x1), c2), c1)
 X = [[-1.0, 5.2, 0.1], [0.0, 0.0, 0.0]]
 
 # Evaluate!
-tree(X)  # [2.0, 29.04, 3.01]
+tree(X, operators)  # [2.0, 29.04, 3.01]
 ```
 
 Note that if an operator is not defined for the particular input, `nothing` will be returned instead.
 
 This is all still pretty fast, too:
 
 ```julia
-@btime tree(X)
+@btime tree(X, operators)
 # 2,949 ns
 @btime eval(:(vec_add(vec_add(vec_square(X[1]), [1.0, 2.0, 3.0]), 0.0)))
 # 115,000 ns

docs/src/eval.md

@@ -8,13 +8,34 @@ eval_tree_array(tree::Node{T}, cX::AbstractMatrix{T}, operators::OperatorEnum) w
 ```
 
 Assuming you are only using a single `OperatorEnum`, you can also use
-the following short-hand by using the expression as a function:
+the following shorthand by using the expression as a function:
+
+```
+    (tree::Node)(X::AbstractMatrix{T}, operators::OperatorEnum; turbo::Bool=false)
+
+Evaluate a binary tree (equation) over a given data matrix. The
+operators contain all of the operators used in the tree.
+
+# Arguments
+- `X::AbstractMatrix{T}`: The input data to evaluate the tree on.
+- `operators::OperatorEnum`: The operators used in the tree.
+- `turbo::Bool`: Use `LoopVectorization.@turbo` for faster evaluation.
+
+# Returns
+- `output::AbstractVector{T}`: the result, which is a 1D array.
+    Any NaN, Inf, or other failure during the evaluation will result in the entire
+    output array being set to NaN.
+```
+
+For example,
+
+```@example
+using DynamicExpressions
 
-```julia
 operators = OperatorEnum(; binary_operators=[+, -, *], unary_operators=[cos])
 tree = Node(; feature=1) * cos(Node(; feature=2) - 3.2)
 
-tree(X)
+tree([1 2 3; 4 5 6.], operators)
 ```
 
 This is possible because when you call `OperatorEnum`, it automatically re-defines
@@ -32,7 +53,31 @@ The notation is the same for `eval_tree_array`, though it will return `nothing`
 when it can't find a method, and not do any NaN checks:
 
 ```@docs
-    eval_tree_array(tree, cX::AbstractArray, operators::GenericOperatorEnum; throw_errors::Bool=true)
+eval_tree_array(tree::Node, cX::AbstractMatrix, operators::GenericOperatorEnum; throw_errors::Bool=true)
+```
+
+Likewise for the shorthand notation:
+
+```
+    (tree::Node)(X::AbstractMatrix, operators::GenericOperatorEnum; throw_errors::Bool=true)
+
+# Arguments
+- `X::AbstractArray`: The input data to evaluate the tree on.
+- `operators::GenericOperatorEnum`: The operators used in the tree.
+- `throw_errors::Bool=true`: Whether to throw errors
+    if they occur during evaluation. Otherwise,
+    MethodErrors will be caught before they happen and 
+    evaluation will return `nothing`,
+    rather than throwing an error. This is useful in cases
+    where you are unsure if a particular tree is valid or not,
+    and would prefer to work with `nothing` as an output.
+
+# Returns
+- `output`: the result of the evaluation.
+    If evaluation failed, `nothing` will be returned for the first argument.
+    A `false` complete means an operator was called on input types
+    that it was not defined for. You can change this behavior by
+    setting `throw_errors=false`.
 ```
 
 ## Derivatives
@@ -46,7 +91,32 @@ all variables (or, all constants). Both use forward-mode automatic, but use
 
 ```@docs
 eval_diff_tree_array(tree::Node{T}, cX::AbstractMatrix{T}, operators::OperatorEnum, direction::Int) where {T<:Number}
-eval_grad_tree_array(tree::Node{T}, cX::AbstractMatrix{T}, operators::OperatorEnum; variable::Bool=false) where {T<:Number}
+eval_grad_tree_array(tree::Node{T}, cX::AbstractMatrix{T}, operators::OperatorEnum; turbo::Bool=false, variable::Bool=false) where {T<:Number}
+```
+
+You can compute gradients this with shorthand notation as well (which by default computes
+gradients with respect to input matrix, rather than constants).
+
+```
+    (tree::Node{T})'(X::AbstractMatrix{T}, operators::OperatorEnum; turbo::Bool=false, variable::Bool=true)
+
+Compute the forward-mode derivative of an expression, using a similar
+structure and optimization to eval_tree_array. `variable` specifies whether
+we should take derivatives with respect to features (i.e., X), or with respect
+to every constant in the expression.
+
+# Arguments
+- `X::AbstractMatrix{T}`: The data matrix, with each column being a data point.
+- `operators::OperatorEnum`: The operators used to create the `tree`. Note that `operators.enable_autodiff`
+    must be `true`. This is needed to create the derivative operations.
+- `variable::Bool`: Whether to take derivatives with respect to features (i.e., `X` - with `variable=true`),
+    or with respect to every constant in the expression (`variable=false`).
+- `turbo::Bool`: Use `LoopVectorization.@turbo` for faster evaluation.
+
+# Returns
+
+- `(evaluation, gradient, complete)::Tuple{AbstractVector{T}, AbstractMatrix{T}, Bool}`: the normal evaluation,
+    the gradient, and whether the evaluation completed as normal (or encountered a nan or inf).
 ```
 
 Alternatively, you can compute higher-order derivatives by using `ForwardDiff` on

src/DynamicExpressions.jl

@@ -6,6 +6,7 @@ include("Equation.jl")
 include("EquationUtils.jl")
 include("EvaluateEquation.jl")
 include("EvaluateEquationDerivative.jl")
+include("EvaluationHelpers.jl")
 include("InterfaceSymbolicUtils.jl")
 include("SimplifyEquation.jl")
 include("OperatorEnumConstruction.jl")
@@ -31,6 +32,7 @@ using Reexport
     eval_diff_tree_array, eval_grad_tree_array
 @reexport import .InterfaceSymbolicUtilsModule: node_to_symbolic, symbolic_to_node
 @reexport import .SimplifyEquationModule: combine_operators, simplify_tree
+@reexport import .EvaluationHelpersModule
 
 import TOML: parsefile
 

src/EvaluationHelpers.jl

@@ -0,0 +1,107 @@
+module EvaluationHelpersModule
+
+import Base: adjoint
+import ..OperatorEnumModule: AbstractOperatorEnum, OperatorEnum, GenericOperatorEnum
+import ..EquationModule: Node
+import ..EvaluateEquationModule: eval_tree_array
+import ..EvaluateEquationDerivativeModule: eval_grad_tree_array
+
+# Evaluation:
+"""
+    (tree::Node)(X::AbstractMatrix{T}, operators::OperatorEnum; turbo::Bool=false)
+
+Evaluate a binary tree (equation) over a given data matrix. The
+operators contain all of the operators used in the tree.
+
+# Arguments
+- `X::AbstractMatrix{T}`: The input data to evaluate the tree on.
+- `operators::OperatorEnum`: The operators used in the tree.
+- `turbo::Bool`: Use `LoopVectorization.@turbo` for faster evaluation.
+
+# Returns
+- `output::AbstractVector{T}`: the result, which is a 1D array.
+    Any NaN, Inf, or other failure during the evaluation will result in the entire
+    output array being set to NaN.
+"""
+function (tree::Node)(X, operators::OperatorEnum; kws...)
+    out, did_finish = eval_tree_array(tree, X, operators; kws...)
+    !did_finish && (out .= convert(eltype(out), NaN))
+    return out
+end
+"""
+    (tree::Node)(X::AbstractMatrix, operators::GenericOperatorEnum; throw_errors::Bool=true)
+
+# Arguments
+- `X::AbstractArray`: The input data to evaluate the tree on.
+- `operators::GenericOperatorEnum`: The operators used in the tree.
+- `throw_errors::Bool=true`: Whether to throw errors
+    if they occur during evaluation. Otherwise,
+    MethodErrors will be caught before they happen and 
+    evaluation will return `nothing`,
+    rather than throwing an error. This is useful in cases
+    where you are unsure if a particular tree is valid or not,
+    and would prefer to work with `nothing` as an output.
+
+# Returns
+- `output`: the result of the evaluation.
+    If evaluation failed, `nothing` will be returned for the first argument.
+    A `false` complete means an operator was called on input types
+    that it was not defined for. You can change this behavior by
+    setting `throw_errors=false`.
+"""
+function (tree::Node)(X, operators::GenericOperatorEnum; kws...)
+    out, did_finish = eval_tree_array(tree, X, operators; kws...)
+    !did_finish && return nothing
+    return out
+end
+function (tree::Node)(X; kws...)
+    ## This will be overwritten by OperatorEnumConstructionModule, and turned
+    ## into a depwarn.
+    return error(
+        "The `tree(X; kws...)` syntax is deprecated. Use `tree(X, operators; kws...)` instead.",
+    )
+end
+
+# Gradients:
+function _grad_evaluator(tree::Node, X, operators::OperatorEnum; variable=true, kws...)
+    _, grad, did_complete = eval_grad_tree_array(
+        tree, X, operators; variable=variable, kws...
+    )
+    !did_complete && (grad .= convert(eltype(grad), NaN))
+    return grad
+end
+function _grad_evaluator(tree::Node, X, operators::GenericOperatorEnum; kws...)
+    return error("Gradients are not implemented for `GenericOperatorEnum`.")
+end
+function _grad_evaluator(tree::Node, X; kws...)
+    ## This will be overwritten by OperatorEnumConstructionModule, and turned
+    ## into a depwarn
+    return error(
+        "The `tree'(X; kws...)` syntax is deprecated. Use `tree'(X, operators; kws...)` instead.",
+    )
+end
+
+"""
+    (tree::Node{T})'(X::AbstractMatrix{T}, operators::OperatorEnum; turbo::Bool=false, variable::Bool=true)
+
+Compute the forward-mode derivative of an expression, using a similar
+structure and optimization to eval_tree_array. `variable` specifies whether
+we should take derivatives with respect to features (i.e., X), or with respect
+to every constant in the expression.
+
+# Arguments
+- `X::AbstractMatrix{T}`: The data matrix, with each column being a data point.
+- `operators::OperatorEnum`: The operators used to create the `tree`. Note that `operators.enable_autodiff`
+    must be `true`. This is needed to create the derivative operations.
+- `variable::Bool`: Whether to take derivatives with respect to features (i.e., `X` - with `variable=true`),
+    or with respect to every constant in the expression (`variable=false`).
+- `turbo::Bool`: Use `LoopVectorization.@turbo` for faster evaluation.
+
+# Returns
+
+- `(evaluation, gradient, complete)::Tuple{AbstractVector{T}, AbstractMatrix{T}, Bool}`: the normal evaluation,
+    the gradient, and whether the evaluation completed as normal (or encountered a nan or inf).
+"""
+Base.adjoint(tree::Node) = ((args...; kws...) -> _grad_evaluator(tree, args...; kws...))
+
+end

src/OperatorEnumConstruction.jl

@@ -5,27 +5,26 @@ import ..OperatorEnumModule: AbstractOperatorEnum, OperatorEnum, GenericOperator
 import ..EquationModule: string_tree, Node
 import ..EvaluateEquationModule: eval_tree_array
 import ..EvaluateEquationDerivativeModule: eval_grad_tree_array
+import ..EvaluationHelpersModule: _grad_evaluator
 
 function create_evaluation_helpers!(operators::OperatorEnum)
     @eval begin
         Base.print(io::IO, tree::Node) = print(io, string_tree(tree, $operators))
         Base.show(io::IO, tree::Node) = print(io, string_tree(tree, $operators))
         function (tree::Node)(X; kws...)
-            out, did_finish = eval_tree_array(tree, X, $operators; kws...)
-            if !did_finish
-                out .= convert(eltype(out), NaN)
-            end
-            return out
+            Base.depwarn(
+                "The `tree(X; kws...)` syntax is deprecated. Use `tree(X, operators; kws...)` instead.",
+                :Node,
+            )
+            return tree(X, $operators; kws...)
         end
         # Gradients:
-        function Base.adjoint(tree::Node{T}) where {T}
-            return (X; kws...) -> begin
-                _, grad, did_complete = eval_grad_tree_array(
-                    tree, X, $operators; variable=true, kws...
-                )
-                !did_complete && (grad .= T(NaN))
-                grad
-            end
+        function _grad_evaluator(tree::Node, X; kws...)
+            Base.depwarn(
+                "The `tree'(X; kws...)` syntax is deprecated. Use `tree'(X, operators; kws...)` instead.",
+                :Node,
+            )
+            return _grad_evaluator(tree, X, $operators; kws...)
         end
     end
 end
@@ -36,16 +35,14 @@ function create_evaluation_helpers!(operators::GenericOperatorEnum)
         Base.show(io::IO, tree::Node) = print(io, string_tree(tree, $operators))
 
         function (tree::Node)(X; kws...)
-            out, did_finish = eval_tree_array(tree, X, $operators; kws...)
-            if !did_finish
-                return nothing
-            end
-            return out
+            Base.depwarn(
+                "The `tree(X; kws...)` syntax is deprecated. Use `tree(X, operators; kws...)` instead.",
+                :Node,
+            )
+            return tree(X, $operators; kws...)
         end
-        function Base.adjoint(::Node{T}) where {T}
-            return _ -> begin
-                error("Gradients are not implemented for `GenericOperatorEnum`.")
-            end
+        function _grad_evaluator(tree::Node, X; kws...)
+            return error("Gradients are not implemented for `GenericOperatorEnum`.")
         end
     end
 end