Cantera  3.2.0a2
Loading...
Searching...
No Matches
MultiNewton.h
Go to the documentation of this file.
1//! @file MultiNewton.h
2
3// This file is part of Cantera. See License.txt in the top-level directory or
4// at https://cantera.org/license.txt for license and copyright information.
5
6#ifndef CT_MULTINEWTON_H
7#define CT_MULTINEWTON_H
8
10#include "OneDim.h" // @todo: remove after Cantera 3.2
11
12namespace Cantera
13{
14
15//! @defgroup onedUtilsGroup Utilities
16//! Utility classes and functions for one-dimensional problems.
17//! @ingroup onedGroup
18
19/**
20 * Newton iterator for multi-domain, one-dimensional problems.
21 * Used by class OneDim.
22 * @ingroup onedUtilsGroup
23 */
25{
26public:
27 //! Constructor
28 //! @param sz Number of variables in the system
29 MultiNewton(int sz);
30 virtual ~MultiNewton() {};
31 MultiNewton(const MultiNewton&) = delete;
32 MultiNewton& operator=(const MultiNewton&) = delete;
33
34 //! Get the number of variables in the system.
35 size_t size() {
36 return m_n;
37 }
38
39 //! Compute the undamped Newton step. The residual function is evaluated
40 //! at `x`, but the Jacobian is not recomputed.
41 //! @since Starting in %Cantera 3.2, the Jacobian is accessed via the OneDim object.
42 void step(double* x, double* step, SteadyStateSystem& r, int loglevel);
43
44 //! @deprecated Use version without MultiJac argument. To be removed after
45 //! %Cantera 3.2.
46 void step(double* x, double* stp, OneDim& r, MultiJac& jac, int loglevel) {
47 warn_deprecated("MultiNewton::step(..., MultiJac&, ...)",
48 "Use version without MultiJac argument. "
49 "To be removed after Cantera 3.2");
50 step(x, stp, r, loglevel);
51 }
52
53 /**
54 * Return the factor by which the undamped Newton step 'step0'
55 * must be multiplied in order to keep all solution components in
56 * all domains between their specified lower and upper bounds.
57 */
58 double boundStep(const double* x0, const double* step0,
59 const SteadyStateSystem& r, int loglevel);
60
61 /**
62 * Performs a damped Newton step to solve the system of nonlinear equations.
63 *
64 * On entry, `step0` must contain an undamped Newton step for the solution `x0`.
65 * This method attempts to find a damping coefficient `alpha_k` such that the next
66 * undamped step would have a norm smaller than that of `step0`. If successful,
67 * the new solution after taking the damped step is returned in `x1`, and the
68 * undamped step at `x1` is returned in `step1`.
69 *
70 * This uses the method outlined in Kee et al. @cite kee2003.
71 *
72 * The system of equations can be written in the form:
73 * @f[
74 * F(x) = 0
75 * @f]
76 *
77 * Where @f$ F @f$ is the system of nonlinear equations and @f$ x @f$ is the
78 * solution vector.
79 *
80 * For the damped Newton method we are solving:
81 *
82 * @f[
83 * x_{k+1} - x_k = \Delta x_k = -\alpha_k J^{-1}(x_k) F(x_k)
84 * @f]
85 *
86 * Where @f$ J @f$ is the Jacobian matrix of @f$ F @f$ with respect to @f$ x @f$,
87 * and @f$ \alpha_k @f$ is the damping factor, and @f$ \Delta x_k @f$ is the Newton
88 * step at @f$ x_k @f$, sometimes called the correction vector. In the equations
89 * here, @f$ k @f$ is just an iteration variable.
90 *
91 * In this method, the Jacobian does not update, even when the solution vector is
92 * evaluated at different points.
93 *
94 * The general algorithm is described below.
95 *
96 * We want to solve the equation:
97 * @f[
98 * x_{k+1} = x_k + \alpha_k \Delta x_k
99 * @f]
100 *
101 * Pick @f$ \alpha_k @f$ such that
102 * @f$ \Vert \Delta x_{k+1} \Vert < \Vert \Delta x_k \Vert @f$
103 * where @f$ \Delta x_k = J^{-1}(x_k) F(x_k) @f$, and
104 * @f$ \Delta x_{k+1} = J^{-1}(x_{k}) F(x_{k+1}) @f$.
105 *
106 * @param[in] x0 initial solution about which a Newton step will be taken
107 * @param[in] step0 initial undamped Newton step
108 * @param[out] x1 solution after taking the damped Newton step
109 * @param[out] step1 Newton step after taking the damped Newton step
110 * @param[out] s1 norm of the subsequent Newton step after taking the damped Newton
111 * step
112 * @param[in] r domain object, used for evaluating residuals over all domains
113 * @param[in] loglevel controls amount of printed diagnostics
114 * @param[in] writetitle controls if logging title is printed
115 *
116 * @returns
117 * - `1` a damping coefficient was found and the solution converges.
118 * - `0` a damping coefficient was found, but the solution has not converged yet.
119 * - `-2` no suitable damping coefficient was found within the maximum iterations.
120 * - `-3` the current solution `x0` is too close to the solution bounds and the
121 * step would exceed the bounds on one or more components.
122 * - `-4` Steady-state Jacobian factorization failed.
123 * - `-5` Error taking Newton step
124 *
125 * @since Starting in %Cantera 3.2, the Jacobian is accessed via the
126 * SteadyStateSystem object.
127 */
128 int dampStep(const double* x0, const double* step0, double* x1, double* step1,
129 double& s1, SteadyStateSystem& r, int loglevel, bool writetitle);
130
131 //! @deprecated Use version without MultiJac argument. To be removed after
132 //! %Cantera 3.2.
133 int dampStep(const double* x0, const double* step0, double* x1, double* step1,
134 double& s1, OneDim& r, MultiJac& jac, int loglevel, bool writetitle)
135 {
136 warn_deprecated("MultiNewton::dampStep(..., MultiJac&, ...)",
137 "Use version without MultiJac argument. "
138 "To be removed after Cantera 3.2");
139 return dampStep(x0, step0, x1, step1, s1, r, loglevel, writetitle);
140 }
141
142 //! Compute the weighted 2-norm of `step`.
143 double norm2(const double* x, const double* step, OneDim& r) const {
144 warn_deprecated("MultiNewton::norm2", "Replaced by "
145 "SteadyStateSystem::weightedNorm. To be removed after Cantera 3.2.");
146 return r.weightedNorm(step);
147 }
148
149 /**
150 * Find the solution to F(x) = 0 by damped Newton iteration. On entry, x0
151 * contains an initial estimate of the solution. On successful return, x1
152 * contains the converged solution. If failure occurs, x1 will contain the
153 * value of x0 i.e. no change in solution.
154 *
155 * The convergence criteria is when the 2-norm of the Newton step is less than one.
156 *
157 * @returns
158 * - `1` a converged solution was found.
159 * - `-2` no suitable damping coefficient was found within the maximum iterations.
160 * - `-3` the current solution `x0` is too close to the solution bounds and the
161 * step would exceed the bounds on one or more components.
162 *
163 * @since Starting in %Cantera 3.2, the Jacobian is accessed via the
164 * SteadyStateSystem object.
165 */
166 int solve(double* x0, double* x1, SteadyStateSystem& r, int loglevel);
167
168 //! @deprecated Use version without MultiJac argument. To be removed after
169 //! %Cantera 3.2.
170 int solve(double* x0, double* x1, OneDim& r, MultiJac& jac, int loglevel) {
171 warn_deprecated("MultiNewton::solve(..., MultiJac&, ...)",
172 "Use version without MultiJac argument. "
173 "To be removed after Cantera 3.2");
174 return solve(x0, x1, r, loglevel);
175 }
176
177 //! Set options.
178 //! @param maxJacAge Maximum number of steps that can be taken before requiring
179 //! a Jacobian update
180 void setOptions(int maxJacAge = 5) {
181 m_maxAge = maxJacAge;
182 }
183
184 //! Change the problem size.
185 void resize(size_t points);
186
187protected:
188 //! Work array holding the system state after the last successful step. Size #m_n.
189 vector<double> m_x;
190
191 //! Work array holding the undamped Newton step or the system residual. Size #m_n.
192 vector<double> m_stp;
193
194 //! Work array holding the damped Newton step. Size #m_n.
195 vector<double> m_stp1;
196
197 //! Maximum allowable Jacobian age before it is recomputed.
198 int m_maxAge = 5;
199
200 //! Factor by which the damping coefficient is reduced in each iteration
201 double m_dampFactor = sqrt(2.0);
202
203 //! Maximum number of damping iterations
204 size_t m_maxDampIter = 7;
205
206 //! number of variables
207 size_t m_n;
208
209 //! Elapsed CPU time spent computing the Jacobian.
210 double m_elapsed = 0.0;
211};
212}
213
214#endif
Class MultiJac evaluates the Jacobian of a system of equations defined by a residual function supplie...
Definition MultiJac.h:25
Newton iterator for multi-domain, one-dimensional problems.
Definition MultiNewton.h:25
double m_dampFactor
Factor by which the damping coefficient is reduced in each iteration.
size_t size()
Get the number of variables in the system.
Definition MultiNewton.h:35
void resize(size_t points)
Change the problem size.
vector< double > m_x
Work array holding the system state after the last successful step. Size m_n.
double norm2(const double *x, const double *step, OneDim &r) const
Compute the weighted 2-norm of step.
double m_elapsed
Elapsed CPU time spent computing the Jacobian.
vector< double > m_stp1
Work array holding the damped Newton step. Size m_n.
vector< double > m_stp
Work array holding the undamped Newton step or the system residual. Size m_n.
void step(double *x, double *stp, OneDim &r, MultiJac &jac, int loglevel)
Definition MultiNewton.h:46
size_t m_maxDampIter
Maximum number of damping iterations.
int dampStep(const double *x0, const double *step0, double *x1, double *step1, double &s1, SteadyStateSystem &r, int loglevel, bool writetitle)
Performs a damped Newton step to solve the system of nonlinear equations.
int dampStep(const double *x0, const double *step0, double *x1, double *step1, double &s1, OneDim &r, MultiJac &jac, int loglevel, bool writetitle)
int m_maxAge
Maximum allowable Jacobian age before it is recomputed.
int solve(double *x0, double *x1, SteadyStateSystem &r, int loglevel)
Find the solution to F(x) = 0 by damped Newton iteration.
double boundStep(const double *x0, const double *step0, const SteadyStateSystem &r, int loglevel)
Return the factor by which the undamped Newton step 'step0' must be multiplied in order to keep all s...
int solve(double *x0, double *x1, OneDim &r, MultiJac &jac, int loglevel)
void setOptions(int maxJacAge=5)
Set options.
void step(double *x, double *step, SteadyStateSystem &r, int loglevel)
Compute the undamped Newton step.
size_t m_n
number of variables
Container class for multiple-domain 1D problems.
Definition OneDim.h:27
double weightedNorm(const double *step) const override
Compute the weighted norm of a step vector.
Definition OneDim.cpp:98
Base class for representing a system of differential-algebraic equations and solving for its steady-s...
Namespace for the Cantera kernel.
Definition AnyMap.cpp:595
void warn_deprecated(const string &source, const AnyBase &node, const string &message)
A deprecation warning for syntax in an input file.
Definition AnyMap.cpp:1997