env

type Ctr struct {

	// current counter value
	Cur int

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

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

	// 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 TimeScales `view:"-"`
}

type Ctrs struct {

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

	// map of the counters by timescale
	Ctrs map[TimeScales]*Ctr
}

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 {
	// Name returns a name for this environment, which can be useful
	// for selecting from a list of options etc.
	Name() string

	// Desc returns an (optional) brief description of this particular
	// environment
	Desc() string

	// Validate checks if the various specific parameters for this
	// Env have been properly set -- if not, error message(s) will
	// be returned.  If everything is OK, nil is returned, in which
	// case calls to Counters(), States(), and Actions() should all
	// return valid data.  It is essential that a model *always* check
	// this as a first step, because the Env will not generally check
	// for errors on any subsequent calls (for greater efficiency
	// and simplicity) and this call can also establish certain general
	// initialization settings that are not run-specific and thus make
	// sense to do once at this point, not every time during Init().
	Validate() error

	// 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(), Counter() etc 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

	// Counter(scale TimeScales) returns current counter state for given time scale,
	// the immediate previous counter state, and whether that time scale changed
	// during the last Step() function call (this may be true even if cur == prv, if
	// the Max = 1).  Use the Ctr struct for each counter, which manages all of this.
	// See external Counter* methods for Python-safe single-return-value versions.
	Counter(scale TimeScales) (cur, prv int, changed 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) etensor.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 etensor.Tensor)
}

type EnvDesc interface {
	// Counters returns []TimeScales list of counters supported by this env.
	// These should be consistent within a paradigm and most models
	// will just expect particular sets of counters, but this can be
	// useful for sanity checking that a suitable env has been selected.
	// See SchemaFromScales function that takes this list of time
	// scales and returns an etable.Schema for Table columns to record
	// these counters in a log.
	Counters() []TimeScales

	// States returns a list of Elements of tensor outputs that this env
	// generates, specifying the unique Name and Shape of the data.
	// This information can be derived directly from an etable.Schema
	// and used for configuring model input / output pathways to fit
	// with those provided by the environment.  Depending on the
	// env paradigm, all elements may not be always available at every
	// point in time e.g., an env might alternate between Action and Reward
	// elements.  This may return nil if Env has not been properly
	// configured.
	States() Elements

	// Actions returns a list of elements of tensor inputs that this env
	// accepts, specifying the unique Name and Shape of the data.
	// Specific paradigms of envs can establish the timing and function
	// of these inputs, and how they then affect subsequent outputs
	// e.g., if the model is required to make a particular choice
	// response and then it can receive a reward or not contingent
	// on that choice.
	Actions() Elements
}

type Envs map[string]Env

type FixedTable struct {

	// name of this environment
	Nm string

	// description of this environment
	Dsc 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 *etable.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 run of model as provided during Init
	Run Ctr `view:"inline"`

	// number of times through entire set of patterns
	Epoch Ctr `view:"inline"`

	// 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 Ctr `view:"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
	Nm string

	// description of this environment
	Dsc 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 *etable.IndexView

	// number of samples to use in constructing the list of items to present according to frequency -- number per epoch ~ NSamples * Freq -- see RndSamp 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
	RndSamp 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 run of model as provided during Init
	Run Ctr `view:"inline"`

	// number of times through entire set of patterns
	Epoch Ctr `view:"inline"`

	// 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 Ctr `view:"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
	Nm string

	// description of this environment
	Dsc 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 *etable.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 run of model as provided during Init
	Run Ctr `view:"inline"`

	// number of times through entire set of patterns
	Epoch Ctr `view:"inline"`

	// 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 Ctr `view:"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
}

type TimeScales etime.Times