// ------------------------------------------------------------------------ // // SPDX-License-Identifier: LGPL-2.1-or-later // Copyright (C) 2010 - 2025 by the deal.II authors // // This file is part of the deal.II library. // // Part of the source code is dual licensed under Apache-2.0 WITH // LLVM-exception OR LGPL-2.1-or-later. Detailed license information // governing the source code and code contributions can be found in // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II. // // ------------------------------------------------------------------------ #ifndef dealii_newton_h #define dealii_newton_h #include #include #include #include #include #include DEAL_II_NAMESPACE_OPEN // Forward declaration #ifndef DOXYGEN class ParameterHandler; #endif namespace Algorithms { /** * Operator class performing Newton's iteration with standard step size * control and adaptive matrix generation. * * This class performs a Newton iteration up to convergence determined by * #control. If after an update the norm of the residual has become larger, * then step size control is activated and the update is subsequently * divided by two until the residual actually becomes smaller (or the * minimal scaling factor determined by #n_stepsize_iterations is reached). * * Since assembling matrices, depending on the implementation, tends to be * costly, this method applies an adaptive reassembling strategy. Only if * the reduction factor for the residual is more than #threshold, the event * Algorithms::bad_derivative is submitted to #inverse_derivative. It is up * to this object to implement reassembling accordingly. * *

Contents of the AnyData objects

* * The only value used by the Newton method is the first vector in the * parameter out of operator()(). It serves as the start vector of * Newton's method and in the end contains the solution. All other vectors * of out are ignored by Newton's method and its inner Operator * objects. All vectors of in are forwarded to the inner Operator * objects, with additional information added as follows. * * When calling (*#residual)(), the AnyData in given to the Newton * iteration is prepended by a vector "Newton iterate", the current * value of the Newton iterate, which can be used to evaluate the residual * at this point. * * For the call to (*#inverse_derivative), the vector "Newton * residual" is inserted before "Newton iterate". */ template class Newton : public OperatorBase { public: /** * Constructor, receiving the applications computing the residual and * solving the linear problem, respectively. */ Newton(OperatorBase &residual, OperatorBase &inverse_derivative); /** * Declare the parameters applicable to Newton's method. */ static void declare_parameters(ParameterHandler ¶m); /** * Read the parameters in the ParameterHandler. */ void parse_parameters(ParameterHandler ¶m); /** * Initialize the pointer data_out for debugging. */ void initialize(OutputOperator &output); /** * The actual Newton iteration. The initial value is in out(0), * which also contains the result after convergence. Values in in * are not used by Newton, but will be handed down to the objects * #residual and #inverse_derivative. */ virtual void operator()(AnyData &out, const AnyData &in) override; virtual void notify(const Event &) override; /** * Set the maximal residual reduction allowed without triggering * assembling in the next step. Return the previous value. */ double threshold(double new_value); /** * Control object for the Newton iteration. */ ReductionControl control; private: /** * The operator computing the residual. */ ObserverPointer> residual; /** * The operator applying the inverse derivative to the residual. */ ObserverPointer> inverse_derivative; /** * The operator handling the output in case the debug_vectors is true. * Call the initialize function first. */ ObserverPointer, Newton> data_out; /** * This flag is set by the function assemble(), indicating that the matrix * must be assembled anew upon start. */ bool assemble_now; /** * A flag used to decide how many stepsize iteration should be made. * Default is the original value of 21. * * Enter zero here to turn off stepsize control. * * @note Controlled by Stepsize iterations in parameter file */ unsigned int n_stepsize_iterations; /** * Threshold for re-assembling matrix. * * If the quotient of two consecutive residuals is smaller than this * threshold, the system matrix is not assembled in this step. * * @note This parameter should be adjusted to the residual gain of the * inner solver. * * The default values is zero, resulting in reassembling in every Newton * step. */ double assemble_threshold; public: /** * Print residual, update and updated solution after each step into file * Newton_NNN? */ bool debug_vectors; /** * Write debug output to @p deallog; the higher the number, the more * output. */ unsigned int debug; }; } // namespace Algorithms DEAL_II_NAMESPACE_CLOSE #endif