Skip to content

Configuration Settings

Jump to bottom Edit New page
Pete Schultz edited this page May 16, 2017 · 3 revisions

This page describes the configuration settings for a PetaVision run. There are two ways to specify configuration settings: through a config file, or on the command line. Not all config settings are available through the command line, but for simple runs it may be easier to specify settings on the command line than to set up a config file.

Configuration Settings

The configuration settings are listed below. Each setting is either boolean, integer, or string. Boolean arguments must be either true or false; integer arguments must be an integer (more technically, a string understood by the std::stoi library function).

  • RequireReturn (boolean). If true, the Communicator will pause during initialization, and wait for the return key to be pressed (more technically, it waits until the getc library function returns a linefeed). If false, the Communicator object does not pause. The default is false.

  • OutputPath (string). This specifies the directory used for output files, for example the PVP files for layers and connections, and the measurements from probes. The output path can also be specified in the HyPerCol parameters in the params file (below). If the config settings and the params file specify an output path, the config setting takes precedence. Relative paths are relative to the working directory. If the OutputPath directory does not exist, it will be created. The default is "output".

  • ParamsFile (string). This specifies the path for the params file, which specifies the parameters of the HyPerCol, layers, connections and probes. There is no default; a params file must be specified. Relative values are relative to the working directory.

  • LogFile (string). This specifies a path for informational, warning, and error messages. If run with more than one MPI process, nonroot processes have their global rank inserted either before the extension if there is one, or at the end of the path if there is not. For example, with a log file of petavision.log, the root process writes to that file, the process with rank 1 writes to petavision_1.log, and so on.

Relative paths are relative to the working directory. If no log file is specified, informational messages are sent to stdout, and warnings and errors are sent to stderr.

  • GPUDevices (string). This is a comma-separated list of GPU device numbers. If a single value is specified, all processes will use that GPU device. If more than one value is specified, processes will cycle through the list according to their rank.

  • RandomSeed (integer). This specifies the base random seed for the column. Layers, connections, and other objects that use random numbers obtain a random seed based on this random seed. Seeding random number generators is handled at the column level to help ensure independence and reproducibility. The default is generated by the clock time at the time the HyPerCol is initialized.

  • WorkingDirectory (string). If nonempty, change to the given directory during initialization of the HyPerCol.

  • Restart (boolean). If true, perform a warm restart. If the HyPerCol parameter checkpointWriteFlag is true, restarts from the highest-indexed checkpoint in the CheckpointWriteDir directory. If checkpointWriteFlag is false, restart from the lastCheckpointDir directory. It is an error to set both the Restart flag and the CheckpointReadDirectory (below). The default is false.

  • CheckpointReadDirectory (string). If nonempty, load a checkpoint from the given path. PetaVision assumes that after loading the checkpoint, the column is in the same state as it was when the checkpoint was written. In particular, it is assumed that the params file of the current run has the same parameters as the older run; however, this assumption is not set or enforced. It is an error to set both the Restart flag (above) and the CheckpointReadDirectory. The default is empty.

  • NumThreads (integer). The number of OpenMP threads for each process to use. The default is the number of available processes (as returned by the OpenMP omp_max_get_threads() library function) divided by the number of MPI processes in the column. Note that the default will underutilize the machines' capability if the run is spread across several machines. The default can also be specified by using the argument -.

  • NumColumns (integer). Specifies the number of MPI processes in the x-direction for the MPI arrangement. See [MPI-in-PetaVision] for more details on the MPI arrangement. The default is 1.

  • NumRows (integer). Specifies the number of MPI processes in the y-direction for the MPI arrangement. See [MPI-in-PetaVision] for more details on the MPI arrangement. The default is 1.

  • BatchWidth (integer). Specifies the number of MPI processes in the batch direction. See [MPI-in-PetaVision] for more details on the MPI arrangement. The default is 1.

  • CheckpointCellNumColumns (integer). Specifies the number of MPI processes in the x-direction for one input/output MPI block. See [MPI-in-PetaVision] for more details on input/output MPI blocks. The default is the value of NumColumns.

  • CheckpointCellNumRows (integer). Specifies the number of MPI processes in the y-direction for one input/output MPI block. See [MPI-in-PetaVision] for more details on input/output MPI blocks. The default is the value of NumRows.

  • CheckpointCellBatchDimension (integer). Specifies the number of MPI processes in the batch direction for one input/output MPI block. See [MPI-in-PetaVision] for more details on input/output MPI blocks. The default is the value of BatchWidth.

  • DryRun (boolean). If set, calling HyPerCol::run will instantiate the layers, connections, and probes, and set the initial values, but will not execute any timesteps of the simulation. It does write a params file to the outputPath directory. This option is useful for checking that the column will build without error, and for inspecting the generated params file for errors.

Specifying settings with a config file

  • When the PV_Init object is instantiated, the arguments (typically arguments on the command line) are scanned. If the first argument does not begin with a hyphen, it is assumed to be the path to a config file. This file is parsed for config settings as follows.

If a line is completely whitespace or if the first non-whitespace character is the number sign #, it skipped as a comment. All other lines must have the form SettingName:SettingValue. For example, you could have the following as a config file.

ParamsFile:example.params
NumThreads:8
NumColumns:2
NumRows:2

If the config file is specified, any other arguments on the command line are ignored, except for --require-return; if present this argument replaces RequireReturn to true regardless of its value in the config file. The order in which settings are specified does not matter.

Specifying settings on the command line

If the first argument does begin with a hyphen, the config settings are defined on the command line and a config file is not used. Not all config settings are available on the command line.

For example, if the config file in the previous section is at config.txt, and the executable is called pvrun, the following commands are equivalent:

pvrun config.txt
pvrun -p example.params -t 8 -columns 2 -rows 2

Note that there must be whitespace between the option and its argument, even when the option is specified by a single layer.

The complete list of command line settings is as follows:

  • -p filename: corresponds to ParamsFile:filename in a config file.

  • -o directory: corresponds to OutputPath:directory.

  • -s seed: corresponds to RandomSeed:seed.

  • -d deviceSpec: corresponds to GPUDevices:deviceSpec.

  • -l logfile.log: corresponds to LogFile:logfile.log.

  • -w directory: corresponds to WorkingDirectory:directory.

  • -r: corresponds to Restart:true. Since the default of Restart is false, there is no command line switch for Restart:false; simply omit -r.

  • -c directory: corresponds to CheckpointReadDirectory:directory. Just as a config file cannot specify both Restart:true and a CheckpointReadDirectory, the command line cannot specify both a -r and -c option.

  • -columns n: corresponds to NumColumns:n.

  • -rows n: corresponds to NumRows:n.

  • -batchwidth n: corresponds to BatchWidth:n.

  • -t n: corresponds to NumThreads:n.

  • -t without an integer argument following corresponds to NumThreads:-.

  • -n: corresponds to DryRun:true.

Add a custom footer
Add a custom sidebar
Clone this wiki locally