carlsim.h

Go to the documentation of this file.

/*
 * Copyright (c) 2014 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>
 *
 * CARLsim available from http://socsci.uci.edu/~jkrichma/CARLsim/
 * Ver 5/6/2015
 */

#ifndef _CARLSIM_H_
#define _CARLSIM_H_

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

#include <callback.h>
#include <carlsim_definitions.h>
#include <carlsim_log_definitions.h>
#include <carlsim_datastructures.h>

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

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

    #include <algorithm>
    #define fmin (std::min)
    #define fmax (std::max)

    #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

    #ifdef _MSC_VER
    #define INFINITY (DBL_MAX+DBL_MAX)
    #define NAN (INFINITY-INFINITY)
    #endif
#else
    #include <interactive_spikegen.h>
    #include <pre_post_group_spikegen.h>
    #include <periodic_spikegen.h>
    #include <spikegen_from_file.h>
    #include <spikegen_from_vector.h>
    #include <simple_weight_tuner.h>
    #include <visual_stimulus.h>
    #include <stopwatch.h>

    #include <pthread.h>
#endif

// \TODO: complete documentation


class CpuSNN; // forward-declaration of implementation
class GroupMonitorCore;
class ConnectionMonitorCore;
class ConnectionGeneratorCore;
class SpikeGeneratorCore;

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

    CARLsim(const std::string& netName="SNN", simMode_t simMode=CPU_MODE, loggerMode_t loggerMode=USER, int ithGPU=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), 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, int maxM=0,
                        int maxPreM=0);

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


    short int connectCompartments(int grpIdLower, int grpIdUpper);

    int createGroup(const std::string& grpName, int nNeur, int neurType);

    int createGroup(const std::string& grpName, const Grid3D& grid, int neurType);

    int createSpikeGeneratorGroup(const std::string& grpName, int nNeur, int neurType);

    int createSpikeGeneratorGroup(const std::string& grpName, const Grid3D& grid, int neurType);


    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);

    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 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);

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

    void setSTDP(int grpId, bool isSet);

    void setSTDP(int grpId, bool isSet, stdpType_t type, float alphaPlus, float tauPlus, float alphaMinus, float tauMinus);

    void setESTDP(int grpId, bool isSet);

    void setESTDP(int grpId, bool isSet, stdpType_t type, ExpCurve curve);

    void setESTDP(int grpId, bool isSet, stdpType_t type, TimingBasedCurve curve);

    void setISTDP(int grpId, bool isSet);

    void setISTDP(int grpId, bool isSet, stdpType_t type, ExpCurve curve);

    void setISTDP(int grpId, bool isSet, stdpType_t 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);

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


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

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

    void setupNetwork(bool removeTempMemory = true);

    // +++++ 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);

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

    void setSpikeGenerator(int grpId, SpikeGenerator* spikeGen);

    SpikeMonitor* setSpikeMonitor(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_t getCARLsimState() { return carlsimState_; }

    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, uint8_t* delays=NULL);

    Grid3D getGroupGrid3D(int grpId);

    int getGroupId(std::string grpName);

    std::string getGroupName(int grpId);

    Point3D getNeuronLocation3D(int neurId);

    Point3D getNeuronLocation3D(int grpId, int relNeurId);

    int getMaxNumCompConnections();

    int getNumConnections();

    int getNumSynapticConnections(short int connectionId);

    int getNumGroups();

    int getNumNeurons();

    int getNumNeuronsReg();

    int getNumNeuronsRegExc();

    int getNumNeuronsRegInh();

    int getNumNeuronsGen();

    int getNumNeuronsGenExc();

    int getNumNeuronsGenInh();

    int getNumPreSynapses();

    int getNumPostSynapses();

    int getGroupStartNeuronId(int grpId);

    int getGroupEndNeuronId(int grpId);

    int getGroupNumNeurons(int grpId);

    GroupSTDPInfo_t getGroupSTDPInfo(int grpId);

    GroupNeuromodulatorInfo_t getGroupNeuromodulatorInfo(int grpId);

    simMode_t getSimMode();

    uint64_t getSimTime();

    uint32_t getSimTimeSec();

    uint32_t getSimTimeMsec();

    int* getSpikeCounter(int grpId);

    SpikeMonitor* getSpikeMonitor(int grpId);

    RangeWeight getWeightRange(short int connId);

    bool isConnectionPlastic(short int connId);

    bool isGroupWithHomeostasis(int grpId);

    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_t stdpType);

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

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

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


private:
    // +++++ PRIVATE METHODS ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ //

    void CARLsimInit();                 

    bool existsGrpId(int grpId);        

    void handleUserWarnings();          

    void printSimulationSpecs();

    // +++++ PRIVATE STATIC PROPERTIES ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ //
    static bool gpuAllocation[MAX_NUM_CUDA_DEVICES];
    static std::string gpuOccupiedBy[MAX_NUM_CUDA_DEVICES];
#if defined(WIN32) || defined(WIN64)
    static HANDLE gpuAllocationLock;
#else
    static pthread_mutex_t gpuAllocationLock;
#endif
    // +++++ PRIVATE PROPERTIES +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ //

    CpuSNN* snn_;                   
    std::string netName_;           
    int randSeed_;                  
    simMode_t simMode_;             
    loggerMode_t loggerMode_;       
    int ithGPU_;                    
    bool enablePrint_;
    bool copyState_;

    std::vector<std::vector<int> > connSyn_;

    std::vector<std::vector<int> > connComp_;

    unsigned int numConnections_;   
    std::vector<std::string> userWarnings_; // !< an accumulated list of user warnings

    std::vector<int> grpIds_;       
    std::vector<bool> grpNeurParams_; 
    std::vector<SpikeGeneratorCore*> spkGen_; 
    std::vector<ConnectionGeneratorCore*> connGen_; 

    bool hasSetHomeoALL_;           
    bool hasSetHomeoBaseFiringALL_; 
    bool hasSetSTDPALL_;            
    bool hasSetSTPALL_;             
    bool hasSetConductances_;       
    carlsimState_t carlsimState_;   

    int def_tdAMPA_;                
    int def_trNMDA_;                
    int def_tdNMDA_;                
    int def_tdGABAa_;               
    int def_trGABAb_;               
    int def_tdGABAb_;               

    // all default values for STDP
    stdpType_t def_STDP_type_;      
    float def_STDP_alphaLTP_;       
    float def_STDP_tauLTP_;         
    float def_STDP_alphaLTD_;       
    float def_STDP_tauLTD_;         
    float def_STDP_betaLTP_;        
    float def_STDP_betaLTD_;        
    float def_STDP_lambda_;         
    float def_STDP_delta_;          

    // all default values for STP
    float def_STP_U_exc_;           
    float def_STP_tau_u_exc_;       
    float def_STP_tau_x_exc_;       
    float def_STP_U_inh_;           
    float def_STP_tau_u_inh_;       
    float def_STP_tau_x_inh_;       

    // all default values for homeostasis
    float def_homeo_scale_;         
    float def_homeo_avgTimeScale_;  

    // all default values for save file
    std::string def_save_fileName_; 
    bool def_save_synapseInfo_;     
};
#endif