Descriptions: encoding algorithms

A description is a CTBase.Descriptions.Description — a Tuple of Symbols that declaratively encodes an algorithm or configuration.

julia> using CTBase

julia> d = (:descent, :bfgs, :bisection)
(:descent, :bfgs, :bisection)

julia> typeof(d) <: CTBase.Descriptions.Description
true

Higher-level packages use descriptions to catalogue algorithms in a uniform, string-free, and composable way.

Building a catalogue

CTBase.Descriptions.add adds a description to a catalogue (a Tuple{Vararg{Description}}). Start with an empty tuple ():

julia> algorithms = ()

julia> algorithms = CTBase.Descriptions.add(algorithms, (:descent, :bfgs, :bisection))
(:descent, :bfgs, :bisection)

julia> algorithms = CTBase.Descriptions.add(algorithms, (:descent, :gradient, :fixedstep))
(:descent, :bfgs, :bisection)
(:descent, :gradient, :fixedstep)

Attempting to add a duplicate raises CTBase.Exceptions.IncorrectArgument:

julia> CTBase.Descriptions.add(algorithms, (:descent, :bfgs, :bisection))
IncorrectArgument → top-level scope, REPL[1]:2
│
│  the description (:descent, :bfgs, :bisection) is already in ((:descent, :bfgs, :bisection), (:descent, :gradient, :fixedstep))
│
│  Got       (:descent, :bfgs, :bisection)
│  Expected  a unique description not in the catalog
│
│  Context   description catalog management
│  Hint      Check existing descriptions before adding, or use a different description
└─

Completing a partial description

CTBase.Descriptions.complete picks the unique catalogue entry that contains all provided symbols:

julia> CTBase.Descriptions.complete(:bisection; descriptions=algorithms)
(:descent, :bfgs, :bisection)

julia> CTBase.Descriptions.complete(:gradient, :fixedstep; descriptions=algorithms)
(:descent, :gradient, :fixedstep)

Among all entries that are a superset of the requested symbols, the one with the largest overlap is returned (first wins on tie). If no entry matches, CTBase.Exceptions.AmbiguousDescription is raised:

julia> CTBase.Descriptions.complete(:euler; descriptions=algorithms)
AmbiguousDescription → top-level scope, REPL[1]:2
│
│  cannot find matching description
│
│  Diagnostic  Unknown symbols — none of the requested symbols appear in any available description
│  Requested   (:euler,)
│  Available   (:descent, :bfgs, :bisection)
│              (:descent, :gradient, :fixedstep)
│
│  Context     description completion
│  Hint        Choose from the available descriptions listed above
└─

Removing symbols from a description

CTBase.Descriptions.remove returns a new description with specified symbols removed — useful for extracting the remainder after stripping a known prefix:

julia> full = CTBase.Descriptions.complete(:bisection; descriptions=algorithms)
(:descent, :bfgs, :bisection)

julia> CTBase.Descriptions.remove(full, (:descent, :bfgs))
(:bisection,)

Function Reference

Function	Purpose	Throws
CTBase.Descriptions.add	Add a description to a catalogue	CTBase.Exceptions.IncorrectArgument on duplicate
CTBase.Descriptions.complete	Complete a partial description	CTBase.Exceptions.AmbiguousDescription on no/ambiguous match
CTBase.Descriptions.remove	Remove symbols from a description	—

See Also

• Exceptions guide — understanding IncorrectArgument and AmbiguousDescription.