Merge pull request #51 from shahriariravanian/main

docstrings fixed

Author: shahriariravanian

Project.toml

@@ -1,7 +1,7 @@
 name = "SymbolicNumericIntegration"
 uuid = "78aadeae-fbc0-11eb-17b6-c7ec0477ba9e"
 authors = ["Shahriar Iravanian <[email protected]>"]
-version = "1.2.0"
+version = "1.2.1"
 
 [deps]
 DataDrivenDiffEq = "2445eb08-9709-466a-b3fc-47e12bd697a2"

docs/make.jl

@@ -11,7 +11,7 @@ makedocs(sitename = "SymbolicNumericIntegration.jl",
          clean = true, doctest = false, linkcheck = true,
          strict = [
              :doctest,
-             # :linkcheck,
+             :linkcheck,
              :parse_error,
              :example_block,
              # Other available options are

docs/src/index.md

@@ -16,6 +16,8 @@ using Pkg
 Pkg.add("SymbolicNumericIntegration")
 ```
 
+Examples:
+
 ```julia
 using Symbolics
 using SymbolicNumericIntegration
@@ -90,21 +92,9 @@ julia> integrate(1 / (x*log(log(x))))
 (SymbolicNumericIntegration.Li(log(x)), 0, 1.1102230246251565e-16)
 ```
 
-`integrate` has the form `integrate(y; kw...)` or `integrate(y, x; kw...)`, where `y` is the integrand and the optional `x` is the variable of integration. The keyword parameters are:
-
-  - `abstol` (default `1e-6`): the error tolerance to accept a solution.
-  - `symbolic` (default `true`): if true, pure symbolic integration is attempted first.
-  - `bypass` (default `false`): if true, the whole expression is considered at once and not per term.
-  - `num_steps` (default `2`): one plus the number of expanded basis to check (if `num_steps` is 1, only the main basis is checked).
-  - `num_trials` (default `5`): the number of attempts to solve the integration numerically for each basis set.
-  - `show_basis` (default `false`): print the basis set, useful for debugging. Only works if `verbose` is also set.
-  - `homotopy` (default: `true` as of version 0.7.0): uses the continuous Homotopy operators to generate the integration candidates.
-  - `verbose` (default `false`): if true, prints extra (and voluminous!) debugging information.
-  - `radius` (default `1.0`): the starting radius to generate random test points.
-  - `opt` (default `STLSQ(exp.(-10:1:0))`): the optimizer passed to `sparse_regression!`.
-  - `max_basis` (default `110`): the maximum number of expression in the basis.
-  - `complex_plane` (default `true`): random test points are generated on the complex plane (only over the real axis if `complex_plane` is `false`).
-  - `use_optim` (default `false`): use Optim.jl `minimize` function instead of the STLSQ algorithm (**experimental**)
+```@docs
+integrate(eq, x; kwargs...)
+```
 
 ## Testing
 

src/integral.jl

@@ -5,33 +5,39 @@ Base.signbit(z::Complex{T}) where {T <: Number} = signbit(real(z))
 Base.signbit(x::SymbolicUtils.Sym{Number}) = false
 
 """
-    integrate is the main entry point
-
-    input:
-    ------
-    eq: a Symbolics expression to integrate
-    x: the independent variable (optional)
-
-    abstol: the desired tolerance
-    num_steps: the number of different steps with expanding basis to be tried
-    num_trials: the number of trials in each step (no changes to the basis)
-    radius: the radius of the disk in the complex plane to generate random test points
-    show_basis: if true, the basis (list of candidate terms) is printed
-    opt: the sparse regression optimizer
-    bypass: if true, do not integrate terms separately but consider all at once
-    symbolic: try symbolic integration first
-    max_basis: the maximum number of candidate terms to consider
-    verbose: print a detailed report
-    complex_plane: generate random test points on the complex plane (if false, the points will be on real axis)
-    homotopy: use the homotopy algorithm to generate the basis (deprecated)
-    use_optim: use Optim.jl `minimize` function instead of the STLSQ algorithm (**experimental**)
-
-    output:
-    -------
-    solved, unsolved, err
-
-    solved is the solved integral and unsolved is the residual unsolved portion of the input
-    err is the numerical error in reaching the solution
+    integrate(eq, x; kwargs...)
+   
+is the main entry point to integrate a univariate expression `eq` with respect to `x' (optional). 
+
+```julia
+integrate(x * sin(2x))
+
+# output
+
+((1//4)*sin(2x) - (1//2)*x*cos(2x), 0, 0)
+```
+
+kwards:
+-------
+abstol: the desired tolerance
+num_steps: the number of different steps with expanding basis to be tried
+num_trials: the number of trials in each step (no changes to the basis)
+radius: the radius of the disk in the complex plane to generate random test points
+show_basis: if true, the basis (list of candidate terms) is printed
+opt: the sparse regression optimizer (from DataDrivenSparse)
+bypass: if true do not integrate terms separately but consider all at once
+symbolic: try symbolic integration first
+max_basis: the maximum number of candidate terms to consider
+verbose: print a detailed report
+complex_plane: generate random test points on the complex plane (if false, the points will be on real axis)
+homotopy: use the homotopy algorithm to generate the basis (deprecated, will be removed in a future version)
+use_optim: use Optim.jl `minimize` function instead of the STLSQ algorithm (**experimental**)
+
+output:
+-------
+solved: the solved integral 
+unsolved: the residual unsolved portion of the input
+err: the numerical error in reaching the solution
 """
 function integrate(eq, x = nothing; abstol = 1e-6, num_steps = 2, num_trials = 10,
                    radius = 1.0,
@@ -65,13 +71,17 @@ function integrate(eq, x = nothing; abstol = 1e-6, num_steps = 2, num_trials = 1
 end
 
 """
-    integrate_sum applies the integral summation rule ∫ Σᵢ fᵢ(x) dx = Σᵢ ∫ fᵢ(x) dx
+    integrate_sum(eq, x, l; kwargs...) 
 
-    eq: the integrand
-    x: the indepedent variable
-    l: a logger
+applies the integral summation rule ∫ Σᵢ fᵢ(x) dx = Σᵢ ∫ fᵢ(x) dx
 
-    output is the same as integrate
+inputs:
+------
+eq: the integrand
+x: the indepedent variable
+l: a logger
+
+output is the same as `integrate`
 """
 function integrate_sum(eq, x, l; bypass = false, kwargs...)
     solved = 0
@@ -122,14 +132,18 @@ function integrate_sum(eq, x, l; bypass = false, kwargs...)
 end
 
 """
-    integrate_term is the central part of the code that tries different
-    methods to integrate eq
-
-    eq: the integrand
-    x: the indepedent variable
-    l: a logger
-
-    output is the same as integrate
+    integrate_term(eq, x, l; kwargs...) 
+    
+is the central part of the code that tries different methods to integrate `eq`,
+which is assume to be a single term.
+
+inputs:
+-------
+eq: the integrand
+x: the indepedent variable
+l: a logger
+
+output is the same as `integrate`
 """
 function integrate_term(eq, x, l; kwargs...)
     args = Dict(kwargs)
@@ -230,13 +244,15 @@ end
 ###############################################################################
 
 """
-	1try_integrate` is the main dispatch point to call different sparse solvers	
-    `try_integrate` tries to find a linear combination of the basis, whose
-    derivative is equal to eq
-
-    output
-    -------
-    integral, error
+	try_integrate(eq, x, basis, radius; kwargs...) 
+	
+is the main dispatch point to call different sparse solvers. It tries to 
+find a linear combination of the basis, whose derivative is equal to eq
+
+output:
+-------
+solved: the solved integration problem or 0 otherwise
+err: the numerical error in reaching the solution
 """
 function try_integrate(eq, x, basis, radius; kwargs...)
     args = Dict(kwargs)
@@ -256,7 +272,9 @@ end
 #################################################################################
 
 """
-	integrate_basis is used for debugging and should not be called in the course of normal execution
+	integrate_basis(eq, x; kwargs...)
+	
+is used for debugging and should not be called in the course of normal execution
 """
 function integrate_basis(eq, x = var(eq); abstol = 1e-6, radius = 1.0, complex_plane = true)
     eq = cache(expand(eq))