Public API

Generic option handling for CTModels tools and strategies.

This module provides the foundational types and functions for:

• Option value tracking with provenance
• Option schema definition with validation and aliases
• Option extraction with alias support
• Type validation and helpful error messages

The Options module is deliberately generic and has no dependencies on other CTModels modules, making it reusable across the ecosystem.

NotProvided

Singleton instance of NotProvidedType.

Use this as the default value in OptionDefinition to indicate that an option has no default value and should not be stored if not provided by the user.

Example

julia> using CTSolvers.Options

julia> def = OptionDefinition(
           name = :optional_param,
           type = Any,
           default = NotProvided,
           description = "Optional parameter"
       )

julia> # If user doesn't provide it, it won't be stored
julia> opts, _ = extract_options((other=1,), [def])
julia> haskey(opts, :optional_param)
false

struct NotProvidedType

Singleton type representing the absence of a default value for an option.

This type is used to distinguish between:

• default = NotProvided: No default value, option must be provided by user or not stored
• default = nothing: The default value is explicitly nothing

Example

# Option with no default - won't be stored if not provided
opt1 = OptionDefinition(
    name = :minimize,
    type = Union{Bool, Nothing},
    default = NotProvided,
    description = "Whether to minimize"
)

# Option with explicit nothing default - will be stored as nothing
opt2 = OptionDefinition(
    name = :backend,
    type = Union{Nothing, KernelAbstractions.Backend},
    default = nothing,
    description = "Execution backend"
)

See also: OptionDefinition, extract_options

struct OptionDefinition{T}

Unified option definition for both option extraction and strategy contracts.

This type provides a comprehensive option definition that can be used for:

• Option extraction in the Options module
• Strategy contract definition in the Strategies module
• Action schema definition

Fields

• name::Symbol: Primary name of the option
• type::Type: Expected Julia type for the option value
• default::T: Default value when the option is not provided (type parameter T)
• description::String: Human-readable description of the option's purpose
• aliases::Tuple{Vararg{Symbol}}: Alternative names for this option (default: empty tuple)
• validator::Union{Function, Nothing}: Optional validation function (default: nothing)
• computed::Bool: Whether the default value is computed from parameters (default: false)

Type Parameter T

The type parameter T represents the type of the default value:

• T = Any when default = nothing (explicit nothing default)
• T = NotProvidedType when default = NotProvided (no default value)
• T = typeof(default) for concrete default values

Validator Contract

Validators must follow this pattern:

x -> condition || throw(ArgumentError("error message"))

The validator should:

• Return true (or any truthy value) if the value is valid
• Throw an exception (preferably ArgumentError) if the value is invalid
• Be a pure function without side effects

Constructor Validation

The constructor performs the following validations:

1. Checks that default matches the specified type (unless default is nothing or NotProvided)
2. Runs the validator on the default value (if both are provided and default is not NotProvided)

Example

def = OptionDefinition(
    name = :max_iter,
    type = Int,
    default = 100,
    description = "Maximum number of iterations",
    aliases = (:max, :maxiter),
    validator = x -> x > 0 || throw(ArgumentError("$x must be positive"))
)

def.name      # :max_iter
def.aliases   # (:max, :maxiter)
all_names(def) # (:max_iter, :max, :maxiter)

Throws

• CTModels.Exceptions.IncorrectArgument: If the default value does not match the declared type
• Exception: If the validator function fails when applied to the default value

See also: all_names, extract_option, extract_options, NotProvided

struct OptionValue{T}

Represents an option value with its source provenance.

Fields

• value::T: The actual option value.
• source::Symbol: Where the value came from (:default, :user, :computed).

Constructor Validation

The constructor validates the source symbol using Val dispatch for compile-time type safety and performance optimization. Invalid sources throw Exceptions.IncorrectArgument.

Notes

The source field tracks the provenance of the option value:

• :default: Value comes from the tool's default configuration
• :user: Value was explicitly provided by the user
• :computed: Value was computed/derived from other options

Example

julia> using CTSolvers.Options

julia> opt = OptionValue(100, :user)
OptionValue{Int64}(100, :user)

julia> opt.value
100

julia> opt.source
:user

Throws

• Exceptions.IncorrectArgument: If source is not one of :default, :user, or :computed

See also: value, source, is_user

aliases(
    def::CTSolvers.Options.OptionDefinition
) -> Tuple{Vararg{Symbol}}

Get the aliases for this option definition.

Returns

• Tuple{Vararg{Symbol}}: Tuple of alias names

Example

julia> using CTSolvers.Options

julia> def = OptionDefinition(name=:max_iter, type=Int, default=100,
                          description="Maximum iterations",
                          aliases=(:max, :maxiter))
OptionDefinition{Int}(...)

julia> aliases(def)
(:max, :maxiter)

See also: all_names, name

all_names(
    def::CTSolvers.Options.OptionDefinition
) -> Tuple{Symbol, Vararg{Symbol}}

Return all valid names for an option definition (primary name plus aliases).

This function is used by the extraction system to search for an option in kwargs using all possible names (primary name and all aliases).

Arguments

• def::OptionDefinition: The option definition

Returns

• Tuple{Vararg{Symbol}}: Tuple containing the primary name followed by all aliases

Example

julia> using CTSolvers.Options

julia> def = OptionDefinition(
           name = :grid_size,
           type = Int,
           default = 100,
           description = "Grid size",
           aliases = (:n, :size)
       )
OptionDefinition{Int}(...)

julia> all_names(def)
(:grid_size, :n, :size)

See also: OptionDefinition, extract_option

default(def::CTSolvers.Options.OptionDefinition) -> Any

Get the default value for this option definition.

Returns

• The default value

Example

julia> using CTSolvers.Options

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

julia> default(def)
100

See also: name, type, is_required

description(
    def::CTSolvers.Options.OptionDefinition
) -> String

Get the description for this option definition.

Returns

• String: The option description

Example

julia> using CTSolvers.Options

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

julia> description(def)
"Maximum iterations"

See also: name, type

extract_option(
    kwargs::NamedTuple,
    def::CTSolvers.Options.OptionDefinition
) -> Tuple{Any, NamedTuple}

Extract a single option from a NamedTuple using its definition, with support for aliases.

This function searches through all valid names (primary name + aliases) in the definition to find the option value in the provided kwargs. If found, it validates the value, checks the type, and returns an OptionValue with :user source. If not found, returns the default value with :default source.

Arguments

• kwargs::NamedTuple: NamedTuple containing potential option values.
• def::OptionDefinition: Definition defining the option to extract.

Returns

• (OptionValue, NamedTuple): Tuple containing the extracted option value and the remaining kwargs.

Notes

• If a validator is provided in the definition, it will be called on the extracted value.
• Validators should follow the pattern x -> condition || throw(ArgumentError("message")).
• If validation fails, the original exception is rethrown after logging context with @error.
• Type mismatches throw Exceptions.IncorrectArgument exceptions.
• The function removes the found option from the returned kwargs.

Throws

• CTBase.Exceptions.IncorrectArgument: If type mismatch between value and definition
• Exception: If validator function fails

Example

def = OptionDefinition(
    name = :grid_size,
    type = Int,
    default = 100,
    description = "Grid size",
    aliases = (:n, :size)
)

kwargs = (n=200, tol=1e-6, max_iter=1000)
opt, remaining = extract_option(kwargs, def)
opt.value      # 200
opt.source     # :user
remaining.tol  # 1e-6

extract_options(
    kwargs::NamedTuple,
    defs::Vector{<:CTSolvers.Options.OptionDefinition}
) -> Tuple{Dict{Symbol, CTSolvers.Options.OptionValue}, NamedTuple}

Extract multiple options from a NamedTuple using a vector of definitions.

This function iteratively applies extract_option for each definition in the vector, building a dictionary of extracted options while progressively removing processed options from the kwargs.

Arguments

• kwargs::NamedTuple: NamedTuple containing potential option values.
• defs::Vector{OptionDefinition}: Vector of definitions defining options to extract.

Returns

• (Dict{Symbol, OptionValue}, NamedTuple): Dictionary mapping option names to their values, and remaining kwargs.

Notes

• The extraction order follows the order of definitions in the vector.
• Each definition's primary name is used as the dictionary key.
• Options not found in kwargs use their definition default values.
• Validation is performed for each option using extract_option.

Throws

• Any exception raised by validators in the definitions

See also: extract_option, OptionDefinition, OptionValue

Example

defs = [
    OptionDefinition(name = :grid_size, type = Int, default = 100, description = "Grid size"),
    OptionDefinition(name = :tol, type = Float64, default = 1e-6, description = "Tolerance")
]

kwargs = (grid_size=200, max_iter=1000)
options, remaining = extract_options(kwargs, defs)
options[:grid_size].value  # 200
options[:tol].value        # 1e-6
remaining.max_iter         # 1000

extract_options(
    kwargs::NamedTuple,
    defs::NamedTuple
) -> Tuple{NamedTuple, NamedTuple}

Extract multiple options from a NamedTuple using a NamedTuple of definitions.

This function is similar to the Vector version but returns a NamedTuple instead of a Dict for convenience when the definition structure is known at compile time.

Arguments

• kwargs::NamedTuple: NamedTuple containing potential option values.
• defs::NamedTuple: NamedTuple of definitions defining options to extract.

Returns

• (NamedTuple, NamedTuple): NamedTuple of extracted options and remaining kwargs.

Notes

• The extraction order follows the order of definitions in the NamedTuple.
• Each definition's primary name is used as the key in the returned NamedTuple.
• Options not found in kwargs use their definition default values.
• Validation is performed for each option using extract_option.

Throws

• Any exception raised by validators in the definitions

See also: extract_option, OptionDefinition, OptionValue

Example

defs = (
    grid_size = OptionDefinition(name = :grid_size, type = Int, default = 100, description = "Grid size"),
    tol = OptionDefinition(name = :tol, type = Float64, default = 1e-6, description = "Tolerance")
)

kwargs = (grid_size=200, max_iter=1000)
options, remaining = extract_options(kwargs, defs)
options.grid_size.value  # 200
options.tol.value        # 1e-6
remaining.max_iter       # 1000

extract_raw_options(options::NamedTuple) -> NamedTuple

Extract raw option values from a NamedTuple of options, unwrapping OptionValue wrappers and filtering out NotProvided values.

This utility function is useful when passing options to external builders or functions that expect plain keyword arguments without OptionValue wrappers or undefined options.

Options with NotProvided values are excluded from the result, allowing external builders to use their own defaults. Options with explicit nothing values are included.

Arguments

• options::NamedTuple: NamedTuple containing option values (may be wrapped in OptionValue)

Returns

• NamedTuple: NamedTuple with unwrapped values, excluding any NotProvided values

Example

opts = (backend = OptionValue(:optimized, :user), 
        show_time = OptionValue(false, :default),
        minimize = OptionValue(nothing, :default),
        optional = OptionValue(NotProvided, :default))

extract_raw_options(opts)
# (backend = :optimized, show_time = false, minimize = nothing)

See also: OptionValue, extract_options, NotProvided

has_default(def::CTSolvers.Options.OptionDefinition) -> Bool

Check if this option definition has a default value.

Returns false when the default value is NotProvided.

Returns

• Bool: true if a default value is defined

Example

julia> using CTSolvers.Options

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

julia> has_default(def)
true

See also: is_required, default

has_validator(
    def::CTSolvers.Options.OptionDefinition
) -> Bool

Check if this option definition has a validator function.

Returns

• Bool: true if a validator is defined

Example

julia> using CTSolvers.Options

julia> def = OptionDefinition(name=:max_iter, type=Int, default=100,
                          description="Maximum iterations",
                          validator=x -> x > 0)
OptionDefinition{Int}(...)

julia> has_validator(def)
true

See also: validator, name

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

Check if this option value was computed from other options.

Returns

• Bool: true if the source is :computed

Example

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

See also: is_user, is_default, source

is_computed(def::CTSolvers.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> using CTSolvers.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

See also: has_default, is_required, OptionDefinition

is_computed(
    opts::CTSolvers.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> Options.is_computed(opts, :step)
true

See also: Options.source, Options.is_user, Options.is_default

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

Check if this option value is using its default.

Returns

• Bool: true if the source is :default

Example

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

See also: is_user, is_computed, source

is_default(
    opts::CTSolvers.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> Options.is_default(opts, :tol)
true

See also: Options.source, Options.is_user, Options.is_computed

is_required(def::CTSolvers.Options.OptionDefinition) -> Bool

Check if this option is required (has no default value).

Returns true when the default value is NotProvided.

Returns

• Bool: true if the option is required

Example

julia> using CTSolvers.Options

julia> def = OptionDefinition(name=:input, type=String, default=NotProvided,
                          description="Input file")
OptionDefinition{NotProvidedType}(...)

julia> is_required(def)
true

See also: has_default, default

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

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

Returns

• Bool: true if the source is :user

Example

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

See also: is_default, is_computed, source

is_user(
    opts::CTSolvers.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> Options.is_user(opts, :max_iter)
true

See also: Options.source, Options.is_default, Options.is_computed

name(def::CTSolvers.Options.OptionDefinition) -> Symbol

Get the primary name of this option definition.

Returns

• Symbol: The option name

Example

julia> using CTSolvers.Options

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

julia> name(def)
:max_iter

See also: type, default, aliases

source(opt::CTSolvers.Options.OptionValue) -> Symbol

Get the source provenance of this option value.

Returns

• Symbol: :default, :user, or :computed

Example

opt = OptionValue(100, :user)
source(opt)  # :user

See also: value, is_user

source(
    opts::CTSolvers.Strategies.StrategyOptions,
    key::Symbol
) -> Symbol

Get the source of an option.

Arguments

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

Returns

• Symbol: Source of the option (:user, :default, or :computed)

Example

julia> Options.source(opts, :max_iter)
:user

See also: Options.is_user, Options.is_default, Options.is_computed

type(def::CTSolvers.Options.OptionDefinition) -> Type

Get the expected type for this option definition.

Returns

• Type: The expected type

Example

julia> using CTSolvers.Options

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

julia> type(def)
Int

See also: name, default

validator(
    def::CTSolvers.Options.OptionDefinition
) -> Union{Nothing, Function}

Get the validator function for this option definition.

Returns

• Union{Function, Nothing}: The validator function or nothing

Example

julia> using CTSolvers.Options

julia> validator_fn = x -> x > 0

julia> def = OptionDefinition(name=:max_iter, type=Int, default=100,
                          description="Maximum iterations",
                          validator=validator_fn)
OptionDefinition{Int}(...)

julia> validator(def) === validator_fn
true

See also: has_validator, name

value(opt::CTSolvers.Options.OptionValue) -> Any

Get the value from this option value wrapper.

Returns

• The stored option value

Example

opt = OptionValue(100, :user)
value(opt)  # 100

See also: source, is_user

value(
    opts::CTSolvers.Strategies.StrategyOptions,
    key::Symbol
) -> Any

Get the value of an option.

Arguments

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

Returns

• Any: Value of the option

Example

julia> Options.value(opts, :max_iter)
200

See also: Options.is_user, Options.is_default, Options.is_computed