modelSpec.h

Go to the documentation of this file.

/*--------------------------------------------------------------------------
   Author: Thomas Nowotny
  
   Institute: Center for Computational Neuroscience and Robotics
              University of Sussex
              Falmer, Brighton BN1 9QJ, UK
  
   email to:  T.Nowotny@sussex.ac.uk
  
   initial version: 2010-02-07
   
   This file contains neuron model declarations.
  
--------------------------------------------------------------------------*/

//--------------------------------------------------------------------------
//--------------------------------------------------------------------------

#ifndef _MODELSPEC_H_
#define _MODELSPEC_H_ 

#include "neuronGroup.h"
#include "synapseGroup.h"
#include "currentSource.h"
#include "utils.h"

#include <map>
#include <set>
#include <string>
#include <vector>
#ifdef MPI_ENABLE
#include <mpi.h>
#endif

using namespace std;


void initGeNN();
extern unsigned int GeNNReady;

// connectivity of the network (synapseConnType)
enum SynapseConnType
{
    ALLTOALL,
    DENSE,
    SPARSE,
};

// conductance type (synapseGType)
enum SynapseGType
{
    INDIVIDUALG,
    GLOBALG,
    INDIVIDUALID,
};

#define NO_DELAY 0 

#define NOLEARNING 0 
#define LEARNING 1 

#define EXITSYN 0 
#define INHIBSYN 1 

#define CPU 0 
#define GPU 1 

enum FloatType
{
    GENN_FLOAT,
    GENN_DOUBLE,
    GENN_LONG_DOUBLE,
};

enum class TimePrecision
{
    DEFAULT,    
    FLOAT,      
    DOUBLE,     
};

#define AUTODEVICE -1  

// Wrappers to save typing when declaring VarInitialisers structures
template<typename S>
inline NewModels::VarInit initVar(const typename S::ParamValues &params)
{
    return NewModels::VarInit(S::getInstance(), params.getValues());
}

template<typename S>
inline typename std::enable_if<std::is_same<typename S::ParamValues, Snippet::ValueBase<0>>::value, NewModels::VarInit>::type initVar()
{
   return NewModels::VarInit(S::getInstance(), {});
}

inline NewModels::VarInit uninitialisedVar()
{
    return NewModels::VarInit(InitVarSnippet::Uninitialised::getInstance(), {});
}

template<typename S>
inline InitSparseConnectivitySnippet::Init initConnectivity(const typename S::ParamValues &params)
{
    return InitSparseConnectivitySnippet::Init(S::getInstance(), params.getValues());
}

template<typename S>
inline typename std::enable_if<std::is_same<typename S::ParamValues, Snippet::ValueBase<0>>::value, InitSparseConnectivitySnippet::Init>::type initConnectivity()
{
    return InitSparseConnectivitySnippet::Init(S::getInstance(), {});
}

inline InitSparseConnectivitySnippet::Init uninitialisedConnectivity()
{
    return InitSparseConnectivitySnippet::Init(InitSparseConnectivitySnippet::Uninitialised::getInstance(), {});
}

/*===============================================================
//
================================================================*/

class NNmodel
{
public:
    // Typedefines
    //=======================
    typedef map<string, NeuronGroup>::value_type NeuronGroupValueType;
    typedef map<string, SynapseGroup>::value_type SynapseGroupValueType;
    typedef map<string, std::pair<unsigned int, unsigned int>>::value_type SynapseGroupSubsetValueType;

    NNmodel();
    ~NNmodel();

    // PUBLIC MODEL FUNCTIONS
    //=======================
    void setName(const std::string&); 

    void setPrecision(FloatType); 
    void setTimePrecision(TimePrecision timePrecision); 
    void setDT(double); 
    void setTiming(bool); 
    void setSeed(unsigned int); 
    void setRNType(const std::string &type); 

#ifndef CPU_ONLY
    void setGPUDevice(int); 
#endif
    string scalarExpr(const double) const;

    void setPopulationSums(); 
    void finalize(); 

    bool zeroCopyInUse() const;

    unsigned int getNumPreSynapseResetRequiredGroups() const;

    bool isPreSynapseResetRequired() const{ return getNumPreSynapseResetRequiredGroups() > 0; }

    bool isHostRNGRequired() const;


    bool isDeviceRNGRequired() const;


    bool canRunOnCPU() const;

    const std::string &getName() const{ return name; }

    const std::string &getPrecision() const{ return ftype; }

    std::string getTimePrecision() const;

    unsigned int getResetKernel() const{ return resetKernel; }

    double getDT() const { return dt; }

    unsigned int getSeed() const { return seed; }

    const std::string &getRNType() const{ return RNtype; }

    bool isFinalized() const{ return final; }

    bool isTimingEnabled() const{ return timing; }

    std::string getGeneratedCodePath(const std::string &path, const std::string &filename) const;

    // PUBLIC INITIALISATION FUNCTIONS
    //================================
    const map<string, string> &getInitKernelParameters() const{ return m_InitKernelParameters; }


    bool isDeviceInitRequired(int localHostID) const;


    bool isDeviceSparseInitRequired() const;

    // PUBLIC NEURON FUNCTIONS
    //========================
    const map<string, NeuronGroup> &getLocalNeuronGroups() const{ return m_LocalNeuronGroups; }

    const map<string, NeuronGroup> &getRemoteNeuronGroups() const{ return m_RemoteNeuronGroups; }

    const map<string, string> &getNeuronKernelParameters() const{ return neuronKernelParameters; }


    unsigned int getNeuronGridSize() const;

    unsigned int getNumLocalNeurons() const;

    unsigned int getNumRemoteNeurons() const;

    unsigned int getNumNeurons() const{ return getNumLocalNeurons() + getNumRemoteNeurons(); }

    const NeuronGroup *findNeuronGroup(const std::string &name) const;

    NeuronGroup *findNeuronGroup(const std::string &name);

    NeuronGroup *addNeuronPopulation(const string&, unsigned int, unsigned int, const double *, const double *, int hostID = 0, int deviceID = 0); 
    NeuronGroup *addNeuronPopulation(const string&, unsigned int, unsigned int, const vector<double>&, const vector<double>&, int hostID = 0, int deviceID = 0); 


    template<typename NeuronModel>
    NeuronGroup *addNeuronPopulation(const string &name, unsigned int size, const NeuronModel *model,
                                     const typename NeuronModel::ParamValues &paramValues,
                                     const typename NeuronModel::VarValues &varInitialisers,
                                     int hostID = 0, int deviceID = 0)
    {
        if (!GeNNReady) {
            gennError("You need to call initGeNN first.");
        }
        if (final) {
            gennError("Trying to add a neuron population to a finalized model.");
        }

#ifdef MPI_ENABLE
        // Determine the host ID
        int mpiHostID = 0;
        MPI_Comm_rank(MPI_COMM_WORLD, &mpiHostID);

        // Pick map to add group to appropriately
        auto &groupMap = (hostID == mpiHostID) ? m_LocalNeuronGroups : m_RemoteNeuronGroups;
#else
        // If MPI is disabled always add to local neuron groups and zero host id
        auto &groupMap = m_LocalNeuronGroups;
        hostID = 0;
#endif

        // Add neuron group to map
        auto result = groupMap.emplace(std::piecewise_construct,
            std::forward_as_tuple(name),
            std::forward_as_tuple(name, size, model,
                                  paramValues.getValues(), varInitialisers.getInitialisers(), hostID, deviceID));

        if(!result.second)
        {
            gennError("Cannot add a neuron population with duplicate name:" + name);
            return NULL;
        }
        else
        {
            return &result.first->second;
        }
    }


    template<typename NeuronModel>
    NeuronGroup *addNeuronPopulation(const string &name, unsigned int size,
                                     const typename NeuronModel::ParamValues &paramValues, const typename NeuronModel::VarValues &varInitialisers,
                                     int hostID = 0, int deviceID = 0)
    {
        return addNeuronPopulation<NeuronModel>(name, size, NeuronModel::getInstance(), paramValues, varInitialisers, hostID, deviceID);
    }

    void setNeuronClusterIndex(const string &neuronGroup, int hostID, int deviceID); 

    void activateDirectInput(const string&, unsigned int type); 
    void setConstInp(const string&, double);

    // PUBLIC SYNAPSE FUNCTIONS
    //=========================
    const map<string, SynapseGroup> &getLocalSynapseGroups() const{ return m_LocalSynapseGroups; }

    const map<string, SynapseGroup> &getRemoteSynapseGroups() const{ return m_RemoteSynapseGroups; }

    const map<string, std::pair<unsigned int, unsigned int>> &getSynapsePostLearnGroups() const{ return m_SynapsePostLearnGroups; }

    const map<string, std::pair<unsigned int, unsigned int>> &getSynapseDynamicsGroups() const{ return m_SynapseDynamicsGroups; }

    const map<string, string> &getSynapseKernelParameters() const{ return synapseKernelParameters; }

    const map<string, string> &getSimLearnPostKernelParameters() const{ return simLearnPostKernelParameters; }

    const map<string, string> &getSynapseDynamicsKernelParameters() const{ return synapseDynamicsKernelParameters; }


    unsigned int getSynapseKernelGridSize() const;


    unsigned int getSynapsePostLearnGridSize() const;


    unsigned int getSynapseDynamicsGridSize() const;

    const SynapseGroup *findSynapseGroup(const std::string &name) const;

    SynapseGroup *findSynapseGroup(const std::string &name);    

    bool isSynapseGroupDynamicsRequired(const std::string &name) const;

    bool isSynapseGroupPostLearningRequired(const std::string &name) const;

    SynapseGroup *addSynapsePopulation(const string &name, unsigned int syntype, SynapseConnType conntype, SynapseGType gtype, const string& src, const string& trg, const double *p); 
    SynapseGroup *addSynapsePopulation(const string&, unsigned int, SynapseConnType, SynapseGType, unsigned int, unsigned int, const string&, const string&, const double *, const double *, const double *); 
    SynapseGroup *addSynapsePopulation(const string&, unsigned int, SynapseConnType, SynapseGType, unsigned int, unsigned int, const string&, const string&, const double *, const double *, const double *, const double *); 
    SynapseGroup *addSynapsePopulation(const string&, unsigned int, SynapseConnType, SynapseGType, unsigned int, unsigned int, const string&, const string&,
                              const vector<double>&, const vector<double>&, const vector<double>&, const vector<double>&); 


    template<typename WeightUpdateModel, typename PostsynapticModel>
    SynapseGroup *addSynapsePopulation(const string &name, SynapseMatrixType mtype, unsigned int delaySteps, const string& src, const string& trg,
                                       const WeightUpdateModel *wum, const typename WeightUpdateModel::ParamValues &weightParamValues, const typename WeightUpdateModel::VarValues &weightVarInitialisers, const typename WeightUpdateModel::PreVarValues &weightPreVarInitialisers, const typename WeightUpdateModel::PostVarValues &weightPostVarInitialisers,
                                       const PostsynapticModel *psm, const typename PostsynapticModel::ParamValues &postsynapticParamValues, const typename PostsynapticModel::VarValues &postsynapticVarInitialisers,
                                       const InitSparseConnectivitySnippet::Init &connectivityInitialiser = uninitialisedConnectivity())
    {
        if (!GeNNReady) {
            gennError("You need to call initGeNN first.");
        }
        if (final) {
            gennError("Trying to add a synapse population to a finalized model.");
        }

        // Get source and target neuron groups
        auto srcNeuronGrp = findNeuronGroup(src);
        auto trgNeuronGrp = findNeuronGroup(trg);

#ifdef MPI_ENABLE
        // Get host ID of target neuron group
        const int hostID = trgNeuronGrp->getClusterHostID();

        // Determine the host ID
        int mpiHostID = 0;
        MPI_Comm_rank(MPI_COMM_WORLD, &mpiHostID);

        // Pick map to add group to appropriately
        auto &groupMap = (hostID == mpiHostID) ? m_LocalSynapseGroups : m_RemoteSynapseGroups;
#else
        // If MPI is disabled always add to local synapse groups
        auto &groupMap = m_LocalSynapseGroups;
#endif

        // Add synapse group to map
        auto result = groupMap.emplace(
            std::piecewise_construct,
            std::forward_as_tuple(name),
            std::forward_as_tuple(name, mtype, delaySteps,
                                  wum, weightParamValues.getValues(), weightVarInitialisers.getInitialisers(), weightPreVarInitialisers.getInitialisers(), weightPostVarInitialisers.getInitialisers(),
                                  psm, postsynapticParamValues.getValues(), postsynapticVarInitialisers.getInitialisers(),
                                  srcNeuronGrp, trgNeuronGrp,
                                  connectivityInitialiser));

        if(!result.second)
        {
            gennError("Cannot add a synapse population with duplicate name:" + name);
            return NULL;
        }
        else
        {
            return &result.first->second;
        }
    }


    template<typename WeightUpdateModel, typename PostsynapticModel>
    SynapseGroup *addSynapsePopulation(const string &name, SynapseMatrixType mtype, unsigned int delaySteps, const string& src, const string& trg,
                                       const typename WeightUpdateModel::ParamValues &weightParamValues, const typename WeightUpdateModel::VarValues &weightVarInitialisers,
                                       const typename PostsynapticModel::ParamValues &postsynapticParamValues, const typename PostsynapticModel::VarValues &postsynapticVarInitialisers,
                                       const InitSparseConnectivitySnippet::Init &connectivityInitialiser = uninitialisedConnectivity())
    {
        // Create empty pre and postsynaptic weight update variable initialisers
        typename WeightUpdateModel::PreVarValues weightPreVarInitialisers;
        typename WeightUpdateModel::PostVarValues weightPostVarInitialisers;

        return addSynapsePopulation(name, mtype, delaySteps, src, trg,
                                    WeightUpdateModel::getInstance(), weightParamValues, weightVarInitialisers, weightPreVarInitialisers, weightPostVarInitialisers,
                                    PostsynapticModel::getInstance(), postsynapticParamValues, postsynapticVarInitialisers,
                                    connectivityInitialiser);
    }


    template<typename WeightUpdateModel, typename PostsynapticModel>
    SynapseGroup *addSynapsePopulation(const string &name, SynapseMatrixType mtype, unsigned int delaySteps, const string& src, const string& trg,
                                       const typename WeightUpdateModel::ParamValues &weightParamValues, const typename WeightUpdateModel::VarValues &weightVarInitialisers, const typename WeightUpdateModel::PreVarValues &weightPreVarInitialisers, const typename WeightUpdateModel::PostVarValues &weightPostVarInitialisers,
                                       const typename PostsynapticModel::ParamValues &postsynapticParamValues, const typename PostsynapticModel::VarValues &postsynapticVarInitialisers,
                                       const InitSparseConnectivitySnippet::Init &connectivityInitialiser = uninitialisedConnectivity())
    {
        return addSynapsePopulation(name, mtype, delaySteps, src, trg,
                                    WeightUpdateModel::getInstance(), weightParamValues, weightVarInitialisers, weightPreVarInitialisers, weightPostVarInitialisers,
                                    PostsynapticModel::getInstance(), postsynapticParamValues, postsynapticVarInitialisers,
                                    connectivityInitialiser);

    }

    void setSynapseG(const string&, double); 
    void setMaxConn(const string&, unsigned int); //< Set maximum connections per neuron for the given group (needed for optimization by sparse connectivity)
    void setSpanTypeToPre(const string&); 


    // PUBLIC CURRENT SOURCE FUNCTIONS
    //================================

    const map<string, CurrentSource> &getLocalCurrentSources() const{ return m_LocalCurrentSources; }

    const map<string, CurrentSource> &getRemoteCurrentSources() const{ return m_RemoteCurrentSources; }

    const map<string, string> &getCurrentSourceKernelParameters() const{ return currentSourceKernelParameters; }

    const CurrentSource *findCurrentSource(const std::string &name) const;

    CurrentSource *findCurrentSource(const std::string &name);


    template<typename CurrentSourceModel>
    CurrentSource *addCurrentSource(const string &currentSourceName, const CurrentSourceModel *model,
                                    const string &targetNeuronGroupName,
                                    const typename CurrentSourceModel::ParamValues &paramValues,
                                    const typename CurrentSourceModel::VarValues &varInitialisers)
    {
        if (!GeNNReady) {
            gennError("You need to call initGeNN first.");
        }
        if (final) {
            gennError("Trying to add a current source to a finalized model.");
        }
        auto targetGroup = findNeuronGroup(targetNeuronGroupName);

#ifdef MPI_ENABLE
        // Get host ID of target neuron group
        const int hostID = targetGroup->getClusterHostID();

        // Determine the host ID
        int mpiHostID = 0;
        MPI_Comm_rank(MPI_COMM_WORLD, &mpiHostID);

        // Pick map to add group to appropriately
        auto &groupMap = (hostID == mpiHostID) ? m_LocalCurrentSources : m_RemoteCurrentSources;
#else
        // If MPI is disabled always add to local current sources
        auto &groupMap = m_LocalCurrentSources;
#endif

        // Add current source to map
        auto result = groupMap.emplace(std::piecewise_construct,
            std::forward_as_tuple(currentSourceName),
            std::forward_as_tuple(currentSourceName, model,
                                  paramValues.getValues(), varInitialisers.getInitialisers()));

        if(!result.second)
        {
            gennError("Cannot add a current source with duplicate name:" + currentSourceName);
            return NULL;
        }
        else
        {
            targetGroup->injectCurrent(&result.first->second);
            return &result.first->second;
        }
    }


    template<typename CurrentSourceModel>
    CurrentSource *addCurrentSource(const string &currentSourceName, const string &targetNeuronGroupName,
                                    const typename CurrentSourceModel::ParamValues &paramValues,
                                    const typename CurrentSourceModel::VarValues &varInitialisers)
    {
        return addCurrentSource<CurrentSourceModel>(currentSourceName, CurrentSourceModel::getInstance(),
                                targetNeuronGroupName, paramValues, varInitialisers);
    }


private:
    //--------------------------------------------------------------------------
    // Private members
    //--------------------------------------------------------------------------
    map<string, NeuronGroup> m_LocalNeuronGroups;

    map<string, NeuronGroup> m_RemoteNeuronGroups;

    map<string, SynapseGroup> m_LocalSynapseGroups;

    map<string, SynapseGroup> m_RemoteSynapseGroups;

    map<string, CurrentSource> m_LocalCurrentSources;

    map<string, CurrentSource> m_RemoteCurrentSources;

    map<string, std::pair<unsigned int, unsigned int>> m_SynapsePostLearnGroups;

    map<string, std::pair<unsigned int, unsigned int>> m_SynapseDynamicsGroups;

    // Kernel members
    map<string, string> m_InitKernelParameters;
    map<string, string> neuronKernelParameters;
    map<string, string> synapseKernelParameters;
    map<string, string> simLearnPostKernelParameters;
    map<string, string> synapseDynamicsKernelParameters;
    map<string, string> currentSourceKernelParameters;

     // Model members
    string name;                    
    string ftype;                   
    TimePrecision m_TimePrecision;  
    string RNtype;                  
    double dt;                      
    bool final;                     
    bool timing;
    unsigned int seed;
    unsigned int resetKernel;       
};

#endif