emer

type Layer interface {

	// AsEmer returns the layer as an *emer.LayerBase,
	// to access base functionality.
	AsEmer() *LayerBase

	// Label satisfies the core.Labeler interface for getting
	// the name of objects generically. Use to access Name via interface.
	Label() string

	// TypeName is the type or category of layer, defined
	// by the algorithm (and usually set by an enum).
	TypeName() string

	// TypeNumber is the numerical value for the type or category
	// of layer, defined by the algorithm (and usually set by an enum).
	TypeNumber() int

	// UnitVarIndex returns the index of given variable within
	// the Neuron, according to *this layer's* UnitVarNames() list
	// (using a map to lookup index), or -1 and error message if
	// not found.
	UnitVarIndex(varNm string) (int, error)

	// UnitValue1D returns value of given variable index on given unit,
	// using 1-dimensional index, and a data parallel index di,
	// for networks capable of processing multiple input patterns
	// in parallel. Returns NaN on invalid index.
	// This is the core unit var access method used by other methods,
	// so it is the only one that needs to be updated for derived layer types.
	UnitValue1D(varIndex int, idx, di int) float32

	// VarRange returns the min / max values for given variable
	VarRange(varNm string) (min, max float32, err error)

	// NumRecvPaths returns the number of receiving pathways.
	NumRecvPaths() int

	// RecvPath returns a specific receiving pathway.
	RecvPath(idx int) Path

	// NumSendPaths returns the number of sending pathways.
	NumSendPaths() int

	// SendPath returns a specific sending pathway.
	SendPath(idx int) Path

	// RecvPathValues fills in values of given synapse variable name,
	// for pathway from given sending layer and neuron 1D index,
	// for all receiving neurons in this layer,
	// into given float32 slice (only resized if not big enough).
	// pathType is the string representation of the path type;
	// used if non-empty, useful when there are multiple pathways
	// between two layers.
	// Returns error on invalid var name.
	// If the receiving neuron is not connected to the given sending
	// layer or neuron then the value is set to math32.NaN().
	// Returns error on invalid var name or lack of recv path
	// (vals always set to nan on path err).
	RecvPathValues(vals *[]float32, varNm string, sendLay Layer, sendIndex1D int, pathType string) error

	// SendPathValues fills in values of given synapse variable name,
	// for pathway into given receiving layer and neuron 1D index,
	// for all sending neurons in this layer,
	// into given float32 slice (only resized if not big enough).
	// pathType is the string representation of the path type -- used if non-empty,
	// useful when there are multiple pathways between two layers.
	// Returns error on invalid var name.
	// If the sending neuron is not connected to the given receiving layer or neuron
	// then the value is set to math32.NaN().
	// Returns error on invalid var name or lack of recv path (vals always set to nan on path err).
	SendPathValues(vals *[]float32, varNm string, recvLay Layer, recvIndex1D int, pathType string) error

	// ParamsString returns a listing of all parameters in the Layer and
	// pathways within the layer. If nonDefault is true, only report those
	// not at their default values.
	ParamsString(nonDefault bool) string

	// WriteWeightsJSON writes the weights from this layer from the
	// receiver-side perspective in a JSON text format.
	WriteWeightsJSON(w io.Writer, depth int)

	// SetWeights sets the weights for this layer from weights.Layer
	// decoded values
	SetWeights(lw *weights.Layer) error
}

type LayerBase struct {
	// EmerLayer provides access to the emer.Layer interface
	// methods for functions defined in the LayerBase type.
	// Must set this with a pointer to the actual instance
	// when created, using InitLayer function.
	EmerLayer Layer `display:"-"`

	// Name of the layer, which must be unique within the network.
	// Layers are typically accessed directly by name, via a map.
	Name string

	// Class is for applying parameter styles across multiple layers
	// that all get the same parameters.  This can be space separated
	// with multple classes.
	Class string

	// Doc contains documentation about the layer.
	// This is displayed in a tooltip in the network view.
	Doc string

	// Off turns off the layer, removing from all computations.
	// This provides a convenient way to dynamically test for
	// the contributions of the layer, for example.
	Off bool

	// Shape of the layer, either 2D or 4D.  Although spatial topology
	// is not relevant to all algorithms, the 2D shape is important for
	// efficiently visualizing large numbers of units / neurons.
	// 4D layers have 2D Pools of units embedded within a larger 2D
	// organization of such pools.  This is used for max-pooling or
	// pooled inhibition at a finer-grained level, and biologically
	// corresopnds to hypercolumns in the cortex for example.
	// Order is outer-to-inner (row major), so Y then X for 2D;
	// 4D: Y-X unit pools then Y-X neurons within pools.
	Shape tensor.Shape

	// Pos specifies the relative spatial relationship to another
	// layer, which determines positioning.  Every layer except one
	// "anchor" layer should be positioned relative to another,
	// e.g., RightOf, Above, etc.  This provides robust positioning
	// in the face of layer size changes etc.
	// Layers are arranged in X-Y planes, stacked vertically along the Z axis.
	Pos relpos.Pos `table:"-" display:"inline"`

	// Index is a 0..n-1 index of the position of the layer within
	// the list of layers in the network.
	Index int `display:"-" edit:"-"`

	// SampleIndexes are the current set of "sample" unit indexes,
	// which are a smaller subset of units that represent the behavior
	// of the layer, for computationally intensive statistics and displays
	// (e.g., PCA, ActRF, NetView rasters), when the layer is large.
	// If none have been set, then all units are used.
	// See utility function CenterPoolIndexes that returns indexes of
	// units in the central pools of a 4D layer.
	SampleIndexes []int `table:"-"`

	// SampleShape is the shape to use for the subset of sample
	// unit indexes, in terms of an array of dimensions.
	// See Shape for more info.
	// Layers that set SampleIndexes should also set this,
	// otherwise a 1D array of len SampleIndexes will be used.
	// See utility function CenterPoolShape that returns shape of
	// units in the central pools of a 4D layer.
	SampleShape tensor.Shape `table:"-"`

	// optional metadata that is saved in network weights files,
	// e.g., can indicate number of epochs that were trained,
	// or any other information about this network that would be useful to save.
	MetaData map[string]string
}

type Network interface {
	// AsEmer returns the network as an *emer.NetworkBase,
	// to access base functionality.
	AsEmer() *NetworkBase

	// Label satisfies the core.Labeler interface for getting
	// the name of objects generically.
	Label() string

	// NumLayers returns the number of layers in the network.
	NumLayers() int

	// EmerLayer returns layer as emer.Layer interface at given index.
	// Does not do extra bounds checking.
	EmerLayer(idx int) Layer

	// MaxParallelData returns the maximum number of data inputs that can be
	// processed in parallel by the network.
	// The NetView supports display of up to this many data elements.
	MaxParallelData() int

	// NParallelData returns the current number of data inputs currently being
	// processed in parallel by the network.
	// Logging supports recording each of these where appropriate.
	NParallelData() int

	// Defaults sets default parameter values for everything in the Network.
	Defaults()

	// UpdateParams() updates parameter values for all Network parameters,
	// based on any other params that might have changed.
	UpdateParams()

	// KeyLayerParams returns a listing for all layers in the network,
	// of the most important layer-level params (specific to each algorithm).
	KeyLayerParams() string

	// KeyPathParams returns a listing for all Recv pathways in the network,
	// of the most important pathway-level params (specific to each algorithm).
	KeyPathParams() string

	// UnitVarNames returns a list of variable names available on
	// the units in this network.
	// This list determines what is shown in the NetView
	// (and the order of vars list).
	// Not all layers need to support all variables,
	// but must safely return math32.NaN() for unsupported ones.
	// This is typically a global list so do not modify!
	UnitVarNames() []string

	// UnitVarProps returns a map of unit variable properties,
	// with the key being the name of the variable,
	// and the value gives a space-separated list of
	// go-tag-style properties for that variable.
	// The NetView recognizes the following properties:
	//	- range:"##" = +- range around 0 for default display scaling
	//	- min:"##" max:"##" = min, max display range
	//	- auto-scale:"+" or "-" = use automatic scaling instead of fixed range or not.
	//	- zeroctr:"+" or "-" = control whether zero-centering is used
	//	- desc:"txt" tooltip description of the variable
	//	- cat:"cat" variable category, for category tabs
	UnitVarProps() map[string]string

	// VarCategories is a list of unit & synapse variable categories,
	// which organizes the variables into separate tabs in the network view.
	// Using categories results in a more compact display and makes it easier
	// to find variables.
	// Set the 'cat' property in the UnitVarProps, SynVarProps for each variable.
	// If no categories returned, the default is Unit, Wt.
	VarCategories() []VarCategory

	// SynVarNames returns the names of all the variables
	// on the synapses in this network.
	// This list determines what is shown in the NetView
	// (and the order of vars list).
	// Not all pathways need to support all variables,
	// but must safely return math32.NaN() for
	// unsupported ones.
	// This is typically a global list so do not modify!
	SynVarNames() []string

	// SynVarProps returns a map of synapse variable properties,
	// with the key being the name of the variable,
	// and the value gives a space-separated list of
	// go-tag-style properties for that variable.
	// The NetView recognizes the following properties:
	// range:"##" = +- range around 0 for default display scaling
	// min:"##" max:"##" = min, max display range
	// auto-scale:"+" or "-" = use automatic scaling instead of fixed range or not.
	// zeroctr:"+" or "-" = control whether zero-centering is used
	// Note: this is typically a global list so do not modify!
	SynVarProps() map[string]string

	// ReadWeightsJSON reads network weights from the receiver-side perspective
	// in a JSON text format. Reads entire file into a temporary weights.Weights
	// structure that is then passed to Layers etc using SetWeights method.
	// Call the NetworkBase version followed by any post-load updates.
	ReadWeightsJSON(r io.Reader) error

	// WriteWeightsJSON writes the weights from this network
	// from the receiver-side perspective in a JSON text format.
	// Call the NetworkBase version after pre-load updates.
	WriteWeightsJSON(w io.Writer) error
}

type NetworkBase struct {
	// EmerNetwork provides access to the emer.Network interface
	// methods for functions defined in the NetworkBase type.
	// Must set this with a pointer to the actual instance
	// when created, using InitNetwork function.
	EmerNetwork Network `display:"-"`

	// overall name of network, which helps discriminate if there are multiple.
	Name string

	// filename of last weights file loaded or saved.
	WeightsFile string

	// map of name to layers, for EmerLayerByName methods
	LayerNameMap map[string]Layer `display:"-"`

	// minimum display position in network
	MinPos math32.Vector3 `display:"-"`

	// maximum display position in network
	MaxPos math32.Vector3 `display:"-"`

	// optional metadata that is saved in network weights files,
	// e.g., can indicate number of epochs that were trained,
	// or any other information about this network that would be useful to save.
	MetaData map[string]string

	// Rand is the random number generator for the network.
	// all random calls must use this.
	// Set seed here for weight initialization values.
	Rand randx.Rand `display:"-"`

	// Random seed to be set at the start of configuring
	// the network and initializing the weights.
	// Set this to get a different set of weights.
	RandSeed int64 `edit:"-"`
}

type Path interface {

	// AsEmer returns the path as an *emer.PathBase,
	// to access base functionality.
	AsEmer() *PathBase

	// Label satisfies the core.Labeler interface for getting
	// the name of objects generically. Use to access Name via interface.
	Label() string

	// TypeName is the type or category of path, defined
	// by the algorithm (and usually set by an enum).
	TypeName() string

	// TypeNumber is the numerical value for the type or category
	// of path, defined by the algorithm (and usually set by an enum).
	TypeNumber() int

	// SendLayer returns the sending layer for this pathway,
	// as an emer.Layer interface.  The actual Path implmenetation
	// can use a Send field with the actual Layer struct type.
	SendLayer() Layer

	// RecvLayer returns the receiving layer for this pathway,
	// as an emer.Layer interface.  The actual Path implmenetation
	// can use a Recv field with the actual Layer struct type.
	RecvLayer() Layer

	// NumSyns returns the number of synapses for this path.
	// This is the max idx for SynValue1D and the number
	// of vals set by SynValues.
	NumSyns() int

	// SynIndex returns the index of the synapse between given send, recv unit indexes
	// (1D, flat indexes). Returns -1 if synapse not found between these two neurons.
	// This requires searching within connections for receiving unit (a bit slow).
	SynIndex(sidx, ridx int) int

	// SynVarNames returns the names of all the variables on the synapse
	// This is typically a global list so do not modify!
	SynVarNames() []string

	// SynVarNum returns the number of synapse-level variables
	// for this paths.  This is needed for extending indexes in derived types.
	SynVarNum() int

	// SynVarIndex returns the index of given variable within the synapse,
	// according to *this path's* SynVarNames() list (using a map to lookup index),
	// or -1 and error message if not found.
	SynVarIndex(varNm string) (int, error)

	// SynValues sets values of given variable name for each synapse,
	// using the natural ordering of the synapses (sender based for Axon),
	// into given float32 slice (only resized if not big enough).
	// Returns error on invalid var name.
	SynValues(vals *[]float32, varNm string) error

	// SynValue1D returns value of given variable index
	// (from SynVarIndex) on given SynIndex.
	// Returns NaN on invalid index.
	// This is the core synapse var access method used by other methods,
	// so it is the only one that needs to be updated for derived types.
	SynValue1D(varIndex int, synIndex int) float32

	// ParamsString returns a listing of all parameters in the pathway.
	// If nonDefault is true, only report those not at their default values.
	ParamsString(nonDefault bool) string

	// WriteWeightsJSON writes the weights from this pathway
	// from the receiver-side perspective in a JSON text format.
	WriteWeightsJSON(w io.Writer, depth int)

	// SetWeights sets the weights for this pathway from weights.Path
	// decoded values
	SetWeights(pw *weights.Path) error
}

type PathBase struct {
	// EmerPath provides access to the emer.Path interface
	// methods for functions defined in the PathBase type.
	// Must set this with a pointer to the actual instance
	// when created, using InitPath function.
	EmerPath Path

	// Name of the path, which can be automatically set to
	// SendLayer().Name + "To" + RecvLayer().Name via
	// SetStandardName method.
	Name string

	// Class is for applying parameter styles across multiple paths
	// that all get the same parameters. This can be space separated
	// with multple classes.
	Class string

	// Doc contains documentation about the pathway.
	// This is displayed in a tooltip in the network view.
	Doc string

	// can record notes about this pathway here.
	Notes string

	// Pattern specifies the pattern of connectivity
	// for interconnecting the sending and receiving layers.
	Pattern paths.Pattern

	// Off inactivates this pathway, allowing for easy experimentation.
	Off bool
}

type VarCategory struct {
	// Category name.
	Cat string
	// Documentation of the category, used as a tooltip.
	Doc string
}