Reference documentation for deal.II version Git 409ee4b167 2020-08-14 09:46:12 -0400
\(\newcommand{\dealvcentcolon}{\mathrel{\mathop{:}}}\) \(\newcommand{\dealcoloneq}{\dealvcentcolon\mathrel{\mkern-1.2mu}=}\) \(\newcommand{\jump}[1]{\left[\!\left[ #1 \right]\!\right]}\) \(\newcommand{\average}[1]{\left\{\!\left\{ #1 \right\}\!\right\}}\)
kinsol.h
Go to the documentation of this file.
1 //-----------------------------------------------------------
2 //
3 // Copyright (C) 2017 - 2020 by the deal.II authors
4 //
5 // This file is part of the deal.II library.
6 //
7 // The deal.II library is free software; you can use it, redistribute
8 // it, and/or modify it under the terms of the GNU Lesser General
9 // Public License as published by the Free Software Foundation; either
10 // version 2.1 of the License, or (at your option) any later version.
11 // The full text of the license can be found in the file LICENSE.md at
12 // the top level directory of deal.II.
13 //
14 //---------------------------------------------------------------
15 
16 #ifndef dealii_sundials_kinsol_h
17 #define dealii_sundials_kinsol_h
18 
19 #include <deal.II/base/config.h>
20 #ifdef DEAL_II_WITH_SUNDIALS
21 
23 # include <deal.II/base/exceptions.h>
24 # include <deal.II/base/logstream.h>
25 # include <deal.II/base/mpi.h>
27 
28 # include <deal.II/lac/vector.h>
30 
31 # include <boost/signals2.hpp>
32 
33 # include <kinsol/kinsol.h>
34 # include <kinsol/kinsol_impl.h>
35 # include <nvector/nvector_serial.h>
36 # include <sundials/sundials_math.h>
37 # include <sundials/sundials_types.h>
38 
39 # include <memory>
40 
41 
43 
44 // Shorthand notation for KINSOL error codes.
45 # define AssertKINSOL(code) Assert(code >= 0, ExcKINSOLError(code))
46 
47 namespace SUNDIALS
48 {
195  template <typename VectorType = Vector<double>>
196  class KINSOL
197  {
198  public:
203  {
204  public:
210  {
214  newton = KIN_NONE,
218  linesearch = KIN_LINESEARCH,
222  fixed_point = KIN_FP,
226  picard = KIN_PICARD,
227  };
228 
258  // Global parameters
260  const unsigned int maximum_non_linear_iterations = 200,
261  const double function_tolerance = 0.0,
262  const double step_tolerance = 0.0,
263  const bool no_init_setup = false,
264  const unsigned int maximum_setup_calls = 0,
265  const double maximum_newton_step = 0.0,
266  const double dq_relative_error = 0.0,
267  const unsigned int maximum_beta_failures = 0,
268  const unsigned int anderson_subspace_size = 0)
269  : strategy(strategy)
279  {}
280 
319  void
321  {
322  static std::string strategy_str("newton");
323  prm.add_parameter("Solution strategy",
324  strategy_str,
325  "Choose among newton|linesearch|fixed_point|picard",
327  "newton|linesearch|fixed_point|picard"));
328  prm.add_action("Solution strategy", [&](const std::string &value) {
329  if (value == "newton")
330  strategy = newton;
331  else if (value == "linesearch")
333  else if (value == "fixed_point")
335  else if (value == "picard")
336  strategy = picard;
337  else
338  Assert(false, ExcInternalError());
339  });
340  prm.add_parameter("Maximum number of nonlinear iterations",
342  prm.add_parameter("Function norm stopping tolerance",
344  prm.add_parameter("Scaled step stopping tolerance", step_tolerance);
345 
346  prm.enter_subsection("Newton parameters");
347  prm.add_parameter("No initial matrix setup", no_init_setup);
348  prm.add_parameter("Maximum iterations without matrix setup",
350  prm.add_parameter("Maximum allowable scaled length of the Newton step",
352  prm.add_parameter("Relative error for different quotient computation",
354  prm.leave_subsection();
355 
356  prm.enter_subsection("Linesearch parameters");
357  prm.add_parameter("Maximum number of beta-condition failures",
359  prm.leave_subsection();
360 
361 
362  prm.enter_subsection("Fixed point and Picard parameters");
363  prm.add_parameter("Anderson acceleration subspace size",
365  prm.leave_subsection();
366  }
367 
376 
381 
389 
397 
407 
414  unsigned int maximum_setup_calls;
415 
422 
431 
437  unsigned int maximum_beta_failures;
438 
446  };
447 
457  const MPI_Comm mpi_comm = MPI_COMM_WORLD);
458 
462  ~KINSOL();
463 
469  unsigned int
470  solve(VectorType &initial_guess_and_solution);
471 
476  std::function<void(VectorType &)> reinit_vector;
477 
490  std::function<int(const VectorType &src, VectorType &dst)> residual;
491 
505  std::function<int(const VectorType &src, VectorType &dst)>
507 
508 
549  std::function<int(const VectorType &current_u, const VectorType &current_f)>
551 
589  std::function<int(const VectorType &ycur,
590  const VectorType &fcur,
591  const VectorType &rhs,
592  VectorType & dst)>
594 
601  std::function<VectorType &()> get_solution_scaling;
602 
610  std::function<VectorType &()> get_function_scaling;
611 
616  int,
617  << "One of the SUNDIALS KINSOL internal functions "
618  << " returned a negative error code: " << arg1
619  << ". Please consult SUNDIALS manual.");
620 
621 
622  private:
628  std::string,
629  << "Please provide an implementation for the function \""
630  << arg1 << "\"");
631 
637  void
639 
644 
648  void *kinsol_mem;
649 
653  N_Vector solution;
654 
658  N_Vector u_scale;
659 
663  N_Vector f_scale;
664 
668  MPI_Comm communicator;
669 
674  };
675 
676 } // namespace SUNDIALS
677 
678 
680 #endif
681 
682 
683 #endif
N_Vector solution
Definition: kinsol.h:653
unsigned int maximum_non_linear_iterations
Definition: kinsol.h:380
AdditionalData(const SolutionStrategy &strategy=linesearch, const unsigned int maximum_non_linear_iterations=200, const double function_tolerance=0.0, const double step_tolerance=0.0, const bool no_init_setup=false, const unsigned int maximum_setup_calls=0, const double maximum_newton_step=0.0, const double dq_relative_error=0.0, const unsigned int maximum_beta_failures=0, const unsigned int anderson_subspace_size=0)
Definition: kinsol.h:257
std::function< int(const VectorType &src, VectorType &dst)> residual
Definition: kinsol.h:490
unsigned int maximum_setup_calls
Definition: kinsol.h:414
static ::ExceptionBase & ExcKINSOLError(int arg1)
void add_parameter(const std::string &entry, ParameterType &parameter, const std::string &documentation="", const Patterns::PatternBase &pattern= *Patterns::Tools::Convert< ParameterType >::to_pattern(), const bool has_to_be_set=false)
std::function< int(const VectorType &src, VectorType &dst)> iteration_function
Definition: kinsol.h:506
void set_functions_to_trigger_an_assert()
Definition: kinsol.cc:344
AdditionalData data
Definition: kinsol.h:643
SolutionStrategy strategy
Definition: kinsol.h:375
N_Vector u_scale
Definition: kinsol.h:658
std::function< VectorType &()> get_function_scaling
Definition: kinsol.h:610
MPI_Comm communicator
Definition: kinsol.h:668
unsigned int anderson_subspace_size
Definition: kinsol.h:445
N_Vector f_scale
Definition: kinsol.h:663
void add_parameters(ParameterHandler &prm)
Definition: kinsol.h:320
void enter_subsection(const std::string &subsection)
#define DeclException1(Exception1, type1, outsequence)
Definition: exceptions.h:515
#define Assert(cond, exc)
Definition: exceptions.h:1411
GrowingVectorMemory< VectorType > mem
Definition: kinsol.h:673
std::function< VectorType &()> get_solution_scaling
Definition: kinsol.h:601
static ::ExceptionBase & ExcFunctionNotProvided(std::string arg1)
#define DEAL_II_NAMESPACE_CLOSE
Definition: config.h:363
unsigned int maximum_beta_failures
Definition: kinsol.h:437
std::function< int(const VectorType &ycur, const VectorType &fcur, const VectorType &rhs, VectorType &dst)> solve_jacobian_system
Definition: kinsol.h:593
void * kinsol_mem
Definition: kinsol.h:648
std::function< void(VectorType &)> reinit_vector
Definition: kinsol.h:476
KINSOL(const AdditionalData &data=AdditionalData(), const MPI_Comm mpi_comm=MPI_COMM_WORLD)
Definition: kinsol.cc:153
void add_action(const std::string &entry, const std::function< void(const std::string &value)> &action)
#define DEAL_II_NAMESPACE_OPEN
Definition: config.h:362
std::function< int(const VectorType &current_u, const VectorType &current_f)> setup_jacobian
Definition: kinsol.h:550
unsigned int solve(VectorType &initial_guess_and_solution)
Definition: kinsol.cc:188
static ::ExceptionBase & ExcInternalError()