neuron.h

此代码经过大量使用

/***************************************************************************
                          neuron.h  -  description
                             -------------------
    copyright            : (C) 2001, 2002 by Matt Grover
    email                : [e-mail]
 ***************************************************************************/

/***************************************************************************
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 ***************************************************************************/

/***************************************************************************
    Implement a spiking neuron based on the Integrate-and-fire model.  This
    class class will be converted into an abstract base class in the near
    future and much of the code will be moved to BasicNeuron.
 ***************************************************************************/

#ifndef NEURON_H
#define NEURON_H

using namespace std;
#include <amygdala/types.h>
#include <vector>
#if GCC_VERSION >= 30000
    #include <ext/hash_map>
#else
    #include <hash_map>
#endif
#include <cmath>
#include <amygdala/network.h>
#include <amygdala/mpspikeinput.h>


class MpNetwork;
class Network;
class FunctionLookup;
class SpikeOutput;

/** State of ouput reporting. */
enum OutputMode { OFF, OUTPUT_LAYERS, ALL };

/** @class PhysicalProperties neuron.h amygdala/neuron.h
 * @brief Container for physical properties of a Neuron such as it's location
    in a 3-D space. */
class PhysicalProperties {
public:
    PhysicalProperties();
    ~PhysicalProperties();
    void SetLocation(float _newVal[]);
    float * GetLocation(float loc[]);

protected:
    /** The location of the neuron in a 3-D space.  */
    float location[3];
};

//class CompareSynapse;

/** @class Synapse neuron.h amygdala/neuron.h
 * @brief Container for synaptic properties (weight, axonal transmition
 * delay, and pointer to the postsynaptic neuron). */
class Synapse {
public:
    Synapse(Neuron* _postNrn, float _weight, AmTimeInt _delay = 0);
    ~Synapse() {}

    float GetWeight() { return weight; }
    void SetWeight(float _weight) { weight = _weight; }
    const AmTimeInt& GetOffset() const { return offset; }
    AmTimeInt GetDelay() const;
    Neuron* GetPostNeuron() const { return postNrn; }
protected:
    float weight;
    Neuron* postNrn;
    AmTimeInt offset;
    friend class CompareSynapse;
};


/** @class SMPSynapse neuron.h amygdala/neuron.h
 * @brief Synapse for synapses between Instances on the same Node.
 */
class SMPSynapse : public Synapse {
public:
    SMPSynapse(MpSpikeInput *_connector, Neuron* _postNrn, float _weight, AmTimeInt _delay = 0);
    /** a spike event occurred. Do the right thing */
    void SpikeEvent();
protected:
    /** The spikeinput of the postsynaptic Network Instance */
    MpSpikeInput *connector;
};


/** @class CompareSynapse neuron.h amygdala/neuron.h
 * @brief CompareSynapse is a functor used to provide a '<' operation
 * for synapses (for sorting).
 * The operation is performed on
 * the value returned by Synapse::GetPostNeuron(). */
class CompareSynapse {
public:
    CompareSynapse() {}
    ~CompareSynapse() {}
//    bool operator()(const Synapse* lsyn, const Synapse* rsyn) {
//        return lsyn->GetPostNeuron() < rsyn->GetPostNeuron(); }
    bool operator()(const Synapse* lsyn, const Synapse* rsyn) {
        return lsyn->postNrn < rsyn->postNrn; }
};

typedef vector<Synapse*>::iterator SynapseItr;


/** @class Neuron neuron.h amygdala/neuron.h
  * @brief Virtual base class for all Neurons.
  *
  * Neuron provides an interface for the implementation of
  * integrate-and-fire model neurons. Neuron cannot be
  * instantiated as an object itself, but can only be
  * instantiated via a child class.  Neuron does not place any
  * restrictions on how child neurons are modeled other than
  * requiring the implementation of a set of functions that
  * will generally be unique to each model.  Neuron implementors
  * should also be aware that Amygdala is an event driven
  * simulator and a Neuron will only interact with the rest
  * of the network when it receives a spike or when it is
  * scheduled to spike itself.  Methods may be added in a future
  * version to allow stepping simulations in which active Neurons
  * are able to calculate their states for each time step.  Neuron
  * does provide a default Hebbian training method, but child
  * classes are able to implement their own training methods
  * if necessary.
  * <P>Notes: Neurons must be added to
  * a Network object before they can be connected to other
  * Neurons and used in a simulation.  This can be done either
  * directly through the Network::AddNeuron() function, or it
  * can be done by adding a Neuron to a Layer object (via Layer::AddNeuron())
  * and then adding the Layer to the Network.  Neurons are connected
  * to each other using the Network::ConnectNeurons() function.
  * Layer also provides methods for connecting groups of Neurons.
  * Network owns all Neuron pointers once they have been added.
  * @see AlphaNeuron, BasicNeuron, FastNeuron
  * @author Matt Grover
  */

class Neuron {
public:
    friend void MpSpikeInput::ReadInputBuffer();

    /** @param neuronId A unique, positive integer that is used
     *  to identify the neuron. */
    Neuron(AmIdInt neuronId);
    virtual ~Neuron();

    /** Set the number of output connections that will be added,
     * if known.  This should only be done <em>BEFORE</em> AddAxonSyn()
     * has been called.  Setting the number of outputs before
     * adding them will often result in more efficient
     * memory usage, but this is not required if the
     * size is unknown.
     * @param size Expected size of the axon (number of outputs). */
    void SetAxonSize(int size);

    /** @return Number of output synapses. */
    int GetAxonSize() const { return axon.size(); }
    /** @return an iterator for the SMP Axon */
    vector <SMPSynapse*>::iterator smpaxon_begin() { return smpAxon.begin(); }
    /** @return an iterator for the SMP Axon */
    vector <SMPSynapse*>::iterator smpaxon_end() { return smpAxon.end(); }

    /** @param index Index number of a synapse on the axon.
     * Synaptic indexes are always sequential for parsing.
     * The index has no meaningful relationship
     * to the neuron ID and is not guaranteed to remain constant
     * if the network is reconstructed or reloaded from a file.
     * This will be supplemented or replaced by an iterator in
     * a future version.
     * @return Neuron ID of an output neuron.*/
    AmIdInt GetAxonID(unsigned int index) { return axon[index]->GetPostNeuron()->GetID(); }

    /** @param index Index number of a synapse on the axon. Synaptic indexes are
     * always sequential to allow parsing.
     * @return Normalized weight of a connection with an output neuron. */
    // FIXME: This has to return the normalized weight -- this will return
    // the scaled weight as it is now.  See the source of the old Neuron::GetWeight()
    float GetAxonWeight(unsigned int index) { return axon[index]->GetWeight(); }

    /** Note: Axon delays are implemented as a delay between the
     * spike time and the time that the output neuron receives
     * the spike.  This value can only be set when a connection
     * is formed through the Network::ConnectNeurons() call, so
     * no Set method is provided in Neuron.
     * @param index Index number of a synapse on the axon. Synaptic indexes are
     * always sequential to enable parsing.
     * @return Spike transmission time for a synapse.  */
    float GetAxonDelay(unsigned int index) { return axon[index]->GetDelay(); }

    /** Set a pointer to the parent network.
     * @param ParNet The Network that contains this Neuron. */
    void SetParentNet(Network* const ParNet) { SNet = ParNet; }

    /** @return The neuron ID. */
    AmIdInt GetID() { return(nId); }

    /** Note: This will change to GetLayerRole() in a future version.
     * @return The type of layer that the neuron belongs to
     * (input, hidden, or output). */
    LayerType GetLayerType() { return(layerType); }

    /** Set the layer type for this neuron. This will
     * change to SetNeuronRole in a future version.
     * @param _layerType One of INPUTLAYER,
     * HIDDENLAYER, OUTPUTLAYER or IOLAYER. */
    void SetLayerType(LayerType _layerType) { layerType = _layerType; }

    /** Set the synaptic and membrane time constants. Default values
     * may vary between child classes and some child classes may
     * not use both constants.
     * @param synapticConst The synaptic time constant in milliseconds.
     * @param membraneConst The membrane time constant in milliseconds.
     * @see Neuron::GetSynapticConst(), Neuron::GetMembraneConst(). */
    void SetTimeConstants(float synapticConst, float membraneConst);

    /** @return The membrane time constant in ms.
     * @see Neuron::SetTimeConstants(). */
    float GetMembraneConst() const { return memTimeConst; }

    /** @return The synaptic time constant in ms.
     * @see Neuron::SetTimeConstants(). */
    float GetSynapticConst() const { return synTimeConst; }

    /** Set the length of the refractory period.  Defaults
     * to 2 ms if not set explicitely.
     * @param period Refractory period in milliseconds. */
    void SetRefractory(float period) { refPeriod = (period * 1000); }

    /** @return The size of the refractory period in milliseconds. */
    float GetRefractory() const { return (refPeriod / 1000); }

    /** Set the learning constant.
     * @param learnConst Value of the learning constant.
     * Typical values are around 1e-5. */
    void SetLearningConst(float learnConst) { learningConst = learnConst; }

    /** @return The value of the learning constant. */
    float GetLearningConst() const { return learningConst; }

    /** Set the value of the rest potential.
     * @param ptnl Value of the rest potential in mV. */
    void SetRestPotential(float ptnl) { restPtnl = ptnl; }

    /** Get the value of the rest potential in mV.
     * @return Value of the rest potential in mV.
     * @see Neuron::SetRestPotential(). */
    float GetRestPotential() const { return restPtnl; }

    /** Set the threshold potential.
     * @param ptnl Value of the threshold potential in mV. */
    void SetThresholdPotential(float ptnl) { thresholdPtnl = ptnl; }

    /** @return The threshold potential in mV. */
    float GetThresholdPotential() const { return thresholdPtnl; }

    /** Set the training mode.
     * @param mode Training mode, can be either
     * true (training on) or false.
     * @see Neuron::IsTraining(). */
    void TrainingOn(bool mode) { trainingMode = mode; }

    /** @return Training mode
     * @see Neuron::TrainingOn(). */
    bool IsTraining() const { return trainingMode; }

    /** Set this to true if this is is an inhibitory
     * neuron. This function has no effect if neuron
     * signs (positive or negative) are not being enforced.
     * @param val Inhibitory status.  If true,
     * all outgoing connections will have
     * negative weights.
     * @see Neuron::EnforceSign(). */
    void Inhibitory(bool val) { inhibitory = val; }

    /** Get the neuron sign.
     * @return True for inhibitory neurons, false otherwise.
     * This value has no real meaning if neuron sign is not
     * being enforced.
     * @see Neuron::EnforceSign(). */
    bool Inhibitory() const { return inhibitory; }

    /** Turn output on or off.  Turning on will cause output
     * neurons to call SpikeOutput::OutputEvent() every time
     * they spike. NOTE: This function may change in a future version.
     * Enabling and disabling output may be controlled through the SpikeOutput
     * family of classes rather than through this call.
     * @param mode One of OFF, OUTPUT_LAYERS, or ALL.
     * OUTPUT_LAYERS mode causes output neurons to register spikes
     * with SpikeOutput, and ALL causes all neurons to register spikes.
     * @see SpikeOutput::OutputEvent().*/
    static void CaptureOutput(OutputMode mode);

    /** Set a pointer to a new output object.  Neuron uses an instance of
     * AmygSimpleOutput by default (until set by SetAmygOutput). Users
     * are responsible for deleting any SpikeOutput objects that they
     * instantiate and pass to Neuron.
     * @param output Pointer to a SpikeOutput object.
     * @see Neuron::CaputureOutput(), Neuron::GetSpikeOutput,
     * SpikeOutput::OutputEvent(). */
    static void SetSpikeOutput(SpikeOutput* output);

    /** Get a pointer to a SpikeOutput object.
     * @return A pointer to the instance of SpikeOutput currently
     * in use.
     * @see Neuron::SetSpikeOutut(). */
    static SpikeOutput* GetSpikeOutput() { return spikeOutput; }

    /** Allow the network to force neurons to be either inhibitory
     * or excitatory. If false, Neurons can form both inhibitory and
     * excitatory output connections.
     * @param enforce True if neuron sign should be enforced. False by default.
     * @see Neuron::Inhibitory(). */
    static void EnforceSign(bool enforce) { enforceSign = enforce; }

    /** Get the sign enforcement mode.