Tutorial topics:




Getting Started: What's the big idea?

BehaviorSearch is a software tool designed to help with automating the exploration of agent-based models (ABMs), by using genetic algorithms and other heuristic techniques to search the parameter-space.

BehaviorSearch interfaces with the popular NetLogo ABM development platform, to provide a low-threshold way to search for combinations of model parameter settings that will result in a specified target behavior.

How to explore your model in four steps:

  1. Choose model parameters to vary and what ranges are allowed.
  2. Design a quantitative measure for a behavior of interest.
  3. Choose a search algorithm to find parameters that maximize (or minimize) your measure.
  4. Run the search and examine the results.


Note: In this tutorial, we will assume that you already have a functioning NetLogo model that you are interested in exploring/analyzing.

Figure 1: BehaviorSearch Experiment Editor GUI,
highlighted some important functional areas of the interface.

When you first open BehaviorSearch, the window that appears is the BehaviorSearch Experiment Editor. BehaviorSearch is centered around the paradigm of an experiment (or search protocol), which contains all of the information necessary to specify how the search should be performed on a model. The BehaviorSearch GUI helps you create, open, modify, and save these experiments (stored as files with the ".bsearch" extension).

The experiment editor may feel daunting at first, with so many choices and options to be filled in. However, it is organized in logical subsections, as shown in Figure 1.

We will now discuss each of these regions in more detail, and how the various options affect the search process.





Specifying a parameter space

First, choose the model you are interested in exploring (with the "Browse for model" button, or by typing in the path). Let's assume you choose the Flocking model from NetLogo's models library (in the Biology category).

The next step is to specify settings, or ranges of settings, for each of the model's parameters. The easiest way to get started is to click the "Load param ranges from model interface" button, which will automatically extract the parameters/ranges that are included in your model's interface tab (i.e. SLIDERS, CHOOSERS, and SWITCHES).

Figure 2: An example search space specification for
the Flocking model from NetLogo's models library.

One search space specification for the Flocking model consists of the following definitions (also shown in Figure 2):

["population" 50]
["vision" [0 0.25 10]]
["minimum-separation" [0 0.25 5]]
["max-align-turn" [0 0.25 20]]
["max-separate-turn" [0 0.25 20]]
["max-cohere-turn" [0 0.25 20]]

In this case, the population parameter (number of birds) is being held constant, whereas each of the other parameters are allowed to range. For instance, the vision parameter ranges from 0 up to 10, by increments of 0.25.

The total size of this search space is 41×21×81×81×81 = 457570701 possible combinations of parameter settings.

You may notice that the syntax for specifying parameter ranges is very similar to that for BehaviorSpace. However, in BehaviorSearch it is also possible to specify a continuous range for a parameter, by using "C" for the increment -- see examples below.


Note: With BehaviorSearch you are specifying only the potential range of variables for the search space, unlike with BehaviorSpace, where every combination will be run. The size of the search space will often be very large, and the search algorithms you choose will only examine a small fraction of it. If you want to perform an exhaustive (factorial-type) search, you should use the BehaviorSpace tool that's built-in to NetLogo. BehaviorSearch is useful when you have a parameter space that's too large too enumerate, and you're willing to use heuristic search methods to try to find parameters that yield behavior that you're interested in.
Technical note: Although you may specify "C" for a continuous ranged parameter, the range may still be discretized if the search space encoding representation that you choose does not support continuous/ real-valued numbers. For instance, the StandardBinaryChromosome and GrayBinaryChromosome encodings will use only 16 bits for a continuous parameter, which allows the parameter to take on up to 65,536 values. For encodings that do allow continous parameters (such as MixedTypeChromosome), the "continuous" variable will technically be limited to 64-bit floating-point precision.



Designing a behavioral measure

Designing a quantative measure that captures the extent to which a model exhibits some type of behavior is often the most challenging part of the process. This is particularly the case if the behavior of interest is particularly qualitative in nature, or involves complex relationships between groups of agents. While it can sometimes be difficult to design an appropriate measure for your particular ABM and behavior, once you have done so it becomes possible to automate the task of searching for that behavior in your model. For the sake of this tutorial, we will only discuss reasonably simple and straightforward behavioral measures. However, in general the measures can be quite complex and powerful, and can address a variety of model exploration and analysis tasks.

Note: Proper methodology for the design of quantitative measures for ABM parameter search is an area of future research -- we plan to publish a more complete discussion of this topic, including a range of richer examples in the future. At present, some preliminary work discussing these ideas can be found on the papers page.)

Options for model running and data collection


For the Flocking model, one potentially interesting question is about the convergence of the flock of birds. In particular, let's investigate directional convergence (as opposed to positional convergence). In the Flocking model, the birds all start facing random directions, but (depending on the parameter settings) they may all converge on the same heading eventually. In this example, our search task will be to find what parameters cause the most convergence to happen quickly.

There are several things that we must specify, regarding how the model should be run, so that we can collect data that will help us search for the model conditions that cause convergence. Specifications for our example are shown in Figure 3; we will discuss them each in turn.

Figure 3: Specifying how the model should be run,
what data to collect, and when to record it.


For our convergence example, the measure is:

standard-deviation [dx] of turtles + standard-deviation [dy] of turtles

The measure can consist of any numeric NetLogo expression - what's important is that the measure is correlated with the behavior we would like to elicit from the model. In this case, we are measuring the sum of the variation of turtles headings in both the X and Y directions. When this measure is high, turtles are pointed all over. When this measure is 0, all of the turtles have exactly the same heading. Finding convergence is the same as minimizing this measure of flock heading variation. We will start recording this measure after 75 ticks have passed, and we are only running the model for 100 steps in total, meaning that we will be recording data between tick 75 and tick 100.

Designing the objective function:


Above, we specified how to collect the data we need from the model in order to perform our search. However, there are several more things that must be specified before our search goal is completely defined. We know how to collect the data, but now we need to turn it into an objective function (a.k.a. "fitness function"). For our flocking convergence example, the additional information we must fill in is shown in Figure 4.

Figure 4: Specifying the search goal/task
(the objective/fitness function)




Choosing a search algorithm

Once the objective function is fully specified, the final choice is about how the parameter space should be represented and explored. This involves choosing a search encoding representation (for the search space), as well as choosing a search algorithm and setting the necessary parameters for that search algorithm. The choices for the Flocking convergence example are shown in Figure 5.

Making choices: Choosing the search algorithm, search algorithm parameters, and search space representation can feel very daunting. The terminology is rather abstruse, and it's not necessarily clear what the best choice is. Part of our ongoing research agenda involves comparing the performance of various algorithms and developing guidelines for choosing efficient/appropriate search techniques. Eventually standards and guidelines will emerge, to help with this decision-making process. Until then, we offer a few general guidelines in this tutorial, and encourage you to explore several options and see what works best for you.

Poor choices may cause the search to progress more slowly (or totally stall). Thus, negative search results may mean that the behavior you're interested in never occurs in the model, or it may mean that you need to try other search methods. On the other hand, positive results tell you that the behavior does occur, and also what parameter settings can elicit it.

Figure 5: Search algorithm options
and search space representation.

Search Space Encoding Representation

The search space consists of all allowable combinations of settings for the model parameters, as you specified above. BehaviorSearch currently supports four different search space encodings (and its extensible architecture makes it simple to plug in new ones in the future):


Search Algorithms and Options

The search algorithm determines what order the different parameter settings will be tried in, in order to find the behavior that you quantified above.

BehaviorSearch currently includes 4 search algorithms (though additional algorithms will be added in future releases). Here is a description of each:


Note on mutation: The mutation-rate affects different search space representations differently. In the StandardBinary and GrayBinary encodings, the mutation-rate is the probability of each bit mutating, whereas for the MixedType and RealHypercube, it is the probability of each whole parameter mutating. Thus, you should generally use much higher mutation-rates (~ 0.5) for the MixedType and RealHypercube representations, and much lower rates (~ 0.02) for binary encodings.

Fitness Caching

There is also a checkbox labeled Use fitness caching. This controls whether the search algorithm caches (memorizes) the result of the objective (fitness) function every time it gets evaluated, so that it doesn't have to recompute it if the search returns to those exact same parameter settings again. Since running ABM simulations can be time-consuming (especially when dealing with large agent populations for many ticks), turning on "fitness caching" can potentially be a considerable time-saver. However, because ABMs are usually stochastic, each time a point in the space is re-evaluated, the search process would get a new independent estimation of the value at that location. The trade-offs in the interaction between the effects of fitness caching and "noisy" fitness evaluation have not been fully investigated -- at present it is unclear precisely when fitness caching will improve overall search performance.

For this tutorial example on Flocking convergence, we are using fitness caching and a GrayBinaryChromosome search space encoding representation, together with a standard generational GA with a population size of 30, a 5% mutation rate, and a crossover rate of 70%, using tournament selection with tournament size 3. For this model and search task, these choices were found to be effective (and far superior to RandomSearch). However, we have not exhaustively tested combinations of search algorithms, search algorithm parameters, and encodings, so other choices might prove to be more efficient.

Evaluation limit: How many total model runs should the search process perform, before stopping?

BestChecking replicates: the number of additional replicate model runs that should be performed to get an unbiased estimate of the true objective function value, each time the search algorithm finds a new set of parameters that it thinks is "better" than any previous set.