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