Remove CTFlows references and fix docstring compliance in Traits module

ocots · ocots · commit 8193b52828cb · 2026-06-23T16:16:03.000+02:00
- Remove CTFlows.Configs references from trait docstrings and examples - Change @extref to @ref for internal Exceptions symbols - Update documentation (getting-started, guide/traits, index) - Clean up trait examples to remove CTFlows-specific configuration references - Part of CTFlows→CTBase migration
diff --git a/docs/src/getting-started.md b/docs/src/getting-started.md
@@ -31,10 +31,11 @@ Three things to keep in mind:
    CTBase.Exceptions.NotImplemented
    ```
 2. **Submodule-first API.** The public API lives in named submodules
-   (`Descriptions`, `Exceptions`, `DevTools`, `Core`, `Unicode`).
+   (`Core`, `Descriptions`, `Exceptions`, `Traits`, `DevTools`, `Unicode`, …).
    You can bring a submodule's exports into scope explicitly:
    ```julia
    using CTBase.Exceptions # brings IncorrectArgument, NotImplemented, … into scope
+   using CTBase.Traits     # brings Autonomous, NonAutonomous, is_autonomous, … into scope
    ```
 3. **Extension-backed features.** `run_tests`, `postprocess_coverage`, and
    `automatic_reference_documentation` require loading the matching weak dependency
@@ -111,6 +112,7 @@ For more, see the **[Exceptions guide](guide/exceptions.md)**.
 | :--- | :--- |
 | Descriptions catalogue and completion | [Descriptions](guide/descriptions.md) |
 | Exception hierarchy and best practices | [Exceptions](guide/exceptions.md) |
+| Compile-time traits and dispatch | [Traits](guide/traits.md) |
 | Modular test runner setup | [Test Runner](guide/test-runner.md) |
 | Coverage report generation | [Coverage](guide/coverage.md) |
 | Auto-generated API reference | [API Documentation](guide/api-documentation.md) |
diff --git a/docs/src/guide/traits.md b/docs/src/guide/traits.md
@@ -5,18 +5,19 @@ CurrentModule = CTBase
 ```
 
 [`CTBase.Traits`](@ref CTBase.Traits) provides a small set of **compile-time
-traits** shared across the control-toolbox ecosystem. Traits are empty marker
-types used as type parameters (or returned by accessor functions) so that
+traits** shared across the control-toolbox ecosystem. A trait is an abstract type
+used as a **type parameter** or returned by an accessor function so that
 behaviour can be selected by dispatch, with **no runtime cost**.
 
 ```@repl traits
 using CTBase
 import CTBase.Traits
 ```
 
-Downstream packages use these traits to encode, for example, the **call
-signature** of a vector field or Hamiltonian, and to dispatch system builders
-without runtime branches.
+A typical use case is encoding a property of a callable object — does it take a
+time argument? does it depend on an extra variable? is it evaluated in-place? —
+so that a wrapper type can select the correct call path at compile time, without
+runtime conditionals.
 
 ## Trait families
 
@@ -30,8 +31,8 @@ Does the object depend on time ``t``?
 | [`Traits.NonAutonomous`](@ref CTBase.Traits.NonAutonomous) | ``t`` must be supplied |
 
 Both are abstract subtypes of [`Traits.TimeDependence`](@ref CTBase.Traits.TimeDependence).
-They are used as the time-dependence type parameter of `CTModels.Model` and of
-CTFlows data wrappers.
+Because they are abstract, they can only appear as type parameters — they are not
+instantiated, only dispatched upon.
 
 ```@repl traits
 Traits.Autonomous <: Traits.TimeDependence
@@ -48,6 +49,8 @@ design variable)?
 | [`Traits.Fixed`](@ref CTBase.Traits.Fixed) | no ``v`` argument |
 | [`Traits.NonFixed`](@ref CTBase.Traits.NonFixed) | ``v`` must be supplied |
 
+Both are concrete subtypes of [`Traits.VariableDependence`](@ref CTBase.Traits.VariableDependence):
+
 ```@repl traits
 Traits.Fixed <: Traits.VariableDependence
 Traits.NonFixed <: Traits.VariableDependence
@@ -64,6 +67,10 @@ Does a function allocate a new output, or write into a pre-allocated buffer?
 
 ### Other families
 
+These traits encode properties that are fixed at construction time and carried
+as type parameters. They are not opted into via the two-method contract described
+below — they are passed directly as type arguments.
+
 | Family | Values |
 |---|---|
 | Integration mode | [`Traits.EndPointMode`](@ref CTBase.Traits.EndPointMode), [`Traits.TrajectoryMode`](@ref CTBase.Traits.TrajectoryMode) |
@@ -79,7 +86,7 @@ A type opts in to a trait by implementing **two methods**: one declaring that it
 [`Traits.is_variable`](@ref CTBase.Traits.is_variable), …) then follow
 generically — they are not implemented per type.
 
-For time dependence, implement `has_time_dependence_trait` and `time_dependence`:
+For time and variable dependence:
 
 ```@repl traits
 struct MyObject end
@@ -91,24 +98,40 @@ Traits.has_variable_dependence_trait(::MyObject) = true
 Traits.variable_dependence(::MyObject) = Traits.Fixed
 
 obj = MyObject()
-Traits.is_autonomous(obj)      # false  (derived from time_dependence)
-Traits.is_nonautonomous(obj)   # true
-Traits.is_variable(obj)        # false  (derived from variable_dependence)
-Traits.is_nonvariable(obj)     # true
+Traits.is_autonomous(obj)
+Traits.is_nonautonomous(obj)
+Traits.is_variable(obj)
+Traits.is_nonvariable(obj)
+```
+
+For mutability, the same pattern applies with `has_mutability_trait` and `mutability`:
+
+```@repl traits
+struct MyMutableObject end
+
+Traits.has_mutability_trait(::MyMutableObject) = true
+Traits.mutability(::MyMutableObject) = Traits.InPlace
+
+Traits.is_inplace(MyMutableObject())
+Traits.is_outofplace(MyMutableObject())
 ```
 
 If a type does not declare a trait, the predicates throw an informative error
 rather than returning a wrong default:
 
 ```@repl traits
+try # hide
 Traits.is_autonomous(3.14)
+catch e # hide
+showerror(IOContext(stdout, :color => false), e) # hide
+end # hide
 ```
 
-!!! note "Single source of truth"
-    `Traits.Autonomous` / `Traits.NonAutonomous` are the very types used as the
-    `CTModels.Model` time-dependence parameter, so `Traits.time_dependence(model)`
-    and `Traits.is_autonomous(model)` work out of the box on a real optimal
-    control problem.
+!!! note "Trait types are shared"
+    Because trait types (e.g. `Traits.Autonomous`) are defined in a single place,
+    a type that carries `Traits.Autonomous` as a type parameter and an object that
+    implements `time_dependence` returning `Traits.Autonomous` are compatible by
+    construction — no conversion or mapping needed.
 
 ## Accessor / predicate summary
 
@@ -120,3 +143,7 @@ Traits.is_autonomous(3.14)
 | [`Traits.ad_trait`](@ref CTBase.Traits.ad_trait) | — |
 | [`Traits.variable_costate_trait`](@ref CTBase.Traits.variable_costate_trait) | — |
 | [`Traits.dynamics_trait`](@ref CTBase.Traits.dynamics_trait) | — |
+
+## See Also
+
+- [Exceptions guide](exceptions.md) — understanding `IncorrectArgument` and `NotImplemented`.
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -27,6 +27,7 @@ It provides the **base layer** shared by all packages: common types, structured
 | [`CTBase.Core`](@ref) | Fundamental numeric type alias (`ctNumber`) and internal display helpers |
 | [`CTBase.Descriptions`](@ref) | Symbolic description tuples: catalogue management, pattern completion, similarity search |
 | [`CTBase.Exceptions`](@ref) | Typed exception hierarchy with rich context fields |
+| [`CTBase.Traits`](@ref) | Compile-time trait types for time dependence, variable dependence, mutability, and dynamics dispatch |
 | [`CTBase.DevTools`](@ref) | Developer tools with tag-based dispatch for `run_tests`, `postprocess_coverage`, and `automatic_reference_documentation` |
 | [`CTBase.Unicode`](@ref) | Unicode subscript/superscript helpers for display |
 
@@ -35,6 +36,7 @@ It provides the **base layer** shared by all packages: common types, structured
 - **[Getting Started](getting-started.md)** — installation, mental model, 5-minute walkthrough.
 - **[Descriptions](guide/descriptions.md)** — catalogue API, pattern matching, error handling.
 - **[Exceptions](guide/exceptions.md)** — exception hierarchy, choosing the right type, best practices.
+- **[Traits](guide/traits.md)** — compile-time trait types, the opt-in contract, and predicate functions.
 - **[Test Runner](guide/test-runner.md)** — modular test infrastructure with `CTBase.DevTools.run_tests`.
 - **[Coverage](guide/coverage.md)** — post-processing coverage artifacts with `CTBase.postprocess_coverage`.
 - **[API Documentation](guide/api-documentation.md)** — auto-generating per-module API pages.
diff --git a/src/Traits/Traits.jl b/src/Traits/Traits.jl
@@ -1,23 +1,47 @@
 """
     Traits
 
-Trait types and trait-based dispatch shared across the control-toolbox ecosystem.
-
-This module provides the trait system used for compile-time dispatch on:
-- Time dependence: [`Autonomous`](@ref), [`NonAutonomous`](@ref)
-- Variable dependence: [`Fixed`](@ref), [`NonFixed`](@ref)
-- Integration mode: [`EndPointMode`](@ref), [`TrajectoryMode`](@ref)
-- Dynamics type: [`StateDynamics`](@ref), [`HamiltonianDynamics`](@ref), [`AugmentedHamiltonianDynamics`](@ref)
-- Mutability: [`InPlace`](@ref), [`OutOfPlace`](@ref)
-- Automatic differentiation: [`WithAD`](@ref), [`WithoutAD`](@ref)
-- Variable costate capability: [`SupportsVariableCostate`](@ref), [`NoVariableCostate`](@ref)
-
-Traits are used as type parameters in configuration types, vector fields, and systems
-to enable static dispatch without runtime type checks.
-
-The time-dependence trait types (`TimeDependence`, `Autonomous`, `NonAutonomous`)
-historically lived in `CTModels.Components`; they are now defined here so the whole
-ecosystem shares a single set of types (CTModels consumes them from here).
+Compile-time trait types and trait-based dispatch utilities.
+
+Traits are abstract or empty concrete types used as type parameters or returned
+by accessor functions. Behaviour is selected by dispatch at compile time, with
+no runtime cost.
+
+# Organization
+
+- **abstract.jl**: Root abstract type `AbstractTrait` and family abstractions
+- **time_dependence.jl**: Time-dependence traits and the opt-in contract
+- **variable_dependence.jl**: Variable-dependence traits and the opt-in contract
+- **mutability.jl**: Mutability traits and the opt-in contract
+- **mode.jl**: Integration-mode traits (`EndPointMode`, `TrajectoryMode`)
+- **dynamics.jl**: Dynamics-type traits (`StateDynamics`, `HamiltonianDynamics`, `AugmentedHamiltonianDynamics`)
+- **ad.jl**: Automatic-differentiation traits (`WithAD`, `WithoutAD`)
+- **variable_costate.jl**: Variable-costate traits (`SupportsVariableCostate`, `NoVariableCostate`)
+- **helpers.jl**: Internal utility (`_caller_function_name`)
+
+# Public API
+
+## Trait families
+
+- **Time dependence**: `TimeDependence`, `Autonomous`, `NonAutonomous`
+- **Variable dependence**: `VariableDependence`, `Fixed`, `NonFixed`
+- **Mutability**: `InPlace`, `OutOfPlace`
+- **Integration mode**: `EndPointMode`, `TrajectoryMode`
+- **Dynamics**: `StateDynamics`, `HamiltonianDynamics`, `AugmentedHamiltonianDynamics`
+- **Automatic differentiation**: `WithAD`, `WithoutAD`
+- **Variable costate**: `SupportsVariableCostate`, `NoVariableCostate`
+
+## Trait contract
+
+For time-dependence, variable-dependence, and mutability, a type opts in by
+implementing two methods — `has_<family>_trait` returning `true`, and an accessor
+(`time_dependence`, `variable_dependence`, `mutability`) returning the trait type.
+Boolean predicates (`is_autonomous`, `is_variable`, `is_inplace`, …) are then
+derived generically.
+
+The remaining families (`EndPointMode`, `StateDynamics`, `WithAD`,
+`SupportsVariableCostate`) are used as type parameters only and do not use the
+two-method contract.
 """
 module Traits
 
diff --git a/src/Traits/abstract.jl b/src/Traits/abstract.jl
@@ -1,29 +1,20 @@
 """
 $(TYPEDEF)
 
-Abstract base type for trait markers in CTFlows.
+Abstract base type for all trait markers.
 
-Traits are empty marker types used as type parameters to encode configuration
-properties at compile time. Unlike tags (which mark extension implementations),
-traits encode semantic properties of the configuration itself (e.g., integration
-mode, content type, mutability).
-
-# Trait Pattern
-
-Traits are used as type parameters in abstract configuration types to enable
-compile-time dispatch without runtime type checks. For example, `AbstractConfig`
-uses `EndPointMode` vs `TrajectoryMode` to distinguish integration modes, and
-`StateDynamics` vs `HamiltonianDynamics` to distinguish dynamics types.
-
-All concrete trait types are empty structs with no fields, making them zero-cost
-at runtime.
+Traits are empty marker types used as type parameters to encode properties at
+compile time. Unlike tags (which mark extension implementations), traits encode
+semantic properties of an object (e.g., integration mode, dynamics type,
+mutability). All concrete trait types are empty structs with no fields, making
+them zero-cost at runtime.
 
 # Interface Requirements
 
 Concrete trait subtypes should:
 - Be empty structs with no fields (pure markers)
 - Subtype an intermediate abstract trait category (e.g., `AbstractModeTrait`)
-- Be used as type parameters in configuration types
+- Be used as type parameters or returned by accessor functions
 
 # Example
 \`\`\`julia-repl
@@ -34,10 +25,6 @@ true
 
 julia> EndPointMode <: Traits.AbstractModeTrait
 true
-
-julia> # Used as type parameters in configs:
-julia> StateEndPointConfig <: CTFlows.Configs.AbstractConfig{<:Any, EndPointMode, StateDynamics}
-true
 \`\`\`
 
 # Notes
diff --git a/src/Traits/ad.jl b/src/Traits/ad.jl
@@ -31,7 +31,7 @@ true
 - `WithoutAD` indicates the system uses pre-computed derivatives or manual implementations
 - The specific meaning depends on the system type and context
 
-See also: [`CTBase.Traits.WithAD`](@ref), [`CTBase.Traits.WithoutAD`](@ref), [`CTBase.Core.AbstractCache`](@ref).
+See also: [`CTBase.Traits.WithAD`](@ref), [`CTBase.Traits.WithoutAD`](@ref), `CTBase.Core.AbstractCache`.
 """
 abstract type AbstractADTrait <: AbstractTrait end
 
@@ -66,7 +66,7 @@ true
 - The cache is passed through parameters during integration or evaluation
 - The specific operations enabled depend on the system type and AD backend
 
-See also: [`CTBase.Traits.AbstractADTrait`](@ref), [`CTBase.Traits.WithoutAD`](@ref), [`CTBase.Core.AbstractCache`](@ref).
+See also: [`CTBase.Traits.AbstractADTrait`](@ref), [`CTBase.Traits.WithoutAD`](@ref), `CTBase.Core.AbstractCache`.
 """
 struct WithAD <: AbstractADTrait end  # system carries H + AD backend
 
diff --git a/src/Traits/dynamics.jl b/src/Traits/dynamics.jl
@@ -16,18 +16,13 @@ true
 
 julia> HamiltonianDynamics <: Traits.AbstractDynamicsTrait
 true
-
-julia> # Used in configuration type parameters:
-julia> StateEndPointConfig <: CTFlows.Configs.AbstractConfig{<:Any, <:Traits.AbstractModeTrait, StateDynamics}
-true
 \`\`\`
 
 # Notes
-- Dynamics traits are used as the third type parameter in `AbstractConfigWithMaC`
 - State dynamics indicates configurations with only state variables (no costate)
 - Hamiltonian dynamics indicates configurations with both state and costate variables
 
-See also: [`CTBase.Traits.StateDynamics`](@ref), [`CTBase.Traits.HamiltonianDynamics`](@ref), [`CTFlows.Configs.AbstractConfig`](@ref).
+See also: [`CTBase.Traits.StateDynamics`](@ref), [`CTBase.Traits.HamiltonianDynamics`](@ref).
 """
 abstract type AbstractDynamicsTrait <: AbstractTrait end
 
@@ -49,17 +44,14 @@ StateDynamics()
 julia> st isa Traits.AbstractDynamicsTrait
 true
 
-julia> # Used in state-only configurations:
-julia> StateEndPointConfig <: CTFlows.Configs.AbstractConfig{<:Any, <:Traits.AbstractModeTrait, StateDynamics}
-true
 \`\`\`
 
 # Notes
 - State configurations store only `x0` (initial state)
 - The `initial_costate` accessor throws a `PreconditionError` for state configurations
 - This mode is suitable for standard ODE integration without adjoint variables
 
-See also: [`CTBase.Traits.HamiltonianDynamics`](@ref), [`CTBase.Traits.AbstractDynamicsTrait`](@ref), [`CTFlows.Configs.StateEndPointConfig`](@ref).
+See also: [`CTBase.Traits.HamiltonianDynamics`](@ref), [`CTBase.Traits.AbstractDynamicsTrait`](@ref).
 """
 struct StateDynamics <: AbstractDynamicsTrait end
 
@@ -81,17 +73,14 @@ HamiltonianDynamics()
 julia> ham isa Traits.AbstractDynamicsTrait
 true
 
-julia> # Used in Hamiltonian configurations:
-julia> HamiltonianEndPointConfig <: CTFlows.Configs.AbstractConfig{<:Any, <:Traits.AbstractModeTrait, HamiltonianDynamics}
-true
 \`\`\`
 
 # Notes
 - Hamiltonian configurations store both `x0` (initial state) and `p0` (initial costate)
 - The `initial_condition` accessor returns `vcat(x0, p0)` for Hamiltonian configurations
 - This mode is suitable for optimal control problems with Pontryagin's maximum principle
 
-See also: [`CTBase.Traits.StateDynamics`](@ref), [`CTBase.Traits.AbstractDynamicsTrait`](@ref), [`CTFlows.Configs.HamiltonianEndPointConfig`](@ref).
+See also: [`CTBase.Traits.StateDynamics`](@ref), [`CTBase.Traits.AbstractDynamicsTrait`](@ref).
 """
 struct HamiltonianDynamics <: AbstractDynamicsTrait end
 
@@ -101,11 +90,10 @@ $(TYPEDEF)
 Trait marker for augmented Hamiltonian dynamics, where the Hamiltonian includes an augmented variable (e.g., a parameter or control variable) in addition to state and costate variables.
 
 # Notes
-- Used in conjunction with [`CTFlows.Configs.AbstractAugmentedHamiltonianConfig`](@ref) to specify that a configuration is for an augmented Hamiltonian system.
 - Subtypes [`CTBase.Traits.AbstractDynamicsTrait`](@ref).
 - Used to distinguish augmented Hamiltonian systems from standard Hamiltonian systems in trait-based dispatch.
 
-See also: [`CTBase.Traits.HamiltonianDynamics`](@ref), [`CTFlows.Configs.AbstractAugmentedHamiltonianConfig`](@ref), [`CTBase.Traits.AbstractDynamicsTrait`](@ref).
+See also: [`CTBase.Traits.HamiltonianDynamics`](@ref), [`CTBase.Traits.AbstractDynamicsTrait`](@ref).
 """
 struct AugmentedHamiltonianDynamics <: AbstractDynamicsTrait end
 
diff --git a/src/Traits/mode.jl b/src/Traits/mode.jl
diff --git a/src/Traits/mutability.jl b/src/Traits/mutability.jl
