NOX::StatusTest::Factory Class Reference

Factory to build a set of status tests from a parameter list. More...

#include <NOX_StatusTest_Factory.H>

List of all members.

Public Member Functions
	Factory ()
	Constructor.
virtual	~Factory ()
	Destructor.
Teuchos::RCP < NOX::StatusTest::Generic >	buildStatusTests (const std::string &file_name, const NOX::Utils &utils, std::map< std::string, Teuchos::RCP< NOX::StatusTest::Generic > > *tagged_tests=0) const
	Returns a status test set from a parameter list xml file.
Teuchos::RCP < NOX::StatusTest::Generic >	buildStatusTests (Teuchos::ParameterList &p, const NOX::Utils &utils, std::map< std::string, Teuchos::RCP< NOX::StatusTest::Generic > > *tagged_tests=0) const
	Returns a status test set from a parameter list.
Private Member Functions
Teuchos::RCP < NOX::StatusTest::Generic >	buildComboTest (Teuchos::ParameterList &p, const NOX::Utils &utils, std::map< std::string, Teuchos::RCP< NOX::StatusTest::Generic > > *tagged_tests=0) const
Teuchos::RCP < NOX::StatusTest::Generic >	buildNormFTest (Teuchos::ParameterList &p, const NOX::Utils &utils) const
Teuchos::RCP < NOX::StatusTest::Generic >	buildNormUpdateTest (Teuchos::ParameterList &p, const NOX::Utils &utils) const
Teuchos::RCP < NOX::StatusTest::Generic >	buildNormWRMSTest (Teuchos::ParameterList &p, const NOX::Utils &utils) const
Teuchos::RCP < NOX::StatusTest::Generic >	buildMaxItersTest (Teuchos::ParameterList &p, const NOX::Utils &utils) const
Teuchos::RCP < NOX::StatusTest::Generic >	buildFiniteValueTest (Teuchos::ParameterList &p, const NOX::Utils &utils) const
Teuchos::RCP < NOX::StatusTest::Generic >	buildDivergenceTest (Teuchos::ParameterList &p, const NOX::Utils &utils) const
Teuchos::RCP < NOX::StatusTest::Generic >	buildStagnationTest (Teuchos::ParameterList &p, const NOX::Utils &utils) const
Teuchos::RCP < NOX::StatusTest::Generic >	buildUserDefinedTest (Teuchos::ParameterList &p, const NOX::Utils &utils) const
bool	checkAndTagTest (const Teuchos::ParameterList &p, const Teuchos::RCP< NOX::StatusTest::Generic > &test, std::map< std::string, Teuchos::RCP< NOX::StatusTest::Generic > > *tagged_tests) const
	Checks if a tag is present in the param list and adds the test to the tagged_test std::map if true. Returns true if a tag was present.
Related Functions
(Note that these are not member functions.)
Teuchos::RCP < NOX::StatusTest::Generic >	buildStatusTests (const std::string &file_name, const NOX::Utils &utils, std::map< std::string, Teuchos::RCP< NOX::StatusTest::Generic > > *tagged_tests=0)
	Nonmember helper function for the NOX::StatusTest::Factory.
Teuchos::RCP < NOX::StatusTest::Generic >	buildStatusTests (Teuchos::ParameterList &p, const NOX::Utils &utils, std::map< std::string, Teuchos::RCP< NOX::StatusTest::Generic > > *tagged_tests=0)
	Nonmember helper function for the NOX::StatusTest::Factory.

---

Detailed Description

Factory to build a set of status tests from a parameter list.

This object takes either an xml file name or a Teuchos::ParameterList and generates an entire set (a tree) of status tests for use in a NOX::Solver derived object.

The tagged_tests field in the constructors allows users to store tests from the tree in a flat list in case they want to change the tolerance values during a run. The tagged_tests flag is optional.

Please use the related nonmember functions instead of calling the factory directly (See example below).

Valid parameters are as follows:

• "Test Type" <std::string> Type of test this list contains. Valid tests include:
  • "Combo" - NOX::StatusTest::Combo
  • "NormF" - NOX::StatusTest::NormF
  • "NormUpdate" - NOX::StatusTest::NormUpdate
  • "NomrWRMS" - NOX::StatusTest::NormWRMS
  • "MaxIters" - NOX::StatusTest::MaxIters
  • "FiniteValue" - NOX::StatusTest::FiniteValue
  • "Divergence" - NOX::StatusTest::Divergence
  • "Stagnation" - NOX::StatusTest::Stagnation
  • "User Defined" - A user constructed test, derived from NOX::StatusTest::Generic.

• "Tag" <std::string> A unique identifier that will place the test in the map for tagged_tests. This allows users to access individual tests to change tolerances on the fly or query values while still using the factory to build objects.

Additional parameters valid for a Combo test (NOX::StatusTest::Combo):

• "Combo Type" <std:string> Type of combo to use. Valid options are:
  • "AND"
  • "OR"

• "Number of Tests" <int> Number of sublists that contain tests to be added to this combo test. The sublists must be named "Test X" where "X" represents the test number starting with 0 and preceeding to "Number of Tests - 1".

• "Test X" <Teuchos::ParameterList> A sublist containing a test to add to the current combo test. The "X" represents the number of the test. the numbering starts with 0 and is valid through "Number of Tests - 1" tests.

Additional parameters valid for a Norm F test (NOX::StatusTest::NormF):

• "Tolerance" <double> required tolerance for the test to return a converged status. (default = 1.0e-8)
• "Norm Type" <std::string> Type of norm to use. Valid options are:
  • "Two Norm" (default)
  • "One Norm"
  • "Max Norm"
• "Scale Type" <std::string> Type of scaling to use. Valid options are:
  • "Unscaled" (default)
  • "Scaled"
• "Initial Guess" < Teuchos::RCP<NOX::Abstract::Group> > If present, a relative tolerance will be used where the group passed in will be used to compute .

Additional parameters valid for a Norm Update test (NOX::StatusTest::NormUpdate):

• "Tolerance" <double> required tolerance for the test to return a converged status. (default = 1.0e-3)
• "Norm Type" <std::string> Type of norm to use. Valid options are:
  • "Two Norm" (default)
  • "One Norm"
  • "Max Norm"
• "Scale Type" <std::string> Type of scaling to use. Valid options are:
  • "Unscaled" (default)
  • "Scaled"

Additional parameters valid for a Norm WRMS test (NOX::StatusTest::NormWRMS):

• "Tolerance" <double> (default = 1.0)
• "Relative Tolerance" <double> (default = 1.0e-5)
• "Absolute Tolerance" <double> or < Teuchos::RCP<const NOX::Abstract::Vector> > (default = 1.0e-8)
• "BDF Multiplier" <double> (default = 1.0)
• "Alpha" <double> (default = 1.0)
• "Beta" <double> (default = 0.5)

Additional parameters valid for a Maximum Iterations test (NOX::StatusTest::MaxIters):

• "Maximum Iterations" <int>

Additional parameters valid for a Finite Value test (NOX::StatusTest::FiniteValue):

• "Vector Type" <std::string> Type of vector to check. Valid options are:
  • "F Vector" (default)
  • "Solution Vector"
• "Norm Type" <std::string> Type of norm to use. Valid options are:
  • "Two Norm" (default)
  • "One Norm"
  • "Max Norm"

Additional parameters valid for a Divergence test (NOX::StatusTest::Divergence):

• "Tolerance" <double> (default = 1.0e+12)
• "Consecutive Iterations" <int> (default = 1)

Additional parameters valid for a Stagnation test (NOX::StatusTest::Stagnation):

• "Tolerance" <double> (default = 1.0e+12)
• "Consecutive Iterations" <int> (default = 1)

Additional parameters valid for a "User Defined" test:

• "User Status Test" < Teuchos::RCP<NOX::StatusTest::Generic> > A status test suppied by the user. It is very important that when registering this status test, that the user set it as a "Generic" object since there is no implicit casting on the ParameterList's get method. See the example below.

Example usage:

     Teuchos::ParameterList stl;
     stl.set("Test Type", "Combo");
     stl.set("Combo Type", "OR");
     stl.set("Number of Tests", 5);
     Teuchos::ParameterList& conv = stl.sublist("Test 0");
     Teuchos::ParameterList& fv = stl.sublist("Test 1");
     Teuchos::ParameterList& divergence = stl.sublist("Test 2");
     Teuchos::ParameterList& stagnation = stl.sublist("Test 3");
     Teuchos::ParameterList& maxiters = stl.sublist("Test 4");
     
     conv.set("Test Type", "Combo");
     conv.set("Combo Type", "AND");
     conv.set("Number of Tests", 4);
     Teuchos::ParameterList& normF = conv.sublist("Test 0");
     Teuchos::ParameterList& normWRMS = conv.sublist("Test 1");
     Teuchos::ParameterList& normUpdate = conv.sublist("Test 2");
     Teuchos::ParameterList& userDefined = conv.sublist("Test 3");
     normF.set("Test Type", "NormF");
     normF.set("Tolerance", 1.0e-12);
     normF.set("Norm Type", "Two Norm");
     normF.set("Scale Type", "Unscaled");
     normWRMS.set("Test Type", "NormWRMS");
     normWRMS.set("Absolute Tolerance", 1.0e-8);
     normWRMS.set("Relative Tolerance", 1.0e-5);
     normWRMS.set("Tolerance", 1.0);
     normWRMS.set("BDF Multiplier", 1.0);
     normWRMS.set("Alpha", 1.0);
     normWRMS.set("Beta", 0.5);
     normUpdate.set("Test Type", "NormUpdate");
     normUpdate.set("Norm Type", "One Norm");
     normUpdate.set("Scale Type", "Scaled");
     userDefined.set("Test Type", "User Defined");
     Teuchos::RCP<NOX::StatusTest::Generic> myTest =
       Teuchos::rcp(new MyTest(1.0e-3));
     userDefined.set("User Status Test", myTest);

     
     fv.set("Test Type", "FiniteValue");
     fv.set("Vector Type", "F Vector");
     fv.set("Norm Type", "Two Norm");
     
     divergence.set("Test Type", "Divergence");
     divergence.set("Tolerance", 1.0e+20);
     divergence.set("Consecutive Iterations", 3);
     
     stagnation.set("Test Type", "Stagnation");
     stagnation.set("Tolerance", 1.0);
     stagnation.set("Consecutive Iterations", 5);
     
     maxiters.set("Test Type", "MaxIters");
     maxiters.set("Maximum Iterations", 20);
     
     Teuchos::RCP<NOX::StatusTest::Generic> status_tests = 
       NOX::StatusTest::buildStatusTests(stl, utils);

Author:

Roger Pawlowski (SNL 1416)

Definition at line 250 of file NOX_StatusTest_Factory.H.

---

Constructor & Destructor Documentation

NOX::StatusTest::Factory::Factory

(

)

Constructor.

Definition at line 69 of file NOX_StatusTest_Factory.C.

NOX::StatusTest::Factory::~Factory

(

)

[virtual]

Destructor.

Definition at line 74 of file NOX_StatusTest_Factory.C.

---

Member Function Documentation

Teuchos::RCP< NOX::StatusTest::Generic > NOX::StatusTest::Factory::buildStatusTests	(	const std::string &	file_name,
		const NOX::Utils &	utils,
		std::map< std::string, Teuchos::RCP< NOX::StatusTest::Generic > > *	tagged_tests = 0
	)			const

Returns a status test set from a parameter list xml file.

Definition at line 80 of file NOX_StatusTest_Factory.C.

Teuchos::RCP< NOX::StatusTest::Generic > NOX::StatusTest::Factory::buildStatusTests	(	Teuchos::ParameterList &	p,
		const NOX::Utils &	utils,
		std::map< std::string, Teuchos::RCP< NOX::StatusTest::Generic > > *	tagged_tests = 0
	)			const

Returns a status test set from a parameter list.

Definition at line 101 of file NOX_StatusTest_Factory.C.

References checkAndTagTest().

bool NOX::StatusTest::Factory::checkAndTagTest	(	const Teuchos::ParameterList &	p,
		const Teuchos::RCP< NOX::StatusTest::Generic > &	test,
		std::map< std::string, Teuchos::RCP< NOX::StatusTest::Generic > > *	tagged_tests
	)			const [private]

Checks if a tag is present in the param list and adds the test to the tagged_test std::map if true. Returns true if a tag was present.

Definition at line 430 of file NOX_StatusTest_Factory.C.

Referenced by buildStatusTests().

---

Friends And Related Function Documentation

Teuchos::RCP< NOX::StatusTest::Generic > buildStatusTests	(	const std::string &	file_name,
		const NOX::Utils &	utils,
		std::map< std::string, Teuchos::RCP< NOX::StatusTest::Generic > > *	tagged_tests = 0
	)			[related]

Nonmember helper function for the NOX::StatusTest::Factory.

Teuchos::RCP< NOX::StatusTest::Generic > buildStatusTests	(	Teuchos::ParameterList &	p,
		const NOX::Utils &	utils,
		std::map< std::string, Teuchos::RCP< NOX::StatusTest::Generic > > *	tagged_tests = 0
	)			[related]

Nonmember helper function for the NOX::StatusTest::Factory.

---

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

• NOX_StatusTest_Factory.H
• NOX_StatusTest_Factory.C