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
*
* 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
};
 
// \TODO: extend documentation, add relevant references
enum STDPType {
    STANDARD,         
    DA_MOD,           
    UNKNOWN_STDP
};
 
static const char* stdpType_string[] = {
    "Standard STDP",
    "Dopamine-modulated STDP",
    "Unknown mode"
};
 
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", "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 GroupSTDPInfo_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;              
} GroupSTDPInfo;
 
typedef struct GroupNeuromodulatorInfo_s {
    float       baseDP;     
    float       base5HT;    
    float       baseACh;    
    float       baseNE;     
    float       decayDP;        
    float       decay5HT;       
    float       decayACh;       
    float       decayNE;        
} 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; 
};
 
#endif