Step 3: Call NOX from your code

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.

Step A: Instantiate a Group object containing the initial guess.

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.

Step B: Construct the status tests

The NOX::StatusTest objects are used to determine when NOX should terminate the iterative process due to either convergence or failure. For example...

• The NOX::StatusTest::MaxIters test is used to control the maximum number of iterations that the nonlinear solver is allowed to take.

• The NOX::StatusTest::NormF test checks the size of . This check can be done based on relative or absolute norms, scaled by , and more. See the description for more details.

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.

Step C: Set the solver parameters

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.

Step D: Construct the solver and solve

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();

If you have problems...

Please report any issues regarding NOX and LOCA to Bugzilla; see Reporting Bugs and Making Enhancement Requests for more information.

Moving on...

Go on to Step 4: Link your code to NOX.