gui_xmldoc.html.svn-base

OPT++

Application Interface Code</a> section.  The "Problem Setup" panel for
an application-based problem is shown below.

<IMG src="../images/maui_application.png" ALIGN=center><BR>

For both the subroutine and the application interfaces, you are
required to provide information about the variables and the
constraints on the tabbed panels on the lower half of the "Problem
Setup" panel.  You must enter the number of variables and constraints
where requested.  To add a variable/constraint, click on the "Add"
button; to edit, double click on the label of the variable/constraint
you wish to edit; to remove a variable/constraint, highlight its label
and click on the "Remove" button.  For each variable, you must provide
a label.  If you are using the application interface, this label must
be the same as the corresponding keyword in the templated application
input deck.  You may provide an initial value or retain the default of
zero.  You may also provide bounds on the variable if there are any.
The linear constraints are linear constraints on the control
(optimization) variables only.  Linear constraints and bounds on state
variables are treated as nonlinear constraints.  The label for the
linear constraints can be anything you like, though we recommend that
it be descriptive of the phenomenon it is describing.  You will also
need to add the list of variables and corresponding coefficients in
the linear expression (only for those variables with non-zero
coefficients).  Choose the comparison operator and provide the
right-hand side if it is non-zero.  The nonlinear constraint editor
looks very similar to the "Problem Setup" panel, so we will not
discuss it here.  Below is a figure that shows the variable and linear
constraint editors with example entries.

<IMG src="../images/maui_arrays.png" ALIGN=center><BR>

Now that your problem description is complete, it is now time to
choose an algorithm.

\section algorithm Setting up the Algorithm

To set up the algorithm you will use to solve your optimization
problem, click on the "Optimization Algorithm" Panel.  As you can see
in the figure below, there is a choice of algorithms.  There is a
nonlinear interior-point method (the default), a parallel direct
search method, and the classic Newton and CG methods.  There are a few
basic algorithmic parameters that are associated with all algorithms.
The meaning of these parameters is fairly straightforward.  In
addition, most of the algorithms have some algorithm-specific
parameters.  All parameters are set to default values that should be
fairly reasonable for many problems.  Where appropriate, the help
messages provide some guidance for how to set these parameters if you
choose to change their values.

<IMG src="../images/maui_nips.png">

In addition the basic parameters, there are some advanced algorithmic
parameters that are associated with all of the algorithms, as shown
below.  These are more complex parameters whose meanings are not as
straightforward as those of the basic parameters.  They are each
assigned default values, and guidance for setting their values is
provided in the help messages where appropriate.

<IMG src="../images/maui_advanced.png" ALIGN=center> <br>

Once you have set up the problem, chosen the algorithm, and set any
desired parameters, you are ready to save the information from the GUI
to an XML file, {filename}.xml, and solve the optimization problem by
executing the following command:

   \verbatim
      opt++.e {filename}.xml
   \endverbatim
   OR
   \verbatim
      mpirun -np {number of procs} opt++.e {name of XML file}, <br>
      if you are using MPI.
   \endverbatim

\section code Code You Need to Provide

<a name="subroutine"><em> Subroutine Interface </em></a>

The subroutine interface is quite similar to the problem set-up
defined in the <a href="SetUp.html"> Setting up and Solving an
Optimization Problem</a> section.  There are a few exceptions,
however.  First, you do not need to provide a main routine.  Next, the
initialization of the optimization variables does not need to be done
in the initialization subroutine.  Both of these are now done for you,
based on the information you provide in the GUI/XML interface.
Finally, the initialization and function subroutines must be contained
in a dynamically loadable library.  Documented code and detailed
instructions on building the library can be found in the following two
examples.

<ul>
  <li> \ref subroutine1
  <li> \ref subroutine2
</ul>

<a name="application"><em> Application Interface </em></a>

For the application interface, the code varies according to the
application.  What you need to provide is an executable (compiled or
script) whose final result will be a file named "fvalue.out"
("convalue.out" in the case of a nonlinear constraint) that contains a
single number...the function value.  OPT++ does not care about
anything else that happens in between.  The most important thing is to
ensure that the directory structure is correct and that the files are
located in the right place.

First you must create a directory to hold all of the model
information.  In our case, we will create the directory "TooMuchFun"
in our home directory.  We will then create a subdirectory,
"makecopies".  (The subdirectory must be named "makecopies".)

<ul>
   <li> mkdir TooMuchFun <br>
   <li> cd TooMuchFun <br>
   <li> mkdir makecopies
</ul>

In the application directory, you must place any user-created files
that are needed by the application.  This includes things like mesh
files and any executables that are not in your path or for which you
have not listed the full path in the OPT++ input.  In our case, we
will put rosen.e in the TooMuchFun directory.  This is our application
executable, we did not include the path in the OPT++ input, and it
cannot be accessed given our current path.  We also recomment putting
the XML input file for OPT++ in this directory, but it is not
necessary.

In the "makecopies", you must place the templated input deck and any
other application files that will be modified by the application
during the execution of the application.  In this case, our
application input deck is named "rosen.in", so we will place
"rosen.in.Tmplt" in "makecopies".  (The templated input file must have
a file extension of ".Tmplt".)  This templated input deck has keywords
placed in the locations where the values of the optimization variables
should appear.  For this very simple case, our templated input deck
looks like the following:

   \verbatim
   var1 = OPT_x1 
   var2 = OPT_x2
   \endverbatim

OPT_x1 and OPT_x2 are the keywords associated with the optimization
variables.

The most common mistakes are to forget a file, to misname it, or to
put it in the wrong location.  So if you have trouble getting things
to work and you can't find the problem elsewhere, be sure that your
application directories are set up correctly.

\section xml Creating an XML Input File Without the GUI

If you would like to create an XML input file for OPT++ but cannot or
choose not to use the GUI, we describe the form of that file here.
Please be aware that you still have build OPT++ as described in
<a href="InstallDoc.html#gui"> Configuring for use with the new (beta)
GUI/XML Interface</a> section of the <a href="InstallDoc.html">
Installation Documentation</a>.  Also, should you decide to use the
GUI at some later time, we currently cannot guarantee it will read
files you construct in this way.  (It is on the to-do list...)  You
can find many examples in the OPT++/tests/xml directory.  Note that
those examples were created using the GUI, so they have some
additional things, like comments, that are not required by OPT++.  We
show the XML files for the examples in the \ref code section.

<ul>
  <li> \ref xml1
  <li> \ref xml2
  <li> \ref xml3
</ul>

<p> Previous Section:  \ref SetUp | Next Section:  \ref Classification
| Back to the <a href="index.html"> Main Page</a> </p>

Last revised <em> July 25, 2006</em>


*/