-
Notifications
You must be signed in to change notification settings - Fork 231
/
parameters.cc
1769 lines (1623 loc) · 109 KB
/
parameters.cc
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/*
Copyright (C) 2011 - 2017 by the authors of the ASPECT code.
This file is part of ASPECT.
ASPECT is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.
ASPECT is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with ASPECT; see the file LICENSE. If not see
<http://www.gnu.org/licenses/>.
*/
#include <aspect/simulator.h>
#include <aspect/global.h>
#include <aspect/utilities.h>
#include <aspect/melt.h>
#include <aspect/free_surface.h>
#include <deal.II/base/parameter_handler.h>
#include <sys/stat.h>
#include <stdlib.h>
#include <boost/lexical_cast.hpp>
namespace aspect
{
template <int dim>
Parameters<dim>::Parameters (ParameterHandler &prm,
MPI_Comm mpi_communicator)
{
parse_parameters (prm, mpi_communicator);
}
template <int dim>
void
Parameters<dim>::
declare_parameters (ParameterHandler &prm)
{
prm.declare_entry ("Dimension", "2",
Patterns::Integer (2,4),
"The number of space dimensions you want to run this program in. "
"ASPECT can run in 2 and 3 space dimensions.");
prm.declare_entry ("Additional shared libraries", "",
Patterns::List (Patterns::FileName()),
"A list of names of additional shared libraries that should be loaded "
"upon starting up the program. The names of these files can contain absolute "
"or relative paths (relative to the directory in which you call ASPECT). "
"In fact, file names that are do not contain any directory "
"information (i.e., only the name of a file such as <myplugin.so> "
"will not be found if they are not located in one of the directories "
"listed in the \\texttt{LD_LIBRARY_PATH} environment variable. In order "
"to load a library in the current directory, use <./myplugin.so> "
"instead."
"\n\n"
"The typical use of this parameter is so that you can implement "
"additional plugins in your own directories, rather than in the ASPECT "
"source directories. You can then simply compile these plugins into a "
"shared library without having to re-compile all of ASPECT. See the "
"section of the manual discussing writing extensions for more "
"information on how to compile additional files into a shared "
"library.");
prm.declare_entry ("Resume computation", "false",
Patterns::Selection ("true|false|auto"),
"A flag indicating whether the computation should be resumed from "
"a previously saved state (if true) or start from scratch (if false). "
"If auto is selected, models will be resumed if there is an existing "
"checkpoint file, otherwise started from scratch.");
prm.declare_entry ("Max nonlinear iterations", "10",
Patterns::Integer (0),
"The maximal number of nonlinear iterations to be performed.");
prm.declare_entry ("Max nonlinear iterations in pre-refinement", boost::lexical_cast<std::string>(std::numeric_limits<int>::max()),
Patterns::Integer (0),
"The maximal number of nonlinear iterations to be performed in the pre-refinement "
"steps. This does not include the last refinement step before moving to timestep 1. "
"When this parameter has a larger value than max nonlinear iterations, the latter is used.");
prm.declare_entry ("Start time", "0",
Patterns::Double (),
"The start time of the simulation. Units: Years if the "
"'Use years in output instead of seconds' parameter is set; "
"seconds otherwise.");
prm.declare_entry ("Timing output frequency", "100",
Patterns::Integer(0),
"How frequently in timesteps to output timing information. This is "
"generally adjusted only for debugging and timing purposes. If the "
"value is set to zero it will also output timing information at the "
"initiation timesteps.");
prm.declare_entry ("Use years in output instead of seconds", "true",
Patterns::Bool (),
"When computing results for mantle convection simulations, "
"it is often difficult to judge the order of magnitude of results "
"when they are stated in MKS units involving seconds. Rather, "
"some kinds of results such as velocities are often stated in "
"terms of meters per year (or, sometimes, centimeters per year). "
"On the other hand, for non-dimensional computations, one wants "
"results in their natural unit system as used inside the code. "
"If this flag is set to `true' conversion to years happens; if "
"it is `false', no such conversion happens. Note that when `true', "
"some input such as prescribed velocities should also use years "
"instead of seconds.");
prm.declare_entry ("CFL number", "1.0",
Patterns::Double (0),
"In computations, the time step $k$ is chosen according to "
"$k = c \\min_K \\frac {h_K} {\\|u\\|_{\\infty,K} p_T}$ where $h_K$ is the "
"diameter of cell $K$, and the denominator is the maximal magnitude "
"of the velocity on cell $K$ times the polynomial degree $p_T$ of the "
"temperature discretization. The dimensionless constant $c$ is called the "
"CFL number in this program. For time discretizations that have explicit "
"components, $c$ must be less than a constant that depends on the "
"details of the time discretization and that is no larger than one. "
"On the other hand, for implicit discretizations such as the one chosen "
"here, one can choose the time step as large as one wants (in particular, "
"one can choose $c>1$) though a CFL number significantly larger than "
"one will yield rather diffusive solutions. Units: None.");
prm.declare_entry ("Maximum time step",
/* boost::lexical_cast<std::string>(std::numeric_limits<double>::max() /
year_in_seconds) = */ "5.69e+300",
Patterns::Double (0),
"Set a maximum time step size for the solver to use. Generally the time step "
"based on the CFL number should be sufficient, but for complicated models "
"or benchmarking it may be useful to limit the time step to some value. "
"The default value is a value so that when converted from years into seconds "
"it equals the largest number representable by a floating "
"point number, implying an unlimited time step."
"Units: Years or seconds, depending on the ``Use years "
"in output instead of seconds'' parameter.");
prm.declare_entry ("Use conduction timestep", "false",
Patterns::Bool (),
"Mantle convection simulations are often focused on convection "
"dominated systems. However, these codes can also be used to "
"investigate systems where heat conduction plays a dominant role. "
"This parameter indicates whether the simulator should also use "
"heat conduction in determining the length of each time step.");
prm.declare_entry ("Nonlinear solver scheme", "IMPES",
Patterns::Selection ("IMPES|iterated IMPES|iterated Stokes|Newton Stokes|Stokes only|Advection only"),
"The kind of scheme used to resolve the nonlinearity in the system. "
"'IMPES' is the classical IMplicit Pressure Explicit Saturation scheme "
"in which ones solves the temperatures and Stokes equations exactly "
"once per time step, one after the other. The `iterated IMPES' scheme "
"iterates this decoupled approach by alternating the solution of the "
"temperature and Stokes systems. The `iterated Stokes' scheme solves "
"the temperature equation once at the beginning of each time step "
"and then iterates out the solution of the Stokes equation. The 'Stokes only' "
"scheme only solves the Stokes system and ignores compositions and the "
"temperature equation (careful, the material model must not depend on "
"the temperature; mostly useful for Stokes benchmarks). The 'Advection only' "
"scheme only solves the temperature and other advection systems and instead "
"of solving for the Stokes system, a prescribed velocity and pressure is "
"used.");
prm.declare_entry ("Nonlinear solver tolerance", "1e-5",
Patterns::Double(0,1),
"A relative tolerance up to which the nonlinear solver "
"will iterate. This parameter is only relevant if "
"Nonlinear solver scheme is set to `iterated Stokes' or "
"`iterated IMPES'.");
prm.declare_entry ("Pressure normalization", "surface",
Patterns::Selection ("surface|volume|no"),
"If and how to normalize the pressure after the solution step. "
"This is necessary because depending on boundary conditions, "
"in many cases the pressure is only determined by the model "
"up to a constant. On the other hand, we often would like to "
"have a well-determined pressure, for example for "
"table lookups of material properties in models "
"or for comparing solutions. If the given value is `surface', then "
"normalization at the end of each time steps adds a constant value "
"to the pressure in such a way that the average pressure at the surface "
"of the domain is what is set in the `Surface pressure' parameter; "
"the surface of the domain is determined by asking "
"the geometry model whether a particular face of the geometry has a zero "
"or small `depth'. If the value of this parameter is `volume' then the "
"pressure is normalized so that the domain average is zero. If `no' is "
"given, the no pressure normalization is performed.");
prm.declare_entry ("Surface pressure", "0",
Patterns::Double(),
"The value the pressure is normalized to in each time step when "
"`Pressure normalization' is set to `surface' with default value 0. "
"This setting is ignored in all other cases."
"\n\n"
"The mathematical equations that describe thermal convection "
"only determine the pressure up to an arbitrary constant. On "
"the other hand, for comparison and for looking up material "
"parameters it is important that the pressure be normalized "
"somehow. We do this by enforcing a particular average pressure "
"value at the surface of the domain, where the geometry model "
"determines where the surface is. This parameter describes what "
"this average surface pressure value is supposed to be. By "
"default, it is set to zero, but one may want to choose a "
"different value for example for simulating only the volume "
"of the mantle below the lithosphere, in which case the surface "
"pressure should be the lithostatic pressure at the bottom "
"of the lithosphere."
"\n\n"
"For more information, see the section in the manual that discusses "
"the general mathematical model.");
prm.declare_entry ("Adiabatic surface temperature", "0",
Patterns::Double(),
"In order to make the problem in the first time step easier to "
"solve, we need a reasonable guess for the temperature and pressure. "
"To obtain it, we use an adiabatic pressure and temperature field. "
"This parameter describes what the `adiabatic' temperature would "
"be at the surface of the domain (i.e. at depth zero). Note "
"that this value need not coincide with the boundary condition "
"posed at this point. Rather, the boundary condition may differ "
"significantly from the adiabatic value, and then typically "
"induce a thermal boundary layer."
"\n\n"
"For more information, see the section in the manual that discusses "
"the general mathematical model.");
prm.declare_entry ("Output directory", "output",
Patterns::DirectoryName(),
"The name of the directory into which all output files should be "
"placed. This may be an absolute or a relative path.");
prm.declare_entry ("Use direct solver for Stokes system", "false",
Patterns::Bool(),
"If set to true the linear system for the Stokes equation will "
"be solved using Trilinos klu, otherwise an iterative Schur "
"complement solver is used. The direct solver is only efficient "
"for small problems.");
prm.declare_entry ("Linear solver tolerance", "1e-7",
Patterns::Double(0,1),
"A relative tolerance up to which the linear Stokes systems in each "
"time or nonlinear step should be solved. The absolute tolerance will "
"then be $\\| M x_0 - F \\| \\cdot \\text{tol}$, where $x_0 = (0,p_0)$ "
"is the initial guess of the pressure, $M$ is the system matrix, "
"F is the right-hand side, and tol is the parameter specified here. "
"We include the initial guess of the pressure "
"to remove the dependency of the tolerance on the static pressure. "
"A given tolerance value of 1 would "
"mean that a zero solution vector is an acceptable solution "
"since in that case the norm of the residual of the linear "
"system equals the norm of the right hand side. A given "
"tolerance of 0 would mean that the linear system has to be "
"solved exactly, since this is the only way to obtain "
"a zero residual."
"\n\n"
"In practice, you should choose the value of this parameter "
"to be so that if you make it smaller the results of your "
"simulation do not change any more (qualitatively) whereas "
"if you make it larger, they do. For most cases, the default "
"value should be sufficient. In fact, a tolerance of 1e-4 "
"might be accurate enough.");
prm.declare_entry ("Linear solver A block tolerance", "1e-2",
Patterns::Double(0,1),
"A relative tolerance up to which the approximate inverse of the $A$ block "
"of the Stokes system is computed. This approximate $A$ is used in the "
"preconditioning used in the GMRES solver. The exact definition of this "
"block preconditioner for the Stokes equation can be found in "
"\\cite{KHB12}.");
prm.declare_entry ("Linear solver S block tolerance", "1e-6",
Patterns::Double(0,1),
"A relative tolerance up to which the approximate inverse of the $S$ block "
"(i.e., the Schur complement matrix $S = BA^{-1}B^{T}$) of the Stokes "
"system is computed. This approximate inverse of the $S$ block is used "
"in the preconditioning used in the GMRES solver. The exact definition of "
"this block preconditioner for the Stokes equation can be found in "
"\\cite{KHB12}.");
prm.declare_entry ("Number of cheap Stokes solver steps", "200",
Patterns::Integer(0),
"As explained in the paper that describes ASPECT (Kronbichler, Heister, and Bangerth, "
"2012, see \\cite{KHB12}) we first try to solve the Stokes system in every "
"time step using a GMRES iteration with a poor but cheap "
"preconditioner. By default, we try whether we can converge the GMRES "
"solver in 200 such iterations before deciding that we need a better "
"preconditioner. This is sufficient for simple problems with variable "
"viscosity and we never need the second phase with the more expensive "
"preconditioner. On the other hand, for more complex problems, and in "
"particular for problems with strongly nonlinear viscosity, the 200 "
"cheap iterations don't actually do very much good and one might skip "
"this part right away. In that case, this parameter can be set to "
"zero, i.e., we immediately start with the better but more expensive "
"preconditioner.");
prm.declare_entry ("Maximum number of expensive Stokes solver steps", "1000",
Patterns::Integer(0),
"This sets the maximum number of iterations used in the expensive Stokes solver. "
"If this value is set too low for the size of the problem, the Stokes solver will "
"not converge and return an error message pointing out that the user didn't allow "
"a sufficiently large number of iterations for the iterative solver to converge.");
prm.declare_entry ("Temperature solver tolerance", "1e-12",
Patterns::Double(0,1),
"The relative tolerance up to which the linear system for "
"the temperature system gets solved. See `linear solver "
"tolerance' for more details.");
prm.declare_entry ("Composition solver tolerance", "1e-12",
Patterns::Double(0,1),
"The relative tolerance up to which the linear system for "
"the composition system gets solved. See `linear solver "
"tolerance' for more details.");
prm.declare_entry ("Use operator splitting", "false",
Patterns::Bool(),
"If set to true, the advection and reactions of compositional fields and "
"temperature are solved separately, and can use different time steps. Note that "
"this will only work if the material/heating model fills the reaction\\_rates/"
"heating\\_reaction\\_rates structures. Operator splitting can be used with any "
"existing solver schemes that solve the temperature/composition equations.");
prm.enter_subsection ("Solver parameters");
{
prm.enter_subsection ("Newton solver parameters");
{
prm.declare_entry ("Nonlinear Newton solver switch tolerance", "1e-5",
Patterns::Double(0,1),
"A relative tolerance with respect to the residual of the first "
"iteration, up to which the nonlinear Picard solver will iterate, "
"before changing to the newton solver.");
prm.declare_entry ("Max pre-Newton nonlinear iterations", "10",
Patterns::Integer (0),
"The maximum number of Picard nonlinear iterations to be performed "
"before switching to Newton iterations.");
prm.declare_entry ("Max Newton line search iterations", "5",
Patterns::Integer (0),
"The maximum number of line search iterations allowed. If the "
"criterion is not reached after this iteration, we apply the scaled "
"increment to the solution and continue.");
prm.declare_entry ("Use Newton residual scaling method", "false",
Patterns::Bool (),
"This method allows to slowly introduce the derivatives based on the improvement "
"of the residual. If set to false, the scaling factor for the Newton derivatives "
"is set to one immediately when switching on the Newton solver.");
prm.declare_entry ("Maximum linear Stokes solver tolerance", "0.9",
Patterns::Double (0,1),
"When the linear Stokes solver tolerance is dynamically chosen, this defines "
"the most loose tolerance allowed.");
prm.declare_entry ("Use Newton stabilization preconditioner", "SPD",
Patterns::Selection ("SPD|PD|symmetric|none"),
"TODO");
prm.declare_entry ("Use Newton stabilization A block", "SPD",
Patterns::Selection ("SPD|PD|symmetric|none"),
"TODO");
prm.declare_entry ("Use Newton failsafe", "false",
Patterns::Bool (),
"Switches on SPD stabilization when solver fails.");
}
prm.leave_subsection ();
prm.enter_subsection ("AMG parameters");
{
prm.declare_entry ("AMG smoother type", "Chebyshev",
Patterns::Selection ("Chebyshev|symmetric Gauss-Seidel"),
"This parameter sets the type of smoother for the AMG. "
"The default is strongly recommended for any normal runs "
"with ASPECT. There are some indications that the symmetric "
"Gaus-Seidel might be better and more stable for the Newton "
"solver. For extensive benchmarking of various settings of the "
"AMG parameters in this secton for the Stokes problem and others, "
"see https://github.com/geodynamics/aspect/pull/234.");
prm.declare_entry ("AMG smoother sweeps", "2",
Patterns::Integer(0),
"Determines how many sweeps of the smoother should be performed. When the flag elliptic "
"is set to true, (which is true for ASPECT), the polynomial degree of "
"the Chebyshev smoother is set to this value. The term sweeps refers to the number of "
"matrix-vector products performed in the Chebyshev case. In the non-elliptic case, "
"this parameter sets the number of SSOR relaxation sweeps for post-smoothing to be performed. "
"The default is strongly recommended. There are indications that for the Newton solver a different "
"value might be better. For extensive benchmarking of various settings of the "
"AMG parameters in this secton for the Stokes problem and others, "
"see https://github.com/geodynamics/aspect/pull/234.");
prm.declare_entry ("AMG aggregation threshold", "0.001",
Patterns::Double(0,1),
"This threshold tells the AMG setup how the coarsening should be performed. "
"In the AMG used by ML, all points that strongly couple with the tentative coarse-level "
"point form one aggregate. The term strong coupling is controlled by the variable "
"aggregation\\_threshold, meaning that all elements that are not smaller than "
"aggregation\\_threshold times the diagonal element do couple strongly. "
"The default is strongly recommended. There are indications that for the Newton solver a different "
"value might be better. For extensive benchmarking of various settings of the "
"AMG parameters in this secton for the Stokes problem and others, "
"see https://github.com/geodynamics/aspect/pull/234.");
prm.declare_entry ("AMG output details", "false",
Patterns::Bool(),
"Turns on extra information on the AMG solver. Note that this will generate much more output.");
}
prm.leave_subsection ();
prm.enter_subsection ("Operator splitting parameters");
{
prm.declare_entry ("Reaction time step", "1000.0",
Patterns::Double (0),
"Set a time step size for computing reactions of compositional fields and the "
"temperature field in case operator splitting is used. This is only used "
"when the nonlinear solver scheme ``operator splitting'' is selected. "
"The reaction time step must be greater than 0. "
"If you want to prescribe the reaction time step only as a relative value "
"compared to the advection time step as opposed to as an absolute value, you "
"should use the parameter ``Reaction time steps per advection step'' and set "
"this parameter to the same (or larger) value as the ``Maximum time step'' "
"(which is 5.69e+300 by default). "
"Units: Years or seconds, depending on the ``Use years "
"in output instead of seconds'' parameter.");
prm.declare_entry ("Reaction time steps per advection step", "0",
Patterns::Integer (0),
"The number of reaction time steps done within one advection time step "
"in case operator splitting is used. This is only used if the nonlinear "
"solver scheme ``operator splitting'' is selected. If set to zero, this "
"parameter is ignored. Otherwise, the reaction time step size is chosen according to "
"this criterion and the ``Reaction time step'', whichever yields the "
"smaller time step. "
"Units: none.");
}
prm.leave_subsection ();
}
prm.leave_subsection ();
prm.enter_subsection("Formulation");
{
prm.declare_entry ("Formulation", "custom",
Patterns::Selection ("isothermal compression|custom|anelastic liquid approximation|Boussinesq approximation"),
"Select a formulation for the basic equations. Different "
"published formulations are available in ASPECT (see the list of "
"possible values for this parameter in the manual for available options). "
"Two ASPECT specific options are\n"
"\\begin{enumerate}\n"
" \\item `isothermal compression': ASPECT's original "
"formulation, using the explicit compressible mass equation, "
"and the full density for the temperature equation.\n"
" \\item `custom': A custom selection of `Mass conservation' and "
"`Temperature equation'.\n"
"\\end{enumerate}\n\n"
"\\note{Warning: The `custom' option is "
"implemented for advanced users that want full control over the "
"equations solved. It is possible to choose inconsistent formulations "
"and no error checking is performed on the consistency of the resulting "
"equations.}\n\n"
"\\note{The `anelastic liquid approximation' option here can also be "
"used to set up the `truncated anelastic liquid approximation' as long as "
"this option is chosen together with a material model that defines a "
"density that depends on temperature and depth and not on the pressure.}");
prm.declare_entry ("Mass conservation", "ask material model",
Patterns::Selection ("incompressible|isothermal compression|hydrostatic compression|"
"reference density profile|implicit reference density profile|"
"ask material model"),
"Possible approximations for the density derivatives in the mass "
"conservation equation. Note that this parameter is only evaluated "
"if `Formulation' is set to `custom'. Other formulations ignore "
"the value of this parameter.");
prm.declare_entry ("Temperature equation", "real density",
Patterns::Selection ("real density|reference density profile"),
"Possible approximations for the density in the temperature equation. "
"Possible approximations are `real density' and `reference density profile'. "
"Note that this parameter is only evaluated "
"if `Formulation' is set to `custom'. Other formulations ignore "
"the value of this parameter.");
}
prm.leave_subsection();
// next declare parameters that pertain to the equations to be
// solved, along with boundary conditions etc. note that at this
// point we do not know yet which geometry model we will use, so
// we do not know which symbolic names will be valid to address individual
// parts of the boundary. we can only work around this by allowing any string
// to indicate a boundary
prm.enter_subsection ("Model settings");
{
prm.declare_entry ("Include melt transport", "false",
Patterns::Bool (),
"Whether to include the transport of melt into the model or not. If this "
"is set to true, two additional pressures (the fluid pressure and the "
"compaction pressure) will be added to the finite element. "
"Including melt transport in the simulation also requires that there is "
"one compositional field that has the name `porosity'. This field will "
"be used for computing the additional pressures and the melt velocity, "
"and has a different advection equation than other compositional fields, "
"as it is effectively advected with the melt velocity.");
prm.declare_entry ("Fixed temperature boundary indicators", "",
Patterns::List (Patterns::Anything()),
"A comma separated list of names denoting those boundaries "
"on which the temperature is fixed and described by the "
"boundary temperature object selected in its own section "
"of this input file. All boundary indicators used by the geometry "
"but not explicitly listed here will end up with no-flux "
"(insulating) boundary conditions."
"\n\n"
"The names of the boundaries listed here can either by "
"numbers (in which case they correspond to the numerical "
"boundary indicators assigned by the geometry object), or they "
"can correspond to any of the symbolic names the geometry object "
"may have provided for each part of the boundary. You may want "
"to compare this with the documentation of the geometry model you "
"use in your model."
"\n\n"
"This parameter only describes which boundaries have a fixed "
"temperature, but not what temperature should hold on these "
"boundaries. The latter piece of information needs to be "
"implemented in a plugin in the BoundaryTemperature "
"group, unless an existing implementation in this group "
"already provides what you want.");
prm.declare_entry ("Fixed composition boundary indicators", "",
Patterns::List (Patterns::Anything()),
"A comma separated list of names denoting those boundaries "
"on which the composition is fixed and described by the "
"boundary composition object selected in its own section "
"of this input file. All boundary indicators used by the geometry "
"but not explicitly listed here will end up with no-flux "
"(insulating) boundary conditions."
"\n\n"
"The names of the boundaries listed here can either by "
"numbers (in which case they correspond to the numerical "
"boundary indicators assigned by the geometry object), or they "
"can correspond to any of the symbolic names the geometry object "
"may have provided for each part of the boundary. You may want "
"to compare this with the documentation of the geometry model you "
"use in your model."
"\n\n"
"This parameter only describes which boundaries have a fixed "
"composition, but not what composition should hold on these "
"boundaries. The latter piece of information needs to be "
"implemented in a plugin in the BoundaryComposition "
"group, unless an existing implementation in this group "
"already provides what you want.");
prm.declare_entry ("Free surface boundary indicators", "",
Patterns::List (Patterns::Anything()),
"A comma separated list of names denoting those boundaries "
"where there is a free surface. Set to nothing to disable all "
"free surface computations."
"\n\n"
"The names of the boundaries listed here can either by "
"numbers (in which case they correspond to the numerical "
"boundary indicators assigned by the geometry object), or they "
"can correspond to any of the symbolic names the geometry object "
"may have provided for each part of the boundary. You may want "
"to compare this with the documentation of the geometry model you "
"use in your model.");
prm.declare_entry ("Prescribed traction boundary indicators", "",
Patterns::Map (Patterns::Anything(),
Patterns::Selection(BoundaryTraction::get_names<dim>())),
"A comma separated list denoting those boundaries "
"on which a traction force is prescribed, i.e., where "
"known external forces act, resulting in an unknown velocity. This is "
"often used to model ``open'' boundaries where we only know the pressure. "
"This pressure then produces a force that is normal to the boundary and "
"proportional to the pressure."
"\n\n"
"The format of valid entries for this parameter is that of a map "
"given as ``key1 [selector]: value1, key2 [selector]: value2, key3: value3, ...'' where "
"each key must be a valid boundary indicator (which is either an "
"integer or the symbolic name the geometry model in use may have "
"provided for this part of the boundary) "
"and each value must be one of the currently implemented boundary "
"traction models. ``selector'' is an optional string given as a subset "
"of the letters `xyz' that allows you to apply the boundary conditions "
"only to the components listed. As an example, '1 y: function' applies "
"the type `function' to the y component on boundary 1. Without a selector "
"it will affect all components of the traction.");
prm.declare_entry ("Remove nullspace", "",
Patterns::MultipleSelection("net rotation|angular momentum|"
"net translation|linear momentum|"
"net x translation|net y translation|net z translation|"
"linear x momentum|linear y momentum|linear z momentum"),
"Choose none, one or several from "
"\n\n"
"\\begin{itemize} \\item net rotation \\item angular momentum \\item net translation "
"\\item linear momentum \\item net x translation \\item net y translation "
"\\item net z translation \\item linear x momentum \\item linear y momentum "
"\\item linear z momentum \\end{itemize}"
"\n\n"
"These are a selection of operations to remove certain parts of the nullspace from "
"the velocity after solving. For some geometries and certain boundary conditions "
"the velocity field is not uniquely determined but contains free translations "
"and/or rotations. Depending on what you specify here, these non-determined "
"modes will be removed from the velocity field at the end of the Stokes solve step.\n"
"\n\n"
"The ``angular momentum'' option removes a rotation such that the net angular momentum "
"is zero. The ``linear * momentum'' options remove translations such that the net "
"momentum in the relevant direction is zero. The ``net rotation'' option removes the "
"net rotation of the domain, and the ``net * translation'' options remove the "
"net translations in the relevant directions. For most problems there should not be a "
"significant difference between the momentum and rotation/translation versions of "
"nullspace removal, although the momentum versions are more physically motivated. "
"They are equivalent for constant density simulations, and approximately equivalent "
"when the density variations are small."
"\n\n"
"Note that while more than one operation can be selected it only makes sense to "
"pick one rotational and one translational operation.");
prm.declare_entry ("Enable additional Stokes RHS", "false",
Patterns::Bool (),
"Whether to ask the material model for additional terms for the right-hand side "
"of the Stokes equation. This feature is likely only used when implementing force "
"vectors for manufactured solution problems and requires filling additional outputs "
"of type AdditionalMaterialOutputsStokesRHS.");
}
prm.leave_subsection ();
prm.enter_subsection ("Mesh refinement");
{
prm.declare_entry ("Initial global refinement", "2",
Patterns::Integer (0),
"The number of global refinement steps performed on "
"the initial coarse mesh, before the problem is first "
"solved there.");
prm.declare_entry ("Initial adaptive refinement", "0",
Patterns::Integer (0),
"The number of adaptive refinement steps performed after "
"initial global refinement but while still within the first "
"time step.");
prm.declare_entry ("Time steps between mesh refinement", "10",
Patterns::Integer (0),
"The number of time steps after which the mesh is to be "
"adapted again based on computed error indicators. If 0 "
"then the mesh will never be changed.");
prm.declare_entry ("Refinement fraction", "0.3",
Patterns::Double(0,1),
"The fraction of cells with the largest error that "
"should be flagged for refinement.");
prm.declare_entry ("Coarsening fraction", "0.05",
Patterns::Double(0,1),
"The fraction of cells with the smallest error that "
"should be flagged for coarsening.");
prm.declare_entry ("Adapt by fraction of cells", "false",
Patterns::Bool(),
"Use fraction of the total number of cells instead of "
"fraction of the total error as the limit for refinement "
"and coarsening.");
prm.declare_entry ("Minimum refinement level", "0",
Patterns::Integer (0),
"The minimum refinement level each cell should have, "
"and that can not be exceeded by coarsening. "
"Should not be higher than the 'Initial global refinement' "
"parameter.");
prm.declare_entry ("Additional refinement times", "",
Patterns::List (Patterns::Double(0)),
"A list of times so that if the end time of a time step "
"is beyond this time, an additional round of mesh refinement "
"is triggered. This is mostly useful to make sure we "
"can get through the initial transient phase of a simulation "
"on a relatively coarse mesh, and then refine again when we "
"are in a time range that we are interested in and where "
"we would like to use a finer mesh. Units: Each element of the "
"list has units years if the "
"'Use years in output instead of seconds' parameter is set; "
"seconds otherwise.");
prm.declare_entry ("Run postprocessors on initial refinement", "false",
Patterns::Bool (),
"Whether or not the postprocessors should be executed after "
"each of the initial adaptive refinement cycles that are run at "
"the start of the simulation.");
}
prm.leave_subsection();
prm.enter_subsection ("Postprocess");
{
prm.declare_entry ("Run postprocessors on nonlinear iterations", "false",
Patterns::Bool (),
"Whether or not the postprocessors should be executed after "
"each of the nonlinear iterations done within one time step. "
"As this is mainly an option for the purposes of debugging, "
"it is not supported when the 'Time between graphical output' "
"is larger than zero, or when the postprocessor is not intended "
"to be run more than once per timestep.");
}
prm.leave_subsection();
prm.enter_subsection ("Checkpointing");
{
prm.declare_entry ("Time between checkpoint", "0",
Patterns::Integer (0),
"The wall time between performing checkpoints. "
"If 0, will use the checkpoint step frequency instead. "
"Units: Seconds.");
prm.declare_entry ("Steps between checkpoint", "0",
Patterns::Integer (0),
"The number of timesteps between performing checkpoints. "
"If 0 and time between checkpoint is not specified, "
"checkpointing will not be performed. "
"Units: None.");
}
prm.leave_subsection ();
prm.enter_subsection ("Discretization");
{
prm.declare_entry ("Stokes velocity polynomial degree", "2",
Patterns::Integer (1),
"The polynomial degree to use for the velocity variables "
"in the Stokes system. The polynomial degree for the pressure "
"variable will then be one less in order to make the velocity/pressure "
"pair conform with the usual LBB (Babuska-Brezzi) condition. In "
"other words, we are using a Taylor-Hood element for the Stokes "
"equations and this parameter indicates the polynomial degree of it. "
"As an example, a value of 2 for this parameter will yield the "
"element $Q_2^d \\times Q_1$ for the $d$ velocity components and the "
"pressure, respectively (unless the `Use locally conservative "
"discretization' parameter is set, which modifies the pressure "
"element). "
"Units: None.");
prm.declare_entry ("Temperature polynomial degree", "2",
Patterns::Integer (1),
"The polynomial degree to use for the temperature variable. "
"As an example, a value of 2 for this parameter will yield "
"either the element $Q_2$ or $DGQ_2$ for the temperature "
"field, depending on whether we use a continuous or "
"discontinuous field. "
"Units: None.");
prm.declare_entry ("Composition polynomial degree", "2",
Patterns::Integer (1),
"The polynomial degree to use for the composition variable(s). "
"As an example, a value of 2 for this parameter will yield "
"either the element $Q_2$ or $DGQ_2$ for the compositional "
"field(s), depending on whether we use continuous or "
"discontinuous field(s). "
"Units: None.");
prm.declare_entry ("Use locally conservative discretization", "false",
Patterns::Bool (),
"Whether to use a Stokes discretization that is locally "
"conservative at the expense of a larger number of degrees "
"of freedom (true), or to go with a cheaper discretization "
"that does not locally conserve mass, although it is "
"globally conservative (false)."
"\n\n"
"When using a locally "
"conservative discretization, the finite element space for "
"the pressure is discontinuous between cells and is the "
"polynomial space $P_ {-q}$ of polynomials of degree $q$ in "
"each variable separately. Here, $q$ is one less than the value "
"given in the parameter ``Stokes velocity polynomial degree''. "
"As a consequence of choosing this "
"element, it can be shown if the medium is considered incompressible "
"that the computed discrete velocity "
"field $\\mathbf u_h$ satisfies the property $\\int_ {\\partial K} \\mathbf u_h "
"\\cdot \\mathbf n = 0$ for every cell $K$, i.e., for each cell inflow and "
"outflow exactly balance each other as one would expect for an "
"incompressible medium. In other words, the velocity field is locally "
"conservative."
"\n\n"
"On the other hand, if this parameter is "
"set to ``false'', then the finite element space is chosen as $Q_q$. "
"This choice does not yield the local conservation property but "
"has the advantage of requiring fewer degrees of freedom. Furthermore, "
"the error is generally smaller with this choice."
"\n\n"
"For an in-depth discussion of these issues and a quantitative evaluation "
"of the different choices, see \\cite {KHB12} .");
prm.declare_entry ("Use discontinuous temperature discretization", "false",
Patterns::Bool (),
"Whether to use a temperature discretization that is discontinuous "
"as opposed to continuous. This then requires the assembly of face terms "
"between cells, and weak imposition of boundary terms for the temperature "
"field via the interior-penalty discontinuous Galerkin method.");
prm.declare_entry ("Use discontinuous composition discretization", "false",
Patterns::Bool (),
"Whether to use a composition discretization that is discontinuous "
"as opposed to continuous. This then requires the assembly of face terms "
"between cells, and weak imposition of boundary terms for the composition "
"field via the discontinuous Galerkin method.");
prm.enter_subsection ("Stabilization parameters");
{
prm.declare_entry ("Use artificial viscosity smoothing", "false",
Patterns::Bool (),
"If set to false, the artificial viscosity of a cell is computed and "
"is computed on every cell separately as discussed in \\cite{KHB12}. "
"If set to true, the maximum of the artificial viscosity in "
"the cell as well as the neighbors of the cell is computed and used "
"instead.");
prm.declare_entry ("alpha", "2",
Patterns::Integer (1, 2),
"The exponent $\\alpha$ in the entropy viscosity stabilization. Valid "
"options are 1 or 2. The recommended setting is 2. (This parameter does "
"not correspond to any variable in the 2012 paper by Kronbichler, "
"Heister and Bangerth that describes ASPECT, see \\cite{KHB12}. "
"Rather, the paper always uses 2 as the exponent in the definition "
"of the entropy, following equation (15) of the paper. The full "
"approach is discussed in \\cite{GPP11}.) Note that this is not the "
"thermal expansion coefficient, also commonly referred to as $\\alpha$."
"Units: None.");
prm.declare_entry ("cR", "0.33",
Patterns::Double (0),
"The $c_R$ factor in the entropy viscosity "
"stabilization. This parameter controls the part of the entropy viscosity "
"that depends on the solution field itself and its residual in addition "
"to the cell diameter and the maximum velocity in the cell. "
"(For historical reasons, the name used here is different "
"from the one used in the 2012 paper by Kronbichler, "
"Heister and Bangerth that describes ASPECT, see \\cite{KHB12}. "
"This parameter corresponds "
"to the factor $\\alpha_E$ in the formulas following equation (15) of "
"the paper. After further experiments, we have also chosen to use a "
"different value than described there.) Units: None.");
prm.declare_entry ("beta", "0.078",
Patterns::Double (0),
"The $\\beta$ factor in the artificial viscosity "
"stabilization. This parameter controls the maximum dissipation of the "
"entropy viscosity, which is the part that only scales with the cell diameter "
"and the maximum velocity in the cell, but does not depend on the solution "
"field itself or its residual. An appropriate value for 2d is 0.078 and "
"0.117 for 3d. (For historical reasons, the name used here is different "
"from the one used in the 2012 paper by Kronbichler, "
"Heister and Bangerth that describes ASPECT, see \\cite{KHB12}. "
"This parameter corresponds "
"to the factor $\\alpha_\\text {max}$ in the formulas following equation (15) of "
"the paper. After further experiments, we have also chosen to use a "
"different value than described there: It can be chosen as stated there for "
"uniformly refined meshes, but it needs to be chosen larger if the mesh has "
"cells that are not squares or cubes.) Units: None.");
prm.declare_entry ("gamma", "0.0",
Patterns::Double (0),
"The strain rate scaling factor in the artificial viscosity "
"stabilization. This parameter determines how much the strain rate (in addition "
"to the velocity) should influence the stabilization. (This parameter does "
"not correspond to any variable in the 2012 paper by Kronbichler, "
"Heister and Bangerth that describes ASPECT, see \\cite{KHB12}. "
"Rather, the paper always uses "
"0, i.e. they specify the maximum dissipation $\\nu_h^\\text{max}$ as "
"$\\nu_h^\\text{max}\\vert_K = \\alpha_\\text{max} h_K \\|\\mathbf u\\|_{\\infty,K}$. "
"Here, we use "
"$\\|\\lvert\\mathbf u\\rvert + \\gamma h_K \\lvert\\varepsilon (\\mathbf u)\\rvert\\|_{\\infty,K}$ "
"instead of $\\|\\mathbf u\\|_{\\infty,K}$. "
"Units: None.");
prm.declare_entry ("Discontinuous penalty", "10",
Patterns::Double (0),
"The value used to penalize discontinuities in the discontinuous Galerkin "
"method. This is used only for the temperature field, and not for the composition "
"field, as pure advection does not use the interior penalty method. This "
"is largely empirically decided -- it must be large enough to ensure "
"the bilinear form is coercive, but not so large as to penalize "
"discontinuity at all costs.");
prm.declare_entry ("Use limiter for discontinuous temperature solution", "false",
Patterns::Bool (),
"Whether to apply the bound preserving limiter as a correction after computing "
"the discontinuous temperature solution. Currently we apply this only to the "
"temperature solution if the 'Global temperature maximum' and "
"'Global temperature minimum' are already defined in the .prm file. "
"This limiter keeps the discontinuous solution in the range given by "
"'Global temperature maximum' and 'Global temperature minimum'.");
prm.declare_entry ("Use limiter for discontinuous composition solution", "false",
Patterns::Bool (),
"Whether to apply the bound preserving limiter as a correction after having "
"the discontinuous composition solution. Currently we apply this only to the "
"compositional solution if the 'Global composition maximum' and "
"'Global composition minimum' are already defined in the .prm file. "
"This limiter keeps the discontinuous solution in the range given by "
"Global composition maximum' and 'Global composition minimum'.");
prm.declare_entry ("Global temperature maximum",
boost::lexical_cast<std::string>(std::numeric_limits<double>::max()),
Patterns::Double (),
"The maximum global temperature value that will be used in the bound preserving "
"limiter for the discontinuous solutions from temperature advection fields.");
prm.declare_entry ("Global temperature minimum",
boost::lexical_cast<std::string>(-std::numeric_limits<double>::max()),
Patterns::Double (),
"The minimum global temperature value that will be used in the bound preserving "
"limiter for the discontinuous solutions from temperature advection fields.");
prm.declare_entry ("Global composition maximum",
boost::lexical_cast<std::string>(std::numeric_limits<double>::max()),
Patterns::List(Patterns::Double ()),
"The maximum global composition values that will be used in the bound preserving "
"limiter for the discontinuous solutions from composition advection fields. "
"The number of the input 'Global composition maximum' values separated by ',' has to be "
"the same as the number of the compositional fields");
prm.declare_entry ("Global composition minimum",
boost::lexical_cast<std::string>(-std::numeric_limits<double>::max()),
Patterns::List(Patterns::Double ()),
"The minimum global composition value that will be used in the bound preserving "
"limiter for the discontinuous solutions from composition advection fields. "
"The number of the input 'Global composition minimum' values separated by ',' has to be "
"the same as the number of the compositional fields");
}
prm.leave_subsection ();
}
prm.leave_subsection ();
prm.enter_subsection ("Compositional fields");
{
prm.declare_entry ("Number of fields", "0",
Patterns::Integer (0),
"The number of fields that will be advected along with the flow field, excluding "
"velocity, pressure and temperature.");
prm.declare_entry ("Names of fields", "",
Patterns::List(Patterns::Anything()),
"A user-defined name for each of the compositional fields requested.");
prm.declare_entry ("Compositional field methods", "",
Patterns::List (Patterns::Selection("field|particles|static")),
"A comma separated list denoting the solution method of each "
"compositional field. Each entry of the list must be "
"one of the currently implemented field types: "
"``field'', ``particles'', or ``static''."
"\n\n"
"These choices correspond to the following methods by which "
"compositional fields gain their values:"
"\\begin{itemize}"
"\\item ``field'': If a compositional field is marked with this "
"method, then its values are computed in each time step by "
"advecting along the values of the previous time step using the "
"velocity field, and applying reaction rates to it. In other words, "
"this corresponds to the usual notion of a composition field as "
"mentioned in Section~\\ref{sec:compositional}. "
"\n"
"\\item ``particles'': If a compositional field is marked with "
"this method, then its values are obtained in each time step "
"by interpolating the corresponding properties from the "
"particles located on each cell. The time evolution therefore "
"happens because particles move along with the velocity field, "
"and particle properties can react with each other as well. "
"See Section~\\ref{sec:particles} for more information about "
"how particles behave."
"\n"
"\\item ``static'': If a compositional field is marked "
"this way, then it does not evolve at all. Its values are "
"simply set to the initial conditions, and will then "
"never change."
"\\end{itemize}");
prm.declare_entry ("Mapped particle properties", "",
Patterns::Map (Patterns::Anything(),
Patterns::Anything()),
"A comma separated list denoting the particle properties "
"that will be projected to those compositional fields that "
"are of the ``particles'' field type."
"\n\n"
"The format of valid entries for this parameter is that of a map "
"given as ``key1: value1, key2: value2 [component2], key3: value3 [component4], "
"...'' where each key must be a valid field name of the "
"``particles'' type, and each value must be one of the currently "
"selected particle properties. Component is a component index of "
"the particle property that is 0 by default, but can be set up to "
"n-1, where n is the number of vector components of this particle "
"property. The component indicator only needs to be "
"set if not the first component of the particle property should be "
"mapped (e.g. the $y$-component of the velocity at the particle positions).");
prm.declare_entry ("List of normalized fields", "",
Patterns::List (Patterns::Integer(0)),
"A list of integers smaller than or equal to the number of "
"compositional fields. All compositional fields in this "
"list will be normalized before the first timestep. "
"The normalization is implemented in the following way: "
"First, the sum of the fields to be normalized is calculated "
"at every point and the global maximum is determined. "
"Second, the compositional fields to be normalized are "
"divided by this maximum.");
}
prm.leave_subsection ();
// Finally declare a couple of parameters related how we should
// evaluate the material models when assembling the matrix and
// preconditioner
prm.enter_subsection ("Material model");
{
prm.declare_entry ("Material averaging", "none",
Patterns::Selection(MaterialModel::MaterialAveraging::
get_averaging_operation_names()),
"Whether or not (and in the first case, how) to do any averaging of "
"material model output data when constructing the linear systems "
"for velocity/pressure, temperature, and compositions in each "
"time step, as well as their corresponding preconditioners."
"\n\n"
"Possible choices: " + MaterialModel::MaterialAveraging::
get_averaging_operation_names()
+
"\n\n"
"The process of averaging, and where it may be used, is "
"discussed in more detail in "
"Section~\\ref{sec:sinker-with-averaging}."
"\n\n"
"More averaging schemes are available in the averaging material "
"model. This material model is a ``compositing material model'' "
"which can be used in combination with other material models.");
}
prm.leave_subsection ();
// also declare the parameters that the FreeSurfaceHandler needs