TestingInterface.hpp

Go to the documentation of this file.

/** \file TestingInterface.hpp
 * \brief Collective numerical comparisons for tutorials and atom tests.
 *
 * Tutorials supply the measured quantities and independent references. Field
 * evaluation, physical norms and derivative assembly remain with the existing
 * operators, FieldEvaluatorInterface and OperatorsTester. In particular, a
 * coefficient-vector norm is not interchangeable with a physical field norm.
 *
 * Numerical comparisons and solver checks are collective on the Core
 * communicator, in the same order on every rank. A failure on any rank fails
 * the check on all ranks. Field evaluation is local, as documented below.
 * Tolerances are explicit; non-finite measurements or invalid tolerances fail.
 * Results use the TEST_INTERFACE logging channel with the TestingInterface tag.
 *
 * addTest/runTest/runTests provide an optional registry so a tutorial's
 * solving code need not branch on which test is requested: register what to
 * check, then let a single option (e.g. "-test_nb N") choose what actually
 * runs. addTestCommandLine is the preferred way to populate it: list every
 * candidate test unconditionally, each guarded by its own addTestCommandLine
 * call, then run whatever was actually selected with one runTests() call.
 */
 
#ifndef MOFEM_TESTING_INTERFACE_HPP
#define MOFEM_TESTING_INTERFACE_HPP
 
#include "UnknownInterface.hpp"
#include <array>
#include <functional>
 
namespace MoFEM {
 
/** Compile-time check categories; strings are used only for diagnostics. */
enum class TestType { SCALAR, POINTWISE, DERIVATIVE, SOLVER };
 
struct TestingInterface : public UnknownInterface {
  ~TestingInterface() override = default;
 
  /** Read or refresh selectors after JSON options have been applied.
   * Selection methods load each prefix lazily on first use. Refreshing changes
   * future selection, not existing registrations or installed TS monitors. */
  virtual MoFEMErrorCode getOptions(const std::string &prefix = "") const = 0;
 
  /** Check convergence and the configured final time, respecting STEPOVER. */
  virtual MoFEMErrorCode checkSolver(TS ts,
                                     const std::string &check_name) const = 0;
 
  using TSCheck = std::function<MoFEMErrorCode(TS, PetscInt, PetscReal, Vec)>;
 
  /**
   * Add a numerical check to the TS monitor sequence. TS owns the callback
   * until its monitors are cancelled or it is destroyed; existing monitors
   * are retained. Initial step zero and interpolated output (step -1) are
   * skipped. The callback is collective on the TS communicator, which must be
   * identical or congruent to the Core communicator.
   *
   * The supplied solution is borrowed and must not be modified. Operator
   * checks must use separate work vectors and restore any modified mesh,
   * history or pipeline data, including on failure. Time/rate/shift data for
   * transient derivative checks must come from the actual tested residual;
   * the monitor does not infer them from the time-step size.
   */
  virtual MoFEMErrorCode addTSMonitor(TS ts, TSCheck check) = 0;
 
  /**
   * Register a TS monitor the same way as addTSMonitor(TS, TSCheck), but
   * only if its number appears in the comma-separated
   * "-<prefix>test_nb <int,int,...>" list or its name appears in the
   * comma-separated "-<prefix>test_name <name,name,...>" list read from the
   * command line; otherwise this call does nothing. Giving both options at
   * once is an error.
   *
   * Pairs with addTestCommandLine: register a per-time-step numerical check
   * under the same prefix/number/name selector used for post-solve tests, so
   * a single "-test_nb"/"-test_name" choice can activate both a solve-time
   * monitor and its matching checkResults() test.
   * Selected monitors share the test registry identity. runTest/runTests
   * recognise them but do not invoke their callbacks; TS invokes those.
   */
  virtual MoFEMErrorCode addTSMonitor(const std::string &prefix, int number,
                                      const std::string &name, TS ts,
                                      TSCheck check) = 0;
 
  using FieldEvaluatorHook = std::function<MoFEMErrorCode(
      boost::ptr_deque<ForcesAndSourcesCore::UserDataOperator> &)>;
 
  /**
   * Build an operator pipeline and immediately evaluate one local point.
   * DIM selects the face (2) or volume (3) element and search dimension.
   * Coordinates are always an (x,y,z) triplet.
   * The hook receives the pipeline and supplies its geometry,
   * field and checking operators; outputs can be captured shared data.
   *
   * The evaluator and its operators live only for this call. Coordinates and
   * hook captures need not outlive it. Evaluation uses the current mesh field
   * coefficients, so a TS callback must first scatter the accepted solution.
   * Results are local and are not communicated. By default a point missing
   * from the calling rank's problem elements returns a test failure. Supplying
   * point_found instead reports local ownership without failing for a missing
   * point; the caller must collectively check that some rank found it before
   * comparing owner results. Other evaluation errors still propagate.
   * Operators must not call collective checks on only the owning rank.
   */
  template <int DIM>
  MoFEMErrorCode
  addFieldEvaluator(const std::string &problem,
                    const std::string &finite_element,
                    const std::array<double, 3> &field_eval_coords,
                    FieldEvaluatorHook hook, double distance = 1e-12,
                    bool *point_found = nullptr);
 
  /** Evaluate a point in dimension 2 or 3. */
  virtual MoFEMErrorCode
  addFieldEvaluator(int dimension, const std::string &problem,
                    const std::string &finite_element,
                    const std::array<double, 3> &field_eval_coords,
                    FieldEvaluatorHook hook, double distance = 1e-12,
                    bool *point_found = nullptr) = 0;
 
  /** Acceptance bound: absolute + relative * scale, with no implicit floor. */
  struct Tolerance {
    PetscReal absolute;
    PetscReal relative;
  };
 
  /** Compare real scalars with scale = abs(expected). */
  template <TestType TYPE>
  MoFEMErrorCode checkValue(const std::string &check_name, PetscReal actual,
                            PetscReal expected, Tolerance tolerance,
                            Sev error_severity = Sev::error,
                            Sev success_severity = Sev::inform) const;
 
  /**
   * Compare a non-negative error norm with absolute + relative * scale.
   *
   * The caller defines the norm and scale. For derivative checks, a useful
   * scale is max(norm(FD), norm(J*v)); for tensors use the intended FTensor
   * contraction, including symmetric off-diagonal weights. Missing evaluation
   * points must be reported as failures, not represented by zero error.
   *
   * Local comparisons are reduced collectively; an already-global norm is
   * also valid. Logging severities are configurable; a failed check still
   * returns MOFEM_ATOM_TEST_INVALID regardless of its logging severity.
   * Logs and propagated errors include the global maximum error, failing-rank
   * count and a representative failing rank's paired error and acceptance bound.
   * Invalid/non-finite inputs are distinguished from tolerance violations.
   */
  template <TestType TYPE>
  MoFEMErrorCode checkError(const std::string &check_name, PetscReal error,
                            PetscReal scale, Tolerance tolerance,
                            Sev error_severity = Sev::error,
                            Sev success_severity = Sev::inform) const;
 
  /** Compare an error using the specified check category. */
  virtual MoFEMErrorCode
  checkError(TestType type, const std::string &check_name, PetscReal error,
             PetscReal scale, Tolerance tolerance,
             Sev error_severity = Sev::error,
             Sev success_severity = Sev::inform) const = 0;
 
  /**
   * Check successful termination at the requested final time. A positive TS
   * reason alone can mean a step limit or event before that time. Event-driven
   * tests should check their expected reason and event state explicitly.
   * Also check the last SNES/KSP solve when a nested solver has run. Unused
   * nested solvers retain the ITERATING reason and are skipped. Earlier
   * failures recovered by the solver do not invalidate successful completion.
   * All applicable numerical results are reported before returning failure,
   * including when the outer solver diverges. PETSc/MPI API errors propagate
   * immediately. All checkSolver overloads require an identical or congruent
   * communicator (same members and rank order), checked before Core reductions.
   * All Core ranks must still call these checks in the same order.
   */
  virtual MoFEMErrorCode checkSolver(TS ts, PetscReal expected_time,
                                     Tolerance tolerance,
                                     const std::string &check_name) const = 0;
 
  /** Require SNES convergence and check its KSP if it has run. */
  virtual MoFEMErrorCode checkSolver(SNES snes,
                                     const std::string &check_name) const = 0;
 
  /** Require KSP convergence; an unsolved solver fails this direct check. */
  virtual MoFEMErrorCode checkSolver(KSP ksp,
                                     const std::string &check_name) const = 0;
 
  /** Require TAO convergence under its configured convergence test.
   * Does not independently test the raw objective gradient or custom subsolvers.
   */
  virtual MoFEMErrorCode checkSolver(Tao tao,
                                     const std::string &check_name) const = 0;
 
  using TestHook = std::function<MoFEMErrorCode()>;
 
  /**
   * Register a named, numbered test for later, on-demand execution.
   *
   * This registry lets a tutorial keep its solving code (readMesh,
   * setupProblem, ..., solveSystem) free of "-test_nb N" branching: checks are
   * registered where it is natural to write them, then run only when asked,
   * through runTest/runTests. A hook is never invoked at registration time,
   * so calling addTest never disturbs already-solved state. Hooks are
   * expected to be collective, called identically by every rank, since they
   * typically perform collective checks (checkValue/checkError, or use
   * addFieldEvaluator). Both number and name must be unique among currently
   * registered tests. Registering either again replaces the conflicting
   * tests and logs a warning for each replaced test. A monitor-only entry with
   * the same number and name gains this hook without a replacement warning.
   * Registry changes do not cancel callbacks already owned by TS.
   */
  virtual MoFEMErrorCode addTest(int number, const std::string &name,
                                 TestHook hook) = 0;
 
  /** Run one previously registered test, looked up by number. Logs a warning
   * and skips the test if that number is not registered. */
  virtual MoFEMErrorCode runTest(int number) const = 0;
 
  /** Run one previously registered test, looked up by name. Logs a warning
   * and skips the test if that name is not registered. */
  virtual MoFEMErrorCode runTest(const std::string &name) const = 0;
 
  /** Run every registered post-solve hook, in ascending order of test number,
   * stopping at and propagating the first failure. Check cached selectors
   * against the current registry and warn about each unmatched selection.
   * Monitor-only entries are recognised but are invoked exclusively by TS. */
  virtual MoFEMErrorCode runTests() const = 0;
 
  /** True if a test or selected TS monitor with this number is registered,
   * e.g. because addTestCommandLine selected it. Lets a tutorial branch on
   * whether a test run was requested without keeping its own flag. */
  virtual bool checkTest(int number) const = 0;
 
  /** True if a test or selected TS monitor with this name is registered. */
  virtual bool checkTest(const std::string &name) const = 0;
 
  /**
   * Run every test selected by "-<prefix>test_nb <int,int,...>" or
   * "-<prefix>test_name <name,name,...>", comma-separated lists read from
   * the command line. Prefix defaults to none, i.e. plain
   * "-test_nb"/"-test_name". Does nothing if neither option is given; giving
   * both is an error. This is the usual entry point for a tutorial's
   * checkResults(): register tests with addTest, then let this one call
   * pick and run everything that was asked for. Each matching post-solve hook
   * runs once, in ascending test-number order, stopping at the first failure.
   * Unmatched selectors warn; monitor-only entries are recognised but skipped.
   */
  virtual MoFEMErrorCode
  runTestCommandLine(const std::string &prefix = "") const = 0;
 
  /**
   * Register a test the same way as addTest, but only if its number appears
   * in the comma-separated "-<prefix>test_nb <int,int,...>" list or its
   * name appears in the comma-separated "-<prefix>test_name
   * <name,name,...>" list read from the command line; otherwise this call
   * does nothing. Giving both options at once is an error.
   *
   * This is the preferred way to add tests: list every candidate test
   * unconditionally in checkResults(), each through its own
   * addTestCommandLine call, then finish with a single runTests() call.
   * Selection is applied at registration time. runTests() runs all registered
   * hooks, including those added directly with addTest. To apply refreshed
   * selectors to existing registrations, use runTestCommandLine instead.
   */
  virtual MoFEMErrorCode addTestCommandLine(const std::string &prefix,
                                            int number,
                                            const std::string &name,
                                            TestHook hook) = 0;
};
 
template <>
MoFEMErrorCode TestingInterface::addFieldEvaluator<2>(
    const std::string &problem, const std::string &finite_element,
    const std::array<double, 3> &field_eval_coords, FieldEvaluatorHook hook,
    double distance, bool *point_found);
 
template <>
MoFEMErrorCode TestingInterface::addFieldEvaluator<3>(
    const std::string &problem, const std::string &finite_element,
    const std::array<double, 3> &field_eval_coords, FieldEvaluatorHook hook,
    double distance, bool *point_found);
 
template <>
MoFEMErrorCode TestingInterface::checkError<TestType::SCALAR>(
    const std::string &check_name, PetscReal error, PetscReal scale,
    Tolerance tolerance, Sev error_severity, Sev success_severity) const;
 
template <>
MoFEMErrorCode TestingInterface::checkError<TestType::POINTWISE>(
    const std::string &check_name, PetscReal error, PetscReal scale,
    Tolerance tolerance, Sev error_severity, Sev success_severity) const;
 
template <>
MoFEMErrorCode TestingInterface::checkError<TestType::DERIVATIVE>(
    const std::string &check_name, PetscReal error, PetscReal scale,
    Tolerance tolerance, Sev error_severity, Sev success_severity) const;
 
template <>
MoFEMErrorCode TestingInterface::checkError<TestType::SOLVER>(
    const std::string &check_name, PetscReal error, PetscReal scale,
    Tolerance tolerance, Sev error_severity, Sev success_severity) const;
 
template <>
MoFEMErrorCode TestingInterface::checkValue<TestType::SCALAR>(
    const std::string &check_name, PetscReal actual, PetscReal expected,
    Tolerance tolerance, Sev error_severity, Sev success_severity) const;
 
template <>
MoFEMErrorCode TestingInterface::checkValue<TestType::POINTWISE>(
    const std::string &check_name, PetscReal actual, PetscReal expected,
    Tolerance tolerance, Sev error_severity, Sev success_severity) const;
 
template <>
MoFEMErrorCode TestingInterface::checkValue<TestType::DERIVATIVE>(
    const std::string &check_name, PetscReal actual, PetscReal expected,
    Tolerance tolerance, Sev error_severity, Sev success_severity) const;
 
template <>
MoFEMErrorCode TestingInterface::checkValue<TestType::SOLVER>(
    const std::string &check_name, PetscReal actual, PetscReal expected,
    Tolerance tolerance, Sev error_severity, Sev success_severity) const;
 
/** Create an owned interface; the referenced Core must outlive it.
 * Core normally owns this object; use getInterface<TestingInterface>() to borrow it.
 */
template <>
TestingInterface *createInterface<TestingInterface>(const MoFEM::Core &core);
 
} // namespace MoFEM
 
#endif // MOFEM_TESTING_INTERFACE_HPP