[WIP] Integrate utilities from CTModels.Utils into CTBase

[ocots]

This PR implements issue #445: migrating the Utils module from CTModels.jl to CTBase.jl.

Overview

The utilities from CTModels.Utils (interpolation, matrix utilities, function utilities, and validation macros) are generic and reusable across the control-toolbox ecosystem. They should live in CTBase as the foundational layer.

Architectural Decision

Rather than creating a monolithic Utils module (which would violate the "one module per responsibility" philosophy), we are splitting by responsibility:

• New module Interpolation — ctinterpolate, ctinterpolate_constant
• Extension of Core — matrix2vec (public), to_out_of_place (private), @ensure (private)

Implementation Plan

The detailed implementation plan is documented in the plan file. Key steps:

1. Create new Interpolation module with interpolation utilities
2. Extend Core with matrix, function, and macro utilities
3. Register modules in src/CTBase.jl
4. Adapt tests from CTModels to CTBase conventions
5. Update documentation in docs/api_reference.jl
6. Verify docstrings follow CTBase conventions

Current Status

This is a placeholder PR to establish the branch. The actual implementation will follow the plan in subsequent commits.

References

• Issue: Add Utils module from CTModels.jl #445
• Plan: See linked plan document for detailed steps

[ocots]

Implementation Complete

All utilities from CTModels.Utils have been successfully integrated into CTBase following the architectural decision to split by responsibility:

New Module: Interpolation

• src/Interpolation/Interpolation.jl - module manifest
• src/Interpolation/types.jl - Interpolant{Linear} and Interpolant{Constant} parametric types
• src/Interpolation/ctinterpolate.jl - ctinterpolate and ctinterpolate_constant factory functions
• src/Interpolation/display.jl - custom show methods for interpolants
• test/suite/interpolation/test_interpolation.jl - comprehensive tests including type stability

Core Extensions

• src/Core/matrix_utils.jl - matrix2vec (public)
• src/Core/function_utils.jl - to_out_of_place (private)
• src/Core/macros.jl - @ensure macro (private)
• Tests in test/suite/core/ for all three utilities

Documentation

• Updated docs/api_reference.jl to include new modules
• Added Interpolation section with public and private documentation
• Updated Core section to include new utility files

Test Results

All 1237 tests pass (41.2s), including:

• 56 tests for interpolation (type-stable call methods)
• 18 tests for function_utils
• 14 tests for macros
• 26 tests for matrix_utils

The implementation follows CTBase conventions: qualified imports, no top-level exports, typed structs with call methods, and comprehensive docstrings with $(TYPEDSIGNATURES).