sandialabs/n2a

An object-oriented language for modeling large-scale neural systems, along with an IDE for writing and simulating models.

Overview

"Neurons to Algorithms" (N2A) is a language for modeling neural systems, along with a software tool for editing models and simulating them. For an introduction to the concepts behind N2A, see the paper N2A: a computational tool for modeling from neurons to algorithms. For the current definition of the language, see the Language Reference page on our wiki.

N2A conceives of each neural component ("part" or "model") as a bundle of attributes, which include constants and equations. All attributes and dynamics are name-value pairs. In the case of equations, the name is a variable and the value tells how that variable relates to other variables and changes through time.

Because models are specified as data rather than code (declarative rather than imperative), it is easy for one model to inherit from another and extend it. In particular, there is no distinction between part definitions (such as an Izhikevich Neuron) and parameters used in a specific configuration. You simply inherit the model and make any necessary changes.

A model may contain other models. For example, a cerebellum model may contain population models for Purkinje cells, inferior-olive cells, and so on. The cerebellum model could be further incorporated into a model of smooth pursuit involving multiple brain regions. The goal of N2A, of course, is to eventually model the entire brain.

Some things N2A is NOT:

• Not a simulator. Rather, the tool compiles the language for a given target (NEURON, NEST, C++, Python, etc.).
• Not deep learning, nor machine learning in general. The goal of N2A is to build an integrated understanding of the whole brain, in a form that can be both analyzed and computed.

Download

Installation -- How to download and install N2A, and set up at least one simulator.

Getting Started -- Run a simple "Hello World" example: the Hodgkin-Huxley cable equations.

Contributing Code -- How to set up a development environment, if you would like to volunteer on this project or simply wish to build from source.

Documentation

The wiki contains language documentation plus several guides and other information about the software package.

n2a's Issues

Direct click does not highlight selected node

This is probably a repaint issue, as subsequent keyboard navigation acts as if the node was selected. It also seems to occur when the previous selection and new selection are farther apart in the tree. Solution is probably to call paintImmediately() on both the old and new selection.

Clean up and re-enable job control

Clean up parameter variation GUI.
Clean up class names: ExecutionEnv --> Host
Create FileSystemProvider for each type of remote system. Funnel data transfer through nio.Files interface.
Ensemble is a collection of both potential and actual (completed or active) runs. The real goal of Ensemble is analysis across multiple runs, rather than simply generating them, so it is acceptable to collect existing runs that satisfy the analysis criteria.

C Backend -- support arbitrary n-arity in connections

Right now the implementation assumes connections are always between exactly two populations. Arities of 1 and 3+ should be supported as well.

Xyce: update and test

The most recent update of the Xyce backend (which is several years old as of this writing) is not fully tested/operational. In addition, the last update lost a mechanism for re-using some expressions once they were emitted. Need to go back through previous version of code and try to restore that capability, in order to generate more compact netlists.

Language: Cleaner parsing of UCUM syntax

This issue is labeled as a bug because it address something that causes unexpected behavior for users.

Right now the parser only reserves a small handful of characters that cause it to leave units mode. This is creating some conflict, for example with a + operator immediately following a unit expression. A better approach would be to further limit the UCUM syntax so that anything that could start another token causes the parser to exit units mode. We can still support full UCUM within parenthesis.

With this in mind, it may be better to fully integrate the UCUM parsing, rather than treating it as a kind of escape sequence. The one awkward aspect of UCUM parsing is that unit prefixes depend on table lookup, rather than purely lexical rules. It may be possible to tokenize prefix and unit atom together, then separate them later when the unit is converted.

Vertical divider on Models tab creeps right

By a couple of pixels each time the program starts. Something is wrong with the offset calculations.

Add references tab

For maintaining links to the literature. This feature used to be in the tool, but needs to be rewritten for the new GUI.

Language -- Redefine gaus() and uniform() to take matrix as well as scalar inputs

The output of these random number generator functions should have a form determined by the input. Scalar input indicates the standard deviation (sigma) of the distribution of the scalar outputs. A vector indicates scaling for vector output. A matrix input would apply an affine transformation to the random numbers. In all cases, the input is simple scaling (sigma), not covariance (sigma^2).

This is merely a convenience to make the math more tidy, as it is currently possible to apply the scaling outside the function. However, specifying both the dimension and scaling is extra work, when dimension is implied by scaling.

Allow only valid parts name in equation tree

Parts may be added by CCP, DnD, and direct entry. In all of these cases, the name of the part should be a valid identifier (like a variable name), such that it can be used in expressions. Right now, the UI lets just about anything in. The one exception is the root node, which is the name of a model in the repository. This may be arbitrary, as long as it is a valid file name (some restrictions apply).

Remember currently selected node in a model

So that when a user switches models during a session, the focus goes back to the last point they were working on. May also make sense to remember the entire open/closed state for all nodes in the equation tree, but this seems less necessary.

Replace $live with $connect

Currently, the connection probe phase is indicated by $live=0 && $init=1. This is both awkward and ugly. Instead, indicate a connection probe with $connect=1 (with $init=0). Thus, each of the startup phases would have exactly one predicate that is true, and in normal operation all predicates are false. Furthermore, the connection probe is explicitly indicated, rather than implied, and has nothing to do with whether the part exists independently or not.

Remove javax.measure from codebase

Instead, use external libraries from https://github.com/unitsofmeasurement

Double-click on expansion handle causes edit on bogus node in equation tree

The double-click seems to get interpreted twice, once to change expansion and again to initiate edit. However, the position where the edit is initiated and the node it is initiated on do not match, producing a horrific user experience.

One solution may be to simply not interpret double-click as edit. Alternately, filter the position so it only initiates edit if it is directly over a tree cell, rather than the expansion handle.

Use double-click to open a model

Right now, a single click in the model list opens the model and switches focus to the equation tree panel. Because there are uses for keeping the focus in the model list, it might make sense to require a double click to shift focus.

The MRU list can remain single-click.

This could be made a user preference.

Internal Backend -- support arbitrary n-arity in connections

Right now the implementation assumes connections are always between exactly two populations. Arities of 1 and 3+ should be supported as well.

For unary connections, the system will simply scan the target population, evaluating one possible connection for each target instance. Note that in the case of self-connection (targeting the connection's own population), the connection instance will exist regardless of the evaluation result.

Give parts a UUID, and use it to relink inherited parts when name changes

At present, parts are only identified by their name. If their name changes, $inherit links are broken. If each part has a UUID that doesn't change, then it can be relocated by searching the DB. Linking can still be done primarily by name, as this is more user-friendly. Relink will only be done if name-based linking fails, or if retrieved part does not match the previously noted UUID.

This is necessary for 1.0 release, because once the base library goes public, it will become more sensitive to changes.

Cleaner error reports for simulation runs

There are multiple issues with error reporting:

• Parse error appear as a java exception. Should show the offending line with a caret under it marking the position.
• Should show all parse errors for a model, not just the first one. This should happen simply by not throwing a java exception anymore.
• In general, clean up any places in the backends where an exceptions are still being thrown, and change them to proper messages. Java exceptions should be reserved for true failures in the code, rather than user errors.
• List of missing variables should be horizontal rather than vertical (comma delimited rather than line delimited).

Better UI for equation filtering

There are several sub-issues:

• Filter setting should persist across runs of the app.
• Icon on the filter button should indicate filter state. This can help prevent confusion when equations are seemingly missing.
• Remember the full open/close state of the tree, so that changing filter state does not punish the user.

Option to lock library models so they can't be accidentally modified

This could be implemented as a metadata tag. In addition, it would be good if there's a user preference setting that turns the mode on/off. That way, library maintainers can add the tag, but still be able to edit.

Internal Backend -- immediately finalize variables touched by a "zero delay" event

Currently, Internal only updates parts that directly receive zero-delay events. However, those parts may modify variables in other parts. It takes another cycle for these secondary changes to become visible. Updating the secondary variables will be expensive, but will make the zero-delay events behave more as one might expect.

Internal Backend -- Add spatial filtering

Although spatial filtering is entirely optional (only $p matters in making connections), Internal should be thorough is supporting language features.

Add options tab

Various settings are currently hard-coded which should be user-settable. For example, the path to the compiler used by the C backend.

Resize font does not update row height in table

On the Runs tab, the table format ends up with larger font, but rows too short to fit that font.

NeuroML backend

Enable bridging to all simulators supported by jNeuroML

Undo/Redo in equation tree

Improve mouse interaction with graphs

JFreeChart has a non-intuitive assignment of functions to mouse buttons, which makes it difficult to work with the graphs. If possible, remap them:

• Button 3 -- context menu (same as now)
• Button 2 drag -- select zoom region
• Scroll wheel (buttons 4 and 5) -- zoom
• Button 1 drag -- pan

App stalls sometimes during launch

Occurs during the call to mainframe.setVisible(). Probably due to a race condition in loading the Model tab.

Cut/Copy/Paste in equation tree

Specifically at the node level. (There is already support for cut/copy/paste of text inside a given equation.)

Support event() for global variables

In general, a global variable on LHS does not necessarily mean the expression should be evaluated at the population level. If the RHS references local variables, the equation should be evaluated within a local instance, and perhaps combine results in the population part as if by external reference.

This issue is specifically about population-level equations, rather than instance-level equations that happen to update population-level variables. At present there is no mechanism (in Internal or C) to trigger a population-level event.

Revoke inherited equations

In the current inheritance system, it is possible to change the value of an equation for a multi-conditional variable, but it is not possible to get rid of a particular condition. Sometimes it is necessary to remove some conditions when adapting the logic of a model.

One possible solution is to use a special value, such as $revoke. Another is to simply treat any entry with a blank value as revoked, rather than assuming some default value such as 0. The blank-entry approach is the most appealing due to its efficiency. One downside of the blank-entry approach is that it can only suppress individual conditions, not an entire multi-line variable. If the latter is ever truly necessary, we could also use $revoke.

How to process revoked entries:

• MPart collation -- No real change of processing. Blank entry overrides inherited value, and remains blank unless overridden by another value.
• Preparing for execution -- Completely remove the equation from the set. If this is a single-line variable, remove the variable. One consequence is that a variable might not get resolved. This is an error which the user must correct.
• View filtering -- Blank entries are hidden except when filter=All.
• Editing -- User is allowed to set variable=. This may cause it to disappear due to filtering. This is different than setting/leaving an entire line blank. That case is the same as deleting the line, not simply setting it to blank. This means that it could expose an inherited value (blank or non-blank).

When equation tree entry loses focus, its value should be saved rather than discarded.

Internal Backend -- iterate over arbitrarily nested populations

Currently, Internal only supports first level of nesting when generating connection candidates. Should iterate over number of container.

Add line comments back into grammar

It would be helpful to put comments on the end of equation lines, particularly multi-line equations, where each condition might merit a separate comment. For simplicity, use # as the comment character.

This will require more careful (and perhaps slower) parsing of equation lines. In particular, a hash appearing inside quote marks should be treated as quoted text rather than the start of a comment. The same issue applies to the @ sign that marks conditions.

It would be safe to comment out an entire line. A single-line equation will simply be a blank assignment, which is equivalent to assigning zero. A blank equation should be treated similarly to a revocation. The condition should be completely removed from the list of cases for that variable. The main difference between a commented-out line and a revocation is that the condition remains visible and its contents is not lost.

Add a button to stop a running simulation

Paste new $metadata item does not update tab stops

Prevent pasting serialized parts into text fields

The uses a string flavor to put serialized parts on the clipboard. This allows easy import/export to email and other apps, but it also means that text fields will paste in the data. There is a SafeTextTransferHandler that prevents this, but it is not set up on all text fields yet.

Multi-line editing for long text fields in equation tree

Repaint is deficient on Jobs tab

The Jobs tab suffers from the same Swing repaint issues as the rest of the application (but these have largely been corrected on the Models tab). Specific problems:

• The view pane doesn't refresh as soon as it should.
• The UI thread seems to stall waiting to display a very complicated graph. It should continue to respond while the graph is rendered in the background.
• When a job finishes, the "clock" icon doesn't always get updated.

Internal Backend -- Support self-connection

Allow connections to specify members of their own population as endpoints. This is primarily to simplify the construction of cables, where compartments connect end-to-end. Implications:

• A connection can also be a compartment, so it is necessary for classes to support both behaviors. Also, search code for any place that assumes the behaviors are mutually exclusive.

• The connection object will be created as a regular instance of its population, then later get connected. However, we can't allow a null pointer during init. Therefore, assign any self-pointers to the new instance itself. Later during connection evaluation, these can be replaced by pointers to other members of the population.

C Backend -- iterate over arbitrarily nested populations

Currently, Internal only supports first level of nesting when generating connection candidates. Should iterate over number of container.

Filter equations to reduce clutter

At present, inherited equations are always displayed. One level of filtering would only show overridden equations. Another level would add equations that the part designed tagged as likely to be overridden, even if they are still set to default values. The part designed could tag these equations with something like "gui.public".

Cooperate with Look & Feel better

Some components, particularly the equation tree, specify fonts and colors. When the L&F changes, these are sometimes no longer suitable. One issue is that some of these are initialized at startup, and don't change when the L&F changes. (A specific example is base font for equation tree nodes.) Another issue is that foreground text color is not based on selected state, and so it doesn't work well in themes where this needs to vary (such as Nimbus, with its very dark highlight).

Internal Backend -- add Runge-Kutta integrator

External simulators are more likely to use RK4 than Euler. Having this capability would reduce need to adjust parameters, particularly $t', when switching between Internal and other backends.

Activity tab shuffling is broken

To reproduce: Drag the "Run" tab until it sorts in front of the "Model" tab. Then run a model. An exception is thrown:

java.lang.ClassCastException: javax.swing.plaf.basic.BasicTabbedPaneUI$ScrollableTabButton cannot be cast to gov.sandia.n2a.ui.jobs.PanelRun
at gov.sandia.n2a.ui.eq.PanelEquationTree$4.actionPerformed(PanelEquationTree.java:849)
...

Apparently something in the shuffle code changes the object stored in the tabs array or the focused object array.

Default value is visible when new node is inserted under parent that has not yet been expanded

New nodes generally are blank, so the user can enter what they want without having to erase something. However, when a new node is inserted into a closed node the first time, its default value is visible. If the containing node is closed and another new node added, it displays correctly. This probably has something to do with how JTree prepares nodes for first display.

Equation tree node font changes during edit

Node immediately below the root (but not nodes at deeper levels) which show inherited values go into edit mode with larger bounds, apparently the same size as the root node itself. Nodes that are overridden keep normal size when going into edit mode. Turning off colorization does not change this behavior, so it must have something else to do with override state.

Language -- Handle spatial constraints symmetrically

Treat both (or any quantity of) ends of a connection in the same way. They should project into a space associated with the connection itself, independent of the respective populations being connected. Use just one function, A.$project, to transform population A into the space.

The one asymmetry is that the connection instance itself must be assigned a point in its space in order to do spatial filtering queries. C.$xyz may be defined explicitly by the user. If not explicit, then it can be the population used as the first level of iteration when generating tuples to test.

DnD between different processes is not undoable

Normally, adding a model via DnD can be undone. However, specifically if the drag originates from the equation tree of another n2a window (running on a remote system), the action can't be undone with ctrl-z. The problem is a hack in the search panel to avoid closing a compound edit so the source side of the DnD can incorporate a delete action. Since this has no meaning across process or system boundaries, the compound edit should be closed immediately. The difficulty is determining the source of the DnD.

NeuroML import/export

MRU list in search panel