SpECTRE
v2021.02.08
Documentation
Introduction
Releases
Installation
User Tutorials
Dev Guide
Code of Conduct
Contributing Guide
Code Reference
Topics
Namespaces
Files
Bibliography
View on GitHub
docs
GroupDefs.hpp
Go to the documentation of this file.
1
// Distributed under the MIT License.
2
// See LICENSE.txt for details.
3
4
/// \file
5
/// Defines all group definitions
6
7
#pragma once
8
9
/*!
10
* \defgroup ActionsGroup Actions
11
* \brief A collection of steps used in algorithms.
12
*/
13
14
/*!
15
* \defgroup AnalyticDataGroup Analytic Data
16
* \brief Analytic data used to specify (for example) initial data to the
17
* equations implemented in \ref EvolutionSystemsGroup.
18
*/
19
20
/*!
21
* \defgroup AnalyticSolutionsGroup Analytic Solutions
22
* \brief Analytic solutions to the equations implemented in \ref
23
* EvolutionSystemsGroup and \ref EllipticSystemsGroup.
24
*/
25
26
/*!
27
* \defgroup BoundaryConditionsGroup Boundary Conditions
28
* A collection of boundary conditions used for evolutions.
29
*/
30
31
/*!
32
* \defgroup CharmExtensionsGroup Charm++ Extensions
33
* \brief Classes and functions used to make Charm++ easier and safer to use.
34
*/
35
36
/*!
37
* \defgroup ComputationalDomainGroup Computational Domain
38
* \brief The building blocks used to describe the computational domain.
39
*
40
* ### Description
41
* The VolumeDim-dimensional computational Domain is constructed from a set of
42
* non-overlapping Block%s. Each Block is a distorted VolumeDim-dimensional
43
* hypercube. Each codimension-1 boundary of a Block is either part of the
44
* external boundary of the computational domain, or is identical to a boundary
45
* of one other Block. Each Block is subdivided into one or more Element%s
46
* that may be changed dynamically if AMR is enabled.
47
*/
48
49
/*!
50
* \defgroup ConservativeGroup Conservative System Evolution
51
* \brief Contains generic functions used for evolving conservative
52
* systems.
53
*/
54
55
/*!
56
* \defgroup ConstantExpressionsGroup Constant Expressions
57
* \brief Contains an assortment of constexpr functions
58
*
59
* ### Description
60
* Contains an assortment of constexpr functions that are useful for
61
* metaprogramming, or efficient mathematical computations, such as
62
* exponentiating to an integer power, where the power is known at compile
63
* time.
64
*/
65
66
/*!
67
* \defgroup ControlSystemGroup Control System
68
* \brief Contains control system elements
69
*
70
* The control system manages the time-dependent mapping between frames, such as
71
* the fixed computational frame (grid frame) and the inertial frame. The
72
* time-dependent parameters of the mapping are adjusted by a feedback control
73
* system in order to follow the dynamical evolution of objects such as horizons
74
* of black holes or surfaces of neutron stars. For example, in binary black
75
* hole simulations the map is typically a composition of maps that include
76
* translation, rotation, scaling, shape, etc.
77
* Each map under the governance of the control system has an associated
78
* time-dependent map parameter \f$\lambda(t)\f$ that is a piecewise Nth order
79
* polynomial. At discrete times (called reset times), the control system resets
80
* the Nth time derivative of \f$\lambda(t)\f$ to a new constant value, in order
81
* to minimize an error function \f$Q(t)\f$ that is specific to each map. At
82
* each reset time, the Nth derivative of \f$\lambda(t)\f$ is set to a function
83
* \f$U(t)\f$, called the control signal, that is determined by \f$Q(t)\f$ and
84
* its time derivatives and time integral. Note that \f$\lambda(t)\f$,
85
* \f$U(t)\f$, and \f$Q(t)\f$ can be vectors.
86
*
87
* The key components of the control system are:
88
* - FunctionsOfTime: each map has an associated FunctionOfTime that represents
89
* the map parameter \f$\lambda(t)\f$ and relevant time derivatives.
90
* - ControlError: each map has an associated ControlError that computes
91
* the error, \f$Q(t)\f$. Note that for each map, \f$Q(t)\f$ is defined to
92
* follow the convention that \f$dQ = -d \lambda\f$ as \f$Q \rightarrow 0\f$.
93
* - Averager: an averager can be used to average out the noise in the 'raw'
94
* \f$Q(t)\f$ returned by the ControlError.
95
* - Controller: the map controller computes the control signal \f$U(t)\f$ from
96
* \f$Q(t)\f$ and its time integral and time derivatives.
97
* The control is accomplished by setting the Nth derivative of
98
* \f$\lambda(t)\f$ to \f$U(t)\f$. Two common controllers are PID
99
* (proportional/integral/derivative)
100
* \f[U(t) = a_{0}\int_{t_{0}}^{t} Q(t') dt'+a_{1}Q(t)+a_{2}\frac{dQ}{dt}\f]
101
* or
102
* PND (proportional/N derivatives)
103
* \f[ U(t) = \sum_{k=0}^{N} a_{k} \frac{d^kQ}{dt^k} \f]
104
* The coefficients \f$ a_{k} \f$ in the computation of \f$U(t)\f$ are chosen
105
* at each time such that the error \f$Q(t)\f$ will be critically damped
106
* on a timescale of \f$\tau\f$ (the damping time),
107
* i.e. \f$Q(t) \propto e^{-t/\tau}\f$.
108
* - TimescaleTuner: each map has a TimescaleTuner that dynamically adjusts
109
* the damping timescale \f$\tau\f$ appropriately to keep the error \f$Q(t)\f$
110
* within some specified error bounds. Note that the reset time interval,
111
* \f$\Delta t\f$, is a constant fraction of this damping timescale,
112
* i.e. \f$\Delta t = \alpha \tau\f$ (empirically, we have found
113
* \f$\alpha=0.3\f$ to be a good choice).
114
*
115
*
116
* For additional details describing our control system approach, see
117
* \cite Hemberger2012jz.
118
*/
119
120
/*!
121
* \defgroup CoordinateMapsGroup Coordinate Maps
122
* \brief Functions for mapping coordinates between different frames
123
*
124
* Coordinate maps provide the maps themselves, the inverse maps, along
125
* with the Jacobian and inverse Jacobian of the maps.
126
*/
127
128
/*!
129
* \defgroup CoordMapsTimeDependentGroup Coordinate Maps, Time-dependent
130
* \brief Functions for mapping time-dependent coordinates between different
131
* frames
132
*
133
* Coordinate maps provide the maps themselves, the inverse maps, the Jacobian
134
* and inverse Jacobian of the maps, and the frame velocity (time derivative of
135
* the map)
136
*/
137
138
/*!
139
* \defgroup DataBoxGroup DataBox
140
* \brief Documentation, functions, metafunctions, and classes necessary for
141
* using DataBox
142
*
143
* DataBox is a heterogeneous compile-time associative container with lazy
144
* evaluation of functions. DataBox can not only store data, but can also store
145
* functions that depend on other data inside the DataBox. The functions will be
146
* evaluated when the data they return is requested. The result is cached, and
147
* if a dependency of the function is modified the cache is invalidated.
148
*
149
* #### Simple and Compute Tags and Their Items
150
*
151
* The compile-time keys are `struct`s called tags, while the values are called
152
* items. Tags are quite minimal, containing only the information necessary to
153
* store the data and evaluate functions. There are two different types of tags
154
* that a DataBox can hold: simple tags and compute tags. Simple tags are for
155
* data that is inserted into the DataBox at the time of creation, while compute
156
* tags are for data that will be computed from a function when the compute item
157
* is retrieved. If a compute item is never retrieved from the DataBox then it
158
* is never evaluated.
159
*
160
* Simple tags must have a member type alias `type` that is the type of the data
161
* to be stored and a `static std::string name()` method that returns the name
162
* of the tag. Simple tags must inherit from `db::SimpleTag`.
163
*
164
* Compute tags must also have a `static std::string name()` method that returns
165
* the name of the tag, but they cannot have a `type` type alias. Instead,
166
* compute tags must have a static member function or static member function
167
* pointer named `function`. `function` can be a function template if necessary.
168
* The `function` must take all its arguments by `const` reference. The
169
* arguments to the function are retrieved using tags from the DataBox that the
170
* compute tag is in. The tags for the arguments are set in the member type
171
* alias `argument_tags`, which must be a `tmpl::list` of the tags corresponding
172
* to each argument. Note that the order of the tags in the `argument_list` is
173
* the order that they will be passed to the function. Compute tags must inherit
174
* from `db::ComputeTag`.
175
*
176
* Here is an example of a simple tag:
177
*
178
* \snippet Test_DataBox.cpp databox_tag_example
179
*
180
* and an example of a compute tag with a function pointer:
181
*
182
* \snippet Test_DataBox.cpp databox_mutating_compute_item_tag
183
*
184
* If the compute item's tag is inline then the compute item is of the form:
185
*
186
* \snippet Test_DataBox.cpp compute_item_tag_function
187
*
188
* Compute tags can also have their functions be overloaded on the type of its
189
* arguments:
190
*
191
* \snippet Test_DataBox.cpp overload_compute_tag_type
192
*
193
* or be overloaded on the number of arguments:
194
*
195
* \snippet Test_DataBox.cpp overload_compute_tag_number_of_args
196
*
197
* Compute tag function templates are implemented as follows:
198
*
199
* \snippet Test_DataBox.cpp overload_compute_tag_template
200
*
201
* Finally, overloading, function templates, and variadic functions can be
202
* combined to produce extremely generic compute tags. The below compute tag
203
* takes as template parameters a parameter pack of integers, which is used to
204
* specify several of the arguments. The function is overloaded for the single
205
* argument case, and a variadic function template is provided for the multiple
206
* arguments case. Note that in practice few compute tags will be this complex.
207
*
208
* \snippet Test_BaseTags.cpp compute_template_base_tags
209
*
210
* #### Subitems and Prefix Tags
211
*
212
* A simple or compute tag might also hold a collection of data, such as a
213
* container of `Tensor`s. In many cases you will want to be able to retrieve
214
* individual elements of the collection from the DataBox without having to
215
* first retrieve the collection. The infrastructure that allows for this is
216
* called *Subitems*. The subitems of the parent tag must refer to a subset of
217
* the data inside the parent tag, e.g. one `Tensor` in the collection. If the
218
* parent tag is `Parent` and the subitems tags are `Sub<0>, Sub<1>`, then when
219
* `Parent` is added to the DataBox, so are `Sub<0>` and `Sub<1>`. This means
220
* the retrieval mechanisms described below will work on `Parent`, `Sub<0>`, and
221
* `Sub<1>`.
222
*
223
* Subitems specify requirements on the tags they act on. For example, there
224
* could be a requirement that all tags with a certain type are to be treated as
225
* a Subitems. Let's say that the `Parent` tag holds a `Variables`, and
226
* `Variables` can be used with the Subitems infrastructure to add the nested
227
* `Tensor`s. Then all tags that hold a `Variables` will have their subitems
228
* added into the DataBox. To add a new type as a subitem the `db::Subitems`
229
* struct must be specialized. See the documentation of `db::Subitems` for more
230
* details.
231
*
232
* The DataBox also supports *prefix tags*, which are commonly used for items
233
* that are related to a different item by some operation. Specifically, say
234
* you have a tag `MyTensor` and you want to also have the time derivative of
235
* `MyTensor`, then you can use the prefix tag `dt` to get `dt<MyTensor>`. The
236
* benefit of a prefix tag over, say, a separate tag `dtMyTensor` is that prefix
237
* tags can be added and removed by the compute tags acting on the original tag.
238
* Prefix tags can also be composed, so a second time derivative would be
239
* `dt<dt<MyTensor>>`. The net result of the prefix tags infrastructure is that
240
* the compute tag that returns `dt<MyTensor>` only needs to know its input
241
* tags, it knows how to name its output based off that. In addition to the
242
* normal things a simple or a compute tag must hold, prefix tags must have a
243
* nested type alias `tag`, which is the tag being prefixed. Prefix tags must
244
* also inherit from `db::PrefixTag` in addition to inheriting from
245
* `db::SimpleTag` or `db::ComputeTag`.
246
*
247
* #### Creating a DataBox
248
*
249
* You should never call the constructor of a DataBox directly. DataBox
250
* construction is quite complicated and the helper functions `db::create` and
251
* `db::create_from` should be used instead. `db::create` is used to construct a
252
* new DataBox. It takes two typelists as explicit template parameters, the
253
* first being a list of the simple tags to add and the second being a list of
254
* compute tags to add. If no compute tags are being added then only the simple
255
* tags list must be specified. The tags lists should be passed as
256
* `db::create<db::AddSimpleTags<simple_tags...>,
257
* db::AddComputeTags<compute_tags...>>`. The arguments to `db::create` are the
258
* initial values of the simple tags and must be passed in the same order as the
259
* tags in the `db::AddSimpleTags` list. If the type of an argument passed to
260
* `db::create` does not match the type of the corresponding simple tag a static
261
* assertion will trigger. Here is an example of how to use `db::create`:
262
*
263
* \snippet Test_DataBox.cpp create_databox
264
*
265
* To create a new DataBox from an existing one use the `db::create_from`
266
* function. The only time a new DataBox needs to be created is when tags need
267
* to be removed or added. Like `db::create`, `db::create_from` also takes
268
* typelists as explicit template parameter. The first template parameter is the
269
* list of tags to be removed, which is passed using `db::RemoveTags`, second is
270
* the list of simple tags to add, and the third is the list of compute tags to
271
* add. If tags are only removed then only the first template parameter needs to
272
* be specified. If tags are being removed and only simple tags are being added
273
* then only the first two template parameters need to be specified. Here is an
274
* example of removing a tag or compute tag:
275
*
276
* \snippet Test_DataBox.cpp create_from_remove
277
*
278
* Adding a simple tag is done using:
279
*
280
* \snippet Test_DataBox.cpp create_from_add_item
281
*
282
* Adding a compute tag is done using:
283
*
284
* \snippet Test_DataBox.cpp create_from_add_compute_item
285
*
286
* #### Accessing and Mutating Items
287
*
288
* To retrieve an item from a DataBox use the `db::get` function. `db::get`
289
* will always return a `const` reference to the object stored in the DataBox
290
* and will also have full type information available. This means you are able
291
* to use `const auto&` when retrieving tags from the DataBox. For example,
292
* \snippet Test_DataBox.cpp using_db_get
293
*
294
* If you want to mutate the value of a simple item in the DataBox use
295
* `db::mutate`. Any compute item that depends on the mutated item will have its
296
* cached value invalidated and be recomputed the next time it is retrieved from
297
* the DataBox. `db::mutate` takes a parameter pack of tags to mutate as
298
* explicit template parameters, a `gsl::not_null` of the DataBox whose items
299
* will be mutated, an invokable, and extra arguments to forward to the
300
* invokable. The invokable takes the arguments passed from the DataBox by
301
* `const gsl::not_null` while the extra arguments are forwarded to the
302
* invokable. The invokable is not allowed to retrieve anything from the
303
* DataBox, so any items must be passed as extra arguments using `db::get` to
304
* retrieve them. For example,
305
*
306
* \snippet Test_DataBox.cpp databox_mutate_example
307
*
308
* In addition to retrieving items using `db::get` and mutating them using
309
* `db::mutate`, there is a facility to invoke an invokable with tags from the
310
* DataBox. `db::apply` takes a `tmpl::list` of tags as an explicit template
311
* parameter, will retrieve all the tags from the DataBox passed in and then
312
* invoke the invokable with the items in the tag list. Similarly,
313
* `db::mutate_apply` invokes the invokable but allows for mutating some of
314
* the tags. See the documentation of `db::apply` and `db::mutate_apply` for
315
* examples of how to use them.
316
*
317
* #### The Base Tags Mechanism
318
*
319
* Retrieving items by tags should not require knowing whether the item being
320
* retrieved was computed using a compute tag or simply added using a simple
321
* tag. The framework that handles this falls under the umbrella term
322
* *base tags*. The reason is that a compute tag can inherit from a simple tag
323
* with the same item type, and then calls to `db::get` with the simple tag can
324
* be used to retrieve the compute item as well. That is, say you have a compute
325
* tag `ArrayCompute` that derives off of the simple tag `Array`, then you can
326
* retrieve the compute tag `ArrayCompute` and `Array` by calling
327
* `db::get<Array>(box)`. The base tags mechanism requires that only one `Array`
328
* tag be present in the DataBox, otherwise a static assertion is triggered.
329
*
330
* The inheritance idea can be generalized further with what are called base
331
* tags. A base tag is an empty `struct` that inherits from `db::BaseTag`. Any
332
* simple or compute item that derives off of the base tag can be retrieved
333
* using `db::get`. Consider the following `VectorBase` and `Vector` tag:
334
*
335
* \snippet Test_BaseTags.cpp vector_base_definitions
336
*
337
* It is possible to retrieve `Vector<1>` from the DataBox using
338
* `VectorBase<1>`. Most importantly, base tags can also be used in compute tag
339
* arguments, as follows:
340
*
341
* \snippet Test_BaseTags.cpp compute_template_base_tags
342
*
343
* As shown in the code example, the base tag mechanism works with function
344
* template compute tags, enabling generic programming to be combined with the
345
* lazy evaluation and automatic dependency analysis offered by the DataBox. To
346
* really demonstrate the power of base tags, let's also have `ArrayComputeBase`
347
* inherit from a simple tag `Array`, which inherits from a base tag `ArrayBase`
348
* as follows:
349
*
350
* \snippet Test_BaseTags.cpp array_base_definitions
351
*
352
* To start, let's create a DataBox that holds a `Vector<0>` and an
353
* `ArrayComputeBase<0>` (the concrete tag must be used when creating the
354
* DataBox, not the base tags), retrieve the tags using the base tag mechanism,
355
* including mutating `Vector<0>`, and then verifying that the dependencies are
356
* handled correctly.
357
*
358
* \snippet Test_BaseTags.cpp base_simple_and_compute_mutate
359
*
360
* Notice that we are able to retrieve `ArrayComputeBase<0>` with `ArrayBase<0>`
361
* and `Array<0>`. We were also able to mutate `Vector<0>` using
362
* `VectorBase<0>`.
363
*
364
* We can even remove tags using their base tags with `db::create_from`:
365
*
366
* \snippet Test_BaseTags.cpp remove_using_base
367
*
368
* The base tags infrastructure even works with Subitems. Even if you mutate the
369
* subitem of a parent using a base tag, the appropriate compute item caches
370
* will be invalidated.
371
*
372
* \note All of the base tags infrastructure works for `db::get`, `db::mutate`,
373
* `db::apply` and `db::mutate_apply`.
374
*/
375
376
/*!
377
* \defgroup DataBoxTagsGroup DataBox Tags
378
* \brief Structures and metafunctions for labeling the contents of DataBoxes
379
*/
380
381
/*!
382
* \defgroup DataStructuresGroup Data Structures
383
* \brief Various useful data structures used in SpECTRE
384
*/
385
386
/*!
387
* \defgroup DgSubcellGroup DG-Subcell
388
* \brief Functions and classes specific to the discontinuous Galerkin method
389
* supplemented with a finite volume or finite difference subcell limiter. Can
390
* also be thought of as a DG-FD hybrid method.
391
*/
392
393
/*!
394
* \defgroup DiscontinuousGalerkinGroup Discontinuous Galerkin
395
* \brief Functions and classes specific to the Discontinuous Galerkin
396
* algorithm.
397
*/
398
399
/*!
400
* \defgroup EllipticSystemsGroup Elliptic Systems
401
* \brief All available elliptic systems
402
*/
403
404
/*!
405
* \defgroup EquationsOfStateGroup Equations of State
406
* \brief The various available equations of state
407
*/
408
409
/*!
410
* \defgroup ErrorHandlingGroup Error Handling
411
* Macros and functions used for handling errors
412
*/
413
414
/*!
415
* \defgroup EventsAndTriggersGroup Events and Triggers
416
* \brief Classes and functions related to events and triggers
417
*/
418
419
/*!
420
* \defgroup EvolutionSystemsGroup Evolution Systems
421
* \brief All available evolution systems and information on how to implement
422
* evolution systems
423
*
424
* \details Actions and parallel components may require an evolution system to
425
* expose the following types:
426
*
427
* - `volume_dim`: The number of spatial dimensions
428
* - `variables_tag`: The evolved variables to compute DG volume contributions
429
* and fluxes for.
430
* - `compute_time_derivative`: A struct that computes the bulk contribution to
431
* the DG discretization of the time derivative. Must expose a `tmpl::list` of
432
* `argument_tags` and a static `apply` function that takes the following
433
* arguments in this order:
434
* - First, the types of the tensors in
435
* `db::add_tag_prefix<Metavariables::temporal_id::step_prefix, variables_tag>`
436
* (which represent the time derivatives of the variables) as not-null pointers.
437
* - The types of the `argument_tags` as constant references.
438
*
439
* Actions and parallel components may also require the Metavariables to expose
440
* the following types:
441
*
442
* - `system`: See above.
443
* - `temporal_id`: A DataBox tag that identifies steps in the algorithm.
444
* Generally use `Tags::TimeStepId`.
445
*/
446
447
/*!
448
* \defgroup ExecutablesGroup Executables
449
* \brief A list of executables and how to use them
450
*
451
* <table class="doxtable">
452
* <tr>
453
* <th>Executable Name </th><th>Description </th>
454
* </tr>
455
* <tr>
456
* <td> \ref ParallelInfoExecutablePage "ParallelInfo" </td>
457
* <td> Executable for checking number of nodes, cores, etc.</td>
458
* </tr>
459
* </table>
460
*/
461
462
/*!
463
* \defgroup FileSystemGroup File System
464
* \brief A light-weight file system library.
465
*/
466
467
/*!
468
* \defgroup GeneralRelativityGroup General Relativity
469
* \brief Contains functions used in General Relativistic simulations
470
*/
471
472
/*!
473
* \defgroup HDF5Group HDF5
474
* \brief Functions and classes for manipulating HDF5 files
475
*/
476
477
/*!
478
* \defgroup InitializationGroup Initialization
479
* \brief Actions and metafunctions used for initialization of parallel
480
* components.
481
*/
482
483
/*!
484
* \defgroup LimitersGroup Limiters
485
* \brief Limiters to control shocks and surfaces in the solution.
486
*/
487
488
/*!
489
* \defgroup LinearSolverGroup Linear Solver
490
* \brief Algorithms to solve linear systems of equations
491
*
492
* \details In a way, the linear solver is for elliptic systems what time
493
* stepping is for the evolution code. This is because the DG scheme for an
494
* elliptic system reduces to a linear system of equations of the type
495
* \f$Ax=b\f$, where \f$A\f$ is a global matrix representing the DG
496
* discretization of the problem. Since this is one equation for each node in
497
* the computational domain it becomes unfeasible to numerically invert the
498
* global matrix \f$A\f$. Instead, we solve the problem iteratively so that we
499
* never need to construct \f$A\f$ globally but only need \f$Ax\f$ that can be
500
* evaluated locally by virtue of the DG formulation. This action of the
501
* operator is what we have to supply in each step of the iterative algorithms
502
* implemented here. It is where most of the computational cost goes and usually
503
* involves computing a volume contribution for each element and communicating
504
* fluxes with neighboring elements. Since the iterative algorithms typically
505
* scale badly with increasing grid size, a preconditioner \f$P\f$ is needed
506
* in order to make \f$P^{-1}A\f$ easier to invert.
507
*
508
* \note The smallest possible residual magnitude the linear solver can reach is
509
* the product between the machine epsilon and the condition number of the
510
* linear operator that is being inverted. Smaller residuals are numerical
511
* artifacts. Requiring an absolute or relative residual below this limit will
512
* likely make the linear solver run until it reaches its maximum number of
513
* iterations.
514
*
515
* \note Remember that when the linear operator \f$A\f$ corresponds to a PDE
516
* discretization, decreasing the linear solver residual below the
517
* discretization error will not improve the numerical solution any further.
518
* I.e. the error \f$e_k=x_k-x_\mathrm{analytic}\f$ to an analytic solution
519
* will be dominated by the linear solver residual at first, but even if the
520
* discretization \f$Ax_k=b\f$ was exactly solved after some iteration \f$k\f$,
521
* the discretization residual
522
* \f$Ae_k=b-Ax_\mathrm{analytic}=r_\mathrm{discretization}\f$ would still
523
* remain. Therefore, ideally choose the absolute or relative residual criteria
524
* based on an estimate of the discretization residual.
525
*
526
* In the iterative algorithms we usually don't work with the physical field
527
* \f$x\f$ directly. Instead we need to apply the operator to an internal
528
* variable defined by the respective algorithm. This variable is exposed as the
529
* `LinearSolver::Tags::Operand` prefix, and the algorithm expects that the
530
* computed operator action is written into
531
* `db::add_tag_prefix<LinearSolver::Tags::OperatorAppliedTo,
532
* LinearSolver::Tags::Operand<...>>` in each step.
533
*/
534
535
/// \defgroup LoggingGroup Logging
536
/// \brief Functions for logging progress of running code
537
538
/// \defgroup MathFunctionsGroup Math Functions
539
/// \brief Useful analytic functions
540
541
/*!
542
* \defgroup NumericalAlgorithmsGroup Numerical Algorithms
543
* \brief Generic numerical algorithms
544
*/
545
546
/*!
547
* \defgroup NumericalFluxesGroup Numerical Fluxes
548
* \brief The set of available numerical fluxes
549
*/
550
551
/*!
552
* \defgroup ObserversGroup Observers
553
* \brief Observing/writing data to disk.
554
*/
555
556
/*!
557
* \defgroup OptionGroupsGroup Option Groups
558
* \brief Tags used for grouping input file options.
559
*
560
* An \ref OptionTagsGroup "option tag" can be placed in a group with other
561
* option tags to give the input file more structure. To assign a group to an
562
* option tag, set its `group` type alias to a struct that provides a help
563
* string and may override a static `name()` function:
564
*
565
* \snippet Test_Options.cpp options_example_group
566
*
567
* A number of commonly used groups are listed here.
568
*
569
* See also the \ref dev_guide_option_parsing "option parsing guide".
570
*/
571
572
/*!
573
* \defgroup OptionParsingGroup Option Parsing
574
* Things related to parsing YAML input files.
575
*/
576
577
/*!
578
* \defgroup OptionTagsGroup Option Tags
579
* \brief Tags used for options parsed from the input file.
580
*
581
* These can be stored in the GlobalCache or passed to the `initialize`
582
* function of a parallel component.
583
*/
584
585
/*!
586
* \defgroup ParallelGroup Parallelization
587
* \brief Functions, classes and documentation related to parallelization and
588
* Charm++
589
*
590
* See
591
* \ref dev_guide_parallelization_foundations "Parallelization infrastructure"
592
* for details.
593
*/
594
595
/*!
596
* \defgroup PeoGroup Performance, Efficiency, and Optimizations
597
* \brief Classes and functions useful for performance optimizations.
598
*/
599
600
/*!
601
* \defgroup PrettyTypeGroup Pretty Type
602
* \brief Pretty printing of types
603
*/
604
605
/*!
606
* \defgroup ProtocolsGroup Protocols
607
* \brief Classes that define metaprogramming interfaces
608
*
609
* See the \ref protocols section of the dev guide for details.
610
*/
611
612
/*!
613
* \defgroup PythonBindingsGroup Python Bindings
614
* \brief Classes and functions useful when writing python bindings.
615
*
616
* See the \ref spectre_writing_python_bindings "Writing Python Bindings"
617
* section of the dev guide for details on how to write python bindings.
618
*/
619
620
/*!
621
* \defgroup SpecialRelativityGroup Special Relativity
622
* \brief Contains functions used in special relativity calculations
623
*/
624
625
/*!
626
* \defgroup SpectralGroup Spectral
627
* Things related to spectral transformations.
628
*/
629
630
// Note: this group is ordered by how it appears in the rendered Doxygen pages
631
// (i.e., "Spin-weighted..."), rather than the group's name (i.e., "Swsh...").
632
/*!
633
* \defgroup SwshGroup Spin-weighted spherical harmonics
634
* Utilities, tags, and metafunctions for using and manipulating spin-weighted
635
* spherical harmonics
636
*/
637
638
/*!
639
* \defgroup SurfacesGroup Surfaces
640
* Things related to surfaces.
641
*/
642
643
/*!
644
* \defgroup TensorGroup Tensor
645
* Tensor use documentation.
646
*/
647
648
/*!
649
* \defgroup TensorExpressionsGroup Tensor Expressions
650
* Tensor Expressions allow writing expressions of
651
* tensors in a way similar to what is used with pen and paper.
652
*
653
* Tensor expressions are implemented using (smart) expression templates. This
654
* allows a domain specific language making expressions such as
655
* \code
656
* auto T = evaluate<Indices::_a_t, Indices::_b_t>(F(Indices::_b,
657
* Indices::_a));
658
* \endcode
659
* possible.
660
*/
661
662
/*!
663
* \defgroup TestingFrameworkGroup Testing Framework
664
* \brief Classes, functions, macros, and instructions for developing tests
665
*
666
* \details
667
*
668
* SpECTRE uses the testing framework
669
* [Catch](https://github.com/philsquared/Catch). Catch supports a variety of
670
* different styles of tests including BDD and fixture tests. The file
671
* `cmake/SpectreAddCatchTests.cmake` parses the source files and adds the found
672
* tests to ctest with the correct properties specified by tags and attributes.
673
*
674
* ### Usage
675
*
676
* To run the tests, type `ctest` in the build directory. You can specify
677
* a regex to match the test name using `ctest -R Unit.Blah`, or run all
678
* tests with a certain tag using `ctest -L tag`.
679
*
680
* ### Comparing double-precision results
681
*
682
* To compare two floating-point numbers that may differ by round-off, use the
683
* helper object `approx`. This is an instance of Catch's comparison class
684
* `Approx` in which the relative tolerance for comparisons is set to roughly
685
* \f$10^{-14}\f$ (i.e. `std::numeric_limits<double>::%epsilon()*100`).
686
* When possible, we recommend using `approx` for fuzzy comparisons as follows:
687
* \example
688
* \snippet Test_TestingFramework.cpp approx_default
689
*
690
* For checks that need more control over the precision (e.g. an algorithm in
691
* which round-off errors accumulate to a higher level), we recommend using
692
* the `approx` helper with a one-time tolerance adjustment. A comment
693
* should explain the reason for the adjustment:
694
* \example
695
* \snippet Test_TestingFramework.cpp approx_single_custom
696
*
697
* For tests in which the same precision adjustment is re-used many times, a new
698
* helper object can be created from Catch's `Approx` with a custom precision:
699
* \example
700
* \snippet Test_TestingFramework.cpp approx_new_custom
701
*
702
* Note: We provide the `approx` object because Catch's `Approx` defaults to a
703
* very loose tolerance (`std::numeric_limits<float>::%epsilon()*100`, or
704
* roughly \f$10^{-5}\f$ relative error), and so is poorly-suited to checking
705
* many numerical algorithms that rely on double-precision accuracy. By
706
* providing a tighter tolerance with `approx`, we avoid having to redefine the
707
* tolerance in every test.
708
*
709
* ### Attributes
710
*
711
* Attributes allow you to modify properties of the test. Attributes are
712
* specified as follows:
713
* \code
714
* // [[TimeOut, 10]]
715
* // [[OutputRegex, The error message expected from the test]]
716
* SPECTRE_TEST_CASE("Unit.Blah", "[Unit]") {
717
* \endcode
718
*
719
* Available attributes are:
720
*
721
* <table class="doxtable">
722
* <tr>
723
* <th>Attribute </th><th>Description </th>
724
* </tr>
725
* <tr>
726
* <td>TimeOut </td>
727
* <td>override the default timeout and set the timeout to N seconds. This
728
* should be set very sparingly since unit tests are designed to be
729
* short. If your test is too long you should consider testing smaller
730
* portions of the code if possible, or writing an integration test instead.
731
* </td>
732
* </tr>
733
* <tr>
734
* <td>OutputRegex </td>
735
* <td>
736
* When testing failure modes the exact error message must be tested, not
737
* just that the test failed. Since the string passed is a regular
738
* expression you must escape any regex tokens. For example, to match
739
* `some (word) and` you must specify the string `some \(word\) and`.
740
* If your error message contains a newline, you can match it using the
741
* dot operator `.`, which matches any character.
742
* </td>
743
* </tr>
744
* </table>
745
*
746
* \example
747
* \snippet Test_H5.cpp willfail_example_for_dev_doc
748
*
749
* ### Debugging Tests in GDB or LLDB
750
*
751
* Several tests fail intentionally at the executable level to test error
752
* handling like ASSERT statements in the code. CTest is aware of which
753
* should fail and passes them. If you want to debug an individual test
754
* in a debugger you need to run a single test
755
* using the %RunTests executable (in dg-charm-build/bin/RunTests) you
756
* must specify the name of the test as the first argument. For example, if you
757
* want to run just the "Unit.Gradient" test you can run
758
* `./bin/RunTests Unit.Gradient`. If you are using a debugger launch the
759
* debugger, for example if you're using LLDB then run `lldb ./bin/RunTests`
760
* and then to run the executable inside the debugger use `run Unit.Gradient`
761
* inside the debugger.
762
*/
763
764
/*!
765
* \defgroup TimeGroup Time
766
* \brief Code related to the representation of time during simulations.
767
*
768
* The time covered by a simulation is divided up into a sequence of
769
* adjacent, non-overlapping (except at endpoints) intervals referred
770
* to as "slabs". The boundaries between slabs can be placed at
771
* arbitrary times. Slabs, as represented in the code as the Slab
772
* class, provide comparison operators comparing slabs agreeing with
773
* the definition as a sequence of intervals. Slabs that do not
774
* jointly belong to any such sequence should not be compared.
775
*
776
* The specific time is represented by the Time class, which encodes
777
* the slab containing the time and the fraction of the slab that has
778
* elapsed as an exact rational. Times are comparable according to
779
* their natural time ordering, except for times belonging to
780
* incomparable slabs.
781
*
782
* Differences in time within a slab are represented as exact
783
* fractions of that slab by the TimeDelta class. TimeDeltas are only
784
* meaningful within a single slab, with the exception that the ratio
785
* of objects with different slabs may be taken, resulting in an
786
* inexact floating-point result. Longer intervals of time are
787
* represented using floating-point values.
788
*/
789
790
/*!
791
* \defgroup TimeSteppersGroup Time Steppers
792
* A collection of ODE integrators primarily used for time stepping.
793
*/
794
795
/*!
796
* \defgroup TypeTraitsGroup Type Traits
797
* A collection of useful type traits, including C++14 and C++17 additions to
798
* the standard library.
799
*/
800
801
/*!
802
* \defgroup UtilitiesGroup Utilities
803
* \brief A collection of useful classes, functions and metafunctions.
804
*/
805
806
/*!
807
* \defgroup VariableFixingGroup Variable Fixing
808
* \brief A collection of different variable fixers ranging in sophistication.
809
*
810
* Build-up of numerical error can cause physical quantities to evolve
811
* toward non-physical values. For example, pressure and density may become
812
* negative. This will subsequently lead to failures in numerical inversion
813
* schemes to recover the corresponding convervative values. A rough fix that
814
* enforces physical quantities stay physical is to simply change them by hand
815
* when needed. This can be done at various degrees of sophistication, but in
816
* general the fixed quantities make up a negligible amount of the physics of
817
* the simulation; a rough fix is vastly preferred to a simulation that fails
818
* to complete due to nonphysical quantities.
819
*/
© Copyright 2017 - 2021
SXS Collaboration
,
Distributed under the
MIT License