How do I add a feature to Tpetra that should not be enabled by default?

Summary

Trilinos developers may at times want to add a feature to Tpetra that should not be enabled or used by default. For example, it may be an experimental algorithm whose benefits have not yet been proven at scale, or a new class whose interface is still in flux. This page gives best practices for doing this.

All new code & tests must build by default

All new code, and its tests, must build by default. (Don't hide it behind some macro.) That doesn't mean it has to run by default. Keep reading :-)

Disable running "experimental" tests & examples by default

Always build the test or example by default. Use TRIBITS_ADD_EXECUTABLE to build the test or example, without running it by default. For example:

TRIBITS_ADD_EXECUTABLE(
  my_fancy_test_executable
  SOURCES my_fancy_test.cpp
)

Use the upcoming Tpetra_ENABLE_Experimental CMake option (PR #3872) to protect tests that use "experimental" features. If the option is OFF, the test won't run. (Examples don't usually run as tests, but if they do, the same applies for them.) Use TRIBITS_ADD_TEST to enable a test that uses an executable. For example:

ASSERT_DEFINED(Tpetra_ENABLE_Experimental) # make sure Tpetra defined this
IF(Tpetra_ENABLE_Experimental)
  TRIBITS_ADD_TEST(
    my_fancy_test_executable
    NAME my_fancy_test_1
    ARGS "--which-fancy-test=1"
    COMM serial mpi
    NUM_MPI_PROCS 1
    STANDARD_PASS_OUTPUT
  )
ENDIF()

Run-time disable experimental code paths in existing classes or functions

If you want to add an "experimental" code path in an existing Tpetra class or function, do the following:

1. Do not protect the code with a macro. THE CODE MUST ALWAYS BUILD.
2. Use Tpetra::Details::Behavior to disable the code path at run time, by default.
3. If you can use an existing Behavior option, please do so.
4. Otherwise, create a new Behavior run-time option.

If you need to create a new Behavior run-time option, you may use an existing configure-time option to set the default value of this option. For example, (PR #3872) will define the TPETRA_ENABLE_EXPERIMENTAL macro. You may use this macro to set the default value of a Behavior run-time option.

Here is an example of how to use Tpetra::Details::Behavior. In this case, we're using the existing option TPETRA_DEBUG to enable extra debug checking at run time.

#include "Tpetra_Details_Behavior.hpp"

void whatever_existing_tpetra_function ()
{
  using Tpetra::Details::Behavior;
  const bool debug = Behavior::debug ();
  if (debug) {
    // Always builds!  No more "this built in release
    // mode, but not in debug mode" issues!
    do_expensive_debug_mode_checks ();
  }
}

Now you can set the TPETRA_DEBUG environment variable to 0 or 1, to control whether or not to do debug checking. See the documentation of Tpetra::Details::Behavior for more options.

Put experimental classes in the Experimental namespace

If your class isn't ready for production, put it in the Tpetra::Experimental namespace. We can always move it or import it into the Tpetra namespace later, once it is ready.