patch bug in wake solver and start adding docstrings from beginning

docs/src/api.md

@@ -1,7 +1,48 @@
 # API Reference
 
+```@contents
+Pages = ["api.md"]
+Depth = 5
+```
+
 ## Public API
 
+```@docs
+DuctAPE.setup_analysis
+```
+
+The remainder of the public API elements are found throughout the remainder of this documentation in the context of their usage.  The index at the bottom of this page may be helpful in locating them.
+
 ## Private API
 
+### Bookkeeping
+```@docs
+DuctAPE.get_problem_dimensions
+```
+
+### Caching
+```@docs
+DuctAPE.allocate_wake_panel_container!
+DuctAPE.allocate_panel_containers!
+DuctAPE.allocate_panel_container!
+DuctAPE.allocate_body_panel_container!
+DuctAPE.allocate_rotor_panel_container!
+DuctAPE.allocate_solve_parameter_extras!
+```
+
+
+### Analysis
+```@docs
+DuctAPE.analyze
+```
+
+### Post-process
+```@docs
+DuctAPE.post_process
+```
+
 ## Index
+
+```@index
+Modules=[DuctAPE, DuctAPE.C4Blade]
+```

docs/src/examples.md

@@ -4,8 +4,31 @@
 
 ## Available Outputs
 
-## Returning the Pre-process objects
+## Returning the Pre-process Objects
 
 ## Multi-Point Analyses
 
+## Pre-compiling the Caches
+
+There are several available caches that can be precompiled to help speed up multiple analyses.
+The first is a cache used for intermediate calculations in the pre- and post-processing phases of the analysis.
+It can be preallocated using `allocate_prepost_container_cache`
+
+```@docs
+DuctAPE.allocate_prepost_container_cache
+```
+
+The second is a cache containing parameters used in the solver, in other words, the results of the pre-processing phase.
+It can be preallocated using `allocate_solve_parameter_cache`.
+
+```@docs
+DuctAPE.allocate_solve_parameter_cache
+```
+
+The final precompileable cache is for intermediate calculations within the solve and can be preallocated using `allocate_solve_container_cache`
+
+```@docs
+DuctAPE.allocate_solve_container_cache
+```
+
 ## Circumventing the Automated Geometry Re-paneling

docs/src/tutorial.md

@@ -6,7 +6,7 @@ Pages = ["tutorial.md"]
 Depth = 5
 ```
 
-The following is a basic tutorial on how to set up the inputs to, and run an analysis of a ducted fan in DuctAPE.
+The following is a basic tutorial on how to set up the inputs to, and run, an analysis of a ducted fan in DuctAPE.
 
 ```@setup dfdc
 include("../assets/plots_default.jl")
@@ -17,19 +17,20 @@ We begin by loading the package, and optionally create a shorthand name.
 ```@example dfdc
 using DuctAPE
 const dt = DuctAPE
+nothing # hide
 ```
 
 ## Build Inputs
 
-The next step is to create the input object of type `Propulsor`
+The next step is to create the input object of type `Propulsor`.
 
 ```@docs
 DuctAPE.Propulsor
 ```
 
 ### Body Geometry
 
-To do so, we begin by defining a matrix of coordinates for the duct and another for the centerbody geometries, for example:
+We begin by defining a matrix of coordinates for the duct and another for the centerbody geometries, for example:
 
 ```@example dfdc
 duct_coordinates = [
@@ -244,6 +245,7 @@ plot!(pg, rotorzloc*ones(length(r)), r.*Rtip, seriestype=:scatter, markerstrokew
     Airfoil types for DuctAPE are currently contained in the C4Blade (Cascade Compatible [CCBlade](https://flow.byu.edu/CCBlade.jl/stable/)) sub-module of DuctAPE which is exported as `c4b` and also contains the various airfoil evaluation functions used for the blade element lookups.
     The available airfoil types include all the airfoil types from CCBlade, as well as `DFDCairfoil` which is an [XROTOR](https://web.mit.edu/drela/Public/web/xrotor/)-like parametric cascade polar used in DFDC.
     In addition there are untested cascade types with similar structure to CCBlades airfoil types called `DTCascade`.
+    Furthermore, there is an experimental actuator disk model implemented via the `ADM` airfoil type in C4Blade.
 
 ### Operating Point
 
@@ -274,7 +276,7 @@ nothing # hide
 
 The `PanelingConstants` object contains the constants required for DuctAPE to re-panel the provided geometry into a format compatible with the solve structure.
 The `PanelingConstants` object is also used to build all of the preallocated caches inside DuctAPE, which can be done up-front if desired.
-Note that there is some functionality in place for cases when the user wants to keep their own specified geometry, but this functionality should be used with caution and only by users who are certain their provided geometry is in the compatible format.  See the examples for an example.
+Note that there is some functionality in place for cases when the user wants to keep their own specified geometry, but this functionality should be used with caution and only by users who are certain their provided geometry is in the compatible format.  See the [Examples](@ref "Circumventing the Automated Geometry Re-paneling") for an example.
 
 ```@docs
 DuctAPE.PanelingConstants
@@ -345,14 +347,18 @@ For more advanced option selection, see the examples and API reference.
 With the propulsor input build, and the options selected, we are now ready to run an analysis.
 This is done simply with the `analyze` function which dispatches the appropriate analysis, solve, and post-processing functions based on the selected options.
 
+```@docs
+DuctAPE.analyze(::DuctAPE.Propulsor, ::DuctAPE.Options)
+```
+
 ```@example dfdc
 outs, success_flag = dt.analyze(propulsor, options)
 nothing # hide
 ```
 
 ## Outputs
 
-There are many outputs contained in the named tuple output from the `analyze` function (see the examples), but some that may be of immediate interest include:
+There are many outputs contained in the named tuple output from the `analyze` function (see the [post_process() docstring](@ref DuctAPE.post_process)), but some that may be of immediate interest include:
 
 ```@example dfdc
 # Total Thrust Coefficient

src/DuctAPE.jl

@@ -79,6 +79,7 @@ include("utilities/caching/caches.jl")
 include("utilities/caching/allocate_caches.jl")
 include("utilities/caching/reshape_caches.jl")
 include("utilities/caching/integration_caches.jl")
+include("utilities/caching/elliptic_grid_parameter_packaging.jl")
 
 # Airfoil utility functions
 include("utilities/airfoils/airfoil_utilities.jl")

src/analysis/analyses.jl

@@ -1,4 +1,29 @@
 """
+    analyze(
+        propulsor::Propulsor,
+        options::Options=set_options();
+        prepost_container_caching=nothing,
+        solve_parameter_caching=nothing,
+        solve_container_caching=nothing,
+        return_inputs=false,
+    )
+
+Analyze propulsor, including preprocessing.
+
+# Arguments
+- `propulsor::Propulsor` : Propulsor input object (see docstring for `Propulsor` type)
+- `options::Options=set_options()` : Options object (see `set_options` and related functions)
+
+# Keyword Arguments
+- `prepost_container_caching=nothing` : Output of `allocate_prepost_container_cache`
+- `solve_parameter_caching=nothing` : Output of `allocate_solve_parameter_container_cache`
+- `solve_container_caching=nothing` : Output of `allocate_solve_container_cache`
+- `return_inputs=false` : flag as to whether or not to return the pre-processed inputs
+
+# Returns
+- `outs::NamedTuple` : Named Tuple of various analysis outputs (see docstring for postprocess for details), note, if linear system decomposition fails, no solve is performed and an empty vector is returned.
+- `ins::NamedTuple` : Named Tuple of various pre-processed inputs (e.g. panels and body linear system), will only be returned if `return_inputs=true`
+- `convergence_flag` : Flag for successful solve convergence
 """
 function analyze(
     propulsor::Propulsor,
@@ -32,9 +57,14 @@ function analyze(
         end
         #TODO: write a function that returns the same as outs below, but all zeros
         #TODO: probably just call  the post-process function directly and return a reset_container! of the output
-        return [],#zero_outputs(),
-        (; solve_parameter_tuple..., ivb, airfoils, idmaps, panels, problem_dimensions),
-        false
+        if return_inputs
+            return [],#zero_outputs(),
+            (; solve_parameter_tuple..., ivb, airfoils, idmaps, panels, problem_dimensions),
+            false
+        else
+            return [],#zero_outputs(),
+            false
+        end
     end
 
     # - Continue with Analysis - #
@@ -55,6 +85,43 @@ function analyze(
 end
 
 """
+    analyze(
+        propulsor::Propulsor,
+        prepost_containers,
+        solve_parameter_cache_vector,
+        solve_parameter_cache_dims,
+        airfoils,
+        ivb,
+        A_bb_LU,
+        idmaps,
+        problem_dimensions,
+        options::Options=set_options();
+        return_inputs=false,
+        solve_container_caching=nothing,
+    )
+
+Analyze propulsor, assuming `setup_analysis` has been called and the outputs thereof are being passed in here.
+
+# Arguments
+- `propulsor::Propulsor` : Propulsor input object
+- `prepost_containers::NamedTuple` : An output from `setup_analysis` containing reshaped views into the prepost cache
+- `solve_parameter_cache_vector::Vector` : An output from `setup_analysis` containing the relevant typed cache vector of solve parameters
+- `solve_parameter_cache_dims::NamedTuple` : An output from `setup_analysis` containing dimensions used for reshaping the solve parameter cache
+- `airfoils::Vector{AFType}` : An output from `setup_analysis` contiaining the blade element airfoil polar objects
+- `ivb::NamedTuple` : An output from `setup_analysis` containing the unit induced velocities on the body
+- `A_bb_LU::LinearAlgebra.LU` : An output from `setup_analysis` that is the LU decomposition of the AIC matrix used in the panel method
+- `idmaps::NamedTuple` : An output from `setup_analysis` containing bookkeeping information (index mappings)
+- `problem_dimensions::NamedTuple` : An output from `setup_analysis` contiaining bookkeeping information (problem dimensions)
+- `options::Options=set_options()` : Options object
+
+# Keyword Arguments
+- `solve_container_caching=nothing` : Output of `allocate_solve_container_cache`
+- `return_inputs=false` : flag as to whether or not to return the pre-processed inputs
+
+# Returns
+- `outs::NamedTuple` : Named Tuple of various analysis outputs (see docstring for postprocess for details), note, if linear system decomposition fails, no solve is performed and an empty vector is returned.
+- `ins::NamedTuple` : Named Tuple of various pre-processed inputs (e.g. panels and body linear system), will only be returned if `return_inputs=true`
+- `convergence_flag` : Flag for successful solve convergence
 """
 function analyze(
     propulsor::Propulsor,
@@ -131,6 +198,33 @@ function analyze(
 end
 
 """
+    analyze(
+        multipoint::AbstractVector{OperatingPoint},
+        propulsor::Propulsor,
+        options::Options=set_options();
+        prepost_container_caching=nothing,
+        solve_parameter_caching=nothing,
+        solve_container_caching=nothing,
+        return_inputs=false,
+    )
+
+Analyze propulsor, including preprocessing, for a set of operating points.
+
+# Arguments
+- `multipoint::AbstractVector{OperatingPoint}` : Vector of Operating Points at which to analyze the propulsor (note that the operating point within the propulsor input will be overwritten with these)
+- `propulsor::Propulsor` : Propulsor input object
+- `options::Options=set_options()` : Options object
+
+# Keyword Arguments
+- `prepost_container_caching=nothing` : Output of `allocate_prepost_container_cache`
+- `solve_parameter_caching=nothing` : Output of `allocate_solve_parameter_container_cache`
+- `solve_container_caching=nothing` : Output of `allocate_solve_container_cache`
+- `return_inputs=false` : flag as to whether or not to return the pre-processed inputs
+
+# Returns
+- `outs::Vector{NamedTuple}` : Vector of named tuples of various analysis outputs (see docstring for postprocess for details), note, if linear system decomposition fails, no solve is performed and an empty vector is returned.
+- `ins::NamedTuple` : Named Tuple of various pre-processed inputs (e.g. panels and body linear system), will only be returned if `return_inputs=true`
+- `convergence_flag` : Flag for successful solve convergence
 """
 function analyze(
     multipoint::AbstractVector{TO},
@@ -187,6 +281,47 @@ function analyze(
     )
 end
 
+"""
+    analyze(
+        multipoint::Vector{OperatingPoint},
+        propulsor::Propulsor,
+        prepost_containers,
+        solve_parameter_cache_vector,
+        solve_parameter_cache_dims,
+        airfoils,
+        ivb,
+        A_bb_LU,
+        idmaps,
+        problem_dimensions,
+        options::Options=set_options();
+        return_inputs=false,
+        solve_container_caching=nothing,
+    )
+
+Analyze propulsor, assuming `setup_analysis` has been called and the inputs are being passed in here.
+
+# Arguments
+- `multipoint::AbstractVector{OperatingPoint}` : Vector of Operating Points at which to analyze the propulsor (note that the operating point within the propulsor input will be overwritten with these)
+- `propulsor::Propulsor` : Propulsor input object
+- `prepost_containers::NamedTuple` : An output from `setup_analysis` containing reshaped views into the prepost cache
+- `solve_parameter_cache_vector::Vector` : An output from `setup_analysis` containing the relevant typed cache vector of solve parameters
+- `solve_parameter_cache_dims::NamedTuple` : An output from `setup_analysis` containing dimensions used for reshaping the solve parameter cache
+- `airfoils::Vector{AFType}` : An output from `setup_analysis` contiaining the blade element airfoil polar objects
+- `ivb::NamedTuple` : An output from `setup_analysis` containing the unit induced velocities on the body
+- `A_bb_LU::LinearAlgebra.LU` : An output from `setup_analysis` that is the LU decomposition of the AIC matrix used in the panel method
+- `idmaps::NamedTuple` : An output from `setup_analysis` containing bookkeeping information (index mappings)
+- `problem_dimensions::NamedTuple` : An output from `setup_analysis` contiaining bookkeeping information (problem dimensions)
+- `options::Options=set_options()` : Options object
+
+# Keyword Arguments
+- `solve_container_caching=nothing` : Output of `allocate_solve_container_cache`
+- `return_inputs=false` : flag as to whether or not to return the pre-processed inputs
+
+# Returns
+- `outs::Vector{NamedTuple}` : Named Tuple of various analysis outputs (see docstring for postprocess for details), note, if linear system decomposition fails, no solve is performed and an empty vector is returned.
+- `ins::NamedTuple` : Named Tuple of various pre-processed inputs (e.g. panels and body linear system), will only be returned if `return_inputs=true`.  Note that some inputs will be overwritten (e.g. the linear system RHS components related to the freestream) and only those associated with the final operating point will be returned.
+- `convergence_flag` : Flag for successful solve convergence
+"""
 function analyze(
     multipoint::AbstractVector{TO},
     propulsor::Propulsor,
@@ -253,6 +388,25 @@ function analyze(
     end
 end
 
+"""
+    analyze_multipoint(
+        operating_point::OperatingPoint,
+        propulsor::Propulsor,
+        prepost_containers,
+        solve_parameter_cache_vector,
+        solve_parameter_cache_dims,
+        airfoils,
+        ivb,
+        A_bb_LU,
+        idmaps,
+        problem_dimensions,
+        options::Options;
+        solve_container_caching=nothing,
+        return_inputs=false,
+    )
+
+Identical to the single analyze function assuming `setup_analysis` has been called; except here we are running a single operating point for a multipoint analysis, and overwriting the operating point in the propulsor with the explicit operating point input.
+"""
 function analyze_multipoint(
     operating_point::TO,
     propulsor::Propulsor,

src/analysis/setup.jl

@@ -1,4 +1,34 @@
 """
+    setup_analysis(
+        propulsor::Propulsor,
+        options::Options=set_options();
+        prepost_container_caching=nothing,
+        solve_parameter_caching=nothing,
+        solve_container_caching=nothing,
+    )
+
+Perform pre-processing and cache setup (as needed) for propuslor analysis.
+
+# Arguments
+- `propulsor::Propulsor` : Propulsor input object (see docstring for `Propulsor` type)
+- `options::Options=set_options()` : Options object (see `set_options` and related functions)
+
+# Keyword Arguments
+- `prepost_container_caching=nothing` : Output of `allocate_prepost_container_cache`
+- `solve_parameter_caching=nothing` : Output of `allocate_solve_parameter_container_cache`
+- `solve_container_caching=nothing` : Output of `allocate_solve_container_cache`
+
+# Returns
+
+- `problem_dimensions::NamedTuple` : Named Tuple contiaining bookkeeping information (problem dimensions)
+- `prepost_containers::NamedTuple` : Named Tuple containing reshaped views into the prepost cache
+- `solve_parameter_cache_vector::Vector` : Vector containing the relevant typed cache vector of solve parameters
+- `solve_parameter_cache_dims::NamedTuple` : Named Tuple containing dimensions used for reshaping the solve parameter cache
+- `ivb::NamedTuple` : NamedTuple containing the unit induced velocities on the body
+- `A_bb_LU::LinearAlgebra.LU` : The LU factorization of the AIC matrix used in the panel method
+- `lu_decomp_flag::Bool` : flag indicating if the LU decomposition was successful
+- `airfoils::Matrix{AFType}` : Matrix contiaining the blade element airfoil polar objects
+- `idmaps::NamedTuple` : Named Tuple containing bookkeeping information (index mappings)
 """
 function setup_analysis(
     propulsor::Propulsor,