# nmplot

Provides direct search optimization algorithms.

## SYNOPSIS

                newobj = nmplot_new ()
                this = nmplot_destroy (this)
                this = nmplot_configure (this,key,value)
                value = nmplot_cget (this,key)
                this = nmplot_display ( this )
                value = nmplot_get ( this , key )
                this = nmplot_search ( this )
                this = nmplot_restart ( this )
                [ this , xdata , ydata , zdata ] = nmplot_contour ( this , xmin , xmax , ymin , ymax , nx , ny )
                this = nmplot_historyplot ( this , datafile  , mytitle , myxlabel , myylabel )
                this = nmplot_simplexhistory ( this , colorforeground , markforeground , markstyle )

## Description

This class provides several direct search optimization algorithms based on the simplex method.

The goal of this class is to provide a neldermead component with plotting features. It enables to make fast plots of the algorithm progress through the iterations.

It is a specialized neldermead class, with a specific output command. This output function allows to store the history of several data through the iterations of the algorithm. These data are :

- the history of the coordinates of the simplex ,

- the history of the function value (averaged on the vertices),

- the history of the minimum function value in the simplex,

- the history of the size of the simplex (as computed with the sigma+ method).

These data are stored into several data files during the optimization process. Several methods allows to plot the data stored into these data files.

## Design

The nmplot component is built on top of the neldermead component. The -outputcommand option (of the neldermead class) is not available since the nmplot class uses its own output function. Additional options -simplexfn, -fbarfn, -foptfn and -sigmafn are provided, which allows to configure the file names where the data is stored.

The nmplot class can be considered as a sample test case of the -outputcommand option of the neldermead class. It gives an example of the situation where the user wants to get specialized outputs out of the neldermead class.

## Functions

The following functions are available.

newobj = nmplot_new ()

  Creates a new nmplot object.

  newobj

    The new object.

this = nmplot_destroy (this)

  Destroy the given object.

  this

    The current object.

this = nmplot_configure (this,key,value)

  Configure the current object with the given value for the given key.

  this

    The current object.

  key

    a 1-by-1 matrix of strings, the key to configure.

    The following keys are available and delegated to the `neldermead` component: -verbose, -verbosetermination, -x0, -maxfunevals, -maxiter, -tolfunabsolute, -tolfunrelative, -tolfunmethod, -tolxabsolute, -tolxrelative, -tolxmethod, -function, -outputcommand, -numberofvariables, -storehistory, -boundsmin, -boundsmax, -nbineqconst, -method, -simplex0method, -coords0, -simplex0length, -simplex0deltausual, -simplex0deltazero, -rho, -chi, -gamma, -sigma, -tolfstdeviationmethod, -tolfstdeviation, -tolsimplexizemethod, -tolsimplexizeabsolute, -tolsimplexizerelative, -tolssizedeltafvmethod, -toldeltafv, -kelleystagnationflag, -kelleynormalizationflag, -kelleystagnationalpha0, -restartflag, -restartdetection, -restartmax, -restarteps, -restartstep, -restartsimplexmethod, -boxnbpoints, -nbineqloops, -ineqscaling. These options are documented in the help page of the `neldermead_configure` function.

    The following specific keys are available.

    -simplexfn

      the name of the file containing the history of the simplex (default simplexfn="").

    -fbarfn

      the name of the file containing the history of the function value, averaged on the vertices of the simplex (default fbarfn="").

    -foptfn

      the name of the file containing the history of the minimum function value in the simplex (default foptfn="").

    -sigmafn

      the name of the file containing the history of the size of the simplex (default sigmafn="").

  value

    the value.

value = nmplot_cget (this,key)

  Get the value for the given key. If the key is unknown, generates an error.

  this

    The current object.

  key

    a 1-by-1 matrix of strings, the name of the key to quiery. The list of available keys is the same as for the `nmplot_configure` function.

value = nmplot_get ( this , key )

  Get the value for the given key. If the key is unknown, generates an error.

  Most fields are available only after an optimization has been performed with one call to the nmplot_search method.

  this

    The current object.

  key

    a 1-by-1 matrix of strings, the key to get.

    The following keys are available and delegated to the `neldermead` component: -funevals, -iterations, -xopt, -fopt, -historyxopt, -historyfopt, -fx0, -status, -historysimplex, -simplexopt, -restartnb. These options are documented in the help page of the `neldermead_configure` function.

this = nmplot_display ( this )

  Display the current settings in the console.

  this

    The current object.

this = nmplot_search ( this )

  Performs the optimization associated with the method associated with the -method option and find the optimum.

  this

    The current object.

  If the -restartflag option is enabled, automatic restarts are performed, based on the -restartdetection option.

this = nmplot_restart ( this )

  Restarts the optimization by updating the simplex and performing a new search.

  this

    The current object.

[ this , xdata , ydata , zdata ] = nmplot_contour ( this , xmin , xmax , ymin , ymax , nx , ny )

  Plot the contours of the cost function. The cost function must be a function with two parameters.

  this

    The current object.

  xmin , xmax , ymin , ymax

    the bounds for the contour plot

  nx , ny

    the number of points in the directions x, y

  xdata , ydata , zdata

    vectors of data, as required by the contour function

nmplot_simplexhistory ( this , colorforeground , markforeground , markstyle )

  Plots the simplex history on the current graphic window. The colorforeground , markforeground , markstyle options are provided to produce fast plots. Specific settings can still be applied with the usual graphic features.

  this

    The current object.

  colorforeground

    the color of the foreground for the simplices (default colorforeground=5).

  markforeground

    the foreground mark for the simplices (default markforeground = 3).

  markstyle

    the mark style for the simplices (default markstyle = 9).

nmplot_historyplot ( this , datafile , mytitle , myxlabel , myylabel )

  Plots the history from the given data file on the current graphic window. The mytitle, myxlabel, myylabel options are provided as a way to produce plots faster. Specific settings can still be applied with the usual graphic features.

  this

    The current object.

  datafile

    the data file which contains the history. The file is expected to be formatted in a way similar to the files associated with the -fbarfn, -foptfn and -sigmafn files. The default value is the value of the -foptfn option.

  mytitle

    the title of the plot. Default value is the empty string.

  myxlabel

    the x label for the plot. Default value is the empty string.

  myylabel

    the y label for the plot. Default value is the empty string.

[ this , result ] = nmplot_function ( this , x , index )

  Call the cost function and return the value.

  this

    The current object.

  x

    the point where the function is to be evaluated

  index

    optional, a flag to pass to the cost function (default = 1). See the section "The cost function" of the neldermead component for available values of index.

## Example

In the following example, we use the fixed shape Spendley et al. simplex algorithm and find the minimum of a quadratic function. We begin by defining a quadratic function associated with 2 input variables. We then define an nmplot object and configure the object so that the "fixed" shape simplex algorithm is used with the regular initial simplex associated with the "spendley" key. Four files are configured, which will contain the history of the simplex, the history of fbar, fopt and sigma through the iterations. The search is performed by the `nmplot_search` function, which writes the 4 data files during the iterations. The `contour` function is called in order to plot the level sets of the objective function. The `nmplot_simplexhistory` then uses the history of the simplex, as stored in the "history.simplex.txt" data file, and plot the various simplices on the contour plot. The `nmplot_historyplot` function is used with the files "history.fbar.txt", "history.fopt.txt" and "history.sigma.txt", which produces 3 plots of the history of the optimization algorithm through the iterations.

                function [y, index] = quadratic ( x, index )
                y = x(1)^2 + x(2)^2 - x(1) * x(2);
                endfunction
                function y = quadraticC ( x1 , x2 )
                [y, index] = quadratic ( [x1,x2], 2 )
                endfunction

                nm = nmplot_new ();
                nm = nmplot_configure(nm,"-numberofvariables",2);
                nm = nmplot_configure(nm,"-function",quadratic);
                nm = nmplot_configure(nm,"-x0",[2.0 2.0]');
                nm = nmplot_configure(nm,"-maxiter",100);
                nm = nmplot_configure(nm,"-maxfunevals",300);
                nm = nmplot_configure(nm,"-tolxrelative",1.e-8);
                nm = nmplot_configure(nm,"-simplex0method","spendley");
                nm = nmplot_configure(nm,"-method","fixed");
                //
                // Setup output files
                //
                nm = nmplot_configure(nm,"-simplexfn","history.simplex.txt");
                nm = nmplot_configure(nm,"-fbarfn","history.fbar.txt");
                nm = nmplot_configure(nm,"-foptfn","history.fopt.txt");
                nm = nmplot_configure(nm,"-sigmafn","history.sigma.txt");
                //
                // Perform optimization
                //
                nm = nmplot_search(nm);
                // Plot the contours of the cost function and the simplex history
                xmin = -2.0;
                xmax = 4.0;
                ymin = -2.0;
                ymax = 4.0;
                nx = 100;
                ny = 100;
                xdata=linspace(xmin,xmax);
                ydata=linspace(ymin,ymax);
                scf();
                subplot(2,2,1);
                contour ( xdata , ydata , quadraticC , [0.1 1.0 2.0 5.0 10.0 15.0 20.0] )
                nmplot_simplexhistory ( nm );
                subplot(2,2,2);
                mytitle = "Function Value Average";
                myxlabel = "Iterations";
                nmplot_historyplot ( nm , "history.fbar.txt" , mytitle , myxlabel );
                subplot(2,2,3);
                mytitle = "Minimum Function Value";
                myxlabel = "Iterations";
                nmplot_historyplot ( nm , "history.fopt.txt" , mytitle , myxlabel );
                subplot(2,2,4);
                mytitle = "Maximum Oriented length";
                myxlabel = "Iterations";
                nmplot_historyplot ( nm , "history.sigma.txt" , mytitle, myxlabel );
                deletefile("history.simplex.txt");
                deletefile("history.fbar.txt");
                deletefile("history.fopt.txt");
                deletefile("history.sigma.txt");
                nm = nmplot_destroy(nm);

## See Also

- neldermead