add README.md for major sub-packages -- might be more easily found by…

… google vs. GoDoc, and has links into doc etc.

README.md

@@ -94,24 +94,18 @@ Here are some of the additional supporting packages:
 
 # TODO
 
-Last updated: 10/28/2019
+Last updated: 12/09/2019
 
 This list is not strictly in order, but roughly so..
 
 - [ ] fix bugs, try to update glfw including keyboard input fixes
 
 - [ ] write converter from Go to Python
 
-- [x] do basic test of deep leabra
-
 - [ ] MPI -- see [MPI Wiki page](https://github.com/emer/emergent/wiki/DMem)
 
 - [ ] add python example code for interchange between pandas, xarray, tensorflow tensor stuff and etable.Table -- right now the best is to just save as .csv and load from there (esp for pandas which doesn't have tensors) -- should be able to use arrow stuff so it would be good to look into that.
 
-- [ ] td/rl -- include ability to simulate drugs!
-
-- [x] pbwm -- in process now
-
 - [ ] pvlv
 
 - [x] virtual environment -- [eve](https://github.com/emer/eve) is under way -- no actual physics yet but core infrastructure in place and usable for basic boxy objects under external control.

actrf/README.md

@@ -0,0 +1,12 @@
+[GoDoc](https://godoc.org/github.com/emer/emergent/actrf)
+
+Package actrf provides activation-based receptive field computation, otherwise known as *reverse correlation* or *spike-triggered averaging*.  It simply computes the activation weighted average of other *source* patterns of activation -- i.e., sum(act * src) / sum(src) which then shows you the patterns of source activity for which a given unit was active.
+
+The RF's are computed and stored in 4D tensors, where the outer 2D are the 2D projection of the activation tensor (e.g., the activations of units in a layer), and the inner 2D are the 2D projection of the source tensor.
+
+This results in a nice standard RF plot that can be visualized in a tensor grid view.
+
+There is a standard ActRF which is cumulative over a user-defined interval and a RunningAvg version which is computed online and continuously updated but is more susceptible to sampling bias (i.e., more sampled areas are more active in general), and a recency bias.
+
+See [objrec CCN sim](https://github.com/CompCogNeuro/sims/blob/master/ch6/objrec) for example usage.
+

env/README.md

@@ -0,0 +1,20 @@
+[GoDoc](https://godoc.org/github.com/emer/emergent/env)
+
+See [Wiki Env](https://github.com/emer/emergent/wiki/Env) page for detailed docs.
+
+Package env defines an interface for environments, which determine the nature and sequence of States that can be used as inputs to a model and it can also accept Action responses from the model that affect how the enviroment evolves in the future.
+
+By adhering to this interface, it is then easier to mix-and-match environments with models.
+
+The overall division of labor is that the model keeps track of the outer-most Run time-scale depending on its own parameters and learning trajectory and the environment is responsible for generating patterns for each run.
+
+Multiple different environments will typically be used in a model, e.g., one for training and other(s) for testing.  Even if these envs all share a common database of patterns, a different Env should be used for each case where different counters and sequences of events etc are presented, which keeps them from interfering with each other.  Also, the etable.IdxView can be used to allow multiple different Env's to all present different indexed views into a shared common etable.Table (e.g., train / test splits). The basic `FixedTable` env implementation uses this.
+
+Thus, the Env encapsulates all of the counter management logic for each aspect of model training and testing, so that the model itself just needs to manange which Env to use, when, and manage the connection of the Env States as inputs to the model, and vice-versa for Actions on the Env coming from the model.
+
+Each `Element` of the overall `State` allows annotation about the different elements of state that are available in general, and the `Step` should update all relevant state elements as appropriate, so these can be queried by the user. Particular paradigms of environments must establish naming conventions for these state elements which then allow the model to use the information appropriately -- the Env interface only provides the most basic framework for establishing these paradigms, and ultimately a given model will only work within a particular paradigm of environments following specific conventions.
+
+See e.g., env.FixedTable for particular implementation of a fixed Table of patterns, for one example of a widely-used paradigm.
+
+Typically each specific implementation of this Env interface will have multiple parameters etc that can be modified to control env behavior -- all of this is paradigm-specific and outside the scope of this basic interface.
+

env/doc.go

@@ -30,14 +30,15 @@ needs to manange which Env to use, when, and manage the connection of
 the Env States as inputs to the model, and vice-versa for Actions on the
 Env coming from the model.
 
-The channel allows annotation about multiple possible channels of I/O
-and any given I/O event can specify which channels are provided.
-Particular paradigms of environments must establish naming conventions
-for these channels which then allow the model to use the information
-appropriately -- the Env interface only provides the most basic framework
-for establishing these paradigms, and ultimately a given model will only
-work within a particular paradigm of environments following specific
-conventions.
+Each Element of the overall State allows annotation about the different
+elements of state that are available in general, and the `Step` should
+update all relevant state elements as appropriate, so these can be queried
+by the user. Particular paradigms of environments must establish naming
+conventions for these state elements which then allow the model to use
+the information appropriately -- the Env interface only provides the most
+basic framework for establishing these paradigms, and ultimately a given
+model will only work within a particular paradigm of environments following
+specific conventions.
 
 See e.g., env.FixedTable for particular implementation of a fixed Table
 of patterns, for one example of a widely-used paradigm.

esg/README.md

@@ -0,0 +1,56 @@
+[GoDoc](https://godoc.org/github.com/emer/emergent/esg)
+
+Package esg is the emergent stochastic generator, where tokens are generated stochastically according to rules defining the contingencies and probabilities.  It can be used for generating sentences (sg as well).
+
+There are two types of rules:
+* unconditional random items
+* conditional items.
+
+Unconditional items are chosen at random, optionally with specified probabilities:
+
+```
+RuleName {
+   %50 Rule2 Rule4
+   %30 'token1' 'token2'
+	...
+}
+```
+
+where Items on separate lines within each rule are orthogonal options, chosen at uniform random unless otherwise specified with a leading %pct. %pct can add up to < 100 in which case *nothing* is an alternative output.
+
+Multiple elements in an item (on the same line) are resolved and emitted in order. Terminal literals are 'quoted' -- otherwise refers to another rule: error message will flag missing rules.
+
+Conditional items are specified by the ? after the rule name:
+
+```
+RuleName ? {
+   Rule2 || Rule3 {
+		Item1
+		Item2
+		...
+	}
+	Rule5 && Rule6 {
+		...
+	}
+	...
+}
+```
+
+The expression before the opening bracket for each item is a standard logical expression using || (or), && (and), and ! (not), along with parens, where the elements are rules that could have been generated earlier in the pass -- they evaluate to true if so, and false if not.
+
+If the whole expression evaluates to true, then it is among items chosen at random (typically only one for conditionals but could be any number).
+
+If just one item per rule it can be put all on one line.
+
+Conventional modifiers, used for defining sub-rules:
+* A = Agent
+    + Ao = Co-Agent
+* V = Verb
+* P = Patient,
+    + Pi = Instrument
+    + Pc = Co-Patient
+* L = Location
+* R = adverb
+
+See [testdata/testrules.txt](https://github.com/emer/emergent/blob/master/esg/testdata/testrules.txt) and [sg CCN sim](https://github.com/CompCogNeuro/sims/blob/master/ch9/sg) for example usage.
+

params/README.md

@@ -0,0 +1,36 @@
+[GoDoc](https://godoc.org/github.com/emer/emergent/params)
+
+See [Wiki Params](https://github.com/emer/emergent/wiki/Params) page for detailed docs.
+
+Package `params` provides general-purpose parameter management functionality for organizing multiple sets of parameters efficiently, and basic IO for saving / loading from JSON files and generating Go code to embed into applications, and a basic GUI for viewing and editing.
+
+The main overall unit that is generally operated upon at run-time is the `params.Set`, which is a collection of `params.Sheet`'s (akin to CSS style sheets) that constitute a coherent set of parameters.
+
+A good strategy is to have a "Base" Set that has all the best parameters so far, and then other sets can modify specific params relative to that one. Order of application is critical, as subsequent params applications overwrite earlier ones, and the typical order is:
+
+* `Defaults()` method called that establishes the hard-coded default parameters.
+* Then apply "Base" `params.Set` for any changes relative to those.
+* Then optionally apply one or more additional `params.Set`'s with current experimental parameters.
+
+Critically, all of this is entirely up to the particular model program(s) to determine and control -- this package just provides the basic data structures for holding all of the parameters, and the IO / and Apply infrastructure.
+
+Within a params.Set, multiple different params.Sheet's can be organized, with each CSS-style sheet achieving a relatively complete parameter styling of a given element of the overal model, e.g., "Network", "Sim", "Env". Or Network could be further broken down into "Learn" vs. "Act" etc, or according to different brain areas ("Hippo", "PFC", "BG", etc). Again, this is entirely at the discretion of the modeler and must be performed under explict program control, especially because order is so critical.
+
+Each `params.Sheet` consists of a collection of params.Sel elements which actually finally contain the parameters.  The `Sel` field specifies a CSS-style selector determining over what scope the parameters should be applied:
+
+* `Type` (no prefix) = name of a type -- anything having this type name will get these params.
+
+* `.Class` = anything with a given class label (each object can have multiple Class labels and thus receive multiple parameter settings, but again, order matters!)
+
+* `#Name` = a specific named object.
+
+The order of application within a given Sheet is also critical -- typically put the most general Type params first, then .Class, then the most specific #Name cases, to achieve within a given Sheet the same logic of establishing Base params for all types and then more specific overrides for special cases (e.g., an overall learning rate that appplies across all projections, but maybe a faster or slower one for a .Class or specific #Name'd projection).
+
+There is a params.Styler interface with methods that any Go type can implement to provide these different labels.  The emer.Network, .Layer, and .Prjn interfaces each implement this interface.
+
+Otherwise, the Apply method will just directly apply params to a given struct type if it does not implement the Styler interface.
+
+Parameter values are limited to float64 values *only*.  These can be specified using "enum" style const integer values, and can be applied to any numeric type (they will be automatically converted), but internally this is the only parameter value type, which greatly simplifies the overall interface, and handles the vast majority of use-cases (especially because named options are just integers and can be set as such).
+
+Finally, there are methods to show where params.Set's set the same parameter differently, and to compare with the default settings on a given object type using go struct field tags of the form def:"val1[,val2...]".
+

patgen/README.md

@@ -0,0 +1,6 @@
+[GoDoc](https://godoc.org/github.com/emer/emergent/patgen)
+
+Package `patgen` contains functions that generate patterns, typically based on various constrained-forms of random patterns, e.g., permuted binary random patterns.
+
+
+

popcode/README.md

@@ -0,0 +1,14 @@
+[GoDoc](https://godoc.org/github.com/emer/emergent/popcode)
+
+Package `popcode` provides population code encoding and decoding support functionality, in 1D and 2D.
+
+# popcode.OneD
+
+`popcode.OneD` `Encode` method turns a single scalar value into a 1D population code according to a set of parameters about the nature of the population code, range of values to encode, etc.
+
+`Decode` takes a distributed pattern of activity and decodes a scalar value from it, using activation-weighted average based on tuning value of individual units.
+
+# popcode.TwoD
+
+`popcode.TwoD` likewise has `Encode` and `Decode` methods for 2D gaussian-bumps that simultaneously encode a 2D value such as a 2D position.
+

popcode/doc.go

@@ -0,0 +1,21 @@
+// Copyright (c) 2019, The Emergent Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+/*
+Package `popcode` provides population code encoding and decoding
+support functionality, in 1D and 2D.
+
+`popcode.OneD` `Encode` method turns a single scalar value into a 1D
+population code according to a set of parameters about the nature
+of the population code, range of values to encode, etc.
+
+`Decode` takes a distributed pattern of activity and decodes a scalar
+value from it, using activation-weighted average based on tuning
+value of individual units.
+
+`popcode.TwoD` likewise has `Encode` and `Decode` methods for 2D
+gaussian-bumps that simultaneously encode a 2D value such as a 2D
+position.
+*/
+package popcode

prjn/README.md

@@ -0,0 +1,18 @@
+[GoDoc](https://godoc.org/github.com/emer/emergent/prjn)
+
+See [Wiki Params](https://github.com/emer/emergent/wiki/Prjns) page for detailed docs.
+
+Package prjn is a separate package for defining patterns of connectivity between layers (i.e., the ProjectionSpecs from C++ emergent).  This is done using a fully independent structure that *only* knows about the shapes of the two layers, and it returns a fully general bitmap representation of the pattern of connectivity between them.
+
+The algorithm-specific leabra.Prjn code then uses these patterns to do all the nitty-gritty of connecting up neurons.
+
+This makes the projection code *much* simpler compared to the ProjectionSpec in C++ emergent, which was involved in both creating the pattern and also all the complexity of setting up the actual connections themselves.  This should be the *last* time any of those projection patterns need to be written (having re-written this code too many times in the C++ version as the details of memory allocations changed).
+
+A Pattern maintains nothing about a specific projection -- it only has the parameters that are applied in creating a new pattern of connectivity, so it can be shared among any number of projections that need the same connectivity parameters.
+
+All Patttern types have a New<Name> where <Name> is the type name, that creates a new instance of given pattern initialized with default values.
+
+Individual Pattern types may have a Defaults() method to initialize default values, but it is not mandatory.
+
+Also, the Edge method is handy for dealing with edges and wrap-around etc.
+