Command-line Options

At run time, Aspherix® recognizes several optional command-line options which may be used in any order. Either the full word or a one-or-two letter abbreviation can be used.

Basic options

-e <value>, -echo <value>

Supported values:

none
screen
log
both

Depending on the value, each command read from the input script will be echoed to the screen and/or logfile. This can be useful to figure out which line of your script is causing an input error. The default value is log. The echo style can also be set by using the echo command in the input script itself.

-i <input_script>, -in <input_script>: Specify a file to use as an input script.

This option is when running Aspherix® in one-partition mode. If it is not specified, Aspherix® reads its input script from stdin - e.g. aspherix < in.run. This option is required when running Aspherix® in multi-partition mode, i.e. on several processors, since multiple processors cannot all read from stdin.

-h, -help: Print available commandline options and help output.

Print list of options compiled available from the command line. Aspherix® will print the info and immediately exit if this option is used.

-l <log_file>, -log <log_file>: Specify log file for Aspherix® to write simulation information to.

By default, Aspherix® writes the log to the file log_aspherix.txt. Using this option, Aspherix® will instead write to the specified log file. Using a log command in the input script will override this setting.

-status <status_file>: Specify a status file for Aspherix® to write output produced by the status command to.

Writes the status output specified via the status and status_style commands to the specified file. By default, this file is called simulation_data_aspherix.csv.

-w <warn_file>, -warn <warn_file>: Specify warnings file for Aspherix® to write runtime warnings to.

By default, Aspherix® writes warnings to the file warnings_aspherix.txt. Using this option, Aspherix® will instead write to the specified log file. Using a warn command in the input script will override this setting.

-nc, -nocite: Disable writing the log.cite file.

Disable writing the log.cite file which is normally written to list references for specific cite-able features used during a Aspherix® run. See the citation page for more details.

-r <restart_file> <data_file>, restart <restart_file> <data_file>

Performs the same operation as if the following 2-line input script were run:

read_restart restartfile
write_data datafile

Note that the specified restartfile and datafile can have wild-card characters (\*, %) as described by the read_restart and write_data commands. However, a filename such as file.\* will need to be enclosed in quotes to avoid shell expansion of the \* character.

-sc <screen_file>, -screen <screen_file>: Specify a file for Aspherix® to write its screen information to.

By default, Aspherix® writes to the screen. If this option is used, Aspherix® writes to the specified file instead and you will see no screen output.

-v <var_name> <var_value(s)>, -var <var_name> <var_value(s)>

Defines the variable var_name for use in the input script. The variable name which can be a single character (referenced as $x in the input script) or a full string (referenced as ${abc}). An index-style variable will be created and populated with the subsequent values until the next command-line option is found.

Note

All subsequent, space-separated arguments will be considered as values until the next command-line option is found, i.e.

aspherix -var varname 1 2 3 -in input.asx

will be equivalent to the command

variable varname index 1 2 3

Using this command-line option is equivalent to putting the line variable var_name index value1 value2 ... at the beginning of the input script. Defining an index variable as a command-line argument overrides any setting for the same index variable within the input script, since index variables cannot be re-defined. See the variable command for more info on defining index and other kinds of variables.

License management command line options

-lp <license_path>, -license_path <license_path>: Supply a license file to Aspherix®.

With this option, a license file can be supplied to Aspherix®. This is only necessary if you have not given a valid license file during the installation process.

-dp <demopw>, -demo_password <demopw>: Set password if required by license file.

In case the license file represents a demo license, an additional password is required. This password can be entered here.

-re, -reinstall: Unpack the documentation and examples.

This option tells Aspherix® to unpack the documentation and examples. This is only necessary if no license file was available during installation.

-configuration <config>

This option defines whether the information given through -license_path and -demo_password is stored in the Aspherix® configuration. The three allowed values are and indicate how the settings are stored:

user: current user only
system: system-wide (may require administrator privileges)
install: relative to the installation path (may require admin privileges)

Hardware agnostic simulations on CPU or GPU

-gpu: Invoke Aspherix® on GPU.

The -gpu command line option will run Aspherix® with GPU support. Based on the available hardware, an architecture will be auto-selected.

-generic: Invoke Aspherix® without any multi-threading (CPU).

The -generic command line option will run Aspherix® in serial mode (single thread), which is essentially identical to Aspherix versions without GPU support.

-openmp

The -openmp command line option will run Aspherix® with multi-threading, where the number of threads N can be set via -num_threads command-line option or via the OMP_NUM_THREADS environment variable e.g.

OMP_NUM_THREADS=4 aspherix -in my_input.asx -openmp

OpenMP environment variables can also be set using the export command, such as

export OMP_NUM_THREADS=2
export OMP_PROC_BIND=close
export OMP_PLACES=cores

where the latter two keywords can be tuned for performance.

To run hybrid MPI/OpenMP runs, combine the mpirun command with the -openmp flag and the appropriate OpenMP enviroment variables such as OMP_NUM_THREADS and so on, e.g.,

OMP_NUM_THREADS=4 mpirun -np 2 aspherix -in my_input.asx -openmp

will launch 2 MPI processes with four OpenMP threads per process. Ideally this should use 2*4=8 cpus. For good performance with hybrid MPI/OpenMP runs it is typically necessary to specify the process mappings and bidings manually, using the appropriate OpenMP environment variables (see above) and MPI keywords, such as –bind-to core and –map-by core (see also –report-bindings and –display-map). Cluster job schedulers might also have dedicated keywords for that.

-num_threads <num_threads>: Specify the number of threads to use for multi-threading (CPU), see -openmp for more details.

-list_architectures: List all available compute architectures.

Shows the available hardware architectures on your system. It can be used to obtain a valid <NAME> for the -architecture command line option.

-architecture <architecture>: Invoke Aspherix® with the selected architecture. Use the -list_architectures to obtain a valid architecture.

-cuda_device <device_id>: Invoke Aspherix® on a GPU with selected index.

Runs Aspherix® on the GPU with device index <device_id>. This index starts at 0, and allows to select a specific GPU when there is more than one available.

Patching command line options

-slp <patch_systemlib>, -system_library_path <patch_systemlib>: System-wide path in which Aspherix searches for patching libraries.

Specifies a system-wide path in which Aspherix attempts to search for patching libraries. If you wish to write this information to the configuration add the -configuration option.

-ulp <patch_userlib>, -user_library_path <patch_userlib>: User-only path in which Aspherix searches for patching libraries.

Specifies a user-only path in which Aspherix attempts to search for patching libraries. If you wish to write this information to the configuration add the -configuration option. Note, patches found in the user path take precedence over those in the system path.

-ipa <patch_install>, -install_patch_archive <patch_install>: Install patch into the corresponding user or system library path.

Installs the <pathc_install> archive into the corresponding user or system library path dependent on the (mandatory) keyword -configuration. If install is chosen then the libraries are installed into lib/aspherix/patches relative to your installation path. The command does not, by default, overwrite existing files. For other behaviour see the following argument.

-op <patch_overwrite>, -overwrite_patches <patch_overwrite>: Overwrite already existing patch libraries.

When installing a patch archive (using -install_patch_archive) overwrite already existing patch libraries.

Additional options for partitioned simulations

These options apply only to simulations using different partitions and are not suitable for common MPI-parallel simulations.

-p <partition>, -partition <partition>: Invoke Aspherix® in multi-partition mode.

Invoke Aspherix® in multi-partition mode. When Aspherix® is run on P processors and this switch is not used, Aspherix® runs in one partition, i.e. all P processors run a single simulation. If this switch is used, the P processors are split into separate partitions and each partition runs its own simulation. The arguments to the switch specifies the number of processors in each partition. Arguments of the form MxN mean M partitions, each with N processors. Arguments of the form N mean a single partition with N processors. The sum of processors in all partitions must equal P. Thus the command -partition 8x2 4 5 has 10 partitions and runs on a total of 25 processors.

To run multiple independent simulations from one input script, using multiple partitions, see this HowTo of the manual. World- and universe-style variables are useful in this context.

-pl <plog_file>, -plog <plog_file>: Specify the base name for the partition log files.

Specify the base name for the partition log files, so partition N writes log information to plog_file.N. If file is none, then no partition log files are created. This overrides the filename specified in the -log command-line option. This option is useful when working with large numbers of partitions, allowing the partition log files to be suppressed (-plog none) or placed in a sub-directory (-plog replica_files/log.aspherix) If this option is not used the log file for partition N is log.aspherix.N or whatever is specified by the -log command-line option.

-pw <pwarn_file>, -pwarn <pwarn_file>: Specify the base name for the partition warning files.

Applies the same behvaior as -plog to the warning file.

-ps <pscreen_file>, -pscreen <pscreen_file>: Specify the base name for the partition screen file.

Applies the same behvaior as -plog to the screen file.

-ro <reorder>, -reorder <reorder>

Reorder the processors in the MPI communicator used to instantiate Aspherix®, in one of several ways. The original MPI communicator ranks all P processors from 0 to P-1. The mapping of these ranks to physical processors is done by MPI before Aspherix® begins. It may be useful in some cases to alter the rank order. E.g. to ensure that cores within each node are ranked in a desired order.

-reorder nth N
-reorder custom filename

If the keyword nth is used with a setting N, then it means every Nth processor will be moved to the end of the ranking. For example, if you use -reorder nth 4 and -partition 9 3 and you are running on 12 processors, the processors will be reordered from

0 1 2 3 4 5 6 7 8 9 10 11

to

0 1 2 4 5 6 8 9 10 3 7 11

so that the processors in each partition will be

0 1 2 4 5 6 8 9 10
3 7 11

See the processors command for how to ensure processors from each partition could then be grouped optimally for quad-core nodes.

If the keyword is custom, then a file that specifies a permutation of the processor ranks is also specified. The format of the reorder file is as follows. Any number of initial blank or comment lines (starting with a # character) can be present. These should be followed by P lines of the form:

I J

where P is the number of processors Aspherix® was launched with. Note that if running in multi-partition mode (see the -partition switch above) P is the total number of processors in all partitions. The I and J values describe a permutation of the P processors. Every I and J should be values from 0 to P-1 inclusive. In the set of P I values, every proc ID should appear exactly once. Ditto for the set of P J values. A single I,J pairing means that the physical processor with rank I in the original MPI communicator will have rank J in the reordered communicator.

Note that rank ordering can also be specified by many MPI implementations, either by environment variables that specify how to order physical processors, or by config files that specify what physical processors to assign to each MPI rank. The -reorder switch simply gives you a portable way to do this without relying on MPI itself. See the processors command command for how to output info on the final assignment of physical processors to the Aspherix® simulation domain.