Parameter Search

Parameter Search

The ParameterSearch executable class is one of the main entry points to using TAG. It can be used to tune either AI agent parameters (see here), or Game parameters (see here). This page attempts to document all the run-time options available. For the most up-to-date summary, you can also look at the code, and/or by executing:

java -jar ParameterSearch.jar --help

The optimisation algorithm used is NTBEA (N-Tuple Bandit Evolutionary Optimisation), and full details of this can be found in the following paper:

Lucas, Simon M., Jialin Liu, and Diego Perez-Liebana. 2018. ‘The N-Tuple Bandit Evolutionary Algorithm for Game Agent Optimisation’. In IEEE Congress on Evolutionary Computation (CEC). Rio de Janeiro. https://doi.org/10.1109/CEC.2018.8477869.

All arguments are specified by command line tags:

Tag Description Default
searchSpace= A filename for a Search Space definition in json format. See details here or here None
iterations= The number of NTBEA iterations to run in each trial. None
game= The game for which we are optimising an AI agent, or which we are tuning directly, e.g. TicTacToe, Uno, or LoveLetter. None
nPlayers= The total number of players in each game The minimum permitted
evalGames= The number of games to run after each NTBEA run with the best predicted setting to estimate its true value. 20% of NTBEA iterations
repeats= The number of times NTBEA should be run from scratch, using the full set of iterations in each, to find a single best recommendation. Any one NTBEA run can give a poor recommendation, and given a budget of X total iterations is is empirically better to run 10 runs, each using X/10 iterations. (See this paper for detailed experiments on test domains that show this.) 1
matchups= If this is non-zero, then after all repeats, a final Tournament will be run with all the recommended agents from each run. This can be used to provide a final recommendation. 0
tuneGame= If true then we are tuning game parameters. If false, then we are optimising an AI agent. false
useThreeTuples= If true then NTBEA will use 1-, 2-, 3- and N-Tuples in its model. Only 1-, 2-, N-Tuples used.
verbose= If true then the results marginalised to each dimension will be logged, plus the Top 10 best tuples for each run. This can be useful to get a feel for the important dimensions in the search space false
opponent= The agent(s) used as opponent. Detailed options below. random
evalMethod= Defines the objective to optimise. When tuning an AI agent this is one of Score, Ordinal, Heuristic, Win. For tuning a game this is a json file detailing an IGameHeuristic (see Game Tuning for details) Win
kExplore= The k value used by NTBEA. This should be scaled to be appropriate to the range of the objective function. The default works well for values in {-1, 0, 1} 1.0
neighbourhood= The size of neighbourhood to look at in NTBEA during each iteration. min(50, \|searchSpace\| * 0.01)
seed= Random seed for Game use (not used by NTBEA itself). System.currentTimeMillis()
gameParams= A json file detailing the game parameters to use (only if optimising an AI agent; this is ignored if tuning a game). See here for details. Game defaults
listener= The full name of an IGameListener implementation or the location of a JSON file from which a listener can be instantiated. A pipe-delimited list can be provided to gather many types of statistics. See section below on Listeners evaluation.listeners.MetricsGameListener
metrics= (Optional) The full class name of an IMetricsCollection implementation. The recommended usage is to include these in the JSON file that defines the listener. evaluation.metrics.GameMetrics
destDir= The directory to which any reported metrics will be written. If this is run for multiple games and/or player counts, then a sub-directory will be created for each. metrics\out
output= Output file with results of each run for easier later analysis. Contains one line per NTBEA run with recommended settings. A separate file will also be generated with the result of any final tournament (see matchups. No file logging
NTBEAMode= NTBEA is the default. CoopNTBEA will tune one agent for all players (for coop games). NTBEA
config= If this is provided it overrides all other parameters, and should be the only one provided. This is then the name of a JSON file which details the parameters to use, with each parameter as a name-value JSON pair. None

Opponent

The value provided for opponent= can be any of:

  • one of mcts, rmhc, random, osla to use the default implementations, with default parameter. (Useful for random or osla; not recommended for mcts or rmhc, in which case you should define a json-file instead.
  • the full classname of a class that extends AbstractPlayer and has a no-argument constructor
  • the name of a json-format file that details the parameters of an agent to use (see details).
  • the name of a directory that contains one or more json-format files, each detailing an agent. The players/opponents in a game will then be sampled from this set of agents.

If tuneGame is set, then the opponent argument must be provided, and will be used for all players.

Tuning an Agent

In this mode, each NTBEA iteration will sample a different set of agent parameters (as defined in the Search Space). This will be used for one player (at a random position), with all the other players using agents defined by the opponent= setting. The exception to this is NTBEAMode=coop, in which case the single NTBEA sample is used for all players

Tuning a Game

In this mode opponent= is a mandatory setting. On each NTBEA iteration a new set of game parameters are used, and all of the players are sampled from the opponent setting.