# The cl-grnm Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

# The cl-grnm Reference Manual

This is the cl-grnm Reference Manual, version 0.1.0, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 03:20:41 2018 GMT+0.

Next: , Previous: , Up: Top   [Contents][Index]

# cl-grnm

## Authorship

This package was originally written by Mario S. Mommer (2006), and this fork is maintained by Rigetti Computing.

## Introduction

These common lisp sources contain two variants of the Nelder-Mead algorithm. The original algorithm [1] and a provably convergent, reliable variant by A. Bürmen et al [4], called the "Grid Restrained Nelder Mead Algorithm" (GRNMA).

It should be mentioned that other, provably convergent variant exist [2,3], which aren't included here. The only reasons are lack of time, and the fact that the implemented variant does not require a simple descent condition, putting it closer to the original.

Other than that, and based on the article [4], the performance of these methods seems to be about equal in terms of number of function evaluations. As a side effect of the additional reliability, both tend to be a lot more efficient than the original algorithm even when it does not fail. In particular when the number of dimensions increases. As a test, one might try the GRNM,

``````(grnm-optimize #'standard-quadratic (make-array 30 :initial-element 1.0d0) :verbose t)
``````

and compare with the original Nelder-Mead,

``````(nm-optimize #'standard-quadratic (make-array 30 :initial-element 1.0d0) :verbose t)
``````

and observe the difference in number of function evaluations (the last value returned).

(This exercise also serves to illustrate the overall deficiencies of direct search algorithms when applied to higher dimensional problems.)

This software is provided under the MIT license; see LICENSE.txt for details.

## Usage

This implementation of the grid restrained Nelder-Mead algorithm expects at least two parameters: the objective function, and an initial guess. It returns four values:

• the minimizer,
• the minimum,
• the last simplex,
• and the number of function evaluations.

The objective function should accept a double-float array as its argument.

The initial guess will usually be an array of double-float numbers (but instead an object of the class `NM-SIMPLEX` may also be provided; see below). For example,

``````(grnm-optimize #'rosenbrock #(40.0d0 40.0d0))
``````

finds the minimum of the Rosenbrock function, and

``````(grnm-optimize #'standard-quadratic (make-array 30 :initial-element 1.0d0))
``````

finds the minimum of the standard quadratic function in 30 dimensions.

A few keyword arguments can customize the behavior. These are

• `:verbose` (default: `NIL`)
• `:converged-p` (default: `burmen-et-al-convergence-test`)
• `:max-function-calls` (default: `NIL`; => as many as needed)

### `:verbose` (default: `NIL`)

Pass T here if you want to see some progress report. The amount of output can be controlled by setting verbose-level to 1 or 2. The difference is that with 1 (the default) only the best value of the simplex is shown, while with 2 the whole simplex is printed on each iteration.

### `:converged-p` (default: `burmen-et-al-convergence-test`)

The `burmen-et-al-convergence-test` is, as the name suggests, the convergence test used in the article by Bürmen et al. It accepts a few parameters: `tol-x`, `tol-f` and `rel`; please see the article for further details.

Another convergence criterion that can be given is `(pp-volume-test <tol>)`, which returns true once the parallelogram(!) spanned by the vertices of the simplex has a volume lower than `<tol>` to the power of N, where N is the dimension of the problem. This is a rather expensive test, as it involves computing a QR decomposition of an N by N matrix on each call.

If you are not in the mood of taking prisoners, you might as well pass (constantly NIL) as the convergence criterion. This has as a consequence that the iteration continues until the simplex collapses, which in floating-point arithmetic happens in finite time. The grid restrained Nelder-Mead algorithm should have converged by then.

### `:max-function-calls` (default: `NIL`)

Maximum number of objective function evaluations. After that many function evaluations, this implementation of the algorithm will declare convergence to have occurred.

The actual number of function calls might be slightly larger (at most by N), as the relevant condition is only checked in certain situations.

## Utilities/Misc

### `NM-optimize`

Apart from the grid-restrained Nelder Mead algorithm, the traditional variant is also provided. The corresponding function is named `NM-optimize`, and its usage is the same as for `GRNM-optimize`.

The only difference is that :max-function-calls has a default value of 100000. Otherwise the algorithm might well iterate forever.

### `initial-simplex <initial guess> :displace <displacement>`

Constructs an initial simplex with the double-float array `<initial guess>` as on of its corners.

The displacement can be a an array of double floats or a number. In the first case, the additional vertices of the simplex are build by adding to each component of the `<initial guess>` the corresponding component in `<displacement>`. If it is a number, then the additional vertices are build by adding `<displacement>` to each component of the `<initial guess>`.

## Tips & Tricks

• One can try to solve constrained optimization problems by returning `MOST-POSITIVE-DOUBLE-FLOAT` whenever the objective function is called with an argument that violates the constraints. Mathematically, this falls out of the theory, but it works most of the time.
• If your objective function is noisy or not smooth (for instance, if its first derivatives are not continuous) it is a good idea to restart the algorithm. Remember that convergence is only guaranteed if the objective function is at least C^1.

## References

[1] J.A. Nelder and R. Mead, "A simplex method for function minimization," The Computer Journal, vol. 7, pp. 308-313, 1965.

[2] P. Tseng, "Fortified-descent simplicial search method: A general approach," SIAM Journal on Optimization, vol. 10, pp. 269-288, 1999.

[3] C.J. Price, I.D. Coope, and D. Byatt, "A convergent variant of the Nelder-Mead algorithm," Journal of Optimization Theory and Applications, vol. 113, pp. 5-19, 2002.

[4] A. Bürmen, J. Puhan and T. Tuma, "Grid Restrained Nelder-Mead Algorithm", Computational Optimization and Applications, vol. 34, no. 3, pp. 359 - 375, 2006

Next: , Previous: , Up: Top   [Contents][Index]

## 2 Systems

The main system appears first, followed by any subsystem dependency.

Previous: , Up: Systems   [Contents][Index]

### 2.1 cl-grnm

Author

Rigetti Computing and Mario S. Sommer

Description

Grid Restrained Nelder-Mead, a multivariate rootfinder.

Version

0.1.0

Source

cl-grnm.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

## 3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

Previous: , Up: Files   [Contents][Index]

### 3.1 Lisp

Next: , Previous: , Up: Lisp files   [Contents][Index]

#### 3.1.1 cl-grnm.asd

Location

cl-grnm.asd

Systems

cl-grnm (system)

Packages

Next: , Previous: , Up: Lisp files   [Contents][Index]

#### 3.1.2 cl-grnm/defpackage.lisp

Parent

cl-grnm (system)

Location

defpackage.lisp

Packages

Next: , Previous: , Up: Lisp files   [Contents][Index]

#### 3.1.3 cl-grnm/la.lisp

Dependency

defpackage.lisp (file)

Parent

cl-grnm (system)

Location

la.lisp

Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

Dependency

la.lisp (file)

Parent

cl-grnm (system)

Location

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

## 4 Packages

Packages are listed by definition order.

Next: , Previous: , Up: Packages   [Contents][Index]

### 4.1 cl-grnm-asd

Source

cl-grnm.asd

Use List
• asdf/interface
• common-lisp

Previous: , Up: Packages   [Contents][Index]

### 4.2 cl-grnm

Source

defpackage.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

## 5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

Next: , Previous: , Up: Definitions   [Contents][Index]

### 5.1 Exported definitions

Previous: , Up: Exported definitions   [Contents][Index]

#### 5.1.1 Functions

Function: burmen-et-al-convergence-test &key TOL-X TOL-F REL
Package
Source

Function: grnm-optimize OBJECTIVE-FUNCTION INITIAL-GUESS &key MAX-FUNCTION-CALLS CONVERGENCE-P VERBOSE
Package
Source

Function: initial-simplex X0 &key DISPLACE
Package
Source

Function: nm-optimize OBJECTIVE-FUNCTION INITIAL-GUESS &key MAX-FUNCTION-CALLS CONVERGENCE-P VERBOSE
Package
Source

Function: pp-volume-test CSIDE
Package
Source

Function: rosenbrock V
Package
Source

Package
Source

Previous: , Up: Definitions   [Contents][Index]

### 5.2 Internal definitions

Next: , Previous: , Up: Internal definitions   [Contents][Index]

#### 5.2.1 Special variables

Special Variable: *biglambda*
Package
Source

Special Variable: *breakdown*
Package
Source

Special Variable: *psi*
Package
Source

Special Variable: *smalllambda*
Package
Source

Special Variable: *tau-a*
Package
Source

Special Variable: *tau-r*
Package
Source

Special Variable: *verbose-level*
Package
Source

Next: , Previous: , Up: Internal definitions   [Contents][Index]

#### 5.2.2 Macros

Macro: with-matrix-dimensions VARFORMS &body BODY
Package
Source

la.lisp (file)

Next: , Previous: , Up: Internal definitions   [Contents][Index]

#### 5.2.3 Functions

Function: deep-shrink F S G GAMMA_S CONVERGENCE-P VERBOSE
Package
Source

Function: default-initial-simplex X0
Package
Source

Function: ip V W &optional START
Package
Source

la.lisp (file)

Function: make-matrix M N
Package
Source

la.lisp (file)

Function: make-vector N &key INITIAL-ELEMENT
Package
Source

la.lisp (file)

Function: nm-iteration SIMPLEX F &key VERBOSE GAMMA_REFLECT GAMMA_EXPAND GAMMA_OUTER_CONTRACTION GAMMA_INNER_CONTRACTION GAMMA_SHRINK
Package
Source

Function: nm-iteration-burmen-et-al SIMPLEX F GRID &key VERBOSE GAMMA_REFLECT GAMMA_EXPAND GAMMA_OUTER_CONTRACTION GAMMA_INNER_CONTRACTION
Package
Source

Function: norm V &optional START
Package
Source

la.lisp (file)

Function: qr-factorization MAT &key WITH-Q
Package
Source

la.lisp (file)

Function: qrthing-closure S N
Package
Source

Function: regrid G X1 DMIN FKT
Package
Source

Function: simplex-qr-thing SIDEV
Package
Source

Function: v*c VECTOR CONSTANT
Package
Source

la.lisp (file)

Function: v+w*c V W C
Package
Source

la.lisp (file)

Next: , Previous: , Up: Internal definitions   [Contents][Index]

#### 5.2.4 Generic functions

Generic Function: best-before-reshape OBJECT
Generic Function: (setf best-before-reshape) NEW-VALUE OBJECT
Package
Methods
Method: best-before-reshape (CACHED-SIMPLEX-DATA cached-simplex-data)

Source

Method: (setf best-before-reshape) NEW-VALUE (CACHED-SIMPLEX-DATA cached-simplex-data)

automatically generated writer method

Source

Generic Function: cached-slot S SLOT COMPUTER
Package
Methods
Method: cached-slot (S nm-simplex) SLOT COMPUTER
Source

Generic Function: data OBJECT
Generic Function: (setf data) NEW-VALUE OBJECT
Package
Methods
Method: data (NM-SIMPLEX nm-simplex)

Source

Method: (setf data) NEW-VALUE (NM-SIMPLEX nm-simplex)

automatically generated writer method

Source

Generic Function: delta OBJECT
Generic Function: (setf delta) NEW-VALUE OBJECT
Package
Methods
Method: delta (GRID grid)

Source

Method: (setf delta) NEW-VALUE (GRID grid)

automatically generated writer method

Source

Generic Function: dimension S
Package
Methods
Method: dimension (S nm-simplex)
Source

Generic Function: dmin OBJECT
Generic Function: (setf dmin) NEW-VALUE OBJECT
Package
Methods
Method: dmin (CACHED-SIMPLEX-DATA cached-simplex-data)

Source

Method: (setf dmin) NEW-VALUE (CACHED-SIMPLEX-DATA cached-simplex-data)

automatically generated writer method

Source

Generic Function: dv OBJECT
Generic Function: (setf dv) NEW-VALUE OBJECT
Package
Methods
Method: dv (CACHED-SIMPLEX-DATA cached-simplex-data)

Source

Method: (setf dv) NEW-VALUE (CACHED-SIMPLEX-DATA cached-simplex-data)

automatically generated writer method

Source

Generic Function: fk S K
Generic Function: (setf fk) NV S K
Package
Methods
Method: fk (S nm-simplex) K
Method: (setf fk) NV (S nm-simplex) K
Source

Generic Function: fx OBJECT
Generic Function: (setf fx) NEW-VALUE OBJECT
Package
Methods
Method: fx (NM-SIMPLEX nm-simplex)

Source

Method: (setf fx) NEW-VALUE (NM-SIMPLEX nm-simplex)

automatically generated writer method

Source

Generic Function: grid-z OBJECT
Generic Function: (setf grid-z) NEW-VALUE OBJECT
Package
Methods
Method: grid-z (GRID grid)

Source

Method: (setf grid-z) NEW-VALUE (GRID grid)

automatically generated writer method

Source

Generic Function: improve S X FX
Package
Methods
Method: improve (S nm-simplex) X FX
Source

Generic Function: maybe-fill-simplex S F
Package
Methods
Method: maybe-fill-simplex (S nm-simplex) F
Source

Generic Function: maybe-reshape S G FF &key FORCE
Package
Methods
Method: maybe-reshape (S nm-simplex) (G grid) FF &key FORCE
Source

Generic Function: pmap OBJECT
Generic Function: (setf pmap) NEW-VALUE OBJECT
Package
Methods
Method: pmap (NM-SIMPLEX nm-simplex)

Source

Method: (setf pmap) NEW-VALUE (NM-SIMPLEX nm-simplex)

automatically generated writer method

Source

Generic Function: pseudopivot S
Package
Methods
Method: pseudopivot (S nm-simplex)
Source

Generic Function: q-factor S
Package
Methods
Method: q-factor (S nm-simplex)
Source

Generic Function: r-factor S
Package
Methods
Method: r-factor (S nm-simplex)
Source

Generic Function: restrict GRID POINT
Package
Methods
Method: restrict (GRID grid) POINT
Source

Generic Function: side-vectors S
Package
Methods
Method: side-vectors (S nm-simplex)
Source

Generic Function: sort-simplex S
Package
Methods
Method: sort-simplex (S nm-simplex)
Source

Generic Function: x OBJECT
Generic Function: (setf x) NEW-VALUE OBJECT
Package
Methods
Method: x (NM-SIMPLEX nm-simplex)

Source

Method: (setf x) NEW-VALUE (NM-SIMPLEX nm-simplex)

automatically generated writer method

Source

Generic Function: xk S K
Generic Function: (setf xk) NV S K
Package
Methods
Method: xk (S nm-simplex) K
Method: (setf xk) NV (S nm-simplex) K
Source

Previous: , Up: Internal definitions   [Contents][Index]

#### 5.2.5 Classes

Class: cached-simplex-data ()
Package
Source

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: pseudopivot
Slot: q-factor
Slot: side-vectors
Slot: r-factor
Slot: dv
Initargs

:dv

dv (generic function)

Writers

(setf dv) (generic function)

Slot: dmin
Initargs

:dmin

dmin (generic function)

Writers

(setf dmin) (generic function)

Slot: best-before-reshape
Initargs

:best-before-reshape

best-before-reshape (generic function)

Writers

(setf best-before-reshape) (generic function)

Class: grid ()
Package
Source

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: z
Initargs

:z

grid-z (generic function)

Writers

(setf grid-z) (generic function)

Slot: delta
Initargs

:delta

delta (generic function)

Writers

(setf delta) (generic function)

Class: nm-simplex ()
Package
Source

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: x
Initargs

:x

x (generic function)

Writers

(setf x) (generic function)

Slot: fx
Initargs

:fx

fx (generic function)

Writers

(setf fx) (generic function)

Slot: pmap
Initargs

:pmap

pmap (generic function)

Writers

(setf pmap) (generic function)

Slot: data

data (generic function)

Writers

(setf data) (generic function)

Previous: , Up: Top   [Contents][Index]

## Appendix A Indexes

Next: , Previous: , Up: Indexes   [Contents][Index]

### A.1 Concepts

Next: , Previous: , Up: Indexes   [Contents][Index]

### A.2 Functions

Jump to: (   B   C   D   F   G   I   M   N   P   Q   R   S   V   W   X
Jump to: (   B   C   D   F   G   I   M   N   P   Q   R   S   V   W   X

Next: , Previous: , Up: Indexes   [Contents][Index]

### A.3 Variables

Jump to: *   B   D   F   P   Q   R   S   X   Z
Jump to: *   B   D   F   P   Q   R   S   X   Z

Previous: , Up: Indexes   [Contents][Index]