Are the Symbolics.jl docs outdated?

New to Julia
1

I’m relatively new to Julia and have been having some trouble following the docs for Symbolics.jl ; not sure if I am misunderstanding something.

(I am looking at the “stable” version of Symbolics.jl docs, in the “variables” section of the Manual; I couldn’t include a link in the post. Though this question also applies to the ? help docs in the REPL since the docs there look identical.)

Examples:
[TermInterface.iscall]
the “examples” section for iscall returns “false” on all their examples when I run them - if I apply Symbolics.value(…) or Symbolics.unwrap(…) to the arg, I can reproduce the intended returns. Is this from an outdated version of Symbolics or something else?

[TermInterface.arguments]
Likewise, the Examples section on arguments doesn’t work for me - I see “MethodError: no method matching arguments(::Num)”; and likewise, if I wrap the args in Symbolics.value(…), they work.

Am I missing something here, or are possibly some of these docs outdated? Any suggestions to a newcomer trying to become acquainted with Symbolics but a little disconcerted with some of the docs examples (or advice on when to trust docs etc)? Thanks!

2

@cryptic.ax looks like we missed a spot.

all docs have something outdated. Just open an issue if you find something.

3

Yeah that docstring is wrong. Even Symbolics v6 didn’t support iscall on Num. The docstring is in SymbolicUtils and should use @syms.

4

thanks so much.

edit: I asked a question about not being able to find @register_derivative, but then I realized it’s quite new and I had a slightly outdated version of Symbolics.

I guess you can really make things weird with something like

@register_derivative sin(x) 1 exp(x)

wonder if there is any use case for such things (or not).

5

@register_derivative is for defining custom derivatives for functions you own. Implementing it for others’ functions is type-piracy. Specifically for sin(x), this will also break precompilation due to method overwriting, since Symbolics already defines the @register_derivative for sin(x)

6

OK. I am not sure if I understand the “break precompilation” statement; I can run this:


julia> @register_derivative sin(x) 1 exp(x)

julia> Dx = Differential(x)
Differential(x, 1)

julia> Dx(sin(x))
Differential(x, 1)(sin(x))

julia> expand_derivatives(Dx(sin(x)))
exp(x)

julia> sin
sin (generic function with 21 methods) #showing this is the builtin

in any case, the first example in the @register_derivative docstring uses the sin(x) example and doesn’t warn against this, which encouraged me to try it out with already registered functions.

Or perhaps do you mean that if I were to do this in a package, then precompiling that package would fail?

In any case thanks so much for the helpful clarifications!