2.3. Initialization

When it comes to running VTK‑m 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 vtkm::cont::Initialize() function. Although it is not strictly necessary to call vtkm::cont::Initialize(), it is recommended to set up state and check for available devices.

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

Initialize the VTKm 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 --vtkm-log-level.

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

• Prints usage when -h or --vtkm-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 --vtkm-device option.

Results are available in the returned InitializeResult.

Note

This method may call exit() on parse error.

vtkm::cont::Initialize() can be called without any arguments, in which case VTK‑m 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 VTK‑m. VTK‑m accepts arguments that, for example, configure the compute device to use or establish logging levels. Any arguments that are handled by VTK‑m 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 VTK‑m command line arguments and environment variable options.

Command Line Argument	Environment Variable	Default Value	Description
--vtkm-help			Causes the program to print information about VTK‑m command line arguments and then exits the program.
--vtkm-log-level	VTKM_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.
--vtkm-device	VTKM_DEVICE		Force VTK‑m to use the specified device. If not specified or Any given, then any available device may be used.
--vtkm-num-threads	VTKM_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.
--vtkm-device-instance	VTKM_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.

vtkm::cont::Initialize() returns a vtkm::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 --vtkm-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 VTK-m.

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 VTK-m.

vtkm::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 vtkm::cont::InitializeOptions enum.

enum class vtkm::cont::InitializeOptions

Values:

enumerator None

Placeholder used when no options are enabled.

This is the value used when the third argument to vtkm::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 --vtkm-device=Any.

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

enumerator AddHelp

Add a help argument.

If -h or --vtkm-help is provided, prints a usage statement. Of course, the usage statement will only print out arguments processed by VTK-m, which is why help is not given by default. Alternatively, a string with usage help is returned from vtkm::cont::Initialize so that the calling program can provide VTK-m’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 vtkm::cont::Initialize().

#include <vtkm/cont/Initialize.h>

int main(int argc, char** argv)
{
  vtkm::cont::InitializeOptions options =
    vtkm::cont::InitializeOptions::ErrorOnBadOption |
    vtkm::cont::InitializeOptions::DefaultAnyDevice;
  vtkm::cont::InitializeResult config = vtkm::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 VTK-m
  // ...

  return 0;
}