`BSEARCH_MAXMEM` is not documented in the CLI help output

[danielvartan]

Originally posted at NetLogo/NetLogo#2673 (comment).

Hi there,

BSEARCH_MAXMEM controls the JVM heap size (default: 1536m) and is especially useful for parallel/multi-threaded runs. It is only documented inside a comment in behaviorsearch_headless.sh, making it effectively invisible to anyone who hasn't read the source.

At minimum, it should appear in the --help output as a documented environment variable. A proper --max-mem CLI flag would be even better.

---

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 "$@"