The @SciMLMessage Macro

@SciMLMessage(message, verbosity::AbstractVerbositySpecifier, option::Symbol[, kwargs...])
@SciMLMessage(message, verbosity::Bool[, kwargs...])

Emit a log message controlled by a verbosity specifier or boolean flag.

message may be a string or a zero-argument function that returns a string.

Arguments

• message: Message string or zero-argument message-producing function.
• verbosity: AbstractVerbositySpecifier instance or Bool controlling emission.
• option: Field name in verbosity that selects the message category.
• kwargs...: Optional key-value metadata forwarded to Julia's logging system.

Examples

The macro works with any AbstractVerbositySpecifier implementation:

# Package defines verbosity specifier
struct SolverVerbosity{Enabled} <: AbstractVerbositySpecifier{Enabled}
    initialization::MessageLevel
    progress::MessageLevel
    convergence::MessageLevel
    diagnostics::MessageLevel
    performance::MessageLevel
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

Alternatively, the macro also accepts a boolean value for verb:

When verb is a boolean:

• true will emit the message at WarnLevel
• false will suppress the message (equivalent to Silent)

The two-argument form @SciMLMessage(message, verbosity) can be used when verbosity is a Bool:

function solve_problem(problem; verbose::Bool = true)
    @SciMLMessage("Starting solver", verbose)
    # ... solver logic ...
end

Like the base logging macros, @SciMLMessage supports additional key-value arguments:

x = 10
@SciMLMessage("Message", verbosity, :option, x, extra_info="some info")
# Output: ┌ Warning: Verbosity toggle: option
#         │          Message
#         │   x = 10
#         └   extra_info = "some info"