welcome

Welcome to MABE!

In this document, we are going to explain the design philosophy of this software package and how we think this tool will help you achieve your goals.

MABEs users work in rather diverse fields such as Biology, Psychology, Cognitive Science, Neuroscience, and Computer Science, so MABE is designed to support a variety of users ranging from code amateurs to experts. Additionally, we all know that no two experiments are alike and that no matter how well a program like MABE is designed, there will be times that modifications must be made. Being able to quickly adapt the software so that it will run your experiment is core to MABEs development philosophy.

MABE is made from many interchangeable modules. For many experiments, you will be able to combine some set of existing modules (e.g. genomes, brains, worlds, etc) to create your experimental system. In other cases, you will find that a module might lack some needed feature and you will need to make simple modifications to the code (such as adding parameters or special case behavior). Lastly, you may need to write a new module or extensively adapt an existing module. Making changes to MABE is relatively simple though because you only need to change the one part of MABE you are interested in, without needing to worry about how the rest of MABE works. As a consequence of MABEs modularity, MABE is a living project-- every module that you (or anyone else) contribute can be used and combined with other modules to create new experiments.

Peace of mind

Each of MABEs modules has been designed with an interface which attempts to balance isolating that module from the rest of the code (to keep things simple) with not limiting communication between modules (which can present barriers to design).

In order to work with any particular module, you only need to know how that module's interface works and nothing more. From the outside, an Optimizer, for example, receives a population of organisms and generates the next generation - nothing more, nothing less. Only if you want to design your own Optimizer, or really understand what goes on when the optimizer is called, do you will need to look inside.

On the other hand, you can design some other element in MABE (such as worlds or brains) without any understanding of how the optimizer works. If you are building a new world, all you need to know about the optimizer is that it creates new populations. So, take a deep breath, you don’t need to understand everything right from the start, you can leave large parts of the MABE map uncharted until you feel the need to journey to those realms.

Playing Nice with Others

AKA : A note to coders

We experience that users want to use MABE to do one of two things: either they have a new idea that they wish to pursue, or they expand on, or modify an experiment that they or someone else performed.

The first workflow, we call vertical workflow because it starts with an idea and ends with a result, and it doesn't necessarily involve other people. It is a self-contained project from start to finish.

The the second workflow instead uses components, code, experimental designs, and/or analysis tools that someone else developed, and may even combine components from multiple experiments. We call this horizontal workflow (like horizontal gene transfer).

You are of course free to just design your experiments and code any which way you want. However, if you want to simplify collaboration, there are some development conventions (code style, naming conventions, etc) which you should follow in order support horizontal workflow, and thus make your code accessible to others (and also yourself. Chances are, you'll want to change, reuse, modify, or expand your own code at some point in the future!). The conventions are outlined in the documentation related to the particular modules when they are relevant.

In short, yes you may need to add some additional code to support horizontal workflow, but we feel that this investment is worth it, and we have attempted to minimize the impact as much as possible.