2.3. Initialization

When it comes to running Viskores code, there are a few ways in which various facilities, such as logging device connections, and device configuration parameters, can be initialized. The preferred method of initializing these features is to run the viskores::cont::Initialize() function. Although it is not strictly necessary to call viskores::cont::Initialize(), it is recommended to set up state and check for available devices.

InitializeResult viskores::cont::Initialize(int &argc, char *argv[], InitializeOptions opts = InitializeOptions::None)

Initialize the Viskores library, parsing arguments when provided:

• Sets log level names when logging is configured.

• Sets the calling thread as the main thread for logging purposes.

• Sets the default log level to the argument provided to --viskores-log-level.

• Forces usage of the device name passed to --viskores-device.

• Prints usage when -h or --viskores-help is passed.

The parameterless version only sets up log level names.

Additional options may be supplied via the opts argument, such as requiring the --viskores-device option.

Results are available in the returned InitializeResult.

Note

This method may call exit() on parse error.

viskores::cont::Initialize() can be called without any arguments, in which case Viskores will be initialized with defaults. But it can also optionally take the argc and argv arguments to the main function to parse some options that control the state of Viskores. Viskores accepts arguments that, for example, configure the compute device to use or establish logging levels. Any arguments that are handled by Viskores are removed from the argc/argv list so that your program can then respond to the remaining arguments.

Many options can also be set with environment variables. If both the environment variable and command line argument are provided, the command line argument is used. The following table lists the currently supported options.

Table 2.1 Viskores command line arguments and environment variable options.

Command Line Argument	Environment Variable	Default Value	Description
--viskores-help			Causes the program to print information about Viskores command line arguments and then exits the program.
--viskores-log-level	VISKORES_LOG_LEVEL	WARNING	Specifies the logging level. Valid values are INFO, WARNING, ERROR, FATAL, and OFF. This can also be set to a numeric value for the logging level.
--viskores-device	VISKORES_DEVICE		Force Viskores to use the specified device. If not specified or Any given, then any available device may be used.
--viskores-num-threads	VISKORES_NUM_THREADS		Set the number of threads to use on a multi-core device. If not specified, the device will use the cores available in the system.
--viskores-device-instance	VISKORES_DEVICE_INSTANCE		Selects the device to use when more than one device device of a given type is available. The device is specified with a numbered index.

viskores::cont::Initialize() returns a viskores::cont::InitializeResult structure. This structure contains information about the supported arguments and options selected during initialization.

struct InitializeResult

Public Members

DeviceAdapterId Device = DeviceAdapterTagUndefined{}

The device passed into --viskores-device argument.

If no device was specified, then this value is set to DeviceAdapterTagUndefined. Note that if the user specifies “any” device, then this value can be set to DeviceAdapterTagAny, which is a pseudo-tag that allows any supported device.

std::string Usage

A usage statement for arguments parsed by Viskores.

If the calling code wants to print a usage statement documenting the options that can be provided on the command line, then this string can be added to document the options supported by Viskores.

viskores::cont::Initialize() takes an optional third argument that specifies some options on the behavior of the argument parsing. The options are specified as a bit-wise “or” of fields specified in the viskores::cont::InitializeOptions enum.

enum class viskores::cont::InitializeOptions

Values:

enumerator None

Placeholder used when no options are enabled.

This is the value used when the third argument to viskores::cont::Initialize is not provided.

enumerator RequireDevice

Issue an error if the device argument is not specified.

enumerator DefaultAnyDevice

If no device is specified, treat it as if the user gave --viskores-device=Any.

This means that DeviceAdapterTagUndefined will never be returned in the result.

enumerator AddHelp

Add a help argument.

If -h or --viskores-help is provided, prints a usage statement. Of course, the usage statement will only print out arguments processed by Viskores, which is why help is not given by default. Alternatively, a string with usage help is returned from viskores::cont::Initialize so that the calling program can provide Viskores’s help in its own usage statement.

enumerator ErrorOnBadOption

If an unknown option is encountered, the program terminates with an error and a usage statement is printed.

If this option is not provided, any unknown options are returned in argv. If this option is used, it is a good idea to use AddHelp as well.

enumerator ErrorOnBadArgument

If an extra argument is encountered, the program terminates with an error and a usage statement is printed.

If this option is not provided, any unknown arguments are returned in argv.

enumerator Strict

If supplied, Initialize treats its own arguments as the only ones supported by the application and provides an error if not followed exactly.

This is a convenience option that is a combination of ErrorOnBadOption, ErrorOnBadArgument, and AddHelp.

Example 2.2 Calling viskores::cont::Initialize().

#include <viskores/cont/Initialize.h>

int main(int argc, char** argv)
{
  viskores::cont::InitializeOptions options =
    viskores::cont::InitializeOptions::ErrorOnBadOption |
    viskores::cont::InitializeOptions::DefaultAnyDevice;
  viskores::cont::InitializeResult config =
    viskores::cont::Initialize(argc, argv, options);

  if (argc != 2)
  {
    std::cerr << "USAGE: " << argv[0] << " [options] filename" << std::endl;
    std::cerr << "Available options are:" << std::endl;
    std::cerr << config.Usage << std::endl;
    return 1;
  }
  std::string filename = argv[1];

  // Do something cool with Viskores
  // ...

  return 0;
}