Merge simpler stopping criterion interface

Since the value type is known from the vector dynamic type at generation time of the stopping criterion,
we don't need to specify it manually, and can remove the value-typed threshold parameters.
This effectively means replacing typed stopping criteria like

```
.with_criteria(gko::stop::ResidualNorm<float>::build().with_baseline(gko::stop::mode::absolute).with_reduction_factor(1e-5))
```

by the simpler

```
.with_criteria(gko::stop::abs_residual_norm(1e-5))
```

Related PR: #1947

Author: upsj

core/config/multigrid_config.cpp

@@ -1,9 +1,10 @@
-// SPDX-FileCopyrightText: 2017 - 2024 The Ginkgo authors
+// SPDX-FileCopyrightText: 2017 - 2025 The Ginkgo authors
 //
 // SPDX-License-Identifier: BSD-3-Clause
 
+#include <ginkgo/core/multigrid/pgm.hpp>
+
 #include "core/config/parse_macro.hpp"
-#include "ginkgo/core/multigrid/pgm.hpp"
 
 
 namespace gko {

core/solver/pipe_cg.cpp

@@ -12,13 +12,13 @@
 #include <ginkgo/core/base/math.hpp>
 #include <ginkgo/core/base/name_demangling.hpp>
 #include <ginkgo/core/base/precision_dispatch.hpp>
+#include <ginkgo/core/base/range.hpp>
 #include <ginkgo/core/base/utils.hpp>
 
 #include "core/config/solver_config.hpp"
 #include "core/distributed/helpers.hpp"
 #include "core/solver/pipe_cg_kernels.hpp"
 #include "core/solver/solver_boilerplate.hpp"
-#include "ginkgo/core/base/range.hpp"
 
 
 namespace gko {

core/stop/iteration.cpp

@@ -1,9 +1,11 @@
-// SPDX-FileCopyrightText: 2017 - 2024 The Ginkgo authors
+// SPDX-FileCopyrightText: 2017 - 2025 The Ginkgo authors
 //
 // SPDX-License-Identifier: BSD-3-Clause
 
 #include "ginkgo/core/stop/iteration.hpp"
 
+#include <ginkgo/core/base/abstract_factory.hpp>
+
 
 namespace gko {
 namespace stop {
@@ -22,5 +24,11 @@ bool Iteration::check_impl(uint8 stoppingId, bool setFinalized,
 }
 
 
+deferred_factory_parameter<Iteration::Factory> max_iters(size_type count)
+{
+    return Iteration::build().with_max_iters(count);
+}
+
+
 }  // namespace stop
 }  // namespace gko

core/stop/residual_norm.cpp

@@ -1,10 +1,12 @@
-// SPDX-FileCopyrightText: 2017 - 2024 The Ginkgo authors
+// SPDX-FileCopyrightText: 2017 - 2025 The Ginkgo authors
 //
 // SPDX-License-Identifier: BSD-3-Clause
 
 #include "ginkgo/core/stop/residual_norm.hpp"
 
+#include <ginkgo/core/base/exception_helpers.hpp>
 #include <ginkgo/core/base/precision_dispatch.hpp>
+#include <ginkgo/core/stop/criterion.hpp>
 
 #include "core/base/dispatch_helper.hpp"
 #include "core/components/fill_array_kernels.hpp"
@@ -234,6 +236,164 @@ GKO_INSTANTIATE_FOR_EACH_VALUE_TYPE(GKO_DECLARE_RESIDUAL_NORM);
     class ImplicitResidualNorm<_type>
 GKO_INSTANTIATE_FOR_EACH_VALUE_TYPE(GKO_DECLARE_IMPLICIT_RESIDUAL_NORM);
 
+class ResidualNormFactory;
+
+struct residual_norm_factory_parameters
+    : public enable_parameters_type<residual_norm_factory_parameters,
+                                    ResidualNormFactory> {
+    double GKO_FACTORY_PARAMETER_SCALAR(threshold, 0.0);
+
+    mode GKO_FACTORY_PARAMETER_SCALAR(baseline, mode::rhs_norm);
+
+    bool GKO_FACTORY_PARAMETER_SCALAR(implicit, false);
+};
+
+
+class ResidualNormFactory
+    : public EnablePolymorphicObject<ResidualNormFactory, CriterionFactory>,
+      public EnablePolymorphicAssignment<ResidualNormFactory> {
+    friend class EnablePolymorphicObject<ResidualNormFactory, CriterionFactory>;
+    friend class enable_parameters_type<residual_norm_factory_parameters,
+                                        ResidualNormFactory>;
+    friend EnableDefaultCriterionFactory<ResidualNormFactory, Criterion,
+                                         residual_norm_factory_parameters>;
+
+    explicit ResidualNormFactory(
+        std::shared_ptr<const Executor> exec,
+        const residual_norm_factory_parameters& parameters = {})
+        : EnablePolymorphicObject<ResidualNormFactory, CriterionFactory>(
+              std::move(exec)),
+          parameters_{parameters}
+    {}
+
+    std::unique_ptr<Criterion> generate_impl(CriterionArgs args) const override
+    {
+        std::unique_ptr<Criterion> result;
+        auto exec = this->get_executor();
+        run<matrix::Dense<double>, matrix::Dense<std::complex<double>>,
+            matrix::Dense<float>, matrix::Dense<std::complex<float>>
+#if GINKGO_ENABLE_HALF
+            ,
+            matrix::Dense<half>, matrix::Dense<std::complex<half>>
+#endif
+#if GINKGO_ENABLE_BFLOAT16
+            ,
+            matrix::Dense<bfloat16>, matrix::Dense<std::complex<bfloat16>>
+#endif
+#if GINKGO_BUILD_MPI
+            ,
+            experimental::distributed::Vector<double>,
+            experimental::distributed::Vector<std::complex<double>>,
+            experimental::distributed::Vector<float>,
+            experimental::distributed::Vector<std::complex<float>>
+#if GINKGO_ENABLE_HALF
+            ,
+            experimental::distributed::Vector<half>,
+            experimental::distributed::Vector<std::complex<half>>
+#endif
+#if GINKGO_ENABLE_BFLOAT16
+            ,
+            experimental::distributed::Vector<bfloat16>,
+            experimental::distributed::Vector<std::complex<bfloat16>>
+#endif
+#endif
+            >(args.b, [&](auto dense_b) {
+            using value_type =
+                typename std::decay_t<decltype(*dense_b)>::value_type;
+            constexpr bool is_distributed =
+                std::is_same_v<std::decay_t<decltype(*dense_b)>,
+                               experimental::distributed::Vector<value_type>>;
+            using vector_type = std::conditional_t<
+                is_distributed, experimental::distributed::Vector<value_type>,
+                matrix::Dense<value_type>>;
+            auto dense_x = as<vector_type>(args.x);
+            auto dense_r = as<vector_type>(args.initial_residual);
+            auto cast_threshold = static_cast<remove_complex<value_type>>(
+                this->parameters_.threshold);
+            auto cast_args =
+                CriterionArgs{args.system_matrix, dense_b, dense_x, dense_r};
+            if (static_cast<double>(cast_threshold) <= 0.0) {
+                GKO_INVALID_STATE(
+                    "stopping criterion threshold is zero or negative when "
+                    "cast to ValueType");
+            }
+            if (this->parameters_.implicit) {
+                result = ImplicitResidualNorm<value_type>::build()
+                             .with_baseline(this->parameters_.baseline)
+                             .with_reduction_factor(cast_threshold)
+                             .on(exec)
+                             ->generate(cast_args);
+            } else {
+                result = ResidualNorm<value_type>::build()
+                             .with_baseline(this->parameters_.baseline)
+                             .with_reduction_factor(cast_threshold)
+                             .on(exec)
+                             ->generate(cast_args);
+            }
+        });
+        return result;
+    }
+
+    residual_norm_factory_parameters parameters_;
+};
+
+
+deferred_factory_parameter<CriterionFactory> absolute_residual_norm(
+    double tolerance)
+{
+    return residual_norm_factory_parameters{}
+        .with_threshold(tolerance)
+        .with_baseline(mode::absolute);
+}
+
+
+deferred_factory_parameter<CriterionFactory> relative_residual_norm(
+    double tolerance)
+{
+    return residual_norm_factory_parameters{}
+        .with_threshold(tolerance)
+        .with_baseline(mode::rhs_norm);
+}
+
+
+deferred_factory_parameter<CriterionFactory> initial_residual_norm(
+    double tolerance)
+{
+    return residual_norm_factory_parameters{}
+        .with_threshold(tolerance)
+        .with_baseline(mode::initial_resnorm);
+}
+
+
+deferred_factory_parameter<CriterionFactory> absolute_implicit_residual_norm(
+    double tolerance)
+{
+    return residual_norm_factory_parameters{}
+        .with_threshold(tolerance)
+        .with_baseline(mode::absolute)
+        .with_implicit(true);
+}
+
+
+deferred_factory_parameter<CriterionFactory> relative_implicit_residual_norm(
+    double tolerance)
+{
+    return residual_norm_factory_parameters{}
+        .with_threshold(tolerance)
+        .with_baseline(mode::rhs_norm)
+        .with_implicit(true);
+}
+
+
+deferred_factory_parameter<CriterionFactory> initial_implicit_residual_norm(
+    double tolerance)
+{
+    return residual_norm_factory_parameters{}
+        .with_threshold(tolerance)
+        .with_baseline(mode::initial_resnorm)
+        .with_implicit(true);
+}
+
 
 }  // namespace stop
 }  // namespace gko

core/stop/time.cpp

@@ -1,9 +1,13 @@
-// SPDX-FileCopyrightText: 2017 - 2024 The Ginkgo authors
+// SPDX-FileCopyrightText: 2017 - 2025 The Ginkgo authors
 //
 // SPDX-License-Identifier: BSD-3-Clause
 
 #include "ginkgo/core/stop/time.hpp"
 
+#include <chrono>
+
+#include <ginkgo/core/base/abstract_factory.hpp>
+
 
 namespace gko {
 namespace stop {
@@ -22,5 +26,12 @@ bool Time::check_impl(uint8 stoppingId, bool setFinalized,
 }
 
 
+deferred_factory_parameter<Time::Factory> time_limit(
+    std::chrono::nanoseconds time)
+{
+    return Time::build().with_time_limit(time);
+}
+
+
 }  // namespace stop
 }  // namespace gko

core/test/matrix/csr.cpp

@@ -5,10 +5,10 @@
 #include <gtest/gtest.h>
 
 #include <ginkgo/core/base/device_matrix_data.hpp>
+#include <ginkgo/core/base/exception.hpp>
 #include <ginkgo/core/matrix/csr.hpp>
 
 #include "core/test/utils.hpp"
-#include "ginkgo/core/base/exception.hpp"
 
 
 namespace {

include/ginkgo/core/base/std_extensions.hpp

@@ -11,7 +11,7 @@
 #include <memory>
 #include <type_traits>
 
-#include "ginkgo/core/base/types.hpp"
+#include <ginkgo/core/base/types.hpp>
 
 
 // This header provides implementations of useful utilities introduced into the

include/ginkgo/core/stop/iteration.hpp

@@ -6,6 +6,7 @@
 #define GKO_PUBLIC_CORE_STOP_ITERATION_HPP_
 
 
+#include <ginkgo/core/base/abstract_factory.hpp>
 #include <ginkgo/core/stop/criterion.hpp>
 
 
@@ -58,6 +59,29 @@ class Iteration : public EnablePolymorphicObject<Iteration, Criterion> {
 };
 
 
+/**
+ * Creates the precursor to an Iteration stopping criterion factory, to be used
+ * in conjunction with `.with_criteria(...)` function calls when building a
+ * solver factory. This stopping criterion will stop the iteration after `count`
+ * iterations of the solver have finished.
+ *
+ * Full usage example: Stop after 100 iterations or when the relative residual
+ * norm is below $10^{-10}$, whichever happens first.
+ * ```cpp
+ * auto factory = gko::solver::Cg<double>::build()
+ *                    .with_criteria(
+ *                        gko::stop::max_iters(100),
+ *                        gko::stop::relative_residual_norm(1e-10))
+ *                    .on(exec);
+ * ```
+ *
+ * @param count  the number of iterations after which to stop
+ * @return a deferred_factory_parameter that can be passed to the
+ *         `with_criteria` function when building a solver.
+ */
+deferred_factory_parameter<Iteration::Factory> max_iters(size_type count);
+
+
 }  // namespace stop
 }  // namespace gko
 

include/ginkgo/core/stop/residual_norm.hpp

@@ -224,6 +224,61 @@ class ImplicitResidualNorm : public ResidualNormBase<ValueType> {
 };
 
 
+/**
+ * Creates the precursor to a ResidualNorm stopping criterion factory, to be
+ * used in conjunction with `.with_criteria(...)` function calls when building a
+ * solver factory. This stopping criterion will stop the iteration after the
+ * residual norm has decreased below the specified value or by the specified
+ * amount.
+ *
+ * Full usage example: Stop after 100 iterations or when the absolute residual
+ * norm is below $10^{-10}$, whichever happens first.
+ * ```cpp
+ * auto factory = gko::solver::Cg<double>::build()
+ *                    .with_criteria(
+ *                        gko::stop::max_iters(100),
+ *                        gko::stop::absolute_residual_norm(1e-10))
+ *                    .on(exec);
+ * ```
+ *
+ * @param tolerance  the value the residual norm needs to be below.
+ *     With residual $r$, initial guess $x_0$, right-hand side $b$, matrix $A$,
+ *     `absolute` means the exact value of the norm $||r||$,
+ *     `relative` means the norm relative to the right-hand side $||r||/||b||$,
+ *     `initial` means the norm relative to the initial residual
+ *     $||r||/||b - A x_0||$.
+ *     An implicit stopping criterion is only available with some solvers, and
+ *     refers to either the energy norm $||r||_A$ in short-recurrence solvers
+ *     like Cg or the euclidian norm $||r||$ in solvers like GMRES.
+ *     Implicit residual norms are cheaper to compute, but may be less precise
+ *     due to accumulating rounding errors.
+ * @return a deferred_factory_parameter that can be passed to the
+ *         `with_criteria` function when building a solver.
+ */
+deferred_factory_parameter<CriterionFactory> absolute_residual_norm(
+    double tolerance);
+
+/** @copydoc absolute_residual_norm */
+deferred_factory_parameter<CriterionFactory> relative_residual_norm(
+    double tolerance);
+
+/** @copydoc absolute_residual_norm */
+deferred_factory_parameter<CriterionFactory> initial_residual_norm(
+    double tolerance);
+
+/** @copydoc absolute_residual_norm */
+deferred_factory_parameter<CriterionFactory> absolute_implicit_residual_norm(
+    double tolerance);
+
+/** @copydoc absolute_residual_norm */
+deferred_factory_parameter<CriterionFactory> relative_implicit_residual_norm(
+    double tolerance);
+
+/** @copydoc absolute_residual_norm */
+deferred_factory_parameter<CriterionFactory> initial_implicit_residual_norm(
+    double tolerance);
+
+
 // The following classes are deprecated, but they internally reference
 // themselves. To reduce unnecessary warnings, we disable deprecation warnings
 // for the definition of these classes.