Nengo.ca

ca.nengo.model.nef.impl
Class DecodableEnsembleImpl

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

public class DecodableEnsembleImpl
extends PlasticEnsembleImpl
implements DecodableEnsemble

Default implementation of DecodableEnsemble.

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
protected  java.util.Map<java.lang.String,DecodedOrigin> myDecodedOrigins
           
protected  java.util.Map<java.lang.String,DecodedTermination> myDecodedTerminations
           
 
Fields inherited from class ca.nengo.model.plasticity.impl.PlasticEnsembleImpl
myPlasticEnsembleTerminations
 
Fields inherited from class ca.nengo.model.impl.EnsembleImpl
myExpandableNodes, myExpandedTerminations
 
Constructor Summary
DecodableEnsembleImpl(java.lang.String name, Node[] nodes, ApproximatorFactory factory)
           
 
Method Summary
 Origin addDecodedOrigin(java.lang.String name, Function[] functions, java.lang.String nodeOrigin, Network environment, Probe probe, float startTime, float endTime)
          Adds an Origin that corresponds to a decoding of the activities of Nodes in this Ensemble.
 Origin addDecodedOrigin(java.lang.String name, Function[] functions, java.lang.String nodeOrigin, Network environment, Probe probe, Probe state, float startTime, float endTime, float tau)
          Lloyd Elliot's decodable origin for decoding band-limited noise using a psc optimized decoder
 Origin addDecodedOrigin(java.lang.String name, Function[] functions, java.lang.String nodeOrigin, Network environment, Probe probe, Termination termination, float[][] evalPoints, float transientTime)
          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)
           
 Termination addDecodedTermination(java.lang.String name, float[][] matrix, float tauPSC, boolean isModulatory)
           
 DecodableEnsembleImpl clone()
           
 void doneOrigins()
          This method can optionally be called after all decoded Origins have been added, in order to free resources that are needed for adding new decodings.
 ApproximatorFactory getApproximatorFactory()
           
 DecodedOrigin[] getDecodedOrigins()
          Used to get decoded origins to give to GPU.
 DecodedTermination[] getDecodedTerminations()
          Used to get decoded terminations to give to GPU.
 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).
 Origin getOrigin(java.lang.String name)
           
 Origin[] getOrigins()
           
 Termination getTermination(java.lang.String name)
           
 Termination[] getTerminations()
           
 java.util.Properties listStates()
           
 DecodedOrigin removeDecodedOrigin(java.lang.String name)
           
 DecodedTermination 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 setTime(float time)
          Allows subclasses to set the simulation time, which is used to support Probeable.
 void stopProbing(java.lang.String stateName)
           
 
Methods inherited from class ca.nengo.model.plasticity.impl.PlasticEnsembleImpl
addTasks, getLearning, getPlasticityInterval, getTasks, isPopulationPlastic, setLearning, setPlasticityInterval, setStates, setTasks
 
Methods inherited from class ca.nengo.model.impl.EnsembleImpl
addTermination, getChildren, getDimension, removeTermination, setMode, toScript
 
Methods inherited from class ca.nengo.model.impl.AbstractEnsemble
addChangeListener, collectSpikes, findCommon1DOrigins, fireVisibleChangeEvent, getCollectSpikesRatio, getDocumentation, getMode, getName, getNodes, getSpikePattern, isCollectingSpikes, redefineNodes, removeChangeListener, removeOrigin, 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.plasticity.PlasticEnsemble
getPlasticityInterval, setPlasticityInterval
 
Methods inherited from interface ca.nengo.model.Ensemble
collectSpikes, getNodes, getSpikePattern, isCollectingSpikes, redefineNodes
 
Methods inherited from interface ca.nengo.model.Node
getChildren, getDocumentation, getName, setDocumentation, setName, toScript
 
Methods inherited from interface ca.nengo.model.SimulationMode.ModeConfigurable
getMode, setMode
 
Methods inherited from interface ca.nengo.util.VisiblyMutable
addChangeListener, removeChangeListener
 

Field Detail

myDecodedOrigins

protected java.util.Map<java.lang.String,DecodedOrigin> myDecodedOrigins

myDecodedTerminations

protected java.util.Map<java.lang.String,DecodedTermination> myDecodedTerminations
Constructor Detail

DecodableEnsembleImpl

public DecodableEnsembleImpl(java.lang.String name,
                             Node[] nodes,
                             ApproximatorFactory factory)
                      throws StructuralException
Parameters:
name - Name of the Ensemble
nodes - Nodes that make up the Ensemble
factory - Source of LinearApproximators to use in decoding output
Throws:
StructuralException - if super constructor fails
Method Detail

addDecodedOrigin

public Origin addDecodedOrigin(java.lang.String name,
                               Function[] functions,
                               java.lang.String nodeOrigin,
                               Network environment,
                               Probe probe,
                               float startTime,
                               float endTime)
                        throws StructuralException,
                               SimulationException
Description copied from interface: DecodableEnsemble
Adds an Origin that corresponds to a decoding of the activities of Nodes in this Ensemble. The decoding is found by running the Ensemble within a Network, and using its output to approximate a vector function of time.

Specified by:
addDecodedOrigin in interface DecodableEnsemble
Parameters:
name - Name of decoding
functions - 1D Functions of time which represent the meaning of the Ensemble output when it runs in the Network provided (see environment arg)
nodeOrigin - The name of the Node-level Origin to decode
environment - A Network in which the Ensemble runs (may include inputs, feedback, etc)
probe - A Probe that is connected to the named Node-level Origin
startTime - Simulation time at which to start
endTime - Simulation time at which to finish
Returns:
An Origin that approximates the given Functions as a linear combination of output from the given nodeOrigin
Throws:
StructuralException - May arise in instantiating the Origin
SimulationException - If there is a problem running the simulation
See Also:
DecodableEnsemble.addDecodedOrigin(java.lang.String, ca.nengo.math.Function[], java.lang.String, ca.nengo.model.Network, ca.nengo.util.Probe, float, float)

addDecodedOrigin

public Origin addDecodedOrigin(java.lang.String name,
                               Function[] functions,
                               java.lang.String nodeOrigin,
                               Network environment,
                               Probe probe,
                               Termination termination,
                               float[][] evalPoints,
                               float transientTime)
                        throws StructuralException,
                               SimulationException
Description copied from interface: DecodableEnsemble
Adds an Origin that corresponds to a decoding of the activities of Nodes in this Ensemble. The decoding is found by running the Ensemble repeatedly with different inputs, and using the steady-state output for each input to approximate a vector function of the input. Input is applied to a caller-defined Termination which may or may not be directly onto the Ensemble.

Specified by:
addDecodedOrigin in interface DecodableEnsemble
Parameters:
name - Name of decoding
functions - Functions of input that represent the meaning of Ensemble output when it runs in the Network provided (see environment arg)
nodeOrigin - The name of the Node-level Origin to decode
environment - A Network in which the Ensemble runs (may include inputs, feedback, etc)
probe - A Probe that is connected to the named Node-level Origin
termination - The Termination through which input is to be applied to the Ensemble
evalPoints - The set of vector inputs that are to be applied at the above Termination
transientTime - The amount of time the Network is to run with each input, so that transients die away (output is averaged over the last 10% of each simulation)
Returns:
An Origin that approximates the given Functions as a linear combination of output from the given nodeOrigin
Throws:
StructuralException - May arise in instantiating the Origin
SimulationException - If there is a problem running the simulations
See Also:
DecodableEnsemble.addDecodedOrigin(java.lang.String, ca.nengo.math.Function[], java.lang.String, ca.nengo.model.Network, ca.nengo.util.Probe, ca.nengo.model.Termination, float[][], float)

addDecodedOrigin

public Origin addDecodedOrigin(java.lang.String name,
                               Function[] functions,
                               java.lang.String nodeOrigin,
                               Network environment,
                               Probe probe,
                               Probe state,
                               float startTime,
                               float endTime,
                               float tau)
                        throws StructuralException,
                               SimulationException
Lloyd Elliot's decodable origin for decoding band-limited noise using a psc optimized decoder

Parameters:
name - Name of decoding
functions - 1D Functions of time which represent the meaning of the Ensemble output when it runs in the Network provided (see environment arg)
nodeOrigin - The name of the Node-level Origin to decode
environment - A Network in which the Ensemble runs (may include inputs, feedback, etc)
probe - A Probe that is connected to the named Node-level Origin
state - Another probe?
startTime - Simulation time at which to start
endTime - Simulation time at which to finish
tau - Time constant
Returns:
The added Origin
Throws:
StructuralException - if origin name is taken
SimulationException - if environment can't run

addDecodedTermination

public Termination addDecodedTermination(java.lang.String name,
                                         float[][] matrix,
                                         float tauPSC,
                                         boolean isModulatory)
                                  throws StructuralException
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:
Added Termination
Throws:
StructuralException - if termination name is taken
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
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?
tfNumerator - Coefficients of transfer function numerator (see CanonicalModel.getRealization(...) for details)
tfDenominator - Coefficients of transfer function denominator
passthrough - How much should pass through?
isModulatory - Is the termination modulatory?
Returns:
The added Termination
Throws:
StructuralException - if termination name is taken
See Also:
NEFEnsemble.addDecodedTermination(java.lang.String, float[][], float[], float[], float, boolean)

removeDecodedTermination

public DecodedTermination removeDecodedTermination(java.lang.String name)
                                            throws StructuralException
Specified by:
removeDecodedTermination in interface DecodableEnsemble
Parameters:
name - Name of an existing termination to remove
Returns:
The removed DecodedTermination
Throws:
StructuralException - if DecodedTermination doesn't exist
See Also:
DecodableEnsemble.removeDecodedTermination(java.lang.String)

removeDecodedOrigin

public DecodedOrigin removeDecodedOrigin(java.lang.String name)
                                  throws StructuralException
Specified by:
removeDecodedOrigin in interface DecodableEnsemble
Parameters:
name - Name of an existing decoding to remove
Returns:
The removed DecodedOrigin
Throws:
StructuralException - if DecodedOrigin doesn't exist
See Also:
DecodableEnsemble.removeDecodedTermination(java.lang.String)

getDecodedTerminations

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

Returns:
all DecodedTerminations

doneOrigins

public void doneOrigins()
Description copied from interface: DecodableEnsemble
This method can optionally be called after all decoded Origins have been added, in order to free resources that are needed for adding new decodings.

Specified by:
doneOrigins in interface DecodableEnsemble
See Also:
DecodableEnsemble.doneOrigins()

getOrigin

public Origin getOrigin(java.lang.String name)
                 throws StructuralException
Specified by:
getOrigin in interface Node
Overrides:
getOrigin in class AbstractEnsemble
Parameters:
name - Name of an Origin on this Node
Returns:
The named Origin if it exists
Throws:
StructuralException - if the named Origin does not exist
See Also:
Node.getOrigin(java.lang.String)

getTermination

public Termination getTermination(java.lang.String name)
                           throws StructuralException
Specified by:
getTermination in interface Node
Overrides:
getTermination in class PlasticEnsembleImpl
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)

getOrigins

public Origin[] getOrigins()
Specified by:
getOrigins in interface Node
Overrides:
getOrigins in class AbstractEnsemble
Returns:
Sets of ouput channels (eg spiking outputs, gap junctional outputs, etc.)
See Also:
Node.getOrigins()

getDecodedOrigins

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

Returns:
All DecodedOrigins

getTerminations

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

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 PlasticEnsembleImpl
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)

setTime

public void setTime(float time)
Allows subclasses to set the simulation time, which is used to support Probeable. This is normally set in the run() method. Subclasses that override run() without calling it should set the time.

Parameters:
time - Simulation time

getApproximatorFactory

public ApproximatorFactory getApproximatorFactory()
Returns:
The source of LinearApproximators for this ensemble (used to find linear decoding vectors).

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 AbstractEnsemble
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 AbstractEnsemble
Returns:
List of state variable names, eg "V", and associated descriptions eg "membrane potential (mV)"
See Also:
Probeable.listStates()

stopProbing

public void stopProbing(java.lang.String stateName)
Specified by:
stopProbing in interface Ensemble
Overrides:
stopProbing in class AbstractEnsemble

clone

public DecodableEnsembleImpl clone()
                            throws java.lang.CloneNotSupportedException
Specified by:
clone in interface ExpandableNode
Specified by:
clone in interface Node
Overrides:
clone in class PlasticEnsembleImpl
Returns:
An independent copy of the Node
Throws:
java.lang.CloneNotSupportedException - if clone can't be made

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)

Nengo.ca