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

Generated by: LCOV version 1.14