Skip to content

Install

Jump to bottom
Randall O'Reilly edited this page Aug 8, 2023 · 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.

The leabra axon and etorch repositories contain implementations of emergent for specific algorithms -- thus, you need to install one of them 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 cemer 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: you must use Go version 1.18 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 goimports (see https://goki.dev/docs/general/structfieldcomments/ for info) and stringer utilities:

go install github.com/goki/go-tools/cmd/goimports@latest
go install github.com/goki/stringer@latest

Stringer 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 &

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 can pick your own name for the directory). Note: you will typically need to replace the 'emer' in the three cp (copy) commands with the folder name that your leabra installation is in. Also, it is essential that you put a . at the end of the cp commands. That tells the command to copy into your current directory. If you leave off the . then nothing will be copied into your directory.

cd ~/
mkdir mycode
cd mycode
cp ~/emer/leabra/examples/ra25/ra25.go .  # If you put leabra in a folder in your user directory, you will need to replace emer in this and the following cp (copy) commands with the directory your leabra installation is in. If leabra is at the top level in your user directory, then delete emer/ from the path name.  
cp ~/emer/leabra/examples/ra25/logitems.go . #This is the definition of the different logs. (Check and make sure this is in the directory.  Recently added, but not in older versions of ra25.)
cp ~/emer/leabra/examples/ra25/random_5x5_25.tsv .   # these are the input patterns
go mod init mycode   # making up a fake package name here, call it what you want
# After you do 'go mod init' you will probably get the following in your terminal (for more recent go versions)
$ 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 and go mod tidy are 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. go mod init creates the go.mod and go.sum files that keep track of the versions of the other go packages that your program depends on, while go mod tidy looks through the go code in your mycode directory (or whatever you called it) to find all the dependencies and add them to the go.mod and go.sum files (go.mod is human readable and editable, with just the package names and versions, while go.sum contains checksums to verify the packages for security purposes.
  2. As of more recent go versions, go build no longer automatically updates the go.mod file, so if your dependencies change, you will need to separately run go mod tidy, or you can type go build -mod=mod to allow it to update go.mod. You should add go.mod and go.sum to git -- the reason go no longer automatically updates these files is because the best practice is to intentionally update and commit these changes as needed, rather than have these changes take place incidentally.
  3. A single top-level go.mod file applies to all directories under it. For example, 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. Note that in many cases you might want to have a particular project have its own go.mod file to insure that that particular project is calling the specific versions of other packages that are required. In that case, each project can have its own go.mod and go.sum files in its directory and when you build the project it will use the packages specified in that go.mod file and not in any go.mod file in a higher level of the directory in which your project resides.
  5. 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 github. For example: github.com/sjread/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