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 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
 
 
 
class 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);
 
    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);
 
    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 type, float alphaPlus, float tauPlus, float alphaMinus, float tauMinus);
 
    void setESTDP(int grpId, bool isSet);
 
    void setESTDP(int grpId, bool isSet, STDPType type, ExpCurve curve);
 
    void setESTDP(int grpId, bool isSet, STDPType type, TimingBasedCurve curve);
 
    void setISTDP(int grpId, bool isSet);
 
    void setISTDP(int grpId, bool isSet, STDPType type, ExpCurve curve);
 
    void setISTDP(int grpId, 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);
 
    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();
 
    // +++++ 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* 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();
 
    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 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);
 
    GroupSTDPInfo getGroupSTDPInfo(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 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);
 
 
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