A small example based on the NOX::LAPACK Vector and Group is included with NOX; see the file Trilinos/packages/nox/examples/lapack/NOX_SimpleExamples/Rosenbrock.C.
There are four steps to calling the solver.
The first step is to somehow construct an object deriving from the Abstract::Group which contains the initial guess as its x-vector. See Step 2: Create concrete implementations of the NOX::Abstract classes for more details. For example:
// Construct an object that derives from the abstract Group object. Here // we call it the ExampleGroup. It should contain the initial guess. Teuchos::RCP<UserConcreteGroup> grp = Teuchos::rcp(new UserConcreteGroup);
Note that the group is not handled as a raw pointer, but is wrapped in a reference counter smart pointer (RCP). RCPs enforce strict memory management in NOX and LOCA and can prevent many errors that users have encountered with objects going out of scope. We use the RCP implementation in the Trilinos package Teuchos. For information on the use of smart pointers, see Teuchos Reference Counted Pointer Beginners Guide.
The NOX::StatusTest objects are used to determine when NOX should terminate the iterative process due to either convergence or failure. For example...
These and other status tests can be combined using the NOX::StatusTest::Combo object. It takes an arbitrary number of status tests and either AND's or OR's them together.
Alternatively, users can build a set of status tests from a Teuchos::ParameterList by using the NOX::StatusTest::Factory object. See NOX::StatusTest::Factory for parameter list arguments and examples.
Finally, the user can create their own status tests, so long as they derive from NOX::StatusTest::Generic.
Here is some sample code.
// Set up the status tests Teuchos::RCP<NOX::StatusTest::NormF> statusTestNormF = Teuchos::rcp(new NOX::StatusTest::NormF(1.0e-4)); Teuchos::RCP<NOX::StatusTest::MaxIters> statusTestMaxIters = Teuchos::rcp(new NOX::StatusTest::MaxIters(20)); Teuchos::RCP<NOX::StatusTest::Combo> statusTestsCombo = Teuchos::rcp(new NOX::StatusTest::Combo(NOX::StatusTest::Combo::OR, statusTestNormF, statusTestMaxIters));
This test uses an OR combination, meaning that either test registered with the Combo test can trigger termination. The first test requires that the norm of the residual is less that 1.0e-4. If met, NOX will terminate returning a "Converged" result. The second test will trigger NOX to terminate if a maximum number of iterations is reached and return a "Failed" result.
Next, we set up a parameter list containing the information on what types of solvers and so forth should be used.
// Create the list of solver parameters Teuchos::RCP<Teuchos::ParameterList> solverParametersPtr = Teuchos::rcp(new Teuchos::ParameterList); // Select the solver (this is the default) solverParametersPtr->set("Nonlinear Solver", "Line Search Based"); // Create the line search parameters sublist Teuchos::ParameterList& lineSearchParameters = solverParametersPtr->sublist("Line Search"); // Set the line search method lineSearchParameters.set("Method","More'-Thuente");
For a full list of parameters; see NOX Parameter Reference Page.
The last step is to create the solver, passing in the group with the initial guess, the status tests, and the solver parameters.
// Create the solver Teuchos::RCP<NOX::Solver::Generic> solver = NOX::Solver::buildSolver(grp, statusTestsCombo, solverParametersPtr); // Solve the nonlinear system NOX::StatusTest::StatusType status = solver->solve(); // Print the parameter list cout << "\n" << "-- Parameter List From Solver --" << "\n"; solver->getList().print(cout); // Get the answer grp = solver->getSolutionGroup(); // Print the answer cout << "\n" << "-- Final Solution From Solver --" << "\n"; grp.printSolution();
Go on to Step 4: Link your code to NOX.