Merge branch 'remove-evaluationtype'

Closes #122
Resolves #103

Author: vladimir-ch

backtracking.go

@@ -33,7 +33,7 @@ type Backtracking struct {
 	initG    float64
 }
 
-func (b *Backtracking) Init(f, g float64, step float64) EvaluationType {
+func (b *Backtracking) Init(f, g float64, step float64) Operation {
 	if step <= 0 {
 		panic("backtracking: bad step size")
 	}
@@ -64,10 +64,10 @@ func (b *Backtracking) Finished(f, _ float64) bool {
 	return ArmijoConditionMet(f, b.initF, b.initG, b.stepSize, b.FuncConst)
 }
 
-func (b *Backtracking) Iterate(_, _ float64) (float64, EvaluationType, error) {
+func (b *Backtracking) Iterate(_, _ float64) (float64, Operation, error) {
 	b.stepSize *= b.Decrease
 	if b.stepSize < minimumBacktrackingStepSize {
-		return 0, NoEvaluation, ErrLinesearchFailure
+		return 0, NoOperation, ErrLinesearchFailure
 	}
 	return b.stepSize, FuncEvaluation, nil
 }

bfgs.go

@@ -39,7 +39,7 @@ type BFGS struct {
 	first bool // Is it the first iteration (used to set the scale of the initial hessian)
 }
 
-func (b *BFGS) Init(loc *Location, xNext []float64) (EvaluationType, IterationType, error) {
+func (b *BFGS) Init(loc *Location) (Operation, error) {
 	if b.Linesearcher == nil {
 		b.Linesearcher = &Bisection{}
 	}
@@ -49,11 +49,11 @@ func (b *BFGS) Init(loc *Location, xNext []float64) (EvaluationType, IterationTy
 	b.ls.Linesearcher = b.Linesearcher
 	b.ls.NextDirectioner = b
 
-	return b.ls.Init(loc, xNext)
+	return b.ls.Init(loc)
 }
 
-func (b *BFGS) Iterate(loc *Location, xNext []float64) (EvaluationType, IterationType, error) {
-	return b.ls.Iterate(loc, xNext)
+func (b *BFGS) Iterate(loc *Location) (Operation, error) {
+	return b.ls.Iterate(loc)
 }
 
 func (b *BFGS) InitDirection(loc *Location, dir []float64) (stepSize float64) {

bisection.go

@@ -26,7 +26,7 @@ type Bisection struct {
 	maxGrad  float64
 }
 
-func (b *Bisection) Init(f, g float64, step float64) EvaluationType {
+func (b *Bisection) Init(f, g float64, step float64) Operation {
 	if step <= 0 {
 		panic("bisection: bad step size")
 	}
@@ -73,7 +73,7 @@ func (b *Bisection) Finished(f, g float64) bool {
 	return false
 }
 
-func (b *Bisection) Iterate(f, g float64) (float64, EvaluationType, error) {
+func (b *Bisection) Iterate(f, g float64) (float64, Operation, error) {
 	// Deciding on the next step size
 	if math.IsInf(b.maxStep, 1) {
 		// Have not yet bounded the minimum
@@ -135,10 +135,10 @@ func (b *Bisection) Iterate(f, g float64) (float64, EvaluationType, error) {
 // both of which indicate the minimization must stop. If the steps are different,
 // it sets the new step size and returns the step and evaluation type. If the steps
 // are the same, it returns an error.
-func (b *Bisection) checkStepEqual(newStep float64, e EvaluationType) (float64, EvaluationType, error) {
+func (b *Bisection) checkStepEqual(newStep float64, op Operation) (float64, Operation, error) {
 	if b.currStep == newStep {
-		return b.currStep, NoEvaluation, ErrLinesearchFailure
+		return b.currStep, NoOperation, ErrLinesearchFailure
 	}
 	b.currStep = newStep
-	return newStep, e, nil
+	return newStep, op, nil
 }

cg.go

@@ -94,7 +94,7 @@ type CG struct {
 	gradPrevNorm float64
 }
 
-func (cg *CG) Init(loc *Location, xNext []float64) (EvaluationType, IterationType, error) {
+func (cg *CG) Init(loc *Location) (Operation, error) {
 	if cg.IterationRestartFactor < 0 {
 		panic("cg: IterationRestartFactor is negative")
 	}
@@ -125,11 +125,11 @@ func (cg *CG) Init(loc *Location, xNext []float64) (EvaluationType, IterationTyp
 	cg.ls.Linesearcher = cg.Linesearcher
 	cg.ls.NextDirectioner = cg
 
-	return cg.ls.Init(loc, xNext)
+	return cg.ls.Init(loc)
 }
 
-func (cg *CG) Iterate(loc *Location, xNext []float64) (EvaluationType, IterationType, error) {
-	return cg.ls.Iterate(loc, xNext)
+func (cg *CG) Iterate(loc *Location) (Operation, error) {
+	return cg.ls.Iterate(loc)
 }
 
 func (cg *CG) InitDirection(loc *Location, dir []float64) (stepSize float64) {

gradientdescent.go

@@ -18,7 +18,7 @@ type GradientDescent struct {
 	ls *LinesearchMethod
 }
 
-func (g *GradientDescent) Init(loc *Location, xNext []float64) (EvaluationType, IterationType, error) {
+func (g *GradientDescent) Init(loc *Location) (Operation, error) {
 	if g.StepSizer == nil {
 		g.StepSizer = &QuadraticStepSize{}
 	}
@@ -31,11 +31,11 @@ func (g *GradientDescent) Init(loc *Location, xNext []float64) (EvaluationType,
 	g.ls.Linesearcher = g.Linesearcher
 	g.ls.NextDirectioner = g
 
-	return g.ls.Init(loc, xNext)
+	return g.ls.Init(loc)
 }
 
-func (g *GradientDescent) Iterate(loc *Location, xNext []float64) (EvaluationType, IterationType, error) {
-	return g.ls.Iterate(loc, xNext)
+func (g *GradientDescent) Iterate(loc *Location) (Operation, error) {
+	return g.ls.Iterate(loc)
 }
 
 func (g *GradientDescent) InitDirection(loc *Location, dir []float64) (stepSize float64) {

interfaces.go

@@ -5,14 +5,40 @@
 package optimize
 
 // A Method can optimize an objective function.
+//
+// It uses a reverse-communication interface between the optimization method
+// and the caller. Method acts as a client that asks the caller to perform
+// needed operations via RequestType returned from Init and Iterate methods.
+// This provides independence of the optimization algorithm on user-supplied
+// data and their representation, and enables automation of common operations
+// like checking for (various types of) convergence and maintaining statistics.
+//
+// A Method can command an Evaluation, a MajorIteration or NoOperation operations.
+// An evaluation operation is one or more of the Evaluation operations
+// (FuncEvaluation, GradEvaluation, etc.) which can be combined with
+// the bitwise or operator. In an evaluation operation, the requested routines
+// will be evaluated at the point specified in Location.X. The corresponding
+// fields of Location will be filled with the results from the routine and can
+// be retrieved upon the next call to Iterate. Alternatively, a Method can
+// declare a MajorIteration. In a MajorIteration, all values in Location must
+// be valid and consistent, and are interpreted as a new minimum. Convergence
+// of the optimization (GradientThreshold, etc.) will be checked using this new
+// minimum.
+//
+// A Method must not return InitIteration and PostIteration operations. These are
+// reserved for the clients to be passed to Recorders. A Method must also not
+// combine the Evaluation operations with the Iteration operations.
 type Method interface {
-	// Init initializes the method and stores the first location to evaluate
-	// in xNext.
-	Init(loc *Location, xNext []float64) (EvaluationType, IterationType, error)
+	// Init initializes the method based on the initial data in loc, updates it
+	// and returns the first operation to be carried out by the caller.
+	// The initial location must be valid as specified by Needs().
+	Init(loc *Location) (Operation, error)
 
-	// Iterate performs one iteration of the method and stores the next
-	// location to evaluate in xNext.
-	Iterate(loc *Location, xNext []float64) (EvaluationType, IterationType, error)
+	// Iterate retrieves data from loc, performs one iteration of the method,
+	// updates loc and returns the next operation.
+	// TODO(vladimir-ch): When decided, say something whether the contents of
+	// Location is preserved between calls to Iterate().
+	Iterate(loc *Location) (Operation, error)
 
 	// Needs specifies information about the objective function needed by the
 	// optimizer beyond just the function value. The information is used
@@ -24,6 +50,13 @@ type Method interface {
 	}
 }
 
+// Statuser can report the status and any error. It is intended for methods as
+// an additional error reporting mechanism apart from the errors returned from
+// Init() and Iterate().
+type Statuser interface {
+	Status() (Status, error)
+}
+
 // Linesearcher is a type that can perform a line search. It tries to find an
 // (approximate) minimum of the objective function along the search direction
 // dir_k starting at the most recent location x_k, i.e., it tries to minimize
@@ -36,7 +69,7 @@ type Linesearcher interface {
 	// φ(0) and φ'(0), respectively, and step contains the first trial step
 	// length. It returns the type of evaluation to be performed at
 	// x_0 + step * dir_0.
-	Init(value, derivative float64, step float64) EvaluationType
+	Init(value, derivative float64, step float64) Operation
 
 	// Finished takes in the values of φ and φ' evaluated at the previous step,
 	// and returns whether a sufficiently accurate minimum of φ has been found.
@@ -45,7 +78,7 @@ type Linesearcher interface {
 	// Iterate takes in the values of φ and φ' evaluated at the previous step
 	// and returns the next step size and the type of evaluation to be
 	// performed at x_k + step * dir_k.
-	Iterate(value, derivative float64) (step float64, e EvaluationType, err error)
+	Iterate(value, derivative float64) (step float64, op Operation, err error)
 }
 
 // NextDirectioner implements a strategy for computing a new line search
@@ -72,17 +105,9 @@ type StepSizer interface {
 	StepSize(loc *Location, dir []float64) float64
 }
 
-// Statuser returns the status of the Function being optimized. This can be used
-// by the Function to terminate early, for example with an error. The user can
-// use one of the pre-provided Status constants, or may call NewStatus to create
-// a custom Status value.
-type Statuser interface {
-	Status() (Status, error)
-}
-
 // A Recorder can record the progress of the optimization, for example to print
 // the progress to StdOut or to a log file. A Recorder must not modify any data.
 type Recorder interface {
 	Init() error
-	Record(*Location, EvaluationType, IterationType, *Stats) error
+	Record(*Location, Operation, *Stats) error
 }

lbfgs.go

@@ -38,7 +38,7 @@ type LBFGS struct {
 	rhoHist []float64   // last Store iterations of rho
 }
 
-func (l *LBFGS) Init(loc *Location, xNext []float64) (EvaluationType, IterationType, error) {
+func (l *LBFGS) Init(loc *Location) (Operation, error) {
 	if l.Linesearcher == nil {
 		l.Linesearcher = &Bisection{}
 	}
@@ -47,11 +47,11 @@ func (l *LBFGS) Init(loc *Location, xNext []float64) (EvaluationType, IterationT
 	}
 	l.ls.Linesearcher = l.Linesearcher
 	l.ls.NextDirectioner = l
-	return l.ls.Init(loc, xNext)
+	return l.ls.Init(loc)
 }
 
-func (l *LBFGS) Iterate(loc *Location, xNext []float64) (EvaluationType, IterationType, error) {
-	return l.ls.Iterate(loc, xNext)
+func (l *LBFGS) Iterate(loc *Location) (Operation, error) {
+	return l.ls.Iterate(loc)
 }
 
 func (l *LBFGS) InitDirection(loc *Location, dir []float64) (stepSize float64) {