Rewrite McLachlan

From Einstein Toolkit Documentation
Jump to: navigation, search


The source code of McLachlan -- i.e. the Kranc script that generates the McLachlan thorn family, as well as the associated helper code -- has become somewhat messy over the years. We have begun to clean things up in the "rewrite" branch. These cleanups include:

  • Avoid duplication of equations. Instead of having one calculation per routine there are now a few "master calculations" that define many equations. The actual calculations (routines) are then automatically generated from respective master calculations by choosing which variables should be defined.
  • Rename some parameters. Some parameters have names that are difficult to understand, and that were taken from the original "BSSN_MoL" code. For example, the real parameter "LapseAdvectionCoeff" is now an integer parameter "advectLapse". Also, all parameters now follow the same naming scheme -- starts with underscore, then camelCase. (It is difficult to use underscores in Kranc.)
  • Rename the grid function "phi" to "phiW", since its content depends on what formulation is used.
  • Code generation is now more flexible. Many choices (e.g. BSSN formulation, whether to evolve A, finite differencing order) can now be made either at Kranc time or at run time. This allows generating both generic thorns or highly tuned thorns from the same source code.
  • Setting shiftGammaCoeff=0.0 to disable evolving B^i is now deprecated, and a warning is generated. Instead, set evolveB=0.
  • Some gauge conditions have been corrected for previously unused parameter combinations. In particular, it is now possible to use lapse and shift advection when A is evolved, e.g. when evolving Kerr-Schild data.
  • Some little-used features were removed, e.g. the ability to set up Minkowski initial conditions without using ADMBase.
  • Kranc is now called in parallel by the makefile, which significantly speeds up code generation.

User-Visible Changes

Apart from improvements and new features, these changes break backward compatibility in two ways:

  • Parameter names change. For backward compatibility, it is still possible to use the old parameter names. At run time, the old parameters are interpreted and the new parameters are set correspondingly (if possible), and a warning is produced.
  • The grid function "phi" and its group "ML_log_confac" are renamed to "phiW" and "ML_confac". It is not possible to add a backward compatibility layer for this.
  • The parameter setting shiftGammaCoeff=0.0 is now implemented differently, leading to differences in B^i and ADMBase::dtbeta^i. Since B^i is unused with this setting, these differences do not influence the time evolution of the other variables. Reproducing the previous behaviour would be possible, but would lead to less efficient code.

Parameter Name Changes

(For backward compatibility, the old parameter names are still accepted.)

Old parameter name New parameter name
my_initial_data initial_data
my_initial_boundary_condition initial_boundary_condition
my_rhs_boundary_condition rhs_boundary_condition
my_boundary_condition boundary_condition
dt_lapse_shift_method (unsupported)
ML_log_confac_bound ML_confac_bound
apply_dissipation (set epsDiss=0 instead)
LapseAdvectionCoeff advectLapse
ShiftAdvectionCoeff advectShift


  • dt_lapse_shift_method enabled a performance optimization that deliberately led to incorrect values for ADMBase's dtlapse and dtshift.

Failing Test Cases

Most test cases can be converted in a straightforward manner, as described above:

  • In the list of variables and groups to be output, phi needs to be replaced by phiW, and ML_log_confac by ML_confac
  • Ditto In file names containing variable or group names

After this is done, some test cases continue to fail. These are:

  • Dissipation/test_ah and Dissipation/test_ob. These test cases contain moving puncture ouput, and the details of finite differencing near the puncture change by about 10^-10 (relative difference) in the rewrite branch. Given that the metric there looks "like noise", this difference seems acceptable.