Add PseudoHamiltonianVectorField data type

BREAKING.md

@@ -3,6 +3,15 @@
 
 This document outlines all breaking changes introduced in CTBase v0.18.0-beta compared to v0.17.4. Use this guide to migrate your code and understand the impact of these changes.
 
+## Non-breaking note (0.28.5-beta)
+
+- **`Data`: new `PseudoHamiltonianVectorField` / `AbstractPseudoHamiltonianVectorField`
+  data type.** Purely additive: two new exported symbols in `CTBase.Data`
+  (`AbstractPseudoHamiltonianVectorField`, `PseudoHamiltonianVectorField`),
+  no changes to any existing type, signature, or exported symbol. **No
+  breaking change**: existing code is entirely unaffected. No migration
+  required.
+
 ## Non-breaking note (0.28.4-beta)
 
 - **`Strategies`: Tip line in `show` now displays the parameterized type

CHANGELOG.md

@@ -6,6 +6,59 @@ 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.28.5-beta] - 2026-07-24
+
+### ✨ New Features
+
+#### **PseudoHamiltonianVectorField**
+
+- **New `PseudoHamiltonianVectorField` data type** in `CTBase.Data` for
+  pseudo-Hamiltonian dynamics that have already been differentiated by
+  hand, with an explicit control argument:
+  - **Definition**: `h̃vf(t, x, p, u, v) = (ẋ, ṗ)` — the vector-field
+    analogue of `PseudoHamiltonian`, the same way `HamiltonianVectorField`
+    is the vector-field analogue of `Hamiltonian`
+  - **Abstract supertype**: `AbstractPseudoHamiltonianVectorField{TD, VD,
+    MD} <: AbstractVectorField{TD, VD, MD}` — a **sibling** of
+    `AbstractHamiltonianVectorField`, not a subtype, mirroring the existing
+    `AbstractPseudoHamiltonian`/`AbstractHamiltonian` sibling relationship;
+    `dynamics_trait = HamiltonianDynamics`
+  - **Both in-place and out-of-place**, mirroring `HamiltonianVectorField`
+    exactly: mutability is auto-detected from the wrapped function's
+    arity, or set explicitly via `is_inplace`
+  - **Variable-costate support** (`dpv`) from the start via the
+    `variable_costate` keyword, mirroring `HamiltonianVectorField`'s
+    `variable_costate` kwarg
+  - **Natural + uniform call signatures**: one natural arity per `(TD, VD,
+    MD)` combination (one more than `HamiltonianVectorField`'s, for the
+    extra `u`) and uniform `(t, x, p, u, v)` / in-place `(dx, dp, t, x, p,
+    u, v)` calls
+  - **No `hamiltonian(sys)` accessor** on the downstream system side
+    (CTFlows.jl) — deliberate, matching `HamiltonianVectorFieldSystem`'s
+    existing gap, since no scalar `H̃` is ever built
+
+### 🧪 Testing
+
+- Added `test/suite/data/test_abstract_pseudo_hamiltonian_vector_field.jl`:
+  abstract-type definition, sibling (not subtype) check against
+  `AbstractHamiltonianVectorField`, trait accessors, dynamics trait,
+  Liskov substitution, exports (17 tests)
+- Added `test/suite/data/test_pseudo_hamiltonian_vector_field.jl`:
+  construction (all `TD`/`VD`/`MD` combinations), natural/uniform
+  signatures, trait accessors, typed constructor, subtyping, `Base.show`,
+  explicit `is_inplace`, ambiguous-arity `PreconditionError`,
+  `variable_costate`/`dpv` behavior (92 tests)
+- Full suite green: **4882/4882**
+
+### 📚 Documentation
+
+- Added the two new `Data/` source files to `docs/api_reference.jl`
+
+### ✅ Compatibility
+
+- **No breaking changes**: purely additive. Existing code unaffected. See
+  [BREAKING.md](BREAKING.md).
+
 ## [0.28.4-beta] - 2026-07-23
 
 ### 🐛 Bug Fixes

Project.toml

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

docs/api_reference.jl

@@ -57,6 +57,8 @@ function generate_api_reference(src_dir::String)
                 joinpath("Data", "hamiltonian.jl"),
                 joinpath("Data", "abstract_hamiltonian_vector_field.jl"),
                 joinpath("Data", "hamiltonian_vector_field.jl"),
+                joinpath("Data", "abstract_pseudo_hamiltonian_vector_field.jl"),
+                joinpath("Data", "pseudo_hamiltonian_vector_field.jl"),
                 joinpath("Data", "abstract_control_law.jl"),
                 joinpath("Data", "control_law.jl"),
                 joinpath("Data", "abstract_path_constraint.jl"),

src/Data/Data.jl

@@ -37,6 +37,8 @@ include(joinpath(@__DIR__, "controlled_vector_field.jl"))
 include(joinpath(@__DIR__, "composed_vector_field.jl"))
 include(joinpath(@__DIR__, "abstract_hamiltonian_vector_field.jl"))
 include(joinpath(@__DIR__, "hamiltonian_vector_field.jl"))
+include(joinpath(@__DIR__, "abstract_pseudo_hamiltonian_vector_field.jl"))
+include(joinpath(@__DIR__, "pseudo_hamiltonian_vector_field.jl"))
 
 # ==============================================================================
 # Module exports
@@ -62,6 +64,8 @@ export AbstractMultiplier
 export Multiplier
 export AbstractPseudoHamiltonian
 export PseudoHamiltonian
+export AbstractPseudoHamiltonianVectorField
+export PseudoHamiltonianVectorField
 export ComposedHamiltonian
 export pseudo_hamiltonian
 export control_law

src/Data/abstract_pseudo_hamiltonian_vector_field.jl

@@ -0,0 +1,55 @@
+# =============================================================================
+# AbstractPseudoHamiltonianVectorField — Abstract type for pseudo-Hamiltonian
+# vector fields
+# =============================================================================
+
+"""
+$(TYPEDEF)
+
+Abstract supertype for pseudo-Hamiltonian vector fields.
+
+A pseudo-Hamiltonian vector field represents the already-differentiated dynamics
+`(ẋ, ṗ) = (dx, dp)(t, x, p, u[, v])` of a pseudo-Hamiltonian system, with an explicit
+control argument `u` — the vector-field analogue of
+[`CTBase.Data.AbstractPseudoHamiltonian`](@ref), exactly as
+[`CTBase.Data.AbstractHamiltonianVectorField`](@ref) is the vector-field analogue of
+[`CTBase.Data.AbstractHamiltonian`](@ref). It extends `AbstractVectorField` with the
+additional structure required for Hamiltonian mechanics.
+
+`AbstractPseudoHamiltonianVectorField` is a **sibling** of
+[`CTBase.Data.AbstractHamiltonianVectorField`](@ref), not a subtype of it — mirroring how
+[`CTBase.Data.AbstractPseudoHamiltonian`](@ref) is a sibling of, not a subtype of,
+[`CTBase.Data.AbstractHamiltonian`](@ref): a pseudo-Hamiltonian vector field's natural
+call signature carries an extra control argument `u` that a plain Hamiltonian vector
+field does not have.
+
+# Type Parameters
+- `TD <: TimeDependence`: Time dependence trait (Autonomous or NonAutonomous)
+- `VD <: VariableDependence`: Variable dependence trait (Fixed or NonFixed)
+- `MD <: AbstractMutabilityTrait`: Mutability trait (InPlace or OutOfPlace)
+
+# Interface Requirements
+
+All subtypes must implement:
+- Call signature: `(t, x, p, u)` or `(x, p, u)` depending on time dependence, plus `v`
+  for non-fixed problems.
+- Returns the combined state-costate derivative `(dx, dp)`.
+
+See also: [`CTBase.Data.AbstractVectorField`](@ref), [`CTBase.Data.PseudoHamiltonianVectorField`](@ref),
+[`CTBase.Data.AbstractHamiltonianVectorField`](@ref), [`CTBase.Data.AbstractPseudoHamiltonian`](@ref).
+"""
+abstract type AbstractPseudoHamiltonianVectorField{
+    TD<:Traits.TimeDependence,
+    VD<:Traits.VariableDependence,
+    MD<:Traits.AbstractMutabilityTrait,
+} <: AbstractVectorField{TD,VD,MD} end
+
+"""
+$(TYPEDSIGNATURES)
+
+Return the dynamics trait of an `AbstractPseudoHamiltonianVectorField`, namely
+[`CTBase.Traits.HamiltonianDynamics`](@ref).
+
+See also: [`CTBase.Traits.dynamics_trait`](@ref), [`CTBase.Data.AbstractPseudoHamiltonianVectorField`](@ref).
+"""
+Traits.dynamics_trait(::AbstractPseudoHamiltonianVectorField) = Traits.HamiltonianDynamics

src/Data/helpers.jl

@@ -216,6 +216,57 @@ function _uniform_sig_hvf(::Type{Traits.InPlace})
     return "f(dx, dp, t, x, p, v)"
 end
 
+# =============================================================================
+# PseudoHamiltonianVectorField-specific signature helpers
+# =============================================================================
+
+"""
+    _natural_sig_phvf(::Type{TD}, ::Type{VD}, ::Type{Traits.OutOfPlace}) where {TD, VD} -> String
+    _natural_sig_phvf(::Type{TD}, ::Type{VD}, ::Type{Traits.InPlace}) where {TD, VD} -> String
+
+Return the natural call signature for a PseudoHamiltonianVectorField based on its traits.
+
+See also: [`CTBase.Data._uniform_sig_phvf`](@ref), [`CTBase.Data._natural_sig_hvf`](@ref).
+"""
+function _natural_sig_phvf(
+    ::Type{TD}, ::Type{VD}, ::Type{Traits.OutOfPlace}
+) where {TD<:Traits.TimeDependence,VD<:Traits.VariableDependence}
+    args = String[]
+    TD === Traits.NonAutonomous && push!(args, "t")
+    push!(args, "x")
+    push!(args, "p")
+    push!(args, "u")
+    VD === Traits.NonFixed && push!(args, "v")
+    return "f(" * join(args, ", ") * ")"
+end
+
+function _natural_sig_phvf(
+    ::Type{TD}, ::Type{VD}, ::Type{Traits.InPlace}
+) where {TD<:Traits.TimeDependence,VD<:Traits.VariableDependence}
+    args = ["dx", "dp"]
+    TD === Traits.NonAutonomous && push!(args, "t")
+    push!(args, "x")
+    push!(args, "p")
+    push!(args, "u")
+    VD === Traits.NonFixed && push!(args, "v")
+    return "f(" * join(args, ", ") * ")"
+end
+
+"""
+    _uniform_sig_phvf(::Type{Traits.OutOfPlace}) -> String
+    _uniform_sig_phvf(::Type{Traits.InPlace}) -> String
+
+Return the uniform call signature for a PseudoHamiltonianVectorField.
+
+See also: [`CTBase.Data._natural_sig_phvf`](@ref), [`CTBase.Data._uniform_sig_hvf`](@ref).
+"""
+function _uniform_sig_phvf(::Type{Traits.OutOfPlace})
+    return "f(t, x, p, u, v)"
+end
+function _uniform_sig_phvf(::Type{Traits.InPlace})
+    return "f(dx, dp, t, x, p, u, v)"
+end
+
 # =============================================================================
 # Hamiltonian-specific signature helpers
 # =============================================================================