env

type Counter struct {

	// current counter value
	Cur int

	// previous counter value, prior to last Incr() call (init to -1)
	Prv int `display:"-"`

	// did this change on the last Step() call or not?
	Chg bool `display:"-"`

	// where relevant, this is a fixed maximum counter value, above which the counter will reset back to 0 -- only used if > 0
	Max int

	// the unit of time scale represented by this counter (just FYI)
	Scale etime.Times `display:"-"`
}

type Counters struct {

	// ordered list of the counter timescales, from outer-most (highest) to inner-most (lowest)
	Order []etime.Times

	// map of the counters by timescale
	Counters map[etime.Times]*Counter
}

type CurPrvF32 struct {

	// current value
	Cur float32

	// previous value
	Prv float32
}

type CurPrvInt struct {

	// current value
	Cur int

	// previous value
	Prv int
}

type CurPrvString struct {

	// current value
	Cur string

	// previous value
	Prv string
}

type Element struct {

	// name of this element -- must be unique
	Name string

	// shape of the tensor for this element -- each element should generally have a well-defined consistent shape to enable the model to process it consistently
	Shape []int

	// names of the dimensions within the Shape -- optional but useful for ensuring correct usage
	DimNames []string
}

type Elements []Element

type Env interface {
	labels.Labeler

	// Init initializes the environment for a given run of the model.
	// The environment may not care about the run number, but may implement
	// different parameterizations for different runs (e.g., between-subject
	// manipulations).  In general the Env can expect that the model will likely
	// have established a different random seed per run, prior to calling this
	// method, and that may be sufficient to enable different run-level behavior.
	// All other initialization / updating beyond this outer-most Run level must
	// be managed internally by the Env itself, and the model can query the
	// Counter state information to determine when things have updated at different
	// time scales.  See Step() for important info about state of env after Init
	// but prior to first Step() call.
	Init(run int)

	// Step generates the next step of environment state.
	// This is the main API for how the model interacts with the environment.
	// The env should update all other levels of state internally over
	// repeated calls to the Step method.
	// If there are no further inputs available, it returns false (most envs
	// typically only return true and just continue running as long as needed).
	//
	// The Env thus always reflects the *current* state of things, and this
	// call increments that current state, such that subsequent calls to
	// State() will return this current state.
	//
	// This implies that the state just after Init and prior to first Step
	// call should be an *initialized* state that then allows the first Step
	// call to establish the proper *first* state.  Typically this means that
	// one or more counters will be set to -1 during Init and then get incremented
	// to 0 on the first Step call.
	Step() bool

	// State returns the given element's worth of tensor data from the environment
	// based on the current state of the env, as a function of having called Step().
	// If no output is available on that element, then nil is returned.
	// The returned tensor must be treated as read-only as it likely points to original
	// source data -- please make a copy before modifying (e.g., Clone() methdod).
	State(element string) tensor.Tensor

	// Action sends tensor data about e.g., responses from model back to act
	// on the environment and influence its subsequent evolution.
	// The nature and timing of this input is paradigm dependent.
	Action(element string, input tensor.Tensor)
}

type Envs map[string]Env

type FixedTable struct {
	// name of this environment, usually Train vs. Test.
	Name string

	// this is an indexed view of the table with the set of patterns to output.
	// The indexes are used for the *sequential* view so you can easily
	// sort / split / filter the patterns to be presented using this view.
	// This adds the random permuted Order on top of those if !sequential.
	Table *table.IndexView

	// present items from the table in sequential order (i.e., according to
	// the indexed view on the Table)?  otherwise permuted random order.
	Sequential bool

	// permuted order of items to present if not sequential.
	// updated every time through the list.
	Order []int

	// current ordinal item in Table. if Sequential then = row number in table,
	// otherwise is index in Order list that then gives row number in Table.
	Trial Counter `display:"inline"`

	// if Table has a Name column, this is the contents of that.
	TrialName CurPrvString

	// if Table has a Group column, this is contents of that.
	GroupName CurPrvString

	// name of the Name column -- defaults to 'Name'.
	NameCol string

	// name of the Group column -- defaults to 'Group'.
	GroupCol string
}

type FreqTable struct {

	// name of this environment
	Name string

	// this is an indexed view of the table with the set of patterns to output -- the indexes are used for the *sequential* view so you can easily sort / split / filter the patterns to be presented using this view -- we then add the random permuted Order on top of those if !sequential
	Table *table.IndexView

	// number of samples to use in constructing the list of items to present according to frequency -- number per epoch ~ NSamples * Freq -- see RandSamp option
	NSamples float64

	// if true, use random sampling of items NSamples times according to given Freq probability value -- otherwise just directly add NSamples * Freq items to the list
	RandSamp bool

	// present items from the table in sequential order (i.e., according to the indexed view on the Table)?  otherwise permuted random order.  All repetitions of given item will be sequential if Sequential
	Sequential bool

	// list of items to present, with repetitions -- updated every time through the list
	Order []int

	// current ordinal item in Table -- if Sequential then = row number in table, otherwise is index in Order list that then gives row number in Table
	Trial Counter `display:"inline"`

	// if Table has a Name column, this is the contents of that
	TrialName CurPrvString

	// if Table has a Group column, this is contents of that
	GroupName CurPrvString

	// name of the Name column -- defaults to 'Name'
	NameCol string

	// name of the Group column -- defaults to 'Group'
	GroupCol string

	// name of the Freq column -- defaults to 'Freq'
	FreqCol string
}

type MPIFixedTable struct {

	// name of this environment
	Name string

	// this is an indexed view of the table with the set of patterns to output -- the indexes are used for the *sequential* view so you can easily sort / split / filter the patterns to be presented using this view -- we then add the random permuted Order on top of those if !sequential
	Table *table.IndexView

	// present items from the table in sequential order (i.e., according to the indexed view on the Table)?  otherwise permuted random order
	Sequential bool

	// permuted order of items to present if not sequential -- updated every time through the list
	Order []int

	// current ordinal item in Table -- if Sequential then = row number in table, otherwise is index in Order list that then gives row number in Table
	Trial Counter `display:"inline"`

	// if Table has a Name column, this is the contents of that
	TrialName CurPrvString

	// if Table has a Group column, this is contents of that
	GroupName CurPrvString

	// name of the Name column -- defaults to 'Name'
	NameCol string

	// name of the Group column -- defaults to 'Group'
	GroupCol string

	// for MPI, trial we start each epoch on, as index into Order
	TrialSt int

	// for MPI, trial number we end each epoch before (i.e., when ctr gets to Ed, restarts)
	TrialEd int
}