add more docstrings

Author: juddmehr

Diff for: docs/src/DuctAPE/private_api.md

@@ -24,19 +24,21 @@ DuctAPE.get_problem_dimensions
 ```
 
 ## Caching
-TODO: go through through the rest of the caching directory and add the remaining files' functions
+TODO: finish up the caching docstrings in the integration-caches.jl file
 
 ### Allocation
 
 The following are various helper functions used in preallocating the various caches.
 
 ```@docs
+DuctAPE.initialize_all_caches
 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!
+DuctAPE.allocate_grid_parameter_cache
 ```
 
 ### Reshaping
@@ -47,6 +49,7 @@ The following are used internally to reshape the cache vectors into more usable
 DuctAPE.withdraw_prepost_container_cache
 DuctAPE.withdraw_solve_parameter_cache
 DuctAPE.withdraw_solve_container_cache
+DuctAPE.withdraw_grid_parameter_cache
 ```
 
 ## Preprocess
@@ -255,4 +258,5 @@ DuctAPE.linear_transform
 DuctAPE.extract_primals!
 DuctAPE.lfs
 DuctAPE.reset_containers!
+DuctAPE.cache_dims!
 ```

Diff for: src/analysis/analyses.jl

@@ -166,7 +166,8 @@ function analyze(
         A_bb_LU,
         airfoils,
         idmaps,
-        problem_dimensions;
+        problem_dimensions,
+        options.multipoint_index;
         write_outputs=options.write_outputs[options.multipoint_index[]],
         outfile=options.outfile[options.multipoint_index[]],
         checkoutfileexists=options.checkoutfileexists,

Diff for: src/postprocess/postprocess.jl

@@ -12,7 +12,8 @@ function post_process(
     A_bb_LU,
     airfoils,
     idmaps,
-    problem_dimensions;
+    problem_dimensions,
+    multipoint_index;
     write_outputs=options.write_outputs,
     outfile=options.outfile,
     checkoutfileexists=options.checkoutfileexists,
@@ -120,6 +121,7 @@ function post_process(
         blade_elements,
         wakeK,
         idmaps,
+        multipoint_index
     )
 
     (;
@@ -526,6 +528,7 @@ function run_residual!(
     blade_elements,
     wakeK,
     idmaps,
+    multipoint_index
 ) where {TS<:ExternalSolverOptions}
 
     #=
@@ -581,6 +584,7 @@ function run_residual!(
     blade_elements,
     wakeK,
     idmaps,
+    multipoint_index
 )
 
     #=
@@ -614,7 +618,8 @@ function run_residual!(
         linsys,
         blade_elements,
         wakeK,
-        idmaps;
+        idmaps,
+        multipoint_index;
         verbose=false,
     )
 

Diff for: src/preprocess/initialize_states.jl

@@ -635,7 +635,7 @@ function initialize_strengths!(
 
     reset_containers!(solve_containers)
 
-    vz_rotor=0.0
+    vz_rotor=-Vinf[] + 1.0
 
     # loop through rotors
     for irotor in 1:nrotor

Diff for: src/preprocess/preprocess.jl

@@ -70,15 +70,17 @@ function reinterpolate_geometry(
     rp_duct_coordinates = zeros(TF, 2, ndn)
     rp_centerbody_coordinates = zeros(TF, 2, ncbn)
     rotor_indices_in_wake = ones(Int, nrotor)
+    blade_element_cache = (;Rtip=zeros(TF,nrotor), Rhub=zeros(TF,nrotor))
 
     reinterpolate_geometry!(
-        @view(wake_grid[:, :, :]),
-        @view(rp_duct_coordinates[:, :]),
-        @view(rp_centerbody_coordinates[:, :]),
-        @view(rotor_indices_in_wake[:]),
+        wake_grid,
+        rp_duct_coordinates,
+        rp_centerbody_coordinates,
+        rotor_indices_in_wake,
         duct_coordinates,
         centerbody_coordinates,
         rotorstator_parameters,
+        blade_element_cache,
         paneling_constants;
         autoshiftduct=autoshiftduct,
         grid_solver_options=grid_solver_options,

Diff for: src/process/residuals/CSORresidual.jl

@@ -25,6 +25,7 @@ function CSOR_residual!(resid, state_variables, sensitivity_parameters, constant
         solve_parameter_cache_dims, # dimensions for shaping the view of the parameter cache
         solve_container_cache,      # cache for solve_containers used in solve
         solve_container_cache_dims, # dimensions for shaping the view of the solve cache
+        multipoint_index,
     ) = constants
 
     # - Separate out the state variables - #
@@ -72,7 +73,8 @@ function CSOR_residual!(resid, state_variables, sensitivity_parameters, constant
         (; linsys..., A_bb_LU),
         (; blade_elements..., airfoils...),
         wakeK,
-        idmaps;
+        idmaps,
+        multipoint_index;
         verbose=solver_options.verbose,
     )
 
@@ -130,7 +132,8 @@ function compute_CSOR_residual!(
     linsys,
     blade_elements,
     wakeK,
-    idmaps;
+    idmaps,
+    multipoint_index;
     verbose=false,
 )
 
@@ -343,7 +346,7 @@ function compute_CSOR_residual!(
         maxBGamr,
         maxdeltaBGamr,
         maxdeltagamw,
-        solver_options.Vconv,
+        solver_options.Vconv[multipoint_index[]],
     )
 
     return nothing
@@ -398,6 +401,8 @@ function relax_Gamr!(
     bladeomega = nrf .* ones(TF, size(Gamr, 2))
     omega = nrf .* ones(TF, size(Gamr, 1))
     deltahat = zeros(TF, size(Gamr, 1))
+    minBGamr = zeros(TF, size(Gamr,2))
+
 
     for (i, (BG, b, delta_prev, delta)) in
         enumerate(zip(eachcol(Gamr), B, eachcol(delta_prev_mat), eachcol(delta_mat)))
@@ -410,21 +415,24 @@ function relax_Gamr!(
         # - Set the normalization value based on the maximum magnitude value of B*Gamr
 
         # find max magnitude
-        maxBGamr[i], mi = findmax(abs.(BG))
+        maxBGamr[i], maxi = findmax(BG)
+        minBGamr[i], mini = findmin(BG)
 
-        # maintain sign of original value
-        maxBGamr[i] *= sign(BG[mi])
+        # # maintain sign of original value
+        # maxBGamr[i] *= sign(BG[maxi])
 
         # make sure we don't have any weird jumps
         meang = sum(BG) / length(BG)
+
         if meang > 0.0 # if mean is positive, make sure maxBGamr[i] is at least 0.1
             maxBGamr[i] = max(maxBGamr[i], 0.1)
         elseif meang < 0.0 # if mean is negative, make sure maxBGamr[i] is at most -0.1
-            maxBGamr[i] = min(maxBGamr[i], -0.1)
+            maxBGamr[i] = min(minBGamr[i], -0.1)
         else # if the average is zero, then set maxBGamr[i] to zero
             maxBGamr[i] = 0.0
         end
 
+
         # note: delta = Gamr_new .- Gamr
         # note: deltahat here is actually 1/deltahat which is the version needed later
         for (j, d) in enumerate(eachrow(deltahat))
@@ -607,11 +615,12 @@ Update CSOR residual values in place.
 - `maxBGamr::Float` : Maximum value of B*Gamr among all blade elements
 - `maxdeltaBGamr::Float` : Maximum change in B*Gamr between iterations among all blade elements
 - `maxdeltagamw::Vector{Float}` : Maximum change in gamw among all wake nodes (one element)
-- `Vconv::Vector{Float}` : Reference velocity upon which the relative convergence criteria is based (one element)
+- `Vconv::Float` : Reference velocity upon which the relative convergence criteria is based (one element)
 """
 function update_CSOR_residual_values!(
     convergence_type::Relative, resid, maxBGamr, maxdeltaBGamr, maxdeltagamw, Vconv
 )
+
     resid[1] = maximum(abs, maxdeltaBGamr ./ maxBGamr)
     resid[2] = abs.(maxdeltagamw[] / Vconv[])
 

Diff for: src/process/solve.jl

@@ -109,7 +109,7 @@ function solve(
         # update iteration number
         iter[] += 1
         if verbose
-            println("Iteration $(iter):")
+            println("Iteration $(iter[]):")
         end
 
         # Call residual
@@ -127,6 +127,7 @@ function solve(
                 solve_parameter_cache_dims, # dimensions for shaping the view of the parameter cache
                 solve_container_cache,      # cache for solve_containers used in solve
                 solve_container_cache_dims, # dimensions for shaping the view of the solve cache
+                multipoint_index,
             ),
         )
 

Diff for: src/utilities/caching/caches.jl

@@ -1,4 +1,16 @@
 """
+    initialize_all_caches(solver_options, paneling_constants)
+
+Convenience function to initialize all caches before calling analysis.
+
+# Arguments
+- `solver_options::SolverOptionsType` : solver options used for cache allocation dispatch
+- `paneling_constants::PanelingConstants` : PanelingConstants object upon which all cache sizing depends
+
+# Returns
+- `prepost_container_caching::NamedTuple` : A named tuple containing the PreallocationTools DiffCache and a named tuple with relevant dimensions for accessing the cache.
+- `solve_parameter_caching::NamedTuple` : A named tuple containing the PreallocationTools DiffCache and a named tuple with relevant dimensions for accessing the cache.
+- `solve_container_caching::NamedTuple` : A named tuple containing the PreallocationTools DiffCache and a named tuple with relevant dimensions for accessing the cache.
 """
 function initialize_all_caches(solver_options, paneling_constants)
 
@@ -17,11 +29,3 @@ function initialize_all_caches(solver_options, paneling_constants)
 
     return prepost_container_caching, solve_parameter_caching, solve_container_caching
 end
-
-"""
-"""
-function cache_dims!(total_length, l, s)
-    dims = (; index=(total_length[] + 1):(total_length[] + l), shape=s)
-    total_length[] += l
-    return dims
-end

Diff for: src/utilities/caching/elliptic_grid_parameter_packaging.jl

@@ -1,3 +1,16 @@
+"""
+    allocate_grid_parameter_cache(pg, x, n)
+
+Allocate a cache used inside the elliptic grid solve.
+
+# Arguments
+- `pg::AbstractArray{Float,3}` : the proposed grid array
+- `x::AbstractVector{Float}` : the array of ξ values used in the solve
+- `n::AbstractVector{Float}` : the array of η values used in the solve
+
+# Returns
+- `grid_parameter_cache::NamedTuple` : A named tuple containing the PreallocationTools DiffCache and dimensions for accessing it.
+"""
 function allocate_grid_parameter_cache(pg, x, n)
     total_length = [0]
 
@@ -19,6 +32,20 @@ function allocate_grid_parameter_cache(pg, x, n)
     )
 end
 
+"""
+    withdraw_grid_parameter_cache(vec, dims)
+
+Reshape the cache used inside the elliptic grid solve.
+
+# Arguments
+- `vec::Vector{Float}` : the cache vector
+- `dims::NamedTuple` : the named tuple of dimensions used to reshape the cache vector
+
+# Returns
+- `proposed_grid::AbstractArray{Float,3}` : the proposed grid array
+- `xi::AbstractVector{Float}` : the array of ξ values used in the solve
+- `eta::AbstractVector{Float}` : the array of η values used in the solve
+"""
 function withdraw_grid_parameter_cache(vec, dims)
     proposed_grid = reshape(@view(vec[dims.proposed_grid.index]), dims.proposed_grid.shape)
 

Diff for: src/utilities/misc.jl

@@ -168,3 +168,24 @@ function promote_propulosor_type(p)
         eltype(p.rotorstator_parameters.twists),
     )
 end
+
+"""
+    cache_dims!(total_length, l, s)
+
+A function that returns a named tuple containing an index range and shape and increases `total_length` by `l`.
+
+This function is used heavily in the cache allocation functions for setting up the dimension maps used to access the vectorized caches.
+
+# Arguments
+- `total_length::Vector{Int}` : single element vector containing the current total length of the eventual cache vector. Modified in place.
+- `l::Int` : total length of the object in question
+- `s::Int` : size of the object in question
+
+# Returns
+- `dims::NamedTuple` : A named tuple containing `index` and `shape` fields
+"""
+function cache_dims!(total_length, l, s)
+    dims = (; index=(total_length[] + 1):(total_length[] + l), shape=s)
+    total_length[] += l
+    return dims
+end