Installation and getting started with MABE

Before we get started...

MABE is a command line program (at least for now) which means that you use it from the command line. If you are not familiar with working on the command line there are many tutorials online (e.g. www.davidbaumgold.com/tutorials/command-line/). You should be able to navigate directories, and run programs before you go to the next step.

Dependencies

Mabe requires a set of software to be installed. The following sections detail which software to install and how to configure them. Pick and follow the appropriate guide for your system below:

• Windows WSL2 Guide
• Windows Old Guide
• Mac OSX Guide
• Linux Guide

For experienced users, the following is the required software.

• C++17 Compiler
• CMake >= 3.13.3
• Python >= 3.7 (optional) for auto plotting data after running MABE (installation will be covered in the section of this guide for your computer) however, you can plot the data using any method you like - it doesn't have to be python-based.
• A linux-like terminal. (optional)

If you already have the required software you can skip ahead to Downloading and Running MABE

Windows WSL2 Guide to Installing and Configuring the Dependencies

This is the new Windows guide to using WSL2 (Windows Subsystem for Linux) to get a linux terminal and compiler tools installed.

Open a terminal using Admin privileges

• Start > (type 'cmd') > right-click cmd and choose Run As Admin
• In cmd window wsl --install
• (reboot when prompted)
• (log into windows as normal, then wait - install will automatically resume)

Verify you have Windows Terminal

• Start > (type 'term') > Make sure the application 'Windows Terminal' is installed. You will be using it.
• If not installed, get it from the Microsoft Store 'Windows Terminal'

Start up Windows Terminal in Ubuntu mode

• Start > (type 'term') > Windows Terminal - Ubuntu

Now update and install tools in this terminal. Make a shortcut if you'd like, because this will be your working terminal. Type the following commands

sudo apt update \
sudo apt install -y g++ cmake

Depending on your version of WSL2, you may find that the default directory is an unknown location on your computer. In this case, note that your home directory in Ubuntu is /home/<yourname>/ and this is where things like .ssh configuration will need to be. This is a completely different home directory than in standard windows! When in Ubuntu, you can navigate to your normal home directory and C drive at /mnt/c/Users/<yourname>/

Continue to Downloading and Running MABE

Windows Guide to Installing and Configuring the Dependencies

You will need a way to edit c++ code files, and a compiler to convert them into computer programs. There are three ways to achieve this; pick whichever one suits your needs:

• Microsoft Visual Studio 2019 with Terminal (easier to set up, but a much longer download) Jump to guide
  • Typical installs require 20-50 GB of hard disk space (system requirements)
• Just MinGW with Terminal <1.2 GB of hard disk space. Use this if you are very comfortable with the linux command line interface. You will need to use Notepad++, VSCode, Visual Studio, or another editor to edit files. Jump to guide

Installing Microsoft Visual Studio 2019 & Terminal on Windows

1. Install CMake

• Download the CMake win64-x64 installer from [https://cmake.org/download/) (25 MB)
• Run the installer and...
• All defaults are okay. Just say 'Yes' or 'OK' to everything but make sure to note the location of the install.
• At the end it will ask about PATH integration. For MABE to work, you do not need to do this if you installed to the default location. But to use it for other software, it might be nice. You can always change this later by running the gui that is also installed.

2. Install Visual Studio 2019

• Download the Community Edition from https://www.visualstudio.com/downloads/
• Run the installer and...
• When asked about which Workloads to install (optional components), select Desktop development with C++ and continue to the next step.

3. Install MSYS2 (GCC 9.x)

• Download the MSYS2 installer from http://www.msys2.org/ (70 MB) Get the one labeled msys2-x86_64-... unless you know you need the 32-bit version, in which case edit the following commands as necessary [rare].
• Run the installer and...
• All defaults are okay. Just say 'Yes' or 'OK' to everything but make sure to note the location of the install.
• Select 'Run MSYS2' on the final screen, or launch it using the shortcut installed in Start.
• Run the following commands (copy and paste them as entire blocks).

pacman -Syu --noconfirm

• Now close the window (you may need to kill the application).
• Open msys2 again to type more commands.

pacman -Syu --noconfirm
pacman -S --needed --noconfirm git \
man winpty git nano vim emacs

• Close the window.
• Important Anytime you want to run the command line you have installed, run it using the MSYS2 MinGW 64-bit shortcut in the Start Menu.
• Continue to the next step.

4. Set the default home directory to be the same as your usual Windows one. This is optional but highly recommended. If you skip this then you can only access your Windows home directory by typing cd /c/Users/YOURNAME (where your should replace YOURNAME with your username). After making this change, you can access your home directory by typing cd ~ and it will be the default directory when you open the terminal.

• Go to the Start menu, and click Run. Or Press WinKey+R where WinKey is the Windows Key.
• Type SystemPropertiesAdvanced and click OK
• Click the Environment Variables button near the bottom.
• Click the New... button in the upper half of the window.
• Type HOME and %USERPROFILE% for Variable Name and Variable Value respectively.
• Click OK on all the windows to close them.

Continue to Installing Python on Windows

Installing MinGW, and Terminal on Windows

1. Install CMake

• Download the CMake win64-x64 installer from [https://cmake.org/download/) (25 MB)
• Run the installer and...
• All defaults are okay. Just say 'Yes' or 'OK' to everything but make sure to note the location of the install.
• At the end it will ask about PATH integration. For MABE to work, you do not need to do this if you installed to the default location. But to use it for other software, it might be nice. You can always change this later by running the gui that is also installed.

2. Install MSYS2 (GCC 9.x)

• Download the MSYS2 installer from http://www.msys2.org/ (70 MB) Get the one labeled msys2-x86_64-... unless you know you need the 32-bit version, in which case edit the following commands as necessary [rare].
• Run the installer and...
• All defaults are okay. Just say 'Yes' or 'OK' to everything but make sure to note the location of the install.
• Select 'Run MSYS2' on the final screen, or launch it using the shortcut installed in Start.
• Run the following commands (copy and paste them).

pacman -Syu --noconfirm

• Now close the window (you may need to kill the application).
• Open msys2 again to type more commands.

pacman -Syu --noconfirm
pacman -S --needed --noconfirm git \
base-devel mingw-w64-x86_64-toolchain \
winpty gdb git man nano vim emacs

• Close the window.
• Important Anytime you want to run the terminal you have installed, run it using the MSYS2 MinGW 64-bit shortcut in the Start Menu, not MSYS2 where GCC will not work.
• Continue to the next step.

3. Set the home directory to be the same as your usual one. This is optional but highly recommended. If you skip this then your home dir is in /c/Users/YOURNAME where you should replace YOURNAME with your username).

• Go to the Start menu, and click Run. Or Press WinKey+R where WinKey is the Windows Key.
• Type SystemPropertiesAdvanced and click OK
• Click the Environment Variables button near the bottom.
• Click the New... button in the upper half of the window.
• Type HOME and %USERPROFILE% for Variable Name and Variable Value respectively.
• Click OK on all the windows to close them.
• Continue to the next step.

Continue to Installing Python3 on Windows

Installing only MinGW and Terminal on Windows

1. Install CMake

• Download the CMake win64-x64 installer from [https://cmake.org/download/) (25 MB)
• Run the installer and...
• All defaults are okay. Just say 'Yes' or 'OK' to everything but make sure to note the location of the install.
• At the end it will ask about PATH integration. For MABE to work, you do not need to do this if you installed to the default location. But to use it for other software, it might be nice. You can always change this later by running the gui that is also installed.

2. Install MSYS2 (GCC 9.x)

• Download the MSYS2 installer from http://www.msys2.org/ (70 MB) Get the one labeled msys2-x86_64-... unless you know you need the 32-bit version, in which case edit the following commands as necessary [rare].
• Run the installer and...
• All defaults are okay. Just say 'Yes' or 'OK' to everything but make sure to note the location of the install.
• Select 'Run MSYS2' on the final screen, or launch it using the shortcut installed in Start.
• Run the following commands (copy and paste them).

pacman -Syu --noconfirm

• Now close the window (you may need to kill the application).
• Open msys2 again to type more commands.

pacman -Syu --noconfirm
pacman -S --needed --noconfirm git \
base-devel mingw-w64-x86_64-toolchain \
winpty gdb git man nano vim emacs

• Close the window.
• Important Anytime you want to run the terminal you have installed, run it using the MSYS2 MinGW 64-bit shortcut in the Start Menu, not MSYS2 where GCC will not work.
• Continue to the next step.

3. Set the home directory to be the same as your usual one. This is optional but highly recommended. If you skip this then your home dir is in /c/Users/YOURNAME where you should replace YOURNAME with your username).

• Go to the Start menu, and click Run. Or Press WinKey+R where WinKey is the Windows Key.
• Type SystemPropertiesAdvanced and click OK
• Click the Environment Variables button near the bottom.
• Click the New... button in the upper half of the window.
• Type HOME and %USERPROFILE% for Variable Name and Variable Value respectively.
• Click OK on all the windows to close them.

Continue to Installing Python3 on Windows

Installing Python3 on Windows

1. Install Notepad++.

• Download the Notepad++ text editor from https://notepad-plus-plus.org/download, the one called Notepad++ Installer 64-bit x64.
• Run the installer and...
• All defaults are okay. You can disable context menu integration if you don't want it to show on right-clicked files.
• Continue to the next step.

2. Install Python3.

• Download the Miniconda Python3 installer from https://conda.io/miniconda.html the one called Python 3.x 64-bit, unless you know you need something else.
• Run the installer and...
• All defaults are okay.
• When it asks if it should automatically add to the path, say No.
• Continue to the next step.

3. Make the terminal aware of python

• open the terminal (Windows menu, type mingw in search; it's the 64-bit one)
• open the .bash_profile file by typing: start notepad++ .bash_profile
• Add the following line (copy paste) anywhere in the file, save, and close.
  • export PATH=/c/Users/[YOUR USER NAME]/Miniconda3:/c/Users/[YOUR USER NAME]/Miniconda3/Scripts:$PATH
  • An example: export PATH=/c/Users/Carmack/Miniconda3:/c/Users/Carmack/Miniconda3/Scripts:$PATH
• Type source .bash_profile

Continue to Downloading and Running MABE

Mac OSX Guide to Installing and Configuring Dependencies

1. Update OSX to the latest version through the App Store

2. Install or Update XCode to the latest version through the App Store

**3. Install cmake (unless you already have it through homebrew or other package manager)

• Download the CMake Darwin dmg installer from [https://cmake.org/download/) (36 MB)
• Copy it to your Applications/ folder, as usual

Installing Python3 on MacOS

1. Install Python3

• Download the Miniconda Python3 installer into your home folder from https://conda.io/miniconda.html the one called Python 3.x 64-bit, unless you know you need something else.
• Open the terminal by finder or presseing COMMAND+Space: type terminal and press enter.
• In the terminal, type bash Miniconda and press the TAB key to finish the rest of the filename, then press enter.
• The installer will start, press enter key, q key (or read the license to the end), then type yes and press enter.
• It will ask if you want to prepend the install location to PATH; answer No
• Allow python to be activated by:
  • In the terminal, open the bash profile file by typing open -a TextEdit ~/.bash_profile
  • Add the following line at the top of the file alias mcpython='export PATH="$HOME/Miniconda3/bin:$PATH"' #
  • Save and close
• Restart the terminal
• Activate python by typing mcpython
• Install required packages by typing conda install -y numpy matplotlib pandas scipy
• Important Anytime you want to run anything requiring python, you will need to "turn on" python by typing mcpython (miniconda python).

4. Install Command Line Tools for XCode

• Open a terminal
• type xcode-select --install and follow the prompts to install the command line tools.

Continue to Downloading and Running MABE

Linux Guide to Installing and Configuring Dependencies

If you're running linux, then most everything should be pretty easy.

• Install a c++17 compiler, or the latest GCC you can get
• Install cmake >= 3.13.3 (Ubuntu 16.04 or greater, for instance)
• On modern Ubuntu, the install command is sudo apt install aptitude then sudo aptitude install g++ though you may need to update first sudo apt-get update. We use the aptitude package manager here because we have experienced trouble with apt and apt-get failing to install a usable c++ compiler binary on modern Ubuntu. PRs appreciated if you can streamline this step.

Continue to Downloading and Running MABE

Downloading and Running MABE

In order to use MABE, you must first download the code from GitHub. In these instructions, you will simply be downloading the git repository. (If you want to be able to make git commits - don't worry if you don't know what that means - then you will want to follow the instructions here: developer contributions)

1. Go to the GitHub page for MABE: https://github.com/Hintzelab/MABE
2. Click on the green button labeled "Code" on the right side of the screen.
3. A drop-down menu will appear-- click on "Download ZIP"
   
4. This automatically downloads a compressed version of all of the MABE code.
5. When the download is complete, open it (it should appear at the bottom of the web browser, if not, you will need to find it in the downloads folder).
6. Once you open the download, you should see a single folder called "MABE-master". Drag this folder to your desktop (or where ever you would like to keep MABE on your computer.)

Compiling Mabe

In order to run MABE, you must first create an executable by compiling the code. You can choose to compile MABE on the command line or with a program (i.e. an Interactive Development Environment or an IDE). IDEs know how to compile code and they can help edit code.

You should use the IDE option if you are on a PC and you want to be able to edit code. You should use command line option if you are not on a PC or you just want to run MABE.

Compiling MABE on the command line

• Open the terminal ("Msys minGW-64 bit" on Windows) and navigate to MABE-master
• on the command line type: sh tools/setup.cmd This will set up mbuild, the command that builds mabe. *next type: ./mbuild
• mbuild will compile MABE, when it's done, go to running-mabe
• Tip: if you are using the windows terminal (CMD.exe) then the commands are simply tools/setup and mbuild because windows will run files with .cmd or .exe if you give it just the basename.

Compiling MABE with an IDE

1. mbuild can be used to create a project file for your editor of choice.

• Open the terminal ("Msys minGW-64 bit" on Windows) and navigate to MABE-master on the command line type: sh tools/setup.cmd This will set up mbuild, the command that builds mabe.
• type: ./mbuild gen for "generate" mode. mbuild will show a list of IDEs that it knows about.
• generate a specific IDE project file with ./mbuild gen DESIRED_IDE_NAME
• navigate to your project and then into the build directory.
• Click on the project file for your IDE.
• Using your IDE, start the compiler and create the executable. This is usually under the Build or Project menu and is usually called Build.

Running MABE

• Open the terminal ("Msys minGW-64 bit" on Windows). Navigate to the directory containing your MABE executable.
• cd into the work/ directory and enter the following on the command line: ./mabe unless you are on the standard windows CMD command line, in which case it's just mabe. If you're in windows powershell, it's .\mabe
• you should see:

        MM   MM      A       BBBBBB    EEEEEE
        MMM MMM     AAA      BB   BB   EE
        MMMMMMM    AA AA     BBBBBB    EEEEEE
        MM M MM   AAAAAAA    BB   BB   EE
        MM   MM  AA     AA   BBBBBB    EEEEEE

        Modular    Agent      Based    Evolver


        https://github.com/HintzeLab/MABE


        for help run MABE with the "-h" flag (i.e. ./mabe -h).

Using Random Seed: 101

Running World Test

Building group with name space: root::

 building brains...
  found brain: root::
    ... building a CGP brain using root:: name space.
    ..... this brain requires genomes: root::

 building genomes...
  found genome: root::
    ... building a Circular genome using root:: name space.

Loading 0 Random organisms
Loading 100 Default organisms

Finished Building Group: root::   Group name space: root::
  population size: 100     Optimizer: Tournament     Archivist: Default


  You are running MABE in run mode.

update: 0   max = 6.000000   ave = 1.810000
update: 1   max = 6.000000   ave = 3.140000
update: 2   max = 7.000000   ave = 4.230000
update: 3   max = 7.000000   ave = 5.300000
update: 4   max = 7.000000   ave = 6.260000
update: 5   max = 7.000000   ave = 6.760000
update: 6   max = 8.000000   ave = 6.990000
update: 7   max = 8.000000   ave = 6.970000
update: 8   max = 8.000000   ave = 7.140000
update: 9   max = 8.000000   ave = 7.480000
update: 10   max = 8.000000   ave = 7.910000
update: 11   max = 8.000000   ave = 7.900000
update: 12   max = 8.000000   ave = 7.940000
update: 13   max = 8.000000   ave = 7.910000
update: 14   max = 8.000000   ave = 7.840000
update: 15   max = 8.000000   ave = 7.950000
update: 16   max = 8.000000   ave = 7.940000
update: 17   max = 9.000000   ave = 7.840000
update: 18   max = 9.000000   ave = 8.010000
update: 19   max = 9.000000   ave = 8.030000
update: 20   max = 10.000000   ave = 8.600000
update: 21   max = 10.000000   ave = 8.910000

Output Files

List the contents of this directory you will see two new files.

 
> ls
pop.csv  max.csv  mabe

Open pop.csv in your editor of choice. You will see that the first line lists column names and the following lines list values. This file contains the average values for the population at various updates.

countCopy_AVE,countDelete_AVE,countIndel_AVE,countPoint_AVE,countPointOffset_AVE,genomeLength_AVE,optimizeValue_AVE,score_AVE,score_VAR,update
0.000000,0.000000,0.000000,0.000000,0.000000,5000.000000,1.810000,1.810000,1.731212,0
1.310000,1.240000,0.000000,249.630000,0.000000,5024.560000,7.910000,7.910000,0.143333,10
1.940000,2.000000,0.000000,504.280000,0.000000,4983.110000,8.600000,8.600000,0.383838,20
2.510000,2.870000,0.000000,765.060000,0.000000,4893.530000,9.940000,9.940000,0.056970,30
2.880000,3.190000,0.000000,1005.050000,0.000000,4911.080000,9.960000,9.960000,0.038788,40
3.110000,3.860000,0.000000,1239.950000,0.000000,4754.000000,9.900000,9.900000,0.393939,50
4.800000,4.500000,0.000000,1504.400000,0.000000,5235.870000,9.880000,9.880000,0.167273,60
5.810000,4.880000,0.000000,1763.790000,0.000000,5328.990000,9.920000,9.920000,0.074343,70
6.480000,6.150000,0.000000,1987.180000,0.000000,5162.200000,9.940000,9.940000,0.056970,80
7.310000,7.540000,0.000000,2246.250000,0.000000,5022.660000,9.890000,9.890000,0.119091,90
8.890000,7.460000,0.000000,2586.150000,0.000000,5385.500000,9.950000,9.950000,0.047980,100

For example, here we see at update (the right most column) 80 the score (the column 3rd from the right) was 9.94
Close pop.csv

Generating Settings Files

Now that you can run MABE, you'll want to be able to change what happens when MABE runs. One way to do this is with settings files.
If you run MABE with the '-s' command line option, MABE will generate settings files.

./MABE -s

If you look at the contents of your directory now, you will see some new settings files. Settings files end with ".cfg" (which stands for configuration).

>ls

pop.csv  mabe  settings_organism.cfg
max.csv  settings.cfg  settings_world.cfg

Open "settings.cfg" and you will see something like this:

% GLOBAL
  initPop = default 100                      #(string) initial population to start MABE (if it's .plf syntax it will be parsed as if preceded by "MASTER = ". If
                                             #  it's a file name with .plf that population loader file is parsed
  mode = run                                 #(string) mode to run MABE in [run,visualize,analyze]
  outputPrefix = ./                          #(string) Directory and prefix specifying where data files will be written
  randomSeed = 101                           #(int) seed for random number generator, if -1 random number generator will be seeded randomly
  updates = 100                              #(int) how long the program will run

% ARCHIVIST
  outputMethod = Default                     #(string) output method, [Default, LODwAP]

% ARCHIVIST_DEFAULT
  filePrefix = NONE                          #(string) prefix for files saved by this archivst. "NONE" indicates no prefix.

The settings files contain all of the possible settings for MABE. Looking through these files is a great way to see what MABE can do. Changing values in these files will change the way that MABE runs.

Loading Settings Files

If you want MABE to use the parameters settings from files, you must use the "-f" command line option.

./mabe -f settings.cfg settings_organism.cfg settings_world.cfg

or you could run:

./mabe -f settings*

If a parameter is defined in more than one file, the last instance of the variable will set the parameter. In this case, the order in which the files are listed would matter, and you would not be able to use "settings*".

Command Line Settings

You can also set parameters on the command line using the "-p" command line option. For example, if you wanted to set the randomSeed to 102 and, popSize to 250, you could run the following:

./MABE -p GLOBAL-randomSeed 102 GLOBAL-initPop "default 250"

You can use the "-f" and "-p" options together, parameters set on the command line will overwrite parameters set in files. Additionally, you can use the "-s" option with both "-f" and "-p". The settings files generated will contain the state of parameters after all files and the command line details have been read.

Generating More Data

Run the following:

./mabe -p GLOBAL-updates 200

Generating Graphs

Now that we have some more data, we can visualize this in a graph.
In order to make graphs you will need to have Python and matplotlib (a graphing package for Python) installed. You can find guides online to help install both of these. It is advisable to install the latest version of Python (version 3.0 or later as opposed to 2.x). Once you have Python and matplotlib, try running:

python ../tools/mgraph.py

(you may need to indicate python3 - i.e. python3 mgraph.py)
After a few seconds, you should see a plot with the data from pop,csv open showing your data.
For more about graphing click here

Go Forth! Do Science!

That's it, you are up and running. Do let us know what awesome things you do with MABE! Please contact us if you need any help or find any errors!

Configuring Nano Text Editor for .cfg file syntax highlighting (mac/linux) [optional]

If you are using the Nano editor you can use the following configuration to allow for syntax highlighting (i.e. color text to make the config files easier to read).
Contributed by Anton Bernatskiy

Add to your cfg.nanorc

# MABE .cfg syntax
syntax "cfg" "\.(cfg)$"
header "^\[[A-Za-z]+\]$"
color cyan "^[[:space:]]*[^=]*="
color brightcyan "^[[:space:]]*%.*$"
color red "[=;]"
color yellow "(^|[[:space:]])#([^{].*)?$"