# optimsimplex_new

Creates a new simplex object.

## Calling Sequence

                newobj = optimsimplex_new([coords, [fun]])
                [newobj, data] = optimsimplex_new(coords, fun, data)

                newobj = optimsimplex_new("axes", x0, [fun, [len]])
                [newobj, data] = optimsimplex_new("axes", x0, x0, fun, len, data)

                newobj = optimsimplex_new("pfeffer", x0, [fun, [deltausual, [deltazero]]])
                [newobj, data] = optimsimplex_new("pfeffer", x0, fun, deltausual, deltazero, data)

                newobj = optimsimplex_new("randbounds", x0, fun, boundsmin, boundsmax)
                [newobj, data] = optimsimplex_new("randbounds", x0, fun, boundsmin, boundsmax, nbpoints, [data])

                newobj = optimsimplex_new("spendley", x0, [fun, [len]])
                [newobj, data] = optimsimplex_new("spendley", x0, fun, len, data)

                newobj = optimsimplex("oriented", simplex0, fun)
                [newobj, data] = optimsimplex("oriented", simplex0, fun, data)

## Argument

newobj

  The new simplex object of TSIMPLEX type (tlist).

data

  user-defined data passed to the function (optional).

coords

  Matrix of point coordinatres in the simplex (optional).

  This argument is expected to be `nbve`-by-`n` matrix, where `n` is the dimension of the space and `nbve` is the number of vertices in the simplex, with `nbve` >= `n + 1`

fun

  The function to compute at vertices (default fun = []) (optional).

  If `fun` is equal to [], then the function values are not computed.

x0

  The initial point, as a row vector of length `n`.

len

  the length of the simplex (default length = 1.0) (optional).

  If length is a value, that unique lenght is used in all directions. If length is a vector with n values, each length is used with the corresponding direction (n is the dimension of the space).

  This argument is only used if the method is "axes" or "spendley".

deltausual

  the absolute delta for non-zeros values (default value is 0.05) (optional).

  This argument is only used if the method is "pfeffer".

deltazero

  the absolute delta for zero values (default value is 0.0075) (optional).

  This argument is only used if the method is "pfeffer".

boundsmin

  array of minimum bounds.

  This argument is only used if the method is "randbounds".

boundsmax

  array of maximum bounds.

  This argument is only used if the method is "randbounds".

nbpoints

  total number of points in the simplex (default value = n+1, where n is the size of x0).

  This argument is only used if the method is "randbounds".

## Description

The following functions allow to create a new simplex object :

optimsimplex_new()

  The `optimsimplex_new` function creates a new simplex object. All input arguments are optional. If no input argument is provided, this function returns an empty simplex object.

  The following calling sequences are available.

                              newobj = optimsimplex_new ( )
                              newobj = optimsimplex_new ( coords )
                              newobj = optimsimplex_new ( coords , fun )
                              [ newobj , data ] = optimsimplex_new ( coords , fun , data )

newobj = optimsimplex_new("axes", ...)

  This function creates a new simplex object so that it is computed axis by axis, with the given length.

  The following calling sequences are available.

                              newobj = optimsimplex_new ( "axes" , x0 )
                              newobj = optimsimplex_new ( "axes" , x0 , fun )
                              newobj = optimsimplex_new ( "axes" , x0 , fun , len )
                              [ newobj , data ] = optimsimplex_new ( "axes" , x0 , fun , len , data )

newobj = optimsimplex_new("pfeffer", ...)

  This function creates a new simplex object so that it is computed from Pfeffer's method, i.e. a relative delta for non-zero values and an absolute delta for zero values.

  The following calling sequences are available.

                              newobj = optimsimplex_new ( "pfeffer" , x0 )
                              newobj = optimsimplex_new ( "pfeffer" , x0 , fun )
                              newobj = optimsimplex_new ( "pfeffer" , x0 , fun , deltausual )
                              newobj = optimsimplex_new ( "pfeffer" , x0 , fun , deltausual , deltazero )
                              [ newobj , data ] = optimsimplex_new ( "pfeffer" , x0 , fun , deltausual , deltazero , data )

newobj = optimsimplex_new("randbounds", ...)

  This function creates a new simplex object so that it is computed by taking the bounds into account with random scaling. The number of vertices in the simplex is arbitrary.

  The following calling sequences are available.

                              newobj = optimsimplex_new ( "randbounds", x0, fun, boundsmin, boundsmax )
                              [ newobj , data ] = optimsimplex_new ( "randbounds", x0, fun, boundsmin, boundsmax, nbpoints )
                              [ newobj , data ] = optimsimplex_new ( "randbounds", x0, fun, boundsmin, boundsmax, nbpoints, data )

  `x0` is the first vertex in the simplex.

  Each component `ix= 1,n` of the vertex `#k = 2`, `nbve` is computed from the formula `x(k,ix) = boundsmin(ix) + rand() * (boundsmax(ix) - boundsmin(ix))`

newobj = optimsimplex_new("spendley", ...)

  This function creates a new simplex object so that it is computed from Spendley's et al. method, i.e. a regular simplex made of `nbve` = `n + 1` vertices.

  The following calling sequences are available.

                              newobj = optimsimplex_new ( "spendley" , x0 )
                              newobj = optimsimplex_new ( "spendley" , x0 , fun )
                              newobj = optimsimplex_new ( "spendley" , x0 , fun , len )
                              [ newobj , data ] = optimsimplex_new ( "spendley" , x0 , fun , len, data )

newobj = optimsimplex_new("oriented", ...)

  This function returns a new oriented simplex, in sorted order. The new simplex has the same sigma-length of the base simplex, but is "oriented" depending on the function value. The created simplex may be used, as Kelley suggest, for a restart of Nelder-Mead algorithm.

  The following calling sequences are available.

                              newobj = optimsimplex_new ( "oriented" , simplex0 , fun )
                              [ newobj , data ] = optimsimplex_new ( "oriented" , simplex0 , fun, data )

When creating a new simplex with this functions, the `fun` argument can be used to compute the function value at the vertices.

The `fun` function is expected to have the following input and output arguments:

                y = myfunction (x)

If `data` is provided, it is passed to the callback function both as an input and output argument. In that case, the function must have the following header :

                [ y , data ] = myfunction ( x , data )

The `data` input parameter may be used if the function uses some additional parameters. It is returned as an output parameter because the function may modify the data while computing the function value. This feature may be used, for example, to count the number of times that the function has been called.

## Example: Creating a simplex with given vertices coordinates

In the following example, one creates a simplex with known vertices coordinates. The function values at the vertices are unset.

        coords = [
        0.    0.
        1.    0.
        0.    1.
    ];

    s1 = optimsimplex_new ( coords );
    optimsimplex_getallx ( s1 )
    optimsimplex_getn(s1)
    optimsimplex_getnbve (s1)
    s1 = optimsimplex_destroy(s1);

## Example : Creating a simplex with randomized bounds

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 additional argument mystuff, which is counts the number of times the function is called. After the creation of the simplex, the value of mystuff.nb is 5, which is the expected result because there is one function call by vertex.

    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);
      mystuff.nb = mystuff.nb + 1
    endfunction

    mystuff = tlist(["T_MYSTUFF","nb"]);
    mystuff.nb = 0;
    [ s1 , mystuff ] = optimsimplex_new ( "randbounds" , [-1.2 1.0], mycostf, ...
      [-5.0 -5.0] , [5.0 5.0], 5 , mystuff );
    s1
    mprintf("Function evaluations: %d\n",mystuff.nb)
    s1 = optimsimplex_destroy ( s1 );

## See Also

- optimsimplex_destroy