Skip to content

Update documentation for BehaviorSearch #2673

Description

@danielvartan

Hi there,

At the moment, the documentation for BehaviorSearch lives on its own website and has not been updated in a while. Since it is bundled with NetLogo, I think it deserves proper documentation on the NetLogo website, like BehaviorSpace.

This could include, for example, instructions on how to use it in headless mode, including the BSEARCH_MAXMEM environment variable.

It would also be worth adding BSEARCH_MAXMEM as an explicit argument.


Location of BehaviorSearch headless: "$NETLOGO_HOME/behaviorsearch/behaviorsearch_headless.sh".

behaviorsearch_headless.sh [options...] arguments...
 --override-parameter-spec VAL         : override the parameter spec/range given
                                          in the .bsearch file, using usual synt
                                         ax (e.g. ["population" 100 200 400] (NO
                                         TE: you may need to \ escape the quotes
                                          in your shell)
 --shorten N                           : only print information to the .objectiv
                                         eFunctionHistory.csv after every Nth mo
                                         del run.
 --suppress-best-history               : don't create the .bestHistory.csv file
 --suppress-model-run-history          : don't create the .modelRunHistory.csv f
                                         ile
 --suppress-objective-function-history : don't create the .objectiveFunctionHist
                                         ory.csv file
 -b (--brief-output)                   : shorthand flag for suppressing model-ru
                                         n-history and objective-function-histor
                                         y output, since these are the largest o
                                         utput files.
 -f (--firstsearchnum) N               : searches will be numbered starting at t
                                         his index (only affects search # column
                                          in the output data)
 -n (--numsearches) N                  : number of times to repeat the search (d
                                         efault 1)
 -o (--output) VAL                     : output filename STEM: will create files
                                          named STEM.xxxx.csv
 -p (--protocol) VAL                   : file (.bsearch) from which to load the
                                         search experiment protocol.
 -q (--quiet)                          : suppress printing progress to stdout
 -r (--randomseed) N                   : random seed to start the first search (
                                         additional searches will be seeded with
                                          following consecutive numbers)
 -t (--threads) N                      : number of simultaneous threads to run t
                                         he search with (defaults to the number
                                         of processors available).
 -v (--version)                        : print version number and exit

  Example: behaviorsearch_headless.sh -p myexperiment.bsearch -o myoutput --threads 1 -n 5

behaviorsearch_headless.sh content:

#!/bin/bash

WD="`pwd`"  #store the current working directory, where this script was called from.

#BehaviorSearch needs to start in the NetLogo base folder,
# and "behaviorsearch" must be installed in a subfolder of the NetLogo folder.
BSEARCH_DIR="`dirname "$0"`" # the copious quoting is for handling paths with spaces
cd "$BSEARCH_DIR"
BSEARCH_DIR="`pwd`"  #in case it's a relative path, like "."
cd ..
LIBRARY_DIR="`pwd`/lib/app"  #in case it's a relative path, like "."
JARS=""
for f in `ls -1 "$LIBRARY_DIR" | grep "jar"`; do
  JARS="$LIBRARY_DIR/$f:$JARS"
done

# If you want to use a different version of java, or if "java" is not in your PATH, 
# you can run this script with the BSEARCH_JAVA environment variable pointing 
# to the java executable you want to use. e.g. "/opt/java6/bin/java"
if [ -z "$BSEARCH_JAVA" ]; then 
	BSEARCH_JAVA="java"
fi

JAVA_VERSION=`"$BSEARCH_JAVA" -version 2>&1 | head -n1 | awk '{ print substr($3,2,3) }' | sed -e 's;\.;0;g'`
if [ $JAVA_VERSION -lt 108 ]; then  #108 = java 1.8
	echo "Sorry, this program requires Java Runtime Environment 1.8 or higher"
	exit 1
fi

# If you have enough RAM, up the '1536m' below to '2048m' or more.
# Or you can set the BSEARCH_MAXMEM environment variable when running the script
# More RAM is especially helpful for multiple threads/parallel execution.
if [ -z "$BSEARCH_MAXMEM" ]; then
    BSEARCH_MAXMEM=1536m
fi

"$BSEARCH_JAVA" -Dbsearch.startupfolder="$WD" -Dbsearch.appfolder="$BSEARCH_DIR" -server -Xms256m "-Xmx$BSEARCH_MAXMEM" -classpath "$JARS" bsearch.app.BehaviorSearch "$@"

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    Fields

    No fields configured for Task.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions