SpECTRE Documentation Coverage Report
Current view: top level - Evolution/Systems/Cce - System.hpp Hit Total Coverage
Commit: 817e13c5144619b701c7cd870655d8dbf94ab8ce Lines: 0 5 0.0 %
Date: 2024-07-19 22:17:05
Legend: Lines: hit not hit

          Line data    Source code
       1           0 : // Distributed under the MIT License.
       2             : // See LICENSE.txt for details.
       3             : 
       4             : #pragma once
       5             : 
       6             : #include <cstddef>
       7             : 
       8             : #include "DataStructures/VariablesTag.hpp"
       9             : #include "Evolution/Systems/Cce/Tags.hpp"
      10             : #include "Utilities/TMPL.hpp"
      11             : 
      12             : /*!
      13             :  * \ingroup EvolutionSystemsGroup
      14             :  * \brief The set of utilities for performing Cauchy characteristic evolution
      15             :  * and Cauchy characteristic matching.
      16             :  *
      17             :  * \details Cauchy characteristic evolution (CCE) is a secondary nonlinear GR
      18             :  * evolution system that covers the domain extending from a spherical boundary
      19             :  * away from the strong-field regime, and extending all the way to future null
      20             :  * infinity \f$\mathcal I^+\f$. The evolution system is governed by five
      21             :  * hypersurface equations that are integrated radially along future null slices,
      22             :  * and one evolution equation that governs the evolution of one hypersurface to
      23             :  * the next.
      24             :  *
      25             :  * The mathematics of CCE are intricate, and SpECTRE's version implements a
      26             :  * number of tricks and improvements that are not yet present in other contexts.
      27             :  * For introductions to CCE generally, see papers \cite Bishop1997ik,
      28             :  * \cite Bishop1998uk, and \cite Barkett2019uae. Here we do not present a full
      29             :  * description of all of the mathematics, but instead just provide a high-level
      30             :  * roadmap of the SpECTRE utilities and how they come together in the CCE
      31             :  * system. This is intended as a map for maintainers of the codebase.
      32             :  *
      33             :  * First, worldtube data from a completed or running Cauchy evolution of the
      34             :  * Einstein field equations (currently the only one implemented in SpECTRE is
      35             :  * Generalized Harmonic) must be translated to Bondi spin-weighted scalars at
      36             :  * the extraction sphere. Relevant utilities for this conversion are
      37             :  * `Cce::WorldtubeDataManager`, `Cce::create_bondi_boundary_data`. Relevant
      38             :  * parts of the parallel infrastructure are `Cce::H5WorldtubeBoundary`,
      39             :  * `Cce::Actions::BoundaryComputeAndSendToEvolution`,
      40             :  * `Cce::Actions::RequestBoundaryData`, and
      41             :  * `Cce::Actions::ReceiveWorldtubeData`.
      42             :  *
      43             :  * The first hypersurface must be initialized with some reasonable starting
      44             :  * value for the evolved Bondi quantity \f$J\f$. There isn't a universal perfect
      45             :  * prescription for this, as a complete description would require, like the
      46             :  * Cauchy initial data problem, knowledge of the system arbitrarily far in the
      47             :  * past. A utility for assigning the initial data is `Cce::InitializeJ`.
      48             :  *
      49             :  * SpECTRE CCE is currently unique in implementing an additional gauge transform
      50             :  * after the worldtube boundary data is derived. This is performed to obtain an
      51             :  * asymptotically well-behaved gauge that is guaranteed to avoid logarithmic
      52             :  * behavior that has plagued other CCE implementations, and so that the
      53             :  * asymptotic computations can be as simple, fast, and reliable as possible.
      54             :  * Relevant utilities for the gauge transformation are
      55             :  * `Cce::GaugeAdjustedBoundaryValue` (see template specializations),
      56             :  * `Cce::GaugeUpdateTimeDerivatives`, `Cce::GaugeUpdateAngularFromCartesian`,
      57             :  * `Cce::GaugeUpdateJacobianFromCoordinates`, `Cce::GaugeUpdateInterpolator`,
      58             :  * `Cce::GaugeUpdateOmega`, `Cce::GaugeUpdateInertialTimeDerivatives`, and
      59             :  * `Cce::InitializeGauge`.
      60             :  *
      61             :  * Next, the CCE system must evaluate the hypersurface differential equations.
      62             :  * There are five, in sequence, deriving \f$\beta, Q, U, W,\f$ and \f$H\f$. For
      63             :  * each of the five radial differential equations, first the products and
      64             :  * derivatives on the right-hand side must be evaluated, then the full
      65             :  * right-hand side of the equation must be computed, and finally the radial
      66             :  * differential equation is integrated. The equations have a hierarchical
      67             :  * structure, so the result for \f$\beta\f$ feeds into the radial differential
      68             :  * equation for \f$Q\f$, and both feed into \f$U\f$, and so on.
      69             :  *
      70             :  * Relevant utilities for computing the inputs to the hypersurface equations are
      71             :  * `Cce::PrecomputeCceDependencies` (see template specializations),
      72             :  * `Cce::mutate_all_precompute_cce_dependencies`, `Cce::PreSwshDerivatives` (see
      73             :  * template specializations), `Cce::mutate_all_pre_swsh_derivatives_for_tag`,
      74             :  * and `Cce::mutate_all_swsh_derivatives_for_tag`. There are a number of
      75             :  * typelists in `IntegrandInputSteps.hpp` that determine the set of quantities
      76             :  * to be evaluated in each of the five hypersurface steps.
      77             :  * Once the hypersurface equation inputs are computed, then a hypersurface
      78             :  * equation right-hand side can be evaluated via `Cce::ComputeBondiIntegrand`
      79             :  * (see template specializations). Then, the hypersurface equation may be
      80             :  * integrated via `Cce::RadialIntegrateBondi` (see template specializations).
      81             :  *
      82             :  * Relevant parts of the parallel infrastructure for performing the hypersurface
      83             :  * steps are: `Cce::CharacteristicEvolution`,
      84             :  * `Cce::Actions::CalculateIntegrandInputsForTag`, and
      85             :  * `Cce::Actions::PrecomputeGlobalCceDependencies`. Note that most of the
      86             :  * algorithmic steps are laid out in order in the phase-dependent action list of
      87             :  * `Cce::CharacteristicEvolution`.
      88             :  *
      89             :  * The time integration for the hyperbolic part of the CCE equations is
      90             :  * performed via \f$\partial_u J = H\f$, where \f$\partial_u\f$ represents
      91             :  * differentiation with respect to retarded time at fixed numerical radius
      92             :  * \f$y\f$.
      93             :  *
      94             :  * At this point, all of the Bondi quantities on a given hypersurface have been
      95             :  * evaluated, and we wish to output the relevant waveform quantities at
      96             :  * \f$\mathcal I^+\f$. This acts much like an additional step in the
      97             :  * hypersurface sequence, with inputs that need to be calculated before the
      98             :  * quantities of interest can be evaluated. The action
      99             :  * `Cce::Actions::CalculateScriInputs` performs the sequence of steps to obtain
     100             :  * those inputs, and the utilities `Cce::CalculateScriPlusValue` (see template
     101             :  * specializations) can be used to evaluate the desired outputs at
     102             :  * \f$\mathcal I^+\f$.
     103             :  *
     104             :  * Unfortunately, those quantities at \f$\mathcal I^+\f$ are not yet an
     105             :  * appropriate waveform output, because the time coordinate with which they are
     106             :  * evaluated is the simulation time, not an asymptotically inertial time. So,
     107             :  * instead of directly writing the waveform outputs, we must put them in a queue
     108             :  * to be interpolated once enough data points have been accumulated to perform a
     109             :  * reliable interpolation at a consistent cut of \f$\mathcal I^+\f$ at constant
     110             :  * inertial time. Utilities for calculating and evolving the asymptotic inertial
     111             :  * time are `Cce::InitializeScriPlusValue` and `Cce::CalculateScriPlusValue`
     112             :  * using arguments involving `Cce::Tags::InertialRetardedTime`. A utility for
     113             :  * managing the interpolation is `Cce::ScriPlusInterpolationManager`, and
     114             :  * relevant parts of the parallel infrastructure for manipulating the data into
     115             :  * the interpolator and writing the results to disk are
     116             :  * `Cce::Actions::InsertInterpolationScriData` and
     117             :  * `Cce::Actions::ScriObserveInterpolated`.
     118             :  *
     119             :  * The template parameter `EvolveCcm` will add an extra evolved variable to the
     120             :  * characteristic system, namely `Cce::Tags::PartiallyFlatCartesianCoords`.
     121             :  *
     122             :  */
     123             : namespace Cce {
     124             : 
     125             : template <bool EvolveCcm>
     126           0 : struct System {
     127           0 :   static constexpr size_t volume_dim = 3;
     128           0 :   using variables_tag =
     129             :       tmpl::list<::Tags::Variables<tmpl::list<Tags::BondiJ>>,
     130             :                  ::Tags::Variables<tmpl::conditional_t<
     131             :                      EvolveCcm,
     132             :                      tmpl::list<Cce::Tags::CauchyCartesianCoords,
     133             :                                 Cce::Tags::PartiallyFlatCartesianCoords,
     134             :                                 Cce::Tags::InertialRetardedTime>,
     135             :                      tmpl::list<Cce::Tags::CauchyCartesianCoords,
     136             :                                 Cce::Tags::InertialRetardedTime>>>>;
     137             : 
     138           0 :   static constexpr bool has_primitive_and_conservative_vars = false;
     139             : };
     140             : }

Generated by: LCOV version 1.14