Install

Installation

This wiki provides an umbrella wiki for all emer projects. The emergent repository itself does not contain directly runnable code (except for tests) -- it serves as a toolkit for other specific algorithms.

Currently the only implemented one is in the leabra repository. Thus, you need to install that to see how emergent works.

In general, emergent works by compiling programs into executables which you then run like any other executable. This is very different from the C++ version of emergent which was a single monolithic program attempting to have all functionality built-in. Instead, the new model is the more prevalent approach of writing more specific code to achieve more specific goals, which is more flexible and allows individuals to be more in control of their own destiny..

First, install GoGi

Note: Due to gonum dependencies, you must use Go version 1.13 or newer!

Emergent depends on GoGi, so first follow the installation instructions for it, including building the standard widgets example to make sure everything is working. This is essential especially because there are non-Go elements that need to be installed to support the 3D GUI, and we don't want to maintain multiple copies of that information!

It is a good idea to also install our version of the stringer utility, which is used to generate string names for constant values that serve as "enum" types in Go (e.g., for a fixed list of options in a drop-down menu to choose among): https://github.com/goki/stringer -- this version also generates a FromString method that converts a string back into its corresponding numerical value.

Then install leabra (Modules version)

We're assuming you've read the discussion of go modules in the GoGi install page. In contrast to prior instructions, we now recommend you just use go modules! -- it is much easier for "end user" use..

$ cd <anywhere you want to install>  # you can put the code anywhere you want!
$ git clone https://github.com/emer/leabra   # makes a leabra directory 
$ cd leabra/examples/ra25
$ go build    # this installs all the dependencies for you!  do *not* type go get ./...
$ ./ra25 &

On Windows you need to do $ go build -buildmode exe if it doesn't work with just plain go build -- this will be fixed at some point but not sure when.

When you do go build above, all of the other packages in emer will be installed into:

• ~/go/pkg/mod/github.com/emer/ So you can look in there for all the code -- the modules mode names the directories with the specific version that is installed, so look for the most recent version!

To see all of the versions available for each emer package, do this:

$ go list -m -versions github.com/emer...

In general, the last version of each should be mutually compatible, but sometimes we are working on "bleeding edge" changes in some of the less core packages, so there may be some breakage there..

Making your own models

To make your own simulations, copy the ra25.go code to your own repository, and modify accordingly. Also see the CCN Textbook sims for many other examples -- finding the closest example in there is probably the best place to start.

Here's an example for starting a new project with ra25.go, in a top-level "mycode" directory:

$ cd ~/
$ mkdir mycode
$ cd mycode
$ cp ~/emer/leabra/examples/ra25/ra25.go .
$ cp ~/emer/leabra/examples/ra25/random_5x5_25.tsv .   # these are the input patterns
$ go mod init github.com/emer/mycode   # making up a fake package name here -- use your own github!
$ go build
$ ./mycode &   # the program will be named after the directory!  not the .go file (see below)

go build options

You can run go build either specifying a particular .go file, or without (i.e., just go build as in above instructions).

• If you have multiple .go files in same dir that all contribute to one executable, then you have to run go build, and the resulting executable will be named after the directory.

• If you have multiple .go files and each should be built as a separate executable, then you have to run go build file.go and the executable will be named after the file.

• If you only have one .go file, you can decide what you prefer.

If you want to update your emergent installation

Given that the emergent code and its supporting code (e.g., goki) is being continually developed, you may want to periodically update your installation to take advantage of the newest "tagged" changes and bug fixes.

If you are using go modules and you created your own individual repository for creating your own models, following the instructions above, here is how to do it.

First, you should find and open the go.mod file that is at the top level of your repository. You should see something like this, which lists the current installed versions of the different packages.

require (
	github.com/emer/emergent v1.1.9
	github.com/emer/etable v1.0.13
	github.com/emer/leabra v1.1.9
	github.com/goki/gi v1.0.14
	github.com/goki/ki v1.0.4
	github.com/goki/mat32 v1.0.2
)

You then need to find out the different "tagged" versions of the different packages to see if there are more recent ones and if so, what they are. To do that you can use the following commands in the terminal. The first one lists all the different versions for each package in github.com/emer and the second command lists the different versions for the different packages in github.com/goki, where goki has the code that implements the GUI for emergent, as well as other packages such as the mat32 package.

Get current version numbers of emergent packages

$ go list -m -versions github.com/emer...

Get current version numbers of goki packages

$ go list -m -versions github.com/goki...

Use the results to determine which version you want and then edit the version numbers and save the updated go.mod file.

The next time you build a project in your repository, it will then update the various packages in your installation to match the versions listed in go.mod. Obviously, if you want to update the installation immediately, then simply build a project in your repository.