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.

The first three arguments have a fixed order:

Position Name Description
1 Search Space A filename for a Search Space definition in json format. See details here or here
2 NTBEA iterations The number of NTBEA iterations to run in each trial.
3 Game The game for which we are optimising an AI agent, or which we are tuning directly, e.g. TicTacToe, Uno, or LoveLetter.

The remaining arguments are all specified by command line tags:

Tag Description Default
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
repeat= 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
tuneGame If supplied then we are tuning game parameters. If not supplied, then we are optimising an AI agent.
useThreeTuples If supplied then NTBEA will use 1-, 2-, 3- and N-Tuples in its model. Only 1-, 2-, N-Tuples are used.
verbose If supplied 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 Off
opponent= The agent(s) used as opponent. Mandatory if tuning a game. Detailed options below. Uses MultiNTBEA
playerDupes= If set to true, and if opponent refers to a directory with many files, then this will sample players in any game randomly allowing for duplicate agents. The default ensures that no single agent will duplicated in this case. false
gameParam= 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
eval= 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
hood= 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()
logFile= Output file with results of each run for easier later analysis. Contains one line per NTBEA run with recommended settings. No file logging

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.
  • coop if the agent being tuned (via the SearchSpace) should be used for all players (generally if the game is co-operative).

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 two exceptions to this are:

  • opponent=coop, in which case the single NTBEA sample is used for all players
  • opponent not provided. The default in this case is to sample independently for each agent in a form of co-evolution (‘MultiNTBEA’). At the time of writing (Jan 2022), this is an algorithm in development and not recommended for general use.

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.