% CSIM_LIFNET Simulate a network of leaky integrate and fire Neurons.
% 
% [ST,VM,PSC] = csim_lifnet(Neurons,Synapses,InSpikes,dt,...
%     Tsim,dt_out,dt_disp,noise,AnalogIN,dt_analog)
%      simulates a network defined by the matrices 'Neurons' and
%      'Synapses' (see below) and returns all the spikes (output matrix
%      'ST') which occurred during the simulation and the membrane
%      voltages (output matrix 'VM') and postsynaptic currents (output
%      matrix 'PSC') of chosen sets of neurons and synapses.  The input
%      to the network consists of several spike trains (cell array
%      'InSpikes', see below) and/or several analog wave forms
%      ('AnalogIN') which are injected into neurons via analog synapses.
%      
%      'dt' is the integration time step.
%  
%      'Tsim' defines how long to simulate.
%      
%      'dt_out' defines the time steps at which the membrane potential
%      of a neuron or PSC of a synapse should be recorded ('dt_out'
%      should be a multiple of 'dt').
%      
%      'dt_disp' defines the time steps at which some progress info is
%      printed in the terminal.
% 
%      'dt_analog' defines the time base for the analog input wave
%      forms.
%      
%      if 'noise' is greater zero then noise is the variance of a
%      Gaussian noise with zero mean which is added at each integration
%      time step to the total input current of each neuron in the
%      network.
%     
%      'Neuron' is a n x #Neurons matrix where each column describes the
%      parameters of a single neuron (n is either 4, 5, 6 or 7).
%
%
%          'Neuron(1,i)' holds the type definition of neuron 'i'. 
%          It can be defined to be either be a 
%              - leaky integrate-and-fire neuron ('Neuron(1,i)=LIF_NEURON')
%              - a spiking input ('Neuron(1,i)=SPIKE_INPUT')
%              - or an analog input ('Neuron(1,i)=ANALOG_INPUT').
%          The constants 'LIF_NEURON', 'SPIKE_INPUT' and 'ANALOG_INPUT' are
%          defined in csim_defs.m
%         
%          In the case of an input (spiking or analog) all other
%          parameters 'Neuron(2:n,i)' are irrelevant. 
%    
%          'Neuron(1,i)' holds also a flag which determines whether the
%          membrane voltage of neuron 'i' is recorded and stored in the
%          output matrix 'VM'. If the bit 'REC_BIT' (defined in csim_defs.m)
%          of 'Neuron(1,i)' is set, e.g.  with the command
%          'Neuron(1,i)=bitset(Neuron(1,i),REC_BIT)' the membrane
%          voltage of neuron 'i' is recorded and stored in the output
%          matrix 'VM'.
%          
%          The following parameters are only relevant for
%          leaky-integrate and fire neurons.
%          
%          'Neuron(2,i)' defines the threshold of neuron 'i'
%          
%          'Neuron(3,i)' defines the length of the absolute refractory
%          period of neuron 'i'
%        
%          'Neuron(4,i)' defines the membrane time constant of neuron
%          'i'
%        
%          'Neuron(5,i)' defines the reset voltage of neuron 'i' (set to
%          0.0 if n < 5)
%        
%          'Neuron(6,i)' defines the background current of neuron 'i'
%          (set to 0.0 if n < 6)
%        
%          'Neuron(7,i)' defines the initial membrane voltage of neuron
%          'i' (set to 0.0 if n < 7)
%   
%     'Synapses' is a s x #Synapses matrix where each column describes the
%     parameters of a single synapse (s is either 10, 11 or 12).
% 
%       'Synapse(1,i)' holds the type definition of synapse 'i'.
%        It can either be 
%           - a static 'Synapse(1,i)=STATIC_SYN',
%           - a dynamic 'Synapse(1,i)=DYNAMIC_SYN' synapse (see
%             [Markram et al, PNAS 95:5323-5328, 1998] for a description
%             of the dynamics) or 
%           - an analog synapse 'Synapse(1,i)=ANALOG_SYN' (to connect 
%             analog inputs to LIF neurons).
%        'Synapse(1,i)' holds also a flag which determines whether the
%        PSC of synapse 'i' is recorded and stored in the
%        output matrix 'PSC'. If the bit 'REC_BIT' (defined in csim_defs.m)
%        of 'Synapse(1,i)' is set, e.g.  with the command
%        'Synapse(1,i)=bitset(Synapse(1,i),REC_BIT)' the PSC of
%        synapse 'i' is recorded and stored in the output
%        matrix 'PSC'.
%        
%        'Synapse(2,i)' is the index (in the range 1..#Neurons) of the
%        presynaptic neuron.
%        
%        'Synapse(3,i)' is the index (in the range 1..#Neurons) of the
%        postsynaptic neuron.
%        
%        'Synapse(4,i)' the weight
%        
%        'Synapse(5,i)' the transmission delay
%        
%        'Synapse(6,i)' the synaptic time constant
%        
%        'Synapse(7,i)' is the variance of a Gaussion zero mean noise
%        added to the PSC if synapse i is an analog synapse. not used
%        otherwise.
%        
%        The following parameters are only relevant if synapse 'i' is a
%        dynamic synapse, i.e. 'bitset(Synapse(1,i),REC_BIT,0)==DYNAMIC_SYN'.
%        
%        'Synapse(8,i)' the U parameter of the model described in
%        [Markram et al, PNAS 95:5323-5328, 1998]
%        
%        'Synapse(9,i)' the D parameter (also known as tau_rec) of the
%        model described in [Markram et al, PNAS 95:5323-5328, 1998]
%        
%        'Synapse(10,i)' the F parameter (also known as tau_facil) of
%        the model described in [Markram et al, PNAS 95:5323-5328, 1998]
%        
%        'Synapse(11,i)' the inital value of the state variable u (i.e.
%        u_0) in the model of [Markram et al, PNAS 95:5323-5328, 1998] (set to 1.0 if not
%        supplied)
%        
%        'Synapse(12,i)' the inital value of the state variable R (i.e.
%        R_0) in the model of [Markram et al, PNAS 95:5323-5328, 1998] (set to 0.0 if not
%        supplied)
%   
%     'InSpikes' is a cell array of length #Neurons. If neuron 'i' is
%     defined to be an input neuron 
%     (i.e. bitset(Neuron(1,i),REC_BIT,0)==SPIKE_INPUT) then
%     'InSpikes{i}' has to be a 1x#Spikes matrix and describes the times
%     at with neuron 'i' will fire a spike.
%       
%     'AnalogIN' is a cell array of length #Neurons. If neuron 'i' is
%     defined to be an analog input neuron (i.e.
%     bitset(Neuron(1,i),REC_BIT,0)==ANALOG_INPUT) then 'AnalogIn{i}' has to be a 1xT
%     matrix and describes the analog wave form.  The values in
%     'AnalogIn{i}' are stepped through with a time step of 'dt_analog'.
%       
%     The output matrix 'ST' is a 2 x #SpikesDuringTheSimulation matrix,
%     where each column 'ST(:,i)' describes a spike: 'ST(2,i)' is the
%     time of the spike and 'ST(1,i)' is the index of the neuron which
%     fired this spike. Note that the spikes of input neurons are not
%     contained in 'ST'.
%       
%     The output matrix 'VM' is a #RecordedNeurons x
%     #RecordingTimePoints matrix.  Each row 'VM(i,:)' is the recording
%     of the membrane potential of a neuron witch has the record bit on
%     (i.e. 'bitget(Neuron(1,i),REC_BIT)==1'). The are as much rows in 'VM' as
%     there are neurons with a set output bit.  Specifically, 'VM(1,:)'
%     is the trace of the neuron with smallest index having the record
%     bit set and 'VM(end,:)' is the trace of the neuron with greatest
%     index having the output bit set.
%       
%     The output matrix 'PSC' is a #RecordedSynapses x
%     #RecordingTimePoints matrix.  Each row 'PSC(i,:)' is the recording
%     of the membrane potential of a Synapse witch has the record bit on
%     (i.e. 'bitget(Synapse(1,i),REC_BIT)==1'). The are as much rows in 'PSC'
%     as there are Synapses with a set record bit.  Specifically,
%     'PSC(1,:)' is the trace of the Synapse with smallest index (i.e.
%     its position in the Matrix Synapses) having the record bit set and
%     'PSC(end,:)' is the trace of the Synapse with greatest index
%     having the record bit set.
% 
%     For a short demo how to use 'csim_lifnet' see 'lifnet_demo.m'
% 
%    
%   Author: Thomas Natschlaeger, 16/11/2001
%