negmas CLI¶
The negmas CLI provides a unified interface to all NegMAS commands including Genius setup,
tournaments, documentation access, and more.
Installation¶
The negmas command is automatically available after installing NegMAS:
$ pip install negmas
Basic Usage¶
Run the main help to see all available subcommands:
$ negmas --help
Common subcommands include:
negmas genius-setup- Download and configure the Genius bridgenegmas genius- Start the Genius bridge for Java agent integrationnegmas tournament- Run negotiation tournaments
Command Reference¶
negmas¶
Usage
negmas [OPTIONS] COMMAND [ARGS]...
docs¶
Opens negmas docs in the browser. Make sure to install the docs first using negmas docs-setup
Usage
negmas docs [OPTIONS]
docs-setup¶
Downloads and installs docs to ~/negmas/docs
Usage
negmas docs-setup [OPTIONS]
genius¶
Start the bridge to genius (to use GeniusNegotiator)
Usage
negmas genius [OPTIONS]
Options
- -p, --path <path>¶
- Path to geniusbridge.jar with embedded NegLoader. Use “auto” to read the path from ~/negmas/config.json
Config key is genius_bridge_jar
You can download this jar from: https://yasserfarouk.github.io/files/geniusbridge.jar
- Default:
'auto'
- -r, --port <port>¶
Port to run the NegLoader on. Pass 0 for the default value
- Default:
25337
- --debug, --no-debug¶
Run the bridge in debug mode if –debug else silently
- Default:
False
- --verbose, --silent¶
Verbose output
- Default:
True
- --save-logs, --no-logs¶
Save logs
- Default:
False
- --die-on-exit, --no-die-on-exit¶
Whether to kill the bridge on exit. For future use. Currently it does nothing.
- Default:
False
- --use-shell, --no-shell¶
Whether to start the new process in a shell
- Default:
False
- --force-timeout, --no-forced-timeout¶
Whether to force a timeout on the bridge
- Default:
True
- --timeout <timeout>¶
The timeout to pass. Zero or negative numbers to disable and use the bridge’s global timeout.
- Default:
0
- --log-path <log_path>¶
Directory to save logs within. Only used if –save-logs. If not given, ~/negmas/logs will be used
genius-setup¶
Downloads the genius bridge and updates your settings
Usage
negmas genius-setup [OPTIONS]
tournament¶
Usage
negmas tournament [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...
Options
- --ignore-warnings, --show-warnings¶
Ignore/show runtime warnings
- Default:
False
combine¶
Combine multiple tournaments at the given base path(s)
Usage
negmas tournament combine [OPTIONS] [PATH]...
Options
- --verbose, --silent¶
Whether to be verbose
- Default:
True
- -d, --dest <dest>¶
The location to save the results
- --config <config>¶
Read configuration from FILE.
- Default:
Sentinel.UNSET
Arguments
- PATH¶
Optional argument(s)
combine-results¶
Combine results from multiple tournaments
Usage
negmas tournament combine-results [OPTIONS] [PATH]...
Options
- -d, --dest <dest>¶
The location to save the results
- --metric <metric>¶
The statistical metric used for choosing the winners. Possibilities are mean, median, std, var, sum, truncated_mean
- Default:
'truncated_mean'
- --max-sources <max_sources>¶
Maximum number of sources to use. Default to all available
- --significance, --no-significance¶
Whether to show significance table
- Default:
False
- --verbose, --silent¶
Whether to be verbose
- Default:
True
- --config <config>¶
Read configuration from FILE.
- Default:
Sentinel.UNSET
Arguments
- PATH¶
Optional argument(s)
create¶
Creates a tournament
Usage
negmas tournament create [OPTIONS]
Options
- -n, --name <name>¶
The name of the tournament. The special value “random” will result in a random name
- Default:
'random'
- -t, --timeout <timeout>¶
Timeout the whole tournament after the given number of seconds (0 for infinite)
- Default:
0
- --configs <configs>¶
Number of unique configurations to generate.
- Default:
5
- --runs <runs>¶
Number of runs for each configuration
- Default:
2
- --max-runs <max_runs>¶
Maximum total number of runs. Zero or negative numbers mean no limit
- Default:
-1
- --steps-min <steps_min>¶
Minimum number of steps (only used if –steps was not passed
- Default:
50
- --steps-max <steps_max>¶
Maximum number of steps (only used if –steps was not passed
- Default:
100
- --agents <agents>¶
Number of agents per competitor
- Default:
3
- --competitors <competitors>¶
A semicolon (;) separated list of agent types to use for the competition.
- Default:
Sentinel.UNSET
- --non-competitors <non_competitors>¶
A semicolon (;) separated list of agent types to exist in the worlds as non-competitors (their scores will not be calculated).
- Default:
Sentinel.UNSET
- -l, --log <log>¶
Default location to save logs (A folder will be created under it)
- Default:
PosixPath('/home/docs/negmas/logs/tournaments')
- --world-config <world_config>¶
A file to load extra configuration parameters for world simulations from.
- Default:
- --verbosity <verbosity>¶
verbosity level (from 0 == silent to 1 == world progress)
- Default:
1
- --log-ufuns, --no-ufun-logs¶
Log ufuns into their own CSV file. Only effective if –debug is given
- Default:
False
- --log-negs, --no-neg-logs¶
Log all negotiations. Only effective if –debug is given
- Default:
False
- --compact, --debug¶
If True, effort is exerted to reduce the memory footprint whichincludes reducing logs dramatically.
- Default:
True
- --raise-exceptions, --ignore-exceptions¶
Whether to ignore agent exceptions
- Default:
True
- --path <path>¶
A path to be added to PYTHONPATH in which all competitors are stored. You can path a : separated list of paths on linux/mac and a ; separated list in windows
- Default:
''
- --config-generator <config_generator>¶
The full path to a configuration generator function that is used to generate all configs for the tournament. MUST be specified
- Default:
''
- --world-generator <world_generator>¶
The full path to a world generator function that is used to generate all worlds (given the assigned configs for the tournament. MUST be specified
- Default:
''
- --assigner <assigner>¶
The full path to an assigner function that assigns competitors to different configurations
- Default:
''
- --scorer <scorer>¶
The full path to a scoring function
- Default:
''
- --cw <cw>¶
Number of competitors to run at every world simulation. It must either be left at default or be a number > 1 and < the number of competitors passed using –competitors
- --config <config>¶
Read configuration from FILE.
- Default:
Sentinel.UNSET
eval¶
Evaluates a tournament and returns the results
Usage
negmas tournament eval [OPTIONS] PATH
Options
- --metric <metric>¶
The statistical metric used for choosing the winners. Possibilities are mean, median, std, var, sum, truncated_mean
- Default:
'truncated_mean'
- --significance, --no-significance¶
Whether to show significance table
- Default:
False
- --compile, --show¶
Whether to recompile results from individual world runs or just show the already-compiled results
- Default:
True
- --verbose, --silent¶
Whether to be verbose
- Default:
True
- --config <config>¶
Read configuration from FILE.
- Default:
Sentinel.UNSET
Arguments
- PATH¶
Required argument
run¶
Runs/continues a tournament
Usage
negmas tournament run [OPTIONS]
Options
- -n, --name <name>¶
The name of the tournament. When invoked after create, there is no need to pass it
- Default:
''
- -l, --log <log>¶
Default location to save logs
- Default:
PosixPath('/home/docs/negmas/logs/tournaments')
- --verbosity <verbosity>¶
verbosity level (from 0 == silent to 1 == world progress)
- Default:
1
- --parallel, --serial¶
Run a parallel/serial tournament on a single machine
- Default:
True
- --distributed, --single-machine¶
Run a distributed tournament using dask
- Default:
False
- --ip <ip>¶
The IP address for a dask scheduler to run the distributed tournament. Effective only if –distributed
- Default:
'127.0.0.1'
- --port <port>¶
The IP port number a dask scheduler to run the distributed tournament. Effective only if –distributed
- Default:
8786
- --compact, --debug¶
If True, effort is exerted to reduce the memory footprint whichincludes reducing logs dramatically.
- Default:
True
- --path <path>¶
A path to be added to PYTHONPATH in which all competitors are stored. You can path a : separated list of paths on linux/mac and a ; separated list in windows
- Default:
''
- --metric <metric>¶
The statistical metric used for choosing the winners. Possibilities are mean, median, std, var, sum, truncated_mean
- Default:
'truncated_mean'
- --significance, --no-significance¶
Whether to show significance table
- Default:
False
- --eval, --no-eval¶
Whether evaluate and show results after the tournament is run
- Default:
False
- --config <config>¶
Read configuration from FILE.
- Default:
Sentinel.UNSET
winners¶
Finds winners of a tournament or a set of tournaments sharing a root
Usage
negmas tournament winners [OPTIONS]
Options
- -n, --name <name>¶
The name of the tournament. When invoked after create, there is no need to pass it
- Default:
''
- -l, --log <log>¶
Default location to save logs
- Default:
PosixPath('/home/docs/negmas/logs/tournaments')
- --recursive, --no-recursive¶
Whether to recursively look for tournament results. –name should not be given if –recursive
- Default:
True
- --metric <metric>¶
The statistical metric used for choosing the winners. Possibilities are mean, median, std, var, sum, truncated_mean
- Default:
'truncated_mean'
- --verbose, --silent¶
Whether to be verbose
- Default:
True
- --significance, --no-significance¶
Whether to show significance table
- Default:
False
- --compile, --show¶
Whether to recompile results from individual world runs or just show the already-compiled results
- Default:
True
- --config <config>¶
Read configuration from FILE.
- Default:
Sentinel.UNSET
version¶
Prints NegMAS version
Usage
negmas version [OPTIONS]