Current design issues

[nilsvu]

@nilsdeppe and I discussed some issues we found with our current code design and how we can improve it. I'm noting some of it down here so others know what's going on and can give feedback:

1. Metavariables are hard to understand: Some parts of them are helpful (action lists give a nice overview of the algorithm) but a lot of the rest is collections of type aliases that various parts of the codebase depend on. They duplicate a lot of code between executables, which is good to be able to control each executable's algorithm manually, but hard to maintain when the number of executables grows. Possible improvements:
   • Group options in the metavariables better, and document the groups. Maybe they can be shared between executables, so it's easier to "compose" an executable (see Factor shared sections and aliases out of Metavariables #5219).
   • Prefer passing compile-time options down to actions instead of having them reach up to the metavariables. This is important to support things like multiple systems, and improves flexibility in general.
2. Compile-time interfaces need documentation: When a class implements an interface that some other part of the code expects, this connection must be clear in the code. The reader must be able to follow breadcrumbs to find the documentation. In object-oriented code this connection would be made through base classes. For template code we can rely on documentation-links, but it would be better to keep the breadcrumbs in C++. Possible improvements:
   • We can use either empty base classes or protocols, which are essentially empty base classes with some support to enforce the compile-time interface.
3. Factory-creation and the registration mechanism are hard to understand: Well, factory creation is hard. Details here: Decouple factory-creation from base classes #2953

[nilsvu]

Update: Point 3. is mostly resolved thanks to @wthrowe's work on the factory mechanism. Points 1. and 2. listed above are "in progress", but still problematic, and I think we should try harder to resolve them. In addition, here are two more issues that, in my opinion, slow down the development of our code and make it hard to learn:

4. Analytic solutions/data classes are very complicated: This is a part of the code that new people often come into contact with first. The interface for these classes is relatively simple (just a member function named variables that returns the quantities you ask for), but the implementation is often very complicated. Reasons are:

   • Dependency resolution using a CachedTempBuffer involves the class itself, the buffer class, and a "computer" class. These are often nested, and call each other in a way that's fairly hard to understand as a newcomer.
   • It's hard to move code to the cpp file and still get the benefits of the CachedTempBuffer. Huge lists of template instantiations in the cpp file are annoying and hard to maintain.
   • Often, derived quantities are computed the same in all analytic solutions (like Christoffel symbols from the metric). It's hard to share this code between classes (adding Christoffel symbol tags and a function that calls into the GR lib to compute them to every class is a lot of boilerplate). We tried many different approaches to deal with this, like the WrappedGr class for GH, derived CachedTempBuffer computers for XCTS, or computing derived quantities in the evolution code instead of in the analytic solution class. So far, none of these has been particularly successful.

5. Adding a new equation to solve/evolve is hard and takes a long time to implement: Only a very small amount of time is spent actually implementing the new equation. The rest is spent copying over, trying to understand, and modifying classes for the system, metavariables, boundary conditions, boundary corrections, analytic data/solutions, etc, and trying to deal with long compiler errors along the way. I don't have great ideas for making this process easier, but I think we should try to improve our "time to science".