nemo.h File Reference

C API for the NeMo spiking neural network simulator. More...

Go to the source code of this file.

Typedefs
typedef nemo_network_class *	nemo_network_t
typedef int	nemo_status_t
Functions
nemo_status_t	nemo_cuda_device_count (unsigned *count)
Configuration
nemo_configuration_t	nemo_new_configuration ()
void	nemo_delete_configuration (nemo_configuration_t)
nemo_status_t	nemo_log_stdout (nemo_configuration_t)
nemo_status_t	nemo_set_stdp_function (nemo_configuration_t, float prefire_fn[], size_t prefire_len, float postfire_fn[], size_t postfire_len, float min_excitatory_weight, float max_excitatory_weight, float min_inhibitory_weight, float max_inhibitory_weight)
nemo_status_t	nemo_set_cpu_backend (nemo_configuration_t, int thread_count)
nemo_status_t	nemo_cpu_thread_count (nemo_configuration_t conf, int *thread_count)
nemo_status_t	nemo_set_cuda_backend (nemo_configuration_t conf, int dev)
nemo_status_t	nemo_cuda_device (nemo_configuration_t conf, int *dev)
nemo_status_t	nemo_backend (nemo_configuration_t conf, backend_t *backend)
nemo_status_t	nemo_backend_description (nemo_configuration_t conf, const char **descr)
nemo_status_t	nemo_set_write_only_synapses (nemo_configuration_t conf)
Construction
Networks are constructed by adding individual neurons and of synapses to the network. Neurons are given indices (ideally, but not necessarily starting from 0) which should be unique for each neuron. When adding synapses the source or target neurons need not necessarily exist yet, but need to be defined before the simulation is created.
nemo_network_t	nemo_new_network ()
void	nemo_delete_network (nemo_network_t)
nemo_status_t	nemo_add_neuron_type (nemo_network_t, const char *name, unsigned *neuron_type)
nemo_status_t	nemo_add_neuron_iz (nemo_network_t, unsigned idx, float a, float b, float c, float d, float u, float v, float sigma)
	Add a single Izhikevich neuron to the network.
nemo_status_t	nemo_add_neuron (nemo_network_t, unsigned type, unsigned idx, unsigned nargs, float args[])
nemo_status_t	nemo_add_synapse (nemo_network_t, unsigned source, unsigned target, unsigned delay, float weight, unsigned char is_plastic, synapse_id *id)
nemo_status_t	nemo_neuron_count (nemo_network_t net, unsigned *ncount)
Simulation
nemo_simulation_t	nemo_new_simulation (nemo_network_t, nemo_configuration_t)
void	nemo_delete_simulation (nemo_simulation_t)
nemo_status_t	nemo_step (nemo_simulation_t, unsigned fstim_nidx[], size_t fstim_count, unsigned istim_nidx[], float istim_current[], size_t istim_count, unsigned *fired[], size_t *fired_count)
nemo_status_t	nemo_apply_stdp (nemo_simulation_t, float reward)
Querying the network
Neuron parameters (static) and state varaibles (dynamic) may be read read back either during construction or simulation. The same function names are used in both cases, but functions are postfixed with '_n' or '_s' to denote network or simulation functions. The synapse state can also be read back during simulation. Synapses are referred to via a synapse_id (see nemo_add_synapse). The weights may change at run-time, while the other synapse data is static. As for neurons, the state can be read back either during construction or simulation, and function names are postfixed with '_n' or '_s' for the two cases.
nemo_status_t	nemo_get_membrane_potential (nemo_simulation_t sim, unsigned neuron, float *v)
nemo_status_t	nemo_get_neuron_state_n (nemo_network_t net, unsigned neuron, unsigned var, float *val)
nemo_status_t	nemo_get_neuron_parameter_n (nemo_network_t net, unsigned neuron, unsigned param, float *val)
nemo_status_t	nemo_get_neuron_state_s (nemo_simulation_t sim, unsigned neuron, unsigned var, float *val)
nemo_status_t	nemo_get_neuron_parameter_s (nemo_simulation_t sim, unsigned neuron, unsigned param, float *val)
nemo_status_t	nemo_get_synapse_source_n (nemo_network_t, synapse_id synapse, unsigned *source)
nemo_status_t	nemo_get_synapse_source_s (nemo_simulation_t, synapse_id synapse, unsigned *source)
nemo_status_t	nemo_get_synapse_target_n (nemo_network_t, synapse_id synapse, unsigned *target)
nemo_status_t	nemo_get_synapse_target_s (nemo_simulation_t, synapse_id synapse, unsigned *target)
nemo_status_t	nemo_get_synapse_delay_n (nemo_network_t, synapse_id synapse, unsigned *delay)
nemo_status_t	nemo_get_synapse_delay_s (nemo_simulation_t, synapse_id synapse, unsigned *delay)
nemo_status_t	nemo_get_synapse_weight_n (nemo_network_t, synapse_id synapse, float *weight)
nemo_status_t	nemo_get_synapse_weight_s (nemo_simulation_t, synapse_id synapse, float *weight)
nemo_status_t	nemo_get_synapse_plastic_n (nemo_network_t, synapse_id synapse, unsigned char *plastic)
nemo_status_t	nemo_get_synapse_plastic_s (nemo_simulation_t, synapse_id synapse, unsigned char *plastic)
nemo_status_t	nemo_get_synapses_from_n (nemo_network_t, unsigned source, synapse_id *synapses[], size_t *len)
nemo_status_t	nemo_get_synapses_from_s (nemo_simulation_t, unsigned source, synapse_id *synapses[], size_t *len)
Modifying the network
Neuron parameters and state variables can be modified during both construction and simulation. The same function names are used in both cases, but functions are postfixed with '_n' or '_s' to denote network or simulation functions. In the current version of NeMo synapses can not be modified during simulation.
nemo_status_t	nemo_set_neuron_n (nemo_network_t, unsigned idx, unsigned nargs, float args[])
nemo_status_t	nemo_set_neuron_s (nemo_simulation_t, unsigned idx, unsigned nargs, float args[])
nemo_status_t	nemo_set_neuron_iz_n (nemo_network_t net, unsigned idx, float a, float b, float c, float d, float u, float v, float sigma)
nemo_status_t	nemo_set_neuron_iz_s (nemo_simulation_t sim, unsigned idx, float a, float b, float c, float d, float u, float v, float sigma)
nemo_status_t	nemo_set_neuron_state_n (nemo_network_t net, unsigned neuron, unsigned var, float val)
nemo_status_t	nemo_set_neuron_parameter_n (nemo_network_t net, unsigned neuron, unsigned param, float val)
nemo_status_t	nemo_set_neuron_state_s (nemo_simulation_t sim, unsigned neuron, unsigned var, float val)
nemo_status_t	nemo_set_neuron_parameter_s (nemo_simulation_t sim, unsigned neuron, unsigned param, float val)
Simulation timing
The simulation has two internal timers which keep track of the elapsed simulated time and wallclock time. Both timers measure from the first simulation step, or from the last timer reset, whichever comes last.
nemo_status_t	nemo_elapsed_wallclock (nemo_simulation_t, unsigned long *)
nemo_status_t	nemo_elapsed_simulation (nemo_simulation_t, unsigned long *)
nemo_status_t	nemo_reset_timer (nemo_simulation_t)
Error handling
The API functions generally return an error status of type nemo_status_t. A non-zero value indicates an error. An error string describing this error is stored internally and can be queried by the user.
const char *	nemo_strerror ()

---

Detailed Description

C API for the NeMo spiking neural network simulator.

---

Typedef Documentation

typedef nemo_network_class* nemo_network_t

Only opaque pointers are exposed in the C API

typedef int nemo_status_t

Status of API calls which can fail.

---

Function Documentation

nemo_status_t nemo_cuda_device_count

(

unsigned *

count

)

Returns:

number of CUDA devices on this system.

In case of error sets device count to 0 and return an error code. The associated error message can read using nemo_strerror. Errors can be the result of missing CUDA libraries, which from the users point of view may or may not be considered an error

nemo_status_t nemo_log_stdout

(

nemo_configuration_t

)

Switch on logging and send output to stdout

nemo_status_t nemo_set_stdp_function	(	nemo_configuration_t	,
		float	prefire_fn[],
		size_t	prefire_len,
		float	postfire_fn[],
		size_t	postfire_len,
		float	min_excitatory_weight,
		float	max_excitatory_weight,
		float	min_inhibitory_weight,
		float	max_inhibitory_weight
	)

Enable spike-timing dependent plasticity in the simulation.

Parameters:

	prefire_fn	STDP function sampled at integer cycle intervals in the prefire part of the STDP window
	prefire_len	Length, in cycles, of the part of the STDP window that precedes the postsynaptic firing.
	postfire_fn	STDP function sampled at integer cycle intervals in the postfire part of the STDP window
	postfire_len	Length, in cycles, of the part of the STDP window that comes after the postsynaptic firing.
	min_excitatory_weight	Smallest positive value below which excitatory synapse weights are not allowed to fall
	max_excitatory_weight	Largest positive value above which excitatory synapse weights are not allowed to rise
	min_inhibitory_weight	Smallest (in absolute terms) negative value below which inhibitory synapse weights are not allowed to fall
	max_inhibitory_weight	Largest (in absolute terms) negative value above which inhibitory synapse weights are not allowed to rise

Note that synapses, both excitatory and inhibitory, stick at zero. I.e. once they reach zero, they never recover. If the minimum weight is non-zero, however, this will not happen.

nemo_status_t nemo_set_cpu_backend	(	nemo_configuration_t	,
		int	thread_count
	)

Specify that the CPU backend should be used and optionally specify the number of threads to use. If the default thread count of -1 is used, the backend will choose a sensible value

nemo_status_t nemo_cpu_thread_count	(	nemo_configuration_t	conf,
		int *	thread_count
	)

Returns:

the number of threads used by the CPU backend or -1 if CPU is not the selected backend.

nemo_status_t nemo_set_cuda_backend	(	nemo_configuration_t	conf,
		int	dev
	)

Specify that the CUDA backend should be used and optionally specify a desired device. If the (default) device value of -1 is used the backend will choose the best available device.If the cuda backend (and the chosen device) cannot be used for whatever reason, an exception is raised.The device numbering is the numbering used internally by NeMo This device numbering may differ from the one provided by the CUDA driver directly, since NeMo ignores any devices it cannot use.

nemo_status_t nemo_backend	(	nemo_configuration_t	conf,
		backend_t *	backend
	)

Returns:

description of the chosen backend

nemo_status_t nemo_backend_description	(	nemo_configuration_t	conf,
		const char **	descr
	)

Returns:

description of the chosen backend

nemo_status_t nemo_set_write_only_synapses

(

nemo_configuration_t

conf

)

Make the synapses write-onlyBy default synapse state can be read back at run-time. This may require setting up data structures of considerable size before starting the simulation. If the synapse state is not required at run-time, specify that synapses are write-only in order to save memory. By default synapses are readable

nemo_network_t nemo_new_network

(

)

Create an empty network object

void nemo_delete_network

(

nemo_network_t

)

Delete network object, freeing up all its associated resources

nemo_status_t nemo_add_neuron_type	(	nemo_network_t	,
		const char *	name,
		unsigned *	neuron_type
	)

Register a new neuron type with the network

Parameters:

	name	canonical name of the neuron type. The neuron type data is loaded from a plugin configuration file of the same name.
[out]	neuron_type	index of the the neuron type, to be used when adding neurons.

See also:

nemo_add_neuron

nemo_status_t nemo_add_neuron_iz	(	nemo_network_t	,
		unsigned	idx,
		float	a,
		float	b,
		float	c,
		float	d,
		float	u,
		float	v,
		float	sigma
	)

Add a single Izhikevich neuron to the network.

Deprecated:

in favour of the generic nemo_add_neuron() function

nemo_status_t nemo_add_neuron	(	nemo_network_t	,
		unsigned	type,
		unsigned	idx,
		unsigned	nargs,
		float	args[]
	)

Add a neuron to the network

Parameters:

	type	index of the neuron type, as returned by add_neuron_type
	idx	user-assigned unique neuron index
	nargs	length of args
	args	floating point parameters followed by state variables of the neuron

Precondition:

The parameter and state arrays must have dimensions matching the neuron type represented by type.

nemo_simulation_t nemo_new_simulation	(	nemo_network_t	,
		nemo_configuration_t
	)

Create a new simulation from an existing populated network and a configuration

void nemo_delete_simulation

(

nemo_simulation_t

)

Delete simulation object, freeing up all its associated resources

nemo_status_t nemo_step	(	nemo_simulation_t	,
		unsigned	fstim_nidx[],
		size_t	fstim_count,
		unsigned	istim_nidx[],
		float	istim_current[],
		size_t	istim_count,
		unsigned *	fired[],
		size_t *	fired_count
	)

Run simulation for a single cycle (1ms)

Neurons can optionally be forced to fire using fstim_nidx and fstim_count. Input current can be provided to a set of neurons using istim_nidx, istim_current, and istim_count.

Parameters:

	fstim_nidx	Indices of the neurons which should be forced to fire this cycle.
	fstim_count	Length of fstim_nidx
	istim_nidx	Indices of neurons which should receive external current stimulus this cycle.
	istim_current	The corresponding vector of current
	istim_count	Length of istim_nidx and istim_current
[out]	fired	Vector which fill be filled with the indices of the neurons which fired this cycle. Set to NULL if the firing output is ignored.
[out]	fired_count	Number of neurons which fired this cycle, i.e. the length of fired. Set to NULL if the firing output is ignored.

Returns:

NEMO_OK if operation succeeded, some other value otherwise.

nemo_status_t nemo_apply_stdp	(	nemo_simulation_t	,
		float	reward
	)

Update synapse weights using the accumulated STDP statistics

Parameters:

reward

Multiplier for the accumulated weight change

nemo_status_t nemo_get_neuron_state_n	(	nemo_network_t	net,
		unsigned	neuron,
		unsigned	var,
		float *	val
	)

Get a single state variable for a single neuron during construction

Parameters:

[in]	net	network object
[in]	neuron	neuron index
[in]	var	state variable index
[out]	val	value of the state variable

Returns:

NEMO_OK if no errors occurred. Returns NEMO_INVALID_INPUT if either the neuron or state variable indices are invalid. Other errors may also be raised. val is undefined unless the return value is NEMO_OK.

For the Izhikevich model the variable indices are 0 = u, 1 = v.

nemo_status_t nemo_get_neuron_parameter_n	(	nemo_network_t	net,
		unsigned	neuron,
		unsigned	param,
		float *	val
	)

Get a single parameter for a single neuron during simulation

Parameters:

[in]	net	network object
[in]	neuron	neuron index
[in]	param	parameter index
[out]	val	value of the state variable

Returns:

NEMO_OK if no errors occurred. Returns NEMO_INVALID_INPUT if either the neuron or parameter indices are invalid. Other errors may also be raised. val is undefined unless the return value is NEMO_OK.

For the Izhikevich model the parameter indices are 0 = a, 1 = b, 2 = c, 3 = d.

nemo_status_t nemo_get_neuron_state_s	(	nemo_simulation_t	sim,
		unsigned	neuron,
		unsigned	var,
		float *	val
	)

Get a single state variable for a single neuron during simulation

Parameters:

[in]	sim	simulation object
[in]	neuron	neuron index
[in]	var	state variable index
[out]	val	value of the state variable

Returns:

NEMO_OK if no errors occurred. Returns NEMO_INVALID_INPUT if either the neuron or state variable indices are invalid. Other errors may also be raised. val is undefined unless the return value is NEMO_OK.

For the Izhikevich model the variable indices are 0 = u, 1 = v.

nemo_status_t nemo_get_neuron_parameter_s	(	nemo_simulation_t	sim,
		unsigned	neuron,
		unsigned	param,
		float *	val
	)

Get a single parameter for a single neuron during simulation

Parameters:

[in]	sim	simulation object
[in]	neuron	neuron index
[in]	param	parameter index
[out]	val	value of the state variable

Returns:

NEMO_OK if no errors occurred. Returns NEMO_INVALID_INPUT if either the neuron or parameter indices are invalid. Other errors may also be raised. val is undefined unless the return value is NEMO_OK.

For the Izhikevich model the parameter indices are 0 = a, 1 = b, 2 = c, 3 = d.

nemo_status_t nemo_get_synapse_source_n	(	nemo_network_t	,
		synapse_id	synapse,
		unsigned *	source
	)

Get source neuron for the specified synapse during construction

Parameters:

	synapse	synapse id (see nemo_add_synapse)
[out]	source	index of source neuron

nemo_status_t nemo_get_synapse_source_s	(	nemo_simulation_t	,
		synapse_id	synapse,
		unsigned *	source
	)

Get source neuron for the specified synapse during simulation

Parameters:

	synapse	synapse id (see nemo_add_synapse)
[out]	source	index of source neuron

nemo_status_t nemo_get_synapse_target_n	(	nemo_network_t	,
		synapse_id	synapse,
		unsigned *	target
	)

Get target for the specified synapse during construction

Parameters:

	synapse	synapse id (see nemo_add_synapse)
[out]	target	index of target neuron

nemo_status_t nemo_get_synapse_target_s	(	nemo_simulation_t	,
		synapse_id	synapse,
		unsigned *	target
	)

Get target for the specified synapse during simulation

Parameters:

	synapse	synapse id (see nemo_add_synapse)
[out]	target	index of target neuron

nemo_status_t nemo_get_synapse_delay_n	(	nemo_network_t	,
		synapse_id	synapse,
		unsigned *	delay
	)

Get conduction delay for the specified synapse during construction

Parameters:

	synapse	synapse id (see nemo_add_synapse)
[out]	delay	conduction delay (in ms) of synapse

nemo_status_t nemo_get_synapse_delay_s	(	nemo_simulation_t	,
		synapse_id	synapse,
		unsigned *	delay
	)

Get conduction delay for the specified synapse during simulation

Parameters:

	synapse	synapse id (see nemo_add_synapse)
[out]	delay	conduction delay (in ms) of synapse

nemo_status_t nemo_get_synapse_weight_n	(	nemo_network_t	,
		synapse_id	synapse,
		float *	weight
	)

Get weight for a single synapse during construction

Parameters:

	synapse	synapse id (see nemo_add_synapse)
[out]	weight	synapse weight

nemo_status_t nemo_get_synapse_weight_s	(	nemo_simulation_t	,
		synapse_id	synapse,
		float *	weight
	)

Get weight for a single synapse during simulation

Parameters:

	synapse	synapse id (see nemo_add_synapse)
[out]	weight	synapse weight

nemo_status_t nemo_get_synapse_plastic_n	(	nemo_network_t	,
		synapse_id	synapse,
		unsigned char *	plastic
	)

Get boolean plasticity status for a single synapse during construction

Parameters:

	synapse	synapse id (see nemo_add_synapse)
[out]	plastic	boolean indicating whether synapse is plastic

nemo_status_t nemo_get_synapse_plastic_s	(	nemo_simulation_t	,
		synapse_id	synapse,
		unsigned char *	plastic
	)

Get boolean plasticity status for a single synapse during simulation

Parameters:

	synapse	synapse id (see nemo_add_synapse)
[out]	plastic	boolean indicating whether synapse is plastic

nemo_status_t nemo_get_synapses_from_n	(	nemo_network_t	,
		unsigned	source,
		synapse_id *	synapses[],
		size_t *	len
	)

Get synapse ids for synapses with the given source id

Parameters:

	source	source neuron id
[out]	synapses	array of synapse ids
[out]	len	length of synapses array

The output array is only valid until the next call to nemo_get_synapses_from

nemo_status_t nemo_get_synapses_from_s	(	nemo_simulation_t	,
		unsigned	source,
		synapse_id *	synapses[],
		size_t *	len
	)

Get synapse ids for synapses with the given source id

Parameters:

	source	source neuron id
[out]	synapses	array of synapse ids
[out]	len	length of synapses array

The output array is only valid until the next call to nemo_get_synapses_from

nemo_status_t nemo_set_neuron_n	(	nemo_network_t	,
		unsigned	idx,
		unsigned	nargs,
		float	args[]
	)

Modify an existing neuron during network construction

Parameters:

	idx	user-assigned unique neuron index
	nargs	length of args
	args	floating point parameters followed by state variables of the neuron

Precondition:

The parameter and state arrays must have dimensions matching the neuron type assigned to this neuron when it was created.

nemo_status_t nemo_set_neuron_s	(	nemo_simulation_t	,
		unsigned	idx,
		unsigned	nargs,
		float	args[]
	)

Modify an existing neuron during simulation

Parameters:

	idx	user-assigned unique neuron index
	nargs	length of args
	args	floating point parameters followed by state variables of the neuron

Precondition:

The parameter and state arrays must have dimensions matching the neuron type assigned to this neuron when it was created.

nemo_status_t nemo_set_neuron_iz_n	(	nemo_network_t	net,
		unsigned	idx,
		float	a,
		float	b,
		float	c,
		float	d,
		float	u,
		float	v,
		float	sigma
	)

Modify the parameters/state for a single Izhikevich neuron during construction

The neuron must already exist.

See also:

nemo_add_neuron for parameters

Deprecated:

in favour of the generic nemo_set_neuron_n() function

nemo_status_t nemo_set_neuron_iz_s	(	nemo_simulation_t	sim,
		unsigned	idx,
		float	a,
		float	b,
		float	c,
		float	d,
		float	u,
		float	v,
		float	sigma
	)

Modify the parameters/state for a single Izhikevich neuron during simulation

The neuron must already exist.

See also:

nemo_add_neuron for parameters

Deprecated:

in favour of the generic nemo_set_neuron_s() function

nemo_status_t nemo_set_neuron_state_n	(	nemo_network_t	net,
		unsigned	neuron,
		unsigned	var,
		float	val
	)

Modify a single state variable for a single neuron during construction

Parameters:

[in]	net	network object
[in]	neuron	neuron index
[in]	var	state variable index
[in]	val	new value of the state variable

Returns:

NEMO_OK if no errors occurred. Returns NEMO_INVALID_INPUT if either the neuron or state variable indices are invalid. Other errors may also be raised.

For the Izhikevich model the variable indices are 0 = u, 1 = v.

nemo_status_t nemo_set_neuron_parameter_n	(	nemo_network_t	net,
		unsigned	neuron,
		unsigned	param,
		float	val
	)

Modify a single parameter for a single neuron during construction

Parameters:

[in]	net	network object
[in]	neuron	neuron index
[in]	param	parameter index
[in]	val	new value of the parameter

Returns:

NEMO_OK if no errors occurred. Returns NEMO_INVALID_INPUT if either the neuron or state variable indices are invalid. Other errors may also be raised.

For the Izhikevich model the parameter indices are 0 = a, 1 = b, 2 = c, 3 = d.

nemo_status_t nemo_set_neuron_state_s	(	nemo_simulation_t	sim,
		unsigned	neuron,
		unsigned	var,
		float	val
	)

Modify a single state variable for a single neuron during simulation

Parameters:

[in]	sim	simulation object
[in]	neuron	neuron index
[in]	var	state variable index
[in]	val	new value of the state variable

Returns:

NEMO_OK if no errors occurred. Returns NEMO_INVALID_INPUT if either the neuron or state variable indices are invalid. Other errors may also be raised. val is undefined unless the return value is NEMO_OK.

For the Izhikevich model the variable indices are 0 = u, 1 = v.

nemo_status_t nemo_set_neuron_parameter_s	(	nemo_simulation_t	sim,
		unsigned	neuron,
		unsigned	param,
		float	val
	)

Modify a single parameter for a single neuron during simulation

Parameters:

[in]	sim	simulation object
[in]	neuron	neuron index
[in]	param	parameter index
[in]	val	new value of the parameter

Returns:

NEMO_OK if no errors occurred. Returns NEMO_INVALID_INPUT if either the neuron or state variable indices are invalid. Other errors may also be raised.

For the Izhikevich model the parameter indices are 0 = a, 1 = b, 2 = c, 3 = d.

nemo_status_t nemo_elapsed_wallclock	(	nemo_simulation_t	,
		unsigned long *
	)

Returns:

number of milliseconds of wall-clock time elapsed since first simulation step (or last timer reset).

nemo_status_t nemo_elapsed_simulation	(	nemo_simulation_t	,
		unsigned long *
	)

Returns:

number of milliseconds of simulated time elapsed since first simulation step (or last timer reset)

nemo_status_t nemo_reset_timer

(

nemo_simulation_t

)

Reset both wall-clock and simulation timer

const char* nemo_strerror

(

)

Returns:

string describing the most recent error (if any)