SpECTRE
v2021.01.11
Documentation
Introduction
Releases
Installation
User Tutorials
Dev Guide
Code of Conduct
Contributing Guide
Code Reference
Topics
Namespaces
Files
Bibliography
View on GitHub
work
build
docs
tmp
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 DiscontinuousGalerkinGroup Discontinuous Galerkin
388
* \brief Functions and classes specific to the Discontinuous Galerkin
389
* algorithm.
390
*/
391
392
/*!
393
* \defgroup EllipticSystemsGroup Elliptic Systems
394
* \brief All available elliptic systems
395
*/
396
397
/*!
398
* \defgroup EquationsOfStateGroup Equations of State
399
* \brief The various available equations of state
400
*/
401
402
/*!
403
* \defgroup ErrorHandlingGroup Error Handling
404
* Macros and functions used for handling errors
405
*/
406
407
/*!
408
* \defgroup EventsAndTriggersGroup Events and Triggers
409
* \brief Classes and functions related to events and triggers
410
*/
411
412
/*!
413
* \defgroup EvolutionSystemsGroup Evolution Systems
414
* \brief All available evolution systems and information on how to implement
415
* evolution systems
416
*
417
* \details Actions and parallel components may require an evolution system to
418
* expose the following types:
419
*
420
* - `volume_dim`: The number of spatial dimensions
421
* - `variables_tag`: The evolved variables to compute DG volume contributions
422
* and fluxes for.
423
* - `compute_time_derivative`: A struct that computes the bulk contribution to
424
* the DG discretization of the time derivative. Must expose a `tmpl::list` of
425
* `argument_tags` and a static `apply` function that takes the following
426
* arguments in this order:
427
* - First, the types of the tensors in
428
* `db::add_tag_prefix<Metavariables::temporal_id::step_prefix, variables_tag>`
429
* (which represent the time derivatives of the variables) as not-null pointers.
430
* - The types of the `argument_tags` as constant references.
431
*
432
* Actions and parallel components may also require the Metavariables to expose
433
* the following types:
434
*
435
* - `system`: See above.
436
* - `temporal_id`: A DataBox tag that identifies steps in the algorithm.
437
* Generally use `Tags::TimeStepId`.
438
*/
439
440
/*!
441
* \defgroup ExecutablesGroup Executables
442
* \brief A list of executables and how to use them
443
*
444
* <table class="doxtable">
445
* <tr>
446
* <th>Executable Name </th><th>Description </th>
447
* </tr>
448
* <tr>
449
* <td> \ref ParallelInfoExecutablePage "ParallelInfo" </td>
450
* <td> Executable for checking number of nodes, cores, etc.</td>
451
* </tr>
452
* </table>
453
*/
454
455
/*!
456
* \defgroup FileSystemGroup File System
457
* \brief A light-weight file system library.
458
*/
459
460
/*!
461
* \defgroup GeneralRelativityGroup General Relativity
462
* \brief Contains functions used in General Relativistic simulations
463
*/
464
465
/*!
466
* \defgroup HDF5Group HDF5
467
* \brief Functions and classes for manipulating HDF5 files
468
*/
469
470
/*!
471
* \defgroup InitializationGroup Initialization
472
* \brief Actions and metafunctions used for initialization of parallel
473
* components.
474
*/
475
476
/*!
477
* \defgroup LimitersGroup Limiters
478
* \brief Limiters to control shocks and surfaces in the solution.
479
*/
480
481
/*!
482
* \defgroup LinearSolverGroup Linear Solver
483
* \brief Algorithms to solve linear systems of equations
484
*
485
* \details In a way, the linear solver is for elliptic systems what time
486
* stepping is for the evolution code. This is because the DG scheme for an
487
* elliptic system reduces to a linear system of equations of the type
488
* \f$Ax=b\f$, where \f$A\f$ is a global matrix representing the DG
489
* discretization of the problem. Since this is one equation for each node in
490
* the computational domain it becomes unfeasible to numerically invert the
491
* global matrix \f$A\f$. Instead, we solve the problem iteratively so that we
492
* never need to construct \f$A\f$ globally but only need \f$Ax\f$ that can be
493
* evaluated locally by virtue of the DG formulation. This action of the
494
* operator is what we have to supply in each step of the iterative algorithms
495
* implemented here. It is where most of the computational cost goes and usually
496
* involves computing a volume contribution for each element and communicating
497
* fluxes with neighboring elements. Since the iterative algorithms typically
498
* scale badly with increasing grid size, a preconditioner \f$P\f$ is needed
499
* in order to make \f$P^{-1}A\f$ easier to invert.
500
*
501
* \note The smallest possible residual magnitude the linear solver can reach is
502
* the product between the machine epsilon and the condition number of the
503
* linear operator that is being inverted. Smaller residuals are numerical
504
* artifacts. Requiring an absolute or relative residual below this limit will
505
* likely make the linear solver run until it reaches its maximum number of
506
* iterations.
507
*
508
* \note Remember that when the linear operator \f$A\f$ corresponds to a PDE
509
* discretization, decreasing the linear solver residual below the
510
* discretization error will not improve the numerical solution any further.
511
* I.e. the error \f$e_k=x_k-x_\mathrm{analytic}\f$ to an analytic solution
512
* will be dominated by the linear solver residual at first, but even if the
513
* discretization \f$Ax_k=b\f$ was exactly solved after some iteration \f$k\f$,
514
* the discretization residual
515
* \f$Ae_k=b-Ax_\mathrm{analytic}=r_\mathrm{discretization}\f$ would still
516
* remain. Therefore, ideally choose the absolute or relative residual criteria
517
* based on an estimate of the discretization residual.
518
*
519
* In the iterative algorithms we usually don't work with the physical field
520
* \f$x\f$ directly. Instead we need to apply the operator to an internal
521
* variable defined by the respective algorithm. This variable is exposed as the
522
* `LinearSolver::Tags::Operand` prefix, and the algorithm expects that the
523
* computed operator action is written into
524
* `db::add_tag_prefix<LinearSolver::Tags::OperatorAppliedTo,
525
* LinearSolver::Tags::Operand<...>>` in each step.
526
*/
527
528
/// \defgroup LoggingGroup Logging
529
/// \brief Functions for logging progress of running code
530
531
/// \defgroup MathFunctionsGroup Math Functions
532
/// \brief Useful analytic functions
533
534
/*!
535
* \defgroup NumericalAlgorithmsGroup Numerical Algorithms
536
* \brief Generic numerical algorithms
537
*/
538
539
/*!
540
* \defgroup NumericalFluxesGroup Numerical Fluxes
541
* \brief The set of available numerical fluxes
542
*/
543
544
/*!
545
* \defgroup ObserversGroup Observers
546
* \brief Observing/writing data to disk.
547
*/
548
549
/*!
550
* \defgroup OptionGroupsGroup Option Groups
551
* \brief Tags used for grouping input file options.
552
*
553
* An \ref OptionTagsGroup "option tag" can be placed in a group with other
554
* option tags to give the input file more structure. To assign a group to an
555
* option tag, set its `group` type alias to a struct that provides a help
556
* string and may override a static `name()` function:
557
*
558
* \snippet Test_Options.cpp options_example_group
559
*
560
* A number of commonly used groups are listed here.
561
*
562
* See also the \ref dev_guide_option_parsing "option parsing guide".
563
*/
564
565
/*!
566
* \defgroup OptionParsingGroup Option Parsing
567
* Things related to parsing YAML input files.
568
*/
569
570
/*!
571
* \defgroup OptionTagsGroup Option Tags
572
* \brief Tags used for options parsed from the input file.
573
*
574
* These can be stored in the GlobalCache or passed to the `initialize`
575
* function of a parallel component.
576
*/
577
578
/*!
579
* \defgroup ParallelGroup Parallelization
580
* \brief Functions, classes and documentation related to parallelization and
581
* Charm++
582
*
583
* See
584
* \ref dev_guide_parallelization_foundations "Parallelization infrastructure"
585
* for details.
586
*/
587
588
/*!
589
* \defgroup PeoGroup Performance, Efficiency, and Optimizations
590
* \brief Classes and functions useful for performance optimizations.
591
*/
592
593
/*!
594
* \defgroup PrettyTypeGroup Pretty Type
595
* \brief Pretty printing of types
596
*/
597
598
/*!
599
* \defgroup ProtocolsGroup Protocols
600
* \brief Classes that define metaprogramming interfaces
601
*
602
* See the \ref protocols section of the dev guide for details.
603
*/
604
605
/*!
606
* \defgroup PythonBindingsGroup Python Bindings
607
* \brief Classes and functions useful when writing python bindings.
608
*
609
* See the \ref spectre_writing_python_bindings "Writing Python Bindings"
610
* section of the dev guide for details on how to write python bindings.
611
*/
612
613
/*!
614
* \defgroup SpecialRelativityGroup Special Relativity
615
* \brief Contains functions used in special relativity calculations
616
*/
617
618
/*!
619
* \defgroup SpectralGroup Spectral
620
* Things related to spectral transformations.
621
*/
622
623
// Note: this group is ordered by how it appears in the rendered Doxygen pages
624
// (i.e., "Spin-weighted..."), rather than the group's name (i.e., "Swsh...").
625
/*!
626
* \defgroup SwshGroup Spin-weighted spherical harmonics
627
* Utilities, tags, and metafunctions for using and manipulating spin-weighted
628
* spherical harmonics
629
*/
630
631
/*!
632
* \defgroup SurfacesGroup Surfaces
633
* Things related to surfaces.
634
*/
635
636
/*!
637
* \defgroup TensorGroup Tensor
638
* Tensor use documentation.
639
*/
640
641
/*!
642
* \defgroup TensorExpressionsGroup Tensor Expressions
643
* Tensor Expressions allow writing expressions of
644
* tensors in a way similar to what is used with pen and paper.
645
*
646
* Tensor expressions are implemented using (smart) expression templates. This
647
* allows a domain specific language making expressions such as
648
* \code
649
* auto T = evaluate<Indices::_a_t, Indices::_b_t>(F(Indices::_b,
650
* Indices::_a));
651
* \endcode
652
* possible.
653
*/
654
655
/*!
656
* \defgroup TestingFrameworkGroup Testing Framework
657
* \brief Classes, functions, macros, and instructions for developing tests
658
*
659
* \details
660
*
661
* SpECTRE uses the testing framework
662
* [Catch](https://github.com/philsquared/Catch). Catch supports a variety of
663
* different styles of tests including BDD and fixture tests. The file
664
* `cmake/SpectreAddCatchTests.cmake` parses the source files and adds the found
665
* tests to ctest with the correct properties specified by tags and attributes.
666
*
667
* ### Usage
668
*
669
* To run the tests, type `ctest` in the build directory. You can specify
670
* a regex to match the test name using `ctest -R Unit.Blah`, or run all
671
* tests with a certain tag using `ctest -L tag`.
672
*
673
* ### Comparing double-precision results
674
*
675
* To compare two floating-point numbers that may differ by round-off, use the
676
* helper object `approx`. This is an instance of Catch's comparison class
677
* `Approx` in which the relative tolerance for comparisons is set to roughly
678
* \f$10^{-14}\f$ (i.e. `std::numeric_limits<double>::%epsilon()*100`).
679
* When possible, we recommend using `approx` for fuzzy comparisons as follows:
680
* \example
681
* \snippet Test_TestingFramework.cpp approx_default
682
*
683
* For checks that need more control over the precision (e.g. an algorithm in
684
* which round-off errors accumulate to a higher level), we recommend using
685
* the `approx` helper with a one-time tolerance adjustment. A comment
686
* should explain the reason for the adjustment:
687
* \example
688
* \snippet Test_TestingFramework.cpp approx_single_custom
689
*
690
* For tests in which the same precision adjustment is re-used many times, a new
691
* helper object can be created from Catch's `Approx` with a custom precision:
692
* \example
693
* \snippet Test_TestingFramework.cpp approx_new_custom
694
*
695
* Note: We provide the `approx` object because Catch's `Approx` defaults to a
696
* very loose tolerance (`std::numeric_limits<float>::%epsilon()*100`, or
697
* roughly \f$10^{-5}\f$ relative error), and so is poorly-suited to checking
698
* many numerical algorithms that rely on double-precision accuracy. By
699
* providing a tighter tolerance with `approx`, we avoid having to redefine the
700
* tolerance in every test.
701
*
702
* ### Attributes
703
*
704
* Attributes allow you to modify properties of the test. Attributes are
705
* specified as follows:
706
* \code
707
* // [[TimeOut, 10]]
708
* // [[OutputRegex, The error message expected from the test]]
709
* SPECTRE_TEST_CASE("Unit.Blah", "[Unit]") {
710
* \endcode
711
*
712
* Available attributes are:
713
*
714
* <table class="doxtable">
715
* <tr>
716
* <th>Attribute </th><th>Description </th>
717
* </tr>
718
* <tr>
719
* <td>TimeOut </td>
720
* <td>override the default timeout and set the timeout to N seconds. This
721
* should be set very sparingly since unit tests are designed to be
722
* short. If your test is too long you should consider testing smaller
723
* portions of the code if possible, or writing an integration test instead.
724
* </td>
725
* </tr>
726
* <tr>
727
* <td>OutputRegex </td>
728
* <td>
729
* When testing failure modes the exact error message must be tested, not
730
* just that the test failed. Since the string passed is a regular
731
* expression you must escape any regex tokens. For example, to match
732
* `some (word) and` you must specify the string `some \(word\) and`.
733
* If your error message contains a newline, you can match it using the
734
* dot operator `.`, which matches any character.
735
* </td>
736
* </tr>
737
* </table>
738
*
739
* \example
740
* \snippet Test_H5.cpp willfail_example_for_dev_doc
741
*
742
* ### Debugging Tests in GDB or LLDB
743
*
744
* Several tests fail intentionally at the executable level to test error
745
* handling like ASSERT statements in the code. CTest is aware of which
746
* should fail and passes them. If you want to debug an individual test
747
* in a debugger you need to run a single test
748
* using the %RunTests executable (in dg-charm-build/bin/RunTests) you
749
* must specify the name of the test as the first argument. For example, if you
750
* want to run just the "Unit.Gradient" test you can run
751
* `./bin/RunTests Unit.Gradient`. If you are using a debugger launch the
752
* debugger, for example if you're using LLDB then run `lldb ./bin/RunTests`
753
* and then to run the executable inside the debugger use `run Unit.Gradient`
754
* inside the debugger.
755
*/
756
757
/*!
758
* \defgroup TimeGroup Time
759
* \brief Code related to the representation of time during simulations.
760
*
761
* The time covered by a simulation is divided up into a sequence of
762
* adjacent, non-overlapping (except at endpoints) intervals referred
763
* to as "slabs". The boundaries between slabs can be placed at
764
* arbitrary times. Slabs, as represented in the code as the Slab
765
* class, provide comparison operators comparing slabs agreeing with
766
* the definition as a sequence of intervals. Slabs that do not
767
* jointly belong to any such sequence should not be compared.
768
*
769
* The specific time is represented by the Time class, which encodes
770
* the slab containing the time and the fraction of the slab that has
771
* elapsed as an exact rational. Times are comparable according to
772
* their natural time ordering, except for times belonging to
773
* incomparable slabs.
774
*
775
* Differences in time within a slab are represented as exact
776
* fractions of that slab by the TimeDelta class. TimeDeltas are only
777
* meaningful within a single slab, with the exception that the ratio
778
* of objects with different slabs may be taken, resulting in an
779
* inexact floating-point result. Longer intervals of time are
780
* represented using floating-point values.
781
*/
782
783
/*!
784
* \defgroup TimeSteppersGroup Time Steppers
785
* A collection of ODE integrators primarily used for time stepping.
786
*/
787
788
/*!
789
* \defgroup TypeTraitsGroup Type Traits
790
* A collection of useful type traits, including C++14 and C++17 additions to
791
* the standard library.
792
*/
793
794
/*!
795
* \defgroup UtilitiesGroup Utilities
796
* \brief A collection of useful classes, functions and metafunctions.
797
*/
798
799
/*!
800
* \defgroup VariableFixingGroup Variable Fixing
801
* \brief A collection of different variable fixers ranging in sophistication.
802
*
803
* Build-up of numerical error can cause physical quantities to evolve
804
* toward non-physical values. For example, pressure and density may become
805
* negative. This will subsequently lead to failures in numerical inversion
806
* schemes to recover the corresponding convervative values. A rough fix that
807
* enforces physical quantities stay physical is to simply change them by hand
808
* when needed. This can be done at various degrees of sophistication, but in
809
* general the fixed quantities make up a negligible amount of the physics of
810
* the simulation; a rough fix is vastly preferred to a simulation that fails
811
* to complete due to nonphysical quantities.
812
*/
© Copyright 2017 - 2020
SXS Collaboration
,
Distributed under the
MIT License