Line data    Source code

       1           0 : // Distributed under the MIT License.
       2             : // See LICENSE.txt for details.
       3             : 
       4             : #pragma once
       5             : 
       6             : #include <type_traits>
       7             : 
       8             : #include "ImplicitSource.hpp"
       9             : #include "ImplicitSourceJacobian.hpp"
      10             : #include "Utilities/ProtocolHelpers.hpp"
      11             : #include "Utilities/TMPL.hpp"
      12             : #include "Utilities/TypeTraits/IsA.hpp"
      13             : 
      14             : /// \cond
      15             : class DataVector;
      16             : template <typename X, typename Symm, typename IndexList>
      17             : class Tensor;
      18             : namespace Tags {
      19             : template <typename Tag>
      20             : struct Source;
      21             : }  // namespace Tags
      22             : /// \endcond
      23             : 
      24             : namespace imex::protocols {
      25             : /// Protocol for an implicit sector of an IMEX system.
      26             : ///
      27             : /// An implicit sector describes the sources for one implicit solve
      28             : /// performed during IMEX evolution.  A system may have multiple
      29             : /// implicit sectors, but they must be independent, i.e., their
      30             : /// sources must not depend on any tensors in other sectors.
      31             : ///
      32             : /// Classes implementing this protocol must define:
      33             : ///
      34             : /// * a `tensors` type alias of tags for the variables to be solved for
      35             : ///
      36             : /// * an `initial_guess` type to be passed to `db::mutate_apply`,
      37             : ///   taking additional arguments for the inhomogeneous terms \f$X\f$
      38             : ///   and implicit weight \f$w\f$ in the equation to be solved:
      39             : ///   \f$u = X + w S(u)\f$.  (See example below.)  It must return a
      40             : ///   `std::vector<GuessResult>` indicating, for each point, whether
      41             : ///   the implicit equation has been solved analytically or whether
      42             : ///   the numerical solve should continue.  An empty return is
      43             : ///   equivalent to `imex::GuessResult::InitialGuess` for every point,
      44             : ///   so numerical solves will be performed for each.  When this is
      45             : ///   called, the sector variables will have the value from the
      46             : ///   explicit part of the time step.  This mutator will not be called
      47             : ///   if the implicit weight is zero, as the solution is trivial in
      48             : ///   that case.  If using the value of the explicit step as an
      49             : ///   initial guess is acceptable, this can be the type
      50             : ///   `imex::GuessExplicitResult`.
      51             : ///
      52             : /// * a `solve_attempts` list of sources that will be attempted to be
      53             : ///   solved, in order.  The first one that succeeds at each point
      54             : ///   will be used.  Pieces of code that need "the" source for the
      55             : ///   sector will use the source from the first entry.  Each attempt
      56             : ///   must be a struct with the following types:
      57             : ///
      58             : ///   * lists used to construct a DataBox during the pointwise
      59             : ///     implicit solve:
      60             : ///
      61             : ///     * `tags_from_evolution` for tags in addition to the sector
      62             : ///        tensors to be made available from the evolution DataBox.
      63             : ///        Volume quantities will be reduced to have one grid point,
      64             : ///        with the appropriate value for the point being solved for.
      65             : ///
      66             : ///     * `simple_tags` for temporaries (e.g., primitives)
      67             : ///
      68             : ///     * `compute_tags`
      69             : ///
      70             : ///   * a `source` type to be passed to `db::mutate_apply` to compute
      71             : ///     the sources. It must conform to imex::protocols::ImplicitSource.
      72             : ///
      73             : ///   * a `jacobian` type to be passed to `db::mutate_apply` to
      74             : ///     compute the source jacobian.  It must conform to
      75             : ///     imex::protocols::ImplicitSourceJacobian. If the implicit equation can
      76             : ///     always be solved analytically for the sector, the jacobian is not
      77             : ///     required and this may be the type
      78             : ///     `imex::NoJacobianBecauseSolutionIsAnalytic`.
      79             : ///
      80             : ///   * lists `source_prep` and `jacobian_prep` that will be called
      81             : ///     before the corresponding main mutator, e.g., for computing
      82             : ///     primitives.  Mutators appearing in multiple lists, as well as
      83             : ///     the `source` and `jacobian` mutators, will be skipped if they
      84             : ///     have already been applied for the current point.  Note that
      85             : ///     the `source_prep` mutators are only used during the implicit
      86             : ///     solve, and any preparation needed before the `source` call in
      87             : ///     the main action loop to record the history is the
      88             : ///     responsibility of the user.
      89             : ///
      90             : /// All `Variables` in the DataBox, including the sources and source
      91             : /// jacobian, will be initialized to zero with a single grid point.
      92             : ///
      93             : /// \snippet DoImplicitStepSector.hpp simple_sector
      94             : ///
      95             : /// Examples of definitions of a complicated implicit source and
      96             : /// jacobian:
      97             : ///
      98             : /// \snippet Test_SolveImplicitSector.cpp source
      99             : /// \snippet Test_SolveImplicitSector.cpp Jacobian
     100           1 : struct ImplicitSector {
     101             :   template <typename ConformingType>
     102           0 :   struct test {
     103           0 :     using tensors = typename ConformingType::tensors;
     104           0 :     using initial_guess = typename ConformingType::initial_guess;
     105           0 :     using solve_attempts = typename ConformingType::solve_attempts;
     106             : 
     107             :     static_assert(tt::is_a_v<tmpl::list, tensors>);
     108             :     static_assert(tt::is_a_v<tmpl::list, solve_attempts>);
     109             :     static_assert(tmpl::size<solve_attempts>::value >= 1);
     110             : 
     111             :     static_assert(
     112             :         tmpl::all<
     113             :             tensors,
     114             :             tt::is_a<Tensor, tmpl::bind<tmpl::type_from, tmpl::_1>>>::value);
     115             : 
     116           0 :     using source_tensors =
     117             :         tmpl::transform<tensors, tmpl::bind<::Tags::Source, tmpl::_1>>;
     118             : 
     119             :     static_assert(
     120             :         tmpl::size<tmpl::list_difference<typename initial_guess::return_tags,
     121             :                                          tensors>>::value == 0,
     122             :         "initial_guess can only modify sector variables.");
     123             : 
     124             :     template <typename SolveAttempt>
     125           0 :     struct test_solve_attempt {
     126           0 :       using source = typename SolveAttempt::source;
     127           0 :       using jacobian = typename SolveAttempt::jacobian;
     128             : 
     129           0 :       using tags_from_evolution = typename SolveAttempt::tags_from_evolution;
     130           0 :       using simple_tags = typename SolveAttempt::simple_tags;
     131           0 :       using compute_tags = typename SolveAttempt::compute_tags;
     132             : 
     133           0 :       using source_prep = typename SolveAttempt::source_prep;
     134           0 :       using jacobian_prep = typename SolveAttempt::jacobian_prep;
     135             : 
     136             :       // check protocol conformity
     137             :       static_assert(
     138             :           tt::assert_conforms_to_v<source, imex::protocols::ImplicitSource>);
     139             :       static_assert(tt::assert_conforms_to_v<
     140             :                     jacobian, imex::protocols::ImplicitSourceJacobian>);
     141             : 
     142             :       static_assert(tt::is_a_v<tmpl::list, tags_from_evolution>);
     143             :       static_assert(tt::is_a_v<tmpl::list, simple_tags>);
     144             :       static_assert(tt::is_a_v<tmpl::list, compute_tags>);
     145             :       static_assert(tt::is_a_v<tmpl::list, source_prep>);
     146             :       static_assert(tt::is_a_v<tmpl::list, jacobian_prep>);
     147             : 
     148             :       static_assert(
     149             :           std::is_same_v<tmpl::list_difference<tags_from_evolution, tensors>,
     150             :                          tags_from_evolution>,
     151             :           "tags_from_evolution cannot include the sector tensors.");
     152             : 
     153             :       static_assert(
     154             :           std::is_same_v<tmpl::list_difference<source_tensors,
     155             :                                                typename source::return_tags>,
     156             :                          tmpl::list<>> and
     157             :               std::is_same_v<tmpl::list_difference<typename source::return_tags,
     158             :                                                    source_tensors>,
     159             :                              tmpl::list<>>,
     160             :           "Implicit source must provide sources for the entire sector.");
     161             : 
     162             :       template <typename T>
     163           0 :       struct is_a_tensor_of_data_vector : std::false_type {};
     164             : 
     165             :       template <typename Symm, typename IndexList>
     166           0 :       struct is_a_tensor_of_data_vector<Tensor<DataVector, Symm, IndexList>>
     167             :           : std::true_type {};
     168             : 
     169             :       static_assert(
     170             :           tmpl::none<simple_tags, is_a_tensor_of_data_vector<tmpl::bind<
     171             :                                       tmpl::type_from, tmpl::_1>>>::value,
     172             :           "Do not include tags for Tensor<DataVector> in simple_tags, because "
     173             :           "they trigger many memory allocations.  Add the tensors as part of "
     174             :           "a Variables instead.");
     175             : 
     176           0 :       using type = std::true_type;
     177             :     };
     178             : 
     179             :     static_assert(
     180             :         tmpl::all<solve_attempts, test_solve_attempt<tmpl::_1>>::value);
     181             :   };
     182             : };
     183             : }  // namespace imex::protocols