diff --git a/docs/src/manual/functions.md b/docs/src/manual/functions.md index 4238f84f1..4204bf92e 100644 --- a/docs/src/manual/functions.md +++ b/docs/src/manual/functions.md @@ -151,7 +151,7 @@ Note that at this time array derivatives cannot be defined. ## Direct Registration API (Advanced, Experimental) -!!! warn +!!! warning This is a lower level API which is not as stable as the macro APIs. diff --git a/docs/src/manual/parsing.md b/docs/src/manual/parsing.md index 921fe32ba..a37ad0d13 100644 --- a/docs/src/manual/parsing.md +++ b/docs/src/manual/parsing.md @@ -7,10 +7,10 @@ to convert from Julia expressions to Symbolics.jl expressions for further manipulation. Towards this end is the `parse_expr_to_symbolic` which performs the parsing. -!!! warn +!!! warning Take the limitations mentioned in the `parse_expr_to_symbolic` docstrings seriously! Because Julia expressions contain no symbolic metadata, there - is limited information and thus the parsing requires heuristics to work. + is limited information and thus the parsing requires heuristics to work. ```@docs parse_expr_to_symbolic diff --git a/src/Symbolics.jl b/src/Symbolics.jl index c34c33d40..5f1b8a35f 100644 --- a/src/Symbolics.jl +++ b/src/Symbolics.jl @@ -68,7 +68,7 @@ include("complex.jl") Performs the substitution on `expr` according to rule(s) `s`. # Examples -```julia +```jldoctest julia> @variables t x y z(t) 4-element Vector{Num}: t diff --git a/src/arrays.jl b/src/arrays.jl index 0518bb48e..261520468 100644 --- a/src/arrays.jl +++ b/src/arrays.jl @@ -426,7 +426,7 @@ end """ shape(s::Any) -Returns `axes(s)` or Unknown(). +Returns `axes(s)` or `Unknown()`. """ shape(s) = axes(s) diff --git a/src/build_function.jl b/src/build_function.jl index 06b433b1c..ffb21142b 100644 --- a/src/build_function.jl +++ b/src/build_function.jl @@ -34,18 +34,14 @@ function throw_missing_specialization(n) end """ -`build_function` + build_function(ex, args...; + expression = Val{true}, + target = JuliaTarget(), + parallel=nothing, + kwargs...) Generates a numerically-usable function from a Symbolics `Num`. -```julia -build_function(ex, args...; - expression = Val{true}, - target = JuliaTarget(), - parallel=nothing, - kwargs...) -``` - Arguments: - `ex`: The `Num` to compile @@ -220,16 +216,16 @@ end Build function target: `JuliaTarget` ```julia -function _build_function(target::JuliaTarget, rhss, args...; - conv = toexpr, - expression = Val{true}, - checkbounds = false, - linenumbers = false, - headerfun = addheader, outputidxs=nothing, - convert_oop = true, force_SA = false, - skipzeros = outputidxs===nothing, - fillzeros = skipzeros && !(typeof(rhss)<:SparseMatrixCSC), - parallel=SerialForm(), kwargs...) +_build_function(target::JuliaTarget, rhss, args...; + conv = toexpr, + expression = Val{true}, + checkbounds = false, + linenumbers = false, + headerfun = addheader, outputidxs=nothing, + convert_oop = true, force_SA = false, + skipzeros = outputidxs===nothing, + fillzeros = skipzeros && !(typeof(rhss)<:SparseMatrixCSC), + parallel=SerialForm(), kwargs...) ``` Generates a Julia function which can then be utilized for further evaluations. @@ -676,11 +672,11 @@ end Build function target: `CTarget` ```julia -function _build_function(target::CTarget, eqs::Array{<:Equation}, args...; - conv = toexpr, expression = Val{true}, - fname = :diffeqf, - lhsname=:du,rhsnames=[Symbol("RHS\$i") for i in 1:length(args)], - libpath=tempname(),compiler=:gcc) +_build_function(target::CTarget, eqs::Array{<:Equation}, args...; + conv = toexpr, expression = Val{true}, + fname = :diffeqf, + lhsname=:du,rhsnames=[Symbol("RHS\$i") for i in 1:length(args)], + libpath=tempname(), compiler=:gcc) ``` This builds an in-place C function. Only works on arrays of equations. If @@ -689,7 +685,7 @@ and returns a lambda to that compiled function. These special keyword arguments control the compilation: - libpath: the path to store the binary. Defaults to a temporary path. -- compiler: which C compiler to use. Defaults to :gcc, which is currently the +- compiler: which C compiler to use. Defaults to `:gcc`, which is currently the only available option. """ function _build_function(target::CTarget, eqs::Array{<:Equation}, args...; @@ -736,15 +732,15 @@ end Build function target: `CTarget` ```julia -function _build_function(target::CTarget, ex::AbstractArray, args...; - columnmajor = true, - conv = toexpr, - expression = Val{true}, - fname = :diffeqf, - lhsname = :du, - rhsnames = [Symbol("RHS\$i") for i in 1:length(args)], - libpath = tempname(), - compiler = :gcc) +_build_function(target::CTarget, ex::AbstractArray, args...; + columnmajor = true, + conv = toexpr, + expression = Val{true}, + fname = :diffeqf, + lhsname = :du, + rhsnames = [Symbol("RHS\$i") for i in 1:length(args)], + libpath = tempname(), + compiler = :gcc) ``` This builds an in-place C function. Only works on expressions. If @@ -823,14 +819,14 @@ _build_function(target::CTarget, ex::Num, args...; kwargs...) = _build_function( Build function target: `StanTarget` ```julia -function _build_function(target::StanTarget, eqs::Array{<:Equation}, vs, ps, iv; - conv = toexpr, expression = Val{true}, - fname = :diffeqf, lhsname=:internal_var___du, - rhsnames=[:internal_var___u,:internal_var___p,:internal_var___t]) +_build_function(target::StanTarget, eqs::Array{<:Equation}, vs, ps, iv; + conv = toexpr, expression = Val{true}, + fname = :diffeqf, lhsname=:internal_var___du, + rhsnames=[:internal_var___u,:internal_var___p,:internal_var___t]) ``` This builds an in-place Stan function compatible with the Stan differential equation solvers. -Unlike other build targets, this one requires (vs, ps, iv) as the function arguments. +Unlike other build targets, this one requires `(vs, ps, iv)` as the function arguments. Only allowed on arrays of equations. """ function _build_function(target::StanTarget, eqs::Array{<:Equation}, vs, ps, iv; @@ -862,16 +858,16 @@ end Build function target: `StanTarget` ```julia -function _build_function(target::StanTarget, ex::AbstractArray, vs, ps, iv; - columnmajor = true, - conv = toexpr, - expression = Val{true}, - fname = :diffeqf, lhsname=:internal_var___du, - rhsnames = [:internal_var___u,:internal_var___p,:internal_var___t]) +_build_function(target::StanTarget, ex::AbstractArray, vs, ps, iv; + columnmajor = true, + conv = toexpr, + expression = Val{true}, + fname = :diffeqf, lhsname=:internal_var___du, + rhsnames = [:internal_var___u,:internal_var___p,:internal_var___t]) ``` This builds an in-place Stan function compatible with the Stan differential equation solvers. -Unlike other build targets, this one requires (vs, ps, iv) as the function arguments. +Unlike other build targets, this one requires `(vs, ps, iv)` as the function arguments. Only allowed on expressions, and arrays of expressions. """ function _build_function(target::StanTarget, ex::AbstractArray, vs, ps, iv; @@ -920,13 +916,13 @@ _build_function(target::StanTarget, ex::Num, vs, ps, iv; kwargs...) = _build_fun Build function target: `MATLABTarget` ```julia -function _build_function(target::MATLABTarget, eqs::Array{<:Equation}, args...; - conv = toexpr, expression = Val{true}, - lhsname=:internal_var___du, - rhsnames=[:internal_var___u,:internal_var___p,:internal_var___t]) +_build_function(target::MATLABTarget, eqs::Array{<:Equation}, args...; + conv = toexpr, expression = Val{true}, + lhsname=:internal_var___du, + rhsnames=[:internal_var___u,:internal_var___p,:internal_var___t]) ``` -This builds an out of place anonymous function @(t,rhsnames[1]) to be used in MATLAB. +This builds an out of place anonymous function `@(t,rhsnames[1])` to be used in MATLAB. Compatible with the MATLAB differential equation solvers. Only allowed on expressions, and arrays of expressions. """ @@ -953,13 +949,13 @@ end Build function target: `MATLABTarget` ```julia -function _build_function(target::MATLABTarget, ex::AbstractArray, args...; - columnmajor = true, - conv = toexpr, - expression = Val{true}, - fname = :diffeqf, - lhsname = :internal_var___du, - rhsnames = [:internal_var___u,:internal_var___p,:internal_var___t]) +_build_function(target::MATLABTarget, ex::AbstractArray, args...; + columnmajor = true, + conv = toexpr, + expression = Val{true}, + fname = :diffeqf, + lhsname = :internal_var___du, + rhsnames = [:internal_var___u,:internal_var___p,:internal_var___t]) ``` This builds an out of place anonymous function @(t,rhsnames[1]) to be used in MATLAB. diff --git a/src/diff.jl b/src/diff.jl index de2a4c091..3845ae8b1 100644 --- a/src/diff.jl +++ b/src/diff.jl @@ -170,13 +170,13 @@ and other derivative rules to expand any derivatives it encounters. ```jldoctest julia> @variables x y z k; -julia> f=k*(abs(x-y)/y-z)^2 +julia> f = k*(abs(x-y)/y-z)^2 k*((abs(x - y) / y - z)^2) -julia> Dx=Differential(x) # Differentiate wrt x +julia> Dx = Differential(x) # Differentiate wrt x (::Differential) (generic function with 2 methods) -julia> dfx=expand_derivatives(Dx(f)) +julia> dfx = expand_derivatives(Dx(f)) (k*((2abs(x - y)) / y - 2z)*IfElse.ifelse(signbit(x - y), -1, 1)) / y ``` """ diff --git a/src/linear_algebra.jl b/src/linear_algebra.jl index 2b37a9b9a..821a77322 100644 --- a/src/linear_algebra.jl +++ b/src/linear_algebra.jl @@ -83,7 +83,7 @@ Currently only works if all equations are linear. `check` if the expr is linear w.r.t `vars`. # Examples -```julia +```jldoctest julia> @variables x y 2-element Vector{Num}: x diff --git a/src/operators.jl b/src/operators.jl index 11b2c08f4..dfd8cc3ff 100644 --- a/src/operators.jl +++ b/src/operators.jl @@ -32,7 +32,7 @@ end Get the time (in seconds) spent in a state in a finite state machine. When used to query the time spent in the enclosing state, the method without arguments is used, i.e., -``` +```julia @mtkmodel FSM begin ... @equations begin @@ -56,7 +56,7 @@ timeInState Get the number of ticks spent in a state in a finite state machine. When used to query the number of ticks spent in the enclosing state, the method without arguments is used, i.e., -``` +```julia @mtkmodel FSM begin ... @equations begin diff --git a/src/rewrite-helpers.jl b/src/rewrite-helpers.jl index 9cfe72ecb..07d50ab6a 100644 --- a/src/rewrite-helpers.jl +++ b/src/rewrite-helpers.jl @@ -1,5 +1,6 @@ """ -replacenode(expr::Symbolic, rules...) + replacenode(expr::Symbolic, rules...) + Walk the expression and replacenode subexpressions according to `rules`. `rules` could be rules constructed with `@rule`, a function, or a pair where the left hand side is matched with equality (using `isequal`) and is replacenoded by the right hand side. @@ -75,7 +76,8 @@ function _hasnode(r, y) end """ -filterchildren(c, x) + filterchildren(c, x) + Returns all parts of `x` that fulfills the condition given in c. c can be a function or an expression. If it is a function, returns everything for which the function is `true`. If c is an expression, returns all expressions that matches it. diff --git a/src/taylor.jl b/src/taylor.jl index cbb95dc4e..242a27d71 100644 --- a/src/taylor.jl +++ b/src/taylor.jl @@ -10,7 +10,7 @@ Return the power series in `x` around `x0` to the powers `ns` with coefficients Examples ======== -```julia +```jldoctest julia> @variables x y[0:3] z 3-element Vector{Any}: x @@ -47,7 +47,7 @@ Calculate the `n`-th order coefficient(s) in the Taylor series of `f` around `x Examples ======== -```julia +```jldoctest julia> @variables x y 2-element Vector{Num}: x @@ -101,7 +101,7 @@ If `rationalize`, float coefficients are approximated as rational numbers (this Examples ======== -```julia +```jldoctest julia> @variables x 1-element Vector{Num}: x diff --git a/src/utils.jl b/src/utils.jl index 17d91a971..e625062a1 100644 --- a/src/utils.jl +++ b/src/utils.jl @@ -27,7 +27,7 @@ Return a vector of variables appearing in `e`, optionally restricting to variabl Note that the returned variables are not wrapped in the `Num` type. # Examples -```julia +```jldoctest julia> @variables t x y z(t); julia> Symbolics.get_variables(x + y + sin(z); sort = true) @@ -97,7 +97,7 @@ Convert a differential variable to a `Term`. Note that it only takes a `Term` not a `Num`. Any upstream metadata can be passed via `x_metadata` -```julia +```jldoctest julia> @variables x t u(x, t) z(t)[1:2]; Dt = Differential(t); Dx = Differential(x); julia> Symbolics.diff2term(Symbolics.value(Dx(Dt(u)))) @@ -156,7 +156,7 @@ it will only output `y` instead of `y(t)`. # Examples -```julia +```jldoctest julia> @variables t z(t) 2-element Vector{Num}: t @@ -251,7 +251,7 @@ Extract the degree of `p` with respect to `sym`. # Examples -```julia +```jldoctest julia> @variables x; julia> Symbolics.degree(x^0) @@ -305,7 +305,7 @@ Note that `p` might need to be expanded and/or simplified with `expand` and/or ` # Examples -```julia +```jldoctest julia> @variables a x y; julia> Symbolics.coeff(2a, x) diff --git a/src/variable.jl b/src/variable.jl index 489a072de..1760724ed 100644 --- a/src/variable.jl +++ b/src/variable.jl @@ -418,7 +418,7 @@ expr = β[1]* x + y^α + σ(3) * (z - t) - β[2] * w(t - 1) Symbolics supports creating variables that denote an array of some size. -```julia +```jldoctest julia> @variables x[1:3] 1-element Vector{Symbolics.Arr{Num, 1}}: x[1:3] @@ -436,7 +436,7 @@ julia> @variables t z(t)[1:3] # also works for dependent variables A symbol or expression that represents an array can be turned into an array of symbols or expressions using the `scalarize` function. -```julia +```jldoctest julia> Symbolics.scalarize(z) 3-element Vector{Num}: (z(t))[1] @@ -451,7 +451,7 @@ operator, and in this case, `@variables` doesn't automatically assign the value, instead, it only returns a vector of symbolic variables. All the rest of the syntax also applies here. -```julia +```jldoctest julia> a, b, c = :runtime_symbol_value, :value_b, :value_c (:runtime_symbol_value, :value_b, :value_c) @@ -676,7 +676,7 @@ notation. Use `@variables` instead to create symbolic array variables (as opposed to array of variables). See `variable` to create one variable with subscripts. -```julia-repl +```jldoctest julia> Symbolics.variables(:x, 1:3, 3:6) 3×4 Matrix{Num}: x₁ˏ₃ x₁ˏ₄ x₁ˏ₅ x₁ˏ₆ @@ -694,7 +694,7 @@ end Create a variable with the given name along with subscripted indices with the `symtype=T`. When `T=FnType`, it creates a symbolic function. -```julia-repl +```jldoctest julia> Symbolics.variable(:x, 4, 2, 0) x₄ˏ₂ˏ₀