docs: add documentation for HomotopyContinuation interface

Author: AayushSabharwal

ext/MTKHomotopyContinuationExt.jl

@@ -4,18 +4,22 @@ using ModelingToolkit
 using ModelingToolkit.SciMLBase
 using ModelingToolkit.Symbolics: unwrap
 using ModelingToolkit.SymbolicIndexingInterface
+using ModelingToolkit.DocStringExtensions
 using HomotopyContinuation
 using ModelingToolkit: iscomplete, parameters, has_index_cache, get_index_cache, get_u0,
                        get_u0_p, check_eqs_u0, CommonSolve
 
 const MTK = ModelingToolkit
 
 function contains_variable(x, wrt)
-    any(isequal(x), wrt) && return true
-    iscall(x) || return false
-    return any(y -> contains_variable(y, wrt), arguments(x))
+    any(y -> occursin(y, x), wrt)
 end
 
+"""
+$(TYPEDSIGNATURES)
+
+Check if `x` is polynomial with respect to the variables in `wrt`.
+"""
 function is_polynomial(x, wrt)
     x = unwrap(x)
     symbolic_type(x) == NotSymbolic() && return true
@@ -33,6 +37,11 @@ function is_polynomial(x, wrt)
     return false
 end
 
+"""
+$(TYPEDSIGNATURES)
+
+Convert `expr` from a symbolics expression to one that uses `HomotopyContinuation.ModelKit`.
+"""
 function symbolics_to_hc(expr)
     if iscall(expr)
         if operation(expr) == getindex
@@ -48,11 +57,32 @@ function symbolics_to_hc(expr)
     end
 end
 
+"""
+$(TYPEDEF)
+
+A subtype of `HomotopyContinuation.AbstractSystem` used to solve `HomotopyContinuationProblem`s.
+"""
 struct MTKHomotopySystem{F, P, J, V} <: HomotopyContinuation.AbstractSystem
+    """
+    The generated function for the residual of the polynomial system. In-place.
+    """
     f::F
+    """
+    The parameter object.
+    """
     p::P
+    """
+    The generated function for the jacobian of the polynomial system. In-place.
+    """
     jac::J
+    """
+    The `HomotopyContinuation.ModelKit.Variable` representation of the unknowns of
+    the system.
+    """
     vars::V
+    """
+    The number of polynomials in the system. Must also be equal to `length(vars)`.
+    """
     nexprs::Int
 end
 
@@ -74,8 +104,17 @@ end
 
 SymbolicIndexingInterface.parameter_values(s::MTKHomotopySystem) = s.p
 
+"""
+    $(TYPEDSIGNATURES)
+
+Create a `HomotopyContinuationProblem` from a `NonlinearSystem` with polynomial equations.
+The problem will be solved by HomotopyContinuation.jl. The resultant `NonlinearSolution`
+will contain the polynomial root closest to the point specified by `u0map` (if real roots
+exist for the system).
+"""
 function MTK.HomotopyContinuationProblem(
-        sys::NonlinearSystem, u0map, parammap; compile = :all, eval_expression = false, eval_module = ModelingToolkit, kwargs...)
+        sys::NonlinearSystem, u0map, parammap = nothing; eval_expression = false,
+        eval_module = ModelingToolkit, kwargs...)
     if !iscomplete(sys)
         error("A completed `NonlinearSystem` is required. Call `complete` or `structural_simplify` on the system before creating a `HomotopyContinuationProblem`")
     end
@@ -100,8 +139,21 @@ function MTK.HomotopyContinuationProblem(
     return MTK.HomotopyContinuationProblem(u0, mtkhsys, sys, obsfn)
 end
 
-function CommonSolve.solve(prob::MTK.HomotopyContinuationProblem; kwargs...)
-    sol = HomotopyContinuation.solve(prob.homotopy_continuation_system; kwargs...)
+"""
+$(TYPEDSIGNATURES)
+
+Solve a `HomotopyContinuationProblem`. Ignores the algorithm passed to it, and always
+uses `HomotopyContinuation.jl`. All keyword arguments are forwarded to
+`HomotopyContinuation.solve`. The original solution as returned by `HomotopyContinuation.jl`
+will be available in the `.original` field of the returned `NonlinearSolution`.
+
+All keyword arguments have their default values in HomotopyContinuation.jl, except
+`show_progress` which defaults to `false`.
+"""
+function CommonSolve.solve(prob::MTK.HomotopyContinuationProblem,
+        alg = nothing; show_progress = false, kwargs...)
+    sol = HomotopyContinuation.solve(
+        prob.homotopy_continuation_system; show_progress, kwargs...)
     realsols = HomotopyContinuation.results(sol; only_real = true)
     if isempty(realsols)
         u = state_values(prob)

src/systems/nonlinear/nonlinearsystem.jl

@@ -566,15 +566,37 @@ function Base.:(==)(sys1::NonlinearSystem, sys2::NonlinearSystem)
         all(s1 == s2 for (s1, s2) in zip(get_systems(sys1), get_systems(sys2)))
 end
 
-struct HomotopyContinuationProblem{uType, H, O} <: SciMLBase.AbstractNonlinearProblem{uType, true}
+"""
+$(TYPEDEF)
+
+A type of Nonlinear problem which specializes on polynomial systems and uses
+HomotopyContinuation.jl to solve the system. Requires importing HomotopyContinuation.jl to
+create and solve.
+"""
+struct HomotopyContinuationProblem{uType, H, O} <:
+       SciMLBase.AbstractNonlinearProblem{uType, true}
+    """
+    The initial values of states in the system. If there are multiple real roots of
+    the system, the one closest to this point is returned.
+    """
     u0::uType
+    """
+    A subtype of `HomotopyContinuation.AbstractSystem` to solve. Also contains the
+    parameter object.
+    """
     homotopy_continuation_system::H
+    """
+    The `NonlinearSystem` used to create this problem. Used for symbolic indexing.
+    """
     sys::NonlinearSystem
+    """
+    A function which generates and returns observed expressions for the given system.
+    """
     obsfn::O
 end
 
-function HomotopyContinuationProblem(args...; kwargs...)
-    error("Requires HomotopyContinuationExt")
+function HomotopyContinuationProblem(::AbstractSystem, _u0, _p; kwargs...)
+    error("HomotopyContinuation.jl is required to create and solve `HomotopyContinuationProblem`s. Please run `Pkg.add(\"HomotopyContinuation\")` to continue.")
 end
 
 SymbolicIndexingInterface.symbolic_container(p::HomotopyContinuationProblem) = p.sys