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

 Generated by: LCOV version 1.14