carlsim.h

Go to the documentation of this file.

/* * Copyright (c) 2016 Regents of the University of California. All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
*    notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
*    notice, this list of conditions and the following disclaimer in the
*    documentation and/or other materials provided with the distribution.
*
* 3. The names of its contributors may not be used to endorse or promote
*    products derived from this software without specific prior written
*    permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*
* *********************************************************************************************** *
* CARLsim
* created by: (MDR) Micah Richert, (JN) Jayram M. Nageswaran
* maintained by:
* (MA) Mike Avery <averym@uci.edu>
* (MB) Michael Beyeler <mbeyeler@uci.edu>,
* (KDC) Kristofor Carlson <kdcarlso@uci.edu>
* (TSC) Ting-Shuo Chou <tingshuc@uci.edu>
* (HK) Hirak J Kashyap <kashyaph@uci.edu>
*
* CARLsim v1.0: JM, MDR
* CARLsim v2.0/v2.1/v2.2: JM, MDR, MA, MB, KDC
* CARLsim3: MB, KDC, TSC
* CARLsim4: TSC, HK
* CARLsim5: HK, JX, KC
*
* CARLsim available from http://socsci.uci.edu/~jkrichma/CARLsim/
* Ver 12/31/2016
*/

#ifndef _CARLSIM_H_
#define _CARLSIM_H_

#include <stdint.h>     // uint64_t, uint32_t, etc.
#include <string>       // std::string
#include <vector>       // std::vector
#include <algorithm>

#include <carlsim_definitions.h>
#include <carlsim_datastructures.h>
#include <carlsim_api.h>

// include the following core functionalities instead of forward-declaring, so that the user only needs to include
// carlsim.h
#include <callback.h>
#include <poisson_rate.h>
#include <spike_monitor.h>
#include <neuron_monitor.h>
#include <connection_monitor.h>
#include <group_monitor.h>
#include <linear_algebra.h>

class GroupMonitor;
class ConnectionMonitor;
class SpikeMonitor;
class SpikeGenerator;



// Cross-platform definition (Linux, Windows)
#if defined(WIN32) || defined(WIN64)
#include <Windows.h>

#include <float.h>
#include <time.h>

//#ifndef isnan
//#define isnan(x) _isnan(x)
//#endif
//
//#ifndef isinf
//#define isinf(x) (!_finite(x))
//#endif
#ifndef srand48
#define srand48(x) srand(x)
#endif

#ifndef drand48
#define drand48() (double(rand())/RAND_MAX)
#endif

#else

#include <pthread.h> // pthread
#include <sys/stat.h> // mkdir
#include <unistd.h> //unix thread affinity macros

#endif

//set by cMake option CARLSIM_LN_FIRING
//{ LN feat for CARLsim6
//#define LN_GET_FIRING
//#define LN_GET_FIRING_MT
//}


class CARLSIM_API CARLsim {
public:
    // +++++ PUBLIC METHODS: CONSTRUCTOR / DESTRUCTOR +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ //

    CARLsim(const std::string& netName = "SNN", SimMode preferredSimMode = CPU_MODE, LoggerMode loggerMode = USER, int ithGPUs = 0, int randSeed = -1);
    ~CARLsim();



    // +++++ PUBLIC METHODS: SETTING UP A SIMULATION ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ //

    short int connect(int grpId1, int grpId2, const std::string& connType, const RangeWeight& wt, float connProb,
        const RangeDelay& delay=RangeDelay(1), const RadiusRF& radRF=RadiusRF(-1.0), bool synWtType=SYN_FIXED,
        float mulSynFast=1.0f, float mulSynSlow=1.0f);

    short int connect(int grpId1, int grpId2, ConnectionGenerator* conn, bool synWtType=SYN_FIXED);

    short int connect(int grpId1, int grpId2, ConnectionGenerator* conn, float mulSynFast, float mulSynSlow,
                        bool synWtType=SYN_FIXED);

    short int connectCompartments(int grpIdLower, int grpIdUpper);


    int createGroup(const std::string& grpName, int nNeur, int neurType, int preferredPartition = ANY, ComputingBackend preferredBackend = CPU_CORES);

    int createGroupLIF(const std::string& grpName, int nNeur, int neurType, int preferredPartition = ANY, ComputingBackend preferredBackend = CPU_CORES);

    int createGroup(const std::string& grpName, const Grid3D& grid, int neurType, int preferredPartition = ANY, ComputingBackend preferredBackend = CPU_CORES);

    int createGroupLIF(const std::string& grpName, const Grid3D& grid, int neurType, int preferredPartition = ANY, ComputingBackend preferredBackend = CPU_CORES);

    int createSpikeGeneratorGroup(const std::string& grpName, int nNeur, int neurType, int preferredPartition = ANY, ComputingBackend preferredBackend = CPU_CORES);

    int createSpikeGeneratorGroup(const std::string& grpName, const Grid3D& grid, int neurType, int preferredPartition = ANY, ComputingBackend preferredBackend = CPU_CORES);


    void setConductances(bool isSet);

    void setConductances(bool isSet, int tdAMPA, int tdNMDA, int tdGABAa, int tdGABAb);

    void setConductances(bool isSet, int tdAMPA, int trNMDA, int tdNMDA, int tdGABAa, int trGABAb, int tdGABAb);

#ifdef LN_I_CALC_TYPES

    void setConductances(int grpId, bool isSet);

    void setConductances(int grpId, bool isSet, int tdAMPA, int tdNMDA, int tdGABAa, int tdGABAb);

     void setConductances(int grpId, bool isSet, int tdAMPA, int trNMDA, int tdNMDA, int tdGABAa, int trGABAb, int tdGABAb);


     void setACNE12(int grpId);

    
    void setNM4weighted(int grpId, IcalcType type, float wDA=1.f, float w5HT=1.f, float wACh=1.f, float wNE=1.f, float wNorm=4.f, float wBase=1.0f);

#endif

    void setHomeostasis(int grpId, bool isSet, float homeoScale, float avgTimeScale);

    void setHomeostasis(int grpId, bool isSet);

    void setHomeoBaseFiringRate(int grpId, float baseFiring, float baseFiringSD=0.0f);

    /*
    * \brief Sets the integration method for the simulation
    *
    * This function specifies the integration method for the simulation. Currently, the chosen integration method
    * will apply to all neurons in the network.
    *
    * The basic simulation time step is 1ms, meaning that spike times cannot be retrieved with sub-millisecond
    * precision. However, the integration time step can be lower than 1ms, which is specified by numStepsPerMs.
    * A numStepsPerMs set to 10 would take 10 integration steps per 1ms simulation time step.
    *
    * By default, the simulation will use Forward-Euler with an integration step of 0.5ms (i.e.,
    * <tt>numStepsPerMs</tt>=2).
    *
    * Currently CARLsim supports the following integration methods:
    * - FORWARD_EULER: The most basic, forward-Euler method. Suggested value for <tt>numStepsPerMs</tt>: >= 2.
    * - RUNGE_KUTTA4:  Fourth-order Runge-Kutta (aka classical Runge-Kutta, aka RK4).
    *                  Suggested value for <tt>numStepsPerMs</tt>: >= 10.
    *
    * \STATE ::CONFIG_STATE
    * \param[in] method the integration method to use
    * \param[in] numStepsPerMs the number of integration steps per 1ms simulation time step
    *
    * \note Note that the higher numStepsPerMs the slower the simulation may be, due to increased computational load.
    * \since v3.1
    */
    void setIntegrationMethod(integrationMethod_t method, int numStepsPerMs);

    void setNeuronParameters(int grpId, float izh_a, float izh_a_sd, float izh_b, float izh_b_sd,
                             float izh_c, float izh_c_sd, float izh_d, float izh_d_sd);

    void setNeuronParameters(int grpId, float izh_a, float izh_b, float izh_c, float izh_d);

    void setNeuronParameters(int grpId, float izh_C, float izh_k, float izh_vr, float izh_vt,
        float izh_a, float izh_b, float izh_vpeak, float izh_c, float izh_d);

    void setNeuronParameters(int grpId, float izh_C, float izh_C_sd, float izh_k, float izh_k_sd,
        float izh_vr, float izh_vr_sd, float izh_vt, float izh_vt_sd,
        float izh_a, float izh_a_sd, float izh_b, float izh_b_sd,
        float izh_vpeak, float izh_vpeak_sd, float izh_c, float izh_c_sd,
        float izh_d, float izh_d_sd);

    void setNeuronParametersLIF(int grpId, int tau_m, int tau_ref=0, float vTh=1.0f, float vReset=0.0f, const RangeRmem& rMem = RangeRmem(1.0f));
    
    void setCompartmentParameters(int grpId, float couplingUp, float couplingDown);

    void setNeuromodulator(int grpId, float baseDP, float tauDP, float base5HT, float tau5HT,
                            float baseACh, float tauACh, float baseNE, float tauNE);

    // new 
    void setNeuromodulator(int grpId,
        float baseDP, float tauDP, float releaseDP, bool activeDP,
        float base5HT, float tau5HT, float release5HT, bool active5HT,
        float baseACh, float tauACh, float releaseAch, bool activeACh,
        float baseNE, float tauNE, float releaseNE, bool activeNE);

    void setNeuromodulator(int grpId, float tauDP = 100.0f, float tau5HT = 100.0f,
                            float tauACh = 100.0f, float tauNE = 100.0f);

    void setSTDP(int preGrpId, int postGrpId, bool isSet);

    void setSTDP(int preGrpId, int postGrpId, bool isSet, STDPType type, float alphaPlus, float tauPlus, float alphaMinus, float tauMinus);

    void setESTDP(int preGrpId, int postGrpId, bool isSet);

    void setESTDP(int preGrpId, int postGrpId, bool isSet, STDPType type, ExpCurve curve);

#ifdef LN_I_CALC_TYPES

    void setESTDP(int preGrpId, int postGrpId, bool isSet, STDPType type, ExpCurve curve, PkaPlcModulation modulation);

    void setConnectionModulation(int preGrpId, int postGrpId, IcalcType icalcType);

#endif


    void setESTDP(int preGrpId, int postGrpId, bool isSet, STDPType type, TimingBasedCurve curve);


    void setISTDP(int preGrpId, int postGrpId, bool isSet);

    void setISTDP(int preGrpId, int postGrpId, bool isSet, STDPType type, ExpCurve curve);

    void setISTDP(int preGrpId, int postGrpId, bool isSet, STDPType type, PulseCurve curve);

    void setSTP(int grpId, bool isSet, float STP_U, float STP_tau_u, float STP_tau_x);

    void setSTP(int grpId, bool isSet);

#ifdef LN_I_CALC_TYPES

    void setNM4STP(int grpId, float wSTP_U[], float wSTP_tau_u[], float wSTP_tau_x[]);
#endif

    void setWeightAndWeightChangeUpdate(UpdateInterval wtANDwtChangeUpdateInterval, bool enableWtChangeDecay, float wtChangeDecay=0.9f);


    // +++++ PUBLIC METHODS: RUNNING A SIMULATION ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ //

    int runNetwork(int nSec, int nMsec=0, bool printRunSummary=true);

    void setupNetwork();

    void setupNetworkMT();

    // +++++ PUBLIC METHODS: LOGGING / PLOTTING +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ //

    const FILE* getLogFpInf();  
    const FILE* getLogFpErr();  
    const FILE* getLogFpDeb();  
    const FILE* getLogFpLog();  

    void saveSimulation(const std::string& fileName, bool saveSynapseInfo=true);

    void setLogFile(const std::string& fileName);

    void setLogsFpCustom(FILE* fpInf=NULL, FILE* fpErr=NULL, FILE* fpDeb=NULL, FILE* fpLog=NULL);



    // +++++ PUBLIC METHODS: INTERACTING WITH A SIMULATION ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ //

    void biasWeights(short int connId, float bias, bool updateWeightRange=false);

    void loadSimulation(FILE* fid);

    //void resetSpikeCounter(int grpId);

    void scaleWeights(short int connId, float scale, bool updateWeightRange=false);

    ConnectionMonitor* setConnectionMonitor(int grpIdPre, int grpIdPost, const std::string& fname);

    void setExternalCurrent(int grpId, const std::vector<float>& current);

    void setExternalCurrent(int grpId, float current);

     GroupMonitor* setGroupMonitor(int grpId, const std::string& fname, int mode=0); 

    //void setSpikeCounter(int grpId, int recordDur=-1);

    void setSpikeGenerator(int grpId, SpikeGenerator* spikeGenFunc);

    SpikeMonitor* setSpikeMonitor(int grpId, const std::string& fileName);

    NeuronMonitor* setNeuronMonitor(int grpId, const std::string& fileName);

    void setSpikeRate(int grpId, PoissonRate* spikeRate, int refPeriod=1);

    void setWeight(short int connId, int neurIdPre, int neurIdPost, float weight, bool updateWeightRange=false);

    void startTesting(bool updateWeights=true);

    void stopTesting();

    //void writePopWeights(std::string fname, int gIDpre, int gIDpost);



    // +++++ PUBLIC METHODS: GETTERS / SETTERS +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ //

    CARLsimState getCARLsimState();


#ifdef LN_GET_FIRING

     void getFiring(std::vector<bool>& firing, int netId=-1);
#endif

#ifdef LN_GET_FIRING_MT
     void getFiringMT(std::vector<bool>& firing, int netId);
#endif

#ifdef LN_AXON_PLAST

     void findWavefrontPath(std::vector<int>& path, std::vector<float>& eligibility, int netId, int grpId, int startNId, int goalNId);

     bool updateDelays(int gGrpIdPre, int gGrpIdPost, std::vector<std::tuple<int, int, uint8_t>> connDelays);


     void printEntrails(char* buffer, unsigned length, int gGrpIdPre, int gGrpIdPost);

#endif


    std::vector<float> getConductanceAMPA(int grpId);

    std::vector<float> getConductanceNMDA(int grpId);

    std::vector<float> getConductanceGABAa(int grpId);

    std::vector<float> getConductanceGABAb(int grpId);

    RangeDelay getDelayRange(short int connId);

    uint8_t* getDelays(int gIDpre, int gIDpost, int& Npre, int& Npost);

    // FIXME: This function is called in SNN::connect() at CONFIG_STATE, which violate the restriction
    Grid3D getGroupGrid3D(int grpId);

    int getGroupId(std::string grpName);

    std::string getGroupName(int grpId);

    Point3D getNeuronLocation3D(int neurId);

    int getMaxNumCompConnections();

    Point3D getNeuronLocation3D(int grpId, int relNeurId);

    int getNeuronId(int grpId, Point3D location);



    int getNumConnections();

    int getNumSynapticConnections(short int connectionId);

    int getNumGroups();

    int getNumNeurons();

    int getNumNeuronsReg();

    int getNumNeuronsRegExc();

    int getNumNeuronsRegInh();

    int getNumNeuronsGen();

    int getNumNeuronsGenExc();

    int getNumNeuronsGenInh();

    int getNumSynapses();

    int getGroupStartNeuronId(int grpId);

    int getGroupEndNeuronId(int grpId);

    int getGroupNumNeurons(int grpId);

    ConnSTDPInfo getConnSTDPInfo(int grpId);

    GroupNeuromodulatorInfo getGroupNeuromodulatorInfo(int grpId);

    int getSimTime();

    int getSimTimeSec();

    int getSimTimeMsec();

    //int* getSpikeCounter(int grpId);

    SpikeMonitor* getSpikeMonitor(int grpId);

    RangeWeight getWeightRange(short int connId);

    bool isConnectionPlastic(short int connId);

    bool isGroupWithHomeostasis(int grpId);



    bool isSimulationWithCOBA();

    bool isSimulationWithCUBA();

#ifdef LN_I_CALC_TYPES

    bool isGroupWith(int grpId, IcalcType icalcType);

    bool isGroupWithCOBA(int grpId);

    bool isGroupWithCUBA(int grpId);


    IcalcType getIcalcType(int grpId);

    bool getConductanceConfig(int grpId, float& dAMPA, float& rNMDA, float& dNMDA, float& dGABAa, float& rGABAb, float& dGABAb);

    bool getConductanceConfig(int grpId, int& tdAMPA, int& trNMDA, int& tdNMDA, int& tdGABAa, int& trGABAb, int& tdGABAb);

#endif

    bool isExcitatoryGroup(int grpId);

    bool isInhibitoryGroup(int grpId);

    bool isPoissonGroup(int grpId);

    // +++++ PUBLIC METHODS: SET DEFAULTS +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ //

    void setDefaultConductanceTimeConstants(int tdAMPA, int trNMDA, int tdNMDA, int tdGABAa, int trGABAb, int tdGABAb);

    void setDefaultHomeostasisParams(float homeoScale, float avgTimeScale);

    void setDefaultSaveOptions(std::string fileName, bool saveSynapseInfo);

    void setDefaultSTDPparams(float alphaPlus, float tauPlus, float alphaMinus, float tauMinus, STDPType stdpType);

    void setDefaultESTDPparams(float alphaPlus, float tauPlus, float alphaMinus, float tauMinus, STDPType stdpType);

    void setDefaultISTDPparams(float betaLTP, float betaLTD, float lambda, float delta, STDPType stdpType);

    void setDefaultSTPparams(int neurType, float STP_U, float STP_tau_u, float STP_tau_x);


    static int cudaDeviceCount();

    static void cudaDeviceDescription(unsigned ithGPU, const char **desc);
        


private:
    // This class provides a pImpl for the CARLsim User API.
    // \see https://marcmutz.wordpress.com/translated-articles/pimp-my-pimpl/
    class Impl;
    Impl* _impl;
};
#endif