ca.nengo.model.nef.impl
Class NEFEnsembleImpl

java.lang.Object
  extended by ca.nengo.model.impl.AbstractEnsemble
      extended by ca.nengo.model.impl.EnsembleImpl
          extended by ca.nengo.model.impl.PlasticEnsembleImpl
              extended by ca.nengo.model.nef.impl.DecodableEnsembleImpl
                  extended by ca.nengo.model.nef.impl.NEFEnsembleImpl
All Implemented Interfaces:
Ensemble, ExpandableNode, DecodableEnsemble, NEFEnsemble, Node, PlasticEnsemble, Probeable, Resettable, SimulationMode.ModeConfigurable, VisiblyMutable, java.io.Serializable, java.lang.Cloneable

public class NEFEnsembleImpl
extends DecodableEnsembleImpl
implements NEFEnsemble

Default implementation of NEFEnsemble. TODO: links to NEF documentation TODO: test

Author:
Bryan Tripp
See Also:
Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from interface ca.nengo.util.VisiblyMutable
VisiblyMutable.Event, VisiblyMutable.Listener, VisiblyMutable.NameChangeEvent, VisiblyMutable.NodeRemovedEvent
 
Field Summary
static java.lang.String BIAS_SUFFIX
           
static java.lang.String INTERNEURON_SUFFIX
           
 
Fields inherited from class ca.nengo.model.nef.impl.DecodableEnsembleImpl
myDecodedOrigins, OrderedOrigins
 
Fields inherited from class ca.nengo.model.impl.EnsembleImpl
myExpandableNodes, myExpandedTerminations
 
Fields inherited from class ca.nengo.model.impl.AbstractEnsemble
myNodes, myTerminations
 
Fields inherited from interface ca.nengo.model.nef.NEFEnsemble
X
 
Constructor Summary
NEFEnsembleImpl(java.lang.String name, NEFNode[] nodes, float[][] encoders, ApproximatorFactory factory, float[][] evalPoints, float[] radii)
           
 
Method Summary
 BiasOrigin addBiasOrigin(Origin existing, int numInterneurons, java.lang.String name, boolean excitatory)
          Adds a BiasOrigin, which operates in parallel with an existing Origin, such that the effective weights of the two origins together are all of the same sign (as is normally the case with synaptic weights in the brain).
 BiasTermination[] addBiasTerminations(DecodedTermination baseTermination, float interneuronTauPSC, float[][] biasDecoders, float[][] functionDecoders)
          Adds BiasTerminations, which are meant to receive projections from BiasOrigins.
 Origin addDecodedOrigin(java.lang.String name, Function[] functions, java.lang.String nodeOrigin)
          Adds an Origin that corresponds to a decoding of the activities of Nodes in this Ensemble.
 Termination addDecodedTermination(java.lang.String name, float[][] matrix, float[] tfNumerator, float[] tfDenominator, float passthrough, boolean isModulatory)
          As above but with arbitrary single-input-single-output PSC dynamics.
 Termination addDecodedTermination(java.lang.String name, float[][] matrix, float tauPSC, boolean isModulatory)
          Adds a new Termination into this Ensemble, at which information is to be received in the form of decoded state variables rather than spikes, etc.
 NEFEnsemble clone()
           
 void fixMode()
          When this method is called, the mode of this node is fixed and cannot be changed by subsequent setMode(...) calls.
protected  float[] getConstantOutput(int nodeIndex, float[][] evalPoints, java.lang.String origin)
           
protected  float[][] getConstantOutputs(float[][] evalPoints, java.lang.String origin)
           
 DecodedOrigin[] getDecodedOrigins()
          Used to get decoded origins to give to GPU.
 DecodedTermination[] getDecodedTerminations()
          Used to get decoded terminations to give to GPU.
 int getDimension()
           
 DynamicalSystem getDirectModeDynamics()
           
 Integrator getDirectModeIntegrator()
           
 float[][] getEncoders()
           
 NEFEnsembleFactory getEnsembleFactory()
           
 float[][] getEvalPoints()
           
 TimeSeries getHistory(java.lang.String stateName)
          Note that the units of TimeSeries' for a given state do not change over time (ie at different time steps).
 boolean getModeFixed()
           
 int getNeurons()
           
 int getNodeCount()
          For changing the number of neurons in the ensemble
 float getRadialInput(float[] state, int node)
           
 float[] getRadii()
           
 boolean getReuseApproximators()
           
 float[] getStaticNeuronData()
          Used to get static neuron data (data that doesn't change each step) and give it to the GPU.
 Termination getTermination(java.lang.String name)
           
 Termination[] getTerminations()
           
 boolean isGPUNode()
           
 void killNeurons(float killrate, boolean saveRelays)
          Stops a given percentage of neurons in this population from firing.
 java.util.Properties listStates()
           
 void releaseMemory()
          Releases any memory that can be freed.
 void removeDecodedTermination(java.lang.String name)
           
 void reset(boolean randomize)
          Resets each Node in this Ensemble.
 void run(float startTime, float endTime)
          Runs each neuron in the Ensemble.
 void setDirectModeDynamics(DynamicalSystem dynamics)
           
 void setDirectModeIntegrator(Integrator integrator)
           
 void setEncoders(float[][] encoders)
           
 void setEnsembleFactory(NEFEnsembleFactory factory)
          Gives the ensemble a reference to the factory used to created it (useful for adding more neurons later)
 void setEvalPoints(float[][] evalPoints)
          Note: by-products of decoding are sometimes cached, so if these are changed it may be necessary to call setReuseApproximators(false) for the change to take effect.
 void setGPU(boolean useGPU)
           
 void setMode(SimulationMode mode)
          This Ensemble does not support SimulationMode.DIRECT.
 void setNeurons(int count)
          TODO: figure out why I have to add these so that it will show up in the Configure menu (nodeCount doens't appear for some reason)
 void setNodeCount(int n)
           
 void setRadii(float[] radii)
           
 void setReuseApproximators(boolean reuse)
           
 
Methods inherited from class ca.nengo.model.nef.impl.DecodableEnsembleImpl
addDecodedOrigin, addDecodedOrigin, addDecodedOrigin, addDecodedOrigin, doneOrigins, getApproximatorFactory, getOrigin, getOrigins, removeDecodedOrigin, setTime
 
Methods inherited from class ca.nengo.model.impl.PlasticEnsembleImpl
addTermination, getPlasticityInterval, getPlasticityRule, setLearning, setPlasticityInterval, setPlasticityRule
 
Methods inherited from class ca.nengo.model.impl.EnsembleImpl
removeTermination
 
Methods inherited from class ca.nengo.model.impl.AbstractEnsemble
addChangeListener, collectSpikes, findCommon1DOrigins, fireVisibleChangeEvent, getCollectSpikesRatio, getDocumentation, getMode, getName, getNodes, getSpikePattern, isCollectingSpikes, redefineNodes, removeChangeListener, setCollectSpikesRatio, setDocumentation, setName, setSpikePattern
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface ca.nengo.model.nef.DecodableEnsemble
addDecodedOrigin, addDecodedOrigin, doneOrigins, removeDecodedOrigin
 
Methods inherited from interface ca.nengo.model.PlasticEnsemble
getPlasticityInterval, getPlasticityRule, setPlasticityInterval, setPlasticityRule
 
Methods inherited from interface ca.nengo.model.Ensemble
collectSpikes, getNodes, getSpikePattern, isCollectingSpikes, redefineNodes
 
Methods inherited from interface ca.nengo.model.Node
getDocumentation, getName, getOrigin, getOrigins, setDocumentation, setName
 
Methods inherited from interface ca.nengo.model.SimulationMode.ModeConfigurable
getMode
 
Methods inherited from interface ca.nengo.util.VisiblyMutable
addChangeListener, removeChangeListener
 

Field Detail

BIAS_SUFFIX

public static java.lang.String BIAS_SUFFIX

INTERNEURON_SUFFIX

public static java.lang.String INTERNEURON_SUFFIX
Constructor Detail

NEFEnsembleImpl

public NEFEnsembleImpl(java.lang.String name,
                       NEFNode[] nodes,
                       float[][] encoders,
                       ApproximatorFactory factory,
                       float[][] evalPoints,
                       float[] radii)
                throws StructuralException
Parameters:
name - Unique name of Ensemble
nodes - Nodes that make up the Ensemble
encoders - List of encoding vectors (one for each node). All must have same length
factory - Source of LinearApproximators to use in decoding output
evalPoints - Vector inputs at which output is found to produce DecodedOrigins
Throws:
StructuralException - if there are a different number of Nodes than encoding vectors or if not all encoders have the same length
Method Detail

getRadii

public float[] getRadii()
Specified by:
getRadii in interface NEFEnsemble
Returns:
Radius of encoded region in each dimension
See Also:
NEFEnsemble.getRadii()

setRadii

public void setRadii(float[] radii)
              throws StructuralException
Parameters:
radii - A list of radii of encoded area along each dimension; uniform radius along each dimension can be specified with a list of length 1
Throws:
StructuralException

setEvalPoints

public void setEvalPoints(float[][] evalPoints)
Note: by-products of decoding are sometimes cached, so if these are changed it may be necessary to call setReuseApproximators(false) for the change to take effect.

Parameters:
evalPoints - Points in the encoded space at which node outputs are evaluated for establishing new DecodedOrigins.

getEvalPoints

public float[][] getEvalPoints()

setDirectModeDynamics

public void setDirectModeDynamics(DynamicalSystem dynamics)
Parameters:
dynamics - DynamicalSystem that models internal neuron dynamics at the ensemble level, when the ensemble runs in direct mode. The input and output dimensions must equal the dimension of the ensemble.

getDirectModeDynamics

public DynamicalSystem getDirectModeDynamics()

getDirectModeIntegrator

public Integrator getDirectModeIntegrator()

setDirectModeIntegrator

public void setDirectModeIntegrator(Integrator integrator)

getConstantOutputs

protected float[][] getConstantOutputs(float[][] evalPoints,
                                       java.lang.String origin)
                                throws StructuralException
Parameters:
evalPoints - Vector points at which to find output (each one must have same dimension as encoder)
origin - Name of Origin from which to collect output for each Node
Returns:
Output of each Node at each evaluation point (1st dimension corresponds to Node)
Throws:
StructuralException - If CONSTANT_RATE is not supported by any Node

getConstantOutput

protected float[] getConstantOutput(int nodeIndex,
                                    float[][] evalPoints,
                                    java.lang.String origin)
                             throws StructuralException,
                                    SimulationException
Parameters:
nodeIndex - Index of Node for which to find output at various inputs
evalPoints - Vector points at which to find output (each one must have same dimension as encoder)
origin - Name of Origin from which to collect output
Returns:
Output of indexed Node at each evaluation point
Throws:
StructuralException - If CONSTANT_RATE is not supported by the given Node
SimulationException - If the Node does not have an Origin with the given name

getDimension

public int getDimension()
Specified by:
getDimension in interface ExpandableNode
Specified by:
getDimension in interface NEFEnsemble
Overrides:
getDimension in class EnsembleImpl
Returns:
Output dimension of Terminations onto this Node
See Also:
NEFEnsemble.getDimension()

getEncoders

public float[][] getEncoders()
Specified by:
getEncoders in interface NEFEnsemble
Returns:
List of encoders for each Node (each item is the encoding vector for a Node).
See Also:
NEFEnsemble.getEncoders()

setEncoders

public void setEncoders(float[][] encoders)
Parameters:
encoders - New encoding vectors (row per Node)

getReuseApproximators

public boolean getReuseApproximators()
Returns:
True if LinearApproximators for a Node Origin are re-used for decoding multiple decoded Origins.

setReuseApproximators

public void setReuseApproximators(boolean reuse)
Parameters:
reuse - True if LinearApproximators for a Node Origin are re-used for decoding multiple decoded Origins.

addDecodedOrigin

public Origin addDecodedOrigin(java.lang.String name,
                               Function[] functions,
                               java.lang.String nodeOrigin)
                        throws StructuralException
Description copied from interface: NEFEnsemble
Adds an Origin that corresponds to a decoding of the activities of Nodes in this Ensemble.

Specified by:
addDecodedOrigin in interface NEFEnsemble
Parameters:
name - Name of decoding
functions - Functions that define the decoding (one function for each dimension of output). All functions must have an input dimension equal to the dimension of this NEFEnsemble.
nodeOrigin - Name of the Node-level Origins from which this Ensemble-level Origin is derived (often Neuron.AXON)
Throws:
StructuralException - if functions do not all have the same input dimension as the dimension of this ensemble
See Also:
NEFEnsemble.addDecodedOrigin(java.lang.String, Function[], String)

addBiasOrigin

public BiasOrigin addBiasOrigin(Origin existing,
                                int numInterneurons,
                                java.lang.String name,
                                boolean excitatory)
                         throws StructuralException
Description copied from interface: NEFEnsemble
Adds a BiasOrigin, which operates in parallel with an existing Origin, such that the effective weights of the two origins together are all of the same sign (as is normally the case with synaptic weights in the brain). TODO: with a little work this could be pushed up to DecodableEnsemble (have to generalize constant-rate responses)

Specified by:
addBiasOrigin in interface NEFEnsemble
Parameters:
existing - An existing Origin on this NEFEnsemble
numInterneurons - Number of interneurons
name - Name of BiasOrigin (name of associated interneuron ensemble is also derived from this)
excitatory - If true, effective weights will be positive; if false they will be negative (inhibitory)
Returns:
Resulting BiasOrigin
Throws:
StructuralException - if given Origin is not a DecodedOrigin or if there is a construction problem
See Also:
NEFEnsemble.addBiasOrigin(ca.nengo.model.Origin, int, java.lang.String, boolean)

addDecodedTermination

public Termination addDecodedTermination(java.lang.String name,
                                         float[][] matrix,
                                         float tauPSC,
                                         boolean isModulatory)
                                  throws StructuralException
Description copied from interface: NEFEnsemble
Adds a new Termination into this Ensemble, at which information is to be received in the form of decoded state variables rather than spikes, etc.

Specified by:
addDecodedTermination in interface NEFEnsemble
Parameters:
name - Unique name for this Termination (in the scope of this Ensemble)
matrix - Transformation matrix which defines a linear map on incoming information, onto the space of vectors that can be represented by this NEFEnsemble. The first dimension is taken as matrix rows, and must have the same length as the Origin that will be connected to this Termination. The second dimension is taken as matrix columns, and must have the same length as the encoders of this NEFEnsemble. TODO: this is transposed?
tauPSC - Time constant of post-synaptic current decay (all Terminations have this property but it may have slightly different interpretations depending other properties of the Termination).
isModulatory - If true, inputs to this Termination do not drive Nodes in the Ensemble directly but may have modulatory influences (eg related to plasticity). If false, the transformation matrix output dimension must match the dimension of this Ensemble.
Returns:
The resulting Termination
Throws:
StructuralException - if given transformation matrix is not a matrix
See Also:
NEFEnsemble.addDecodedTermination(java.lang.String, float[][], float, boolean)

addDecodedTermination

public Termination addDecodedTermination(java.lang.String name,
                                         float[][] matrix,
                                         float[] tfNumerator,
                                         float[] tfDenominator,
                                         float passthrough,
                                         boolean isModulatory)
                                  throws StructuralException
Description copied from interface: NEFEnsemble
As above but with arbitrary single-input-single-output PSC dynamics.

Specified by:
addDecodedTermination in interface NEFEnsemble
Parameters:
name - Unique name for this Termination (in the scope of this Ensemble)
matrix - Transformation matrix which defines a linear map on incoming information
tfNumerator - Coefficients of transfer function numerator (see CanonicalModel.getRealization(...) for details)
tfDenominator - Coefficients of transfer function denominator
isModulatory - If true, inputs to this Termination do not drive Nodes in the Ensemble directly but may have modulatory influences (eg related to plasticity). If false, the transformation matrix output dimension must match the dimension of this Ensemble.
Returns:
The resulting Termination
Throws:
StructuralException - if given transformation matrix is not a matrix or there is a problem with the transfer function
See Also:
NEFEnsemble.addDecodedTermination(java.lang.String, float[][], float[], float[], float, boolean)

addBiasTerminations

public BiasTermination[] addBiasTerminations(DecodedTermination baseTermination,
                                             float interneuronTauPSC,
                                             float[][] biasDecoders,
                                             float[][] functionDecoders)
                                      throws StructuralException
Description copied from interface: NEFEnsemble
Adds BiasTerminations, which are meant to receive projections from BiasOrigins. A pair of BiasTerminations is returned, one to receive a projection directly from a BiasOrigin, and the other to receive a projection indirectly through an ensemble of interneurons that is associated with the BiasOrigin.

Specified by:
addBiasTerminations in interface NEFEnsemble
Parameters:
baseTermination - The Termination that is to be biased (so that projections to it consist of weights of a single sign)
interneuronTauPSC - Time constant of post-synaptic current decay of inhibitory termination from interneurons onto this ensemble
biasDecoders - The decoding weights of the associated BiasOrigin
functionDecoders - The decoding vectors of the BiasOrigin's associated base origin
Returns:
A pair of BiasTerminations: the first is to receive direct input from a BiasOrigin and the second is to receive input from the interneuron ensemble associated with the BiasOrigin (see BiasOrigin.getInterneurons())
Throws:
StructuralException
See Also:
NEFEnsemble.addBiasTerminations(ca.nengo.model.nef.impl.DecodedTermination, float, float[][], float[][])

removeDecodedTermination

public void removeDecodedTermination(java.lang.String name)
Specified by:
removeDecodedTermination in interface NEFEnsemble
Parameters:
name - Name of Termination to remove.
See Also:
NEFEnsemble.removeDecodedTermination(java.lang.String)

getTerminations

public Termination[] getTerminations()
Specified by:
getTerminations in interface Node
Overrides:
getTerminations in class EnsembleImpl
Returns:
Sets of input channels (these have the same dimension as corresponding Origins to which they are connected).
See Also:
Node.getTerminations()

getDecodedTerminations

public DecodedTermination[] getDecodedTerminations()
Used to get decoded terminations to give to GPU.


getDecodedOrigins

public DecodedOrigin[] getDecodedOrigins()
Used to get decoded origins to give to GPU.


run

public void run(float startTime,
                float endTime)
         throws SimulationException
Description copied from class: AbstractEnsemble
Runs each neuron in the Ensemble.

Specified by:
run in interface Node
Overrides:
run in class DecodableEnsembleImpl
Parameters:
startTime - simulation time at which running starts (s)
endTime - simulation time at which running ends (s)
Throws:
SimulationException - if a problem is encountered while trying to run
See Also:
Node.run(float, float)

getRadialInput

public float getRadialInput(float[] state,
                            int node)
Parameters:
state - State vector
node - Node number
Returns:
Radial input to the given node

getTermination

public Termination getTermination(java.lang.String name)
                           throws StructuralException
Specified by:
getTermination in interface Node
Overrides:
getTermination in class EnsembleImpl
Parameters:
name - Name of a Termination onto this Node
Returns:
The named Termination if it exists
Throws:
StructuralException - if the named Termination does not exist
See Also:
Node.getTermination(java.lang.String)

setMode

public void setMode(SimulationMode mode)
Description copied from class: EnsembleImpl
This Ensemble does not support SimulationMode.DIRECT.

Specified by:
setMode in interface SimulationMode.ModeConfigurable
Overrides:
setMode in class EnsembleImpl
Parameters:
mode - SimulationMode in which it is desired that the object runs.
See Also:
SimulationMode.ModeConfigurable.setMode(ca.nengo.model.SimulationMode)

fixMode

public void fixMode()
When this method is called, the mode of this node is fixed and cannot be changed by subsequent setMode(...) calls.


getModeFixed

public boolean getModeFixed()
Returns:
whether or not the mode for this ensemble has been fixed

reset

public void reset(boolean randomize)
Description copied from class: AbstractEnsemble
Resets each Node in this Ensemble.

Specified by:
reset in interface Resettable
Overrides:
reset in class PlasticEnsembleImpl
Parameters:
randomize - True indicates that the object should be reset to a randomly selected initial state (the object must be aware of the distribution from which to draw from). False indicates that the object should be reset to a fixed initial state (which it must also know). Some objects may not support randomization of the initial state, in which case a fixed state will be used in either case.
See Also:
Resettable.reset(boolean)

setEnsembleFactory

public void setEnsembleFactory(NEFEnsembleFactory factory)
Description copied from interface: NEFEnsemble
Gives the ensemble a reference to the factory used to created it (useful for adding more neurons later)

Specified by:
setEnsembleFactory in interface NEFEnsemble

getEnsembleFactory

public NEFEnsembleFactory getEnsembleFactory()
Specified by:
getEnsembleFactory in interface NEFEnsemble

getNodeCount

public int getNodeCount()
Description copied from interface: NEFEnsemble
For changing the number of neurons in the ensemble

Specified by:
getNodeCount in interface NEFEnsemble

setNodeCount

public void setNodeCount(int n)
                  throws StructuralException
Specified by:
setNodeCount in interface NEFEnsemble
Throws:
StructuralException

getHistory

public TimeSeries getHistory(java.lang.String stateName)
                      throws SimulationException
Description copied from interface: Probeable
Note that the units of TimeSeries' for a given state do not change over time (ie at different time steps). CAUTION: The TimeSeries should not contain a reference to any arrays that you are going to change later. The caller owns what you return.

Specified by:
getHistory in interface Probeable
Overrides:
getHistory in class DecodableEnsembleImpl
Parameters:
stateName - A state variable name
Returns:
Composite of Node states by given name. States of different nodes may be defined at different times, so only the states at the end of the most recent step are given. Only the first dimension of each Node state is included in the composite.
Throws:
SimulationException - if the Probeable does not have the requested state
See Also:
Probeable.getHistory(java.lang.String)

listStates

public java.util.Properties listStates()
Specified by:
listStates in interface Probeable
Overrides:
listStates in class DecodableEnsembleImpl
Returns:
List of state variable names, eg "V", and associated descriptions eg "membrane potential (mV)"
See Also:
Probeable.listStates()

clone

public NEFEnsemble clone()
                  throws java.lang.CloneNotSupportedException
Specified by:
clone in interface Node
Overrides:
clone in class DecodableEnsembleImpl
Returns:
An independent copy of the Node
Throws:
java.lang.CloneNotSupportedException

releaseMemory

public void releaseMemory()
Releases any memory that can be freed. Should be called after all origins are created for this ensemble

Specified by:
releaseMemory in interface NEFEnsemble

setNeurons

public void setNeurons(int count)
                throws StructuralException
TODO: figure out why I have to add these so that it will show up in the Configure menu (nodeCount doens't appear for some reason)

Throws:
StructuralException

getNeurons

public int getNeurons()

getStaticNeuronData

public float[] getStaticNeuronData()
Used to get static neuron data (data that doesn't change each step) and give it to the GPU. Data is returned in an array. neuronData[0] = numNeurons neuronData[1] = tauRC neuronData[2] = tauRef neuronData[3] = maxTimeStep neuronData[4 ... 3 + numNeurons] = bias for each neuron neuronData[4 + numNeurons ... 4 + 2 * numNeurons] = scale for each neuron


isGPUNode

public boolean isGPUNode()

setGPU

public void setGPU(boolean useGPU)

killNeurons

public void killNeurons(float killrate,
                        boolean saveRelays)
Stops a given percentage of neurons in this population from firing.

Parameters:
killrate - the percentage of neurons to stop firing
saveRelays - if true, do nothing if there is only one node in this population