Line data Source code
1 : //* This file is part of the MOOSE framework
2 : //* https://mooseframework.inl.gov
3 : //*
4 : //* All rights reserved, see COPYRIGHT for full restrictions
5 : //* https://github.com/idaholab/moose/blob/master/COPYRIGHT
6 : //*
7 : //* Licensed under LGPL 2.1, please see LICENSE for details
8 : //* https://www.gnu.org/licenses/lgpl-2.1.html
9 :
10 : #pragma once
11 :
12 : #include "libmesh/libmesh.h"
13 :
14 : // MOOSE includes
15 : #include "SolverParams.h"
16 : #include "MultiMooseEnum.h"
17 :
18 : #include "libmesh/petsc_macro.h"
19 : #include "libmesh/linear_solver.h"
20 : #include "libmesh/petsc_linear_solver.h"
21 :
22 : #include <petscksp.h>
23 :
24 : // Forward declarations
25 : class FEProblemBase;
26 : class NonlinearSystemBase;
27 : class CommandLine;
28 : class InputParameters;
29 : class ParallelParamObject;
30 :
31 : namespace libMesh
32 : {
33 : class DofMapBase;
34 : }
35 :
36 : namespace Moose
37 : {
38 : namespace PetscSupport
39 : {
40 :
41 : /**
42 : * A struct for storing the various types of petsc options and values
43 : */
44 : class PetscOptions
45 : {
46 : public:
47 63223 : PetscOptions()
48 442561 : : flags("", "", true), dont_add_these_options("", "", true), user_set_options("", "", true)
49 : {
50 63223 : }
51 :
52 : /// PETSc key-value pairs
53 : std::vector<std::pair<std::string, std::string>> pairs;
54 :
55 : /// Single value PETSc options (flags)
56 : MultiMooseEnum flags;
57 :
58 : /// Flags to explicitly not set, even if they are specified programmatically
59 : MultiMooseEnum dont_add_these_options;
60 :
61 : /// Options that are set by the user at the input level
62 : MultiMooseEnum user_set_options;
63 :
64 : /// Preconditioner description
65 : std::string pc_description;
66 : };
67 :
68 : /**
69 : * A function for setting the PETSc options in PETSc from the options supplied to MOOSE. This
70 : * interface function should be used when setting options on a per-system basis
71 : */
72 : void petscSetOptions(const PetscOptions & po,
73 : const SolverParams & solver_params,
74 : FEProblemBase * const problem = nullptr);
75 :
76 : /**
77 : * A function for setting the PETSc options in PETSc from the options supplied to MOOSE. This
78 : * interface function should be used for setting options all at once for all systems in a
79 : * multi-system context. Note that PetscOptions is not a vector because the options database has
80 : * prefixes for the different systems
81 : */
82 : void petscSetOptions(const PetscOptions & po,
83 : const std::vector<SolverParams> & solver_params,
84 : FEProblemBase * problem);
85 :
86 : /**
87 : * Set the default options for a KSP
88 : */
89 : void petscSetKSPDefaults(FEProblemBase & problem, KSP ksp);
90 :
91 : /**
92 : * Set the defaults for a libMesh LinearSolver
93 : *
94 : * Used in explicit solves
95 : */
96 : template <typename T>
97 : void
98 320 : setLinearSolverDefaults(FEProblemBase & problem, libMesh::LinearSolver<T> & linear_solver)
99 : {
100 320 : petscSetKSPDefaults(problem,
101 320 : libMesh::cast_ref<libMesh::PetscLinearSolver<T> &>(linear_solver).ksp());
102 320 : }
103 :
104 : /**
105 : * Sets the default options for PETSc
106 : */
107 : void petscSetDefaults(FEProblemBase & problem);
108 :
109 : PetscErrorCode petscSetupOutput(CommandLine * cmd_line);
110 :
111 : /**
112 : * Helper function for outputting the norm values with/without color
113 : */
114 : void outputNorm(libMesh::Real old_norm, libMesh::Real norm, bool use_color = false);
115 :
116 : /**
117 : * Helper function for displaying the linear residual during PETSC solve
118 : */
119 : PetscErrorCode petscLinearMonitor(KSP /*ksp*/, PetscInt its, PetscReal rnorm, void * void_ptr);
120 :
121 : /**
122 : * Process some MOOSE-wrapped PETSc options. These options have no support for multi-system as
123 : * indicated by the fact that this function takes no prefix nor solver system argument
124 : */
125 : void processSingletonMooseWrappedOptions(FEProblemBase & fe_problem,
126 : const InputParameters & params);
127 :
128 : /**
129 : * Stores the PETSc options supplied from the parameter object on the problem
130 : * @param fe_problem The problem on which we will store the parameters
131 : * @param prefix A prefix to apply to all the parameter object's PETSc options. This should either
132 : * be a single character '-' or a string like "-foo_" where the trailing '_' is required
133 : * @param param_object The parameter object potentially holding PETSc options
134 : * String prefixes may be used to select the system the parameters is applied to
135 : */
136 : void storePetscOptions(FEProblemBase & fe_problem,
137 : const std::string & prefix,
138 : const ParallelParamObject & param_object);
139 :
140 : /**
141 : * Set flags that will instruct the user on the reason their simulation diverged from PETSc's
142 : * perspective
143 : * @param fe_problem The problem from which to retrieve the PETSc options
144 : * @param prefix The prefix to add to the convergence flags. This should not contain a
145 : * leading dash per PETSc prefix convention. Note that this function will immediately \emph add said
146 : * dash at the start of \p prefix so that calls to \p PetscOptionsSetValue work. This is the
147 : * reason we pass \p prefix by value
148 : */
149 : void setConvergedReasonFlags(FEProblemBase & fe_problem, std::string prefix);
150 :
151 : /**
152 : * Sets the FE problem's solve type from the input params.
153 : */
154 : void setSolveTypeFromParams(FEProblemBase & fe_problem, const InputParameters & params);
155 :
156 : /**
157 : * Sets the FE problem's line search from the input params.
158 : */
159 : void setLineSearchFromParams(FEProblemBase & fe_problem, const InputParameters & params);
160 :
161 : /**
162 : * Sets the FE problem's matrix-free finite difference type from the input params.
163 : */
164 : void setMFFDTypeFromParams(FEProblemBase & fe_problem, const InputParameters & params);
165 :
166 : /**
167 : * Stores the Petsc flags and pair options fron the input params in the given PetscOptions object.
168 : */
169 : void storePetscOptionsFromParams(FEProblemBase & fe_problem, const InputParameters & params);
170 :
171 : /**
172 : * Populate flags in a given PetscOptions object using a vector of input arguments
173 : * @param petsc_flags Container holding the flags of the petsc options
174 : * @param prefix The prefix to add to the user provided \p petsc_flags. This should not contain a
175 : * leading dash per PETSc prefix convention. Note that this function will immediately \emph add said
176 : * dash at the start of \p prefix so that later calls to \p PetscOptionsSetValue work. This is the
177 : * reason we pass \p prefix by value
178 : * @param param_object The \p ParallelParamObject adding the PETSc options
179 : * @param petsc_options Data structure which handles petsc options within moose
180 : */
181 : void addPetscFlagsToPetscOptions(const MultiMooseEnum & petsc_flags,
182 : std::string prefix,
183 : const ParallelParamObject & param_object,
184 : PetscOptions & petsc_options);
185 :
186 : /**
187 : * Populate name and value pairs in a given PetscOptions object using vectors of input arguments
188 : * @param petsc_pair_options Option-value pairs of petsc settings
189 : * @param mesh_dimension The mesh dimension, needed for multigrid settings
190 : * @param prefix The prefix to add to the user provided \p petsc_pair_options. This should not
191 : * contain a leading dash per PETSc prefix convention. Note that this function will immediately
192 : * \emph add said dash at the start of \p prefix so that later calls to \p PetscOptionsSetValue
193 : * work. This is the reason we pass \p prefix by value
194 : * @param param_object The \p ParallelParamObject adding the PETSc options
195 : * @param petsc_options Data structure which handles petsc options within moose
196 : */
197 : void addPetscPairsToPetscOptions(
198 : const std::vector<std::pair<MooseEnumItem, std::string>> & petsc_pair_options,
199 : const unsigned int mesh_dimension,
200 : std::string prefix,
201 : const ParallelParamObject & param_object,
202 : PetscOptions & petsc_options);
203 :
204 : /**
205 : * Returns the valid petsc line search options as a set of strings
206 : */
207 : std::set<std::string> getPetscValidLineSearches();
208 :
209 : /**
210 : * Returns the PETSc options that are common between Executioners and Preconditioners
211 : * @return InputParameters object containing the PETSc related parameters
212 : *
213 : * The output of this function should be added to the the parameters object of the overarching class
214 : * @see CreateExecutionerAction
215 : */
216 : InputParameters getPetscValidParams();
217 :
218 : /// A helper function to produce a MultiMooseEnum with commonly used PETSc single options (flags)
219 : MultiMooseEnum getCommonPetscFlags();
220 :
221 : /// A helper function to produce a MultiMooseEnum with commonly used PETSc snes single options (flags)
222 : MultiMooseEnum getCommonSNESFlags();
223 :
224 : /// A helper function to produce a MultiMooseEnum with commonly used PETSc ksp single options (flags)
225 : MultiMooseEnum getCommonKSPFlags();
226 :
227 : /// A helper function to produce a MultiMooseEnum with commonly used PETSc iname options (keys in key-value pairs)
228 : MultiMooseEnum getCommonPetscKeys();
229 :
230 : /// A helper function to produce a MultiMooseEnum with commonly used PETSc snes option names (keys)
231 : MultiMooseEnum getCommonSNESKeys();
232 :
233 : /// A helper function to produce a MultiMooseEnum with commonly used PETSc ksp option names (keys)
234 : MultiMooseEnum getCommonKSPKeys();
235 :
236 : /// check if SNES type is variational inequalities (VI) solver
237 : bool isSNESVI(FEProblemBase & fe_problem);
238 :
239 : /**
240 : * A wrapper function for dealing with different versions of
241 : * PetscOptionsSetValue. This is not generally called from
242 : * MOOSE code, it is instead intended to be called by stuff in
243 : * MOOSE::PetscSupport.
244 : */
245 : void setSinglePetscOption(const std::string & name,
246 : const std::string & value = "",
247 : FEProblemBase * const problem = nullptr);
248 :
249 : /**
250 : * Same as setSinglePetscOption, but does not set the option if it doesn't make sense for the
251 : * current simulation type, e.g. if \p name is contained within \p dont_add_these_options
252 : */
253 : void setSinglePetscOptionIfAppropriate(const MultiMooseEnum & dont_add_these_options,
254 : const std::string & name,
255 : const std::string & value = "",
256 : FEProblemBase * const problem = nullptr);
257 :
258 : void addPetscOptionsFromCommandline();
259 :
260 : /**
261 : * Setup which side we want to apply preconditioner
262 : */
263 : void petscSetDefaultPCSide(FEProblemBase & problem, KSP ksp);
264 :
265 : /**
266 : * Set norm type
267 : */
268 : void petscSetDefaultKSPNormType(FEProblemBase & problem, KSP ksp);
269 :
270 : /**
271 : * This method takes an adjacency matrix, and a desired number of colors and applies
272 : * a graph coloring algorithm to produce a coloring. The coloring is returned as a vector
273 : * of unsigned integers indicating which color or group each vextex in the adjacency matrix
274 : * belongs to.
275 : */
276 : void colorAdjacencyMatrix(PetscScalar * adjacency_matrix,
277 : unsigned int size,
278 : unsigned int colors,
279 : std::vector<unsigned int> & vertex_colors,
280 : const char * coloring_algorithm);
281 :
282 : /**
283 : * Function to ensure that a particular petsc option is not added to the PetscOptions
284 : * storage object to be later set unless explicitly specified in input or on the command line.
285 : */
286 : void dontAddPetscFlag(const std::string & flag, PetscOptions & petsc_options);
287 :
288 : /**
289 : * Function to ensure that -snes_converged_reason is not added to the PetscOptions storage
290 : * object to be later set unless explicitly specified in input or on the command line.
291 : */
292 : void dontAddNonlinearConvergedReason(FEProblemBase & fe_problem);
293 :
294 : /**
295 : * Function to ensure that -ksp_converged_reason is not added to the PetscOptions storage
296 : * object to be later set unless explicitly specified in input or on the command line.
297 : */
298 : void dontAddLinearConvergedReason(FEProblemBase & fe_problem);
299 :
300 : /**
301 : * Function to ensure that common KSP options are not added to the PetscOptions storage
302 : * object to be later set unless explicitly specified in input or on the command line.
303 : */
304 : void dontAddCommonKSPOptions(FEProblemBase & fe_problem);
305 :
306 : /**
307 : * Function to ensure that common SNES options are not added to the PetscOptions storage
308 : * object to be later set unless explicitly specified in input or on the command line.
309 : */
310 : void dontAddCommonSNESOptions(FEProblemBase & fe_problem);
311 :
312 : /**
313 : * Create a matrix from a binary file. Note that the returned libMesh matrix wrapper will not
314 : * destroy the created matrix on destruction. \p petsc_mat must be destroyed manually via \p
315 : * MatDestroy
316 : * @param mat_number_to_load A binary file may contain multiple writes of a matrix. This parameter
317 : * can be used to load a particular matrix from the binary file. By default we load the
318 : * first written matrix
319 : */
320 : std::unique_ptr<PetscMatrix<Number>>
321 : createMatrixFromFile(const libMesh::Parallel::Communicator & comm,
322 : Mat & petsc_mat,
323 : const std::string & binary_mat_file,
324 : unsigned int mat_number_to_load = 1);
325 :
326 : #define SNESGETLINESEARCH SNESGetLineSearch
327 : }
328 : }
|
