customUpdate.h

Go to the documentation of this file.

#pragma once

// Standard includes
#include <string>
#include <vector>

// GeNN includes
#include "gennExport.h"
#include "gennUtils.h"
#include "customUpdateModels.h"
#include "variableMode.h"

//------------------------------------------------------------------------
// CustomUpdateBase
//------------------------------------------------------------------------
class GENN_EXPORT CustomUpdateBase
{
public:
    CustomUpdateBase(const CustomUpdateBase &) = delete;
    CustomUpdateBase() = delete;

    //------------------------------------------------------------------------
    // Public methods
    //------------------------------------------------------------------------

    void setVarLocation(const std::string &varName, VarLocation loc);

    //------------------------------------------------------------------------
    // Public const methods
    //------------------------------------------------------------------------
    const std::string &getName() const{ return m_Name; }
    const std::string &getUpdateGroupName() const { return m_UpdateGroupName; }

    const CustomUpdateModels::Base *getCustomUpdateModel() const{ return m_CustomUpdateModel; }

    const std::vector<double> &getParams() const{ return m_Params; }
    const std::vector<Models::VarInit> &getVarInitialisers() const{ return m_VarInitialisers; }

    const std::vector<Models::EGPReference> &getEGPReferences() const{ return m_EGPReferences;  }

    VarLocation getVarLocation(const std::string &varName) const;

    VarLocation getVarLocation(size_t index) const{ return m_VarLocation.at(index); }

    bool isVarInitRequired() const;

protected:
    CustomUpdateBase(const std::string &name, const std::string &updateGroupName,
                     const CustomUpdateModels::Base *customUpdateModel, const std::vector<double> &params,
                     const std::vector<Models::VarInit> &varInitialisers, const std::vector<Models::EGPReference> &egpReferences,
                     VarLocation defaultVarLocation, VarLocation defaultExtraGlobalParamLocation);

    //------------------------------------------------------------------------
    // Protected methods
    //------------------------------------------------------------------------
    void initDerivedParams(double dt);

    //------------------------------------------------------------------------
    // Protected const methods
    //------------------------------------------------------------------------
    const std::vector<double> &getDerivedParams() const{ return m_DerivedParams; }

    bool isInitRNGRequired() const;

    bool isZeroCopyEnabled() const;

    bool isBatched() const { return m_Batched; }


    void updateHash(boost::uuids::detail::sha1 &hash) const;


    void updateInitHash(boost::uuids::detail::sha1 &hash) const;

    boost::uuids::detail::sha1::digest_type getVarLocationHashDigest() const;

    template<typename V>
    bool isReduction(const std::vector<V> &varRefs, VarAccessDuplication duplication) const
    {
        // Return true if any variables have REDUCE flag in their access mode and have correct duplication flag
        const auto vars = getCustomUpdateModel()->getVars();
        if(std::any_of(vars.cbegin(), vars.cend(),
                       [duplication](const Models::Base::Var &v)
                       { 
                           return (v.access & VarAccessModeAttribute::REDUCE) && (v.access & duplication);
                       }))
        {
            return true;
        }

        // Loop through all variable references
        const auto modelVarRefs = getCustomUpdateModel()->getVarRefs();
        for (size_t i = 0; i < varRefs.size(); i++) {
            const auto varRef = varRefs.at(i);
            const auto modelVarRef = modelVarRefs.at(i);

            // If custom update model reduces into this variable reference and the variable it targets has correct duplication flag
            if ((modelVarRef.access & VarAccessModeAttribute::REDUCE) & (varRef.getVar().access & duplication)) {
                return true;
            }
        }

        return false;
    }

    template<typename V>
    void checkVarReferences(const std::vector<V> &varRefs)
    {
        // Loop through all variable references
        const auto modelVarRefs = getCustomUpdateModel()->getVarRefs();
        for(size_t i = 0; i < varRefs.size(); i++) {
            const auto varRef = varRefs.at(i);
            const auto modelVarRef = modelVarRefs.at(i);

            // Check types of variable references against those specified in model
            // **THINK** due to GeNN's current string-based type system this is rather conservative
            if(varRef.getVar().type != modelVarRef.type) {
                throw std::runtime_error("Incompatible type for variable reference '" + modelVarRef.name + "'");
            }

            // Check that no reduction targets reference duplicated variables
            if((varRef.getVar().access & VarAccessDuplication::DUPLICATE) 
                && (modelVarRef.access & VarAccessModeAttribute::REDUCE))
            {
                throw std::runtime_error("Reduction target variable reference must be to SHARED or SHARED_NEURON variables.");
            }
        }
    }

    template<typename V>
    void checkVarReferenceBatching(const std::vector<V>& varRefs, unsigned int batchSize)
    {
        // If target of any variable references is not shared across batches, custom update should be batched
        if(batchSize > 1) {
            m_Batched = std::any_of(varRefs.cbegin(), varRefs.cend(),
                                    [](const V& v) 
                                    {
                                        return (v.isBatched() && !(v.getVar().access & VarAccessDuplication::SHARED)); 
                                    });
        }
        else {
            m_Batched = false;
        }

        // Loop through all variable references
        const auto modelVarRefs = getCustomUpdateModel()->getVarRefs();
        for (size_t i = 0; i < varRefs.size(); i++) {
            const auto varRef = varRefs.at(i);
            const auto modelVarRef = modelVarRefs.at(i);

            // If custom update is batched, check that any variable references to shared variables are read-only
            // **NOTE** if custom update isn't batched, it's totally fine to write to shared variables
            if(m_Batched && (varRef.getVar().access & VarAccessDuplication::SHARED)
               && (modelVarRef.access == VarAccessMode::READ_WRITE))
            {
                throw std::runtime_error("Variable references to SHARED variables in batched custom updates cannot be read-write.");
            }
        }
    }

private:
    //------------------------------------------------------------------------
    // Members
    //------------------------------------------------------------------------
    const std::string m_Name;
    const std::string m_UpdateGroupName;

    const CustomUpdateModels::Base *m_CustomUpdateModel;
    const std::vector<double> m_Params;
    std::vector<double> m_DerivedParams;
    std::vector<Models::VarInit> m_VarInitialisers;

    std::vector<Models::EGPReference> m_EGPReferences;

    std::vector<VarLocation> m_VarLocation;

    std::vector<VarLocation> m_ExtraGlobalParamLocation;

    bool m_Batched;
};

//------------------------------------------------------------------------
// CustomUpdate
//------------------------------------------------------------------------
class GENN_EXPORT CustomUpdate : public CustomUpdateBase
{
public:
    //------------------------------------------------------------------------
    // Public const methods
    //------------------------------------------------------------------------
    const std::vector<Models::VarReference> &getVarReferences() const{ return m_VarReferences;  }
    unsigned int getSize() const { return m_Size; }

protected:
    CustomUpdate(const std::string &name, const std::string &updateGroupName,
                 const CustomUpdateModels::Base *customUpdateModel, const std::vector<double> &params,
                 const std::vector<Models::VarInit> &varInitialisers, const std::vector<Models::VarReference> &varReferences,
                 const std::vector<Models::EGPReference> &egpReferences, VarLocation defaultVarLocation, 
                 VarLocation defaultExtraGlobalParamLocation);

    //------------------------------------------------------------------------
    // Protected methods
    //------------------------------------------------------------------------
    void finalize(unsigned int batchSize);

    //------------------------------------------------------------------------
    // Protected const methods
    //------------------------------------------------------------------------
    bool isBatchReduction() const { return isReduction(getVarReferences(), VarAccessDuplication::SHARED); }
    bool isNeuronReduction() const { return isReduction(getVarReferences(), VarAccessDuplication::SHARED_NEURON); }
    bool isPerNeuron() const{ return m_PerNeuron; }


    boost::uuids::detail::sha1::digest_type getHashDigest() const;


    boost::uuids::detail::sha1::digest_type getInitHashDigest() const;

    const NeuronGroup *getDelayNeuronGroup() const { return m_DelayNeuronGroup; }

private:
    //------------------------------------------------------------------------
    // Members
    //------------------------------------------------------------------------
    const std::vector<Models::VarReference> m_VarReferences;
    const unsigned int m_Size;
    const NeuronGroup *m_DelayNeuronGroup;

    bool m_PerNeuron;
};

//------------------------------------------------------------------------
// CustomUpdateWU
//------------------------------------------------------------------------
class GENN_EXPORT CustomUpdateWU : public CustomUpdateBase
{
public:
    //------------------------------------------------------------------------
    // Public const methods
    //------------------------------------------------------------------------
    const std::vector<Models::WUVarReference> &getVarReferences() const{ return m_VarReferences;  }

protected:
    CustomUpdateWU(const std::string &name, const std::string &updateGroupName,
                   const CustomUpdateModels::Base *customUpdateModel, const std::vector<double> &params,
                   const std::vector<Models::VarInit> &varInitialisers, const std::vector<Models::WUVarReference> &varReferences,
                   const std::vector<Models::EGPReference> &egpReferences, VarLocation defaultVarLocation, 
                   VarLocation defaultExtraGlobalParamLocation);

    //------------------------------------------------------------------------
    // Protected methods
    //------------------------------------------------------------------------
    void finalize(unsigned int batchSize);

    //------------------------------------------------------------------------
    // Protected const methods
    //------------------------------------------------------------------------
    bool isBatchReduction() const { return isReduction(getVarReferences(), VarAccessDuplication::SHARED); }
    bool isTransposeOperation() const;

    const SynapseGroupInternal *getSynapseGroup() const { return m_SynapseGroup; }


    boost::uuids::detail::sha1::digest_type getHashDigest() const;


    boost::uuids::detail::sha1::digest_type getInitHashDigest() const;

private:
    //------------------------------------------------------------------------
    // Members
    //------------------------------------------------------------------------
    const std::vector<Models::WUVarReference> m_VarReferences;
    const SynapseGroupInternal *m_SynapseGroup;
};