Emergent Neural Network Simulation Framework

<p align="center"> <a href="https://goreportcard.com/report/github.com/emer/emergent"><img src="https://goreportcard.com/badge/github.com/emer/emergent" alt="Go Report Card"></a> <a href="https://pkg.go.dev/github.com/emer/emergent"><img src="https://img.shields.io/badge/dev-reference-007d9c?logo=go&logoColor=white&style=flat" alt="pkg.go.dev docs"></a> <a href="https://github.com/emer/emergent/actions"><img alt="GitHub Actions Workflow Status" src="https://img.shields.io/github/actions/workflow/status/emer/emergent/go.yml"></a> <a href="https://raw.githack.com/wiki/emer/emergent/coverage.html"><img alt="Test Coverage" src="https://github.com/emer/emergent/wiki/coverage.svg"></a> <a href="https://github.com/emer/emergent/tags"><img alt="Version" src="https://img.shields.io/github/v/tag/emer/emergent?label=version&color=blue"></a> </p>

IMPORTANT branch information:

• main is the latest version based on Cogent Lab, used by axon, and is still undergoing significant development.

• leabra is an awkward in-between version that works with the current leabra and Computational Cognitive Neuroscience simulations, which had to be updated for teaching in Fall 2024, so the simulations could run on the web browser.

• v1 is the version that works with the old v1 versions of leabra, using the old goki GUI framework.

The emergent neural network simulation framework provides a toolkit in the Go programming language (golang) for developing neural network models across multiple levels of complexity, from biologically-detailed spiking networks in the axon package, to PyTorch abstract deep networks in the eTorch package. It builds on the Cogent Core GUI framework and Cogent Lab to provide dynamic graphical interfaces for visualizing and manipulating networks and data, making the models uniquely accessible for teaching (e.g., see the Computational Cognitive Neuroscience simulations) and supporting the development of complex dynamical models for research.

See cogent core install instructions for general installation instructions. The emergent wiki install page has a tutorial for how to create your own simulation based on the leabra ra25 example.

The Wiki Rationale and History pages for a more detailed rationale for this version of emergent, and a history of emergent (and its predecessors). The Wiki tends to be a bit out of date, but can have some useful information. In general it is best to take the plunge and "use the source" directly :)

The single clearest motivation for using Go vs. the ubiquitous Python, is that Python is too slow to implement the full computational model: it can only serve as a wrapper around backend code which is often written in C or C++. By contrast, Go can implement the entire model in one coherent language. This, along with the advantages of the strongly typed, rapidly compiled Go language vs. duck typed Python for developing large scale frameworks, and the many other benefits of the Go language environment for reproducible, reliable builds across platforms, results in a satisfying and productive programming experience.

Furthermore, the Go shader language gosl in Cogent Lab enables Go to run efficiently on the GPU as well, enabling the same code base to be used for both CPU and GPU execution. This enables even very complex, biologically-detailed models as in the axon framework to take full advantage of GPU acceleration, resulting in 10x or more speedup factors over CPU.

See the ra25 example in the axon package for a complete working example (intended to be a good starting point for creating your own models), and any of the 26 models in the Comp Cog Neuro sims repository which also provide good starting points, using the leabra framework.

Current Status / News

• December 2024: Updated to Cogent Lab and tracking ongoing development there. In general much of the prior functionality in emergent has / will migrate to Lab.

• June 2024: Major changes ongoing in coordination with the Cogent Core framework development over the prior year, replacing the previous GoKi GUI framework. Many packages have migrated to Cogent Core, which is a much cleaner major rewrite, which should be stable and released in beta status soon. axon is staying updated but everything else should use the v1 branch. Leabra and Comp Cog Neuro sims will be updated after the dust settles, hopefully in time for Fall 2024 classes.

• Nov 2020: Full Python conversions of CCN sims complete, and eTorch for viewing and interacting with PyTorch models.

• April 2020: Version 1.0 of GoGi GUI is now released, and we have updated all module dependencies accordingly. We now recommend using the go modules instead of GOPATH -- the Wiki Install instructions have been updated accordingly.

• 12/30/2019: Version 1.0.0 released! The Comp Cog Neuro sims that accompany the CCN Textbook are now complete and have driven extensive testing and bugfixing.

• 3/2019: Python interface is up and running! See the python directory in leabra for the README status and how to give it a try. You can run the full leabra/examples/ra25 code using Python, including the GUI etc.

• 2/2019: Initial implementation and benchmarking (see examples/bench for details -- shows that the Go version is comparable in speed to C++).

Design / Organization

• The emergent repository contains a collection of packages supporting the implementation of biologically based neural networks. The main package is emer which specifies a minimal abstract interface for a neural network.

• Go uses interfaces to represent abstract collections of functionality (i.e., sets of methods). The emer package provides a set of minimal interfaces for each structural level (e.g., emer.Layer etc), along with concrete "Base" types that implement a lot of shared functionality (e.g., emer.LayerBase), which are available as AsEmer() from the interface. Each algorithm must implement the interface methods to support the Network view, logging, parameter setting and other shared emergent functionality.

• The emer interfaces are designed to support generic access to network state, e.g., for the 3D network viewer, but specifically avoid anything algorithmic or structural, so that most of the algorithm-specific code uses direct slices and methods that return algorithm-specific types.

• There are 3 main levels of structure: Network, Layer and Path (pathway of connectivity between layers, also known as a Projection). The Network typically calls methods on its Layers, and Layers have methods to access Neuron or Unit-level data. The Path fully manages everything about a pathway of connectivity between two layers, including access to Synapse or Connection level state.

• Layers have a Shape property, using the tensor.Shape type (from the Cogent Core tensor package), which specifies their n-dimensional (tensor) shape. Standard layers are expected to use a 2D Y*X shape (note: dimension order is outer-to-inner or RowMajor), and a 4D shape that enables Pools as hypercolumn-like structures within a layer that can have their own local level of inihbition, and are also used extensively for organizing patterns of connectivity.

Packages

Here are some of the additional supporting packages, organized by overall functionality:

Core Network

• emer: the primary abstract Network, Layer, Path interfaces.

• params: a parameter-styling infrastructure (e.g., params.Set, params.Sheet, params.Sel), which implement a powerful, flexible, and efficient CSS style-sheet approach to parameters. See the Wiki Params page for more info.

• netview: the NetView interactive 3D network viewer, implemented in the Cogent Core xyz 3D framework.

• paths is a separate package for defining patterns of connectivity between layers. This is done using a fully independent structure that only knows about the shapes of the two layers, and it returns a fully general bitmap representation of the pattern of connectivity between them. The algorithm-specific code then uses these patterns to do all the nitty-gritty of connecting up neurons. This makes the pathway code much simpler compared to earlier implementations that combined both of these functions.

• relpos provides relative positioning of layers (right of, above, etc).

• weights provides weight-file parsing / loading routines: much easier to read into a temporary structure and then apply to