looper

package
v1.4.31 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 27, 2023 License: BSD-3-Clause Imports: 7 Imported by: 35

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

Constants

This section is empty.

Variables

View Source 
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 added in v1.2.3 

type Ctr struct {

	// current counter value
	Cur int `desc:"current counter value"`

	// maximum counter value -- only used if > 0
	Max int `desc:"maximum counter value -- only used if > 0"`

	// increment per iteration
	Inc int `desc:"increment per iteration"`
}

Ctr combines an integer with a maximum value. It supports time tracking within looper.

func (*Ctr) Incr added in v1.2.3 

func (ct *Ctr) Incr()

Incr increments the counter by 1. Does not interact with Max.

func (*Ctr) IsOverMax added in v1.2.3 

func (ct *Ctr) IsOverMax() bool

IsOverMax returns true if counter is at or over Max (only if Max > 0)

func (*Ctr) Set added in v1.2.3 

func (ct *Ctr) Set(cur int) bool

Set sets the Cur value with return value indicating whether it is different from current Cur.

func (*Ctr) SetCurMax added in v1.4.14 

func (ct *Ctr) SetCurMax(cur, max int)

SetCurMax sets the Cur and Max values, as a convenience.

func (*Ctr) SetCurMaxPlusN added in v1.4.14 

func (ct *Ctr) SetCurMaxPlusN(cur, n int)

SetCurMaxPlusN sets the Cur value and Max as Cur + N -- run N more beyond current.

func (*Ctr) SkipToMax added in v1.3.44 

func (ct *Ctr) SkipToMax()

SkipToMax sets the counter to its Max value -- for skipping over rest of loop

type Event added in v1.2.3 

type Event struct {

	// Might be 'plus' or 'minus' for example.
	Name string `desc:"Might be 'plus' or 'minus' for example."`

	// The counter value upon which this Event occurs.
	AtCtr int `desc:"The counter value upon which this Event occurs."`

	// Callback function for the Event.
	OnEvent NamedFuncs `desc:"Callback function for the Event."`
}

A Event has function(s) that can be called at a particular point in the loop, when the counter is AtCtr value.

func NewEvent added in v1.3.9 

func NewEvent(name string, atCtr int, fun func()) *Event

NewEvent returns a new event with given name, function, at given counter

func (*Event) String added in v1.2.3 

func (event *Event) String() string

String describes the Event in human readable text.

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 `` /* 167-byte string literal not displayed */

	// OnStart is called at the beginning of each loop.
	OnStart NamedFuncs `desc:"OnStart is called at the beginning of each loop."`

	// 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 `` /* 158-byte string literal not displayed */

	// OnStart is called at the end of each loop.
	OnEnd NamedFuncs `desc:"OnStart is called at the end of each loop."`

	// If true, end loop. Maintained as an unordered map because they should not have side effects.
	IsDone NamedFuncsBool `desc:"If true, end loop. Maintained as an unordered map because they should not have side effects."`

	// Events occur when Ctr.Cur gets to their AtCtr.
	Events []*Event `desc:"Events occur when Ctr.Cur gets to their AtCtr."`
}

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) AddEvents added in v1.2.3 

func (lp *Loop) AddEvents(events ...*Event)

AddEvents to the list of events.

func (*Loop) AddNewEvent added in v1.3.9 

func (lp *Loop) AddNewEvent(name string, atCtr int, fun func()) *Event

AddNewEvent to the list.

func (*Loop) EventByName added in v1.3.15 

func (lp *Loop) EventByName(name string) (*Event, bool)

EventByName returns event by name, false if not found

func (*Loop) SkipToMax added in v1.3.44 

func (lp *Loop) SkipToMax()

SkipToMax sets the counter to its Max value for this level. for skipping over rest of loop

type Manager added in v1.2.3 

type Manager struct {

	// map of stacks by Mode
	Stacks map[etime.Modes]*Stack `desc:"map of stacks by Mode"`

	// The current evaluation mode.
	Mode etime.Modes `desc:"The current evaluation mode."`
	// 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 NewManager added in v1.3.1 

func NewManager() *Manager

NewManager returns a new initialized manager

func (*Manager) AddEventAllModes added in v1.2.3 

func (man *Manager) AddEventAllModes(t etime.Times, event ...*Event)

AddEventAllModes adds Event(s) to all stacks at given time

func (*Manager) AddMainToAll added in v1.3.3 

func (man *Manager) AddMainToAll(name string, fun func(mode etime.Modes, time etime.Times))

AddMainToAll adds given function taking mode and time args to Main in all stacks, loops

func (*Manager) AddOnEndToAll added in v1.3.3 

func (man *Manager) AddOnEndToAll(name string, fun func(mode etime.Modes, time etime.Times))

AddOnEndToAll adds given function taking mode and time args to OnEnd in all stacks, loops

func (*Manager) AddOnStartToAll added in v1.3.3 

func (man *Manager) AddOnStartToAll(name string, fun func(mode etime.Modes, time etime.Times))

AddOnStartToAll adds given function taking mode and time args to OnStart in all stacks, loops

func (*Manager) AddStack added in v1.2.3 

func (man *Manager) AddStack(mode etime.Modes) *Stack

AddStack adds a new Stack for given mode

func (*Manager) ClearStep added in v1.3.17 

func (man *Manager) ClearStep(mode etime.Modes)

ClearStep clears stepping variables from given mode, so it will run to completion in a subsequent Cont(). Called by Run

func (*Manager) Cont added in v1.3.17 

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 added in v1.2.3 

func (man *Manager) DocString() string

DocString returns an indented summary of the loops and functions in the stack.

func (*Manager) GetLoop added in v1.2.3 

func (man *Manager) GetLoop(modes etime.Modes, times etime.Times) *Loop

GetLoop returns the Loop associated with an evaluation mode and timescale.

func (*Manager) Init added in v1.2.3 

func (man *Manager) Init()

Init initializes the state of the manager, to be called on a newly created object.

func (*Manager) IsRunning added in v1.2.3 

func (man *Manager) IsRunning() bool

IsRunning is True if running.

func (*Manager) ModeStack added in v1.3.41 

func (man *Manager) ModeStack() *Stack

ModeStack returns the Stack for the current Mode

func (*Manager) ResetAndRun added in v1.3.17 

func (man *Manager) ResetAndRun(mode etime.Modes)

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 added in v1.2.3 

func (man *Manager) ResetCounters()

ResetCounters resets the Cur on all loop Counters, and resets the Manager's place in the loops.

func (*Manager) ResetCountersBelow added in v1.3.51 

func (man *Manager) ResetCountersBelow(mode etime.Modes, time etime.Times)

ResetCountersBelow resets the Cur on all loop Counters below given level (inclusive), and resets the Manager's place in the loops.

func (*Manager) ResetCountersByMode added in v1.2.3 

func (man *Manager) ResetCountersByMode(mode etime.Modes)

ResetCountersByMode resets counters for given mode.

func (*Manager) Run added in v1.2.3 

func (man *Manager) Run(mode etime.Modes)

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.

func (*Manager) Step added in v1.2.3 

func (man *Manager) Step(mode etime.Modes, numSteps int, stopscale etime.Times)

Step numSteps stopscales. Use this if you want to do exactly one trial or two epochs or 50 cycles or whatever

func (*Manager) Stop added in v1.3.17 

func (man *Manager) Stop(level etime.Times)

Stop stops currently running stack of loops at given run time level

type NamedFunc 

type NamedFunc struct {
	Name string
	Func func()
}

NamedFunc lets you keep an ordered map of functions.

type NamedFuncs added in v1.2.3 

type NamedFuncs []NamedFunc

NamedFunc is an ordered map of functions.

func (*NamedFuncs) Add added in v1.2.3 

func (funcs *NamedFuncs) Add(name string, fun func()) *NamedFuncs

Add adds a named function to a list.

func (*NamedFuncs) Delete added in v1.3.9 

func (funcs *NamedFuncs) Delete(nm string) error

Delete deletes function of given name

func (*NamedFuncs) FindName added in v1.3.9 

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 added in v1.2.3 

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 added in v1.3.9 

func (funcs *NamedFuncs) InsertAfter(after, nm string, f func()) error

InsertAfter inserts function after other function of given name

func (*NamedFuncs) InsertAt added in v1.3.9 

func (funcs *NamedFuncs) InsertAt(i int, nm string, f func())

InsertAt inserts function at given index

func (*NamedFuncs) InsertBefore added in v1.3.9 

func (funcs *NamedFuncs) InsertBefore(before, nm string, f func()) error

InsertBefore inserts function before other function of given name

func (*NamedFuncs) Prepend added in v1.3.9 

func (funcs *NamedFuncs) Prepend(nm string, f func())

Prepend adds a function to the start of the list

func (*NamedFuncs) Replace added in v1.3.9 

func (funcs *NamedFuncs) Replace(nm string, f func()) error

Replace replaces function with other function of given name

func (*NamedFuncs) String added in v1.2.3 

func (funcs *NamedFuncs) String() string

String describes named functions.

type NamedFuncsBool added in v1.2.3 

type NamedFuncsBool map[string]func() bool

NamedFuncsBool is like NamedFuncs, but for functions that return a bool.

func (*NamedFuncsBool) Add added in v1.2.3 

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 `desc:"evaluation mode for this stack"`

	// An ordered map of Loops, from the outer loop at the start to the inner loop at the end.
	Loops map[etime.Times]*Loop `desc:"An ordered map of Loops, from the outer loop at the start to the inner loop at the end."`

	// 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 `` /* 219-byte string literal not displayed */

	// If true, stop model at the end of the current StopLevel.
	StopNext bool `desc:"If true, stop model at the end of the current StopLevel."`

	// If true, stop model ASAP.
	StopFlag bool `desc:"If true, stop model ASAP."`

	// Time level to stop at the end of.
	StopLevel etime.Times `desc:"Time level to stop at the end of."`

	// How many iterations at StopLevel before actually stopping.
	StopIterations int `desc:"How many iterations at StopLevel before actually stopping."`

	// Saved Time level for stepping -- what was set for last step or by gui.
	StepLevel etime.Times `desc:"Saved Time level for stepping -- what was set for last step or by gui."`

	// Saved number of steps for stepping -- what was set for last step or by gui.
	StepIterations int `desc:"Saved number of steps for stepping -- what was set for last step or by gui."`
}

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 added in v1.3.3 

func (stack *Stack) AddMainToAll(name string, fun func(mode etime.Modes, time etime.Times))

AddMainToAll adds given function taking mode and time args to Main in all loops

func (*Stack) AddOnEndToAll added in v1.3.3 

func (stack *Stack) AddOnEndToAll(name string, fun func(mode etime.Modes, time etime.Times))

AddOnEndToAll adds given function taking mode and time args to OnEnd in all loops

func (*Stack) AddOnStartToAll added in v1.3.3 

func (stack *Stack) AddOnStartToAll(name string, fun func(mode etime.Modes, time etime.Times))

AddOnStartToAll adds given function taking mode and time args to OnStart in all loops

func (*Stack) AddTime added in v1.2.3 

func (stack *Stack) AddTime(time etime.Times, ctrMax int) *Stack

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 added in v1.4.1 

func (stack *Stack) AddTimeIncr(time etime.Times, ctrMax, ctrIncr int) *Stack

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) ClearStep added in v1.3.17 

func (stack *Stack) ClearStep()

ClearStep clears stepping control state

func (*Stack) CtrsToStats added in v1.3.2 

func (stack *Stack) CtrsToStats(stats *estats.Stats)

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.

func (*Stack) Init 

func (stack *Stack) Init(mode etime.Modes)

Init initializes new data structures for a newly created object

func (*Stack) SetStep 

func (stack *Stack) SetStep(numSteps int, stopscale etime.Times)

SetStep sets stepping to given level and iterations

func (*Stack) TimeAbove added in v1.3.3 

func (stack *Stack) TimeAbove(time etime.Times) etime.Times

TimeAbove returns the time above the given time in the stack returning etime.NoTime if this is the highest level, or given time does not exist in order.

func (*Stack) TimeBelow added in v1.3.3 

func (stack *Stack) TimeBelow(time etime.Times) etime.Times

TimeBelow returns the time below the given time in the stack returning etime.NoTime if this is the lowest level, or given time does not exist in order.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.