Public API

Common

Shared utilities and types for CTFlows.

This module provides fallback implementations for grid invariance (IND) support:

• deepvalue(x::Real) — Base case for extracting primal values
• real_norm(u::Real, t) — Base case for internal norm computation

ForwardDiff-specific implementations are provided in CTFlowsForwardDiff when ForwardDiff is loaded.

struct ODEParameters{V}

Wrapper type for parameters passed through SciML's p slot.

This type formalizes the contract for what transits in the ODE problem's parameter slot. For CTFlows, the primary content is the variable parameter for NonFixed systems (or nothing for Fixed systems).

The wrapper makes the contract explicit and extensible — additional fields can be added later (callbacks, extra data) without breaking existing code.

Fields

• variable::V: The variable parameter (or nothing for Fixed systems).

Constructor Validation

• V can be Nothing (for Fixed systems) or any concrete type (for NonFixed).
• No validation is performed at construction — the system's VariableDependence determines whether variable should be used.

Example

using CTFlows.Common

# Fixed system: variable is nothing
params_fixed = ODEParameters(nothing)

# NonFixed system: variable is a value
params_nonfixed = ODEParameters(0.5)

# NonFixed system: variable is a vector
params_vector = ODEParameters([1.0, 2.0])

Notes

• This type is used exclusively by the SciML extension to wrap the variable before passing it to ODEProblem.
• The RHS functor reads variable(p) to access the actual variable value.

See also: CTBase.Traits.VariableDependence, CTBase.Traits.Fixed, CTBase.Traits.NonFixed.

__hvf_inplace() -> Bool

Default value for in-place flag in hamiltonianvectorfield getter.

Returns false by default, meaning the getter returns out-of-place vector fields unless specified otherwise.

__unsafe() -> Bool

Default value for unsafe flag in integration functions.

Returns false by default, meaning ODE solver retcodes are checked and failures throw exceptions unless explicitly bypassed.

__variable() -> CTBase.Core.NotProvidedType

Default value for variable parameter in user-facing API calls.

Returns CTBase.Core.NotProvided by default, meaning the variable parameter is optional unless required by the system's trait (e.g., NonFixed systems).

See also: CTBase.Traits.VariableDependence, CTBase.Traits.Fixed, CTBase.Traits.NonFixed.

__variable_costate() -> Bool

Default value for variable_costate flag in Hamiltonian flow calls.

Returns false by default, meaning the flow does not integrate the augmented variable costate equation ṗᵥ = -∂H/∂v unless explicitly requested.

Returns

• Bool: The default value for the variable_costate parameter.

See also: CTFlows.Configs.AugmentedHamiltonianEndPointConfig.

deepvalue(x::Number) -> Number

Extract the primal value from a number. Base case for scalar numbers.

This is a fallback implementation used when AD backends are not loaded. ForwardDiff-specific implementations are provided in CTFlowsForwardDiff for recursive extraction from nested dual numbers.

Arguments

• x::Number: A number (e.g., Float64, ComplexF64).

Returns

• Number: The input value unchanged for real and complex numbers.

Example

julia> using CTFlows.Common

julia> deepvalue(3.14)
3.14

julia> deepvalue(1.0 + 2.0im)
1.0 + 2.0im

Notes

• For ForwardDiff.Dual numbers, the more specific method in CTFlowsForwardDiff recursively extracts the primal value via deepvalue(value(x)).
• This method serves as the base case for all Number subtypes not handled by extensions.

See also: CTFlows.Common.real_norm.

deepvalue(x::ForwardDiff.Dual) -> Number

Recursively extract the primal (real) value from a ForwardDiff dual number.

Handles nested dual numbers for higher-order differentiation (e.g., second-order derivatives where the partials themselves are dual numbers). This extends the fallback Common.deepvalue(x::Real) to support ForwardDiff.

Arguments

• x::ForwardDiff.Dual: A ForwardDiff dual number (possibly nested).

Returns

• Real: The primal (Float64) part of the dual number.

Example

julia> using ForwardDiff

julia> d1 = ForwardDiff.Dual{:Tag}(3.0, 1.0)
Dual{:Tag}(3.0, 1.0)

julia> CTFlowsForwardDiff.deepvalue(d1)
3.0

julia> d2 = ForwardDiff.Dual{:Tag2}(d1, d1)  # Nested dual
Dual{:Tag2}(Dual{:Tag}(3.0, 1.0), Dual{:Tag}(3.0, 1.0))

julia> CTFlowsForwardDiff.deepvalue(d2)
3.0

See also: Common.deepvalue, real_norm

real_norm(u::Number, t) -> Any

Compute the internal norm for a scalar number.

This is a fallback implementation used when AD backends are not loaded. ForwardDiff-specific implementations are provided in CTFlowsForwardDiff.

Arguments

• u::Number: A scalar number (real or complex).
• t: Time parameter (unused but required by SciML interface).

Returns

• Number: The absolute value for real numbers, or magnitude for complex numbers.

Example

julia> using CTFlows.Common

julia> real_norm(3.0, 0.0)
3.0

julia> real_norm(3.0 + 4.0im, 0.0)
5.0

Notes

• For real numbers, returns abs(u).
• For complex numbers, returns abs(u) (the magnitude).
• Used by SciML integrators for step-size control in grid-invariant computations.

See also: CTFlows.Common.deepvalue.

real_norm(u::ForwardDiff.Dual, t) -> Any

Compute the internal norm for a scalar ForwardDiff dual number using only its primal part.

This extends the fallback Common.real_norm(u::Real, t) to support ForwardDiff dual numbers, ensuring grid invariance (IND) when integrating ODEs with dual numbers.

Arguments

• u::ForwardDiff.Dual: A scalar dual number.
• t: Time parameter (unused but required by SciML interface).

Returns

• Real: The absolute value of the primal part.

See also: Common.real_norm, deepvalue

real_norm(u::AbstractArray, t) -> Any

Compute the internal norm for adaptive step-size control using only the primal parts of dual numbers.

This function ensures grid invariance (IND) when integrating ODEs with ForwardDiff dual numbers: the adaptive time grid chosen by the solver is identical whether integrating with real numbers or dual numbers. Without this, the step-size controller would make decisions based on dual values, breaking grid invariance.

This implementation uses Common.deepvalue to extract primal parts and DiffEqBase.ODE_DEFAULT_NORM to compute the norm. When ForwardDiff is loaded, Common.deepvalue is extended to handle dual numbers via CTFlowsForwardDiff.

Arguments

• u::AbstractArray: State vector (may contain dual numbers).
• t: Time parameter (unused but required by SciML interface).

Returns

• Real: The norm computed on the primal parts only.

Example

julia> using ForwardDiff

julia> u_real = [1.0, 2.0, 3.0]
julia> u_dual = ForwardDiff.Dual{:T}.(u_real, ones(3))

julia> CTFlowsSciMLIntegrator.real_norm(u_real, 0.0) ≈ CTFlowsSciMLIntegrator.real_norm(u_dual, 0.0)
true

See also: CTFlows.Common.deepvalue, CTFlows.Common.real_norm.

variable(p::CTFlows.Common.ODEParameters) -> Any

Accessor for the variable field of ODEParameters.

Returns the variable parameter stored in the ODEParameters wrapper. For Fixed systems, this is nothing. For NonFixed systems, this is the actual variable value (scalar or vector).

Arguments

• p::ODEParameters: The ODEParameters instance.

Returns

• The variable value (or nothing for Fixed systems).

Example

julia> using CTFlows.Common

julia> params_fixed = ODEParameters(nothing)
ODEParameters{Nothing}(nothing)

julia> variable(params_fixed)
nothing

julia> params_nonfixed = ODEParameters(0.5)
ODEParameters{Float64}(0.5)

julia> variable(params_nonfixed)
0.5

See also: CTFlows.Common.ODEParameters, CTBase.Traits.VariableDependence.