#include "src/interfaces/TestingInterface.hpp"

Inheritance diagram for MoFEM::TestingInterface:

Collaboration diagram for MoFEM::TestingInterface:

Classes
struct	Tolerance

Public Types
using	TSCheck = std::function< MoFEMErrorCode(TS, PetscInt, PetscReal, Vec)>

using	FieldEvaluatorHook = std::function< MoFEMErrorCode(boost::ptr_deque< ForcesAndSourcesCore::UserDataOperator > &)>

using	TestHook = std::function< MoFEMErrorCode()>

Public Member Functions
	~TestingInterface () override=default

virtual MoFEMErrorCode	getOptions (const std::string &prefix="") const =0

virtual MoFEMErrorCode	checkSolver (TS ts, const std::string &check_name) const =0

virtual MoFEMErrorCode	addTSMonitor (TS ts, TSCheck check)=0

virtual MoFEMErrorCode	addTSMonitor (const std::string &prefix, int number, const std::string &name, TS ts, TSCheck check)=0

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)

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

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

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

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

virtual MoFEMErrorCode	checkSolver (TS ts, PetscReal expected_time, Tolerance tolerance, const std::string &check_name) const =0

virtual MoFEMErrorCode	checkSolver (SNES snes, const std::string &check_name) const =0

virtual MoFEMErrorCode	checkSolver (KSP ksp, const std::string &check_name) const =0

virtual MoFEMErrorCode	checkSolver (Tao tao, const std::string &check_name) const =0

virtual MoFEMErrorCode	addTest (int number, const std::string &name, TestHook hook)=0

virtual MoFEMErrorCode	runTest (int number) const =0

virtual MoFEMErrorCode	runTest (const std::string &name) const =0

virtual MoFEMErrorCode	runTests () const =0

virtual bool	checkTest (int number) const =0

virtual bool	checkTest (const std::string &name) const =0

virtual MoFEMErrorCode	runTestCommandLine (const std::string &prefix="") const =0

virtual MoFEMErrorCode	addTestCommandLine (const std::string &prefix, int number, const std::string &name, TestHook hook)=0

template<>
MoFEMErrorCode	addFieldEvaluator (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	addFieldEvaluator (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	addFieldEvaluator (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	addFieldEvaluator (const std::string &problem, const std::string &finite_element, const std::array< double, 3 > &field_eval_coords, FieldEvaluatorHook hook, double distance, bool *point_found)

Public Member Functions inherited from MoFEM::UnknownInterface
virtual MoFEMErrorCode	query_interface (boost::typeindex::type_index type_index, UnknownInterface **iface) const =0

template<class IFACE >
MoFEMErrorCode	registerInterface (bool error_if_registration_failed=true)
	Register interface.

template<class IFACE >
MoFEMErrorCode	getInterface (IFACE *&iface) const
	Get interface reference to pointer of interface.

template<class IFACE >
MoFEMErrorCode	getInterface (IFACE **const iface) const
	Get interface pointer to pointer of interface.

template<class IFACE , typename boost::enable_if< boost::is_pointer< IFACE >, int >::type = 0>
IFACE	getInterface () const
	Get interface pointer to pointer of interface.

template<class IFACE , typename boost::enable_if< boost::is_reference< IFACE >, int >::type = 0>
IFACE	getInterface () const
	Get reference to interface.

template<class IFACE >
IFACE *	getInterface () const
	Function returning pointer to interface.

virtual	~UnknownInterface ()=default

Additional Inherited Members
Static Public Member Functions inherited from MoFEM::UnknownInterface
static MoFEMErrorCode	getLibVersion (Version &version)
	Get library version.

static MoFEMErrorCode	getFileVersion (moab::Interface &moab, Version &version)
	Get database major version.

static MoFEMErrorCode	setFileVersion (moab::Interface &moab, Version version=Version(MoFEM_VERSION_MAJOR, MoFEM_VERSION_MINOR, MoFEM_VERSION_BUILD))
	Get database major version.

static MoFEMErrorCode	getInterfaceVersion (Version &version)
	Get database major version.

Detailed Description

Examples: mofem/atom_tests/field_evaluator.cpp, mofem/tutorials/adv-0_plasticity/plastic.cpp, mofem/tutorials/adv-3_level_set/level_set.cpp, mofem/tutorials/adv-4_dynamic_first_order_con_law/dynamic_first_order_con_law.cpp, mofem/tutorials/adv-5_poroelasticity/seepage.cpp, mofem/tutorials/adv-6_dg_projection/between_meshes_dg_projection.cpp, mofem/tutorials/clx-0_acoustics/helmholtz.cpp, mofem/tutorials/cor-6_simple_elasticity/simple_elasticity.cpp, mofem/tutorials/cor-7_elasticity_mixed_formulation/elasticity_mixed_formulation.cpp, mofem/tutorials/cor-9_reaction_diffusion/reaction_diffusion.cpp, mofem/tutorials/mix-0_mixed_poisson/mixed_poisson.cpp, mofem/tutorials/mix-1_light_intensity_equation/phase.cpp, mofem/tutorials/scl-0_least_squares/approximation.cpp, mofem/tutorials/scl-1_poisson_2d_homogeneous/poisson_2d_homogeneous.cpp, mofem/tutorials/scl-6_heat_equation/heat_equation.cpp, mofem/tutorials/scl-7_wave_equation/wave_equation.cpp, mofem/tutorials/scl-8_heat_radiation/radiation.cpp, mofem/tutorials/scl-9_heat_method/heat_method.cpp, mofem/tutorials/vec-10_elasticity_schur/schur_elastic.cpp, mofem/tutorials/vec-3_nonlinear_dynamics/nonlinear_dynamic_elastic.cpp, mofem/tutorials/vec-4_shallow_wave/approx_sphere.cpp, mofem/tutorials/vec-4_shallow_wave/shallow_wave.cpp, mofem/tutorials/vec-5_free_surface/free_surface.cpp, mofem/tutorials/vec-6_dg_kirchhoff_plate/plate.cpp, and mofem/tutorials/vec-7_shape_optimisation/adjoint.cpp.

Definition at line 35 of file TestingInterface.hpp.

Member Typedef Documentation

◆ FieldEvaluatorHook

using MoFEM::TestingInterface::FieldEvaluatorHook = std::function<MoFEMErrorCode( boost::ptr_deque<ForcesAndSourcesCore::UserDataOperator> &)>

Definition at line 83 of file TestingInterface.hpp.

◆ TestHook

using MoFEM::TestingInterface::TestHook = std::function<MoFEMErrorCode()>

Definition at line 191 of file TestingInterface.hpp.

◆ TSCheck

using MoFEM::TestingInterface::TSCheck = std::function<MoFEMErrorCode(TS, PetscInt, PetscReal, Vec)>

Definition at line 47 of file TestingInterface.hpp.

Constructor & Destructor Documentation

◆ ~TestingInterface()

MoFEM::TestingInterface::~TestingInterface ( )

overridedefault

Member Function Documentation

◆ addFieldEvaluator() [1/6]

template<>

MoFEMErrorCode MoFEM::TestingInterface::addFieldEvaluator	(	const std::string &	problem,
		const std::string &	finite_element,
		const std::array< double, 3 > &	field_eval_coords,
		FieldEvaluatorHook	hook,
		double	distance,
		bool *	point_found
	)

Definition at line 679 of file TestingInterface.cpp.

                                        {
  return addFieldEvaluator(2, problem, finite_element, field_eval_coords,
                           std::move(hook), distance, point_found);
}

◆ addFieldEvaluator() [2/6]

template<>

MoFEMErrorCode MoFEM::TestingInterface::addFieldEvaluator	(	const std::string &	problem,
		const std::string &	finite_element,
		const std::array< double, 3 > &	field_eval_coords,
		FieldEvaluatorHook	hook,
		double	distance,
		bool *	point_found
	)

Definition at line 688 of file TestingInterface.cpp.

                                        {
  return addFieldEvaluator(3, problem, finite_element, field_eval_coords,
                           std::move(hook), distance, point_found);
}

◆ addFieldEvaluator() [3/6]

template<>

MoFEMErrorCode MoFEM::TestingInterface::addFieldEvaluator	(	const std::string &	problem,
		const std::string &	finite_element,
		const std::array< double, 3 > &	field_eval_coords,
		FieldEvaluatorHook	hook,
		double	distance,
		bool *	point_found
	)

◆ addFieldEvaluator() [4/6]

template<>

MoFEMErrorCode MoFEM::TestingInterface::addFieldEvaluator	(	const std::string &	problem,
		const std::string &	finite_element,
		const std::array< double, 3 > &	field_eval_coords,
		FieldEvaluatorHook	hook,
		double	distance,
		bool *	point_found
	)

◆ addFieldEvaluator() [5/6]

template<int DIM>

MoFEMErrorCode MoFEM::TestingInterface::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`
	)

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.

◆ addFieldEvaluator() [6/6]

virtual MoFEMErrorCode MoFEM::TestingInterface::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`
	)

pure virtual

Evaluate a point in dimension 2 or 3.

◆ addTest()

virtual MoFEMErrorCode MoFEM::TestingInterface::addTest	(	int	number,
		const std::string &	name,
		TestHook	hook
	)

pure virtual

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.

◆ addTestCommandLine()

virtual MoFEMErrorCode MoFEM::TestingInterface::addTestCommandLine	(	const std::string &	prefix,
		int	number,
		const std::string &	name,
		TestHook	hook
	)

pure virtual

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.

Examples: mofem/tutorials/adv-4_dynamic_first_order_con_law/dynamic_first_order_con_law.cpp, mofem/tutorials/clx-0_acoustics/helmholtz.cpp, mofem/tutorials/cor-6_simple_elasticity/simple_elasticity.cpp, mofem/tutorials/vec-3_nonlinear_dynamics/nonlinear_dynamic_elastic.cpp, and mofem/tutorials/vec-7_shape_optimisation/adjoint.cpp.

◆ addTSMonitor() [1/2]

virtual MoFEMErrorCode MoFEM::TestingInterface::addTSMonitor	(	const std::string &	prefix,
		int	number,
		const std::string &	name,
		TS	ts,
		TSCheck	check
	)

pure virtual

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.

◆ addTSMonitor() [2/2]

virtual MoFEMErrorCode MoFEM::TestingInterface::addTSMonitor	(	TS	ts,
		TSCheck	check
	)

pure virtual

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.

◆ checkError() [1/2]

template<TestType TYPE>

MoFEMErrorCode MoFEM::TestingInterface::checkError	(	const std::string &	check_name,
		PetscReal	error,
		PetscReal	scale,
		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.

◆ checkError() [2/2]

virtual MoFEMErrorCode MoFEM::TestingInterface::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

pure virtual

Compare an error using the specified check category.

◆ checkSolver() [1/5]

virtual MoFEMErrorCode MoFEM::TestingInterface::checkSolver	(	KSP	ksp,
		const std::string &	check_name
	)		const

pure virtual

Require KSP convergence; an unsolved solver fails this direct check.

◆ checkSolver() [2/5]

virtual MoFEMErrorCode MoFEM::TestingInterface::checkSolver	(	SNES	snes,
		const std::string &	check_name
	)		const

pure virtual

Require SNES convergence and check its KSP if it has run.

◆ checkSolver() [3/5]

virtual MoFEMErrorCode MoFEM::TestingInterface::checkSolver	(	Tao	tao,
		const std::string &	check_name
	)		const

pure virtual

Require TAO convergence under its configured convergence test. Does not independently test the raw objective gradient or custom subsolvers.

◆ checkSolver() [4/5]

virtual MoFEMErrorCode MoFEM::TestingInterface::checkSolver	(	TS	ts,
		const std::string &	check_name
	)		const

pure virtual

Check convergence and the configured final time, respecting STEPOVER.

◆ checkSolver() [5/5]

virtual MoFEMErrorCode MoFEM::TestingInterface::checkSolver	(	TS	ts,
		PetscReal	expected_time,
		Tolerance	tolerance,
		const std::string &	check_name
	)		const

pure virtual

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.

◆ checkTest() [1/2]

virtual bool MoFEM::TestingInterface::checkTest ( const std::string & name ) const

pure virtual

True if a test or selected TS monitor with this name is registered.

◆ checkTest() [2/2]

virtual bool MoFEM::TestingInterface::checkTest ( int number ) const

pure virtual

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.

◆ checkValue()

template<TestType TYPE>

MoFEMErrorCode MoFEM::TestingInterface::checkValue	(	const std::string &	check_name,
		PetscReal	actual,
		PetscReal	expected,
		Tolerance	tolerance,
		Sev	error_severity = `Sev::error`,
		Sev	success_severity = `Sev::inform`
	)		const

Compare real scalars with scale = abs(expected).

◆ getOptions()

virtual MoFEMErrorCode MoFEM::TestingInterface::getOptions ( const std::string & prefix = "" ) const

pure virtual

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.

◆ runTest() [1/2]

virtual MoFEMErrorCode MoFEM::TestingInterface::runTest ( const std::string & name ) const

pure virtual

Run one previously registered test, looked up by name. Logs a warning and skips the test if that name is not registered.

◆ runTest() [2/2]

virtual MoFEMErrorCode MoFEM::TestingInterface::runTest ( int number ) const

pure virtual

Run one previously registered test, looked up by number. Logs a warning and skips the test if that number is not registered.

◆ runTestCommandLine()

virtual MoFEMErrorCode MoFEM::TestingInterface::runTestCommandLine ( const std::string & prefix = "" ) const

pure virtual

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.

◆ runTests()

virtual MoFEMErrorCode MoFEM::TestingInterface::runTests ( ) const

pure virtual

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.

The documentation for this struct was generated from the following files:

src/interfaces/TestingInterface.hpp
src/interfaces/impl/TestingInterface.cpp

Classes

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ FieldEvaluatorHook

◆ TestHook

◆ TSCheck

Constructor & Destructor Documentation

◆ ~TestingInterface()

Member Function Documentation

◆ addFieldEvaluator() [1/6]

◆ addFieldEvaluator() [2/6]

◆ addFieldEvaluator() [3/6]

◆ addFieldEvaluator() [4/6]

◆ addFieldEvaluator() [5/6]

◆ addFieldEvaluator() [6/6]

◆ addTest()

◆ addTestCommandLine()

◆ addTSMonitor() [1/2]

◆ addTSMonitor() [2/2]

◆ checkError() [1/2]

◆ checkError() [2/2]

◆ checkSolver() [1/5]

◆ checkSolver() [2/5]

◆ checkSolver() [3/5]

◆ checkSolver() [4/5]

◆ checkSolver() [5/5]

◆ checkTest() [1/2]

◆ checkTest() [2/2]

◆ checkValue()

◆ getOptions()

◆ runTest() [1/2]

◆ runTest() [2/2]

◆ runTestCommandLine()

◆ runTests()