neuron_impl_external_devices.h

Go to the documentation of this file.

/*
 * Copyright (c) 2017 The University of Manchester
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 
#ifndef _NEURON_IMPL_EXTERNAL_DEVICES_H_
#define _NEURON_IMPL_EXTERNAL_DEVICES_H_
 
#include "neuron_impl.h"
 
enum send_type {
    SEND_TYPE_INT = 0, 
    SEND_TYPE_UINT,    
    SEND_TYPE_ACCUM,   
    SEND_TYPE_UACCUM,  
    SEND_TYPE_FRACT,   
    SEND_TYPE_UFRACT,  
};
 
// Includes for model parts used in this implementation
 
#include <neuron/models/neuron_model_lif_impl.h>
#include <neuron/synapse_types/synapse_types_exponential_impl.h>
#include <neuron/input_types/input_type_current.h>
 
#include <neuron/current_sources/current_source_impl.h>
#include <neuron/current_sources/current_source.h>
 
// Further includes
#include <debug.h>
 
 
typedef struct packet_firing_data_t {
    uint32_t key;
    uint32_t value_as_payload;
    accum min_value;
    accum max_value;
    uint32_t timesteps_between_sending;
    uint32_t time_until_next_send;
    enum send_type type;
} packet_firing_data_t;
 
enum word_recording_indices {
    V_RECORDING_INDEX = 0,
    GSYN_EXC_RECORDING_INDEX = 1,
    GSYN_INH_RECORDING_INDEX = 2,
    N_RECORDED_VARS = 3
};
 
enum bitfield_recording_indices {
    PACKET_RECORDING_BITFIELD = 0,
    N_BITFIELD_VARS = 1
};
 
// This import depends on variables defined above
#include <neuron/neuron_recording.h>
 
static neuron_t *neuron_array;
 
static packet_firing_data_t *packet_firing_array;
 
static synapse_types_t *synapse_types_array;
 
static uint n_steps_per_timestep;
 
// Typesafe magic reinterpret cast
static inline uint _int_bits(int value) {
    typedef union _int_bits_union {
        int int_value;
        uint uint_value;
    } _int_bits_union;
 
    _int_bits_union converter;
    converter.int_value = value;
    return converter.uint_value;
}
 
static inline uint _get_payload(enum send_type type, accum value) {
    switch (type) {
    case SEND_TYPE_INT:
        return _int_bits((int) value);
    case SEND_TYPE_UINT:
        return (uint) value;
    case SEND_TYPE_ACCUM:
        return _int_bits(bitsk(value));
    case SEND_TYPE_UACCUM:
        return bitsuk((unsigned accum) value);
    case SEND_TYPE_FRACT:
        return _int_bits(bitslr((long fract) value));
    case SEND_TYPE_UFRACT:
        return bitsulr((long unsigned fract) value);
    default:
        log_error("Unknown enum value %u", value);
        rt_error(RTE_SWERR);
    }
    return 0;
}
 
SOMETIMES_UNUSED // Marked unused as only used sometimes
static bool neuron_impl_initialise(uint32_t n_neurons) {
 
    // Allocate DTCM for neuron array
    log_info("Initialising for %u neurons", n_neurons);
    neuron_array = spin1_malloc(n_neurons * sizeof(neuron_t));
    if (neuron_array == NULL) {
        log_error("Unable to allocate neuron array - Out of DTCM");
        return false;
    }
 
    // Allocate DTCM for packet firing array and copy block of data
    packet_firing_array =
            spin1_malloc(n_neurons * sizeof(packet_firing_data_t));
    if (packet_firing_array == NULL) {
        log_error("Unable to allocate packet firing array - Out of DTCM");
        return false;
    }
 
    // Allocate DTCM for synapse shaping parameters
    synapse_types_array =
            spin1_malloc(n_neurons * sizeof(synapse_types_t));
    if (synapse_types_array == NULL) {
        log_error("Unable to allocate synapse parameters array"
                " - Out of DTCM");
        return false;
    }
 
    return true;
}
 
SOMETIMES_UNUSED // Marked unused as only used sometimes
static void neuron_impl_add_inputs(
        index_t synapse_type_index, index_t neuron_index,
        input_t weights_this_timestep) {
    // simple wrapper to synapse type input function
    synapse_types_t *parameters = &synapse_types_array[neuron_index];
    synapse_types_add_neuron_input(synapse_type_index,
            parameters, weights_this_timestep);
}
 
static uint32_t n_words_needed(size_t size) {
    return (size + (sizeof(uint32_t) - 1)) / sizeof(uint32_t);
}
 
SOMETIMES_UNUSED // Marked unused as only used sometimes
static void neuron_impl_load_neuron_parameters(
        address_t address, uint32_t next, uint32_t n_neurons,
        address_t save_initial_state) {
 
    // Read the number of steps per timestep
    n_steps_per_timestep = address[next++];
    if (n_steps_per_timestep > 1) {
        log_info("Looping over %u steps each timestep", n_steps_per_timestep);
    } else if (n_steps_per_timestep == 0) {
        log_error("bad number of steps per timestep: 0");
    }
 
    neuron_params_t *neuron_params = (neuron_params_t *) &address[next];
    for (uint32_t i = 0; i < n_neurons; i++) {
        neuron_model_initialise(&neuron_array[i], &neuron_params[i], n_steps_per_timestep);
    }
    next += n_words_needed(n_neurons * sizeof(neuron_params_t));
 
    spin1_memcpy(packet_firing_array, &address[next],
            n_neurons * sizeof(packet_firing_data_t));
    next += n_words_needed(n_neurons * sizeof(packet_firing_data_t));
 
    synapse_types_params_t *synapse_params = (synapse_types_params_t *) &address[next];
    for (uint32_t i = 0; i < n_neurons; i++) {
        synapse_types_initialise(&synapse_types_array[i], &synapse_params[i], n_steps_per_timestep);
    }
    next += n_words_needed(n_neurons * sizeof(synapse_types_params_t));
 
    // If we are to save the initial state, copy the whole of the parameters
    // to the initial state
    if (save_initial_state) {
        spin1_memcpy(save_initial_state, address, next * sizeof(uint32_t));
    }
 
#if LOG_LEVEL >= LOG_DEBUG
    for (index_t n = 0; n < n_neurons; n++) {
        neuron_model_print_parameters(&neuron_array[n]);
    }
#endif // LOG_LEVEL >= LOG_DEBUG
}
 
static bool _test_will_fire(packet_firing_data_t *packet_firing) {
    if (packet_firing->time_until_next_send == 0) {
        packet_firing->time_until_next_send =
                packet_firing->timesteps_between_sending;
        --packet_firing->time_until_next_send;
        return true;
    }
    --packet_firing->time_until_next_send;
    return false;
}
 
SOMETIMES_UNUSED // Marked unused as only used sometimes
static void neuron_impl_do_timestep_update(
        UNUSED uint32_t timer_count, UNUSED uint32_t time, uint32_t n_neurons) {
 
    for (uint32_t neuron_index = 0; neuron_index < n_neurons; neuron_index++) {
        // Get the neuron itself
        neuron_t *this_neuron = &neuron_array[neuron_index];
 
        // Get threshold and additional input parameters for this neuron
        packet_firing_data_t *the_packet_firing =
            &packet_firing_array[neuron_index];
        synapse_types_t *the_synapse_type =
                &synapse_types_array[neuron_index];
 
        // Store whether the neuron has spiked
        bool will_fire = false;
 
        // Loop however many times requested; do this in reverse for efficiency,
        // and because the index doesn't actually matter
        for (uint32_t i = n_steps_per_timestep; i > 0; i--) {
            // Get the voltage
            state_t soma_voltage = neuron_model_get_membrane_voltage(this_neuron);
 
            // Get the exc and inh values from the synapses
            input_t exc_values[NUM_EXCITATORY_RECEPTORS];
            input_t *exc_input_values =
                    synapse_types_get_excitatory_input(exc_values, the_synapse_type);
            input_t inh_values[NUM_INHIBITORY_RECEPTORS];
            input_t *inh_input_values =
                    synapse_types_get_inhibitory_input(inh_values, the_synapse_type);
 
            // Sum g_syn contributions from all receptors for recording
            REAL total_exc = 0;
            REAL total_inh = 0;
 
            for (int i = 0; i < NUM_EXCITATORY_RECEPTORS; i++) {
                total_exc += exc_input_values[i];
            }
            for (int i = 0; i < NUM_INHIBITORY_RECEPTORS; i++) {
                total_inh += inh_input_values[i];
            }
 
            // Do recording if on the first step
            if (i == n_steps_per_timestep) {
                neuron_recording_record_accum(
                        V_RECORDING_INDEX, neuron_index, soma_voltage);
                neuron_recording_record_accum(
                        GSYN_EXC_RECORDING_INDEX, neuron_index, total_exc);
                neuron_recording_record_accum(
                        GSYN_INH_RECORDING_INDEX, neuron_index, total_inh);
            }
 
            // Get any input from an injected current source
            REAL current_offset = current_source_get_offset(time, neuron_index);
 
            // update neuron parameters
            state_t result = neuron_model_state_update(
                    NUM_EXCITATORY_RECEPTORS, exc_input_values,
                    NUM_INHIBITORY_RECEPTORS, inh_input_values,
                    0, current_offset, this_neuron);
 
            // determine if a packet should fly
            will_fire = _test_will_fire(the_packet_firing);
 
            // If spike occurs, communicate to relevant parts of model
            if (will_fire) {
                if (the_packet_firing->value_as_payload) {
                    accum value_to_send = result;
                    if (result > the_packet_firing->max_value) {
                        value_to_send = the_packet_firing->max_value;
                    }
                    if (result < the_packet_firing->min_value) {
                        value_to_send = the_packet_firing->min_value;
                    }
 
                    uint payload = _get_payload(
                        the_packet_firing->type,
                        value_to_send * the_packet_firing->value_as_payload);
 
                    send_spike_mc_payload(the_packet_firing->key, payload);
                } else {
                    send_spike_mc(the_packet_firing->key);
                }
            }
 
            // Shape the existing input according to the included rule
            synapse_types_shape_input(the_synapse_type);
        }
 
        if (will_fire) {
            // Record the spike
            neuron_recording_record_bit(PACKET_RECORDING_BITFIELD, neuron_index);
        }
 
    #if LOG_LEVEL >= LOG_DEBUG
        neuron_model_print_state_variables(this_neuron);
    #endif // LOG_LEVEL >= LOG_DEBUG
    }
}
 
SOMETIMES_UNUSED // Marked unused as only used sometimes
static void neuron_impl_store_neuron_parameters(
        address_t address, uint32_t next, uint32_t n_neurons) {
    // Skip over the steps per timestep
    next += 1;
 
    neuron_params_t *neuron_params = (neuron_params_t *) &address[next];
    for (uint32_t i = 0; i < n_neurons; i++) {
        neuron_model_save_state(&neuron_array[i], &neuron_params[i]);
    }
    next += n_words_needed(n_neurons * sizeof(neuron_params_t));
 
    spin1_memcpy(&address[next], packet_firing_array,
            n_neurons * sizeof(packet_firing_data_t));
    next += n_words_needed(n_neurons * sizeof(packet_firing_data_t));
 
    synapse_types_params_t *synapse_params = (synapse_types_params_t *) &address[next];
    for (uint32_t i = 0; i < n_neurons; i++) {
        synapse_types_save_state(&synapse_types_array[i], &synapse_params[i]);
    }
    next += n_words_needed(n_neurons * sizeof(synapse_types_params_t));
}
 
#if LOG_LEVEL >= LOG_DEBUG
SOMETIMES_UNUSED // Marked unused as only used sometimes
void neuron_impl_print_inputs(uint32_t n_neurons) {
    bool empty = true;
    for (index_t i = 0; i < n_neurons; i++) {
        synapse_types_t *params = &synapse_types_array[i];
        input_t exc_values[NUM_EXCITATORY_RECEPTORS];
        input_t inh_values[NUM_INHIBITORY_RECEPTORS];
        empty = empty && (0 == bitsk(
                synapse_types_get_excitatory_input(exc_values, params)
                - synapse_types_get_inhibitory_input(inh_values, params)));
    }
 
    if (!empty) {
        for (index_t i = 0; i < n_neurons; i++) {
            synapse_types_t *params = &synapse_types_array[i];
            input_t exc_values[NUM_EXCITATORY_RECEPTORS];
            input_t inh_values[NUM_INHIBITORY_RECEPTORS];
            input_t input = synapse_types_get_excitatory_input(exc_values, params)
                    - synapse_types_get_inhibitory_input(inh_values, params);
            if (bitsk(input) != 0) {
                log_debug("%3u: %12.6k (= ", i, input);
                synapse_types_print_input(params);
                log_debug(")\n");
            }
        }
    }
}
 
SOMETIMES_UNUSED // Marked unused as only used sometimes
void neuron_impl_print_synapse_parameters(uint32_t n_neurons) {
    for (index_t n = 0; n < n_neurons; n++) {
        synapse_types_print_parameters(&synapse_types_array[n]);
    }
}
 
SOMETIMES_UNUSED // Marked unused as only used sometimes
const char *neuron_impl_get_synapse_type_char(uint32_t synapse_type) {
    return synapse_types_get_type_char(synapse_type);
}
#endif // LOG_LEVEL >= LOG_DEBUG
 
#endif // _NEURON_IMPL_EXTERNAL_DEVICES_H_