Updating old examples for Diagnostic Variables changes

In GRChombo#119, we have added a new diagnostic variables feature which allows separating out diagnostic variables (quantities that are not part of your evolution system of equations) from evolution variables. The advantage of this separation is that these variables are no longer interpolated in time (which is a relatively expensive procedure) but in order to make it work we have had to rewrite code which will break existing examples so this page explains how to update them to make them compatible with the changes if you wish to merge the changes into your examples' branch.

There are also some optional changes which we made in GRChombo#124 if you use CCZ4 variables at the end of this page.

Mandatory Changes

UserVariables.hpp

• As a reference this is the file for the BinaryBH example:

/* GRChombo
* Copyright 2012 The GRChombo collaboration.
* Please refer to LICENSE in GRChombo's root directory.
*/

 #ifndef USERVARIABLES_HPP
 #define USERVARIABLES_HPP

 #include "ArrayTools.hpp"
 #include "CCZ4UserVariables.hpp"
 #include "DiagnosticVariables.hpp"

 /// This enum gives the index of every variable stored in the grid
 enum
 {
     // Note that it is important that the first enum value is set to 1 more than
     // the last CCZ4 var enum
     NUM_VARS = NUM_CCZ4_VARS,
 };

 namespace UserVariables
 {
 static const std::array<std::string, NUM_VARS> variable_names =
     ccz4_variable_names;
 } // namespace UserVariables

 #include "UserVariables.inc.hpp"

 #endif /* USERVARIABLES_HPP */

• You will either need to include an example-specific DiagnosticVariables.hpp file (more complicated: see this section) or EmptyDiagnosticVariables.hpp (easier: see this section):

  #include "DiagnosticVariables.hpp"

• You will need to change the type of UserVariables::variable_names i.e. replace

  static constexpr char const *variable_names[NUM_VARS] = {

  with

  static const std::array<std::string, NUM_VARS> variable_names = {

  Note that you might need to add

  #include <array>
  #include <string>

  at the start of the file to make it work (the above example does not have this as these are included already in CCZ4UserVariables.hpp).

• You will need to include UserVariables.inc.hpp at the end of the file:

  #include "UserVariables.inc.hpp"

<SpecificPhysicsLevel>.hpp

• If present you will need to remove the declaration of the specificWritePlotHeader function. This interface is no longer supported and you should instead use the plot_vars parameter to specify which variables are in plot files.

<SpecificPhysicsLevel>.cpp

• As for the header file, remove the definition of specificWritePlotHeader if present.

• If you use the WeylExtraction class, note that it will assume that Weyl4_Re and Weyl4_Im are diagnostic variables so make sure that these have been converted (see the Converting variables to diagnostic variables section) and that BoxLoops::loops have been modified accordingly.

No diagnostic variables (or quick fix)

• If you have no variables you wish to convert to diagnostic variables or just want the quickest fix, and you don't use WeylExtraction, you can just include EmptyDiagnosticVariables.hpp instead of creating an example-specific DiagnosticVariables.hpp:

  #include "EmptyDiagnosticVariables.hpp"

Converting variables to diagnostic variables

DiagnosticVariables.hpp

• As a reference, this is the file for the BinaryBH example:

  /* GRChombo
   * Copyright 2012 The GRChombo collaboration.
   * Please refer to LICENSE in GRChombo's root directory.
   */
  
  #ifndef DIAGNOSTICVARIABLES_HPP
  #define DIAGNOSTICVARIABLES_HPP
  
  // assign an enum to each variable
  enum
  {
      c_Ham,
  
      c_Mom1,
      c_Mom2,
      c_Mom3,
  
      c_Weyl4_Re,
      c_Weyl4_Im,
  
      NUM_DIAGNOSTIC_VARS
  };
  
  namespace DiagnosticVariables
  {
  static const std::array<std::string, NUM_DIAGNOSTIC_VARS> variable_names = {
      "Ham",
  
      "Mom1",     "Mom2",    "Mom3",
  
      "Weyl4_Re", "Weyl4_Im"};
  }
  
  #endif /* DIAGNOSTICVARIABLES_HPP */

• If you wish to convert a variable to a diagnostic variable. you just need to remove its enumerator (e.g. c_Weyl4_Re) from the enumeration inUserVariables.hpp and add it to the enumeration in DiagnosticVariables.hpp. Make sure to remove the name from UserVariables::variable_names and add it to DiagnosticVariables::variable_names too in the corresponding place.

• The last enumerator in the DiagnosticVariables.hpp enumeration should be NUM_DIAGNOSTIC_VARS which is also what the length of DiagnosticVariables::variable_names should be.

<SpecificPhysicsLevel>.cpp

• If you convert a variable to a diagnostic variable, check every BoxLoops::loop where this variable is computed to ensure that the LevelData<FArrayBox> &out argument (third argument) is m_state_diagnostics. For example in BinaryBHLevel.cpp, the diagnostic variables Weyl4_Re and Weyl4_Im are computed in:

  BoxLoops::loop(Weyl4(m_p.extraction_params.center, m_dx), m_state_new,
                      m_state_diagnostics, EXCLUDE_GHOST_CELLS);

• This may mean that some compute packs will need to be split in order to loop separately with m_state_new as out (for evolution variables) and m_state_diagnostics as out (for diagnostic variables).

• There is no need to set diagnostic variables to zero initially as may have done previously (since the NaN checker probably only checks evolution variables in m_state_new) so remove any SetValue(0.0,...) for them.

AMRInterpolator and SurfaceExtraction

• Note that if you use the AMRInterpolator to interpolate variables which you have converted to diagnostic variables, you will need to specify this in the fourth argument when calling addComp for an InterpolationQuery. For example, if I wished to interpolate Ham for the BinaryBH example, I would use something like

  int num_points = 100;
  std::vector<double> interp_out(num_points);
  InterpolationQuery query(num_points);
  query.addComp(c_Ham, interp_out.data(), Derivative::LOCAL,
                VariableType::diagnostic);
  ...

• If you use SurfaceExtraction to interpolate, on a surface, variables which you have converted to diagnostic variables, you will need to specify this in the second argument when calling add_var, for example

  add_var(c_Ham, VariableType::diagnostic);

Things to note

• Diagnostic variables are not saved in checkpoint files (since you don't need them for a restart) but you may save them in plot files by specifying the variable names in the plot_vars parameter.
• If you use the standard CCZ4 variables, you can include the CCZ4UserVariables.hpp file in your UserVariables.hpp file instead of specifying them all in your examples' enumeration.
  • The first normal evolution variable (or NUM_VARS if there aren't any others) in the enumeration should be assigned the value NUM_CCZ4_VARS.
  • If there are additional evolution variables (unlike the BinaryBH example e.g. matter variables), you can create UserVariables::variable_names by concatenating ccz4_variable_names with UserVariables::user_variable_names using ArrayTools::concatenate (in the ArrayTools.hpp header). For example, below is UserVariables.hpp for the ScalarField example:

    /* GRChombo
    * Copyright 2012 The GRChombo collaboration.
    * Please refer to LICENSE in GRChombo's root directory.
    */
    
    #ifndef USERVARIABLES_HPP
    #define USERVARIABLES_HPP
    
    #include "ArrayTools.hpp"
    #include "CCZ4UserVariables.hpp"
    #include "DiagnosticVariables.hpp"
    
    // assign an enum to each variable
    enum
    {
        // Note that it is important that the first enum value is set to 1 more than
        // the last CCZ4 var enum
        c_phi = NUM_CCZ4_VARS, // matter field added
        c_Pi,                  //(minus) conjugate momentum
    
        NUM_VARS
    };
    
    namespace UserVariables
    {
    static const std::array<std::string, NUM_VARS - NUM_CCZ4_VARS>
        user_variable_names = {"phi", "Pi"};
    
    static const std::array<std::string, NUM_VARS> variable_names =
        ArrayTools::concatenate(ccz4_variable_names, user_variable_names);
    } // namespace UserVariables
    
    #include "UserVariables.inc.hpp"
    
    #endif /* USERVARIABLES_HPP */