HPX

PrevUpHomeNext

HPX Command Line Options

More Details about HPX Command Line Options

The predefined command line options for any application using hpx::init are described in the table below:

Table 13. Default HPX Command Line Options

Option

Description

HPX options (allowed on command line only)

 

--hpx:help

print out program usage (default: this message), possible values: 'full' (additionally prints options from components)

--hpx:version

print out HPX version and copyright information

--hpx:info

print out HPX configuration information

--hpx:options-file arg

specify a file containing command line options (alternatively: @filepath)

HPX options (additionally allowed in an options file)

 

--hpx:worker

run this instance in worker mode

--hpx:console

run this instance in console mode

--hpx:connect

run this instance in worker mode, but connecting late

--hpx:run-agas-server

run AGAS server as part of this runtime instance

--hpx:run-hpx-main

run the hpx_main function, regardless of locality mode

--hpx:hpx arg

the IP address the HPX parcelport is listening on, expected format: 'address:port' (default: 127.0.0.1:7910)

--hpx:agas arg

the IP address the AGAS root server is running on, expected format: 'address:port' (default: 127.0.0.1:7910)

--hpx:run-agas-server-only

run only the AGAS server

--hpx:nodefile arg

the file name of a node file to use (list of nodes, one node name per line and core)

--hpx:nodes arg

the (space separated) list of the nodes to use (usually this is extracted from a node file)

--hpx:endnodes

this can be used to end the list of nodes specified using the option --hpx:nodes

--hpx:ifsuffix arg

suffix to append to host names in order to resolve them to the proper network interconnect

--hpx:ifprefix arg

prefix to prepend to host names in order to resolve them to the proper network interconnect

--hpx:iftransform arg

sed-style search and replace (s/search/replace/) used to transform host names to the proper network interconnect

--hpx:localities arg

the number of localities to wait for at application startup (default: 1)

--hpx:node arg

number of the node this locality is run on (must be unique)

--hpx:ignore-batch-env

ignore batch environment variables

--hpx:expect-connecting-localities

this locality expects other localities to dynamically connect (this is implied if the number of initial localities is larger than 1)

--hpx:pu-offset

the first processing unit this instance of HPX should be run on (default: 0), valid for --hpx:queuing=local, --hpx:queuing=abp-priority, --hpx:queuing=static, and --hpx:queuing=local-priority only

--hpx:pu-step

the step between used processing unit numbers for this instance of HPX (default: 1), valid for --hpx:queuing=local, --hpx:queuing=abp-priority, --hpx:queuing=static and --hpx:queuing=local-priority only

--hpx:threads arg

the number of operating system threads to spawn for this HPX locality (default: 1, using 'all' will spawn one thread for each processing unit)

--hpx:cores arg

the number of cores to utilize for this HPX locality (default: 'all', i.e. the number of cores is based on the number of threads (--hpx:threads) assuming --hpx:bind=compact)

--hpx:affinity arg

the affinity domain the OS threads will be confined to, possible values: pu, core, numa, machine (default: pu), valid for --hpx:queuing=local, --hpx:queuing=abp-priority, --hpx:queuing=static, and --hpx:queuing=local-priority only

--hpx:bind arg

the detailed affinity description for the OS threads, see the additional documentation for a detailed description of possible values. Do not use with --hpx:pu-step, --hpx:pu-offset, or --hpx:affinity options. Implies --hpx:numa-sensitive (--hpx:bind=none disables defining thread affinities).

--hpx:print-bind

print to the console the bit masks calculated from the arguments specified to all --hpx:bind options.

--hpx:queuing arg

the queue scheduling policy to use, options are 'local/l', 'local-priority-fifo/lo', 'local-priority-lifo', 'abp/a', 'abp-priority', 'hierarchy/h', and 'periodic/pe' (default: local-priority-fifo/lo)

--hpx:hierarchy-arity

the arity of the of the thread queue tree, valid for --hpx:queuing=hierarchy only (default: 2)

--hpx:high-priority-threads arg

the number of operating system threads maintaining a high priority queue (default: number of OS threads), valid for --hpx:queuing=local, --hpx:queuing=abp-priority, and --hpx:queuing=local-priority only

--hpx:numa-sensitive

makes the local-priority scheduler NUMA sensitive, valid for --hpx:queuing=local, --hpx:queuing=abp-priority, --hpx:queuing=static, and --hpx:queuing=local-priority only

HPX configuration options

 

--hpx:app-config arg

load the specified application configuration (ini) file

--hpx:config arg

load the specified hpx configuration (ini) file

--hpx:ini arg

add a configuration definition to the default runtime configuration

--hpx:exit

exit after configuring the runtime

HPX debugging options

 

--hpx:list-symbolic-names

list all registered symbolic names after startup

--hpx:list-component-types

list all dynamic component types after startup

--hpx:dump-config-initial

print the initial runtime configuration

--hpx:dump-config

print the final runtime configuration

--hpx:debug-hpx-log [arg]

enable all messages on the HPX log channel and send all HPX logs to the target destination (default: cout)

--hpx:debug-agas-log [arg]

enable all messages on the AGAS log channel and send all AGAS logs to the target destination (default: cout)

--hpx:debug-parcel-log [arg]

enable all messages on the parcel transport log channel and send all parcel transport logs to the target destination (default: cout)

--hpx:debug-timing-log [arg]

enable all messages on the timing log channel and send all timing logs to the target destination (default: cout)

--hpx:debug-clp

debug command line processing

--hpx:attach-debugger arg

wait for a debugger to be attached, possible arg values: startup or exception (default: startup)

HPX options related to performance counters

 

--hpx:print-counter

print the specified performance counter either repeatedly and/or at the times specified by --hpx:print-counter-at (see also option --hpx:print-counter-interval)

--hpx:print-counter-reset

print the specified performance counter either repeatedly and/or at the times specified by --hpx:print-counter-at, reset the counter after the value is queried. (see also option --hpx:print-counter-interval)

--hpx:print-counter-interval

print the performance counter(s) specified with --hpx:print-counter repeatedly after the time interval (specified in milliseconds), (default: 0, which means print once at shutdown)

--hpx:print-counter-destination

print the performance counter(s) specified with --hpx:print-counter to the given file (default: console)

--hpx:list-counters

list the names of all registered performance counters, possible values: minimal (prints counter name skeletons), full (prints all available counter names)

--hpx:list-counter-infos

list the description of all registered performance counters, possible values: minimal (prints info for counter name skeletons), 'full' (prints all available counter infos)

--hpx:print-counter-format

print the performance counter(s) specified with --hpx:print-counter, possible formats in csv format with header or without any header (see option --hpx:no-csv-header), possible values: csv (prints counter values in CSV format with full names as header), csv-short (prints counter values in CSV format with shortnames provided with --hpx:print-counter as --hpx:print-counter shortname,full-countername)

--hpx:no-csv-header

print the performance counter(s) specified with --hpx:print-counter and csv or csv-short format specified with --hpx:print-counter-format without header

--hpx:printer-counter-at arg

print the performance counter(s) specified with --hpx:print-counter (or --hpx:print-counter-reset) at the given point in time, possible argument values: startup, shutdown (default), noshutdown

--hpx:reset-counters

reset all performance counter(s) specified with --hpx:print-counter after they have been evaluated

--hpx:print-counter-at

print the performance counter(s) specified with --hpx:print-counter (or --hpx:print-counter-reset) at the given point in time, possible argument are values: 'startup', 'shutdown' (default), 'noshutdown'.

--hpx:print-counters-locally

Each locality prints only its own local counters. If this is used with --hpx-print-counter-destination=<file>, the code will append a ".<locality_id>"` to the file name in order to avoid clashes between localities.


Command Line Argument Shortcuts

Additionally, the following shortcuts are available from every HPX application.

Table 14. Predefined command line option shortcuts

Shortcut option

Equivalent long option

-a

--hpx:agas

-c

--hpx:console

-h

--hpx:help

-I

--hpx:ini

-l

--hpx:localities

-p

--hpx:app-config

-q

--hpx:queuing

-r

--hpx:run-agas-server

-t

--hpx:threads

-v

--hpx:version

-w

--hpx:worker

-x

--hpx:hpx

-0

--hpx:node=0

-1

--hpx:node=1

-2

--hpx:node=2

-3

--hpx:node=3

-4

--hpx:node=4

-5

--hpx:node=5

-6

--hpx:node=6

-7

--hpx:node=7

-8

--hpx:node=8

-9

--hpx:node=9


It is possible to define your own shortcut options. In fact, all of the shortcuts listed above are pre-defined using the technique described here. Also, it is possible to redefine any of the pre-defined shortcuts to expand differently as well.

Shortcut options are obtained from the internal configuration database. They are stored as key-value properties in a special properties section named hpx.commandline. You can define your own shortcuts by adding the corresponding definitions to one of the ini configuration files as described in the section Configure HPX Applications. For instance, in order to define a command line shortcut --pc which should expand to --hpx:print-counter, the following configuration information needs to be added to one of the ini configuration files:

[hpx.commandline.aliases]
--pc = --hpx:print-counter
[Note] Note

Any arguments for shortcut options passed on the command line are retained and passed as arguments to the corresponding expanded option. For instance, given the definition above, the command line option

--pc=/threads{locality#0/total}/count/cumulative

would be expanded to

--hpx:print-counter=/threads{locality#0/total}/count/cumulative

[Important] Important

Any shortcut option should either start with a single '-' or with two '--' characters. Shortcuts starting with a single '-' are interpreted as short options (i.e. everything after the first character following the '-' is treated as the argument). Shortcuts starting with '--' are interpreted as long options. No other shortcut formats are supported.

Specifying Options for Single Localities Only

For runs involving more than one locality it is sometimes desirable to supply specific command line options to single localities only. When the HPX application is launched using a scheduler (like PBS, for more details see section Using PBS), specifying dedicated command line options for single localities may be desirable. For this reason all of the command line options which have the general format --hpx:<some_key> can be used in a more general form: --hpx:<N>:<some_key>, where <N> is the number of the locality this command line options will be applied to, all other localities will simply ignore the option. For instance, the following PBS script passes the option --hpx:pu-offset=4 to the locality '1' only.

#!/bin/bash
#
#PBS -l nodes=2:ppn=4

APP_PATH=~/packages/hpx/bin/hello_world
APP_OPTIONS=

pbsdsh -u $APP_PATH $APP_OPTIONS --hpx:1:pu-offset=4 --hpx:nodes=`cat $PBS_NODEFILE`
[Caution] Caution

If the first application specific argument (inside $APP_OPTIONS) is a non-option (i.e. does not start with a '-' or a '--', then it must be placed before the option --hpx:nodes, which, in this case, should be the last option on the command line.

Alternatively, use the option --hpx:endnodes to explicitly mark the end of the list of node names:

pbsdsh -u $APP_PATH --hpx:1:pu-offset=4 --hpx:nodes=`cat $PBS_NODEFILE` --hpx:endnodes $APP_OPTIONS

PrevUpHomeNext