"cns" Function Reference

cns

The main function of the CNS framework. All interaction between MATLAB and a network model on the GPU occurs via the cns function. This includes initializing a model on a GPU, running it, getting and setting fields, etc.

Running One Model at a Time (Synchronously)

We first describe how to run CNS in its simpler mode of operation, in which (for a given instance of MATLAB) there is only a single initialized model (a single session) active at a time. In this mode, every call to the cns function causes MATLAB to wait until the operation is complete. For ease of exposition in these sections, only the single-session, synchronous syntax is given for each command.

Initializing and Deallocating
cns('init') Initialize a network model on a GPU (or CPU).
cns('test') Test initialization, displaying memory usage.
cns('platform') Change the defaults for some 'init' parameters.
cns('done') Deallocate model, freeing resources.
Getting and Setting Fields
cns('get') Retrieve fields from an initialized model.
cns('update') Retrieve all variables from an initialized model.
cns('set') Change the value of fields in an initialized model.
Running the Model
cns('run') Run an initialized model for some number of full iterations, possibly retrieving time series of some variables.
cns('step') Run an initialized model through one or more steps of a single iteration, possibly retrieving some variables.

Running One or More Models Asynchronously

CNS also allows you to write MATLAB scripts that manage multiple CNS models running concurrently and asynchronously from the main MATLAB thread. The most commmon reason to do this is to take advantage of a multi-GPU computer. Another reason is to allow MATLAB to continue working while one or more models are executing on GPUs.

General Remarks on Asynchronous Operation
Asynchronous Mode Syntax: a Multi-Session Example Script
Initializing and Deallocating Sessions
Running and Waiting
Input and Output
Other Useful Commands

cns('init')

Initializes a network model on a GPU (or CPU) using information provided in a model structure.

Syntax

cns('init', m)
cns('init', m, platform)
cns('init', m, platform, nice)

m

The model structure.

platform

One of the following (defaults to 'gpu'):

  • 'gpu' - use the first available GPU (assuming exclusive access has been set up -- if not, this is the same as 'gpu0').
  • 'gpu#' - use the specified GPU ('gpu0', 'gpu1', etc.)
  • 'cpu' - use the CPU.
  • 'debug' - use the CPU in debug mode, which enables the PRINT and ERROR macros.

nice

Applies when using a GPU. One of the following (defaults to 'nice'):

  • 'nice' - yield CPU while waiting for the GPU.
  • 'mean' - don't yield CPU while waiting for the GPU.

Notes

After calling init, you can call it again to re-initialize using a different model structure, without first calling done, as long as the new model uses the same package and the platform and nice flag do not change. Omitting the done call means you do not release the GPU, avoiding the possibility of it being claimed by another user.

The platform call can be used to change the default values of platform and nice so you do not have to provide values with every init call.

CPU mode is much slower than GPU mode, but is useful when you don't have access to a GPU, or want to use the PRINT and ERROR macros for debugging.

The mean option can be about 10% faster than nice, but it causes CPU usage to stay pinned at 100% even when the only processing is happening on the GPU, making the CPU unavailable to other processes.

Initialization sets the value of ITER_NO to 1.

cns('test')

Performs a test initialization and prints a summary of memory usage, along with any errors. This is useful for determining why an init call might be failing.

Syntax

Parameters are the same as for the init call.

Notes

The test call deallocates the model immediately, whether the initialization succeeds or not.

cns('platform')

Allows you to change the default values of some parameters to the init call so that you do not have to provide them in every init call.

Syntax

cns('platform', platform)
cns('platform', platform, nice)

platform, nice

These have the same meaning as in the init call.

Notes

The settings you provide here become the defaults for the init call. These defaults will persist until MATLAB exits.

cns('done')

Deallocates an initialized model, freeing up GPU (or CPU) resources.

Syntax

cns('done')

cns('get')

Retrieves values from one or more fields of an initialized network model. Usually you will only do this after one or more iterations or steps have been executed.

Syntax

a = cns('get', field-params)
[a, a, ...] = cns('get', {field-params}, {field-params}, ...)

field-params

Identifies a field, or a subrange of a field, to retrieve (click here for details). The number of these must match the number of outputs. The {} can be omitted when only one field/subrange is requested.

a

The value requested. The number of these outputs must match the number of field-params.

cns('update')

Updates a model structure with the current values of all variables in the active model. This allows you to save the state of a running model. If you then deallocate the model, you can use the updated model structure to reactivate it in the same state.

Syntax

m2 = cns('update', m1)

m1

The original model structure.

m2

The updated model structure.

Notes

In many situations, the updated model structure will be a lot larger than the one used to initialize the network in the first place. Variables with default values will probably no longer be at those values, and even if they were, the update call would still store separate values for every cell and synapse in the updated model structure.

cns('set')

Changes values in one or more fields of an initialized network model. Most commonly done to introduce new input data.

Syntax

cns('set', field-params, a)
cns('set', {field-params, a}, {field-params, a}, ...)

field-params

Identifies a field, or a subrange of a field, to set (click here for details). The {} can be omitted when only one field/subrange is being set.

a

The new value for the corresponding field/subrange. Its size must match that of the field/subrange, or it can be a scalar, which sets the entire field/subrange to the same value.

cns('run')

Runs an initialized model for some number of full iterations. Can also retrieve the values of variables at regular intervals as the model iterates.

Syntax

cns('run')
cns('run', iterations)

[s, s, ...] = cns('run', {field-params}, {field-params}, ...)
[s, s, ...] = cns('run', iterations, {field-params}, {field-params}, ...)
[s, s, ...] = cns('run', iterations, sampleRate, {field-params}, {field-params}, ...)
[s, s, ...] = cns('run', iterations, sampleRate, bufferSize, {field-params}, {field-params}, ...)

iterations

The number of full iterations of the model to perform. Defaults to 1.

field-params

Identifies a variable, or a subrange of a variable, to retrieve (click here for details). The number of these must match the number of outputs. By default, the variable/subrange will be retrieved at the end of each iteration; this can be changed by specifying sampleRate.

s

The value requested. The number of these outputs must match the number of field-params. Because sampling may have occurred multiple times (depending on iterations and sampleRate), each output will have an additional dimension representing the sample number. This will be dimension 1.

sampleRate

Number of iterations between each sampling of the requested variable(s). Defaults to 1.

bufferSize

By default, CNS attempts to collect all the outputs [s, s, ...] in GPU memory and transfer them back to MATLAB when the run call is complete. This is fastest, but may require more GPU memory than is available. Setting bufferSize to n means CNS will perform a GPU-MATLAB transfer whenever it has collected n samples (and any remaining samples will get transferred when the run call completes).

Notes

The run call automatically increments ITER_NO after every iteration.

cns('step')

Runs an initialized model through one or more steps of a single iteration. Can optionally retrieve the values of some variables when done.

Syntax

cns('step', step)

[a, a, ...] = cns('step', step, {field-params}, {field-params}, ...)

step

A single step number to execute, or a two-element vector indicating a range of step numbers to execute.

field-params

Identifies a variable, or a subrange of a variable, to retrieve when finished (click here for details). The number of these must match the number of outputs.

a

The value requested. The number of these outputs must match the number of field-params.

Notes

The step call does not update ITER_NO, although you may do so yourself via a set call.

Field Parameters

The get and set calls, and optionally the run and step calls, all involve identifying fields or subranges of fields.

Entire Fields

Identifying an entire field takes these two parameters.

z, field

z

The layer number, or 0 for a model-level field.

(Note: for the get and set calls only, you may pass a negative number (-g) to indicate an entire group of layers (group g). In this case, the corresponding value a returned by get will be a cell array of values, one per layer in the group. Similarly, the corresponding value a accepted by set must be a cell array.)

field

The name of the field.

Subranges

For some field classes, you can optionally identify only a subrange to retrieve or set. By "subrange" we mean:

  • A single cell, or a range of cells, instead of an entire layer.
  • Selected synapses of a synapse field.
  • Selected values of a multivalued field.

This is done using additional arguments, i.e.:

z, field, additional-arguments

These are as follows:

Field Class Optional (*) Additional Arguments
Single-Valued Multivalued
parameter none 
values
N-D array 
c1, c2, ...

values (*)
values (*), c1, c2, ...
cell field 
c1, c2, ...

values
values, c1, c2, ...
synapse field 
synapses
synapses, c1, c2, ...

values
values, synapses
values, synapses, c1, c2, ...
ITER_NO none n/a

values

Identifies certain values of a multivalued field. A scalar number indicates one value, a two-element vector indicates a range of values, and [] indicates all values. Defaults to [].

Negative indices count backwards from the number of values: -1 means the last value, -2 the second-to-last, [-3 -1] means the last three values, etc.

(*) Note: for multivalued N-D array fields, this parameter is actually required, and must be a scalar.

synapses

For synapse fields. Identifies certain synapses. A scalar number indicates one synapse, a two-element vector indicates a range of synapses, and [] indicates all synapses. Defaults to [].

c1, c2, ...

For cell and synapse fields, identifies a particular cell, or a range of cells, in layer z using from 1 to N indices, where N is the dimensionality of layer z. (See cns_iconv for an explanation of using less than N indices.) If no indices are provided, defaults to the entire layer.

Each index cn can be a scalar indicating a single position, a two-element vector indicating a range of positions, or [] indicating all positions for that dimension. Negative indices count backwards from the size of the dimension: -1 means the last position, -2 the second-to-last, [-3 -1] means the last three positions, etc.

For N-D array fields, everything is the same, except you are identifying elements of an array, not cells of a layer. If no indices are provided, defaults to the entire array.

Important restriction: CNS must be able to transfer the subrange you identify using a single CPU-GPU memory transfer operation. This imposes some limitations. For example, a subrange identifying multiple positions for an outer dimension and only certain positions for an inner dimension is not allowed.

General Remarks on Asynchronous Operation

It is increasingly common for a single computer to have more than one GPU. Since communication between the host and GPU (or between two different GPUs) is much slower than the internal memory bandwidth inside a single GPU, CNS cannot automatically decompose a single large model into parts that run on multiple GPUs. However, CNS does allow you to initialize and run multiple models simultaneously, from a single instance of MATLAB, as long as each model runs on a single GPU (on the same computer). This allows you to (manually) decompose models that are too large to run in one GPU into multiple smaller models -- as long as you are prepared to write the MATLAB code that manages communication between the parts. Asynchronous operation also allows you to instantiate the same model on multiple GPUs to increase overall throughput (this case is illustrated in the next section).

Even in single-GPU systems, asynchronous operation can help maximize use of computing resources by allowing a MATLAB script to perform (CPU-based) processing while a model is executing on the GPU.

Note 1: this functionality is currently only available under Linux or Mac OS. Your compiler must have the <pthread.h> library.

Note 2: concurrency involving multiple computers is outside the scope of CNS, but since CNS is called just like any other MATLAB program, it will be compatible with any multi-computer concurrency solution that can run MATLAB jobs.

To run one or more models asynchronously, one writes a MATLAB script that:

  • initializes the models,
  • starts them all running asynchronously, and
  • executes a loop in which MATLAB waits for one of the models to complete, at which time further actions may be taken.

This "run asynchronously and wait" model was chosen for compatibility with MATLAB's fundamentally single-threaded programming model, in which strategies like asynchronous callbacks are not allowed. An example script is shown below.

Asynchronous Mode Syntax: a Multi-Session Example Script

This script uses CNS in asynchronous mode to process images through a model using all available GPUs. Note that in this example, each GPU will be running the exact same model, but this is not required in general.

Most cns commands are the same as in the synchronous case, but with the addition of a session ID to identify which concurrently running session is being referred to. The session ID variable is shown in red below. When given as input, the session ID is always the second argument to the cns function, right after the command name ('run', 'get', etc.) There are also a few new commands (e.g. the 'wait' command) that only work with session IDs.

m     = ...; % a model structure
z_in  = ...; % number of the model's input layer
z_out = ...; % number of the model's output layer
paths = ...; % a cell array of image paths

% Create one session per GPU.  Initially none of them will be running.
% Note we are assuming the GPUs have been configured for exclusive access.
for i = 1 : cns('devcount')
    sid = cns('init', cns_newsession, m); % Initialize a new session and get its session ID.
    cns('set', sid, '$imno', 0);          % Create session property '$imno' and set it to 0.
end

next_imno = 1;
while true

    % Read the next image.  If this is not the first time through the loop, this can happen
    % while earlier images are still being processed.
    if next_imno <= numel(paths)
        im = imread(paths{next_imno});
    end

    % Wait for any session to finish processing the image it's currently working on.  If
    % we're just starting, all sessions will be waiting and the one with the lowest session
    % ID will be chosen.  When we've run out of images, code below will start closing the
    % sessions.  When there are no more open sessions, we're done.
    sid = cns('wait', 'any');
    if isempty(sid), break; end

    % Retrieve the image number the session was working on (stored in the '$imno' property).
    imno = cns('get', sid, '$imno');
    if imno > 0
        out = cns('get', sid, z_out, 'val'); % Retrieve the output.
        ...                                  % Do something useful with the output here.
    end

    % If there are still images left to process, load the next one into the waiting session
    % and start it running again.  Otherwise, close the session.
    if next_imno <= numel(paths)
        cns('set', sid, z_in, 'val', im);    % Load the input image.
        cns('set', sid, '$imno', next_imno); % Remember the image number.
        cns('run', sid);                     % Process the image (asynchronously).
        next_imno = next_imno + 1;
    else
        cns('done', sid);
    end

end

The following sections discuss asynchronous mode cns commands in more detail.

Asynchronous Mode: Initializing and Deallocating Sessions

In asynchronous mode, a session is initialized (or reinitialized) using one of these variations on the basic cns('init') command:

sid = cns('init', cns_newsession, m, ...)

sid = cns('init', sid, m, ...)

The first version creates a new session and returns the session ID. The second version is used to re-initialize an existing session with a new model structure. Other arguments (not shown here) are identical to those in the basic cns('init') command. Note that setting exclusive access can be very helpful when working with multiple sessions.

The cns_newsession function can be used to preallocate an array of session IDs, like this:

sids = cns_newsession(1, 4);
for i = 1 : 4
    sids(i) = cns('init', cns_newsession, m, ...);
end

Sessions can be closed using the following commands:

cns('done', sids)
cns('done', 'all')

Where:

  • sids is an array of zero or more session IDs
  • 'all' means close all active sessions

Asynchronous Mode: Running and Waiting

The asynchronous versions of cns('run') and cns('step') are:

cns('run', sid, ...)
cns('step', sid, ...)

Aside from the session ID, all the arguments are the same as in the synchronous case, except that there can be no output arguments. You can still request variables to be retrieved (i.e. you can still specify field-params), but if you supply output arguments, then CNS will block your MATLAB script until the 'run' or 'step' call is complete -- i.e. the call will not be asynchronous. If you want the call to return immediately so that your MATLAB script can move on to do something else while the 'run' or 'step' call executes, you have to omit the output arguments. You can pick up any outputs later using a cns('output') call.

Once you have issued an asynchronous 'run' or 'step' call for a session, making any other cns call for that session (for example, a 'get' or 'set' call) will implicitly cause MATLAB to stop and wait for the previous asynchronous call to complete.

Waiting can be explicitly controlled using the following commands, both of which block MATLAB until at least one of a list of sessions completes its work:

sid = cns('wait', sids)
sid = cns('wait', 'any')

The first version waits for any of a list of sessions whose IDs you supply; the second waits for any active session. The return value will be the ID of the first session of interest to complete. (If sids is empty, or there are no active sessions, the return value will be empty.)

The following commands are similar, except that there is no waiting; these calls always return immediately:

sid = cns('poll', sids)
sid = cns('poll', 'any')

Here, if any of the sessions of interest have completed, the return value will be one of their IDs; otherwise the return value will be empty. It is an error to call this function with sids empty or with no active sessions.

Asynchronous Mode: Input and Output

As mentioned above, there is one additional output command that applies to asynchronous mode. It is used to retrieve any outputs requested by an asynchronous cns('run') or cns('step') command.

[s, s, ...] = cns('output', sid)
[a, a, ...] = cns('output', sid)

The number of output parameters must match the number of outputs requested in the 'run' or 'step' call.

The other input/output commands ('get', 'update', and 'set') all have identical syntax to their synchronous counterparts, except that the second argument is a session ID. All these commands, and the 'output' command, implicitly cause MATLAB to wait if the session is still executing.

Asynchronous Mode: Other Useful Commands

When working asynchronously with multiple sessions, you usually need to keep track of what you asked a given session to do so that you can respond appropriately when it completes. It's helpful to be able to 'tag' a session with some piece of data. This is illustrated in the example above, where we associate a '$imno' (image number) property with every session. This information doesn't need to be propagated over to the GPU; it just needs to be available from within MATLAB. Such 'session properties' can be set and retrieved as follows:

        cns('set', sid, propname, value)
value = cns('get', sid, propname)

Here, propname must be a string starting with '$', such as our '$imno' example.

The following call reports the number of devices (e.g. GPUs) your computer has:

count = cns('devcount')
count = cns('devcount', platform)

The first version reports this number for the currently selected platform ('gpu' by default). The second version reports this number for the platform you supply.

if the platform is: count will be:
'gpu' the number of GPUs in the computer
'gpu#' 1
'cpu' or 'debug' inf

The following call returns a vector of session IDs for all active sessions:

sids = cns('sessions')

Finally, this last call is useful when you have multiple sessions and:

  • you need to call some MATLAB code that itself makes cns calls, but
  • the code you need to call does not accept a session ID as an argument.

The 'use' call allows you to set a session ID that will be used by cns calls that do not pass a session ID explicitly. The affected calls are init, done, get, update, set, run, and step. The following three commands allow you to set, clear and retrieve this session ID.

      cns('use', sid)
      cns('use', 'none')

sid = cns('use')

cns_build

Compiles a package of cell types so that it can be used to build network models. Packages must be compiled whenever files in the package directory change.

Can also produce several other outputs that help in package development. All outputs go into the package directory.

Syntax

cns_build package
cns_build package action

package

The package name. cns_build will locate the package by looking for a file called package.m in your MATLAB path.

action

One of the actions in the table below. Defaults to compile.

Action Description Output Files
compile Compiles the package. Generates two MATLAB "mex" files, one for GPU execution and one for CPU execution. 
package_compiled_*.mex*
help Generates a text file listing all available CNS macros for each cell type. 
package_compiled_help.txt
info Generates a text file showing GPU compilation details for each kernel. This can be useful for determining if your kernels are written (and being compiled) efficiently. Click here for details on interpreting this file. 
package_compiled_cuda_info.txt
generate For the curious. Generates all the same temporary files that are normally generated during the compile process, but just leaves them in the package directory without compiling them. 
package_generated_*
preprocess Also for the curious. Performs the compile process up to and including the C++ preprocessor step, but does not perform the final compilation into object code. Interesting if you want to see what all the macros expand into. 
package_compiled_*_pre.*
clean Deletes any of the above compilation outputs from the package directory. n/a

Interpreting GPU Compilation Details

The file package_compiled_cuda_info.txt, produced by the info option, will contain a section like this for every kernel:

code {
    name = _Z11_kernel_maxjjPKf9_OutTablejjjPK7ushort4PK10_LayerData
    lmem = 0
    smem = 224
    reg  = 22
    bar  = 1
    const {

The three useful pieces of information are highlighted:

  1. The type name. (In this example, "max".)
  2. The amount of local memory the kernel uses. This is a misnomer on NVIDIA's part: "local memory" in their terminology refers to memory a kernel uses for local calculations that does not fit into registers. It is actually in main GPU memory, which has high latency. You want this number to be zero. (In this example, it is.) A common way this number gets to be nonzero is when you declare local C++ arrays in the kernel. Consider using CNS's alternative fast local arrays instead.
  3. The number of registers the kernel uses. Lower is better, because it means you can make the block size larger.

The file also contains a lot of other junk which you can ignore.

cns_call

Calls the appropriate MATLAB method for an existing layer or group. This is safer than calling the method directly; see notes.

Syntax

[out1, out2, ...] = cns_call(m,  z, method, arg1, arg2, ...)
[out1, out2, ...] = cns_call(m, -g, method, arg1, arg2, ...)

m

A model structure. This will be passed as the method's first argument.

z

A layer number. The method will be called with arguments (m, z, arg1, arg2, ...).

g

A group number. The method will be called with arguments (m, g, arg1, arg2, ...). Note the "-" sign to distinguish g from a layer number. It is removed before calling the method itself.

method

The method name.

arg1, arg2, ...

Any additional inputs. Depends on the particular method.

out1, out2, ...

Any outputs. Depends on the particular method.

Notes

Using cns_call is preferable to calling the method directly, like this:

package_type.method(m,  z, arg1, arg2, ...)
package_type.method(m, -g, arg1, arg2, ...)

because if the layer (or group) is a subtype of type which overrides method, cns_call will correctly call the subtype's implementation of the method.

cns_center

Returns the position in common coordinate space of a cell along a particular dimension. This is a floating point number.

Syntax

p = cns_center(m, z, dim, c)

m

A model structure.

z

The layer number.

dim

The dimension name or number.

c

Index (along this dimension) of the cell in layer z.

p

The resulting common coordinate position.

Notes

The equivalent kernel macro is type_dim_CENTER.

cns_fltmax

Returns the largest single-precision floating point number.

Syntax

cns_fltmax

cns_fltmin

Returns the smallest single-precision floating point number.

Syntax

cns_fltmin

ns_getconsts

Retrieves the values of compile-time constants that apply at the scope of a model, layer, or group (based on the package and cell type).

Syntax

[v, v, ...] = cns_getconsts(m, n, name, name, ...)
s = cns_getconsts(m, n)
s = cns_getconsts(m, n, nameList)

m

A model structure.

n

  • A positive number indicates a layer.
  • A negative number indicates a group.
  • Zero indicates model scope.

name

The name of a constant (at the scope defined by n) whose value you want to retrieve.

v

The value of the corresponding constant.

nameList

A cell array of constant names (at the scope defined by n) whose values you want to retrieve. Defaults to all valid constants.

s

A structure with one field per name in nameList (or all valid constants if nameList is not provided), where the value of each such field is the value of the corresponding constant.

cns_getdflts

Fills in any default values for fields not explicitly given values in a model structure.

Note: internally, cns('init') does this automatically, so you do not need to explicitly call this function yourself. It is provided in the event you want to write MATLAB code that accesses these values -- or if you just want to inspect them.

Syntax

m = cns_getdflts(m)
m = cns_getdflts(m, n)

m

A model structure.

n

Indicates what part of the model structure to fill in defaults for.

  • A positive number indicates a layer.
  • A negative number indicates a group.
  • Zero indicates model scope.
  • If n is omitted, fill in defaults for the entire structure (model scope plus all layers and groups).

cns_getknownfields

Shows you which information in a model structure is actually known to CNS -- as opposed to additional information that may have been stored there.

Syntax

[k, u] = cns_getknownfields(m)

m

A model structure.

k

The same model structure but with any non-CNS information removed.

u

Contains any information from m that was not known to CNS.

cns_findwithin

Finds a range of indices of other cells that are within a certain radius of a given cell in common coordinate space along a particular dimension.

Syntax

[v1 v2]          = cns_findwithin(m, z, dim, c, pz, r)
[v1 v2 ok]       = cns_findwithin(m, z, dim, c, pz, r)
[v1 v2 c1 c2]    = cns_findwithin(m, z, dim, c, pz, r)
[v1 v2 c1 c2 ok] = cns_findwithin(m, z, dim, c, pz, r)

m

A model structure.

z

The layer number of the given cell.

dim

The dimension name, or its number in layer z.

c

Index (along this dimension) of the given cell in layer z.

pz

Layer number in which we are searching for cells.

r

The radius within which we are searching for cells. Expressed in units of the common coordinate space along this dimension. A floating point value.

v1, v2

Range of indices of the found cells along this dimension in layer pz. These are guaranteed to be valid indices, i.e., between 1 and the dimension size. The range may be empty.

c1, c2

These are the same as v1 and v2 except they are not guaranteed to be valid -- they can be less than 1 or greater than the dimension size. (This usually happens close to an edge.) Essentially, these are the indices that correspond to the search we performed, but they are not necessarily the indices of actual cells.

ok

When only v1 and v2 are returned, ok is true iff (v1 == c1) and (v2 == c2). When both ranges are returned, ok is true iff the range (v1 - v2) is not empty.

Notes

The equivalent kernel macro is FIND_type_dim_WITHIN.

cns_findwithin_at

Finds a range of indices of cells that are within a certain radius of a specified point in common coordinate space along a particular dimension.

Syntax

[v1 v2]          = cns_findwithin_at(m, pz, dim, p, r)
[v1 v2 ok]       = cns_findwithin_at(m, pz, dim, p, r)
[v1 v2 c1 c2]    = cns_findwithin_at(m, pz, dim, p, r)
[v1 v2 c1 c2 ok] = cns_findwithin_at(m, pz, dim, p, r)

m

A model structure.

pz

Layer number in which we are searching for cells.

dim

The dimension name, or its number in layer pz.

p

Position in common coordinate space (along this dimension), relative to which we are searching. A floating point value expressed in the units of the common coordinate space.

r

The radius within which we are searching for cells. Expressed in units of the common coordinate space along this dimension. A floating point value.

v1, v2

Range of indices of the found cells along this dimension in layer pz. These are guaranteed to be valid indices, i.e., between 1 and the dimension size. The range may be empty.

c1, c2

These are the same as v1 and v2 except they are not guaranteed to be valid -- they can be less than 1 or greater than the dimension size. (This usually happens close to an edge.) Essentially, these are the indices that correspond to the search we performed, but they are not necessarily the indices of actual cells.

ok

When only v1 and v2 are returned, ok is true iff (v1 == c1) and (v2 == c2). When both ranges are returned, ok is true iff the range (v1 - v2) is not empty.

Notes

The equivalent kernel macro is FIND_type_dim_WITHIN_AT.

cns_findnearest

Finds a range of indices of other cells that are the n nearest neighbors of a given cell in common coordinate space along a particular dimension.

Syntax

[v1 v2]          = cns_findnearest(m, z, dim, c, pz, n)
[v1 v2 ok]       = cns_findnearest(m, z, dim, c, pz, n)
[v1 v2 c1 c2]    = cns_findnearest(m, z, dim, c, pz, n)
[v1 v2 c1 c2 ok] = cns_findnearest(m, z, dim, c, pz, n)

m

A model structure.

z

The layer number of the given cell.

dim

The dimension name, or its number in layer z.

c

Index (along this dimension) of the given cell in layer z.

pz

Layer number in which we are searching for cells.

n

The number of nearby cells we want to find.

v1, v2

Range of indices of the found cells along this dimension in layer pz. These are guaranteed to be valid indices, i.e., between 1 and the dimension size. The range may be empty.

c1, c2

These are the same as v1 and v2 except they are not guaranteed to be valid -- they can be less than 1 or greater than the dimension size. (This usually happens close to an edge.) Essentially, these are the indices that correspond to the search we performed, but they are not necessarily the indices of actual cells.

ok

When only v1 and v2 are returned, ok is true iff (v1 == c1) and (v2 == c2). When both ranges are returned, ok is true iff the range (v1 - v2) is not empty.

Notes

The equivalent kernel macro is FIND_type_dim_NEAREST.

cns_findnearest_at

Finds a range of indices of cells that are the n closest to a specified point in common coordinate space along a particular dimension.

Syntax

[v1 v2]          = cns_findnearest_at(m, pz, dim, p, n)
[v1 v2 ok]       = cns_findnearest_at(m, pz, dim, p, n)
[v1 v2 c1 c2]    = cns_findnearest_at(m, pz, dim, p, n)
[v1 v2 c1 c2 ok] = cns_findnearest_at(m, pz, dim, p, n)

m

A model structure.

pz

Layer number in which we are searching for cells.

dim

The dimension name, or its number in layer pz.

p

Position in common coordinate space (along this dimension), relative to which we are searching. A floating point value expressed in the units of the common coordinate space.

n

The number of nearby cells we want to find.

v1, v2

Range of indices of the found cells along this dimension in layer pz. These are guaranteed to be valid indices, i.e., between 1 and the dimension size. The range may be empty.

c1, c2

These are the same as v1 and v2 except they are not guaranteed to be valid -- they can be less than 1 or greater than the dimension size. (This usually happens close to an edge.) Essentially, these are the indices that correspond to the search we performed, but they are not necessarily the indices of actual cells.

ok

When only v1 and v2 are returned, ok is true iff (v1 == c1) and (v2 == c2). When both ranges are returned, ok is true iff the range (v1 - v2) is not empty.

Notes

The equivalent kernel macro is FIND_type_dim_NEAREST_AT.

cns_groupno

Finds group numbers in a model structure by group name.

Syntax

Finding a Single Group Number

g = cns_groupno(m, name)
g = cns_groupno(m, name, err)

m

A model structure.

name

A group name. Can also be a group number, in which case it will just be validated.

err

Affects what happens if the group name cannot be found in m. If true, will halt with an error. If false, will cause g to return 0. Defaults to true.

g

The group number if found. If not found, and err is false, will return 0.

Finding All Group Numbers

s = cns_groupno(m)

m

A model structure.

s

Returns a structure with one field per group name, where the value of each such field is the group number.

cns_iconv

Converts cell indices between representations of different dimensionality, e.g., between N-D indices and 1-D (linear) indices.

In MATLAB, elements of an N-D array can be accessed using any number of indices from 1 to N. When using D < N indices, the dimensions (D : N) are treated as a single dimension, indexed by the Dth index. This can be quite useful.

This function is a generalization of MATLAB's sub2ind and ind2sub functions. cns_iconv converts indices between any two representations (D1 ≤ N) and (D2 ≤ N).

Syntax

[j1, j2, ...] = cns_iconv(m, z, i1, i2, ...)

m

A model structure.

z

The layer number.

i1, i2, ...

The indices of a cell in layer z. From 1 to N numbers, where N is the dimensionality of the layer. These can also be arrays (for multiple cells), but must all be of the same size.

j1, j2, ...

The indices of the same cell using a (presumably different) dimensionality representation. The output dimensionality is determined by the number of outputs. For multiple cells, each j will be the same size as the i inputs.

cns_install

Creates some internal CNS binaries. Only needs to be done once, at CNS installation time.

The main cns directory must already be in your MATLAB search path; see cns_path.

Syntax

cns_install

cns_intmax

Returns the largest integer CNS can accurately represent.

Syntax

cns_intmax

cns_intmin

Returns the smallest integer CNS can accurately represent.

Syntax

cns_intmin

cns_layerno

Finds layer numbers in a model structure by layer name.

Syntax

Finding a Single Layer Number

z = cns_layerno(m, name)
z = cns_layerno(m, name, err)

m

A model structure.

name

A layer name. Can also be a layer number, in which case it will just be validated.

err

Affects what happens if the layer name cannot be found in m. If true, will halt with an error. If false, will cause z to return 0. Defaults to true.

z

The layer number if found. If not found, and err is false, will return 0.

Finding All Layer Numbers

s = cns_layerno(m)

m

A model structure.

s

Returns a structure with one field per layer name, where the value of each such field is the layer number.

cns_mapdim

For dimensions of a layer that are mapped to a common coordinate space, this is the main function used to determine layer size and assign common coordinates along those dimensions. This can be done in many different ways.

Syntax

m = cns_mapdim(m, z, dim, mode, mode-specific-args)

m

A model structure.

z

The layer number for which we are determining the size and common coordinates (along some dimension).

dim

The name or number of the dimension (of layer z) for which we are determining the size and common coordinates.

mode

Identifies the particular method we will use; see the table below.

mode-specific-args

Additional arguments depending on the mode; see the table below.

Mode Description and Additional Arguments
'pixels' Sets the dimension size to an arbitrary number, and assigns common coordinates so that the cells (pixels) fill the interval [0, 1]. The only additional argument is:

size

size

A positive integer.
'scaledpixels' This is similar to 'pixels' except that the dimension size is given as a scaled-down version of a base size. If the base size is odd, the resulting dimension size is guaranteed to be odd, no matter what the scale factor. Similarly, an even base size will always result in an even dimension size. All this is done so that multiple layers which represent different rescalings of an image will all have the same form -- either they will all have a central cell, or none will. The additional arguments are:

baseSize, factor

baseSize

A positive integer.

factor

The scale factor. A floating-point number greater than or equal to 1.
'copy' Copies settings for this dimension from another layer. Layer z will have the same number of cells, at the same common coordinate positions, as layer pz. The only additional argument is:

pz

pz

The layer number to copy settings from.
'int' Sets up layer z as the result of a valid "convolution" of another layer pz with a filter. (It's not strictly convolution because the filter can move across layer pz in steps of 1 or greater. This is illustrated nicely here.) Ensures that the resulting layer z will always be symmetric about the center -- any losses at the edges will be the same at both edges. The additional arguments are:

pz, rfSize, rfStep, rfMargin, parity

pz

The layer number which is the input to the convolution.

rfSize

The size of the filter (a positive integer). Can also be inf, indicating that the filter represents a global pooling operation -- in this case the resulting layer z will have size 1.

rfStep

The step size with which the filter moves across layer pz. A positive integer. Ignored if rfSize is inf.

rfMargin

Defaults to 0. A positive (integer) value tells cns_mapdim to ignore that many units at either edge of layer pz. A negative (integer) value allows the convolution to go "over the edge" by that many units. Ignored if rfSize is inf.

parity

There are two ways the resulting layer can be symmetric about the center: it can have a single unit in the center, or two units equally far from the center on opposite sides. Sometimes only one of these is possible. When both are possible, this optional parameter controls the decision.

  • 1 - odd parity. Place a unit in the center.
  • 0 - even parity. Place two units equally far from the center on opposite sides.
  • [] - maximize the number of units in the resulting layer. (The default.)
'int-td' This is the top-down version of 'int'. Here, layer pz is treated as the result of the convolution, and we're setting up layer z so that it will be large enough to produce layer pz as a result. The additional arguments are:

pz, rfSize, rfStep

pz

The layer number which is the output of the convolution.

rfSize

The size of the filter (a positive integer). Cannot be inf.

rfStep

The step size with which the filter moves across layer z. A positive integer.
'win' TODO. The additional arguments are:

pz, rfSize, rfStep, rfMargin, parity

pz

TODO.

rfSize

TODO. A positive floating-point number. Can be inf.

rfStep

TODO. A positive floating-point number.

rfMargin

TODO. Any positive or negative floating-point number.

parity

TODO.

cns_path

Adds all CNS's directories to your MATLAB search path. Meant to be called from your startup.m file.

Syntax

run path/cns_path

path

A path identifying the main cns directory. Must be valid from wherever startup.m is executed.

cns_rename

Renames a package by renaming files in the package directory.

Syntax

cns_rename oldname newname
cns_rename oldname newname subdir1 subdir2 ...

oldname

The current package name. cns_rename will locate the package by looking for a file called oldname.m in your MATLAB path.

newname

The new name for the package.

subdir1 subdir2 ...

By default, cns_rename only renames files in the package directory itself. Here you may optionally add any subdirectories in which you also want files to be renamed. These are assumed to be relative to (i.e. underneath) the package directory.

Notes

All files in the package directory (and any subdirectories you specify) that start with oldname_ will be renamed to start with newname_. The function line inside each ".m" file is also updated.

Any references to the old function names that may exist in function bodies are not updated.

The package directory itself is not renamed.

cns_setstepnos

Automatically determines the execution order of layers for feedforward models.

Syntax

m = cns_setstepnos(m, mode, mode-specific-args)

m

A model structure.

mode

Selects the method that will be used to figure out the execution order; see the table below. (Currently the only option is 'field'.)

mode-specific-args

Additional arguments depending on the mode; see the table below.

Mode Description and Additional Arguments
'field' Assumes that all layer-layer dependencies are encoded by one or more pointer fields (class 'lz') defined at the base level. The only additional argument is:

field

field

The name of a single pointer field, or a cell array of names.

Notes

It may also be appropriate to set the independent flag for your model.

cns_splitdim

Shows how CNS will automatically factor a split dimension of a given size.

Syntax

s = cns_splitdim(n)
s = cns_splitdim(n, numParts)

n

The size of the dimension to be factored.

numParts

The number of parts into which it will be factored. Defaults to 2.

s

The resulting sizes.

cns_super

Used by a MATLAB method in a subtype to call the same method in a supertype.

Syntax

[out1, out2, ...] = cns_super(arg1, arg2, ...)

arg1, arg2, ...

Any inputs. Depends on the particular method.

out1, out2, ...

Any outputs. Depends on the particular method.

cns_trace

Traces pathways through a network formed by explicit synapses.

Starting with a cell (or cells) in a specific layer, we find all cells in a target layer that can be reached by following a specific sequence of layer-layer jumps.

Syntax

[j1, j2, ...] = cns_trace(m, z, path, i1, i2, ...)

m

A model structure.

z

The layer number containing the starting cell(s).

path

A vector of layer numbers representing a sequence of jumps. A positive number represents a forward jump (pre-to-postsynaptic), and a negative number represents a backward jump (post-to-presynaptic). The (absolute value of) the last element is the target layer. For example, [-3 4] means a backward jump to layer 3 and then a forward jump to layer 4; the output cells will be in layer 4.

i1, i2, ...

Indices of one or more starting cells in layer z. You can specify these indices using from 1 to N dimensions, where N is the dimensionality of layer z (see cns_iconv for an explanation of N-D indices). i1 will contain index 1 for all starting cells, i2 will contain index 2 for all starting cells, etc.

j1, j2, ...

Indices of the resulting cells in the target layer, represented using from 1 to M dimensions, determined by the number of outputs, where M is the dimensionality of the target layer. j1 will contain index 1 for all result cells, j2 will contain index 2 for all result cells, etc.