Nengo.ca

ca.nengo.model.nef.impl
Class DecodedOrigin

java.lang.Object
  extended by ca.nengo.model.nef.impl.DecodedOrigin
All Implemented Interfaces:
Configurable, Noise.Noisy, Origin, ShortTermPlastic, Resettable, SimulationMode.ModeConfigurable, java.io.Serializable, java.lang.Cloneable
Direct Known Subclasses:
BiasOrigin

public class DecodedOrigin
extends java.lang.Object
implements Origin, Resettable, SimulationMode.ModeConfigurable, Noise.Noisy, Configurable, ShortTermPlastic

An Origin of functions of the state variables of an NEFEnsemble. TODO: how do units fit in. define in constructor? ignore? TODO: select nodes make up decoded origin

See Also:
Serialized Form

Constructor Summary
DecodedOrigin(Node node, java.lang.String name, Node[] nodes, java.lang.String nodeOrigin, Function[] functions, float[][] decoders)
          With this constructor decoding vectors are specified by the caller.
DecodedOrigin(Node node, java.lang.String name, Node[] nodes, java.lang.String nodeOrigin, Function[] functions, LinearApproximator approximator)
          With this constructor, decoding vectors are generated using default settings.
DecodedOrigin(Node node, java.lang.String name, Node[] nodes, java.lang.String nodeOrigin, TimeSeries targetSignal, LinearApproximator approximator)
          With this constructor the target is a signal over time rather than a function.
 
Method Summary
 DecodedOrigin clone()
           
 DecodedOrigin clone(Ensemble e)
          Clone method that changes necessary parameters to point to a new parent, for use in cloning ensembles, etc.
 Configuration getConfiguration()
           
 float[][] getDecoders()
           
 int getDimensions()
           
 float[] getError()
           
 float[] getError(int samples)
           
 ExpressModel getExpressModel()
           
 Function[] getFunctions()
           
 SimulationMode getMode()
           
 java.lang.String getName()
           
 Node getNode()
           
protected  java.lang.String getNodeOrigin()
           
 Noise getNoise()
           
 boolean getRequiredOnCPU()
           
 DynamicalSystem getSTPDynamics()
           
 DynamicalSystem getSTPDynamics(int i)
          Provides access to copy of dynamics for an individual node, to allow node-by-node parameterization.
protected  TimeSeries getSTPHistory()
           
 InstantaneousOutput getValues()
           
 void rebuildDecoder(LinearApproximator approximator)
          Recalculates the decoders
 void redefineNodes(Node[] nodes, LinearApproximator approximator)
          Changes the set of nodes and recalculates the decoders
 void rescaleDecoders(float[] scale)
          Rescales the decoders.
 void reset(boolean randomize)
           
 void run(float[] state, float startTime, float endTime)
          Must be called at each time step after Nodes are run and before getValues().
 void setDecoders(float[][] decoders)
           
 void setExpressModel(ExpressModel em)
           
 void setMode(SimulationMode mode)
          Sets the object to run in either the given mode or the closest mode that it supports (all ModeConfigurables must support SimulationMode.DEFAULT, and must default to this mode).
 void setNoise(Noise noise)
           
 void setRequiredOnCPU(boolean val)
           
 void setSTPDynamics(DynamicalSystem dynamics)
           
 void setValues(InstantaneousOutput val)
           
 void setValues(RealOutput ro)
           
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DecodedOrigin

public DecodedOrigin(Node node,
                     java.lang.String name,
                     Node[] nodes,
                     java.lang.String nodeOrigin,
                     Function[] functions,
                     LinearApproximator approximator)
              throws StructuralException
With this constructor, decoding vectors are generated using default settings.

Parameters:
node - The parent Node
name - Name of this Origin
nodes - Nodes that belong to the NEFEnsemble from which this Origin arises
nodeOrigin - Name of the Origin on each given node from which output is to be decoded
functions - Output Functions on the vector that is represented by the NEFEnsemble (one Function per dimension of output). For example if the Origin is to output x1*x2, where the ensemble represents [x1 x1], then one 2D function would be needed in this list. The input dimension of each function must be the same as the dimension of the state vector represented by this ensemble.
approximator - A LinearApproximator that can be used to approximate new functions as a weighted sum of the node outputs.
Throws:
StructuralException - if functions do not all have the same input dimension (we don't check against the state dimension at this point)

DecodedOrigin

public DecodedOrigin(Node node,
                     java.lang.String name,
                     Node[] nodes,
                     java.lang.String nodeOrigin,
                     Function[] functions,
                     float[][] decoders)
              throws StructuralException
With this constructor decoding vectors are specified by the caller.

Parameters:
node - The parent Node
name - As in other constructor
nodes - As in other constructor
nodeOrigin - Name of the Origin on each given node from which output is to be decoded
functions - As in other constructor
decoders - Decoding vectors which are scaled by the main output of each Node, and then summed, to estimate the same function of the ensembles state vector that is defined by the 'functions' arg. The 'functions' arg is still needed, because in DIRECT SimulationMode, these functions are used directly. The 'decoders' arg allows the caller to provide decoders that are generated with non-default methods or parameters (eg an unusual number of singular values). Must be a matrix with one row per Node and one column per function.
Throws:
StructuralException - If dimensions.length != neurons.length, decoders is not a matrix (ie all elements with same length), or if the number of columns in decoders is not equal to the number of functions

DecodedOrigin

public DecodedOrigin(Node node,
                     java.lang.String name,
                     Node[] nodes,
                     java.lang.String nodeOrigin,
                     TimeSeries targetSignal,
                     LinearApproximator approximator)
              throws StructuralException
With this constructor the target is a signal over time rather than a function.

Parameters:
node - The parent Node
name - As in other constructor
nodes - As in other constructor
nodeOrigin - Name of the Origin on each given node from which output is to be decoded
targetSignal - Signal over time that this origin should produce.
approximator - A LinearApproximator that can be used to approximate new signals as a weighted sum of the node outputs.
Throws:
StructuralException
Method Detail

getExpressModel

public ExpressModel getExpressModel()
Returns:
Simplified model of deviations from DIRECT mode that are associated with spiking simulations

setExpressModel

public void setExpressModel(ExpressModel em)
Parameters:
em - Simplified model of deviations from DIRECT mode that are associated with spiking simulations

getConfiguration

public Configuration getConfiguration()
Specified by:
getConfiguration in interface Configurable
Returns:
This Configurable's Configuration data
See Also:
Configurable.getConfiguration()

getError

public float[] getError()
Returns:
Mean-squared error of this origin over 500 randomly selected points

getError

public float[] getError(int samples)
Parameters:
samples - The number of input vectors the error is sampled over
Returns:
Mean-squared error of this origin over randomly selected points

setNoise

public void setNoise(Noise noise)
Specified by:
setNoise in interface Noise.Noisy
Parameters:
noise - New output noise model (defaults to no noise)

getNoise

public Noise getNoise()
Specified by:
getNoise in interface Noise.Noisy
Returns:
Noise with which output of this Origin is corrupted

reset

public void reset(boolean randomize)
Specified by:
reset in interface Resettable
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)

getName

public java.lang.String getName()
Specified by:
getName in interface Origin
Returns:
Name of this Origin (unique in the scope of a source of Origins, eg a Neuron or Ensemble)
See Also:
Origin.getName()

getDimensions

public int getDimensions()
Specified by:
getDimensions in interface Origin
Returns:
Dimensionality of information coming from this Origin (eg number of axons, or dimension of decoded function of variables represented by the Ensemble)
See Also:
Origin.getDimensions()

getDecoders

public float[][] getDecoders()
Returns:
Decoding vectors for each Node

getSTPDynamics

public DynamicalSystem getSTPDynamics()
Specified by:
getSTPDynamics in interface ShortTermPlastic
Returns:
Dynamics of short-term plasticity
See Also:
ShortTermPlastic.getSTPDynamics()

getSTPDynamics

public DynamicalSystem getSTPDynamics(int i)
Provides access to copy of dynamics for an individual node, to allow node-by-node parameterization.

Parameters:
i - Node number
Returns:
Dynamics of short-term plasticity for the specified node

setSTPDynamics

public void setSTPDynamics(DynamicalSystem dynamics)
Specified by:
setSTPDynamics in interface ShortTermPlastic
Parameters:
dynamics - New dynamics of short-term plasticity
See Also:
ShortTermPlastic.setSTPDynamics(ca.nengo.dynamics.DynamicalSystem)

setDecoders

public void setDecoders(float[][] decoders)
Parameters:
decoders - New decoding vectors (row per Node)

setMode

public void setMode(SimulationMode mode)
Description copied from interface: SimulationMode.ModeConfigurable
Sets the object to run in either the given mode or the closest mode that it supports (all ModeConfigurables must support SimulationMode.DEFAULT, and must default to this mode).

Specified by:
setMode in interface SimulationMode.ModeConfigurable
Parameters:
mode - Requested simulation mode

getMode

public SimulationMode getMode()
Specified by:
getMode in interface SimulationMode.ModeConfigurable
Returns:
The mode in which the Ensemble is currently running.

run

public void run(float[] state,
                float startTime,
                float endTime)
         throws SimulationException
Must be called at each time step after Nodes are run and before getValues().

Parameters:
state - Idealized state (as defined by inputs) which can be fed into (idealized) functions that make up the Origin, when it is running in DIRECT mode. This is not used in other modes, and can be null.
startTime - simulation time of timestep onset
endTime - simulation time of timestep end
Throws:
SimulationException - If the given state is not of the expected dimension (ie the input dimension of the functions provided in the constructor)

getSTPHistory

protected TimeSeries getSTPHistory()

getValues

public InstantaneousOutput getValues()
                              throws SimulationException
Specified by:
getValues in interface Origin
Returns:
Instantaneous output from this Origin.
Throws:
SimulationException - if there is any problem retrieving values
See Also:
Origin.getValues()

setValues

public void setValues(InstantaneousOutput val)
Specified by:
setValues in interface Origin
See Also:
ca.nengo.model.Origin#setValues()

setValues

public void setValues(RealOutput ro)
Parameters:
ro - Values to be set

getFunctions

public Function[] getFunctions()
Returns:
List of Functions approximated by this DecodedOrigin

getNodeOrigin

protected java.lang.String getNodeOrigin()
Returns:
Name of Node-level Origin on which this DecodedOrigin is based

getNode

public Node getNode()
Specified by:
getNode in interface Origin
Returns:
The Node to which the Origin belongs
See Also:
Origin.getNode()

clone

public DecodedOrigin clone()
                    throws java.lang.CloneNotSupportedException
Specified by:
clone in interface Origin
Overrides:
clone in class java.lang.Object
Returns:
Valid clone
Throws:
java.lang.CloneNotSupportedException - if clone cannot be made

clone

public DecodedOrigin clone(Ensemble e)
                    throws java.lang.CloneNotSupportedException
Description copied from interface: Origin
Clone method that changes necessary parameters to point to a new parent, for use in cloning ensembles, etc.

Specified by:
clone in interface Origin
Parameters:
e - New parent ensemble
Returns:
A clone of the origin for the new parent ensemble
Throws:
java.lang.CloneNotSupportedException - if clone cannot be made

rescaleDecoders

public void rescaleDecoders(float[] scale)
Rescales the decoders. Useful if the radius changes but you don't want to regenerate the decoders.

Parameters:
scale - vector to multiply each decoder by

rebuildDecoder

public void rebuildDecoder(LinearApproximator approximator)
Recalculates the decoders

Parameters:
approximator - approximator?

redefineNodes

public void redefineNodes(Node[] nodes,
                          LinearApproximator approximator)
Changes the set of nodes and recalculates the decoders

Parameters:
nodes - Nodes to replace existing nodes
approximator - approximator?

setRequiredOnCPU

public void setRequiredOnCPU(boolean val)
Specified by:
setRequiredOnCPU in interface Origin

getRequiredOnCPU

public boolean getRequiredOnCPU()
Specified by:
getRequiredOnCPU in interface Origin

Nengo.ca