criterion.hpp

// SPDX-FileCopyrightText: 2017 - 2026 The Ginkgo authors
//
// SPDX-License-Identifier: BSD-3-Clause
 
#ifndef GKO_PUBLIC_CORE_STOP_CRITERION_HPP_
#define GKO_PUBLIC_CORE_STOP_CRITERION_HPP_
 
 
#include <ginkgo/core/base/abstract_factory.hpp>
#include <ginkgo/core/base/array.hpp>
#include <ginkgo/core/base/executor.hpp>
#include <ginkgo/core/base/lin_op.hpp>
#include <ginkgo/core/base/polymorphic_object.hpp>
#include <ginkgo/core/base/utils.hpp>
#include <ginkgo/core/log/logger.hpp>
#include <ginkgo/core/stop/stopping_status.hpp>
 
 
namespace gko {
namespace stop {
 
 
class Criterion : public PolymorphicObject {
public:
    class Updater {
        friend class Criterion;
 
    public:
        Updater(const Updater&) = delete;
        Updater(Updater&&) = delete;
        Updater& operator=(const Updater&) = delete;
        Updater& operator=(Updater&&) = delete;
 
        bool check(uint8 stopping_id, bool set_finalized,
                   array<stopping_status>* stop_status, bool* one_changed) const
        {
            auto converged = parent_->check(stopping_id, set_finalized,
                                            stop_status, one_changed, *this);
            return converged;
        }
 
#define GKO_UPDATER_REGISTER_PARAMETER(_type, _name) \
    const Updater& _name(_type const& value) const   \
    {                                                \
        _name##_ = value;                            \
        return *this;                                \
    }                                                \
    mutable _type _name##_ {}
#define GKO_UPDATER_REGISTER_PTR_PARAMETER(_type, _name) \
    const Updater& _name(ptr_param<_type> value) const   \
    {                                                    \
        _name##_ = value.get();                          \
        return *this;                                    \
    }                                                    \
    mutable _type* _name##_ {}
 
        GKO_UPDATER_REGISTER_PARAMETER(size_type, num_iterations);
        // ignore_residual_check default is false
        GKO_UPDATER_REGISTER_PARAMETER(bool, ignore_residual_check);
        GKO_UPDATER_REGISTER_PTR_PARAMETER(const LinOp, residual);
        GKO_UPDATER_REGISTER_PTR_PARAMETER(const LinOp, residual_norm);
        GKO_UPDATER_REGISTER_PTR_PARAMETER(const LinOp,
                                           implicit_sq_residual_norm);
        GKO_UPDATER_REGISTER_PTR_PARAMETER(const LinOp, solution);
 
#undef GKO_UPDATER_REGISTER_PTR_PARAMETER
#undef GKO_UPDATER_REGISTER_PARAMETER
 
    private:
        Updater(Criterion* parent) : parent_{parent} {}
 
        Criterion* parent_;
    };
 
    Updater update() { return {this}; }
 
    bool check(uint8 stopping_id, bool set_finalized,
               array<stopping_status>* stop_status, bool* one_changed,
               const Updater& updater)
    {
        this->template log<log::Logger::criterion_check_started>(
            this, updater.num_iterations_, updater.residual_,
            updater.residual_norm_, updater.solution_, stopping_id,
            set_finalized);
        auto all_converged = this->check_impl(
            stopping_id, set_finalized, stop_status, one_changed, updater);
        this->template log<log::Logger::criterion_check_completed>(
            this, updater.num_iterations_, updater.residual_,
            updater.residual_norm_, updater.implicit_sq_residual_norm_,
            updater.solution_, stopping_id, set_finalized, stop_status,
            *one_changed, all_converged);
        return all_converged;
    }
 
protected:
    virtual bool check_impl(uint8 stopping_id, bool set_finalized,
                            array<stopping_status>* stop_status,
                            bool* one_changed, const Updater& updater) = 0;
 
    void set_all_statuses(uint8 stopping_id, bool set_finalized,
                          array<stopping_status>* stop_status);
 
    explicit Criterion(std::shared_ptr<const gko::Executor> exec)
        : PolymorphicObject(exec)
    {}
};
 
 
struct CriterionArgs {
    std::shared_ptr<const LinOp> system_matrix;
    std::shared_ptr<const LinOp> b;
    const LinOp* x;
    const LinOp* initial_residual;
 
 
    CriterionArgs(std::shared_ptr<const LinOp> system_matrix,
                  std::shared_ptr<const LinOp> b, const LinOp* x,
                  const LinOp* initial_residual = nullptr)
        : system_matrix{system_matrix},
          b{b},
          x{x},
          initial_residual{initial_residual}
    {}
};
 
 
using CriterionFactory = AbstractFactory<Criterion, CriterionArgs>;
 
 
template <typename ConcreteFactory, typename ConcreteCriterion,
          typename ParametersType, typename PolymorphicBase = CriterionFactory>
using EnableDefaultCriterionFactory =
    EnableDefaultFactory<ConcreteFactory, ConcreteCriterion, ParametersType,
                         PolymorphicBase>;
 
 
#define GKO_ENABLE_CRITERION_FACTORY(_criterion, _parameters_name,           \
                                     _factory_name)                          \
public:                                                                      \
    const _parameters_name##_type& get_##_parameters_name() const            \
    {                                                                        \
        return _parameters_name##_;                                          \
    }                                                                        \
                                                                             \
    class _factory_name                                                      \
        : public ::gko::stop::EnableDefaultCriterionFactory<                 \
              _factory_name, _criterion, _parameters_name##_type> {          \
        friend class ::gko::enable_parameters_type<_parameters_name##_type,  \
                                                   _factory_name>;           \
        explicit _factory_name(std::shared_ptr<const ::gko::Executor> exec)  \
            : ::gko::stop::EnableDefaultCriterionFactory<                    \
                  _factory_name, _criterion, _parameters_name##_type>(       \
                  std::move(exec))                                           \
        {}                                                                   \
        explicit _factory_name(std::shared_ptr<const ::gko::Executor> exec,  \
                               const _parameters_name##_type& parameters)    \
            : ::gko::stop::EnableDefaultCriterionFactory<                    \
                  _factory_name, _criterion, _parameters_name##_type>(       \
                  std::move(exec), parameters)                               \
        {}                                                                   \
    };                                                                       \
    friend ::gko::stop::EnableDefaultCriterionFactory<                       \
        _factory_name, _criterion, _parameters_name##_type>;                 \
                                                                             \
private:                                                                     \
    _parameters_name##_type _parameters_name##_;                             \
                                                                             \
public:                                                                      \
    static_assert(true,                                                      \
                  "This assert is used to counter the false positive extra " \
                  "semi-colon warnings")
 
 
}  // namespace stop
}  // namespace gko
 
 
#endif  // GKO_PUBLIC_CORE_STOP_CRITERION_HPP_