Skip to content

Install

Jump to bottom
StephenJRead edited this page Sep 6, 2021 · 30 revisions

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! Although we strongly suggest you install in the same directory as the GoGi code
$ 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: https://github.com/golang/go/issues/40795

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(you might have to replace the 'emer' in the two cp (copy) commands with the folder name that your leabra installation is in:

$ 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!
# After you do 'go mod init' you will probably get the following in your terminal
$ go: to add module requirements and sums:
	go mod tidy
# if so, type in:
$ go mod tidy 
# and it will add the module requirements and sums.
$ go build
$ ./mycode &   # the program will be named after the directory!  not the .go file (see below)

Several points to keep in mind about what go mod init is doing in the above, when you set things up for your own model. (Note that mycode in the following refers to whatever you called the directory).

  1. What go mod init (followed by go mod tidy) is doing at that point is looking at the go code for the ra25.go project in your mycode directory (or whatever you called it) and then creating and initializing the go.mod file to list all the dependencies that are called by the go code in the mycode directory. At the same time it creates a go.sum file.
  2. If you update your emergent installation, as described below, building the ra25 code (or another project below the go.mod file in the file hierarchy) at this point updates the go.mod file with a list of new versions of the dependencies used by ra25.
  3. Once you do go mod init followed by go mod tidy you can create a separate ra25 folder within the mycode directory and move the ra25 code into that and then use mycode as a repository for any other new projects you want to work on. You should leave go.mod and go.sum at the top level within the mycode directory and not in the ra25 file. When you do that, when you create any other new project in the mycode directory, building the new code will search upward in the directory until it finds a go.mod file
  4. In the go mod init instruction above, the package name is completely arbitrary, unless you want another program to be able to import this package. If all you are doing is creating projects and importing from other packages, the name can be arbitrary. However, it would make sense to give it a meaningful name, especially if you think that anyone else would ever want to find your package, say if you made it available on your git.hub. For example: github.com/read/mycode. It is not a good idea to give this package the same name as any other package.

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.

test

Clone this wiki locally