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 Subitms. 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  */