SemOptimizer: cleanup docstrings

Author: Alexey Stukalov

ext/SEMNLOptExt/NLopt.jl

@@ -4,12 +4,22 @@
 
 const NLoptConstraint = Pair{Any, Number}
 
-"""
-Uses *NLopt.jl* as the optimization engine.
-Only available if *NLopt.jl* is loaded in the current Julia session!
+struct SemOptimizerNLopt <: SemOptimizer{:NLopt}
+    algorithm::Symbol
+    local_algorithm::Union{Symbol, Nothing}
+    options::Dict{Symbol, Any}
+    local_options::Dict{Symbol, Any}
+    equality_constraints::Vector{NLoptConstraint}
+    inequality_constraints::Vector{NLoptConstraint}
+end
+
+SEM.sem_optimizer_subtype(::Val{:NLopt}) = SemOptimizerNLopt
 
-# Constructor
+############################################################################################
+### Constructor
+############################################################################################
 
+"""
     SemOptimizer(;
         engine = :NLopt,
         algorithm = :LD_LBFGS,
@@ -21,6 +31,10 @@ Only available if *NLopt.jl* is loaded in the current Julia session!
         constraint_tol::Number = 0.0,
         kwargs...)
 
+Uses *NLopt.jl* as the optimization engine. For more information on the available algorithms
+and options, see the [*NLopt.jl*](https://github.com/JuliaOpt/NLopt.jl) package and
+the [NLopt docs](https://nlopt.readthedocs.io/en/latest/).
+
 # Arguments
 - `algorithm`: optimization algorithm.
 - `options::Dict{Symbol, Any}`: options for the optimization algorithm
@@ -38,8 +52,10 @@ Each constraint could be a function or any other callable object that
 takes the two input arguments:
   - the vector of the model parameters;
   - the array for the in-place calculation of the constraint gradient.
-To override the default tolerance, the constraint could be specified
+To override the default tolerance, the constraint can be specified
 as a pair of the function and its tolerance: `constraint_func => tol`.
+For information on how to use inequality and equality constraints,
+see [Constrained optimization](@ref) in our online documentation.
 
 # Example
 ```julia
@@ -55,42 +71,14 @@ my_constrained_optimizer = SemOptimizer(;
 )
 ```
 
-# Usage
-All algorithms and options from the *NLopt* library are available, for more information see
-the [*NLopt.jl*](https://github.com/JuliaOpt/NLopt.jl) package and the
-[NLopt docs](https://nlopt.readthedocs.io/en/latest/).
-For information on how to use inequality and equality constraints,
-see [Constrained optimization](@ref) in our online documentation.
-
-# Extended help
-
-## Interfaces
+# Interfaces
 - `algorithm(::SemOptimizerNLopt)`
 - `local_algorithm(::SemOptimizerNLopt)`
 - `options(::SemOptimizerNLopt)`
 - `local_options(::SemOptimizerNLopt)`
 - `equality_constraints(::SemOptimizerNLopt)`
 - `inequality_constraints(::SemOptimizerNLopt)`
-
-## Implementation
-
-Subtype of `SemOptimizer`.
 """
-struct SemOptimizerNLopt <: SemOptimizer{:NLopt}
-    algorithm::Symbol
-    local_algorithm::Union{Symbol, Nothing}
-    options::Dict{Symbol, Any}
-    local_options::Dict{Symbol, Any}
-    equality_constraints::Vector{NLoptConstraint}
-    inequality_constraints::Vector{NLoptConstraint}
-end
-
-SEM.sem_optimizer_subtype(::Val{:NLopt}) = SemOptimizerNLopt
-
-############################################################################################
-### Constructor
-############################################################################################
-
 function SemOptimizerNLopt(;
     algorithm = :LD_LBFGS,
     local_algorithm = nothing,

ext/SEMProximalOptExt/ProximalAlgorithms.jl

@@ -1,35 +1,30 @@
 ############################################################################################
 ### Types
 ############################################################################################
-"""
-Connects to `ProximalAlgorithms.jl` as the optimization backend.
-
-Can be used for regularized SEM, for a tutorial see the online docs on [Regularization](@ref).
-
-# Constructor
+mutable struct SemOptimizerProximal{A, B, C} <: SemOptimizer{:Proximal}
+    algorithm::A
+    operator_g::B
+    operator_h::C
+end
 
+"""
     SemOptimizerProximal(;
         algorithm = ProximalAlgorithms.PANOC(),
         operator_g,
         operator_h = nothing,
         kwargs...,
+    )
+
+Connects to `ProximalAlgorithms.jl` as the optimization backend. For more information on
+the available algorithms and options, see the online docs on [Regularization](@ref) and
+the documentation of [*ProximalAlgorithms.jl*](https://github.com/JuliaFirstOrder/ProximalAlgorithms.jl) /
+[ProximalOperators.jl](https://github.com/JuliaFirstOrder/ProximalOperators.jl).
 
 # Arguments
-- `algorithm`: optimization algorithm.
+- `algorithm`: proximal optimization algorithm.
 - `operator_g`: proximal operator (e.g., regularization penalty)
 - `operator_h`: optional second proximal operator
-
-# Usage
-All algorithms and operators from `ProximalAlgorithms.jl` are available,
-for more information see the online docs on [Regularization](@ref) and
-the documentation of `ProximalAlgorithms.jl` / `ProximalOperators.jl`.
 """
-mutable struct SemOptimizerProximal{A, B, C} <: SemOptimizer{:Proximal}
-    algorithm::A
-    operator_g::B
-    operator_h::C
-end
-
 SemOptimizerProximal(;
     algorithm = ProximalAlgorithms.PANOC(),
     operator_g,

src/optimizer/Empty.jl

@@ -1,13 +1,11 @@
 ############################################################################################
 ### Types
 ############################################################################################
-"""
-Empty placeholder for models that don't need
-an optimizer part.
 
-# Constructor
+"""
+    SemOptimizer(engine = :Empty)
 
-    SemOptimizerEmpty()
+Constructs a dummy placeholder optimizer for models that don't need it.
 """
 struct SemOptimizerEmpty <: SemOptimizer{:Empty} end
 

src/optimizer/abstract.jl

@@ -21,6 +21,30 @@ sem_optimizer_subtype(engine::Symbol) = sem_optimizer_subtype(Val(engine))
 # fallback method for unsupported engines
 sem_optimizer_subtype(::Val{E}) where {E} = throw_engine_error(E)
 
+"""
+    SemOptimizer(args...; engine::Symbol = :Optim, kwargs...)
+
+Constructs a `SemOptimizer` object that can be passed to [`fit`](@ref) for specifying aspects
+of the numerical optimization involved in fitting a SEM.
+
+The keyword `engine` controlls which Julia package is used, with `:Optim` being the default.
+- [`optimizer_engines()`](@ref optimizer_engines) prints a list of currently available engines.
+- [`optimizer_engine_doc(EngineName)`](@ref optimizer_engine_doc) prints information on the usage of a specific engine.
+
+More engines become available if specific packages are loaded, for example
+[*NLopt.jl*](https://github.com/JuliaOpt/NLopt.jl) (also see [Constrained optimization](@ref)
+in the online documentation) or
+[*ProximalAlgorithms.jl*](https://github.com/JuliaFirstOrder/ProximalAlgorithms.jl)
+(also see [Regularization](@ref) in the online documentation).
+
+The arguments `args...` and `kwargs...` are engine-specific and control further
+aspects of the optimization process, such as the algorithm, convergence criteria or constraints.
+Information on those can be accessed with [`optimizer_engine_doc`](@ref).
+
+[Custom optimizer types](@ref) shows how to connect the *SEM.jl* package to a completely new optimization engine.
+"""
+SemOptimizer
+
 # default constructor that dispatches to the engine-specific type
 SemOptimizer(::Val{E}, args...; kwargs...) where {E} =
     sem_optimizer_subtype(E)(args...; kwargs...)

src/optimizer/optim.jl

@@ -3,66 +3,52 @@
 ############################################################################################
 ### Types and Constructor
 ############################################################################################
-"""
-    SemOptimizerOptim{A, B} <: SemOptimizer{:Optim}
-
-Connects to `Optim.jl` as the optimization backend.
 
-# Constructor
+# SemOptimizer for the Optim.jl
+mutable struct SemOptimizerOptim{A, B} <: SemOptimizer{:Optim}
+    algorithm::A
+    options::B
+end
 
-    SemOptimizerOptim(;
+"""
+    SemOptimizer(;
+        engine = :Optim,
         algorithm = LBFGS(),
         options = Optim.Options(;f_reltol = 1e-10, x_abstol = 1.5e-8),
         kwargs...)
 
+Connects to *Optim.jl* as the optimization engine.
+
+For more information on the available algorithms and options,
+see the [*Optim.jl* docs](https://julianlsolvers.github.io/Optim.jl/stable/).
+
 # Arguments
-- `algorithm`: optimization algorithm from `Optim.jl`
+- `algorithm`: optimization algorithm from *Optim.jl*
 - `options::Optim.Options`: options for the optimization algorithm
 
-# Usage
-All algorithms and options from the Optim.jl library are available, for more information see
-the Optim.jl online documentation.
-
 # Examples
 ```julia
-my_optimizer = SemOptimizerOptim()
-
 # hessian based optimization with backtracking linesearch and modified initial step size
 using Optim, LineSearches
 
-my_newton_optimizer = SemOptimizerOptim(
+my_newton_optimizer = SemOptimizer(
+    engine = :Optim,
     algorithm = Newton(
         ;linesearch = BackTracking(order=3),
         alphaguess = InitialHagerZhang()
     )
 )
 ```
 
-# Extended help
-
-## Constrained optimization
-
+# Constrained optimization
 When using the `Fminbox` or `SAMIN` constrained optimization algorithms,
 the vector or dictionary of lower and upper bounds for each model parameter can be specified
 via `lower_bounds` and `upper_bounds` keyword arguments.
 Alternatively, the `lower_bound` and `upper_bound` keyword arguments can be used to specify
 the default bound for all non-variance model parameters,
 and the `variance_lower_bound` and `variance_upper_bound` keyword --
 for the variance parameters (the diagonal of the *S* matrix).
-
-## Interfaces
-- `algorithm(::SemOptimizerOptim)`
-- `options(::SemOptimizerOptim)`
-
-## Implementation
-
-Subtype of `SemOptimizer`.
 """
-mutable struct SemOptimizerOptim{A, B} <: SemOptimizer{:Optim}
-    algorithm::A
-    options::B
-end
-
 SemOptimizerOptim(;
     algorithm = LBFGS(),
     options = Optim.Options(; f_reltol = 1e-10, x_abstol = 1.5e-8),