Merge pull request #459 from control-toolbox/move/ctflows-to-ctbase-phase-a

Add AbstractCache and make_coerce to CTBase.Core

Author: ocots

src/Core/Core.jl

@@ -12,6 +12,7 @@ import DocStringExtensions: TYPEDEF, TYPEDSIGNATURES
 
 include("types.jl")
 include("tags.jl")
+include("caches.jl")
 include("default.jl")
 
 # Private utilities
@@ -24,7 +25,8 @@ include("palette.jl")
 include("display.jl")
 
 # Export public API
-export ctNumber, matrix2vec, to_out_of_place, @ensure
+export ctNumber, matrix2vec, to_out_of_place, make_coerce, @ensure
+export AbstractTag, AbstractCache
 export Style, Palette
 export DEFAULT_PALETTE, MONOCHROME_PALETTE, HIGH_CONTRAST_PALETTE
 export current_palette, set_palette!, set_color!, reset_palette!, show_palette

src/Core/caches.jl

@@ -0,0 +1,27 @@
+"""
+$(TYPEDEF)
+
+Abstract base type for computation caches.
+
+Caches store pre-allocated buffers and prepared plans (for example automatic
+differentiation plans) so that repeated computations avoid reallocating on every
+call. Concrete cache types are defined by the packages or extensions that provide
+a specific backend.
+
+# Interface Requirements
+
+Concrete cache subtypes typically:
+- Hold pre-allocated buffers and/or a prepared plan
+- Are constructed once and reused across many calls
+- Are backend- or extension-specific
+
+# Example
+```julia
+struct MyCache <: AbstractCache
+    buffer::Vector{Float64}
+end
+```
+
+See also: [`AbstractTag`](@ref).
+"""
+abstract type AbstractCache end

src/Core/function_utils.jl

@@ -30,3 +30,38 @@ function to_out_of_place(f!, n; T=Float64)
     end
     return isnothing(f!) ? nothing : f
 end
+
+"""
+    make_coerce(x) -> coerce_fn
+
+Return a coercion function matching the shape of `x`.
+
+For scalars (`Number`), returns `only`, which extracts the single element from a
+1-element vector. For arrays (`AbstractVector`, `AbstractMatrix`), returns
+`identity` (a no-op). This is used to map a uniform vector-valued result back to
+the natural shape of the original input.
+
+# Arguments
+- `x`: A value whose type determines the coercion strategy.
+
+# Returns
+- A coercion function with signature `(y) -> coerced_y`.
+
+# Example
+```julia-repl
+julia> coerce_scalar = make_coerce(1.0);
+
+julia> coerce_scalar([5.0])
+5.0
+
+julia> coerce_vector = make_coerce([1.0, 2.0]);
+
+julia> coerce_vector([3.0, 4.0])
+2-element Vector{Float64}:
+ 3.0
+ 4.0
+```
+"""
+make_coerce(::Number) = only
+make_coerce(::AbstractVector) = identity
+make_coerce(::AbstractMatrix) = identity