The @SciMLMessage Macro

`@SciMLMessage(message, verbosity, option)`

A macro that emits a log message based on the log level specified in the option of the AbstractVerbositySpecifier supplied.

f_or_message may be a message String, or a 0-argument function that returns a String.

Usage

To emit a simple string, @SciMLMessage("message", verbosity, :option) will emit a log message with the LogLevel specified in verbosity for the given option.

@SciMLMessage can also be used to emit a log message coming from the evaluation of a 0-argument function. This function is resolved in the environment of the macro call. Therefore it can use variables from the surrounding environment. This may be useful if the log message writer wishes to carry out some calculations using existing variables and use them in the log message. The function is only called if the message category is not Silent(), avoiding unnecessary computation.

The macro works with any AbstractVerbositySpecifier implementation:

# Package defines verbosity specifier
@concrete struct SolverVerbosity <: AbstractVerbositySpecifier
    initialization
    progress
    convergence
    diagnostics
    performance
end

# Usage in package code
function solve_problem(problem; verbose = SolverVerbosity(Standard()))
    @SciMLMessage("Initializing solver", verbose, :initialization)

    # ... solver setup ...

    for iteration in 1:max_iterations
        @SciMLMessage("Iteration $iteration", verbose, :progress)

        # ... iteration work ...

        if converged
            @SciMLMessage("Converged after $iteration iterations", verbose, :convergence)
            break
        end
    end

    return result
end