add more docstrings, add capabilities to save iteration count for sin…

…gle solvers

src/analysis/setup.jl

@@ -70,16 +70,16 @@ function setup_analysis(
     (; prepost_container_cache, prepost_container_cache_dims) = prepost_container_caching
 
     # Get correct cached types
-    prepost_container_cache_vec = @views PreallocationTools.get_tmp(
+    prepost_container_cache_vector = @views PreallocationTools.get_tmp(
         prepost_container_cache, TF(1.0)
     )
 
     # reset cache
-    prepost_container_cache_vec .= 0
+    prepost_container_cache_vector .= 0
 
     # Reshape Cache
     prepost_containers = withdraw_prepost_container_cache(
-        prepost_container_cache_vec, prepost_container_cache_dims
+        prepost_container_cache_vector, prepost_container_cache_dims
     )
 
     # - Set up Solver Sensitivity Paramter Cache - #
@@ -111,13 +111,11 @@ function setup_analysis(
         solve_parameter_tuple.operating_point[f] .= getfield(propulsor.operating_point, f)
     end
 
-    # - Do preprocessutations - #
+    ##### ----- PERFORM PREPROCESSING COMPUTATIONS ----- #####
     if options.verbose
         println("Pre-computing Parameters")
     end
 
-    ##### ----- PERFORM PREPROCESSING COMPUTATIONS ----- #####
-
     # - Preprocess - #
     A_bb_LU, lu_decomp_flag, airfoils, idmaps, _ = precompute_parameters!(
         solve_parameter_tuple.ivr,

src/process/process.jl

@@ -1,4 +1,29 @@
 """
+    process(
+        solver_options::SolverOptionsType,
+        solve_parameter_cache_vector,
+        solve_parameter_cache_dims,
+        airfoils,
+        A_bb_LU,
+        solve_container_caching,
+        idmaps,
+        options,
+    )
+
+Process (the step between pre-process and post-process) the solution, in other words: call the solver(s).
+
+# Arguments
+- `solver_options::SolverOptionsType` : the solver options contained in the options object, used for dispatch.
+- `solve_parameter_cache_vector::Vector{Float}` : The vector cache for parameters used in the solve.
+- `solve_parameter_cache_dims::NamedTuple` : A named tuple containing the dimensions of the solve parameters.
+- `airfoils::NamedTuple` : The airfoils to be interpolated that are associated with each blade element
+- `A_bb_LU::LinearAlgebra.LU` : The LU decomposition of the panel method LHS matrix
+- `solve_container_caching::NamedTuple` : A named tuple containing the cache and dimensions for the intermediate solve values.
+- `idmaps::NamedTuple` : The set of index maps used in various solve sub-functions
+- `options::Options` : User options
+
+# Returns
+- `converged_states::Vector{Float}` : The output of a call to `ImplicitAD.implicit`
 """
 function process(
     solver_options::TS,
@@ -66,8 +91,6 @@ function process(
     )
 end
 
-"""
-"""
 function process(
     solver_options::CSORSolverOptions,
     solve_parameter_cache_vector,

src/process/residuals/CSORresidual.jl

@@ -1,4 +1,16 @@
 """
+    CSOR_residual!(resid, state_variables, sensitivity_parameters, constants)
+
+The in-place residual used for the CSOR solve method.
+
+# Arguments
+- `resid::Vector{Float}` : In-place residual.
+- `state_variables::Vector{Float}` : The state variables
+- `sensitivity_parameters::Vector{Float}` : The parameters to which the solution is sensitive.
+- `constants::NamedTuple` : Various constants required in the solve
+
+# Returns
+- `state_variables::Vector{Float}` : The state variables (modified in place)
 """
 function CSOR_residual!(resid, state_variables, sensitivity_parameters, constants)
 
@@ -68,6 +80,42 @@ function CSOR_residual!(resid, state_variables, sensitivity_parameters, constant
 end
 
 """
+    compute_CSOR_residual!(
+        resid,
+        solver_options,
+        solve_containers,
+        Gamr,
+        sigr,
+        gamw,
+        operating_point,
+        ivr,
+        ivw,
+        linsys,
+        blade_elements,
+        wakeK,
+        idmaps;
+        verbose=false,
+    )
+
+Description
+
+# Arguments
+- `resid::type` :
+- `solver_options::type` :
+- `solve_containers::type` :
+- `Gamr::type` :
+- `sigr::type` :
+- `gamw::type` :
+- `operating_point::type` :
+- `ivr::type` :
+- `ivw::type` :
+- `linsys::type` :
+- `blade_elements::type` :
+- `wakeK::type` :
+- `idmaps::type` :;
+
+# Keyword Arguments
+- `verbose::Bool=false` : Flag to print verbose statements
 """
 function compute_CSOR_residual!(
     resid,
@@ -302,7 +350,24 @@ function compute_CSOR_residual!(
 end
 
 """
-# Arguments:
+    relax_Gamr!(
+        Gamr,
+        delta_prev_mat,
+        delta_mat,
+        maxBGamr,
+        maxdeltaBGamr,
+        B;
+        nrf=0.4,
+        bt1=0.2,
+        bt2=0.6,
+        pf1=0.4,
+        pf2=0.5,
+        test=false,
+    )
+
+Apply relaxed step to Gamr.
+
+# Arguments
 - `Gamr::Array{Float}` : Array of rotor circulations (columns = rotors, rows = blade elements), updated in place
 - `delta_prev_mat::Array{Float}` : Array of previous iteration's differences in circulation values, updated in place
 - `delta_mat::Array{Float}` : Array of current iteration's differences in circulation values
@@ -413,7 +478,13 @@ function relax_Gamr!(
 end
 
 """
-# Arguments:
+    relax_gamw!(
+        gamw, delta_prev, delta, maxdeltagamw; nrf=0.4, btw=0.6, pfw=1.2, test=false
+    )
+
+Apply relaxed step to gamw.
+
+# Arguments
 - `gamw::Array{Float}` : Array of rotor circulations (columns = rotors, rows = blade elements), updated in place
 - `delta_prev_mat::Array{Float}` : Array of previous iteration's differences in circulation values, updated in place
 - `delta_mat::Array{Float}` : Array of current iteration's differences in circulation values
@@ -461,6 +532,14 @@ function relax_gamw!(
 end
 
 """
+    apply_relaxation_schedule(
+        resid::AbstractArray, solver_options::TS
+    ) where {TS<:SolverOptionsType}
+
+Apply custom relaxation schedule to all relaxation factor inputs.
+
+# Arguments
+- `var::type` :
 """
 function apply_relaxation_schedule(
     resid::AbstractArray, solver_options::TS
@@ -487,6 +566,12 @@ function apply_relaxation_schedule(
 end
 
 """
+    apply_relaxation_schedule(resid, nominal, schedule)
+
+Apply custom relaxation schedule to a single relaxation factor input.
+
+# Arguments
+- `var::type` :
 """
 function apply_relaxation_schedule(resid, nominal, schedule)
     rf = linear_transform(
@@ -497,6 +582,18 @@ function apply_relaxation_schedule(resid, nominal, schedule)
 end
 
 """
+    update_CSOR_residual_values!(
+        convergence_type::ConvergenceType, resid, maxBGamr, maxdeltaBGamr, maxdeltagamw, Vconv
+    )
+
+Description
+
+# Arguments
+- `var::type` :
+
+# Keyword Arguments
+- `var::type=default` :
+
 """
 function update_CSOR_residual_values!(
     convergence_type::Relative, resid, maxBGamr, maxdeltaBGamr, maxdeltagamw, Vconv
@@ -507,8 +604,6 @@ function update_CSOR_residual_values!(
     return resid
 end
 
-"""
-"""
 function update_CSOR_residual_values!(
     convergence_type::Absolute, resid, maxBGamr, maxdeltaBGamr, maxdeltagamw, Vconv
 )
@@ -518,6 +613,20 @@ function update_CSOR_residual_values!(
     return resid
 end
 
+"""
+    check_CSOR_convergence!(
+        conv, resid; f_circ=1e-3, f_dgamw=2e-4, convergence_type=Relative(), verbose=false
+    )
+
+Description
+
+# Arguments
+- `var::type` :
+
+# Keyword Arguments
+- `var::type=default` :
+
+"""
 function check_CSOR_convergence!(
     conv, resid; f_circ=1e-3, f_dgamw=2e-4, convergence_type=Relative(), verbose=false
 )

src/process/solve.jl

@@ -1,4 +1,7 @@
 """
+    solve(sensitivity_parameters, const_cache; initial_guess=nothing)
+
+A compact dispatch of `solve` that automatically dispatches based on the solver_options contained in const_cache.
 """
 function solve(sensitivity_parameters, const_cache; initial_guess=nothing)
     return solve(
@@ -13,6 +16,27 @@ end
 #       FIXED POINT SOLVERS       #
 #---------------------------------#
 
+"""
+    solve(
+        solver_options::SolverOptionsType,
+        sensitivity_parameters,
+        const_cache;
+        initial_guess=nothing,
+    )
+
+Converge the residual, solving for the state variables that do so.
+
+# Arguments
+- `solver_options::SolverOptionsType` : SolverOptionsType used for dispatch
+- `sensitivity_parameters::Vector{Float}` : Sensitivity parameters for solve (parameters passed in through ImplicitAD)
+- `const_cache::NamedTuple` : A named tuple containing constants and caching helpers.
+
+# Keyword Arguments
+- `initial_guess=nothing::Vector{Float}` : An optional manually provided initial guess (contained in the sensitivity parameters anyway).
+
+# Returns
+- `converged_states::Vector{Float}` : the states for which the residual has converged.
+"""
 function solve(
     solver_options::CSORSolverOptions,
     sensitivity_parameters,
@@ -44,7 +68,7 @@ function solve(
             solver_options, sensitivity_parameters, solve_parameter_cache_dims.state_dims
         )
     else
-        state_variables .= initial_guess
+        state_variables = initial_guess
     end
 
     # - Separate out the state variables - #
@@ -73,17 +97,17 @@ function solve(
 
     resid = MVector{2,TF}(999 * ones(TF, 2))
     conv = @view(solver_options.converged[multipoint_index[]])
-    iter = 0
+    iter = @view(solver_options.iterations[multipoint_index[]]) .= 0
 
     # - SOLVE - #
     if verbose
         println("  " * "CSOR Solve Trace:")
     end
 
     # loop until converged or max iterations are reached
-    while !conv[] && iter <= solver_options.iteration_limit
+    while !conv[] && iter[] <= solver_options.iteration_limit
         # update iteration number
-        iter += 1
+        iter[] += 1
         if verbose
             println("Iteration $(iter):")
         end
@@ -317,7 +341,7 @@ function solve(
         solve_container_cache_dims,
     ) = const_cache
 
-    (; algorithm, atol, iteration_limit, converged) = solver_options
+    (; algorithm, atol, iteration_limit, converged, iterations) = solver_options
 
     # - Extract Initial Guess Vector for State Variables - #
     if isnothing(initial_guess)
@@ -381,13 +405,15 @@ function solve(
         jwrap!,
         copy(initial_guess);
         tol=atol,
+        tracing=true,
         show_trace=verbose,
         method=algorithm,
         iterations=iteration_limit,
     )
 
     # update convergence flag
     converged[multipoint_index[]] = result.converged
+    iterations[multipoint_index[]] = result.trace.trace[end].iteration
 
     return result.x
 end
@@ -542,6 +568,7 @@ function solve(
         atol,
         iteration_limit,
         converged,
+        iterations,
     ) = solver_options
 
     # - Extract Initial Guess Vector for State Variables - #
@@ -622,8 +649,15 @@ function solve(
         solve_container_cache_dims,
     ) = const_cache
 
-    (; algorithm, linesearch_method, linesearch_kwargs, atol, iteration_limit, converged) =
-        solver_options
+    (;
+        algorithm,
+        linesearch_method,
+        linesearch_kwargs,
+        atol,
+        iteration_limit,
+        converged,
+        iterations,
+    ) = solver_options
 
     # - Extract Initial Guess Vector for State Variables - #
     if isnothing(initial_guess)
@@ -708,6 +742,7 @@ function solve(
     # update convergence flag
     # note: need to do this complicated check to ensure that we're only checking |f(x)|<atol rather than claiming convergences when the step size is zero but it's really just stuck.
     _, converged[multipoint_index[]] = NLsolve.assess_convergence(NLsolve.value(df), atol)
+    iterations[multipoint_index[]] = result.iterations
 
     return result.zero
 end