Options and strategies

julia

route_to(; kwargs...)

Create a disambiguated option value by explicitly routing it to specific strategies.

This function resolves ambiguity when the same option name exists in multiple strategies (e.g., both modeler and solver have max_iter). It creates a RoutedOption that tells the orchestration layer exactly which strategy should receive which value.

Arguments

kwargs...: Named arguments where keys are strategy identifiers (:solver, :modeler, etc.) and values are the option values to route to those strategies

Returns

RoutedOption: A routed option containing the strategy => value mappings

Throws

Exceptions.PreconditionError: If no strategies are provided

Example

julia

julia> using CTBase.Strategies

julia> # Single strategy
julia> route_to(solver=100)
RoutedOption((solver = 100,))

julia> # Multiple strategies with different values
julia> route_to(solver=100, modeler=50)
RoutedOption((solver = 100, modeler = 50))

julia> # Alternative positional syntax
julia> route_to(:solver, 100, :modeler, 50)
RoutedOption((solver = 100, modeler = 50))

Usage in solve()

julia

# Without disambiguation - error if max_iter exists in multiple strategies
solve(ocp, method; max_iter=100)  # ❌ Ambiguous!

# With disambiguation - explicit routing (keyword syntax)
solve(ocp, method;
    max_iter = route_to(solver=100)              # Only solver gets 100
)

solve(ocp, method;
    max_iter = route_to(solver=100, modeler=50)  # Different values for each
)

# With disambiguation - explicit routing (positional syntax)
solve(ocp, method;
    max_iter = route_to(:solver, 100, :modeler, 50)  # Different values for each
)

Notes

Strategy identifiers must match the actual strategy IDs in your method tuple
You can route to one or multiple strategies in a single call
Alternative positional syntax: route_to(:solver, 100, :modeler, 50)
Both syntaxes are equivalent; choose based on preference
This is the recommended way to disambiguate options
The orchestration layer will validate that the strategy IDs exist

julia

route_to(args...)

Create a disambiguated option value using positional arguments.

This is an alternative syntax to the keyword argument version. Accepts alternating strategy identifier (Symbol) and value pairs.

Arguments

args::Vararg{Any}: Alternating strategy_id (Symbol) and value pairs. Must have an even number of arguments. Odd-numbered arguments must be Symbols.

Returns

RoutedOption: A routed option containing the strategy => value mappings

Throws

Exceptions.PreconditionError: If no arguments provided, odd number of arguments, or odd-numbered arguments are not Symbols

Example

julia

julia> using CTBase.Strategies

julia> # Single strategy
julia> route_to(:solver, 100)
RoutedOption((solver = 100,))

julia> # Multiple strategies
julia> route_to(:solver, 100, :modeler, 50)
RoutedOption((solver = 100, modeler = 50))

Notes

This is equivalent to the keyword syntax: route_to(solver=100, modeler=50)
Strategy identifiers must be Symbols (e.g., :solver, not "solver")
The number of arguments must be even (pairs of Symbol-value)

CTBase.Strategies.bypass Function

julia

bypass(val) -> CTBase.Strategies.BypassValue

Mark an option value to bypass validation.

This function creates a BypassValue wrapper around the provided value. When passed to a strategy constructor, this value will be accepted even if the option name is unknown (not in metadata) or if validation would otherwise fail.

This can be combined with route_to to bypass validation for specific strategies when routing ambiguous options.

Arguments

val: The option value to wrap

Returns

BypassValue: The wrapped value

Example

julia

julia> using CTBase.Strategies

julia> # Pass an unknown option directly to strategy
julia> solver = Ipopt(
           max_iter=100, 
           custom_backend_option=bypass(42)  # Bypasses validation
       )
Ipopt(options=StrategyOptions{...})

julia> # Alternative syntax using force alias
julia> solver = Ipopt(
           max_iter=100, 
           custom_backend_option=force(42)  # Same as bypass(42)
       )
Ipopt(options=StrategyOptions{...})

julia> # Combine with routing for ambiguous options
julia> solve(ocp, method; 
           backend = route_to(ipopt=bypass(42))  # Route to ipopt AND bypass validation
       )

Notes

Use with caution! Bypassed options are passed directly to the backend.
Typos in option names will not be caught by validation.
Invalid values for the backend will cause backend-level errors.
Can be combined with route_to for strategy-specific bypassing
force is an alias for bypass - they are identical functions

CTBase.Strategies.force Function

Force an option value to bypass validation.

This function is an alias for bypass and provides identical functionality. The name force may be more intuitive for users who prefer "force" semantics when bypassing validation.

Arguments

val: The option value to wrap

Returns

BypassValue: The wrapped value

Example

julia

julia> using CTBase.Strategies

julia> # Force acceptance of unknown option
julia> solver = Ipopt(
           max_iter=100, 
           custom_backend_option=force(42)  # Forces validation bypass
       )
Ipopt(options=StrategyOptions{...})

julia> # Same as bypass(42)
julia> @test force(42) == bypass(42)
true

Notes

force and bypass are the same function: force === bypass
Choose the name that best fits your mental model
Both functions create BypassValue wrappers
Use with caution for the same reasons as bypass

CTBase.Strategies.options Function

Return the current options of a strategy as a StrategyOptions.

Arguments

strategy::AbstractStrategy: The strategy instance

Returns

StrategyOptions: Current option values with provenance tracking

Example

julia

# For a concrete strategy instance:
julia> strategy = MyStrategy(backend=:sparse)
julia> opts = options(strategy)
julia> opts
StrategyOptions with values=(backend=:sparse), sources=(backend=:user)

CTBase.Strategies.option_names Function

julia

option_names(
    strategy_type::Type{<:CTBase.Strategies.AbstractStrategy}
) -> Tuple

Get all option names for a strategy type.

Returns a tuple of all option names defined in the strategy's metadata. This is useful for discovering what options are available without needing to instantiate the strategy.

Arguments

strategy_type::Type{<:AbstractStrategy}: The strategy type to introspect

Returns

Tuple{Vararg{Symbol}}: Tuple of option names

Example

julia

julia> using CTBase.Strategies

julia> option_names(MyStrategy)
(:max_iter, :tol, :backend)

julia> for name in option_names(MyStrategy)
           println("Available option: ", name)
       end
Available option: max_iter
Available option: tol
Available option: backend

Notes

This function operates on types, not instances
If you have an instance, use option_names(typeof(strategy))

CTBase.Strategies.option_type Function

julia

option_type(
    strategy_type::Type{<:CTBase.Strategies.AbstractStrategy},
    key::Symbol
) -> Type

Get the expected type for a specific option.

Returns the Julia type that the option value must satisfy. This is useful for validation and documentation purposes.

Arguments

strategy_type::Type{<:AbstractStrategy}: The strategy type
key::Symbol: The option name

Returns

Type: The expected type for the option value

Example

julia

julia> using CTBase.Strategies

julia> option_type(MyStrategy, :max_iter)
Int64

julia> option_type(MyStrategy, :tol)
Float64

Throws

KeyError: If the option name does not exist

Notes

This function operates on types, not instances
If you have an instance, use option_type(typeof(strategy), key)

CTBase.Strategies.option_default Function

julia

option_default(
    strategy_type::Type{<:CTBase.Strategies.AbstractStrategy},
    key::Symbol
) -> Any

Get the default value for a specific option.

Returns the value that will be used if the option is not explicitly provided by the user during strategy construction.

Arguments

strategy_type::Type{<:AbstractStrategy}: The strategy type
key::Symbol: The option name

Returns

The default value for the option (type depends on the option)

Example

julia

julia> using CTBase.Strategies

julia> option_default(MyStrategy, :max_iter)
100

julia> option_default(MyStrategy, :tol)
1.0e-6

Throws

KeyError: If the option name does not exist

Notes

This function operates on types, not instances
If you have an instance, use option_default(typeof(strategy), key)

CTBase.Strategies.option_defaults Function

julia

option_defaults(
    strategy_type::Type{<:CTBase.Strategies.AbstractStrategy}
) -> NamedTuple

Get all default values as a NamedTuple.

Returns a NamedTuple containing the default value for every option defined in the strategy's metadata. This is useful for resetting configurations or understanding the baseline behavior.

Arguments

strategy_type::Type{<:AbstractStrategy}: The strategy type

Returns

NamedTuple: All default values keyed by option name

Example

julia

julia> using CTBase.Strategies

julia> option_defaults(MyStrategy)
(max_iter = 100, tol = 1.0e-6)

julia> defaults = option_defaults(MyStrategy)
julia> defaults.max_iter
100

Notes

This function operates on types, not instances
If you have an instance, use option_defaults(typeof(strategy))

CTBase.Strategies.option_description Function

julia

option_description(
    strategy_type::Type{<:CTBase.Strategies.AbstractStrategy},
    key::Symbol
) -> String

Get the human-readable description for a specific option.

Returns the documentation string that explains what the option controls. This is useful for generating help messages and documentation.

Arguments

strategy_type::Type{<:AbstractStrategy}: The strategy type
key::Symbol: The option name

Returns

String: The option description

Example

julia

julia> using CTBase.Strategies

julia> option_description(MyStrategy, :max_iter)
"Maximum number of iterations"

julia> option_description(MyStrategy, :tol)
"Convergence tolerance"

Throws

KeyError: If the option name does not exist

Notes

This function operates on types, not instances
If you have an instance, use option_description(typeof(strategy), key)

CTBase.Strategies.option_value Function

julia

option_value(
    strategy::CTBase.Strategies.AbstractStrategy,
    key::Symbol
) -> Any

Get the current value of an option from a strategy instance.

Returns the effective value that the strategy is using for the specified option. This may be a user-provided value or the default value.

Arguments

strategy::AbstractStrategy: The strategy instance
key::Symbol: The option name

Returns

The current option value (type depends on the option)

Example

julia

julia> using CTBase.Strategies

julia> strategy = MyStrategy(max_iter=200)
julia> option_value(strategy, :max_iter)
200

julia> option_value(strategy, :tol)  # Uses default
1.0e-6

Throws

KeyError: If the option name does not exist

CTBase.Strategies.option_source Function

julia

option_source(
    strategy::CTBase.Strategies.AbstractStrategy,
    key::Symbol
) -> Symbol

Get the source provenance of an option value.

Returns a symbol indicating where the option value came from:

:user - Explicitly provided by the user
:default - Using the default value from metadata
:computed - Calculated from other options

Arguments

strategy::AbstractStrategy: The strategy instance
key::Symbol: The option name

Returns

Symbol: The source provenance (:user, :default, or :computed)

Example

julia

julia> using CTBase.Strategies

julia> strategy = MyStrategy(max_iter=200)
julia> option_source(strategy, :max_iter)
:user

julia> option_source(strategy, :tol)
:default

Throws

KeyError: If the option name does not exist

CTBase.Strategies.has_option Function

julia

has_option(
    strategy::CTBase.Strategies.AbstractStrategy,
    key::Symbol
) -> Any

Check if an option exists in a strategy instance.

Returns true if the option is present in the strategy's options, false otherwise. This is useful for checking if unknown options were stored in permissive mode.

Arguments

strategy::AbstractStrategy: The strategy instance
key::Symbol: The option name

Returns

Bool: true if the option exists

Example

julia

julia> using CTBase.Strategies

julia> strategy = MyStrategy(max_iter=200; mode=:permissive, custom_opt=123)
julia> has_option(strategy, :max_iter)
true

julia> has_option(strategy, :custom_opt)
true

julia> has_option(strategy, :nonexistent)
false

CTBase.Options.is_user Function

julia

is_user(opt::CTBase.Options.OptionValue) -> Bool

Check if this option value was explicitly provided by the user.

Returns

Bool: true if the source is :user

Example

julia

opt = OptionValue(100, :user)
is_user(opt)  # true

julia

is_user(
    opts::CTBase.Strategies.StrategyOptions,
    key::Symbol
) -> Bool

Check if an option was provided by the user.

Arguments

opts::StrategyOptions: Strategy options
key::Symbol: Option name

Returns

Bool: true if the option was provided by the user

Example

julia

julia> Options.is_user(opts, :max_iter)
true

CTBase.Options.is_default Function

julia

is_default(opt::CTBase.Options.OptionValue) -> Bool

Check if this option value is using its default.

Returns

Bool: true if the source is :default

Example

julia

opt = OptionValue(100, :default)
is_default(opt)  # true

julia

is_default(
    opts::CTBase.Strategies.StrategyOptions,
    key::Symbol
) -> Bool

Check if an option is using its default value.

Arguments

opts::StrategyOptions: Strategy options
key::Symbol: Option name

Returns

Bool: true if the option is using its default value

Example

julia

julia> Options.is_default(opts, :tol)
true

CTBase.Options.is_computed Function

julia

is_computed(opt::CTBase.Options.OptionValue) -> Bool

Check if this option value was computed from other options.

Returns

Bool: true if the source is :computed

Example

julia

opt = OptionValue(100, :computed)
is_computed(opt)  # true

julia

is_computed(def::CTBase.Options.OptionDefinition) -> Bool

Check if this option definition has a computed default value.

Returns true when the default value is computed from strategy parameters (e.g., backend in Exa{GPU} which depends on the GPU parameter).

Returns

Bool: true if the default is computed from parameters

Example

julia

julia> using CTBase.Options

julia> # Static default
julia> def1 = OptionDefinition(name=:max_iter, type=Int, default=100,
                          description="Maximum iterations")
OptionDefinition{Int}(...)

julia> is_computed(def1)
false

julia> # Computed default
julia> def2 = OptionDefinition(name=:backend, type=Any, default=compute_backend(),
                          description="Backend", computed=true)
OptionDefinition{...}(...)

julia> is_computed(def2)
true

julia

is_computed(
    opts::CTBase.Strategies.StrategyOptions,
    key::Symbol
) -> Bool

Check if an option was computed.

Arguments

opts::StrategyOptions: Strategy options
key::Symbol: Option name

Returns

Bool: true if the option was computed

Example

julia

julia> Options.is_computed(opts, :step)
true

CTBase.Strategies.id Function

Return the unique identifier for this strategy type.

Arguments

strategy_type::Type{<:AbstractStrategy}: The strategy type

Returns

Symbol: Unique identifier for the strategy

Example

julia

# For a concrete strategy type MyStrategy:
julia> id(MyStrategy)
:mystrategy

CTBase.Strategies.metadata Function

Return metadata about a strategy type.

Arguments

strategy_type::Type{<:AbstractStrategy}: The strategy type

Returns

StrategyMetadata: Option specifications and validation rules

Example

julia

# For a concrete strategy type MyStrategy:
julia> meta = metadata(MyStrategy)
julia> meta
StrategyMetadata with option definitions for max_iter, etc.

CTBase.Strategies.create_registry Function

julia

create_registry(
    pairs::Pair...
) -> CTBase.Strategies.StrategyRegistry

Create a strategy registry from family-to-strategies mappings.

This function validates the registry structure and ensures:

All strategy IDs are unique within each family
All strategies are subtypes of their declared family
No duplicate family definitions

Arguments

pairs...: Pairs of family type => tuple of strategy types

Returns

StrategyRegistry: Validated registry ready for use

Validation Rules 2. ID Uniqueness: Within each family, all strategy id() values must be unique

Type Hierarchy: Each strategy must be a subtype of its family
No Duplicates: Each family can only appear once in the registry

Example

julia

julia> using CTBase.Strategies

julia> registry = create_registry(
           AbstractNLPModeler => (Modelers.ADNLP, Modelers.Exa),
           AbstractNLPSolver => (Solvers.Ipopt, Solvers.MadNLP, Solvers.Knitro)
       )
StrategyRegistry with 2 families

julia> strategy_ids(AbstractNLPModeler, registry)
(:adnlp, :exa)

Throws

ErrorException: If duplicate IDs are found within a family
ErrorException: If a strategy is not a subtype of its family
ErrorException: If a family appears multiple times

CTBase.Strategies.strategy_ids Function

julia

strategy_ids(
    family::Type{<:CTBase.Strategies.AbstractStrategy},
    registry::CTBase.Strategies.StrategyRegistry
) -> Tuple{Vararg{Symbol}}

Get all strategy IDs for a given family.

Returns a tuple of symbolic identifiers for all strategies registered under the specified family type. The order matches the registration order.

Arguments

family::Type{<:AbstractStrategy}: The abstract family type
registry::StrategyRegistry: The registry to query

Returns

Tuple{Vararg{Symbol}}: Tuple of strategy IDs in registration order

Example

julia

julia> using CTBase.Strategies

julia> ids = strategy_ids(AbstractNLPModeler, registry)
(:adnlp, :exa)

julia> for strategy_id in ids
           println("Available: ", strategy_id)
       end
Available: adnlp
Available: exa

Throws

ErrorException: If the family is not found in the registry

CTBase.Strategies.type_from_id Function

julia

type_from_id(
    strategy_id::Symbol,
    family::Type{<:CTBase.Strategies.AbstractStrategy},
    registry::CTBase.Strategies.StrategyRegistry;
    parameter
) -> Type

Lookup a strategy type from its ID within a family.

Searches the registry for a strategy with the given symbolic identifier within the specified family. This is the core lookup mechanism used by the builder functions to convert symbolic descriptions to concrete types.

Arguments

strategy_id::Symbol: The symbolic identifier to look up
family::Type{<:AbstractStrategy}: The family to search within
registry::StrategyRegistry: The registry to query

Returns

Type{<:AbstractStrategy}: The concrete strategy type matching the ID

Example

julia

julia> using CTBase.Strategies

julia> T = type_from_id(:adnlp, AbstractNLPModeler, registry)
Modelers.ADNLP

julia> id(T)
:adnlp

Throws

Exceptions.IncorrectArgument: If the family is not found in the registry
Exceptions.IncorrectArgument: If the ID is not found within the family (includes suggestions)

CTBase.Strategies.parameter Function

Return the strategy parameter type for a concrete strategy type, or nothing if the strategy is non-parameterized.

Every concrete strategy type must implement this method:

Non-parameterized strategies return nothing.
Parameterized strategies return the concrete parameter type.

Arguments

strategy_type::Type{<:AbstractStrategy}: The strategy type

Returns

Type{<:AbstractStrategyParameter}: The parameter type (e.g. CPU, GPU)
Nothing: If the strategy is non-parameterized

Example

julia

# Non-parameterized:
julia> parameter(Ipopt)
nothing

# Parameterized:
julia> parameter(MadNLP{CPU})
CPU

Implementation

julia

# Non-parameterized strategy:
Strategies.parameter(::Type{<:MyStrategy}) = nothing

# Parameterized strategy (bound repeated verbatim from the struct definition):
Strategies.parameter(::Type{<:MyStrategy{P}}) where {P<:AbstractStrategyParameter} = P

A non-throwing 2-arg variant, parameter(strategy_type, default), is also available for callers that cannot guarantee the type they're querying implements this contract — see below.

CTBase.Strategies.default_parameter Function

julia

default_parameter(
    _::Type{<:CTBase.Strategies.AbstractStrategy}
) -> Type{CPU}

Return the default parameter type used when constructing a parameterized strategy without an explicit parameter token.

This is a separate concern from CTBase.Strategies.parameter:

parameter(S) extracts the parameter from an already-instantiated type (e.g. S{CPU}).
default_parameter(S) declares which parameter to use when none is specified at construction.

Every parameterized strategy must implement this method. Non-parameterized strategies do not need to implement it.

Arguments

strategy_type::Type{<:AbstractStrategy}: The strategy type

Returns

Type{<:AbstractStrategyParameter}: Default parameter type

Throws

Exceptions.NotImplemented: If the strategy does not implement this method

Example

julia

# Strategy that defaults to CPU
Strategies.default_parameter(::Type{<:MyStrategy}) = Strategies.CPU

# Strategy that defaults to GPU
Strategies.default_parameter(::Type{<:MyOtherStrategy}) = Strategies.GPU

julia

default_parameter(
    _::Type{<:CTBase.Differentiation.DifferentiationInterface}
) -> Type{CPU}

Return the default execution parameter for DifferentiationInterface when none is specified.

Returns CPU, so DifferentiationInterface(...) builds a DifferentiationInterface{CPU} and every existing call site is unaffected by the device parameterization.

Options and strategies ​

Options and strategies