carlsim_datastructures.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
* CARLsim6: LN, JX, KC, KW
*
* CARLsim available from http://socsci.uci.edu/~jkrichma/CARLsim/
* Ver 12/31/2016
*/

#ifndef _CARLSIM_DATASTRUCTURES_H_
#define _CARLSIM_DATASTRUCTURES_H_

#include <ostream>          // print struct info
#include <user_errors.h>    // CARLsim user errors

enum LoggerMode {
     USER,            
     DEVELOPER,       
     SHOWTIME,        
     SILENT,          
     CUSTOM,          
     UNKNOWN_LOGGER
};
static const char* loggerMode_string[] = {
    "USER","DEVELOPER","SHOWTIME","SILENT","CUSTOM","Unknown mode"
};

enum SimMode {
    CPU_MODE,     
    GPU_MODE,     
    HYBRID_MODE   
};
static const char* simMode_string[] = {
    "CPU mode","GPU mode","Hybrid mode"
};

enum integrationMethod_t {
    FORWARD_EULER,
    RUNGE_KUTTA4,
    UNKNOWN_INTEGRATION
};
static const char* integrationMethod_string[] = {
    "Forward-Euler", "4-th order Runge-Kutta", "Unknown integration method"
};


enum ComputingBackend {
    CPU_CORES, 
    GPU_CORES  
};
static const char* ComputingBackend_string[] = {
    "CPU (x86/x64 Multi Core Processor)", 
    "GPU (NVIDIA Many CUDA Core Processor)",
};


// \TODO: extend documentation, add relevant references
enum STDPType {
    STANDARD,         
    DA_MOD,           
    SE_MOD,           
    AC_MOD,           
    NE_MOD,           
#ifdef LN_I_CALC_TYPES
    AC_DA_MOD,        
    AC_NE_MOD,        
    SE_DA_MOD,        
    NM4_MOD,          
    PKA_PLC_MOD,      
    //MOD_DA_D1,       //!< dopamine-modulated STDP, receptor D1 (experimental)
    //MOD_DA_D2,       //!< serotonin-modulated STDP, receptor D2 (experimental)
    //MOD_5HT_R1,      //!< serotonin-modulated STDP, (experimental)
    //MOD_ACH_N,         //!< acetylcholine-modulated STDP, nicotinic receptor (experimental)
    //MOD_ACH_M,         //!< acetylcholine-modulated STDP, muscarinic receptor (experimental)
    //           // LN2021 \todo metabotropic -> change cell param instead of synap properties
    //MOD_NE_A1,     //!< norepinephrine-modulated STDP, receptor \alpha 1 (experimental)
    //MOD_NE_A2,     //!< norepinephrine-modulated STDP, receptor \alpha 2 (experimental)
    //MOD_NE_B1,     //!< norepinephrine-modulated STDP, receptor \beta 1 (experimental)
    //MOD_NE_B2,     //!< norepinephrine-modulated STDP, receptor \beta 2 (experimental)
#endif
    UNKNOWN_STDP
};

static const char* stdpType_string[] = {
    "STANDARD",
    "DA_MOD",
    "SE_MOD",
    "AC_MOD",
    "NE_MOD",
#ifdef LN_I_CALC_TYPES
    "AC_DA_MOD",
    "AC_NE_MOD",
    "SE_DA_MOD",
    "NM4_MOD",
    "PKA_PLC_MOD",
    //"MOD_DA_D1",
    //"MOD_DA_D2",
    //"MOD_5HT_R1",
    //"MOD_ACH_N",
    //"MOD_ACH_M",
    //"MOD_NE_A1",
    //"MOD_NE_A2",
    //"MOD_NE_B1",
    //"MOD_NE_B2",
#endif
    "UNKNOWN_STDP"
};

static const char* stdpType_desc[] = {
    "Standard STDP",
    "Dopamine-modulated STDP",
    "Serotonin-modulated STDP",
    "Acetylcholine-modulated STDP",
    "Norepinphrine-modulated STDP",
#ifdef LN_I_CALC_TYPES
    "Acetylcholine-influenced-Dopamine-modulated STDP",
    "Acetylcholine-Norephinephrine encoded uncertainty STDP",
    "Serotonin-Dopamin encoded cost/reward STDP",
    "Multivariate-modulated STDP",
    "PKA/PLC-modulated STDP",
    //"MOD_DA_D1",
    //"MOD_DA_D2",
    //"MOD_5HT_R1",
    //"MOD_ACH_N",
    //"MOD_ACH_M",
    //"MOD_NE_A1",
    //"MOD_NE_A2",
    //"MOD_NE_B1",
    //"MOD_NE_B2",
#endif
    "Unknown mode"
};

#ifdef LN_I_CALC_TYPES

enum IcalcType {
    CUBA,           
    COBA,           
    NM4W_LN21,      
    GPCR_NB14,      
    DASEAC_CK09,    
    ACNE_ANCK12,    
    ACNE_K12,       
    ACNE_K13,       
    D1D2_AK12,      
    ACDA_BK19,      
    alpha1_ADK13,   
    alpha2A_ADK13,  
    D1_ADK13,       
    D2_AK15,        
    UNKNOWN_ICALC   
};

static const char* IcalcType_string[] = {
    "CUBA",
    "COBA",
    "NM4-mod.(LN21)",
    "GPCRs(NB14)"
    "DA/5HT/ACh-mod.(CK09)",
    "ACh/NE-mod.(ANCK12)",
    "ACh/NE-mod.(K12)",
    "ACh/NE-mod.(K13)",
    "D1,D2-rec.(AK12)",
    "ACh->DA(BK19)",
    "alpha1(ADK13)",
    "alpha2A(ADK13)",
    "D1(ADK13)",
    "D2(AK15)",
    "Unknown mode"
};
#endif

enum STDPCurve {
    EXP_CURVE,           
    PULSE_CURVE,         
    TIMING_BASED_CURVE,  
    UNKNOWN_CURVE        
};
static const char* stdpCurve_string[] = {
    "exponential curve",
    "pulse curve",
    "timing-based curve",
    "Unknow curve"
};

enum SpikeMonMode {
    COUNT,      
    AER,        
};
static const char* spikeMonMode_string[] = {
    "SpikeCount Mode","SpikeTime Mode"
};

enum Neuromodulator {
    NM_DA,      
    NM_5HT,     
    NM_ACh,     
    NM_NE,      
    NM_UNKNOWN  
};
static const char* neuromodulator_string[] = {
    "Dopamine", 
    "Serotonin", 
    "Acetylcholine", 
    "Noradrenaline",    // \FIXME synonym norepinephrine
    "Unknown neuromodulator"  
};

enum UpdateInterval {
    INTERVAL_10MS,      
    INTERVAL_100MS,     
    INTERVAL_1000MS     
};
static const char* updateInterval_string[] = {
    "10 ms interval", "100 ms interval", "1000 ms interval"
};

enum CARLsimState {
    CONFIG_STATE,       
    SETUP_STATE,        
    RUN_STATE           
};
static const char* carlsimState_string[] = {
    "Configuration state", "Setup state", "Run state"
};

struct RangeDelay {
    RangeDelay(int _val) {
        min = _val;
        max = _val;
    }
    RangeDelay(int _min, int _max) {
        UserErrors::assertTrue(_min<=_max, UserErrors::CANNOT_BE_LARGER, "RangeDelay", "minDelay", "maxDelay");
        min = _min;
        max = _max;
    }

    friend std::ostream& operator<<(std::ostream &strm, const RangeDelay &d) {
        return strm << "delay=[" << d.min << "," << d.max << "]";
    }
    int min,max;
};

struct RangeWeight {
    RangeWeight(double _val) {
        init = _val;
        max = _val;
        min = 0;
    }
    RangeWeight(double _min, double _max) {
        UserErrors::assertTrue(_min<=_max, UserErrors::CANNOT_BE_LARGER, "RangeWeight", "minWt", "maxWt");
        min = _min;
        init = _min;
        max = _max;
    }
    RangeWeight(double _min, double _init, double _max) {
        UserErrors::assertTrue(_min<=_init, UserErrors::CANNOT_BE_LARGER, "RangeWeight", "minWt", "initWt");
        UserErrors::assertTrue(_init<=_max, UserErrors::CANNOT_BE_LARGER, "RangeWeight", "initWt", "maxWt");
        min = _min;
        init = _init;
        max = _max;
    }

    friend std::ostream& operator<<(std::ostream &strm, const RangeWeight &w) {
        return strm << "wt=[" << w.min << "," << w.init << "," << w.max << "]";
    }
    double min, init, max;
};

struct RadiusRF {
    RadiusRF() : radX(0.0), radY(0.0), radZ(0.0) {}
    RadiusRF(double rad) : radX(rad), radY(rad), radZ(rad) {}
    RadiusRF(double rad_x, double rad_y, double rad_z) : radX(rad_x), radY(rad_y), radZ(rad_z) {}

    friend std::ostream& operator<<(std::ostream &strm, const RadiusRF &r) {
        return strm << "RadiusRF=[" << r.radX << "," << r.radY << "," << r.radZ << "]";
    }

    double radX, radY, radZ;
};

struct RangeRmem{
    RangeRmem(double _rMem){
        // same membrane resistance for all neurons in the group
        UserErrors::assertTrue(_rMem >= 0.0f, UserErrors::CANNOT_BE_NEGATIVE, "RangeRmem", "rMem");
        minRmem = _rMem;
        maxRmem = _rMem;
    }

    RangeRmem(double _minRmem, double _maxRmem){
        // membrane resistances of the  neuron group varies uniformly between a maximum and a minimum value
        UserErrors::assertTrue(_minRmem >= 0.0f, UserErrors::CANNOT_BE_NEGATIVE, "RangeRmem", "minRmem");
        UserErrors::assertTrue(_minRmem <= _maxRmem, UserErrors::CANNOT_BE_LARGER, "RangeRmem", "minRmem", "maxRmem");
        minRmem = _minRmem;
        maxRmem = _maxRmem;
    }

    friend std::ostream& operator<<(std::ostream &strm, const RangeRmem &rMem) {
        return strm << "RangeRmem=[" << rMem.minRmem << "," << rMem.maxRmem << "]";
    }
    double minRmem, maxRmem;    
};


typedef struct ConnSTDPInfo_s {
    bool        WithSTDP;           
    bool        WithESTDP;          
    bool        WithISTDP;          
    STDPType  WithESTDPtype;        
    STDPType  WithISTDPtype;        
    STDPCurve WithESTDPcurve;       
    STDPCurve WithISTDPcurve;       
    float       TAU_PLUS_INV_EXC;   
    float       TAU_MINUS_INV_EXC;  
    float       ALPHA_PLUS_EXC;     
    float       ALPHA_MINUS_EXC;    
    float       TAU_PLUS_INV_INB;   
    float       TAU_MINUS_INV_INB;  
    float       ALPHA_PLUS_INB;     
    float       ALPHA_MINUS_INB;    
    float       GAMMA;              
    float       BETA_LTP;           
    float       BETA_LTD;           
    float       LAMBDA;             
    float       DELTA;              
} ConnSTDPInfo;

typedef struct GroupNeuromodulatorInfo_s {
    float       baseDP;     
    float       base5HT;    
    float       baseACh;    
    float       baseNE;     

    float       decayDP;        
    float       decay5HT;       
    float       decayACh;       
    float       decayNE;        

    float       releaseDP;      
    float       release5HT;     
    float       releaseACh;     
    float       releaseNE;      

    bool        activeDP;       
    bool        active5HT;      
    bool        activeACh;      
    bool        activeNE;       

// \todo LN2021  doc:  mol   concentration   in ppm / mol /   acting molecules in the group 

// \todo LN2021 
    //float     maxDP;      //!< max concentration of Dopamine
    //float     max5HT; //!< baseline concentration of Serotonin
    //float     maxACh; //!< baseline concentration of Acetylcholine
    //float     maxNE;      //!< baseline concentration of Noradrenaline

} GroupNeuromodulatorInfo;

struct Grid3D {
    Grid3D() : numX(-1), numY(-1), numZ(-1), N(-1),
                     distX(-1.0f), distY(-1.0f), distZ(-1.0f),
                     offsetX(-1.0f), offsetY(-1.0f), offsetZ(-1.0f) {
    }

    Grid3D(int _x) : numX(_x), numY(1), numZ(1), N(_x),
                     distX(1.0f), distY(1.0f), distZ(1.0f),
                     offsetX(1.0f), offsetY(1.0f), offsetZ(1.0f) {
        UserErrors::assertTrue(_x > 0, UserErrors::MUST_BE_POSITIVE, "Grid3D", "numX");
    }

    Grid3D(int _x, float _distX, float _offsetX) : numX(_x), numY(1), numZ(1), N(_x),
                                                   distX(_distX), distY(1.0f), distZ(1.0f),
                                                   offsetX(_offsetX), offsetY(1.0f), offsetZ(1.0f) {
        UserErrors::assertTrue(_x > 0, UserErrors::MUST_BE_POSITIVE, "Grid3D", "numX");
        UserErrors::assertTrue(_distX > 0.0f, UserErrors::MUST_BE_POSITIVE, "Grid3D", "distX");
    }

    Grid3D(int _x, int _y) : numX(_x), numY(_y), numZ(1), N(_x * _y),
                             distX(1.0f), distY(1.0f), distZ(1.0f),
                             offsetX(1.0f), offsetY(1.0f), offsetZ(1.0f) {
        UserErrors::assertTrue(_x > 0, UserErrors::MUST_BE_POSITIVE, "Grid3D", "numX");
        UserErrors::assertTrue(_y > 0, UserErrors::MUST_BE_POSITIVE, "Grid3D", "numY");
    }

    Grid3D(int _x, float _distX, float _offsetX, int _y, float _distY, float _offsetY)
        : numX(_x), numY(_y), numZ(1), N(_x * _y),
          distX(_distX), distY(_distY), distZ(1.0f),
          offsetX(_offsetX), offsetY(_offsetY), offsetZ(1.0f) {
        UserErrors::assertTrue(_x > 0, UserErrors::MUST_BE_POSITIVE, "Grid3D", "numX");
        UserErrors::assertTrue(_distX > 0.0f, UserErrors::MUST_BE_POSITIVE, "Grid3D", "distX");
        UserErrors::assertTrue(_y > 0, UserErrors::MUST_BE_POSITIVE, "Grid3D", "numY");
        UserErrors::assertTrue(_distY > 0.0f, UserErrors::MUST_BE_POSITIVE, "Grid3D", "distY");
    }
    Grid3D(int _x, int _y, int _z) : numX(_x), numY(_y), numZ(_z), N(_x * _y * _z),
                                     distX(1.0f), distY(1.0f), distZ(1.0f),
                                     offsetX(1.0f), offsetY(1.0f), offsetZ(1.0f) {
         UserErrors::assertTrue(_x>0, UserErrors::MUST_BE_POSITIVE, "Grid3D", "numX");
         UserErrors::assertTrue(_y>0, UserErrors::MUST_BE_POSITIVE, "Grid3D", "numY");
         UserErrors::assertTrue(_z>0, UserErrors::MUST_BE_POSITIVE, "Grid3D", "numZ");
    }
    Grid3D(int _x, float _distX, float _offsetX, int _y, float _distY, float _offsetY, int _z, float _distZ, float _offsetZ)
        : numX(_x), numY(_y), numZ(_z), N(_x * _y * _z),
          distX(_distX), distY(_distY), distZ(_distZ),
          offsetX(_offsetX), offsetY(_offsetY), offsetZ(_offsetZ) {
        UserErrors::assertTrue(_x > 0, UserErrors::MUST_BE_POSITIVE, "Grid3D", "numX");
        UserErrors::assertTrue(_distX > 0.0f, UserErrors::MUST_BE_POSITIVE, "Grid3D", "distX");
        UserErrors::assertTrue(_y > 0, UserErrors::MUST_BE_POSITIVE, "Grid3D", "numY");
        UserErrors::assertTrue(_distY > 0.0f, UserErrors::MUST_BE_POSITIVE, "Grid3D", "distY");
        UserErrors::assertTrue(_z > 0, UserErrors::MUST_BE_POSITIVE, "Grid3D", "numZ");
        UserErrors::assertTrue(_distZ > 0.0f, UserErrors::MUST_BE_POSITIVE, "Grid3D", "distZ");
    }

    friend std::ostream& operator<<(std::ostream &strm, const Grid3D &g) {
        return strm << "Grid3D=[" << g.numX << "," << g.numY << "," << g.numZ << "]";
    }

    int numX, numY, numZ;
    float distX, distY, distZ;
    float offsetX, offsetY, offsetZ;
    int N;
};

struct ExpCurve {
    ExpCurve(float _alphaPlus, float _tauPlus, float _alphaMinus, float _tauMinus) : alphaPlus(_alphaPlus), tauPlus(_tauPlus), alphaMinus(_alphaMinus), tauMinus(_tauMinus) {
        UserErrors::assertTrue(_tauPlus > 0.0f, UserErrors::MUST_BE_POSITIVE, "ExpCurve", "tauPlus");
        UserErrors::assertTrue(_tauMinus > 0.0f, UserErrors::MUST_BE_POSITIVE, "ExpCurve", "tauMinus");

        stdpCurve = EXP_CURVE;
    }

    STDPCurve stdpCurve; 
    float alphaPlus; 
    float tauPlus; 
    float alphaMinus; 
    float tauMinus; 
};

struct TimingBasedCurve {
    TimingBasedCurve(float _alphaPlus, float _tauPlus, float _alphaMinus, float _tauMinus, float _gamma) : alphaPlus(_alphaPlus), tauPlus(_tauPlus), alphaMinus(_alphaMinus), tauMinus(_tauMinus) , gamma(_gamma) {
        UserErrors::assertTrue(_alphaPlus > 0.0f, UserErrors::MUST_BE_POSITIVE, "TimingBasedCurve", "alphaPlus");
        UserErrors::assertTrue(_alphaMinus < 0.0f, UserErrors::MUST_BE_NEGATIVE, "TimingBasedCurve", "alphaMinus");
        UserErrors::assertTrue(_tauPlus > 0.0f, UserErrors::MUST_BE_POSITIVE, "TimingBasedCurve", "tauPlus");
        UserErrors::assertTrue(_tauMinus > 0.0f, UserErrors::MUST_BE_POSITIVE, "TimingBasedCurve", "tauMinus");
        UserErrors::assertTrue(_gamma > 0.0f, UserErrors::MUST_BE_POSITIVE, "TimingBasedCurve", "gamma");
        UserErrors::assertTrue(_tauPlus >= _gamma, UserErrors::CANNOT_BE_SMALLER, "TimingBasedCurve", "tauPlus >= gamma");

        stdpCurve = TIMING_BASED_CURVE;
    }

    STDPCurve stdpCurve; 
    float alphaPlus; 
    float tauPlus; 
    float alphaMinus; 
    float tauMinus; 
    float gamma; 
};

struct PulseCurve {
    PulseCurve(float _betaLTP, float _betaLTD, float _lambda, float _delta) : betaLTP(_betaLTP), betaLTD(_betaLTD), lambda(_lambda), delta(_delta) {
        UserErrors::assertTrue(_betaLTP > 0.0f, UserErrors::MUST_BE_POSITIVE, "PulseCurve", "betaLTP");
        UserErrors::assertTrue(_betaLTD < 0.0f, UserErrors::MUST_BE_NEGATIVE, "PulseCurve", "betaLTD");
        UserErrors::assertTrue(_lambda > 0.0f, UserErrors::MUST_BE_POSITIVE, "PulseCurve", "lambda");
        UserErrors::assertTrue(_delta > 0.0f, UserErrors::MUST_BE_POSITIVE, "PulseCurve", "delta");
        UserErrors::assertTrue(_lambda < _delta, UserErrors::MUST_BE_SMALLER, "PulseCurve", "lambda < delta");

        stdpCurve = PULSE_CURVE;
    }

    STDPCurve stdpCurve; 
    float betaLTP; 
    float betaLTD; 
    float lambda; 
    float delta; 
};


#ifdef LN_I_CALC_TYPES
/*
 * mapping structure config for Nadim/Bucher 
 * neuromodulator nm 
 * \param[in] nm_pka    index of nm induces PKA 
 * \param[in] w_pka     weigth of PKA targeting nm
 * \param[in] nm_plc    index of nm inducing PLC
 * \param[in] w_plc     weigth of PLCA targeting nm
*/
struct PkaPlcModulation {

    PkaPlcModulation(int nm_pka, float w_pka, int nm_plc, float w_plc) {

        UserErrors::assertTrue(nm_pka != nm_plc, UserErrors::CANNOT_BE_IDENTICAL, "PkaPlcModulation", "nm_pka,plc");
        UserErrors::assertTrue(w_pka != .0f, UserErrors::CANNOT_BE_ZERO, "PkaPlcModulation", "w_pka");
        UserErrors::assertTrue(w_plc != .0f, UserErrors::CANNOT_BE_ZERO, "PkaPlcModulation", "w_plc");

        i_nm[i_pka] = nm_pka;       w_nm[i_pka] = w_pka;    desc[i_pka] = neuromodulator_string[nm_pka];
        i_nm[i_plc] = nm_plc;       w_nm[i_plc] = w_plc;    desc[i_plc] = neuromodulator_string[nm_plc];
    }

    // members 
    const STDPType type = PKA_PLC_MOD;
    const int i_pka = 0;    
    const int i_plc = 1;    
    float   w_nm[2];            
    int     i_nm[2];            
    const char* desc[2];    

    // symbolic accessor 
    int nm_pka() { return i_nm[i_pka]; }
    int nm_plc() { return i_nm[i_plc]; }
    float w_pka() { return w_nm[i_pka]; }
    float w_plc() { return w_nm[i_plc]; }
    const char* lingat_pka() { return desc[nm_pka()]; }
    const char* lingat_plc() { return desc[nm_plc()]; }

};


/*

generalization:
struct Nm4w {

};

*/

#endif

#endif