Deleted vectorized computation feature. Deleted neldermead_contour. Fixed the demos.
[scilab.git] / scilab / modules / optimization / help / en_US / optimsimplex / optimsimplex.xml
index 1357ba8..e7df8c2 100644 (file)
@@ -14,7 +14,7 @@
   </info>
 
   <refnamediv>
-    <refname>simplex</refname>
+    <refname>optimsimplex</refname>
 
     <refpurpose>Manage a simplex with arbitrary number of points.</refpurpose>
   </refnamediv>
   <refsynopsisdiv>
     <title>SYNOPSIS</title>
 
-    <synopsis>[ newobj , data ] = simplex_new ( coords , fun , data )
-this = simplex_destroy (this)
-[ this , data ] = simplex_axes ( this , x0 , fun , len , data )
-[ this , data ] = simplex_pfeffer ( this , x0 , fun , deltausual , deltazero , data )
-[ this , data ] = simplex_randbounds ( this , x0 , fun , boundsmin , boundsmax , nbpoints  , data )
-[ this , data ] = simplex_spendley ( this , x0 , fun , len , data )
-this = simplex_setall ( this , simplex )
-this = simplex_setallfv ( this , fv )
-this = simplex_setallx ( this , x )
-this = simplex_setfv ( this , ive , fv )
-this = simplex_setn ( this , n )
-this = simplex_setnbve ( this , nbve )
-this = simplex_setve ( this , ive , fv , x )
-this = simplex_setx ( this , ive , x )
-simplex = simplex_getall ( this )
-fv = simplex_getallfv ( this )
-x = simplex_getallx ( this )
-fv = simplex_getfv ( this , ive )
-n = simplex_getn ( this )
-n = simplex_getnbve ( this )
-vertex = simplex_getve ( this , ive )
-x = simplex_getx ( this , ive )
-sicenter = simplex_center ( this )
-simplex_check ( this )
-[ this , data ] = simplex_computefv ( this , fun , data )
-df = simplex_deltafv ( this )
-dfm = simplex_deltafvmax ( this )
-m = simplex_dirmat ( this )
-sd = simplex_fvmean ( this )
-sd = simplex_fvstdev ( this )
-[ g , data ] = simplex_gradientfv ( this , fun , method , data )
-g = simplex_gradforward ( this )
-[ g , data ] = simplex_gradcentered ( this , fun , data )
-[ ns , data ] = simplex_oriented ( this , fun , data )
-simplex_print ( this )
-[ r , data ] = simplex_reflect ( this , fun , data )
-[ this , data ] = simplex_shrink ( this , fun , sigma , data )
-ssize = simplex_size ( this , method )
-this = simplex_sort ( this )
-str = simplex_tostring ( this )
-cen = simplex_xbar ( this , iexcl )</synopsis>
+    <synopsis>[ newobj , data ] = optimsimplex_new ( coords , fun , data )
+this = optimsimplex_destroy (this)
+[ this , data ] = optimsimplex_axes ( this , x0 , fun , len , data )
+[ this , data ] = optimsimplex_pfeffer ( this , x0 , fun , deltausual , deltazero , data )
+[ this , data ] = optimsimplex_randbounds ( this , x0 , fun , boundsmin , boundsmax , nbpoints  , data )
+[ this , data ] = optimsimplex_spendley ( this , x0 , fun , len , data )
+this = optimsimplex_setall ( this , simplex )
+this = optimsimplex_setallfv ( this , fv )
+this = optimsimplex_setallx ( this , x )
+this = optimsimplex_setfv ( this , ive , fv )
+this = optimsimplex_setn ( this , n )
+this = optimsimplex_setnbve ( this , nbve )
+this = optimsimplex_setve ( this , ive , fv , x )
+this = optimsimplex_setx ( this , ive , x )
+simplex = optimsimplex_getall ( this )
+fv = optimsimplex_getallfv ( this )
+x = optimsimplex_getallx ( this )
+fv = optimsimplex_getfv ( this , ive )
+n = optimsimplex_getn ( this )
+nbve = optimsimplex_getnbve ( this )
+vertex = optimsimplex_getve ( this , ive )
+x = optimsimplex_getx ( this , ive )
+sicenter = optimsimplex_center ( this )
+optimsimplex_check ( this )
+[ this , data ] = optimsimplex_computefv ( this , fun , data )
+df = optimsimplex_deltafv ( this )
+dfm = optimsimplex_deltafvmax ( this )
+m = optimsimplex_dirmat ( this )
+sd = optimsimplex_fvmean ( this )
+sd = optimsimplex_fvstdev ( this )
+[ g , data ] = optimsimplex_gradientfv ( this , fun , method , data )
+g = optimsimplex_gradforward ( this )
+[ g , data ] = optimsimplex_gradcentered ( this , fun , data )
+[ ns , data ] = optimsimplex_oriented ( this , fun , data )
+optimsimplex_print ( this )
+[ r , data ] = optimsimplex_reflect ( this , fun , data )
+[ this , data ] = optimsimplex_shrink ( this , fun , sigma , data )
+ssize = optimsimplex_size ( this , method )
+this = optimsimplex_sort ( this )
+str = optimsimplex_tostring ( this )
+cen = optimsimplex_xbar ( this , iexcl )</synopsis>
   </refsynopsisdiv>
 
   <refsection>
     <title>Purpose</title>
 
-    <para>The goal of this toolbox is to provide a building block for
-    optimization algorithms based on a simplex. That Optimsimplex package may
-    be used in the following optimization methods :<itemizedlist>
-        <listitem>
-          <para>the Spendley et al. simplex method,</para>
-        </listitem>
+    <para>The goal of this component is to provide a building block for
+    optimization algorithms based on a simplex. The optimsimplex package may
+    be used in the following optimization methods :</para>
 
-        <listitem>
-          <para>the Nelder-Mead method,</para>
-        </listitem>
+    <itemizedlist>
+      <listitem>
+        <para>the Spendley et al. simplex method,</para>
+      </listitem>
 
-        <listitem>
-          <para>the Box algorithm for constrained optimization,</para>
-        </listitem>
+      <listitem>
+        <para>the Nelder-Mead method,</para>
+      </listitem>
 
-        <listitem>
-          <para>the multi-dimensional search by Virginia Torczon,</para>
+      <listitem>
+        <para>the Box algorithm for constrained optimization,</para>
+      </listitem>
 
-          <para>etc ...</para>
-        </listitem>
-      </itemizedlist></para>
+      <listitem>
+        <para>the multi-dimensional search by Virginia Torczon,</para>
+      </listitem>
+
+      <listitem>
+        <para>etc ...</para>
+      </listitem>
+    </itemizedlist>
   </refsection>
 
   <refsection>
@@ -173,14 +177,37 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
     simplex gradient can be computed with a order 1 forward formula and with a
     order 2 centered formula.</para>
 
-    <para>The simplex_new function allows to create a simplex. If vertices
-    coordinates are given, there are registered in the simplex. If a function
-    is provided, it is evaluated at each vertex. The simplex_destroy function
-    destroys the object and frees internal memory. Several functions allow to
-    create a simplex with special shapes, including axes-by-axes
-    (simplex_axes), regular (simplex_spendley), randomized bounds simplex with
-    arbitrary k vertices (simplex_randbounds) and an heuristical small
-    variation around a given point (simplex_pfeffer).</para>
+    <para>The optimsimplex_new function allows to create a simplex. If
+    vertices coordinates are given, there are registered in the simplex. If a
+    function is provided, it is evaluated at each vertex. The
+    optimsimplex_destroy function destroys the object and frees internal
+    memory. Several functions allow to create a simplex with special shapes,
+    including axes-by-axes (optimsimplex_axes), regular
+    (optimsimplex_spendley), randomized bounds simplex with arbitrary nbve
+    vertices (optimsimplex_randbounds) and an heuristical small variation
+    around a given point (optimsimplex_pfeffer).</para>
+
+    <para>In the following functions, simplices and vertices are, depending on
+    the functions either input or output arguments. The following general
+    principle have been used to manage the storing of the coordinates of the
+    points.</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>The vertices are stored row by row, while the coordinates are
+        stored column by column. This implies the following rules.</para>
+      </listitem>
+
+      <listitem>
+        <para>The coordinates of a vertex are stored in a row vector, i.e. a 1
+        x n matrix where n is the dimension of the space.</para>
+      </listitem>
+
+      <listitem>
+        <para>The function values are stored in a column vector, i.e. a nbve x
+        1 matrix where nbve is the number of vertices.</para>
+      </listitem>
+    </itemizedlist>
   </refsection>
 
   <refsection>
@@ -190,7 +217,8 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
 
     <variablelist>
       <varlistentry>
-        <term>[ newobj , data ] = simplex_new ( coords , fun , data )</term>
+        <term>[ newobj , data ] = optimsimplex_new ( coords , fun , data
+        )</term>
 
         <listitem>
           <para>Creates a new simplex object. All input arguments are
@@ -213,9 +241,9 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
                 <para>optional, matrix of point coordinates in the
                 simplex.</para>
 
-                <para>The coords matrix is expected to be a n x k matrix,
-                where n is the dimension of the space and k is the number of
-                vertices in the simplex, with k&gt;= n+1.</para>
+                <para>The coords matrix is expected to be a nbve x n matrix,
+                where n is the dimension of the space and nbve is the number
+                of vertices in the simplex, with nbve&gt;= n+1.</para>
               </listitem>
             </varlistentry>
 
@@ -228,7 +256,9 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
                 <para>The function is expected to have the following input and
                 output arguments :</para>
 
-                <programlisting role="example">function y = myfunction (x)</programlisting>
+                <programlisting role="example"> 
+function y = myfunction (x)
+ </programlisting>
               </listitem>
             </varlistentry>
 
@@ -243,7 +273,9 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
                 function both as an input and output argument. In that case,
                 the function must have the following header :</para>
 
-                <programlisting role="example">function [ y , data ] = myfunction ( x , data )</programlisting>
+                <programlisting role="example"> 
+function [ y , data ] = myfunction ( x , data )
+ </programlisting>
 
                 <para>The data input parameter may be used if the function
                 uses some additionnal parameters. It is returned as an output
@@ -258,7 +290,7 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>this = simplex_destroy (this)</term>
+        <term>this = optimsimplex_destroy (this)</term>
 
         <listitem>
           <para>Destroy the given object.</para>
@@ -276,8 +308,8 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>[ this , data ] = simplex_axes ( this , x0 , fun , len , data
-        )</term>
+        <term>[ this , data ] = optimsimplex_axes ( this , x0 , fun , len ,
+        data )</term>
 
         <listitem>
           <para>Configure the current simplex so that it is computed axis by
@@ -309,7 +341,9 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
                 <para>The function is expected to have the following input and
                 output arguments :</para>
 
-                <programlisting role="example">function y = myfunction (x)</programlisting>
+                <programlisting role="example"> 
+function y = myfunction (x)
+ </programlisting>
               </listitem>
             </varlistentry>
 
@@ -335,7 +369,9 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
                 function both as an input and output argument. In that case,
                 the function must have the following header :</para>
 
-                <programlisting role="example">function [ y , data ] = myfunction ( x , data )</programlisting>
+                <programlisting role="example"> 
+function [ y , data ] = myfunction ( x , data )
+ </programlisting>
 
                 <para>The data input parameter may be used if the function
                 uses some additionnal parameters. It is returned as an output
@@ -350,8 +386,8 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>[ this , data ] = simplex_pfeffer ( this , x0 , fun , deltausual
-        , deltazero , data )</term>
+        <term>[ this , data ] = optimsimplex_pfeffer ( this , x0 , fun ,
+        deltausual , deltazero , data )</term>
 
         <listitem>
           <para>Configure the current simplex so that it is computed from
@@ -384,7 +420,9 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
                 <para>The function is expected to have the following input and
                 output arguments :</para>
 
-                <programlisting role="example">function y = myfunction (x)</programlisting>
+                <programlisting role="example"> 
+function y = myfunction (x)
+ </programlisting>
               </listitem>
             </varlistentry>
 
@@ -417,7 +455,9 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
                 function both as an input and output argument. In that case,
                 the function must have the following header :</para>
 
-                <programlisting role="example">function [ y , data ] = myfunction ( x , data )</programlisting>
+                <programlisting role="example"> 
+function [ y , data ] = myfunction ( x , data )
+ </programlisting>
 
                 <para>The data input parameter may be used if the function
                 uses some additionnal parameters. It is returned as an output
@@ -432,7 +472,7 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>[ this , data ] = simplex_randbounds ( this , x0 , fun ,
+        <term>[ this , data ] = optimsimplex_randbounds ( this , x0 , fun ,
         boundsmin , boundsmax , nbpoints , data )</term>
 
         <listitem>
@@ -467,7 +507,9 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
                 <para>The function is expected to have the following input and
                 output arguments :</para>
 
-                <programlisting role="example">function y = myfunction (x)</programlisting>
+                <programlisting role="example"> 
+function y = myfunction (x)
+ </programlisting>
               </listitem>
             </varlistentry>
 
@@ -485,10 +527,12 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
               <listitem>
                 <para>array of maximum bounds</para>
 
-                <para>Each component ix =1 , n of the vertex #jve = 2,k is
+                <para>Each component ix =1,n of the vertex #k = 2,nbve is
                 computed from the formula :</para>
 
-                <programlisting role="example">x ( ix , jve ) = boundsmin( ix ) + rand() * (boundsmax( ix ) - boundsmin( ix ))</programlisting>
+                <programlisting role="example"> 
+x ( k , ix ) = boundsmin( ix ) + rand() * (boundsmax( ix ) - boundsmin( ix ))
+ </programlisting>
               </listitem>
             </varlistentry>
 
@@ -511,7 +555,9 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
                 function both as an input and output argument. In that case,
                 the function must have the following header :</para>
 
-                <programlisting role="example">function [ y , data ] = myfunction ( x , data )</programlisting>
+                <programlisting role="example"> 
+function [ y , data ] = myfunction ( x , data )
+ </programlisting>
 
                 <para>The data input parameter may be used if the function
                 uses some additionnal parameters. It is returned as an output
@@ -526,12 +572,12 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>[ this , data ] = simplex_spendley ( this , x0 , fun , len ,
-        data )</term>
+        <term>[ this , data ] = optimsimplex_spendley ( this , x0 , fun , len
+        , data )</term>
 
         <listitem>
           <para>Configure the current simplex so that it is computed from
-          Spendley's et al. method, i.e. a regular simplex made of k = n+1
+          Spendley's et al. method, i.e. a regular simplex made of nbve = n+1
           vertices.</para>
 
           <variablelist>
@@ -560,7 +606,9 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
                 <para>The function is expected to have the following input and
                 output arguments :</para>
 
-                <programlisting role="example">function y = myfunction (x)</programlisting>
+                <programlisting role="example"> 
+function y = myfunction (x)
+ </programlisting>
               </listitem>
             </varlistentry>
 
@@ -584,7 +632,9 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
                 function both as an input and output argument. In that case,
                 the function must have the following header :</para>
 
-                <programlisting role="example">function [ y , data ] = myfunction ( x , data )</programlisting>
+                <programlisting role="example"> 
+function [ y , data ] = myfunction ( x , data )
+ </programlisting>
 
                 <para>The data input parameter may be used if the function
                 uses some additionnal parameters. It is returned as an output
@@ -599,7 +649,7 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>this = simplex_setall ( this , simplex )</term>
+        <term>this = optimsimplex_setall ( this , simplex )</term>
 
         <listitem>
           <para>Set all the coordinates and and the function values of all the
@@ -644,11 +694,12 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>this = simplex_setallfv ( this , fv )</term>
+        <term>this = optimsimplex_setallfv ( this , fv )</term>
 
         <listitem>
           <para>Set all the function values of all the vertices. The vertex #k
-          is expected to be stored in fv(k) with k = 1 , nbve</para>
+          is expected to be stored in fv(k) with k = 1 , nbve. The fv input
+          argument is expected to be a row vector.</para>
 
           <variablelist>
             <varlistentry>
@@ -671,11 +722,11 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>this = simplex_setallx ( this , x )</term>
+        <term>this = optimsimplex_setallx ( this , x )</term>
 
         <listitem>
           <para>Set all the coordinates of all the vertices. The vertex #k is
-          expected to be stored in x(1:n,k) with k = 1 , nbve</para>
+          expected to be stored in x(k,1:n) with k = 1 , nbve</para>
 
           <variablelist>
             <varlistentry>
@@ -698,7 +749,7 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>this = simplex_setfv ( this , ive , fv )</term>
+        <term>this = optimsimplex_setfv ( this , ive , fv )</term>
 
         <listitem>
           <para>Set the function value at given index and // returns an
@@ -733,7 +784,7 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>this = simplex_setn ( this , n )</term>
+        <term>this = optimsimplex_setn ( this , n )</term>
 
         <listitem>
           <para>Set the dimension of the space of the simplex.</para>
@@ -759,7 +810,7 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>this = simplex_setnbve ( this , nbve )</term>
+        <term>this = optimsimplex_setnbve ( this , nbve )</term>
 
         <listitem>
           <para>Set the number of vertices of the simplex.</para>
@@ -785,7 +836,7 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>this = simplex_setve ( this , ive , fv , x )</term>
+        <term>this = optimsimplex_setve ( this , ive , fv , x )</term>
 
         <listitem>
           <para>Sets the coordinates of the vertex and the function value at
@@ -820,7 +871,7 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
               <term>x</term>
 
               <listitem>
-                <para>the coordinates of the point, as a column vector</para>
+                <para>the coordinates of the point, as a row vector</para>
               </listitem>
             </varlistentry>
           </variablelist>
@@ -828,10 +879,10 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>this = simplex_setx ( this , ive , x )</term>
+        <term>this = optimsimplex_setx ( this , ive , x )</term>
 
         <listitem>
-          <para>Set the coordinates of the vertex at given index, as a column
+          <para>Set the coordinates of the vertex at given index, as a row
           vector, into the current simplex.</para>
 
           <variablelist>
@@ -855,7 +906,7 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
               <term>x</term>
 
               <listitem>
-                <para>the coordinates of the point, as a column vector</para>
+                <para>the coordinates of the point, as a row vector</para>
               </listitem>
             </varlistentry>
           </variablelist>
@@ -863,7 +914,7 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>simplex = simplex_getall ( this )</term>
+        <term>simplex = optimsimplex_getall ( this )</term>
 
         <listitem>
           <para>Returns all the coordinates of all the vertices and the
@@ -905,11 +956,11 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>fv = simplex_getallfv ( this )</term>
+        <term>fv = optimsimplex_getallfv ( this )</term>
 
         <listitem>
-          <para>Returns all the function values of all the vertices, as a
-          column vector.</para>
+          <para>Returns all the function values of all the vertices, as a row
+          vector.</para>
 
           <variablelist>
             <varlistentry>
@@ -933,7 +984,7 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>x = simplex_getallx ( this )</term>
+        <term>x = optimsimplex_getallx ( this )</term>
 
         <listitem>
           <para>Returns all the coordinates of all the vertices.</para>
@@ -953,7 +1004,7 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
               <listitem>
                 <para>the coordinates.</para>
 
-                <para>The vertex #k is stored in x(1:n,k) with k = 1 ,
+                <para>The vertex #k is stored in x(k,1:n) with k = 1 ,
                 nbve.</para>
               </listitem>
             </varlistentry>
@@ -962,7 +1013,7 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>fv = simplex_getfv ( this , ive )</term>
+        <term>fv = optimsimplex_getfv ( this , ive )</term>
 
         <listitem>
           <para>Returns the function value at given index</para>
@@ -988,7 +1039,7 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>n = simplex_getn ( this )</term>
+        <term>n = optimsimplex_getn ( this )</term>
 
         <listitem>
           <para>Returns the dimension of the space of the simplex</para>
@@ -1006,7 +1057,7 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>n = simplex_getnbve ( this )</term>
+        <term>nbve = optimsimplex_getnbve ( this )</term>
 
         <listitem>
           <para>Returns the number of vertices in the simplex.</para>
@@ -1024,7 +1075,7 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>vertex = simplex_getve ( this , ive )</term>
+        <term>vertex = optimsimplex_getve ( this , ive )</term>
 
         <listitem>
           <para>Returns the vertex at given index as a tlist, with fields n, x
@@ -1051,11 +1102,11 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>x = simplex_getx ( this , ive )</term>
+        <term>x = optimsimplex_getx ( this , ive )</term>
 
         <listitem>
-          <para>Returns the coordinates of the vertex at given index, as a
-          column vector.</para>
+          <para>Returns the coordinates of the vertex at given index, as a row
+          vector.</para>
 
           <variablelist>
             <varlistentry>
@@ -1078,7 +1129,7 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>sicenter = simplex_center ( this )</term>
+        <term>sicenter = optimsimplex_center ( this )</term>
 
         <listitem>
           <para>Returns the center of the given simplex</para>
@@ -1096,7 +1147,7 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>simplex_check ( this )</term>
+        <term>optimsimplex_check ( this )</term>
 
         <listitem>
           <para>Check the consistency of the internal data. Generates an error
@@ -1115,7 +1166,8 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>[ this , data ] = simplex_computefv ( this , fun , data )</term>
+        <term>[ this , data ] = optimsimplex_computefv ( this , fun , data
+        )</term>
 
         <listitem>
           <para>Set the values of the function at vertices points.</para>
@@ -1138,7 +1190,9 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
                 <para>The function is expected to have the following input and
                 output arguments :</para>
 
-                <programlisting role="example">function y = myfunction (x)</programlisting>
+                <programlisting role="example"> 
+function y = myfunction (x)
+ </programlisting>
               </listitem>
             </varlistentry>
 
@@ -1153,7 +1207,9 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
                 function both as an input and output argument. In that case,
                 the function must have the following header :</para>
 
-                <programlisting role="example">function [ y , data ] = myfunction ( x , data )</programlisting>
+                <programlisting role="example"> 
+function [ y , data ] = myfunction ( x , data )
+ </programlisting>
 
                 <para>The data input parameter may be used if the function
                 uses some additionnal parameters. It is returned as an output
@@ -1168,7 +1224,7 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>df = simplex_deltafv ( this )</term>
+        <term>df = optimsimplex_deltafv ( this )</term>
 
         <listitem>
           <para>Returns the vector of difference of function values with
@@ -1187,7 +1243,7 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>dfm = simplex_deltafvmax ( this )</term>
+        <term>dfm = optimsimplex_deltafvmax ( this )</term>
 
         <listitem>
           <para>Returns the difference of function value between the high and
@@ -1209,7 +1265,7 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>m = simplex_dirmat ( this )</term>
+        <term>m = optimsimplex_dirmat ( this )</term>
 
         <listitem>
           <para>Returns the n x n matrix of simplex directions i.e. the matrix
@@ -1229,7 +1285,7 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>sd = simplex_fvmean ( this )</term>
+        <term>sd = optimsimplex_fvmean ( this )</term>
 
         <listitem>
           <para>Returns the mean of the function value on the simplex.</para>
@@ -1247,7 +1303,7 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>sd = simplex_fvstdev ( this )</term>
+        <term>sd = optimsimplex_fvstdev ( this )</term>
 
         <listitem>
           <para>Returns the standard deviation of the function value on the
@@ -1266,8 +1322,8 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>[ g , data ] = simplex_gradientfv ( this , fun , method , data
-        )</term>
+        <term>[ g , data ] = optimsimplex_gradientfv ( this , fun , method ,
+        data )</term>
 
         <listitem>
           <para>Returns the simplex gradient of the function.</para>
@@ -1290,7 +1346,9 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
                 <para>The function is expected to have the following input and
                 output arguments :</para>
 
-                <programlisting role="example">function y = myfunction (x)</programlisting>
+                <programlisting role="example"> 
+function y = myfunction (x)
+ </programlisting>
               </listitem>
             </varlistentry>
 
@@ -1319,7 +1377,9 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
                 function both as an input and output argument. In that case,
                 the function must have the following header :</para>
 
-                <programlisting role="example">function [ y , data ] = myfunction ( x , data )</programlisting>
+                <programlisting role="example"> 
+function [ y , data ] = myfunction ( x , data )
+ </programlisting>
 
                 <para>The data input parameter may be used if the function
                 uses some additionnal parameters. It is returned as an output
@@ -1334,7 +1394,8 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>[ ns , data ] = simplex_oriented ( this , fun , data )</term>
+        <term>[ ns , data ] = optimsimplex_oriented ( this , fun , data
+        )</term>
 
         <listitem>
           <para>Returns a new oriented simplex, in sorted order. The new
@@ -1361,7 +1422,9 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
                 <para>The function is expected to have the following input and
                 output arguments :</para>
 
-                <programlisting role="example">function y = myfunction (x)</programlisting>
+                <programlisting role="example"> 
+function y = myfunction (x)
+ </programlisting>
               </listitem>
             </varlistentry>
 
@@ -1376,7 +1439,9 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
                 function both as an input and output argument. In that case,
                 the function must have the following header :</para>
 
-                <programlisting role="example">function [ y , data ] = myfunction ( x , data )</programlisting>
+                <programlisting role="example"> 
+function [ y , data ] = myfunction ( x , data )
+ </programlisting>
 
                 <para>The data input parameter may be used if the function
                 uses some additionnal parameters. It is returned as an output
@@ -1391,7 +1456,7 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>simplex_print ( this )</term>
+        <term>optimsimplex_print ( this )</term>
 
         <listitem>
           <para>Display the current simplex, with coordinates and function
@@ -1410,7 +1475,7 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>[ r , data ] = simplex_reflect ( this , fun , data )</term>
+        <term>[ r , data ] = optimsimplex_reflect ( this , fun , data )</term>
 
         <listitem>
           <para>Returns a new simplex by reflexion of current simplex, by
@@ -1435,7 +1500,9 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
                 <para>The function is expected to have the following input and
                 output arguments :</para>
 
-                <programlisting role="example">function y = myfunction (x)</programlisting>
+                <programlisting role="example"> 
+function y = myfunction (x)
+ </programlisting>
               </listitem>
             </varlistentry>
 
@@ -1450,7 +1517,9 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
                 function both as an input and output argument. In that case,
                 the function must have the following header :</para>
 
-                <programlisting role="example">function [ y , data ] = myfunction ( x , data )</programlisting>
+                <programlisting role="example"> 
+function [ y , data ] = myfunction ( x , data )
+ </programlisting>
 
                 <para>The data input parameter may be used if the function
                 uses some additionnal parameters. It is returned as an output
@@ -1465,8 +1534,8 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>[ this , data ] = simplex_shrink ( this , fun , sigma , data
-        )</term>
+        <term>[ this , data ] = optimsimplex_shrink ( this , fun , sigma ,
+        data )</term>
 
         <listitem>
           <para>Shrink the simplex with given coefficient sigma and returns an
@@ -1491,7 +1560,9 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
                 <para>The function is expected to have the following input and
                 output arguments :</para>
 
-                <programlisting role="example">function y = myfunction (x)</programlisting>
+                <programlisting role="example"> 
+function y = myfunction (x)
+ </programlisting>
               </listitem>
             </varlistentry>
 
@@ -1515,7 +1586,9 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
                 function both as an input and output argument. In that case,
                 the function must have the following header :</para>
 
-                <programlisting role="example">function [ y , data ] = myfunction ( x , data )</programlisting>
+                <programlisting role="example"> 
+function [ y , data ] = myfunction ( x , data )
+ </programlisting>
 
                 <para>The data input parameter may be used if the function
                 uses some additionnal parameters. It is returned as an output
@@ -1530,7 +1603,7 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>ssize = simplex_size ( this , method )</term>
+        <term>ssize = optimsimplex_size ( this , method )</term>
 
         <listitem>
           <para>Returns the size of the simplex.</para>
@@ -1539,12 +1612,12 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
           requires 2 nested loops over the vertices.</para>
 
           <para>The sigmaminus (resp. sigmamplus) size is the minimum (resp.
-          maximum) length of the vector from the given vertex to the first
-          vertex. It requires one loop over the vertices.</para>
+          maximum) length of the vector from each vertex to the first vertex.
+          It requires one loop over the vertices.</para>
 
           <para>The "Nash" size is the sum of the norm of the length of the
-          vector from the given vertex to the first vertex. It requires one
-          loop over the vertices.</para>
+          vector from the given vertex to the first vertex. The 1-norm is
+          used. It requires one loop over the vertices.</para>
 
           <variablelist>
             <varlistentry>
@@ -1569,7 +1642,7 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>this = simplex_sort ( this )</term>
+        <term>this = optimsimplex_sort ( this )</term>
 
         <listitem>
           <para>Sorts the simplex with increasing function value order so that
@@ -1588,7 +1661,7 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>str = simplex_tostring ( this )</term>
+        <term>str = optimsimplex_tostring ( this )</term>
 
         <listitem>
           <para>Returns the current simplex as a string.</para>
@@ -1606,7 +1679,7 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
       </varlistentry>
 
       <varlistentry>
-        <term>cen = simplex_xbar ( this , iexcl )</term>
+        <term>cen = optimsimplex_xbar ( this , iexcl )</term>
 
         <listitem>
           <para>Returns the center of n vertices, by excluding the vertex with
@@ -1645,17 +1718,18 @@ cen = simplex_xbar ( this , iexcl )</synopsis>
     <para>In the following example, one creates a simplex with known vertices
     coordinates. The function values at the vertices are unset.</para>
 
-    <programlisting role="example">
+    <programlisting role="example"> 
 coords = [
-0.0 1.0 0.0
-0.0 0.0 1.0
+    0.    0.  
+    1.    0.  
+    0.    1.  
 ];
-s1 = simplex_new ( coords );
-computed = simplex_getallx ( s1 );
-computed = simplex_getn(s1);
-computed = simplex_getnbve (s1);
-s1 = simplex_destroy(s1);
-    </programlisting>
+s1 = optimsimplex_new ( coords );
+computed = optimsimplex_getallx ( s1 );
+computed = optimsimplex_getn(s1);
+computed = optimsimplex_getnbve (s1);
+s1 = optimsimplex_destroy(s1);
+ </programlisting>
   </refsection>
 
   <refsection>
@@ -1664,42 +1738,77 @@ s1 = simplex_destroy(s1);
     <para>In the following example, one creates a simplex with in the 2D
     domain [-5 5]^2, with [-1.2 1.0] as the first vertex. One uses the
     randomized bounds method to generate a simplex with 5 vertices. The
-    function takes an additionnal argument myobj, which is counts the number
+    function takes an additionnal argument mystuff, which is counts the number
     of times the function is called. After the creation of the simplex, the
-    value of mydude.nb is 5, which is the expected result because there is one
-    function call by vertex.</para>
+    value of mystuff.nb is 5, which is the expected result because there is
+    one function call by vertex.</para>
 
-    <programlisting role="example">
-function [ y , myobj ] = mycostf ( x , myobj )
+    <programlisting role="example"> 
+function y = rosenbrock (x)
+  y = 100*(x(2)-x(1)^2)^2+(1-x(1))^2;
+endfunction
+function [ y , mystuff ] = mycostf ( x , mystuff )
   y = rosenbrock(x);
-  myobj.nb = myobj.nb + 1
+  mystuff.nb = mystuff.nb + 1
 endfunction
 
-mydude = tlist(["T_MYSTUFF","nb"]);
-mydude.nb = 0;
-s1 = simplex_new ();
-[ s1 , mydude ] = simplex_randbounds ( s1 , x0 = [-1.2 1.0], fun = mycostf, ...
-  boundsmin = [-5.0 -5.0] , boundsmax = [5.0 5.0], nbve=5 , data = mydude );
-s1 = simplex_destroy ( s1 );
-
-    </programlisting>
+mystuff = tlist(["T_MYSTUFF","nb"]);
+mystuff.nb = 0;
+s1 = optimsimplex_new ();
+[ s1 , mystuff ] = optimsimplex_randbounds ( s1 , x0 = [-1.2 1.0], fun = mycostf, ...
+  boundsmin = [-5.0 -5.0] , boundsmax = [5.0 5.0], nbve=5 , data = mystuff );
+mprintf("Function evaluations: %d\n",mystuff.nb)
+s1 = optimsimplex_destroy ( s1 );
+ </programlisting>
   </refsection>
 
   <refsection>
     <title>TODO</title>
 
-    <para><itemizedlist>
-        <listitem>
-          <para>implement reflection and expansion as in multidimensional
-          search by Torczon</para>
-        </listitem>
-      </itemizedlist></para>
+    <itemizedlist>
+      <listitem>
+        <para>implement reflection and expansion as in multidimensional search
+        by Torczon</para>
+      </listitem>
+
+      <listitem>
+        <para>move optimsimplex_reflect into a proper method, not a weird
+        constructor</para>
+      </listitem>
+    </itemizedlist>
+  </refsection>
+
+  <refsection>
+    <title>Initial simplex strategies</title>
+
+    <para>In this section, we analyse the various initial simplex which are
+    provided in this component.</para>
+
+    <para>It is known that direct search methods based on simplex designs are
+    very sensitive to the initial simplex. This is why the current component
+    provides various ways to create such an initial simplex.</para>
+
+    <para>The first historical simplex-based algorithm is the one presented in
+    "Sequential Application of Simplex Designs in Optimisation and
+    Evolutionary Operation" by W. Spendley, G. R. Hext and F. R. Himsworth.
+    The optimsimplex_spendley function creates the regular simplex which is
+    presented in this paper.</para>
+
+    <para>The method used in the optimsimplex_randbounds function is due to
+    M.J. Box in "A New Method of Constrained Optimization and a Comparison
+    With Other Methods".</para>
+
+    <para>Pfeffer's method is an heuristic which is presented in "Global
+    Optimization Of Lennard-Jones Atomic Clusters" by Ellen Fan. It is due to
+    L. Pfeffer at Stanford and it is used in fminsearch.</para>
   </refsection>
 
   <refsection>
     <title>Authors</title>
 
-    <para>Michael Baudin, 2008-2009</para>
+    <para>Michael Baudin - INRIA - 2008-2009</para>
+
+    <para>Michael Baudin - Digiteo - 2009</para>
   </refsection>
 
   <refsection>
@@ -1748,5 +1857,8 @@ s1 = simplex_destroy ( s1 );
     <para>"A convergent variant of the Nelder-Mead algorithm", C. J. Price, I.
     D. Coope, D. Byatt, Journal of Optimization Theory and Applications,
     Volume 113 , Issue 1 (April 2002), Pages: 5 - 19,</para>
+
+    <para>"Global Optimization Of Lennard-Jones Atomic Clusters", Ellen Fan,
+    Thesis, February 26, 2002, McMaster University</para>
   </refsection>
 </refentry>