README
¶
Looper: A flexible steppable control hierarchy
Docs: GoDoc
Looper implements a fully generic looping control system with extensible functionality at each level of the loop, with logic that supports reentrant stepping so each time it is Run it advances at any specified step size, with results that are identical to running.
Each loop implements the following logic:
OnStart() // run at start of loop
do {
Main() // run in loop
<run subloops>
} while !IsDone() // test for completion
OnEnd() // run after loop is done
The Loop object has the above function lists where function closures can be added to perform any relevant functionality.
Each level of loop holds a corresponding counter value, and the looper automatically increments and uses these counters to stop looping at a given level. Each Stack of loops is associated with a given etime.Mode, e.g., etime.Train or etime.Test.
Algorithm and Sim Integration
Specific algorithms use AddLevels to add inner, lower levels of loops to implement specific algorithm code (typically Phase and Cycle). Leabra and Axon use the Time struct as a context for holding the relevant counters and mode, which is then accessed directly in the callback functions as needed.
In cases where something must be done prior to looping through cycles (e.g., ApplyInputs and new phase startup methods), trigger it on the first cycle, before calling other functions, using a provided AddCycle0 function.
Concrete Example of Looping Logic
The stack_test.go can generate a trace the looping -- edit the if false to true to see.
Documentation
¶
Index ¶
- Variables
- type Ctr
- type Event
- type Loop
- type Manager
- func (man *Manager) AddEventAllModes(t etime.Times, event ...*Event)
- func (man *Manager) AddMainToAll(name string, fun func(mode etime.Modes, time etime.Times))
- func (man *Manager) AddOnEndToAll(name string, fun func(mode etime.Modes, time etime.Times))
- func (man *Manager) AddOnStartToAll(name string, fun func(mode etime.Modes, time etime.Times))
- func (man *Manager) AddStack(mode etime.Modes) *Stack
- func (man *Manager) ClearStep(mode etime.Modes)
- func (man *Manager) Cont()
- func (man *Manager) DocString() string
- func (man *Manager) GetLoop(modes etime.Modes, times etime.Times) *Loop
- func (man *Manager) Init()
- func (man *Manager) IsRunning() bool
- func (man *Manager) ModeStack() *Stack
- func (man *Manager) ResetAndRun(mode etime.Modes)
- func (man *Manager) ResetCounters()
- func (man *Manager) ResetCountersBelow(mode etime.Modes, time etime.Times)
- func (man *Manager) ResetCountersByMode(mode etime.Modes)
- func (man *Manager) Run(mode etime.Modes)
- func (man *Manager) Step(mode etime.Modes, numSteps int, stopscale etime.Times)
- func (man *Manager) Stop(level etime.Times)
- type NamedFunc
- type NamedFuncs
- func (funcs *NamedFuncs) Add(name string, fun func()) *NamedFuncs
- func (funcs *NamedFuncs) Delete(nm string) error
- func (funcs *NamedFuncs) FindName(nm string) (int, error)
- func (funcs *NamedFuncs) HasNameLike(nameSubstring string) bool
- func (funcs *NamedFuncs) InsertAfter(after, nm string, f func()) error
- func (funcs *NamedFuncs) InsertAt(i int, nm string, f func())
- func (funcs *NamedFuncs) InsertBefore(before, nm string, f func()) error
- func (funcs *NamedFuncs) Prepend(nm string, f func())
- func (funcs *NamedFuncs) Replace(nm string, f func()) error
- func (funcs *NamedFuncs) String() string
- type NamedFuncsBool
- type Stack
- func (stack *Stack) AddMainToAll(name string, fun func(mode etime.Modes, time etime.Times))
- func (stack *Stack) AddOnEndToAll(name string, fun func(mode etime.Modes, time etime.Times))
- func (stack *Stack) AddOnStartToAll(name string, fun func(mode etime.Modes, time etime.Times))
- func (stack *Stack) AddTime(time etime.Times, ctrMax int) *Stack
- func (stack *Stack) AddTimeIncr(time etime.Times, ctrMax, ctrIncr int) *Stack
- func (stack *Stack) ClearStep()
- func (stack *Stack) CtrsToStats(stats *estats.Stats)
- func (stack *Stack) Init(mode etime.Modes)
- func (stack *Stack) SetStep(numSteps int, stopscale etime.Times)
- func (stack *Stack) TimeAbove(time etime.Times) etime.Times
- func (stack *Stack) TimeBelow(time etime.Times) etime.Times
Constants ¶
This section is empty.
Variables ¶
var ( // If you want to debug the flow of time, set this to true. PrintControlFlow = false // If PrintControlFlow = true, this cuts off printing at timescales // that are faster than this -- default is to print all. NoPrintBelow = etime.AllTimes )
Functions ¶
This section is empty.
Types ¶
type Ctr ¶
type Ctr struct {
// current counter value
Cur int
// maximum counter value -- only used if > 0
Max int
// increment per iteration
Inc int
}
Ctr combines an integer with a maximum value. It supports time tracking within looper.
func (*Ctr) Incr ¶
func (ct *Ctr) Incr()
Incr increments the counter by 1. Does not interact with Max.
func (*Ctr) Set ¶
Set sets the Cur value with return value indicating whether it is different from current Cur.
func (*Ctr) SetCurMaxPlusN ¶
SetCurMaxPlusN sets the Cur value and Max as Cur + N -- run N more beyond current.
type Event ¶
type Event struct {
// Might be 'plus' or 'minus' for example.
Name string
// The counter value upon which this Event occurs.
AtCtr int
// Callback function for the Event.
OnEvent NamedFuncs
}
A Event has function(s) that can be called at a particular point in the loop, when the counter is AtCtr value.
type Loop ¶
type Loop struct {
// Tracks time within the loop. Also tracks the maximum. OnStart, Main, and OnEnd will be called Ctr.Max times, or until IsDone is satisfied, whichever ends first.
Counter Ctr
// OnStart is called at the beginning of each loop.
OnStart NamedFuncs
// OnStart is called in the middle of each loop. In general, only use Main for the last Loop in a Stack. For example, actual Net updates might occur here.
Main NamedFuncs
// OnStart is called at the end of each loop.
OnEnd NamedFuncs
// If true, end loop. Maintained as an unordered map because they should not have side effects.
IsDone NamedFuncsBool
// Events occur when Ctr.Cur gets to their AtCtr.
Events []*Event
}
Loop contains one level of a multi-level iteration scheme. It wraps around an inner loop recorded in a Stack, or around Main functions. It records how many times the loop should be repeated in the Counter. It records what happens at the beginning and end of each loop. For example, a loop with 1 start, 1 end, and a Counter with max=3 will do: Start, Inner, End, Start, Inner, End, Start, Inner, End Where the Inner loop is specified by a Stack or by Main, and Start and End are functions on the loop. See Stack for more details on how loops are combined.
func (*Loop) AddNewEvent ¶
AddNewEvent to the list.
func (*Loop) EventByName ¶
EventByName returns event by name, false if not found
type Manager ¶
type Manager struct {
// map of stacks by Mode
Stacks map[etime.Modes]*Stack
// The current evaluation mode.
Mode etime.Modes
// contains filtered or unexported fields
}
Manager holds data relating to multiple stacks of loops, as well as the logic for stepping through it. It also holds helper methods for constructing the data. It's also a control object for stepping through Stacks of Loops. It holds data about how the flow is going.
func (*Manager) AddEventAllModes ¶
AddEventAllModes adds Event(s) to all stacks at given time
func (*Manager) AddMainToAll ¶
AddMainToAll adds given function taking mode and time args to Main in all stacks, loops
func (*Manager) AddOnEndToAll ¶
AddOnEndToAll adds given function taking mode and time args to OnEnd in all stacks, loops
func (*Manager) AddOnStartToAll ¶
AddOnStartToAll adds given function taking mode and time args to OnStart in all stacks, loops
func (*Manager) ClearStep ¶
ClearStep clears stepping variables from given mode, so it will run to completion in a subsequent Cont(). Called by Run
func (*Manager) Cont ¶
func (man *Manager) Cont()
Cont continues running based on current state of the manager. This is common pathway for Step and Run, which set state and call Cont. Programatic calling of Step can continue with Cont.
func (*Manager) DocString ¶
DocString returns an indented summary of the loops and functions in the stack.
func (*Manager) GetLoop ¶
GetLoop returns the Loop associated with an evaluation mode and timescale.
func (*Manager) Init ¶
func (man *Manager) Init()
Init initializes the state of the manager, to be called on a newly created object.
func (*Manager) ResetAndRun ¶
ResetAndRun calls ResetCountersByMode on this mode and then Run. This ensures that the Stack is run from the start, regardless of what state it might have been in.
func (*Manager) ResetCounters ¶
func (man *Manager) ResetCounters()
ResetCounters resets the Cur on all loop Counters, and resets the Manager's place in the loops.
func (*Manager) ResetCountersBelow ¶
ResetCountersBelow resets the Cur on all loop Counters below given level (inclusive), and resets the Manager's place in the loops.
func (*Manager) ResetCountersByMode ¶
ResetCountersByMode resets counters for given mode.
func (*Manager) Run ¶
Run runs the stack of loops for given mode (Train, Test, etc). This resets any stepping settings for this stack and runs until completion or stopped externally.
type NamedFunc ¶
type NamedFunc struct {
Name string
Func func()
}
NamedFunc lets you keep an ordered map of functions.
type NamedFuncs ¶
type NamedFuncs []NamedFunc
NamedFunc is an ordered map of functions.
func (*NamedFuncs) Add ¶
func (funcs *NamedFuncs) Add(name string, fun func()) *NamedFuncs
Add adds a named function to a list.
func (*NamedFuncs) Delete ¶
func (funcs *NamedFuncs) Delete(nm string) error
Delete deletes function of given name
func (*NamedFuncs) FindName ¶
func (funcs *NamedFuncs) FindName(nm string) (int, error)
FindName finds index of function by name, returns not found err message if not found
func (*NamedFuncs) HasNameLike ¶
func (funcs *NamedFuncs) HasNameLike(nameSubstring string) bool
HasNameLike checks if there's an existing function that contains a substring. This could be helpful to ensure that you don't add duplicate logic to a list of functions. If you plan on using this, add a comment documenting which name is important, because the default assumption is that names are just documentation.
func (*NamedFuncs) InsertAfter ¶
func (funcs *NamedFuncs) InsertAfter(after, nm string, f func()) error
InsertAfter inserts function after other function of given name
func (*NamedFuncs) InsertAt ¶
func (funcs *NamedFuncs) InsertAt(i int, nm string, f func())
InsertAt inserts function at given index
func (*NamedFuncs) InsertBefore ¶
func (funcs *NamedFuncs) InsertBefore(before, nm string, f func()) error
InsertBefore inserts function before other function of given name
func (*NamedFuncs) Prepend ¶
func (funcs *NamedFuncs) Prepend(nm string, f func())
Prepend adds a function to the start of the list
func (*NamedFuncs) Replace ¶
func (funcs *NamedFuncs) Replace(nm string, f func()) error
Replace replaces function with other function of given name
func (*NamedFuncs) String ¶
func (funcs *NamedFuncs) String() string
String describes named functions.
type NamedFuncsBool ¶
NamedFuncsBool is like NamedFuncs, but for functions that return a bool.
func (*NamedFuncsBool) Add ¶
func (funcs *NamedFuncsBool) Add(name string, f func() bool)
Add adds a function by name.
type Stack ¶
type Stack struct {
// evaluation mode for this stack
Mode etime.Modes
// An ordered map of Loops, from the outer loop at the start to the inner loop at the end.
Loops map[etime.Times]*Loop
// The list and order of time scales looped over by this stack of loops, ordered from top to bottom, so longer timescales like Run should be at the beginning and shorter timescales like Trial should be and the end.
Order []etime.Times
// If true, stop model at the end of the current StopLevel.
StopNext bool
// If true, stop model ASAP.
StopFlag bool
// Time level to stop at the end of.
StopLevel etime.Times
// How many iterations at StopLevel before actually stopping.
StopIterations int
// Saved Time level for stepping -- what was set for last step or by gui.
StepLevel etime.Times
// Saved number of steps for stepping -- what was set for last step or by gui.
StepIterations int
}
Stack contains a list of Loops Ordered from top to bottom. For example, a Stack might be created like this:
mystack := manager.AddStack(etime.Train).AddTime(etime.Run, 2).AddTime(etime.Trial, 3)
myStack.Loops[etime.Run].OnStart.Add("NewRun", initRunFunc)
myStack.Loops[etime.Trial].OnStart.Add("PresentTrial", trialFunc)
When run, myStack will behave like this: initRunFunc, trialFunc, trialFunc, trialFunc, initRunFunc, trialFunc, trialFunc, trialFunc
func (*Stack) AddMainToAll ¶
AddMainToAll adds given function taking mode and time args to Main in all loops
func (*Stack) AddOnEndToAll ¶
AddOnEndToAll adds given function taking mode and time args to OnEnd in all loops
func (*Stack) AddOnStartToAll ¶
AddOnStartToAll adds given function taking mode and time args to OnStart in all loops
func (*Stack) AddTime ¶
AddTime adds a new timescale to this Stack with a given ctrMax number of iterations. The order in which this method is invoked is important, as it adds loops in order from top to bottom. Sets a default increment of 1 for the counter -- see AddTimeIncr for different increment.
func (*Stack) AddTimeIncr ¶
AddTimeIncr adds a new timescale to this Stack with a given ctrMax number of iterations, and increment per step. The order in which this method is invoked is important, as it adds loops in order from top to bottom.
func (*Stack) CtrsToStats ¶
CtrsToStats sets the current counter values to estats Int values by their time names only (no eval Mode). These values can then be read by elog LogItems to record the counters in logs. Typically, a TrialName string is also expected to be set, to describe the current trial (Step) contents in a useful way, and other relevant info (e.g., group / category info) can also be set.
Source Files