feat: constraint-kind trait family and path-constraint/multiplier carriers

CHANGELOGS.md

@@ -5,6 +5,36 @@ All notable changes to CTBase will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.27.3-beta] - 2026-07-09
+
+### ✨ New Features
+
+#### **Traits** — constraint-kind trait family
+
+- **New `AbstractConstraintKind` trait family**: distinguishes path constraints by which
+  primal variables they depend on. Three concrete traits: `StateConstraintKind` (state only),
+  `ControlConstraintKind` (control only), `MixedConstraintKind` (state and control).
+  Type-parameter-only contract (like `AbstractFeedback`). Added `constraint_kind()` accessor
+  and predicates `is_state_constraint()`, `is_control_constraint()`, `is_mixed_constraint()`.
+
+#### **Data** — path constraint and multiplier carriers
+
+- **New `AbstractPathConstraint{K,TD,VD}` and `PathConstraint{F,K,TD,VD}` types**: generic
+  carriers for path-constraint functions with constraint-kind, time-dependence, and
+  variable-dependence traits. Supports natural call signatures per kind (e.g. `g(x)` for
+  state, `g(u)` for control, `g(x,u)` for mixed) and uniform signature `g(t,x,u,v)`.
+  User-facing constructors: `StateConstraint(g)`, `ControlConstraint(g)`, `MixedConstraint(g)`.
+- **New `AbstractMultiplier{TD,VD}` and `Multiplier{F,TD,VD}` types**: carriers for
+  Lagrange multiplier functions with time and variable dependence. Call signature `μ(t,x,p,v)`
+  (uniform) or natural forms `μ(x,p)`, `μ(t,x,p)`, etc. Semantically parallel to `Hamiltonian`.
+- **Display helpers**: `_kind_label`, `_natural_sig_pc` / `_natural_args_pc` / `_uniform_sig_pc`,
+  `_natural_sig_mult` / `_uniform_sig_mult` for `show` support.
+
+### 🔧 Compatibility
+
+- No breaking changes. New types and traits expand the API surface for path constraints
+  without affecting existing code.
+
 ## [0.27.2-beta] - 2026-07-09
 
 ### 🐛 Fixed

Project.toml

@@ -1,6 +1,6 @@
 name = "CTBase"
 uuid = "54762871-cc72-4466-b8e8-f6c8b58076cd"
-version = "0.27.2-beta"
+version = "0.27.3-beta"
 authors = ["Olivier Cots <olivier.cots@irit.fr>", "Jean-Baptiste Caillau <caillau@univ-cotedazur.fr>"]
 
 [deps]

src/Data/Data.jl

@@ -25,6 +25,10 @@ include(joinpath(@__DIR__, "abstract_hamiltonian.jl"))
 include(joinpath(@__DIR__, "hamiltonian.jl"))
 include(joinpath(@__DIR__, "abstract_control_law.jl"))
 include(joinpath(@__DIR__, "control_law.jl"))
+include(joinpath(@__DIR__, "abstract_path_constraint.jl"))
+include(joinpath(@__DIR__, "path_constraint.jl"))
+include(joinpath(@__DIR__, "abstract_multiplier.jl"))
+include(joinpath(@__DIR__, "multiplier.jl"))
 include(joinpath(@__DIR__, "abstract_pseudo_hamiltonian.jl"))
 include(joinpath(@__DIR__, "pseudo_hamiltonian.jl"))
 include(joinpath(@__DIR__, "composed_hamiltonian.jl"))
@@ -49,6 +53,13 @@ export ControlLaw
 export OpenLoop
 export ClosedLoop
 export DynClosedLoop
+export AbstractPathConstraint
+export PathConstraint
+export StateConstraint
+export ControlConstraint
+export MixedConstraint
+export AbstractMultiplier
+export Multiplier
 export AbstractPseudoHamiltonian
 export PseudoHamiltonian
 export ComposedHamiltonian

src/Data/abstract_multiplier.jl

@@ -0,0 +1,92 @@
+"""
+$(TYPEDEF)
+
+Abstract supertype for path-constraint multiplier functions together with their
+time-dependence and variable-dependence traits.
+
+A multiplier is a function `μ(t, x, p[, v])` returning the Lagrange multiplier
+associated with a path constraint. It has the same call structure as a
+[`CTBase.Data.AbstractHamiltonian`](@ref) (it depends on the state and costate), but
+carries no dynamics semantics of its own.
+
+# Type Parameters
+- `TD <: TimeDependence`: `Autonomous` or `NonAutonomous`.
+- `VD <: VariableDependence`: `Fixed` or `NonFixed`.
+
+# Notes
+- All multiplier types support both natural and uniform call signatures.
+- The uniform signature `(t, x, p, v)` is used internally by flows.
+
+See also: [`CTBase.Data.Multiplier`](@ref), [`CTBase.Traits.TimeDependence`](@ref), [`CTBase.Traits.VariableDependence`](@ref).
+"""
+abstract type AbstractMultiplier{TD<:Traits.TimeDependence,VD<:Traits.VariableDependence} end
+
+# =============================================================================
+# Trait accessors for AbstractMultiplier
+# =============================================================================
+
+"""
+$(TYPEDSIGNATURES)
+
+Indicates that all `AbstractMultiplier` types support time-dependence queries.
+
+# Returns
+- `true`: Always returns `true` for multiplier types.
+
+See also: [`CTBase.Traits.time_dependence`](@ref), [`CTBase.Data.AbstractMultiplier`](@ref).
+"""
+function Traits.has_time_dependence_trait(::AbstractMultiplier)
+    return true
+end
+
+"""
+$(TYPEDSIGNATURES)
+
+Indicates that all `AbstractMultiplier` types support variable-dependence queries.
+
+# Returns
+- `true`: Always returns `true` for multiplier types.
+
+See also: [`CTBase.Traits.variable_dependence`](@ref), [`CTBase.Data.AbstractMultiplier`](@ref).
+"""
+function Traits.has_variable_dependence_trait(::AbstractMultiplier)
+    return true
+end
+
+"""
+$(TYPEDSIGNATURES)
+
+Return the time-dependence trait of a multiplier.
+
+# Arguments
+- `m::AbstractMultiplier`: The multiplier object.
+
+# Returns
+- `TD`: The time-dependence type (`Autonomous` or `NonAutonomous`).
+
+See also: [`CTBase.Traits.time_dependence`](@ref), [`CTBase.Traits.TimeDependence`](@ref).
+"""
+function Traits.time_dependence(
+    ::AbstractMultiplier{TD,<:Traits.VariableDependence}
+) where {TD<:Traits.TimeDependence}
+    return TD
+end
+
+"""
+$(TYPEDSIGNATURES)
+
+Return the variable-dependence trait of a multiplier.
+
+# Arguments
+- `m::AbstractMultiplier`: The multiplier object.
+
+# Returns
+- `VD`: The variable-dependence type (`Fixed` or `NonFixed`).
+
+See also: [`CTBase.Traits.variable_dependence`](@ref), [`CTBase.Traits.VariableDependence`](@ref).
+"""
+function Traits.variable_dependence(
+    ::AbstractMultiplier{<:Traits.TimeDependence,VD}
+) where {VD<:Traits.VariableDependence}
+    return VD
+end

src/Data/abstract_path_constraint.jl

@@ -0,0 +1,165 @@
+# =============================================================================
+# AbstractPathConstraint — abstract supertype for path constraints
+# =============================================================================
+
+"""
+$(TYPEDEF)
+
+Abstract supertype for path constraints together with their constraint-kind,
+time-dependence, and variable-dependence traits.
+
+A path constraint is a function `g(...)` evaluated along the trajectory of an
+optimal control problem. The constraint-kind trait
+([`CTBase.Traits.AbstractConstraintKind`](@ref)) determines which primal variables the
+constraint depends on:
+
+- **State**: `g(x)` — depends on the state (and optionally time and variable).
+- **Control**: `g(u)` — depends on the control (and optionally time and variable).
+- **Mixed**: `g(x, u)` — depends on both state and control.
+
+# Type Parameters
+- `K <: AbstractConstraintKind`: `StateConstraintKind`, `ControlConstraintKind`, or `MixedConstraintKind`.
+- `TD <: TimeDependence`: `Autonomous` or `NonAutonomous`.
+- `VD <: VariableDependence`: `Fixed` or `NonFixed`.
+
+# Notes
+- All path constraint types support both natural and uniform call signatures.
+- The uniform signature is always `g(t, x, u, v)`, ignoring the unused arguments.
+
+See also: [`CTBase.Data.PathConstraint`](@ref), [`CTBase.Traits.AbstractConstraintKind`](@ref),
+[`CTBase.Traits.TimeDependence`](@ref), [`CTBase.Traits.VariableDependence`](@ref).
+"""
+abstract type AbstractPathConstraint{
+    K<:Traits.AbstractConstraintKind,
+    TD<:Traits.TimeDependence,
+    VD<:Traits.VariableDependence,
+} end
+
+# =============================================================================
+# Trait accessors for AbstractPathConstraint
+# =============================================================================
+
+"""
+$(TYPEDSIGNATURES)
+
+Return the constraint-kind trait of a path constraint.
+
+# Returns
+- `K`: The constraint-kind type (`StateConstraintKind`, `ControlConstraintKind`, or `MixedConstraintKind`).
+
+See also: [`CTBase.Traits.constraint_kind`](@ref), [`CTBase.Traits.AbstractConstraintKind`](@ref).
+"""
+function Traits.constraint_kind(
+    ::AbstractPathConstraint{K,<:Any,<:Any}
+) where {K<:Traits.AbstractConstraintKind}
+    return K
+end
+
+"""
+$(TYPEDSIGNATURES)
+
+Indicates that all `AbstractPathConstraint` types support time-dependence queries.
+
+# Returns
+- `true`: Always returns `true` for path constraint types.
+
+See also: [`CTBase.Traits.time_dependence`](@ref), [`CTBase.Data.AbstractPathConstraint`](@ref).
+"""
+function Traits.has_time_dependence_trait(::AbstractPathConstraint)
+    return true
+end
+
+"""
+$(TYPEDSIGNATURES)
+
+Indicates that all `AbstractPathConstraint` types support variable-dependence queries.
+
+# Returns
+- `true`: Always returns `true` for path constraint types.
+
+See also: [`CTBase.Traits.variable_dependence`](@ref), [`CTBase.Data.AbstractPathConstraint`](@ref).
+"""
+function Traits.has_variable_dependence_trait(::AbstractPathConstraint)
+    return true
+end
+
+"""
+$(TYPEDSIGNATURES)
+
+Return the time-dependence trait of a path constraint.
+
+# Arguments
+- `pc::AbstractPathConstraint`: The path constraint object.
+
+# Returns
+- `TD`: The time-dependence type (`Autonomous` or `NonAutonomous`).
+
+See also: [`CTBase.Traits.time_dependence`](@ref), [`CTBase.Traits.TimeDependence`](@ref).
+"""
+function Traits.time_dependence(
+    ::AbstractPathConstraint{<:Any,TD,<:Traits.VariableDependence}
+) where {TD<:Traits.TimeDependence}
+    return TD
+end
+
+"""
+$(TYPEDSIGNATURES)
+
+Return the variable-dependence trait of a path constraint.
+
+# Arguments
+- `pc::AbstractPathConstraint`: The path constraint object.
+
+# Returns
+- `VD`: The variable-dependence type (`Fixed` or `NonFixed`).
+
+See also: [`CTBase.Traits.variable_dependence`](@ref), [`CTBase.Traits.VariableDependence`](@ref).
+"""
+function Traits.variable_dependence(
+    ::AbstractPathConstraint{<:Any,<:Traits.TimeDependence,VD}
+) where {VD<:Traits.VariableDependence}
+    return VD
+end
+
+# =============================================================================
+# Constraint-kind predicates — dispatch on the K type parameter
+# =============================================================================
+
+"""
+$(TYPEDSIGNATURES)
+
+Return `true` if the path constraint is a pure state constraint, `false` otherwise.
+
+# Returns
+- `Bool`: `true` if the constraint-kind trait is `StateConstraintKind`, `false` otherwise.
+
+See also: [`CTBase.Traits.StateConstraintKind`](@ref), [`CTBase.Traits.constraint_kind`](@ref).
+"""
+Traits.is_state_constraint(::AbstractPathConstraint) = false
+Traits.is_state_constraint(::AbstractPathConstraint{<:Traits.StateConstraintKind}) = true
+
+"""
+$(TYPEDSIGNATURES)
+
+Return `true` if the path constraint is a pure control constraint, `false` otherwise.
+
+# Returns
+- `Bool`: `true` if the constraint-kind trait is `ControlConstraintKind`, `false` otherwise.
+
+See also: [`CTBase.Traits.ControlConstraintKind`](@ref), [`CTBase.Traits.constraint_kind`](@ref).
+"""
+Traits.is_control_constraint(::AbstractPathConstraint) = false
+Traits.is_control_constraint(::AbstractPathConstraint{<:Traits.ControlConstraintKind}) = true
+
+"""
+$(TYPEDSIGNATURES)
+
+Return `true` if the path constraint is a mixed state–control constraint, `false` otherwise.
+
+# Returns
+- `Bool`: `true` if the constraint-kind trait is `MixedConstraintKind`, `false` otherwise.
+
+See also: [`CTBase.Traits.MixedConstraintKind`](@ref), [`CTBase.Traits.constraint_kind`](@ref).
+"""
+Traits.is_mixed_constraint(::AbstractPathConstraint) = false
+Traits.is_mixed_constraint(::AbstractPathConstraint{<:Traits.MixedConstraintKind}) = true