various improvements and rework interface.md

Author: lkdvos

docs/src/interface.md

@@ -1,28 +1,139 @@
-# The algorithm interface
+# [The algorithm interface](@id sec_interface)
 
-## General design ideas
+This section starts a single, cohesive story that will weave through all documentation pages.
+We will incrementally build an iterative algorithm, enrich it with stopping criteria, and
+finally refine how it records (logs) its progress. Instead of presenting the API in the
+abstract, we anchor every concept in one concrete, tiny example you can copy & adapt.
 
-The interface this package provides is based on three ingredients of running an algorithm
-consists of:
+Why an “interface” for algorithms? Iterative numerical methods nearly always share the
+same moving pieces:
 
-* a [`Problem`](@ref) that is to be solved and contains all information that is algorithm independent.
-  This is _static information_ in the sense that it does not change during the runtime of the algorithm.
-* an [`Algorithm`](@ref) that includes all of the _settings_ and _parameters_ that an algorithm.
-  this is also information that is _static_.
-* a [`State`](@ref) that contains all remaining data, especially data that might vary during the iteration,
-  temporary caches, for example the current iteration the algorithm run is in and the current iterate, respectively.
+* immutable input (the mathematical problem you are solving),
+* immutable configuration (parameters and knobs of the chosen algorithm), and
+* mutable working data (current iterate, caches, diagnostics) that evolves as you step.
 
-The combination of the static information should be enough to initialize the varying data.
+Bundling these together loosely—without forcing one giant monolithic type—makes it easier to:
 
-This general scheme is a guiding principle of the package, splitting information into _static_
-or _configuration_ types or data that allows to [`initialize_state`](@ref) a corresponding _variable_ data type.
+* reason about what is allowed to change and what must remain fixed,
+* write generic tooling (e.g. stopping logic, logging, benchmarking) that applies across many algorithms,
+* test algorithms in isolation by constructing minimal `Problem`/`Algorithm` pairs, and
+* extend behavior (add new stopping criteria, new logging events) without rewriting core loops.
 
-The order of arguments is given by two ideas
+The interface in this package formalizes those roles with three abstract types:
+* [`Problem`](@ref): immutable, algorithm‑agnostic input data.
+* [`Algorithm`](@ref): immutable configuration and parameters deciding how to iterate.
+* [`State`](@ref): mutable data that evolves (current iterate, caches, counters, diagnostics).
+It provides a framework for decomposing iterative methods into small, composable parts:
+concrete `Problem`/`Algorithm`/`State` types have to implement a minimal set of core functionality,
+and this package helps to stitch everything together and provide additional helper functionality such as stopping criteria and logging functionality.
 
-1. for non-mutating functions the order should be from the most fixed data to the most variable one.
-  For example the three types just mentioned would be ordered like `f(problem, algorithm, state)`
-2. For mutating functions the variable that is mutated comes first, for the remainder the guiding principle from 1 continues.
-  The main case here is `f!(state, problem, algorithm)`.
+## [Concrete example: Heron's method](@id sec_heron)
+
+To make everything tangible, we will work through a concrete example to illustrate the library's goals and concepts.
+Our running example is Heron's / Babylonian method for estimating $\sqrt{S}$.
+(see also the concise background on Wikipedia: [Babylonian method (Heron's method)](https://en.wikipedia.org/wiki/Methods_of_computing_square_roots#Babylonian_method)):
+Starting from an initial guess $x_0$, we may converge to the solution by iterating:
+
+$$x_{k+1} = \frac{1}{2}\left(x_k + \frac{S}{x_k}\right)$$
+
+We therefore suggest the following concrete implementations of the abstract types provided by this package:
+They are illustrative; various performance and generality questions will be left unaddressed to keep this example simple.
+
+### Algorithm types
+
+```@example Heron
+using AlgorithmsInterface
+
+struct SqrtProblem <: Problem
+    S::Float64                # number whose square root we seek
+end
+
+struct HeronAlgorithm <: Algorithm
+    stopping_criterion        # will be plugged in later (any StoppingCriterion)
+end
+
+mutable struct HeronState <: State
+    iterate::Float64          # current iterate
+    iteration::Int            # current iteration count
+    stopping_criterion_state  # will be plugged in later (any StoppingCriterionState)
+end
+```
+
+### Initialization
+
+In order to start implementing the core parts of our algorithm, we start at the very beginning.
+There are two main entry points provided by the interface:
+
+- [`initialize_state`](@ref) constructs an entirely new state for the algorithm
+- [`initialize_state!`](@ref) (in-place) reset of an existing state.
+
+An example implementation might look like:
+
+```@example Heron
+function AlgorithmsInterface.initialize_state(problem::SqrtProblem, algorithm::HeronAlgorithm; kwargs...)
+    x0 = rand() # random initial guess
+    stopping_criterion_state = initialize_state(problem, algorithm, algorithm.stopping_criterion)
+    return HeronState(x0, 0, stopping_criterion_state)
+end
+
+function AlgorithmsInterface.initialize_state!(problem::SqrtProblem, algorithm::HeronAlgorithm, state::HeronState; kwargs...)
+    # reset the state for the algorithm
+    state.iterate = rand()
+    state.iteration = 0
+    
+    # reset the state for the stopping criterion
+    state = AlgorithmsInterface.initialize_state!(
+        problem, algorithm, algorithm.stopping_criterion, state.stopping_criterion_state
+    )
+    return state
+end
+```
+
+### Iteration steps
+
+Algorithms define a mutable step via [`step!`](@ref). For Heron's method:
+
+```@example Heron
+function AlgorithmsInterface.step!(problem::SqrtProblem, algorithm::HeronAlgorithm, state::HeronState)
+    S = problem.S
+    x = state.iterate
+    state.iterate = 0.5 * (x + S / x)
+    return state
+end
+```
+
+Note that we are only focussing on the actual algorithm, and *not* incrementing the iteration counter.
+These kinds of bookkeeping should be handled by the [`increment!(state)`](@ref) function, which will by default already increment the iteration counter.
+The following generic functionality is therefore enough for our purposes, and does *not* need to be defined.
+Nevertheless, if additional bookkeeping would be desired, this can be achieved by overloading that function:
+
+```julia
+function AlgorithmsInterface.increment!(state::State)
+    state.iteration += 1
+    return state
+end
+```
+
+### Running the algorithm
+
+With these definitions in place you can already run (assuming you also choose a stopping criterion – added in the next section):
+
+```@example Heron
+function heron_sqrt(x; maxiter = 10)
+    prob = SqrtProblem(x)
+    alg  = HeronAlgorithm(StopAfterIteration(maxiter))
+    state = solve(prob, alg)  # allocates & runs
+    return state.iterate
+end
+
+println("Approximate sqrt: ", heron_sqrt(16.0))
+```
+
+We will refine this example with better halting logic and logging shortly.
+
+## Reference: Core interface types & functions
+
+Below are the automatic API docs for the core interface pieces. Read them after grasping the example above – the intent should now be clearer.
 
 ```@autodocs
 Modules = [AlgorithmsInterface]
@@ -31,7 +142,7 @@ Order = [:type, :function]
 Private = true
 ```
 
-## Algorithm
+### Algorithm
 
 ```@autodocs
 Modules = [AlgorithmsInterface]
@@ -40,7 +151,7 @@ Order = [:type, :function]
 Private = true
 ```
 
-## Problem
+### Problem
 
 ```@autodocs
 Modules = [AlgorithmsInterface]
@@ -49,11 +160,15 @@ Order = [:type, :function]
 Private = true
 ```
 
-## State
+### State
 
 ```@autodocs
 Modules = [AlgorithmsInterface]
 Pages = ["interface/state.jl"]
 Order = [:type, :function]
 Private = true
-```
+```
+
+### Next: Stopping criteria
+
+Proceed to the stopping criteria section to add robust halting logic (iteration caps, time limits, tolerance on successive iterates, and combinations) to this square‑root example.

src/interface/interface.jl

@@ -43,16 +43,31 @@ The state is modified in-place.
 All keyword arguments are passed to the [`initialize_state!`](@ref)`(problem, algorithm, state)` function.
 """
 function solve!(problem::Problem, algorithm::Algorithm, state::State; kwargs...)
+    # obtain logger once to minimize overhead from accessing ScopedValue
+    # additionally handle logging initialization to enable stateful LoggingAction
     logger = algorithm_logger()
+    # initialize_logger(logger, problem, algorithm, state)
+
+    # initialize the state and emit message
     initialize_state!(problem, algorithm, state; kwargs...)
-    isnothing(logger) || handle_message(logger, problem, algorithm, state, :Start)
+    emit_message(logger, problem, algorithm, state, :Start)
+
+    # main body of the algorithm
     while !is_finished!(problem, algorithm, state)
-        isnothing(logger) || handle_message(logger, problem, algorithm, state, :PreStep)
+        # logging event between convergence check and algorithm step
+        emit_message(logger, problem, algorithm, state, :PreStep)
+
+        # algorithm step
         increment!(state)
         step!(problem, algorithm, state)
-        isnothing(logger) || handle_message(logger, problem, algorithm, state, :PostStep)
+
+        # logging event between algorithm step and convergence check
+        emit_message(logger, problem, algorithm, state, :PostStep)
     end
-    isnothing(logger) || handle_message(logger, problem, algorithm, state, :Stop)
+
+    # emit message about finished state
+    emit_message(logger, problem, algorithm, state, :Stop)
+
     return state
 end
 

src/logging.jl

@@ -46,7 +46,7 @@ The callback function must have the following signature:
 ```julia
 callback(algorithm, problem, state; kwargs...) = ...
 ```
-Here `args...` and `kwargs...` are optional and can be filled out with context-specific information.
+Here `kwargs...` are optional and can be filled out with context-specific information.
 """
 struct CallbackAction{F} <: LoggingAction
     callback::F
@@ -59,6 +59,16 @@ function handle_message!(
     return nothing
 end
 
+"""
+    IfAction(predicate, action)
+
+Concrete [`LoggingAction`](@ref) that wraps another action and hides it behind a clause, only
+emitting logging events whenever the `predicate` evaluates to true. The `predicate` must have
+the signature:
+```julia
+predicate(algorithm, problem, state; kwargs...)::Bool
+```
+"""
 struct IfAction{F, A <: LoggingAction} <: LoggingAction
     predicate::F
     action::A
@@ -97,18 +107,34 @@ struct AlgorithmLogger
 end
 AlgorithmLogger(args...) = AlgorithmLogger(Dict{Symbol, LoggingAction}(args...))
 
-"""
-    const LOGGING_ENABLED = Ref(true)
 
-Global toggle for enabling and disabling all logging features.
-"""
+@doc """
+    get_global_logging_state()
+    set_global_logging_state!(state::Bool) -> previous_state
+
+Retrieve or set the value to globally enable or disable the handling of logging events.
+""" get_global_logging_state, set_global_logging_state!
+
 const LOGGING_ENABLED = Ref(true)
 
-"""
-    const algorithm_logger = ScopedValue(AlgorithmLogger())
+get_global_logging_state() = LOGGING_ENABLED[]
+function set_global_logging_state(state::Bool)
+    previous = LOGGING_ENABLED[]
+    LOGGING_ENABLED[] = state
+    return previous
+end
+
+
+@doc """
+    algorithm_logger()::Union{AlgorithmLogger, Nothing}
+
+Retrieve the current logger that is responsible for handling logging events.
+The current logger is determined by a `ScopedValue`.
+Whenever `nothing` is returned, no logging should happen.
+
+See also [`set_global_logging_state!`](@ref) for globally toggling whether logging should happen.
+""" algorithm_logger
 
-Scoped value for handling the logging events of arbitrary algorithms.
-"""
 const ALGORITHM_LOGGER = ScopedValue(AlgorithmLogger())
 
 function algorithm_logger()
@@ -118,21 +144,22 @@ function algorithm_logger()
     return logger
 end
 
-# @inline here to enable the cheap global check
-@inline function log!(problem::Problem, algorithm::Algorithm, state::State, context::Symbol; kwargs...)
-    if LOGGING_ENABLED[]
-        logger::AlgorithmLogger = ALGORITHM_LOGGER[]
-        handle_message(logger, problem, algorithm, state, context; kwargs...)
-    end
-    return nothing
-end
+"""
+    emit_message(problem::Problem, algorithm::Algorithm, state::State, context::Symbol; kwargs...) -> nothing
+    emit_message(algorithm_logger, problem::Problem, algorithm::Algorithm, state::State, context::Symbol; kwargs...) -> nothing
 
-# @noinline to keep the algorithm function bodies small
-@noinline function handle_message(
+Use the current or the provided algorithm logger to handle the logging event of the given `context`.
+The [`AlgorithmLogger`](@ref) is responsible for dispatching the correct events to the correct [`LoggingAction`](@ref)s.
+"""
+emit_message(problem::Problem, algorithm::Algorithm, state::State, context::Symbol; kwargs...) =
+    emit_message(algorithm_logger(), problem, algorithm, state, context; kwargs...)
+emit_message(::Nothing, problem::Problem, algorithm::Algorithm, state::State, context::Symbol; kwargs...) =
+    nothing
+function emit_message(
         alglogger::AlgorithmLogger, problem::Problem, algorithm::Algorithm, state::State, context::Symbol;
         kwargs...
     )
-    isempty(alglogger.actions) && return nothing
+    @noinline; @nospecialize
     action::LoggingAction = @something(get(alglogger.actions, context, nothing), return nothing)
     try
         handle_message!(action, problem, algorithm, state, args...; kwargs...)