Debian Codegraph @

include/deal.II/algorithms/newton.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2010 - 2025 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15
16 #ifndef dealii_newton_h
17 #define dealii_newton_h
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/algorithms/any_data.h>
22 #include <deal.II/algorithms/operator.h>
23
24 #include <deal.II/base/event.h>
25 #include <deal.II/base/observer_pointer.h>
26
27 #include <deal.II/lac/solver_control.h>
28
29 DEAL_II_NAMESPACE_OPEN
30
31 // Forward declaration
32 #ifndef DOXYGEN
33 class ParameterHandler;
34 #endif
35
36 namespace Algorithms
37 {
38 /**
39 * Operator class performing Newton's iteration with standard step size
40 * control and adaptive matrix generation.
41 *
42 * This class performs a Newton iteration up to convergence determined by
43 * #control. If after an update the norm of the residual has become larger,
44 * then step size control is activated and the update is subsequently
45 * divided by two until the residual actually becomes smaller (or the
46 * minimal scaling factor determined by #n_stepsize_iterations is reached).
47 *
48 * Since assembling matrices, depending on the implementation, tends to be
49 * costly, this method applies an adaptive reassembling strategy. Only if
50 * the reduction factor for the residual is more than #threshold, the event
51 * Algorithms::bad_derivative is submitted to #inverse_derivative. It is up
52 * to this object to implement reassembling accordingly.
53 *
54 * <h3>Contents of the AnyData objects</h3>
55 *
56 * The only value used by the Newton method is the first vector in the
57 * parameter <tt>out</tt> of operator()(). It serves as the start vector of
58 * Newton's method and in the end contains the solution. All other vectors
59 * of <tt>out</tt> are ignored by Newton's method and its inner Operator
60 * objects. All vectors of <tt>in</tt> are forwarded to the inner Operator
61 * objects, with additional information added as follows.
62 *
63 * When calling (*#residual)(), the AnyData <tt>in</tt> given to the Newton
64 * iteration is prepended by a vector <tt>"Newton iterate"</tt>, the current
65 * value of the Newton iterate, which can be used to evaluate the residual
66 * at this point.
67 *
68 * For the call to (*#inverse_derivative), the vector <tt>"Newton
69 * residual"</tt> is inserted before <tt>"Newton iterate"</tt>.
70 */
71 template <typename VectorType>
72 class Newton : public OperatorBase
73 {
74 public:
75 /**
76 * Constructor, receiving the applications computing the residual and
77 * solving the linear problem, respectively.
78 */
79 Newton(OperatorBase &residual, OperatorBase &inverse_derivative);
80
81 /**
82 * Declare the parameters applicable to Newton's method.
83 */
84 static void
85 declare_parameters(ParameterHandler &param);
86
87 /**
88 * Read the parameters in the ParameterHandler.
89 */
90 void
91 parse_parameters(ParameterHandler &param);
92
93 /**
94 * Initialize the pointer data_out for debugging.
95 */
96 void
97 initialize(OutputOperator<VectorType> &output);
98
99 /**
100 * The actual Newton iteration. The initial value is in <tt>out(0)</tt>,
101 * which also contains the result after convergence. Values in <tt>in</tt>
102 * are not used by Newton, but will be handed down to the objects
103 * #residual and #inverse_derivative.
104 */
105 virtual void
106 operator()(AnyData &out, const AnyData &in) override;
107
108 virtual void
109 notify(const Event &) override;
110
111 /**
112 * Set the maximal residual reduction allowed without triggering
113 * assembling in the next step. Return the previous value.
114 */
115 double
116 threshold(double new_value);
117
118 /**
119 * Control object for the Newton iteration.
120 */
121 ReductionControl control;
122
123 private:
124 /**
125 * The operator computing the residual.
126 */
127 ObserverPointer<OperatorBase, Newton<VectorType>> residual;
128
129 /**
130 * The operator applying the inverse derivative to the residual.
131 */
132 ObserverPointer<OperatorBase, Newton<VectorType>> inverse_derivative;
133
134 /**
135 * The operator handling the output in case the debug_vectors is true.
136 * Call the initialize function first.
137 */
138 ObserverPointer<OutputOperator<VectorType>, Newton<VectorType>> data_out;
139
140 /**
141 * This flag is set by the function assemble(), indicating that the matrix
142 * must be assembled anew upon start.
143 */
144 bool assemble_now;
145
146 /**
147 * A flag used to decide how many stepsize iteration should be made.
148 * Default is the original value of 21.
149 *
150 * Enter zero here to turn off stepsize control.
151 *
152 * @note Controlled by <tt>Stepsize iterations</tt> in parameter file
153 */
154 unsigned int n_stepsize_iterations;
155
156 /**
157 * Threshold for re-assembling matrix.
158 *
159 * If the quotient of two consecutive residuals is smaller than this
160 * threshold, the system matrix is not assembled in this step.
161 *
162 * @note This parameter should be adjusted to the residual gain of the
163 * inner solver.
164 *
165 * The default values is zero, resulting in reassembling in every Newton
166 * step.
167 */
168 double assemble_threshold;
169
170 public:
171 /**
172 * Print residual, update and updated solution after each step into file
173 * <tt>Newton_NNN</tt>?
174 */
175 bool debug_vectors;
176 /**
177 * Write debug output to @p deallog; the higher the number, the more
178 * output.
179 */
180 unsigned int debug;
181 };
182 } // namespace Algorithms
183
184 DEAL_II_NAMESPACE_CLOSE
185
186 #endif