Public API

This page lists exported symbols of CTBase.Core.

---

From CTBase.Core

CTBase.Core [Module]

CTBase.Core Module

Core

Fundamental types, constants, and utilities for CTBase.

This module contains the core building blocks used throughout the CTBase ecosystem, including type aliases and internal utilities.

@ensure [Macro]

CTBase.Core.@ensure Macro

@ensure condition exception

Throws the provided exception if condition is false.

Usage

julia> @ensure true Exceptions.IncorrectArgument("This won't throw")
julia> @ensure false Exceptions.IncorrectArgument("This will throw")
ERROR: IncorrectArgument("This will throw")

Arguments

• condition: A Boolean expression to test.

• exception: An instance of an exception to throw if condition is false.

Throws

• The provided exception if the condition is not satisfied.

AbstractCache [Abstract Type]

CTBase.Core.AbstractCache Type

abstract type AbstractCache

Abstract base type for computation caches.

Caches store pre-allocated buffers and prepared plans (for example automatic differentiation plans) so that repeated computations avoid reallocating on every call. Concrete cache types are defined by the packages or extensions that provide a specific backend.

Interface Requirements

Concrete cache subtypes typically:

• Hold pre-allocated buffers and/or a prepared plan

• Are constructed once and reused across many calls

• Are backend- or extension-specific

Example

struct MyCache <: AbstractCache
    buffer::Vector{Float64}
end

See also: CTBase.Core.AbstractTag.

AbstractTag [Abstract Type]

CTBase.Core.AbstractTag Type

AbstractTag

Abstract type for tag dispatch pattern used to handle extension-dependent implementations.

This type is used for multiple dispatch in validation functions and other contexts where behavior depends on loaded extensions (e.g., Enzyme, Zygote, CUDA).

Example

struct MyTag <: AbstractTag end

function validate_backend(tag::MyTag, backend::Symbol)
    # Tag-specific validation logic
end

See also: Extension-based validation patterns in extension modules

DEFAULT_PALETTE [Constant]

CTBase.Core.DEFAULT_PALETTE Constant

The standard colour palette used out of the box.

Maps each semantic role to a colour that mirrors Julia's REPL conventions (green for values, cyan for types, etc.).

See also: CTBase.Core.Palette, CTBase.Core.MONOCHROME_PALETTE, CTBase.Core.HIGH_CONTRAST_PALETTE, CTBase.Core.set_palette!

HIGH_CONTRAST_PALETTE [Constant]

CTBase.Core.HIGH_CONTRAST_PALETTE Constant

A palette using bright, bold variants for improved readability.

Useful on terminals with poor contrast or for users who prefer stronger colour cues.

Example

julia> using CTBase

julia> CTBase.Core.set_palette!(CTBase.Core.HIGH_CONTRAST_PALETTE)

See also: CTBase.Core.DEFAULT_PALETTE, CTBase.Core.MONOCHROME_PALETTE, CTBase.Core.reset_palette!

MONOCHROME_PALETTE [Constant]

CTBase.Core.MONOCHROME_PALETTE Constant

A palette with every style set to the empty code.

No colour or formatting is ever emitted, regardless of terminal capability. Useful for CI logs, plain-text output, or accessibility contexts where styled text is unwanted.

Example

julia> using CTBase

julia> CTBase.Core.set_palette!(CTBase.Core.MONOCHROME_PALETTE)

See also: CTBase.Core.DEFAULT_PALETTE, CTBase.Core.HIGH_CONTRAST_PALETTE, CTBase.Core.reset_palette!

NotProvided [Constant]

CTBase.Core.NotProvided Constant

NotProvided

Singleton instance of CTBase.Core.NotProvidedType.

The canonical "not provided" sentinel used across the control-toolbox ecosystem (option defaults, optional variable parameters, optional AD backends, …).

Example

julia> using CTBase.Core

julia> x = NotProvided
NotProvided

julia> x isa NotProvidedType
true

julia> x === NotProvided
true

See also: CTBase.Core.NotProvidedType.

NotProvidedType [Struct]

CTBase.Core.NotProvidedType Type

struct NotProvidedType

Singleton type marking the absence of a provided value.

Ecosystem-wide sentinel for "no default / argument not given". The canonical value is CTBase.Core.NotProvided.

See also: CTBase.Core.NotProvided.

Palette [Struct]

CTBase.Core.Palette Type

struct Palette

A complete set of display styles, one per semantic role.

Each field is a CTBase.Core.Style that governs how a particular category of information is rendered. The active palette is read at every call to CTBase.Core.get_format_codes, so swapping it with CTBase.Core.set_palette! takes effect immediately for subsequent show calls.

Fields

• name: identifiers, type names, option keys (default: bold blue)

• type: type annotations, hierarchy entries (default: cyan)

• value: data values, option values (default: green)

• keyword: Julia symbols (:euler), aliases, IDs (default: yellow)

• count: numeric counts (default: magenta)

• label: secondary labels, metadata tags (default: gray)

• emphasis: message text, function names (default: bold)

• muted: structural chars (│, └─, →), time suffix (default: dim)

• error: failures, missing extensions (default: red)

• warning: notable values (Got, Retcode, skipped test) (default: yellow)

• success: positive hints, Expected, passing test (default: green)

See also: CTBase.Core.DEFAULT_PALETTE, CTBase.Core.MONOCHROME_PALETTE, CTBase.Core.HIGH_CONTRAST_PALETTE, CTBase.Core.set_palette!

Style [Struct]

CTBase.Core.Style Type

struct Style

An ANSI display style described by a numeric escape code.

The code field holds the numeric part of the escape sequence (e.g. "32" for green, "1;34" for bold blue). An empty string means no styling — used by monochrome palettes and when colour is disabled.

Example

julia> using CTBase

julia> CTBase.Core.Style("32")   # green
Style("32")

julia> CTBase.Core.Style("")     # no styling
Style("")

See also: CTBase.Core.Palette, CTBase.Core.set_color!

ctNumber [Abstract Type]

CTBase.Core.ctNumber Type

Type alias for a real number.

This constant is primarily meant as a short, semantic alias when writing APIs that accept real-valued quantities.

Example

julia> using CTBase

julia> CTBase.ctNumber === Real
true

current_palette [Function]

CTBase.Core.current_palette Function

current_palette() -> CTBase.Core.Palette

Return the currently active CTBase.Core.Palette.

The active palette is used by every show and describe call in CTBase to derive ANSI codes. Change it with CTBase.Core.set_palette!.

Example

julia> using CTBase

julia> CTBase.Core.current_palette() === CTBase.Core.DEFAULT_PALETTE
true

See also: CTBase.Core.set_palette!, CTBase.Core.reset_palette!

get_format_codes [Function]

CTBase.Core.get_format_codes Function

get_format_codes(
    io::IO
) -> @NamedTuple{name::String, type::String, value::String, keyword::String, count::String, label::String, emphasis::String, muted::String, error::String, warning::String, success::String, reset::String, bold::String, dim::String}

Return ANSI opening codes for every semantic role in the active CTBase.Core.Palette, respecting the colour capability of io.

Each field is an opening escape sequence; callers must close styling with the reset field. Returns empty strings for all codes when get(io, :color, false) is false, or when the active palette has an empty code for that role (e.g. CTBase.Core.MONOCHROME_PALETTE).

Returns

A NamedTuple with the following fields:

Field	Default colour	Semantic role
name	bold blue	identifiers, type names, option keys
type	cyan	type annotations, hierarchy entries
value	green	data values
keyword	yellow	Julia symbols, aliases
count	magenta	numeric counts
label	gray	secondary labels, metadata tags
emphasis / bold	bold	message text, function names
muted / dim	dim	structural chars, time suffix
error	red	failures, missing extensions
warning	yellow	notable attention values
success	green	positive hints, expected values
reset	—	resets all styling

bold and dim are legacy aliases for emphasis and muted; prefer the semantic names in new code.

Example

julia> using CTBase

julia> io = IOContext(stdout, :color => true);

julia> fmt = CTBase.Core.get_format_codes(io);

julia> print(io, fmt.name, "option_name", fmt.reset, "::", fmt.type, "Int", fmt.reset)
option_name::Int

See also: CTBase.Core.set_palette!, CTBase.Core.Palette

make_coerce [Function]

CTBase.Core.make_coerce Function

make_coerce(x) -> coerce_fn

Return a coercion function matching the shape of x.

For scalars (Number), returns only, which extracts the single element from a 1-element vector. For arrays (AbstractVector, AbstractMatrix), returns identity (a no-op). This is used to map a uniform vector-valued result back to the natural shape of the original input.

Arguments

• x: A value whose type determines the coercion strategy.

Returns

• A coercion function with signature (y) -> coerced_y.

Example

julia> coerce_scalar = make_coerce(1.0);

julia> coerce_scalar([5.0])
5.0

julia> coerce_vector = make_coerce([1.0, 2.0]);

julia> coerce_vector([3.0, 4.0])
2-element Vector{Float64}:
 3.0
 4.0

matrix2vec [Function]

CTBase.Core.matrix2vec Function

matrix2vec(A::Matrix{<:Real}) -> Vector{<:Vector{<:Real}}
matrix2vec(
    A::Matrix{<:Real},
    dim::Int64
) -> Vector{<:Vector{<:Real}}

Transform a matrix into a vector of vectors along the specified dimension.

Each row or column of the matrix A is extracted and stored as an individual vector, depending on dim.

Arguments

• A: A matrix of elements of type <:ctNumber.

• dim: The dimension along which to split the matrix (1 for rows, 2 for columns). Defaults to 1.

Returns

A Vector of Vectors extracted from the rows or columns of A.

Note

This is useful when data needs to be represented as a sequence of state or control vectors in optimal control problems.

Example

julia> A = [1 2 3; 4 5 6]
julia> matrix2vec(A, 1)  # splits into rows: [[1, 2, 3], [4, 5, 6]]
julia> matrix2vec(A, 2)  # splits into columns: [[1, 4], [2, 5], [3, 6]]

reset_palette! [Function]

CTBase.Core.reset_palette! Function

reset_palette!() -> CTBase.Core.Palette

Restore the active palette to CTBase.Core.DEFAULT_PALETTE and return it.

Example

julia> using CTBase

julia> CTBase.Core.set_palette!(CTBase.Core.MONOCHROME_PALETTE)

julia> CTBase.Core.reset_palette!()

julia> CTBase.Core.current_palette() === CTBase.Core.DEFAULT_PALETTE
true

See also: CTBase.Core.set_palette!, CTBase.Core.current_palette

set_color! [Function]

CTBase.Core.set_color! Function

set_color!(
    role::Symbol,
    code::AbstractString
) -> CTBase.Core.Palette

Override a single semantic role in the active palette and return the updated CTBase.Core.Palette.

role must be one of :name, :type, :value, :keyword, :count, :label, :emphasis, :muted, :error, :warning, :success. code is the ANSI numeric code string (e.g. "32" for green, "1;34" for bold blue, "" to suppress styling for that role).

Example

julia> using CTBase

julia> CTBase.Core.set_color!(:error, "35")   # make errors magenta

julia> CTBase.Core.reset_palette!()

See also: CTBase.Core.set_palette!, CTBase.Core.reset_palette!

set_palette! [Function]

CTBase.Core.set_palette! Function

set_palette!(p::CTBase.Core.Palette) -> CTBase.Core.Palette

Replace the active CTBase.Core.Palette with p and return p.

The change is global and immediate: the next show or describe call uses the new palette. Use CTBase.Core.reset_palette! to restore the default.

Example

julia> using CTBase

julia> CTBase.Core.set_palette!(CTBase.Core.HIGH_CONTRAST_PALETTE)

julia> CTBase.Core.current_palette() === CTBase.Core.HIGH_CONTRAST_PALETTE
true

julia> CTBase.Core.reset_palette!()

See also: CTBase.Core.current_palette, CTBase.Core.reset_palette!

show_palette [Function]

CTBase.Core.show_palette Function

show_palette()
show_palette(io::IO)

Print a visual preview of the active CTBase.Core.Palette to io.

The preview has three sections:

• Role swatches: every semantic role with a colored swatch block (████), a representative sample string, and a description of when the role is used.

• Mock describe: a simulated describe/show block exercising name, type, value, keyword, count, label, and muted.

• Mock error: a simulated exception block exercising error, emphasis, muted, warning, and success.

By default io wraps stdout with :color => true so the preview is always colored in an interactive session. Pass a custom IOContext to override.

Example

julia> using CTBase

julia> CTBase.Core.show_palette()

julia> CTBase.Core.set_palette!(CTBase.Core.HIGH_CONTRAST_PALETTE)
julia> CTBase.Core.show_palette()
julia> CTBase.Core.reset_palette!()

See also: CTBase.Core.set_palette!, CTBase.Core.current_palette, CTBase.Core.DEFAULT_PALETTE

to_out_of_place [Function]

CTBase.Core.to_out_of_place Function

to_out_of_place(
    f!,
    n;
    T
) -> Union{Nothing, CTBase.Core.var"#f#3"{CTBase.Core.var"#f#2#4"{Type{Float64}, _A, _B}} where {_A, _B}}

Convert an in-place function f! to an out-of-place function f.

The resulting function f returns a vector of type T and length n by first allocating memory and then calling f! to fill it.

The buffer element type is widened from the call arguments (via _promote_arg_eltype) so that ForwardDiff.Dual values are accommodated during automatic differentiation. The T keyword acts as a floor, so plain Float64/Int calls keep their previous behaviour.

Arguments

• f!: An in-place function of the form f!(result, args...).

• n: The length of the output vector.

• T: The element type of the output vector (default is Float64).

Returns

An out-of-place function f(args...; kwargs...) that returns the result as a vector or scalar, depending on n.

Example

julia> f!(r, x) = (r[1] = sin(x); r[2] = cos(x))
julia> f = to_out_of_place(f!, 2)
julia> f(π/4)  # returns approximately [0.707, 0.707]