Update documentation for Global and clean up usage of globalStatus #187

btracey · 2016-10-13T19:17:19Z

No description provided.

btracey · 2016-10-13T19:17:46Z

This changes the wording somewhat from the Local documentation, I can rectify the differences when we like the Global wording.

sbinet · 2016-11-15T14:20:30Z

global.go

+}
+
+// globalOperation executes the requested operation at the given location.
+// Modifications to this function must keep in mind that it can be called


"Modifications to this function must keep in mind that it..."

this reads a bit funny.

perhaps:
Modifications to this function must be applied while keeping in mind that globalOperation can be...

sbinet · 2016-12-09T08:36:55Z

global.go

-	// Done communicates to the optimization method that the optimization has
-	// concluded to allow for shutdown.
+
+	// Done communicates that the optimization has concluded to allow for shutdown.


perhaps semantically relate it to the sync.WaitGroup.Done() method? (or explicitly unrelate it to that)

I was a bit thrown off tracks that it didn't return anything (not even struct{}) so it couldn't really be used like in:

for { select { case <-gm.Done(): // do clean-up } }

and then I remembered that it looked a bit like sync.WaitGroup.Done().

vladimir-ch

I've returned to this after a long time, some comments are old, some are new. Read them accordingly.

vladimir-ch · 2016-10-30T23:08:15Z

global.go

+// operation, the requested fields of Problem will be evaluated at the value
+// in Location.X, filling the corresponding fields of Location. These values
+// can be retrieved and used upon the next call to IterateGlobal with that task id.
+// The corresponding fields of Location will be filled with the results that


Delete this line

vladimir-ch · 2016-10-30T23:15:26Z

global.go

+// aside from the commanded evaluations. Thus, the type implementing Method may
+// use multiple Operations to set the Location fields at a particular x value.
+//
+// A GlobalMethod may alternately declare MajorIteration. This updates the optimal


I would rewrite this paragraph to something like:

When IterateGlobal declares MajorIteration, the caller can update the optimal location to the values in Location, and check for convergence. The type implementing GlobalMethod must make sure that the fields of Location are valid and consistent.

vladimir-ch · 2016-10-30T23:18:07Z

global.go

+// location to the values in Location, and checks for the convergence of the
+// optimization. Consequently, the fields of Location must be valid and consistent.
+//
+// A GlobalMethod must not return InitIteration and PostIteration operations. These are


s/A GlobalMethod/IterateGlobal/

vladimir-ch · 2016-10-30T23:26:29Z

global.go

+// optimization. Consequently, the fields of Location must be valid and consistent.
+//
+// A GlobalMethod must not return InitIteration and PostIteration operations. These are
+// reserved for the clients to be passed to Recorders. A Method must also not


s/A Method/IterateGlobal/

vladimir-ch · 2017-04-11T04:28:59Z

global.go

+// can be retrieved and used upon the next call to IterateGlobal with that task id.
+// The corresponding fields of Location will be filled with the results that
+// The GlobalMethod interface requires that entries of Location are not modified
+// aside from the commanded evaluations. Thus, the type implementing Method may


s/Method/GlobalMethod/

vladimir-ch · 2017-04-16T22:44:43Z

global.go

-// It uses a mutex to protect updates where necessary.
-func (g *globalStatus) globalOperation(op Operation, loc *Location, x []float64) Status {
-	// Do a quick check to see if one of the other workers converged in the meantime.
+// globalStatus is a data struct that coordinates information between concurrently


globalStatus coordinates access to information shared between ...?

vladimir-ch · 2017-04-16T22:46:17Z

global.go

+
+// updateStatus updates the status and error fields of g. This update only happens
+// if status == NotTerminated, so that the first different status is the one
+// maintained


Dot at the end.

vladimir-ch · 2017-04-16T22:47:08Z

global.go

+// globalOperation executes the requested operation at the given location.
+// When modifying this function, keep in mind that it can be called concurrently.
+// Uses of the internal fields should be through the methods of globalStatus and
+// protected by a mux where appropriate.


vladimir-ch · 2017-04-16T22:48:03Z

global.go

 	switch op {
 	case NoOperation:
 	case InitIteration:
 		panic("optimize: Method returned InitIteration")


GlobalMethod

vladimir-ch · 2017-04-16T22:48:13Z

global.go

 	case InitIteration:
 		panic("optimize: Method returned InitIteration")
 	case PostIteration:
 		panic("optimize: Method returned PostIteration")


GlobalMethod

btracey · 2017-04-29T15:10:13Z

Done on all requests.

btracey · 2017-10-17T15:16:26Z

Implemented by gonum/gonum#265

sbinet reviewed Nov 15, 2016

View reviewed changes

sbinet reviewed Dec 9, 2016

View reviewed changes

vladimir-ch reviewed Apr 16, 2017

View reviewed changes

vladimir-ch approved these changes May 4, 2017

View reviewed changes

Update documentation for Global and clean up usage of globalStatus

49cd999

btracey force-pushed the globdoc branch from 4d20b00 to 49cd999 Compare May 5, 2017 14:39

btracey closed this Oct 17, 2017

Update documentation for Global and clean up usage of globalStatus #187

Update documentation for Global and clean up usage of globalStatus #187

Uh oh!

Conversation

btracey commented Oct 13, 2016

Uh oh!

btracey commented Oct 13, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vladimir-ch left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

btracey commented Apr 29, 2017

Uh oh!

btracey commented Oct 17, 2017

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants